[or-cvs] r8589: Control-spec tweaks: add USEFEATURE, along with description (in tor/trunk: . doc)
nickm at seul.org
nickm at seul.org
Tue Oct 3 18:59:57 UTC 2006
Date: 2006-10-03 14:59:57 -0400 (Tue, 03 Oct 2006)
New Revision: 8589
r8858 at totoro: nickm | 2006-10-03 14:20:40 -0400
Control-spec tweaks: add USEFEATURE, along with description of new naming scheme.
Property changes on: tor/trunk
svk:merge ticket from /tor/branches/verbose-nicknames [r8858] on 96637b51-b116-0410-a10e-9941ebb49b64
--- tor/trunk/doc/control-spec.txt 2006-10-03 18:59:52 UTC (rev 8588)
+++ tor/trunk/doc/control-spec.txt 2006-10-03 18:59:57 UTC (rev 8589)
@@ -78,10 +78,30 @@
; Identifiers for servers.
ServerID = Nickname / Fingerprint
Nickname = 1*19 NicknameChar
NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
Fingerprint = "$" 40*HEXDIG
+ ; A "=" indicates that the given nickname is canonical; a "~" indicates
+ ; that the given nickname is not canonical.
+ LongName = Fingerprint [ ( "=" / "~" ) Nickname ]
+ ; How a controller tells Tor about a particular OR. There are four
+ ; possible formats:
+ ; $Digest -- The router whose identity key hashes to the given digest.
+ ; This is the preferred way to refer to an OR.
+ ; $Digest~Name -- The router whose identity key hashes to the given
+ ; digest, but only if the routes has the given nickname.
+ ; $Digest=Name -- The router whose identity key hashes to the given
+ ; digest, but only if the router is Named and has the given
+ ; nickname.
+ ; Name -- The Named router with the given nickname, or, if no such
+ ; router exists, any router whose nickname matches the one given.
+ ; This is not a safe way to refer to routers, since Named status
+ ; could under some circumstances change over time.
+ ServerSpec = LongName / Nickname
; Unique identifiers for streams or circuits. Currently, Tor only
; uses digits, but this may change
StreamID = 1*16 IDChar
@@ -438,7 +458,7 @@
Sent from the client to the server. The format is:
"EXTENDCIRCUIT" SP CircuitID SP
- ServerID *("," ServerID) SP
+ ServerSpec *("," ServerSpec) SP
("purpose=" Purpose) CRLF
This request takes one of two forms: either the CircuitID is zero, in
@@ -571,6 +591,46 @@
Tells the server to hang up on this controller connection. This command
can be used before authenticating.
+ The syntax is:
+ "USEFEATURE" *(SP FeatureName) CRLF
+ FeatureName = 1*(ALPHA / DIGIT / "_" / "-")
+ Sometimes extensions to the controller protocol break compatibility with
+ older controllers. In this case, whenever possible, the extensions are
+ first included in Tor disabled by default, and only enabled on a given
+ controller connection when the 'USEFEATURE' command is given. Once a
+ "USEFEATURE" command is given, it applies to all subsequent interactions on
+ the same connection; to disable an enabled feature, a new controller
+ connection must be opened.
+ This is a forward-compatibility mechanism; each feature will eventually
+ become a regular part of the control protocol in some future version of Tor.
+ Tor will ignore a request to use any feature that is already on by default.
+ Tor will give a "552" error if any requested feature is not recognized.
+ Feature names are case-insensitive.
+ Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to
+ request the extended event syntax.
+ This will not be enabled-by-default until at least XXX (or, at least two
+ stable releases after XXX, the release where it was first used for
+ Instead of ServerID as specified elsewhere, the controller should
+ identify ORs by LongName in events and GETINFO results. This format is
+ strictly more informative, since rather than including Nickname for
+ known Named routers and Fingerprint for unknown or unNamed routers; the
+ LongName format includes a Fingerprint, an indication of Named status,
+ and a Nickname (if one is known).
Reply codes follow the same 3-character format as used by SMTP, with the
More information about the tor-commits