mirror of
https://github.com/torproject/torspec.git
synced 2024-11-23 09:49:45 +00:00
198 lines
7.3 KiB
Plaintext
198 lines
7.3 KiB
Plaintext
Filename: 286-hibernation-api.txt
|
|
Title: Controller APIs for hibernation access on mobile
|
|
Author: Nick Mathewson
|
|
Created: 30-November-2017
|
|
Status: Rejected
|
|
|
|
Notes: This proposal was useful for our early thinking, but a simpler
|
|
solution (DisableNetwork) proved much more useful.
|
|
|
|
|
|
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
|
|
behavior.
|
|
|
|
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
|
|
begins.
|
|
|
|
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
|
|
mode.
|
|
|
|
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".
|
|
|
|
"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
|
|
own.
|
|
|
|
|
|
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.
|
|
|
|
|
|
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"
|
|
|
|
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
|
|
state.
|
|
"exiting" -- Tor is in this state because it's getting ready
|
|
to exit.
|
|
|
|
We add a STATUS_GENERAL hibernation event as follows:
|
|
|
|
HIBERNATION
|
|
"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
|
|
recognize.
|
|
|
|
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
|
|
command:
|
|
"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.
|
|
|
|
|