proposals/137-bootstrap-phases.txt

   1 Filename: 137-bootstrap-phases.txt
   2 Title: Keep controllers informed as Tor bootstraps
   3 Author: Roger Dingledine
   4 Created: 07-Jun-2008
   5 Status: Closed
   6 Implemented-In: 0.2.1.x
   7
   8 1. Overview.
   9
  10   Tor has many steps to bootstrapping directory information and
  11   initial circuits, but from the controller's perspective we just have
  12   a coarse-grained "CIRCUIT_ESTABLISHED" status event. Tor users with
  13   slow connections or with connectivity problems can wait a long time
  14   staring at the yellow onion, wondering if it will ever change color.
  15
  16   This proposal describes a new client status event so Tor can give
  17   more details to the controller. Section 2 describes the changes to the
  18   controller protocol; Section 3 describes Tor's internal bootstrapping
  19   phases when everything is going correctly; Section 4 describes when
  20   Tor detects a problem and issues a bootstrap warning; Section 5 covers
  21   suggestions for how controllers should display the results.
  22
  23 2. Controller event syntax.
  24
  25   The generic status event is:
  26
  27     "650" SP StatusType SP StatusSeverity SP StatusAction
  28                                         [SP StatusArguments] CRLF
  29
  30   So in this case we send
  31   650 STATUS_CLIENT NOTICE/WARN BOOTSTRAP \
  32   PROGRESS=num TAG=Keyword SUMMARY=String \
  33   [WARNING=String REASON=Keyword COUNT=num RECOMMENDATION=Keyword]
  34
  35   The arguments MAY appear in any order. Controllers MUST accept unrecognized
  36   arguments.
  37
  38   "Progress" gives a number between 0 and 100 for how far through
  39   the bootstrapping process we are. "Summary" is a string that can be
  40   displayed to the user to describe the *next* task that Tor will tackle,
  41   i.e., the task it is working on after sending the status event. "Tag"
  42   is an optional string that controllers can use to recognize bootstrap
  43   phases from Section 3, if they want to do something smarter than just
  44   blindly displaying the summary string.
  45
  46   The severity describes whether this is a normal bootstrap phase
  47   (severity notice) or an indication of a bootstrapping problem
  48   (severity warn). If severity warn, it should also include a "warning"
  49   argument string with any hints Tor has to offer about why it's having
  50   troubles bootstrapping, a "reason" string that lists one of the reasons
  51   allowed in the ORConn event, a "count" number that tells how many
  52   bootstrap problems there have been so far at this phase, and a
  53   "recommendation" keyword to indicate how the controller ought to react.
  54
  55 3. The bootstrap phases.
  56
  57   This section describes the various phases currently reported by
  58   Tor. Controllers should not assume that the percentages and tags listed
  59   here will continue to match up, or even that the tags will stay in
  60   the same order. Some phases might also be skipped (not reported) if the
  61   associated bootstrap step is already complete, or if the phase no longer
  62   is necessary.  Only "starting" and "done" are guaranteed to exist in all
  63   future versions.
  64
  65   Current Tor versions enter these phases in order, monotonically;
  66   future Tors MAY revisit earlier stages.
  67
  68   Phase 0:
  69   tag=starting summary="starting"
  70
  71   Tor starts out in this phase.
  72
  73   Phase 5:
  74   tag=conn_dir summary="Connecting to directory mirror"
  75
  76   Tor sends this event as soon as Tor has chosen a directory mirror ---
  77   one of the authorities if bootstrapping for the first time or after
  78   a long downtime, or one of the relays listed in its cached directory
  79   information otherwise.
  80
  81   Tor will stay at this phase until it has successfully established
  82   a TCP connection with some directory mirror. Problems in this phase
  83   generally happen because Tor doesn't have a network connection, or
  84   because the local firewall is dropping SYN packets.
  85
  86   Phase 10
  87   tag=handshake_dir summary="Finishing handshake with directory mirror"
  88
  89   This event occurs when Tor establishes a TCP connection with a relay used
  90   as a directory mirror (or its https proxy if it's using one). Tor remains
  91   in this phase until the TLS handshake with the relay is finished.
  92
  93   Problems in this phase generally happen because Tor's firewall is
  94   doing more sophisticated MITM attacks on it, or doing packet-level
  95   keyword recognition of Tor's handshake.
  96
  97   Phase 15:
  98   tag=onehop_create summary="Establishing one-hop circuit for dir info"
  99
 100   Once TLS is finished with a relay, Tor will send a CREATE_FAST cell
 101   to establish a one-hop circuit for retrieving directory information.
 102   It will remain in this phase until it receives the CREATED_FAST cell
 103   back, indicating that the circuit is ready.
 104
 105   Phase 20:
 106   tag=requesting_status summary="Asking for networkstatus consensus"
 107
 108   Once we've finished our one-hop circuit, we will start a new stream
 109   for fetching the networkstatus consensus. We'll stay in this phase
 110   until we get the 'connected' relay cell back, indicating that we've
 111   established a directory connection.
 112
 113   Phase 25:
 114   tag=loading_status summary="Loading networkstatus consensus"
 115
 116   Once we've established a directory connection, we will start fetching
 117   the networkstatus consensus document. This could take a while; this
 118   phase is a good opportunity for using the "progress" keyword to indicate
 119   partial progress.
 120
 121   This phase could stall if the directory mirror we picked doesn't
 122   have a copy of the networkstatus consensus so we have to ask another,
 123   or it does give us a copy but we don't find it valid.
 124
 125   Phase 40:
 126   tag=loading_keys summary="Loading authority key certs"
 127
 128   Sometimes when we've finished loading the networkstatus consensus,
 129   we find that we don't have all the authority key certificates for the
 130   keys that signed the consensus. At that point we put the consensus we
 131   fetched on hold and fetch the keys so we can verify the signatures.
 132
 133   Phase 45
 134   tag=requesting_descriptors summary="Asking for relay descriptors"
 135
 136   Once we have a valid networkstatus consensus and we've checked all
 137   its signatures, we start asking for relay descriptors. We stay in this
 138   phase until we have received a 'connected' relay cell in response to
 139   a request for descriptors.
 140
 141   Phase 50:
 142   tag=loading_descriptors summary="Loading relay descriptors"
 143
 144   We will ask for relay descriptors from several different locations,
 145   so this step will probably make up the bulk of the bootstrapping,
 146   especially for users with slow connections. We stay in this phase until
 147   we have descriptors for at least 1/4 of the usable relays listed in
 148   the networkstatus consensus. This phase is also a good opportunity to
 149   use the "progress" keyword to indicate partial steps.
 150
 151   Phase 80:
 152   tag=conn_or summary="Connecting to entry guard"
 153
 154   Once we have a valid consensus and enough relay descriptors, we choose
 155   some entry guards and start trying to build some circuits. This step
 156   is similar to the "conn_dir" phase above; the only difference is
 157   the context.
 158
 159   If a Tor starts with enough recent cached directory information,
 160   its first bootstrap status event will be for the conn_or phase.
 161
 162   Phase 85:
 163   tag=handshake_or summary="Finishing handshake with entry guard"
 164
 165   This phase is similar to the "handshake_dir" phase, but it gets reached
 166   if we finish a TCP connection to a Tor relay and we have already reached
 167   the "conn_or" phase. We'll stay in this phase until we complete a TLS
 168   handshake with a Tor relay.
 169
 170   Phase 90:
 171   tag=circuit_create "Establishing circuits"
 172
 173   Once we've finished our TLS handshake with an entry guard, we will
 174   set about trying to make some 3-hop circuits in case we need them soon.
 175
 176   Phase 100:
 177   tag=done summary="Done"
 178
 179   A full 3-hop circuit has been established. Tor is ready to handle
 180   application connections now.
 181
 182 4. Bootstrap problem events.
 183
 184   When an OR Conn fails, we send a "bootstrap problem" status event, which
 185   is like the standard bootstrap status event except with severity warn.
 186   We include the same progress, tag, and summary values as we would for
 187   a normal bootstrap event, but we also include "warning", "reason",
 188   "count", and "recommendation" key/value combos.
 189
 190   The "reason" values are long-term-stable controller-facing tags to
 191   identify particular issues in a bootstrapping step.  The warning
 192   strings, on the other hand, are human-readable. Controllers SHOULD
 193   NOT rely on the format of any warning string. Currently the possible
 194   values for "recommendation" are either "ignore" or "warn" -- if ignore,
 195   the controller can accumulate the string in a pile of problems to show
 196   the user if the user asks; if warn, the controller should alert the
 197   user that Tor is pretty sure there's a bootstrapping problem.
 198
 199   Currently Tor uses recommendation=ignore for the first nine bootstrap
 200   problem reports for a given phase, and then uses recommendation=warn
 201   for subsequent problems at that phase. Hopefully this is a good
 202   balance between tolerating occasional errors and reporting serious
 203   problems quickly.
 204
 205 5. Suggested controller behavior.
 206
 207   Controllers should start out with a yellow onion or the equivalent
 208   ("starting"), and then watch for either a bootstrap status event
 209   (meaning the Tor they're using is sufficiently new to produce them,
 210   and they should load up the progress bar or whatever they plan to use
 211   to indicate progress) or a circuit_established status event (meaning
 212   bootstrapping is finished).
 213
 214   In addition to a progress bar in the display, controllers should also
 215   have some way to indicate progress even when no controller window is
 216   open. For example, folks using Tor Browser Bundle in hostile Internet
 217   cafes don't want a big splashy screen up. One way to let the user keep
 218   informed of progress in a more subtle way is to change the task tray
 219   icon and/or tooltip string as more bootstrap events come in.
 220
 221   Controllers should also have some mechanism to alert their user when
 222   bootstrapping problems are reported. Perhaps we should gather a set of
 223   help texts and the controller can send the user to the right anchor in a
 224   "bootstrapping problems" page in the controller's help subsystem?
 225
 226 6. Getting up to speed when the controller connects.
 227
 228   There's a new "GETINFO /status/bootstrap-phase" option, which returns
 229   the most recent bootstrap phase status event sent. Specifically,
 230   it returns a string starting with either "NOTICE BOOTSTRAP ..." or
 231   "WARN BOOTSTRAP ...".
 232
 233   Controllers should use this getinfo when they connect or attach to
 234   Tor to learn its current state.
 235