From 8587cc799f9cb45d1f18ff1256ce9aee72982e1a Mon Sep 17 00:00:00 2001 From: Poet (Tim Sally) Date: Tue, 16 Nov 2010 12:33:38 -0600 Subject: [PATCH 3/3] (1) Several updates to grammars for events and GETINFO results. All relate to the fact that LongName has replaced ServerID since 0.2.2.1-alpha. See documentation of VERBOSE_NAMES for more information. The following grammars were changed: * orconn-status GETINFO result * entry-guards GETINFO result * Path general token * OR Connection status changed event * New descriptors available event In all cases a note was added about when the old grammar applies. (2) Update to the description of entry-guards. The description incorrectly said that the helper-nodes alias would be removed in 0.1.3.x. As of this writing the helper-nodes alias is still in Tor. --- doc/spec/control-spec.txt | 58 +++++++++++++++++++++++++++++++------------- 1 files changed, 41 insertions(+), 17 deletions(-) diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt index 4a94e89..4e5c34b 100644 --- a/doc/spec/control-spec.txt +++ b/doc/spec/control-spec.txt @@ -481,27 +481,36 @@ StreamID SP StreamStatus SP CircID SP Target CRLF "orconn-status" - A series of lines as for an OR connection status event. Each is of the - form: + A series of lines as for an OR connection status event. In Tor + 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor + 0.2.2.1-alpha and later by default, each line is of the form: + LongName SP ORStatus CRLF + + Before 0.1.2.2-alpha, each line is of the form: ServerID SP ORStatus CRLF "entry-guards" A series of lines listing the currently chosen entry guards, if any. - Each is of the form: + In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor + 0.2.2.1-alpha and later by default, each line is of the form: + LongName SP Status [SP ISOTime] CRLF + + Before 0.1.2.2-alpha, each line is of the form: ServerID2 SP Status [SP ISOTime] CRLF + ServerID2 = Nickname / 40*HEXDIG - Status-with-time = ("unlisted") SP ISOTime - Status = ("up" / "never-connected" / "down" / - "unusable" / "unlisted" ) + The definition of Status is the same for both: + Status = "up" / "never-connected" / "down" / + "unusable" / "unlisted" - ServerID2 = Nickname / 40*HEXDIG - [From 0.1.1.4-alpha to 0.1.1.10-alpha, this was called "helper-nodes". - Tor still supports calling it that for now, but support will be - removed in 0.1.3.x.] - [Older versions of Tor (before 0.1.2.x-final) generated 'down' instead - of unlisted/unusable. Current Tors never generate 'down'.] + From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called + "helper-nodes". Tor still supports calling "helper-nodes", but it + is depricated and should not be used + + [Note that older versions of Tor (before 0.1.2.x-final) generated 'down' + instead of unlisted/unusable. Current Tors never generate 'down'.] [XXXX ServerID2 differs from ServerID in not prefixing fingerprints with a $. This is an implementation error. It would be nice to add @@ -1005,7 +1014,11 @@ "FAILED" / ; circuit closed (was not built) "CLOSED" ; circuit closed (was built) - Path = ServerID *("," ServerID) + Path = LongName *("," LongName) + ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, Path + ; is as follows: + Path = ServerID *("," ServerID) Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" / "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" / @@ -1094,19 +1107,26 @@ 4.1.3. OR Connection status changed The syntax is: - "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON=" + + "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON=" Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED" + ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, OR + ; Connection is as follows: + "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON=" + Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF + NEW is for incoming connections, and LAUNCHED is for outgoing connections. CONNECTED means the TLS handshake has finished (in either direction). FAILED means a connection is being closed that hasn't finished its handshake, and CLOSED is for connections that have handshaked. - A ServerID is specified unless it's a NEW connection, in which - case we don't know what server it is yet, so we use Address:Port. + A LongName or ServerID is specified unless it's a NEW connection, in + which case we don't know what server it is yet, so we use Address:Port. If extended events are enabled (see 3.19), optional reason and circuit counting information is provided for CLOSED and FAILED @@ -1143,7 +1163,11 @@ 4.1.6. New descriptors available Syntax: - "650" SP "NEWDESC" 1*(SP ServerID) CRLF + "650" SP "NEWDESC" 1*(SP LongName) CRLF + ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, it + ; is as follows: + "650" SP "NEWDESC" 1*(SP ServerID) CRLF 4.1.7. New Address mapping -- 1.7.3.1