Hello!
This email is about a new feature that has some implications here for applications that use Tor. I want to make sure we've thought about and prepared for those implications, since we still have time to tweak this feature.
== Overview
In 0.4.0.x, Tor will begin supporting a new "dormant" mode in which it does not initiate network activity, and tries to avoid CPU wakeups. This mode is intended to help mobile devices sleep, and to minimize the impact of unused Tor clients on the network, and on the devices that run them. For the implementation history, see: https://trac.torproject.org/projects/tor/ticket/28335 and https://trac.torproject.org/projects/tor/ticket/28624
By default, Tor will become dormant if it is a pure client (not a relay, not an onion service[*]), and if it has received not client activity for 24 hours. (You can change the interval with DormantClientTimeout.)
Unlike "DisableNetwork 1", Tor in dormant mode will not close any listener ports, and will become active again as soon as it receives a client connection. But like a "DisableNetwork 1" Tor, a dormant Tor will not build predicted circuits, and will not download directory information -- and therefore, will not bootstrap.
Controllers can make Tor become dormant or non-dormant by sending the commands "SIGNAL DORMANT" and "SIGNAL ACTIVE" respectively -- these are now documented in control-spec.txt.
Dormant state is persistent: if Tor has been idle for 20 hours, and you stop tor and start it again, and idle for 4 more hours, Tor will become dormant. If you stop tor and start it again, Tor will start in dormant mode.
== Documentation
Here's the documentation we have so far -- please let me know if you have ideas for clarification:
DormantClientTimeout N minutes|hours|days|weeks If Tor spends this much time without any client activity, enter a dormant state where automatic circuits are not built, and directory information is not fetched. Does not affect servers or onion services. Must be at least 10 minutes. (Default: 24 hours)
DormantTimeoutDisabledByIdleStreams 0|1 If true, then any open client stream (even one not reading or writing) counts as client activity for the purpose of DormantClientTimeout. If false, then only network activity counts. (Default: 1)
DormantOnFirstStartup 0|1 If true, then the first time Tor starts up with a fresh DataDirectory, it starts in dormant mode, and takes no actions until the user has made a request. (This mode is recommended if installing a Tor client for a user who might not actually use it.) If false, Tor bootstraps the first time it is started, whether it sees a user request or not.
After the first time Tor starts, it begins in dormant mode if it was dormant before, and not otherwise. (Default: 0)
== Compatibility issues
I see two issues here: one minor, and one major.
Minor issue: some applications periodically make requests to the tor network on their own -- for example, Tor Browser's update requests. These requests prevent Tor from becoming dormant. If this is undesired, we can add some way around this.
Major issue: some applications expect that Tor will always bootstrap when it starts, and delay presenting their own UI until Tor is ready. But if Tor starts as dormant, then it will not bootstrap until it receives a request from the client or a "SIGNAL ACTIVE" command from the controller. This could lead to breakage as the application waits for Tor to tell it that it's ready, and Tor waits for somebody to tell it that it's needed.
Are all application developers okay with the issues above, and okay with working around them? If not, we may need changes in Tor before 0.4.0.x is released. Let's talk!
[*] I'd like to add support for dormant onion services, but that's harder. See https://trac.torproject.org/projects/tor/ticket/28424 .
peace,