|
@@ -564,10 +564,17 @@ $Id$
|
|
|
"OR=" ("0"/"1") SP "DIR=" ("0"/"1")
|
|
|
Combines status/reachability/*; controllers MUST ignore unrecognized
|
|
|
elements in this entry.
|
|
|
-
|
|
|
- "status/version/recommended" -- List of currently recommended versions
|
|
|
- "status/version/current" -- Status of the current version. One of:
|
|
|
- new, old, unrecommended, recommended, new in series, obsolete.
|
|
|
+ "status/bootstrap-phase"
|
|
|
+ Returns the most recent bootstrap phase status event
|
|
|
+ sent. Specifically, it returns a string starting with either
|
|
|
+ "NOTICE BOOTSTRAP ..." or "WARN BOOTSTRAP ...". Controllers should
|
|
|
+ use this getinfo when they connect or attach to Tor to learn its
|
|
|
+ current bootstrap state.
|
|
|
+ "status/version/recommended"
|
|
|
+ List of currently recommended versions.
|
|
|
+ "status/version/current"
|
|
|
+ Status of the current version. One of: new, old, unrecommended,
|
|
|
+ recommended, new in series, obsolete.
|
|
|
|
|
|
Examples:
|
|
|
C: GETINFO version desc/name/moria1
|
|
@@ -663,7 +670,7 @@ $Id$
|
|
|
|
|
|
This message informs the server about a new descriptor. If Purpose is
|
|
|
specified, it must be either "general", "controller", or "bridge",
|
|
|
- else we return a 552 error.
|
|
|
+ else we return a 552 error. The default is "general".
|
|
|
|
|
|
If Cache is specified, it must be either "no" or "yes", else we
|
|
|
return a 552 error. If Cache is not specified, Tor will decide for
|
|
@@ -673,11 +680,11 @@ $Id$
|
|
|
The descriptor, when parsed, must contain a number of well-specified
|
|
|
fields, including fields for its nickname and identity.
|
|
|
|
|
|
- If there is an error in parsing the descriptor, the server must send a "554
|
|
|
- Invalid descriptor" reply. If the descriptor is well-formed but the server
|
|
|
- chooses not to add it, it must reply with a 251 message whose body explains
|
|
|
- why the server was not added. If the descriptor is added, Tor replies with
|
|
|
- "250 OK".
|
|
|
+ If there is an error in parsing the descriptor, the server must send a
|
|
|
+ "554 Invalid descriptor" reply. If the descriptor is well-formed but
|
|
|
+ the server chooses not to add it, it must reply with a 251 message
|
|
|
+ whose body explains why the server was not added. If the descriptor
|
|
|
+ is added, Tor replies with "250 OK".
|
|
|
|
|
|
3.15. REDIRECTSTREAM
|
|
|
|
|
@@ -1017,9 +1024,9 @@ $Id$
|
|
|
accept reasons not listed above. Reasons are as given in tor-spec.txt,
|
|
|
except for:
|
|
|
|
|
|
- END (We received a RELAY_END cell from the other side of thise
|
|
|
+ END (We received a RELAY_END cell from the other side of this
|
|
|
stream.)
|
|
|
- [XXXX document more.]
|
|
|
+ [XXXX document more. -NM]
|
|
|
|
|
|
The "REMOTE_REASON" field is provided only when we receive a RELAY_END
|
|
|
cell, and only if extended events are enabled. It contains the actual
|
|
@@ -1038,7 +1045,6 @@ $Id$
|
|
|
that requested the connection, and can be (e.g.) used to look up the
|
|
|
requesting program.
|
|
|
|
|
|
-
|
|
|
Purpose = "DIR_FETCH" / "UPLOAD_DESC" / "DNS_REQUEST" /
|
|
|
"USER" / "DIRPORT_TEST"
|
|
|
|
|
@@ -1046,7 +1052,6 @@ $Id$
|
|
|
only if extended events are enabled (see 3.19). Clients MUST accept
|
|
|
purposes not listed above.
|
|
|
|
|
|
-
|
|
|
4.1.3. OR Connection status changed
|
|
|
|
|
|
The syntax is:
|
|
@@ -1083,9 +1088,9 @@ $Id$
|
|
|
Type = "DIR" / "OR" / "EXIT" / "APP" / ...
|
|
|
Num = 1*DIGIT
|
|
|
|
|
|
- BytesRead and BytesWritten are the totals. In Tor 0.1.x.y-alpha
|
|
|
- and later, we also include a breakdown of the connection types
|
|
|
- that used bandwidth this second (not implemented yet).
|
|
|
+ BytesRead and BytesWritten are the totals. [In a future Tor version,
|
|
|
+ we may also include a breakdown of the connection types that used
|
|
|
+ bandwidth this second (not implemented yet).]
|
|
|
|
|
|
4.1.5. Log messages
|
|
|
|
|
@@ -1174,7 +1179,7 @@ $Id$
|
|
|
controllers. These recommendations are suggestions only; no controller
|
|
|
is required to implement them.
|
|
|
|
|
|
- Compatibility node: versions of Tor before 0.2.0.22-rc incorrectly
|
|
|
+ Compatibility note: versions of Tor before 0.2.0.22-rc incorrectly
|
|
|
generated "STATUS_SERVER" as "STATUS_SEVER". To be compatible with those
|
|
|
versions, tools should accept both.
|
|
|
|
|
@@ -1280,6 +1285,60 @@ $Id$
|
|
|
|
|
|
Actions for STATUS_CLIENT events can be as follows:
|
|
|
|
|
|
+ BOOTSTRAP
|
|
|
+ "PROGRESS=" num
|
|
|
+ "TAG=" Keyword
|
|
|
+ "SUMMARY=" String
|
|
|
+ ["WARNING=" String
|
|
|
+ "REASON=" Keyword
|
|
|
+ "COUNT=" num
|
|
|
+ "RECOMMENDATION=" Keyword
|
|
|
+ ]
|
|
|
+
|
|
|
+ Tor has made some progress at establishing a connection to the
|
|
|
+ Tor network, fetching directory information, or making its first
|
|
|
+ circuit; or it has encountered a problem while bootstrapping. This
|
|
|
+ status event is especially useful for users with slow connections
|
|
|
+ or with connectivity problems.
|
|
|
+
|
|
|
+ "Progress" gives a number between 0 and 100 for how far through
|
|
|
+ the bootstrapping process we are. "Summary" is a string that can
|
|
|
+ be displayed to the user to describe the *next* task that Tor
|
|
|
+ will tackle, i.e., the task it is working on after sending the
|
|
|
+ status event. "Tag" is a string that controllers can use to
|
|
|
+ recognize bootstrap phases, if they want to do something smarter
|
|
|
+ than just blindly displaying the summary string; see Section 5
|
|
|
+ for the current tags that Tor issues.
|
|
|
+
|
|
|
+ The StatusSeverity describes whether this is a normal bootstrap
|
|
|
+ phase (severity notice) or an indication of a bootstrapping
|
|
|
+ problem (severity warn).
|
|
|
+
|
|
|
+ For bootstrap problems, we include the same progress, tag, and
|
|
|
+ summary values as we would for a normal bootstrap event, but we
|
|
|
+ also include "warning", "reason", "count", and "recommendation"
|
|
|
+ key/value combos. The "count" number tells how many bootstrap
|
|
|
+ problems there have been so far at this phase. The "reason"
|
|
|
+ string lists one of the reasons allowed in the ORCONN event. The
|
|
|
+ "warning" argument string with any hints Tor has to offer about
|
|
|
+ why it's having troubles bootstrapping.
|
|
|
+
|
|
|
+ The "reason" values are long-term-stable controller-facing tags to
|
|
|
+ identify particular issues in a bootstrapping step. The warning
|
|
|
+ strings, on the other hand, are human-readable. Controllers
|
|
|
+ SHOULD NOT rely on the format of any warning string. Currently
|
|
|
+ the possible values for "recommendation" are either "ignore" or
|
|
|
+ "warn" -- if ignore, the controller can accumulate the string in
|
|
|
+ a pile of problems to show the user if the user asks; if warn,
|
|
|
+ the controller should alert the user that Tor is pretty sure
|
|
|
+ there's a bootstrapping problem.
|
|
|
+
|
|
|
+ Currently Tor uses recommendation=ignore for the first
|
|
|
+ nine bootstrap problem reports for a given phase, and then
|
|
|
+ uses recommendation=warn for subsequent problems at that
|
|
|
+ phase. Hopefully this is a good balance between tolerating
|
|
|
+ occasional errors and reporting serious problems quickly.
|
|
|
+
|
|
|
ENOUGH_DIR_INFO
|
|
|
Tor now knows enough network-status documents and enough server
|
|
|
descriptors that it's going to start trying to build circuits now.
|
|
@@ -1533,9 +1592,9 @@ $Id$
|
|
|
|
|
|
5.3. Backward compatibility with v0 control protocol.
|
|
|
|
|
|
- The 'version 0' control protocol was replaced in Tor 0.1.1.x. Support was
|
|
|
- removed in Tor 0.2.0.x. Every non-obsolete version of Tor now supports the
|
|
|
- version 1 control protocol.
|
|
|
+ The 'version 0' control protocol was replaced in Tor 0.1.1.x. Support
|
|
|
+ was removed in Tor 0.2.0.x. Every non-obsolete version of Tor now
|
|
|
+ supports the version 1 control protocol.
|
|
|
|
|
|
For backward compatibility with the "version 0" control protocol,
|
|
|
Tor used to check whether the third octet of the first command is zero.
|
|
@@ -1543,7 +1602,7 @@ $Id$
|
|
|
|
|
|
This compatibility was removed in Tor 0.1.2.16 and 0.2.0.4-alpha.
|
|
|
|
|
|
-5.4. Options for use by controllers
|
|
|
+5.4. Tor config options for use by controllers
|
|
|
|
|
|
Tor provides a few special configuration options for use by controllers.
|
|
|
These options can be set and examined by the SETCONF and GETCONF commands,
|
|
@@ -1583,4 +1642,131 @@ $Id$
|
|
|
|
|
|
As HashedControlPassword, but is not saved to the torrc file by
|
|
|
SAVECONF. Added in Tor 0.2.0.20-rc.
|
|
|
-
|
|
|
+
|
|
|
+5.5. Phases from the Bootstrap status event.
|
|
|
+
|
|
|
+ This section describes the various bootstrap phases currently reported
|
|
|
+ by Tor. Controllers should not assume that the percentages and tags
|
|
|
+ listed here will continue to match up, or even that the tags will stay
|
|
|
+ in the same order. Some phases might also be skipped (not reported)
|
|
|
+ if the associated bootstrap step is already complete, or if the phase
|
|
|
+ no longer is necessary. Only "starting" and "done" are guaranteed to
|
|
|
+ exist in all future versions.
|
|
|
+
|
|
|
+ Current Tor versions enter these phases in order, monotonically.
|
|
|
+ Future Tors MAY revisit earlier stages.
|
|
|
+
|
|
|
+ Phase 0:
|
|
|
+ tag=starting summary="starting"
|
|
|
+
|
|
|
+ Tor starts out in this phase.
|
|
|
+
|
|
|
+ Phase 5:
|
|
|
+ tag=conn_dir summary="Connecting to directory mirror"
|
|
|
+
|
|
|
+ Tor sends this event as soon as Tor has chosen a directory mirror --
|
|
|
+ e.g. one of the authorities if bootstrapping for the first time or
|
|
|
+ after a long downtime, or one of the relays listed in its cached
|
|
|
+ directory information otherwise.
|
|
|
+
|
|
|
+ Tor will stay at this phase until it has successfully established
|
|
|
+ a TCP connection with some directory mirror. Problems in this phase
|
|
|
+ generally happen because Tor doesn't have a network connection, or
|
|
|
+ because the local firewall is dropping SYN packets.
|
|
|
+
|
|
|
+ Phase 10
|
|
|
+ tag=handshake_dir summary="Finishing handshake with directory mirror"
|
|
|
+
|
|
|
+ This event occurs when Tor establishes a TCP connection with a relay used
|
|
|
+ as a directory mirror (or its https proxy if it's using one). Tor remains
|
|
|
+ in this phase until the TLS handshake with the relay is finished.
|
|
|
+
|
|
|
+ Problems in this phase generally happen because Tor's firewall is
|
|
|
+ doing more sophisticated MITM attacks on it, or doing packet-level
|
|
|
+ keyword recognition of Tor's handshake.
|
|
|
+
|
|
|
+ Phase 15:
|
|
|
+ tag=onehop_create summary="Establishing one-hop circuit for dir info"
|
|
|
+
|
|
|
+ Once TLS is finished with a relay, Tor will send a CREATE_FAST cell
|
|
|
+ to establish a one-hop circuit for retrieving directory information.
|
|
|
+ It will remain in this phase until it receives the CREATED_FAST cell
|
|
|
+ back, indicating that the circuit is ready.
|
|
|
+
|
|
|
+ Phase 20:
|
|
|
+ tag=requesting_status summary="Asking for networkstatus consensus"
|
|
|
+
|
|
|
+ Once we've finished our one-hop circuit, we will start a new stream
|
|
|
+ for fetching the networkstatus consensus. We'll stay in this phase
|
|
|
+ until we get the 'connected' relay cell back, indicating that we've
|
|
|
+ established a directory connection.
|
|
|
+
|
|
|
+ Phase 25:
|
|
|
+ tag=loading_status summary="Loading networkstatus consensus"
|
|
|
+
|
|
|
+ Once we've established a directory connection, we will start fetching
|
|
|
+ the networkstatus consensus document. This could take a while; this
|
|
|
+ phase is a good opportunity for using the "progress" keyword to indicate
|
|
|
+ partial progress.
|
|
|
+
|
|
|
+ This phase could stall if the directory mirror we picked doesn't
|
|
|
+ have a copy of the networkstatus consensus so we have to ask another,
|
|
|
+ or it does give us a copy but we don't find it valid.
|
|
|
+
|
|
|
+ Phase 40:
|
|
|
+ tag=loading_keys summary="Loading authority key certs"
|
|
|
+
|
|
|
+ Sometimes when we've finished loading the networkstatus consensus,
|
|
|
+ we find that we don't have all the authority key certificates for the
|
|
|
+ keys that signed the consensus. At that point we put the consensus we
|
|
|
+ fetched on hold and fetch the keys so we can verify the signatures.
|
|
|
+
|
|
|
+ Phase 45
|
|
|
+ tag=requesting_descriptors summary="Asking for relay descriptors"
|
|
|
+
|
|
|
+ Once we have a valid networkstatus consensus and we've checked all
|
|
|
+ its signatures, we start asking for relay descriptors. We stay in this
|
|
|
+ phase until we have received a 'connected' relay cell in response to
|
|
|
+ a request for descriptors.
|
|
|
+
|
|
|
+ Phase 50:
|
|
|
+ tag=loading_descriptors summary="Loading relay descriptors"
|
|
|
+
|
|
|
+ We will ask for relay descriptors from several different locations,
|
|
|
+ so this step will probably make up the bulk of the bootstrapping,
|
|
|
+ especially for users with slow connections. We stay in this phase until
|
|
|
+ we have descriptors for at least 1/4 of the usable relays listed in
|
|
|
+ the networkstatus consensus. This phase is also a good opportunity to
|
|
|
+ use the "progress" keyword to indicate partial steps.
|
|
|
+
|
|
|
+ Phase 80:
|
|
|
+ tag=conn_or summary="Connecting to entry guard"
|
|
|
+
|
|
|
+ Once we have a valid consensus and enough relay descriptors, we choose
|
|
|
+ some entry guards and start trying to build some circuits. This step
|
|
|
+ is similar to the "conn_dir" phase above; the only difference is
|
|
|
+ the context.
|
|
|
+
|
|
|
+ If a Tor starts with enough recent cached directory information,
|
|
|
+ its first bootstrap status event will be for the conn_or phase.
|
|
|
+
|
|
|
+ Phase 85:
|
|
|
+ tag=handshake_or summary="Finishing handshake with entry guard"
|
|
|
+
|
|
|
+ This phase is similar to the "handshake_dir" phase, but it gets reached
|
|
|
+ if we finish a TCP connection to a Tor relay and we have already reached
|
|
|
+ the "conn_or" phase. We'll stay in this phase until we complete a TLS
|
|
|
+ handshake with a Tor relay.
|
|
|
+
|
|
|
+ Phase 90:
|
|
|
+ tag=circuit_create "Establishing circuits"
|
|
|
+
|
|
|
+ Once we've finished our TLS handshake with an entry guard, we will
|
|
|
+ set about trying to make some 3-hop circuits in case we need them soon.
|
|
|
+
|
|
|
+ Phase 100:
|
|
|
+ tag=done summary="Done"
|
|
|
+
|
|
|
+ A full 3-hop exit circuit has been established. Tor is ready to handle
|
|
|
+ application connections now.
|
|
|
+
|