Ticket #24107: xxx-hibernation-api.txt

File xxx-hibernation-api.txt, 7.2 KB (added by nickm, 23 months ago)
Line 
1Filename: xxx-hibernation-api.txt
2Title: Controller APIs for hibernation access on mobile
3Author: Nick Mathewson
4Created: ??-November-2017
5Status: Open
6
7
81. Introduction
9
10   On mobile platforms, battery life is achieved by reducing
11   needless network access and CPU access.  Tor currently provides
12   few ways for controllers and operating systems to tune its
13   behavior.
14
15   This proposal describes controller APIs for better management of
16   Tor's hibernation mechanisms, and extensions to those mechanisms,
17   for better power management in mobile environments.
18
191.1. Background: hibernation and idling in Tor today
20
21   We have an existing "hibernation" mechanism that we use to
22   implement "bandwidth accounting" and "slow shutdown" mechanisms:
23   When a Tor instance is close to its bandwidth limit: it stops
24   accepting new connections or circuits, and only processes those
25   it has, until the bandwidth limit is reached.  Once the bandwidth
26   limit is reached, Tor closes all connections and circuits, and
27   all non-controller listeners, until a new accounting limit
28   begins.
29
30   Tor handles the INT signal on relays similarly: it stops
31   accepting new connections or circuits, and gives the existing
32   ones a short interval in which to shut down.  Then Tor closes all
33   connections and exits the process entirely.
34
35   Tor's "idle" mechanism is related to hibernation, though its
36   implementation is separate.  When a Tor clients has passed a
37   certain amount of time without any user activity, it declares
38   itself "idle" and stops performing certain background tasks, such
39   as fetching directory information, or building circuits in
40   anticipation of future needs.  (This is tied in the codebase to
41   the "predicted ports" mechanism, but it doesn't have to be.)
42
43
441.2. Background: power-management signals on mobile platforms
45
46   (I'm not a mobile developer, so I'm about to wildly oversimplify.
47   Please let me know where I'm wrong.)
48
49   Mobile platforms achieve long battery life by turning off the
50   parts they don't need.  The most important parts to turn off are
51   the antenna(s) and the screen; the CPU can be run in a slower
52   mode.
53
54   But it doesn't do much good turning things off when they're
55   unused, if some background app is going to make sure that they're
56   always in use!  So mobile platforms use signals of various kinds
57   to tell applications "okay, shut up now".
58
59   Some apps need to do online background activities periodically;
60   to help this out, mobile platforms give them a signal "Hey, now
61   is a good time if you want to do that" and "stop now!"
62
63
641.3. Mostly out-of-scope: limiting CPU wakeups when idle.
65
66   The changes described here will be of limited use if we do not
67   also alter Tor so that, when it's idle, the CPU is pretty quiet.
68   That isn't the case right now: we have large numbers of callbacks
69   that happen periodically (every second, every minute, etc)
70   whether they need to or not.  We're hoping to limit those, but
71   that's not what this proposal is about.
72
73
742. Improvements to the hibernation model
75
76   To present a consistent interface that applications and
77   controllers can use to manage power consumption, we make these
78   enhancements to our hibernation model.
79
80   First, we add three new hibernation states: "IDLE",
81   "IDLE_UPDATING", "SLEEP", and "SLEEP_UPDATING".
82
83   "IDLE" is like the current "idle" or "no predicted ports" state:
84   Tor doesn't launch circuits or start any directory activity, but
85   its listeners are still open.  Tor clients can enter the IDLE
86   state on their own when they are LIVE, but haven't gotten any
87   client activity for a while.  Existing connections and circuits
88   are not closed. If the Tor instance receives any new connections,
89   it becomes LIVE.
90
91   "IDLE_UPDATING" is like IDLE, except that Tor should check for
92   directory updates as appropriate.  If there are any, it should
93   fetch directory information, and then become IDLE again.
94
95   "SLEEPING" is like the current "dormant state we use for
96   bandwidth exhaustion, but it is controller-initiated: it begins
97   when Tor is told to enter it, and ends when Tor is told to leave
98   it.  Existing connections and circuits are closed; listeners are
99   closed too.
100
101   "SLEEP_UPDATING" is like SLEEP, except that Tor should check for
102   directory updates as appropriate.  If there are any, it should
103   fetch directory information, and then SLEEP again.
104
105
1062.1. Relay operation
107
108   Relays and bridges should not automatically become IDLE on their
109   own.
110
111
1122.2. Onion service operation
113
114   When a Tor instance that is running an onion service is IDLE, it
115   does the minimum to try to remain responsive on the onion
116   service: It keeps its introduction points open if it can. Once a
117   day, it fetches new directory information and opens new
118   introduction points.
119
120
1213. Controller hibernation API
122
1233.1. Examining the current hibernation state
124
125   We define a new "GETINFO status/hibernation" to inspect the
126   current hibernation state.  Possible values are:
127     - "live"
128     - "idle:control"
129     - "idle:no-activity"
130     - "sleep:control"
131     - "sleep:accounting"
132     - "idle-update:control"
133     - "sleep-update:control"
134     - "shutdown:exiting"
135     - "shutdown:accounting"
136     - "shutdown:control"
137
138   The first part of each value indicates Tor's current state:
139      "live" -- completely awake
140      "idle" -- waiting to see if anything happens
141      "idle-update" -- waiting to see if anything happens; probing
142         for directory information
143      "sleep" -- completely unresponsive
144      "shutdown" -- unresponsive to new requests; still processing
145         existing requests.
146
147   The second part of each value indicates the reason that Tor
148   entered this state:
149      "control" -- a controller told us to do this.
150      "no-activity" -- Tor became idle on its own due to not
151         noticing any requests.
152      "accounting" -- the bandwidth system told us to enter this
153         state.
154      "exiting" -- Tor is in this state because it's getting ready
155         to exit.
156
157   We add a STATUS_GENERAL hibernation event as follows:
158
159      HIBERNATION
160      "STATUS=" (one of the status pairs above.)
161
162      Indicates that Tor's hibernation status has changed.
163
164   Note: Controllers MUST accept status values here that they don't
165   recognize.
166
167   The "GETINFO accounting/hibernating" value and the "STATUS_SERVER
168   HIBERANATION_STATUS" event keep their old meaning.
169
1703.2. Changing the hibernation state
171
172   We add the following new possible values to the SIGNAL controller
173   command:
174      "SLEEP" -- enter the sleep state, after an appropriate
175         shutdown interval.
176
177      "IDLE" -- enter the idle state
178
179      "SLEEPWALK" -- If in sleep or idle, start probing for
180         directory information in the sleep-update or idle-update
181         state respectively.  Remain in that state until we've
182         probed for directory information, or until we're told to
183         IDLE or SLEEP again, or (if we're idle) until we get client
184         activity. Has no effect if not in sleep or idle.
185
186      "WAKEUP" -- If in sleep, sleep-update, idle, idle-update, or
187         shutdown:sleep state, enter the live state.  Has no effect
188         in any other state.
189
1903.3. New configuration parameters
191
192   StartIdle -- Boolean.  If set to 1, Tor begins in IDLE mode.
193
194