[tor-dev] Proposal 286: Controller APIs for hibernation access on mobile
teor2345 at gmail.com
Thu Nov 30 21:35:24 UTC 2017
> On 30 Nov 2017, at 23:55, Nick Mathewson <nickm at torproject.org> wrote:
> Filename: 286-hibernation-api.txt
> Title: Controller APIs for hibernation access on mobile
> Author: Nick Mathewson
> Created: 30-November-2017
> Status: Open
> 1. Introduction
> On mobile platforms, battery life is achieved by reducing
> needless network access and CPU access. Tor currently provides
> few ways for controllers and operating systems to tune its
> This proposal describes controller APIs for better management of
> Tor's hibernation mechanisms, and extensions to those mechanisms,
> for better power management in mobile environments.
> 1.1. Background: hibernation and idling in Tor today
> We have an existing "hibernation" mechanism that we use to
> implement "bandwidth accounting" and "slow shutdown" mechanisms:
> When a Tor instance is close to its bandwidth limit: it stops
> accepting new connections or circuits, and only processes those
> it has, until the bandwidth limit is reached. Once the bandwidth
> limit is reached, Tor closes all connections and circuits, and
> all non-controller listeners, until a new accounting limit
> Tor handles the INT signal on relays similarly: it stops
> accepting new connections or circuits, and gives the existing
> ones a short interval in which to shut down. Then Tor closes all
> connections and exits the process entirely.
> Tor's "idle" mechanism is related to hibernation, though its
> implementation is separate. When a Tor clients has passed a
> certain amount of time without any user activity, it declares
> itself "idle" and stops performing certain background tasks, such
> as fetching directory information, or building circuits in
> anticipation of future needs. (This is tied in the codebase to
> the "predicted ports" mechanism, but it doesn't have to be.)
> 1.2. Background: power-management signals on mobile platforms
> (I'm not a mobile developer, so I'm about to wildly oversimplify.
> Please let me know where I'm wrong.)
> Mobile platforms achieve long battery life by turning off the
> parts they don't need. The most important parts to turn off are
> the antenna(s) and the screen; the CPU can be run in a slower
> But it doesn't do much good turning things off when they're
> unused, if some background app is going to make sure that they're
> always in use! So mobile platforms use signals of various kinds
> to tell applications "okay, shut up now".
> Some apps need to do online background activities periodically;
> to help this out, mobile platforms give them a signal "Hey, now
> is a good time if you want to do that" and "stop now!"
> 1.3. Mostly out-of-scope: limiting CPU wakeups when idle.
> The changes described here will be of limited use if we do not
> also alter Tor so that, when it's idle, the CPU is pretty quiet.
> That isn't the case right now: we have large numbers of callbacks
> that happen periodically (every second, every minute, etc)
> whether they need to or not. We're hoping to limit those, but
> that's not what this proposal is about.
> 2. Improvements to the hibernation model
> To present a consistent interface that applications and
> controllers can use to manage power consumption, we make these
> enhancements to our hibernation model.
> First, we add three new hibernation states: "IDLE",
> "IDLE_UPDATING", "SLEEP", and "SLEEP_UPDATING".
Four new hibernation states
> "IDLE" is like the current "idle" or "no predicted ports" state:
> Tor doesn't launch circuits or start any directory activity, but
> its listeners are still open. Tor clients can enter the IDLE
> state on their own when they are LIVE, but haven't gotten any
> client activity for a while. Existing connections and circuits
> are not closed. If the Tor instance receives any new connections,
> it becomes LIVE.
> "IDLE_UPDATING" is like IDLE, except that Tor should check for
> directory updates as appropriate. If there are any, it should
> fetch directory information, and then become IDLE again.
> "SLEEPING" is like the current "dormant state we use for
> bandwidth exhaustion, but it is controller-initiated: it begins
> when Tor is told to enter it, and ends when Tor is told to leave
> it. Existing connections and circuits are closed; listeners are
> closed too.
> "SLEEP_UPDATING" is like SLEEP, except that Tor should check for
> directory updates as appropriate. If there are any, it should
> fetch directory information, and then SLEEP again.
> 2.1. Relay operation
> Relays and bridges should not automatically become IDLE on their
> 2.2. Onion service operation
> When a Tor instance that is running an onion service is IDLE, it
> does the minimum to try to remain responsive on the onion
> service: It keeps its introduction points open if it can. Once a
> day, it fetches new directory information and opens new
> introduction points.
… and re-posts its descriptor?
And if an IP goes down, does it pick a new one?
Or if the descriptor expires?
How often does that happen in v2?
I think it happens after 3 hours by default in v3.
> 3. Controller hibernation API
> 3.1. Examining the current hibernation state
> We define a new "GETINFO status/hibernation" to inspect the
> current hibernation state. Possible values are:
> - "live"
> - "idle:control"
> - "idle:no-activity"
> - "sleep:control"
> - "sleep:accounting"
> - "idle-update:control"
> - "sleep-update:control"
> - "shutdown:exiting"
> - "shutdown:accounting"
> - "shutdown:control"
Why is there no reason for "live"?
> The first part of each value indicates Tor's current state:
> "live" -- completely awake
> "idle" -- waiting to see if anything happens
> "idle-update" -- waiting to see if anything happens; probing
> for directory information
> "sleep" -- completely unresponsive
> "shutdown" -- unresponsive to new requests; still processing
> existing requests.
> The second part of each value indicates the reason that Tor
> entered this state:
> "control" -- a controller told us to do this.
> "no-activity" -- Tor became idle on its own due to not
> noticing any requests.
> "accounting" -- the bandwidth system told us to enter this
> "exiting" -- Tor is in this state because it's getting ready
> to exit.
Missing a reason corresponding to StartIdle
> We add a STATUS_GENERAL hibernation event as follows:
> "STATUS=" (one of the status pairs above.)
> Indicates that Tor's hibernation status has changed.
> Note: Controllers MUST accept status values here that they don't
> The "GETINFO accounting/hibernating" value and the "STATUS_SERVER
> HIBERANATION_STATUS" event keep their old meaning.
> 3.2. Changing the hibernation state
> We add the following new possible values to the SIGNAL controller
> "SLEEP" -- enter the sleep state, after an appropriate
> shutdown interval.
> "IDLE" -- enter the idle state
> "SLEEPWALK" -- If in sleep or idle, start probing for
> directory information in the sleep-update or idle-update
> state respectively. Remain in that state until we've
> probed for directory information, or until we're told to
> IDLE or SLEEP again, or (if we're idle) until we get client
> activity. Has no effect if not in sleep or idle.
> "WAKEUP" -- If in sleep, sleep-update, idle, idle-update, or
> shutdown:sleep state, enter the live state. Has no effect
> in any other state.
> 3.3. New configuration parameters
> StartIdle -- Boolean. If set to 1, Tor begins in IDLE mode.
More information about the tor-dev