commit 4af0ad43a6d309847374802162d29e84caef85cb Author: Taylor Yu <catalyst@torproject.org> Date: Thu Jan 10 17:00:39 2019 -0600 Details for new 0.4.0.x bootstrap phases Also add an overview of bootstrap reporting, and divide phases into three stages. Part of ticket 28928. --- control-spec.txt | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 108 insertions(+), 11 deletions(-) diff --git a/control-spec.txt b/control-spec.txt index 6b63679..faaf160 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -3453,8 +3453,43 @@ exist in all future versions. Current Tor versions enter these phases in order, monotonically. - Future Tors MAY revisit earlier stages. - [XXXX: do we revisit earlier stages if the network fails?] + Future Tors MAY revisit earlier phases, for example, if the network + fails. + +5.5.1. Overview of Bootstrap reporting. + + Bootstrap phases can be viewed as belonging to one of three stages: + + 1. Initial connection to a Tor relay or bridge + 2. Obtaining directory information + 3. Building an application circuit + + Tor doesn't specifically enter Stage 1; that is a side effect of + other actions that Tor is taking. Tor could be making a connection + to a fallback directory server, or it could be making a connection + to a guard candidate. Either one counts as Stage 1 for the purposes + of bootstrap reporting. + + Stage 2 might involve Tor contacting directory servers, or it might + involve reading cached directory information from a previous + session. Large parts of Stage 2 might be skipped if there is already + enough cached directory information to build circuits. Tor will + defer reporting progress in Stage 2 until Stage 1 is complete. + + Tor defers this reporting because Tor can already have enough + directory information to build circuits, yet not be able to connect + to a relay. Without that deferral, a user might misleadingly see Tor + stuck at a large amount of progress when something as fundamental as + making a TCP connection to any relay is failing. + + Tor also doesn't specifically enter Stage 3; that is a side effect + of Tor building circuits for some purpose or other. In a typical + client, Tor builds predicted circuits to provide lower latency for + application connection requests. In Stage 3, Tor might make new + connections to relays or bridges that it did not connect to in Stage + 1. + +5.5.2. Phases in Bootstrap Stage 1. Phase 0: tag=starting summary="Starting" @@ -3465,35 +3500,60 @@ tag=conn_pt summary="Connecting to pluggable transport" [This phase is new in 0.4.0.x] + Tor is making a TCP connection to the transport plugin for a + pluggable transport. Tor will use this pluggable transport to make + its first connection to a bridge. + Phase 2: tag=conn_done_pt summary="Connected to pluggable transport" [New in 0.4.0.x] + Tor has completed its TCP connection to the transport plugin for the + pluggable transport. + Phase 3: tag=conn_proxy summary="Connecting to proxy" [New in 0.4.0.x] + Tor is making a TCP connection to a proxy to make its first + connection to a relay or bridge. + Phase 4: tag=conn_done_proxy summary="Connected to proxy" [New in 0.4.0.x] + Tor has completed its TCP connection to a proxy to make its first + connection to a relay or bridge. + Phase 5: tag=conn summary="Connecting to a relay" [New in 0.4.0.x; prior versions of Tor had a "conn_dir" phase that sometimes but not always corresponded to connecting to a directory server] + Tor is making its first connection to a relay. This might be through + a pluggable transport or proxy connection that Tor has already + established. + Phase 10: tag=conn_done summary="Connected to a relay" [New in 0.4.0.x] + Tor has completed its first connection to a relay. + Phase 14: tag=handshake summary="Handshaking with a relay" [New in 0.4.0.x; prior versions of Tor had a "handshake_dir" phase] + Tor is in the process of doing a TLS handshake with a relay. + Phase 15: tag=handshake_done summary="Handshake with a relay done" [New in 0.4.0.x] + Tor has completed its TLS handshake with a relay. + +5.5.3. Phases in Bootstrap Stage 2. + Phase 20: tag=onehop_create summary="Establishing an encrypted directory connection" [prior to 0.4.0.x, this was numbered 15] @@ -3541,8 +3601,9 @@ phase until we have received a 'connected' relay cell in response to a request for descriptors. - [Some versions of Tor (between 0.2.6.2-alpha and 0.4.0.x): - Tor could report having internal paths only; see Section 5.6] + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] Phase 50: tag=loading_descriptors summary="Loading relay descriptors" @@ -3556,8 +3617,9 @@ This phase is also a good opportunity to use the "progress" keyword to indicate partial steps. - [Some versions of Tor (between 0.2.6.2-alpha and 0.4.0.x): - Tor could report having internal paths only; see Section 5.6] + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] Phase 75: tag=enough_dirinfo summary="Loaded enough directory info to build @@ -3565,40 +3627,73 @@ [New in 0.4.0.x; previously, Tor would misleadingly report the "conn_or" tag once it had enough directory info.] +5.5.4. Phases in Bootstrap Stage 3. + Phase 76: tag=ap_conn_pt summary="Connecting to pluggable transport to build circuits" [New in 0.4.0.x] + This is similar to conn_pt, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + Phase 77: tag=ap_conn_done_pt summary="Connected to pluggable transport to build circuits" [New in 0.4.0.x] + This is similar to conn_done_pt, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + Phase 78: tag=ap_conn_proxy summary="Connecting to proxy to build circuits" [New in 0.4.0.x] - [XXX fix mispaste in control_bootstrap.c for this!] + + This is similar to conn_proxy, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. Phase 79: tag=ap_conn_done_proxy summary="Connected to proxy to build circuits" [New in 0.4.0.x] + This is similar to conn_done_proxy, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + Phase 80: tag=ap_conn summary="Connecting to a relay to build circuits" [New in 0.4.0.x] + This is similar to conn, except for making connections to additional + relays or bridges that Tor needs to use to build application + circuits. + Phase 85: tag=ap_conn_done summary="Connected to a relay to build circuits" [New in 0.4.0.x] + This is similar to conn_done, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + Phase 89: tag=ap_handshake summary="Finishing handshake with a relay to build circuits" [New in 0.4.0.x] + This is similar to handshake, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + Phase 90: tag=ap_handshake_done summary="Handshake fininshed with a relay to build circuits" [New in 0.4.0.x] + This is similar to handshake_done, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + Phase 95: tag=circuit_create summary="Establishing a[n internal] Tor circuit" [prior to 0.4.0.x, this was numbered 90] @@ -3607,8 +3702,9 @@ we will set about trying to make some 3-hop circuits in case we need them soon. - [Some versions of Tor (between 0.2.6.2-alpha and 0.4.0.x): - Tor could report having internal paths only; see Section 5.6] + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] Phase 100: tag=done summary="Done" @@ -3616,8 +3712,9 @@ A full 3-hop circuit has been established. Tor is ready to handle application connections now. - [Some versions of Tor (between 0.2.6.2-alpha and 0.4.0.x): - Tor could report having internal paths only; see Section 5.6] + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] 5.6 Bootstrap phases reported by older versions of Tor