[tor-commits] [torspec/master] Details for new 0.4.0.x bootstrap phases
nickm at torproject.org
nickm at torproject.org
Mon Feb 25 18:34:49 UTC 2019
commit 4af0ad43a6d309847374802162d29e84caef85cb
Author: Taylor Yu <catalyst at 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
More information about the tor-commits
mailing list