Add xxx-single-guard-node as proposal 236.
[torspec.git] / control-spec.txt
1
2                    TC: A Tor control protocol (Version 1)
3
4 0. Scope
5
6   This document describes an implementation-specific protocol that is used
7   for other programs (such as frontend user-interfaces) to communicate with a
8   locally running Tor process.  It is not part of the Tor onion routing
9   protocol.
10
11   This protocol replaces version 0 of TC, which is now deprecated.  For
12   reference, TC is described in "control-spec-v0.txt".  Implementors are
13   recommended to avoid using TC directly, but instead to use a library that
14   can easily be updated to use the newer protocol.  (Version 0 is used by Tor
15   versions 0.1.0.x; the protocol in this document only works with Tor
16   versions in the 0.1.1.x series and later.)
17
18       The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
19       NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
20       "OPTIONAL" in this document are to be interpreted as described in
21       RFC 2119.
22
23 1. Protocol outline
24
25   TC is a bidirectional message-based protocol.  It assumes an underlying
26   stream for communication between a controlling process (the "client"
27   or "controller") and a Tor process (or "server").  The stream may be
28   implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on,
29   but it must provide reliable in-order delivery.  For security, the
30   stream should not be accessible by untrusted parties.
31
32   In TC, the client and server send typed messages to each other over the
33   underlying stream.  The client sends "commands" and the server sends
34   "replies".
35
36   By default, all messages from the server are in response to messages from
37   the client.  Some client requests, however, will cause the server to send
38   messages to the client indefinitely far into the future.  Such
39   "asynchronous" replies are marked as such.
40
41   Servers respond to messages in the order messages are received.
42
43 1.1. Forward-compatibility
44
45   This is an evolving protocol; new client and server behavior will be
46   allowed in future versions.  To allow new backward-compatible client
47   on behalf of the client, we may add new commands and allow existing
48   commands to take new arguments in future versions.  To allow new
49   backward-compatible server behavior, we note various places below
50   where servers speaking a future versions of this protocol may insert
51   new data, and note that clients should/must "tolerate" unexpected
52   elements in these places.  There are two ways that we do this:
53
54   * Adding a new field to a message:
55
56     For example, we might say "This message has three space-separated
57     fields; clients MUST tolerate more fields."  This means that a
58     client MUST NOT crash or otherwise fail to parse the message or
59     other subsequent messages when there are more than three fields, and
60     that it SHOULD function at least as well when more fields are
61     provided as it does when it only gets the fields it accepts.  The
62     most obvious way to do this is by ignoring additional fields; the
63     next-most-obvious way is to report additional fields verbatim to the
64     user, perhaps as part of an expert UI.
65
66   * Adding a new possible value to a list of alternatives:
67
68     For example, we might say "This field will be OPEN, CLOSED, or
69     CONNECTED.  Clients MUST tolerate unexpected values."  This means
70     that a client MUST NOT crash or otherwise fail to parse the message
71     or other subsequent when there are unexpected values, and that the
72     client SHOULD try to handle the rest of the message as well as it
73     can.  The most obvious way to do this is by pretending that each
74     list of alternatives has an additional "unrecognized value" element,
75     and mapping any unrecognized values to that element; the
76     next-most-obvious way is to create a separate "unrecognized value"
77     element for each unrecognized value.
78
79     Clients SHOULD NOT "tolerate" unrecognized alternatives by
80     pretending that the message containing them is absent.  For example,
81     a stream closed for an unrecognized reason is nevertheless closed,
82     and should be reported as such.
83
84     (If some list of alternatives is given, and there isn't an explicit
85     statement that clients must tolerate unexpected values, clients still
86     must tolerate unexpected values. The only exception would be if there
87     were an explicit statement that no future values will ever be added.)
88
89 2. Message format
90
91 2.1. Description format
92
93   The message formats listed below use ABNF as described in RFC 2234.
94   The protocol itself is loosely based on SMTP (see RFC 2821).
95
96   We use the following nonterminals from RFC 2822: atom, qcontent
97
98   We define the following general-use nonterminals:
99
100      QuotedString = DQUOTE *qcontent DQUOTE
101
102   There are explicitly no limits on line length.  All 8-bit characters
103   are permitted unless explicitly disallowed.  In QuotedStrings,
104   backslashes and quotes must be escaped; other characters need not be
105   escaped.
106
107   Wherever CRLF is specified to be accepted from the controller, Tor MAY also
108   accept LF.  Tor, however, MUST NOT generate LF instead of CRLF.
109   Controllers SHOULD always send CRLF.
110
111 2.2. Commands from controller to Tor
112
113     Command = Keyword OptArguments CRLF / "+" Keyword OptArguments CRLF CmdData
114     Keyword = 1*ALPHA
115     OptArguments = [ SP *(SP / VCHAR) ]
116
117   A command is either a single line containing a Keyword and arguments, or a
118   multiline command whose initial keyword begins with +, and whose data
119   section ends with a single "." on a line of its own.  (We use a special
120   character to distinguish multiline commands so that Tor can correctly parse
121   multi-line commands that it does not recognize.) Specific commands and
122   their arguments are described below in section 3.
123
124 2.3. Replies from Tor to the controller
125
126     Reply = SyncReply / AsyncReply
127     SyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
128     AsyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
129
130     MidReplyLine = StatusCode "-" ReplyLine
131     DataReplyLine = StatusCode "+" ReplyLine CmdData
132     EndReplyLine = StatusCode SP ReplyLine
133     ReplyLine = [ReplyText] CRLF
134     ReplyText = XXXX
135     StatusCode = 3DIGIT
136
137   Specific replies are mentioned below in section 3, and described more fully
138   in section 4.
139
140   [Compatibility note:  versions of Tor before 0.2.0.3-alpha sometimes
141   generate AsyncReplies of the form "*(MidReplyLine / DataReplyLine)".
142   This is incorrect, but controllers that need to work with these
143   versions of Tor should be prepared to get multi-line AsyncReplies with
144   the final line (usually "650 OK") omitted.]
145
146 2.4. General-use tokens
147
148   ; CRLF means, "the ASCII Carriage Return character (decimal value 13)
149   ; followed by the ASCII Linefeed character (decimal value 10)."
150   CRLF = CR LF
151
152   ; How a controller tells Tor about a particular OR.  There are four
153   ; possible formats:
154   ;    $Fingerprint -- The router whose identity key hashes to the fingerprint.
155   ;        This is the preferred way to refer to an OR.
156   ;    $Fingerprint~Nickname -- The router whose identity key hashes to the
157   ;        given fingerprint, but only if the router has the given nickname.
158   ;    $Fingerprint=Nickname -- The router whose identity key hashes to the
159   ;        given fingerprint, but only if the router is Named and has the given
160   ;        nickname.
161   ;    Nickname -- The Named router with the given nickname, or, if no such
162   ;        router exists, any router whose nickname matches the one given.
163   ;        This is not a safe way to refer to routers, since Named status
164   ;        could under some circumstances change over time.
165   ;
166   ; The tokens that implement the above follow:
167
168   ServerSpec = LongName / Nickname
169   LongName   = Fingerprint [ ( "=" / "~" ) Nickname ]
170
171   Fingerprint = "$" 40*HEXDIG
172   NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
173   Nickname = 1*19 NicknameChar
174
175   ; What follows is an outdated way to refer to ORs.
176   ; Feature VERBOSE_NAMES replaces ServerID with LongName in events and
177   ; GETINFO results. VERBOSE_NAMES can be enabled starting in Tor version
178   ; 0.1.2.2-alpha and it is always-on in 0.2.2.1-alpha and later.
179   ServerID = Nickname / Fingerprint
180
181
182   ; Unique identifiers for streams or circuits.  Currently, Tor only
183   ; uses digits, but this may change
184   StreamID = 1*16 IDChar
185   CircuitID = 1*16 IDChar
186   ConnID = 1*16 IDChar
187   QueueID = 1*16 IDChar
188   IDChar = ALPHA / DIGIT
189
190   Address = ip4-address / ip6-address / hostname   (XXXX Define these)
191
192   ; A "CmdData" section is a sequence of octets concluded by the terminating
193   ; sequence CRLF "." CRLF.  The terminating sequence may not appear in the
194   ; body of the data.  Leading periods on lines in the data are escaped with
195   ; an additional leading period as in RFC 2821 section 4.5.2.
196   CmdData = *DataLine "." CRLF
197   DataLine = CRLF / "." 1*LineItem CRLF / NonDotItem *LineItem CRLF
198   LineItem = NonCR / 1*CR NonCRLF
199   NonDotItem = NonDotCR / 1*CR NonCRLF
200
201   ; ISOTime, ISOTime2, and ISOTime2Frac are time formats as specified in
202   ; ISO8601.
203   ;  example ISOTime:      "2012-01-11 12:15:33"
204   ;  example ISOTime2:     "2012-01-11T12:15:33"
205   ;  example ISOTime2Frac: "2012-01-11T12:15:33.51"
206   IsoDatePart = 4*DIGIT "-" 2*DIGIT "-" 2*DIGIT
207   IsoTimePart = 2*DIGIT ":" 2*DIGIT ":" 2*DIGIT
208   ISOTime  = IsoDatePart " " IsoTimePart
209   ISOTime2 = IsoDatePart "T" IsoTimePart
210   ISOTime2Frac = IsoTime2 [ "." 1*DIGIT ]
211
212 3. Commands
213
214   All commands are case-insensitive, but most keywords are case-sensitive.
215
216 3.1. SETCONF
217
218   Change the value of one or more configuration variables.  The syntax is:
219
220     "SETCONF" 1*(SP keyword ["=" value]) CRLF
221     value = String / QuotedString
222
223   Tor behaves as though it had just read each of the key-value pairs
224   from its configuration file.  Keywords with no corresponding values have
225   their configuration values reset to 0 or NULL (use RESETCONF if you want
226   to set it back to its default).  SETCONF is all-or-nothing: if there
227   is an error in any of the configuration settings, Tor sets none of them.
228
229   Tor responds with a "250 configuration values set" reply on success.
230   If some of the listed keywords can't be found, Tor replies with a
231   "552 Unrecognized option" message. Otherwise, Tor responds with a
232   "513 syntax error in configuration values" reply on syntax error, or a
233   "553 impossible configuration setting" reply on a semantic error.
234
235   Some configuration options (e.g. "Bridge") take multiple values. Also,
236   some configuration keys (e.g. for hidden services and for entry
237   guard lists) form a context-sensitive group where order matters (see
238   GETCONF below). In these cases, setting _any_ of the options in a
239   SETCONF command is taken to reset all of the others. For example,
240   if two ORListenAddress values are configured, and a SETCONF command
241   arrives containing a single ORListenAddress value, the new command's
242   value replaces the two old values.
243
244   Sometimes it is not possible to change configuration options solely by
245   issuing a series of SETCONF commands, because the value of one of the
246   configuration options depends on the value of another which has not yet
247   been set. Such situations can be overcome by setting multiple configuration
248   options with a single SETCONF command (e.g. SETCONF ORPort=443
249   ORListenAddress=9001).
250
251 3.2. RESETCONF
252
253   Remove all settings for a given configuration option entirely, assign
254   its default value (if any), and then assign the String provided.
255   Typically the String is left empty, to simply set an option back to
256   its default. The syntax is:
257
258     "RESETCONF" 1*(SP keyword ["=" String]) CRLF
259
260   Otherwise it behaves like SETCONF above.
261
262 3.3. GETCONF
263
264   Request the value of a configuration variable.  The syntax is:
265
266     "GETCONF" 1*(SP keyword) CRLF
267
268   If all of the listed keywords exist in the Tor configuration, Tor replies
269   with a series of reply lines of the form:
270       250 keyword=value
271   If any option is set to a 'default' value semantically different from an
272   empty string, Tor may reply with a reply line of the form:
273       250 keyword
274
275   Value may be a raw value or a quoted string.  Tor will try to use unquoted
276   values except when the value could be misinterpreted through not being
277   quoted. (Right now, Tor supports no such misinterpretable values for
278   configuration options.)
279
280   If some of the listed keywords can't be found, Tor replies with a
281   "552 unknown configuration keyword" message.
282
283   If an option appears multiple times in the configuration, all of its
284   key-value pairs are returned in order.
285
286   Some options are context-sensitive, and depend on other options with
287   different keywords.  These cannot be fetched directly.  Currently there
288   is only one such option: clients should use the "HiddenServiceOptions"
289   virtual keyword to get all HiddenServiceDir, HiddenServicePort,
290   HiddenServiceVersion, and HiddenserviceAuthorizeClient option settings.
291
292 3.4. SETEVENTS
293
294   Request the server to inform the client about interesting events.  The
295   syntax is:
296
297      "SETEVENTS" [SP "EXTENDED"] *(SP EventCode) CRLF
298
299      EventCode = 1*(ALPHA / "_")  (see section 4.1.x for event types)
300
301   Any events *not* listed in the SETEVENTS line are turned off; thus, sending
302   SETEVENTS with an empty body turns off all event reporting.
303
304   The server responds with a "250 OK" reply on success, and a "552
305   Unrecognized event" reply if one of the event codes isn't recognized.  (On
306   error, the list of active event codes isn't changed.)
307
308   If the flag string "EXTENDED" is provided, Tor may provide extra
309   information with events for this connection; see 4.1 for more information.
310   NOTE: All events on a given connection will be provided in extended format,
311   or none.
312   NOTE: "EXTENDED" was first supported in Tor 0.1.1.9-alpha; it is
313   always-on in Tor 0.2.2.1-alpha and later.
314
315   Each event is described in more detail in Section 4.1.
316
317 3.5. AUTHENTICATE
318
319   Sent from the client to the server.  The syntax is:
320      "AUTHENTICATE" [ SP 1*HEXDIG / QuotedString ] CRLF
321
322   The server responds with "250 OK" on success or "515 Bad authentication" if
323   the authentication cookie is incorrect.  Tor closes the connection on an
324   authentication failure.
325
326   The authentication token can be specified as either a quoted ASCII string,
327   or as an unquoted hexadecimal encoding of that same string (to avoid escaping
328   issues).
329
330   For information on how the implementation securely stores authentication
331   information on disk, see section 5.1.
332
333   Before the client has authenticated, no command other than
334   PROTOCOLINFO, AUTHCHALLENGE, AUTHENTICATE, or QUIT is valid.  If the
335   controller sends any other command, or sends a malformed command, or
336   sends an unsuccessful AUTHENTICATE command, or sends PROTOCOLINFO or
337   AUTHCHALLENGE more than once, Tor sends an error reply and closes
338   the connection.
339
340   To prevent some cross-protocol attacks, the AUTHENTICATE command is still
341   required even if all authentication methods in Tor are disabled.  In this
342   case, the controller should just send "AUTHENTICATE" CRLF.
343
344   (Versions of Tor before 0.1.2.16 and 0.2.0.4-alpha did not close the
345   connection after an authentication failure.)
346
347 3.6. SAVECONF
348
349   Sent from the client to the server.  The syntax is:
350      "SAVECONF" CRLF
351
352   Instructs the server to write out its config options into its torrc. Server
353   returns "250 OK" if successful, or "551 Unable to write configuration
354   to disk" if it can't write the file or some other error occurs.
355
356   See also the "getinfo config-text" command, if the controller wants
357   to write the torrc file itself.
358
359 3.7. SIGNAL
360
361   Sent from the client to the server. The syntax is:
362
363      "SIGNAL" SP Signal CRLF
364
365      Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" /
366               "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" /
367               "CLEARDNSCACHE"
368
369   The meaning of the signals are:
370
371       RELOAD    -- Reload: reload config items. (like HUP)
372       SHUTDOWN  -- Controlled shutdown: if server is an OP, exit immediately.
373                    If it's an OR, close listeners and exit after
374                    ShutdownWaitLength seconds. (like INT)
375       DUMP      -- Dump stats: log information about open connections and
376                    circuits. (like USR1)
377       DEBUG     -- Debug: switch all open logs to loglevel debug. (like USR2)
378       HALT      -- Immediate shutdown: clean up and exit now. (like TERM)
379       CLEARDNSCACHE -- Forget the client-side cached IPs for all hostnames.
380       NEWNYM    -- Switch to clean circuits, so new application requests
381                    don't share any circuits with old ones.  Also clears
382                    the client-side DNS cache.  (Tor MAY rate-limit its
383                    response to this signal.)
384
385   The server responds with "250 OK" if the signal is recognized (or simply
386   closes the socket if it was asked to close immediately), or "552
387   Unrecognized signal" if the signal is unrecognized.
388
389 3.8. MAPADDRESS
390
391   Sent from the client to the server.  The syntax is:
392
393     "MAPADDRESS" 1*(Address "=" Address SP) CRLF
394
395   The first address in each pair is an "original" address; the second is a
396   "replacement" address.  The client sends this message to the server in
397   order to tell it that future SOCKS requests for connections to the original
398   address should be replaced with connections to the specified replacement
399   address.  If the addresses are well-formed, and the server is able to
400   fulfill the request, the server replies with a 250 message:
401     250-OldAddress1=NewAddress1
402     250 OldAddress2=NewAddress2
403
404   containing the source and destination addresses.  If request is
405   malformed, the server replies with "512 syntax error in command
406   argument".  If the server can't fulfill the request, it replies with
407   "451 resource exhausted".
408
409   The client may decline to provide a body for the original address, and
410   instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
411   "." for hostname), signifying that the server should choose the original
412   address itself, and return that address in the reply.  The server
413   should ensure that it returns an element of address space that is unlikely
414   to be in actual use.  If there is already an address mapped to the
415   destination address, the server may reuse that mapping.
416
417   If the original address is already mapped to a different address, the old
418   mapping is removed.  If the original address and the destination address
419   are the same, the server removes any mapping in place for the original
420   address.
421
422   Example:
423     C: MAPADDRESS 0.0.0.0=torproject.org 1.2.3.4=tor.freehaven.net
424     S: 250-127.192.10.10=torproject.org
425     S: 250 1.2.3.4=tor.freehaven.net
426
427   {Note: This feature is designed to be used to help Tor-ify applications
428   that need to use SOCKS4 or hostname-less SOCKS5.  There are three
429   approaches to doing this:
430      1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
431      2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
432         feature) to resolve the hostname remotely.  This doesn't work
433         with special addresses like x.onion or x.y.exit.
434      3. Use MAPADDRESS to map an IP address to the desired hostname, and then
435         arrange to fool the application into thinking that the hostname
436         has resolved to that IP.
437   This functionality is designed to help implement the 3rd approach.}
438
439   Mappings set by the controller last until the Tor process exits:
440   they never expire. If the controller wants the mapping to last only
441   a certain time, then it must explicitly un-map the address when that
442   time has elapsed.
443
444 3.9. GETINFO
445
446   Sent from the client to the server.  The syntax is as for GETCONF:
447     "GETINFO" 1*(SP keyword) CRLF
448   one or more NL-terminated strings.  The server replies with an INFOVALUE
449   message, or a 551 or 552 error.
450
451   Unlike GETCONF, this message is used for data that are not stored in the Tor
452   configuration file, and that may be longer than a single line.  On success,
453   one ReplyLine is sent for each requested value, followed by a final 250 OK
454   ReplyLine.  If a value fits on a single line, the format is:
455       250-keyword=value
456   If a value must be split over multiple lines, the format is:
457       250+keyword=
458       value
459       .
460   Recognized keys and their values include:
461
462     "version" -- The version of the server's software, including the name
463       of the software. (example: "Tor 0.0.9.4")
464
465     "config-file" -- The location of Tor's configuration file ("torrc").
466
467     "config-defaults-file" -- The location of Tor's configuration
468       defaults file ("torrc.defaults").  This file gets parsed before
469       torrc, and is typically used to replace Tor's default
470       configuration values. [First implemented in 0.2.3.9-alpha.]
471
472     "config-text" -- The contents that Tor would write if you send it
473       a SAVECONF command, so the controller can write the file to
474       disk itself. [First implemented in 0.2.2.7-alpha.]
475
476     "exit-policy/default" -- The default exit policy lines that Tor will
477       *append* to the ExitPolicy config option.
478
479     "exit-policy/ipv4"
480     "exit-policy/ipv6"
481     "exit-policy/full" -- This OR's exit policy, in IPv4-only, IPv6-only, or
482       all-entries flavors.
483
484     "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest
485       server descriptor for a given OR.  (Note that modern Tor clients
486       do not download server descriptors by default, but download
487       microdescriptors instead.  If microdescriptors are enabled, you'll
488       need to use md/* instead.)
489
490     "md/id/<OR identity>" or "md/name/<OR nickname>" -- the latest
491       microdescriptor for a given OR. [First implemented in
492       0.2.3.8-alpha.]
493
494     "dormant" -- A nonnegative integer: zero if Tor is currently active and
495       building circuits, and nonzero if Tor has gone idle due to lack of use
496       or some similar reason.  [First implemented in 0.2.3.16-alpha]
497
498     "desc-annotations/id/<OR identity>" -- outputs the annotations string
499       (source, timestamp of arrival, purpose, etc) for the corresponding
500       descriptor. [First implemented in 0.2.0.13-alpha.]
501
502     "extra-info/digest/<digest>"  -- the extrainfo document whose digest (in
503       hex) is <digest>.  Only available if we're downloading extra-info
504       documents.
505
506     "ns/id/<OR identity>" or "ns/name/<OR nickname>" -- the latest router
507       status info (v3 directory style) for a given OR.  Router status
508       info is as given in
509       dir-spec.txt, and reflects the current beliefs of this Tor about the
510       router in question. Like directory clients, controllers MUST
511       tolerate unrecognized flags and lines.  The published date and
512       descriptor digest are those believed to be best by this Tor,
513       not necessarily those for a descriptor that Tor currently has.
514       [First implemented in 0.1.2.3-alpha.]
515       [In 0.2.0.9-alpha this switched from v2 directory style to v3]
516
517     "ns/all" -- Router status info (v3 directory style) for all ORs we
518       have an opinion about, joined by newlines.
519       [First implemented in 0.1.2.3-alpha.]
520       [In 0.2.0.9-alpha this switched from v2 directory style to v3]
521
522     "ns/purpose/<purpose>" -- Router status info (v3 directory style)
523       for all ORs of this purpose. Mostly designed for /ns/purpose/bridge
524       queries.
525       [First implemented in 0.2.0.13-alpha.]
526       [In 0.2.0.9-alpha this switched from v2 directory style to v3]
527
528     "desc/all-recent" -- the latest server descriptor for every router that
529       Tor knows about.  (See note about desc/id/* and desc/name/* above.)
530
531     "network-status" -- a space-separated list (v1 directory style)
532       of all known OR identities. This is in the same format as the
533       router-status line in v1 directories; see dir-spec-v1.txt section
534       3 for details.  (If VERBOSE_NAMES is enabled, the output will
535       not conform to dir-spec-v1.txt; instead, the result will be a
536       space-separated list of LongName, each preceded by a "!" if it is
537       believed to be not running.) This option is deprecated; use
538       "ns/all" instead.
539
540     "address-mappings/all"
541     "address-mappings/config"
542     "address-mappings/cache"
543     "address-mappings/control" -- a \r\n-separated list of address
544       mappings, each in the form of "from-address to-address expiry".
545       The 'config' key returns those address mappings set in the
546       configuration; the 'cache' key returns the mappings in the
547       client-side DNS cache; the 'control' key returns the mappings set
548       via the control interface; the 'all' target returns the mappings
549       set through any mechanism.
550       Expiry is formatted as with ADDRMAP events, except that "expiry" is
551       always a time in UTC or the string "NEVER"; see section 4.1.7.
552       First introduced in 0.2.0.3-alpha.
553
554     "addr-mappings/*" -- as for address-mappings/*, but without the
555       expiry portion of the value.  Use of this value is deprecated
556       since 0.2.0.3-alpha; use address-mappings instead.
557
558     "address" -- the best guess at our external IP address. If we
559       have no guess, return a 551 error. (Added in 0.1.2.2-alpha)
560
561     "fingerprint" -- the contents of the fingerprint file that Tor
562       writes as a relay, or a 551 if we're not a relay currently.
563       (Added in 0.1.2.3-alpha)
564
565     "circuit-status"
566       A series of lines as for a circuit status event. Each line is of
567       the form described in section 4.1.1, omitting the initial
568       "650 CIRC ".  Note that clients must be ready to accept additional
569       arguments as described in section 4.1.
570
571     "stream-status"
572       A series of lines as for a stream status event.  Each is of the form:
573          StreamID SP StreamStatus SP CircuitID SP Target CRLF
574
575     "orconn-status"
576       A series of lines as for an OR connection status event.  In Tor
577       0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
578       0.2.2.1-alpha and later by default, each line is of the form:
579          LongName SP ORStatus CRLF
580
581      In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
582      VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line
583      is of the form:
584          ServerID SP ORStatus CRLF
585
586     "entry-guards"
587       A series of lines listing the currently chosen entry guards, if any.
588       In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
589       0.2.2.1-alpha and later by default, each line is of the form:
590          LongName SP Status [SP ISOTime] CRLF
591
592      In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
593      VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line
594      is of the form:
595          ServerID2 SP Status [SP ISOTime] CRLF
596          ServerID2 = Nickname / 40*HEXDIG
597
598       The definition of Status is the same for both:
599          Status = "up" / "never-connected" / "down" /
600                   "unusable" / "unlisted"
601
602       [From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called
603        "helper-nodes". Tor still supports calling "helper-nodes", but it
604         is deprecated and should not be used.]
605
606       [Older versions of Tor (before 0.1.2.x-final) generated 'down' instead
607        of unlisted/unusable.  Current Tors never generate 'down'.]
608
609       [XXXX ServerID2 differs from ServerID in not prefixing fingerprints
610        with a $.  This is an implementation error.  It would be nice to add
611        the $ back in if we can do so without breaking compatibility.]
612
613     "traffic/read" -- Total bytes read (downloaded).
614
615     "traffic/written" -- Total bytes written (uploaded).
616
617     "accounting/enabled"
618     "accounting/hibernating"
619     "accounting/bytes"
620     "accounting/bytes-left"
621     "accounting/interval-start"
622     "accounting/interval-wake"
623     "accounting/interval-end"
624       Information about accounting status.  If accounting is enabled,
625       "enabled" is 1; otherwise it is 0.  The "hibernating" field is "hard"
626       if we are accepting no data; "soft" if we're accepting no new
627       connections, and "awake" if we're not hibernating at all.  The "bytes"
628       and "bytes-left" fields contain (read-bytes SP write-bytes), for the
629       start and the rest of the interval respectively.  The 'interval-start'
630       and 'interval-end' fields are the borders of the current interval; the
631       'interval-wake' field is the time within the current interval (if any)
632       where we plan[ned] to start being active. The times are UTC.
633
634     "config/names"
635       A series of lines listing the available configuration options. Each is
636       of the form:
637          OptionName SP OptionType [ SP Documentation ] CRLF
638          OptionName = Keyword
639          OptionType = "Integer" / "TimeInterval" / "TimeMsecInterval" /
640            "DataSize" / "Float" / "Boolean" / "Time" / "CommaList" /
641            "Dependant" / "Virtual" / "String" / "LineList"
642          Documentation = Text
643
644     "config/defaults"
645       A series of lines listing default values for each configuration
646       option. Options which don't have a valid default don't show up
647       in the list.  Introduced in Tor 0.2.4.1-alpha.
648          OptionName SP OptionValue CRLF
649          OptionName = Keyword
650          OptionValue = Text
651
652     "info/names"
653       A series of lines listing the available GETINFO options.  Each is of
654       one of these forms:
655          OptionName SP Documentation CRLF
656          OptionPrefix SP Documentation CRLF
657          OptionPrefix = OptionName "/*"
658       The OptionPrefix form indicates a number of options beginning with the
659       prefix. So if "config/*" is listed, other options beginning with
660       "config/" will work, but "config/*" itself is not an option.
661
662     "events/names"
663       A space-separated list of all the events supported by this version of
664       Tor's SETEVENTS.
665
666     "features/names"
667       A space-separated list of all the features supported by this version
668       of Tor's USEFEATURE.
669
670     "signal/names"
671       A space-separated list of all the values supported by the SIGNAL
672       command.
673
674     "ip-to-country/*"
675       Maps IP addresses to 2-letter country codes.  For example,
676       "GETINFO ip-to-country/18.0.0.1" should give "US".
677
678     "next-circuit/IP:port"
679       XXX todo.
680
681     "process/pid" -- Process id belonging to the main tor process.
682     "process/uid" -- User id running the tor process, -1 if unknown (this is
683      unimplemented on Windows, returning -1).
684     "process/user" -- Username under which the tor process is running,
685      providing an empty string if none exists (this is unimplemented on
686      Windows, returning an empty string).
687     "process/descriptor-limit" -- Upper bound on the file descriptor limit, -1
688      if unknown.
689
690     "dir/status-vote/current/consensus" [added in Tor 0.2.1.6-alpha]
691     "dir/status/authority"
692     "dir/status/fp/<F>"
693     "dir/status/fp/<F1>+<F2>+<F3>"
694     "dir/status/all"
695     "dir/server/fp/<F>"
696     "dir/server/fp/<F1>+<F2>+<F3>"
697     "dir/server/d/<D>"
698     "dir/server/d/<D1>+<D2>+<D3>"
699     "dir/server/authority"
700     "dir/server/all"
701       A series of lines listing directory contents, provided according to the
702       specification for the URLs listed in Section 4.4 of dir-spec.txt.  Note
703       that Tor MUST NOT provide private information, such as descriptors for
704       routers not marked as general-purpose.  When asked for 'authority'
705       information for which this Tor is not authoritative, Tor replies with
706       an empty string.
707
708       Note that, as of Tor 0.2.3.3-alpha, Tor clients don't download server
709       descriptors anymore, but microdescriptors.  So, a "551 Servers
710       unavailable" reply to all "GETINFO dir/server/*" requests is actually
711       correct.  If you have an old program which absolutely requires server
712       descriptors to work, try setting UseMicrodescriptors 0 or
713       FetchUselessDescriptors 1 in your client's torrc.
714
715     "status/circuit-established"
716     "status/enough-dir-info"
717     "status/good-server-descriptor"
718     "status/accepted-server-descriptor"
719     "status/..."
720       These provide the current internal Tor values for various Tor
721       states. See Section 4.1.10 for explanations. (Only a few of the
722       status events are available as getinfo's currently. Let us know if
723       you want more exposed.)
724     "status/reachability-succeeded/or"
725       0 or 1, depending on whether we've found our ORPort reachable.
726     "status/reachability-succeeded/dir"
727       0 or 1, depending on whether we've found our DirPort reachable.
728     "status/reachability-succeeded"
729       "OR=" ("0"/"1") SP "DIR=" ("0"/"1")
730       Combines status/reachability-succeeded/*; controllers MUST ignore
731       unrecognized elements in this entry.
732     "status/bootstrap-phase"
733       Returns the most recent bootstrap phase status event
734       sent. Specifically, it returns a string starting with either
735       "NOTICE BOOTSTRAP ..." or "WARN BOOTSTRAP ...". Controllers should
736       use this getinfo when they connect or attach to Tor to learn its
737       current bootstrap state.
738     "status/version/recommended"
739       List of currently recommended versions.
740     "status/version/current"
741       Status of the current version. One of: new, old, unrecommended,
742       recommended, new in series, obsolete, unknown.
743     "status/version/num-concurring"
744     "status/version/num-versioning"
745       These options are deprecated; they no longer give useful information.
746     "status/clients-seen"
747       A summary of which countries we've seen clients from recently,
748       formatted the same as the CLIENTS_SEEN status event described in
749       Section 4.1.14. This GETINFO option is currently available only
750       for bridge relays.
751
752     "net/listeners/or"
753     "net/listeners/dir"
754     "net/listeners/socks"
755     "net/listeners/trans"
756     "net/listeners/natd"
757     "net/listeners/dns"
758     "net/listeners/control"
759       A quoted, space-separated list of the locations where Tor is listening
760       for connections of the specified type. These can contain IPv4
761       network address...
762
763         "127.0.0.1:9050" "127.0.0.1:9051"
764
765       ... or local unix sockets...
766
767         "unix:/home/my_user/.tor/socket"
768
769       ... or IPv6 network addresses:
770
771         "[2001:0db8:7000:0000:0000:dead:beef:1234]:9050"
772
773       [New in Tor 0.2.2.26-beta.]
774
775     "dir-usage"
776       A newline-separated list of how many bytes we've served to answer
777       each type of directory request. The format of each line is:
778          Keyword 1*SP Integer 1*SP Integer
779       where the first integer is the number of bytes written, and the second
780       is the number of requests answered.
781
782   Examples:
783      C: GETINFO version desc/name/moria1
784      S: 250+desc/name/moria=
785      S: [Descriptor for moria]
786      S: .
787      S: 250-version=Tor 0.1.1.0-alpha-cvs
788      S: 250 OK
789
790 3.10. EXTENDCIRCUIT
791
792   Sent from the client to the server.  The format is:
793       "EXTENDCIRCUIT" SP CircuitID
794                       [SP ServerSpec *("," ServerSpec)]
795                       [SP "purpose=" Purpose] CRLF
796
797   This request takes one of two forms: either the CircuitID is zero, in
798   which case it is a request for the server to build a new circuit,
799   or the CircuitID is nonzero, in which case it is a request for the
800   server to extend an existing circuit with that ID according to the
801   specified path.
802
803   If the CircuitID is 0, the controller has the option of providing
804   a path for Tor to use to build the circuit. If it does not provide
805   a path, Tor will select one automatically from high capacity nodes
806   according to path-spec.txt.
807
808   If CircuitID is 0 and "purpose=" is specified, then the circuit's
809   purpose is set. Two choices are recognized: "general" and
810   "controller". If not specified, circuits are created as "general".
811
812   If the request is successful, the server sends a reply containing a
813   message body consisting of the CircuitID of the (maybe newly created)
814   circuit. The syntax is "250" SP "EXTENDED" SP CircuitID CRLF.
815
816 3.11. SETCIRCUITPURPOSE
817
818   Sent from the client to the server.  The format is:
819       "SETCIRCUITPURPOSE" SP CircuitID SP "purpose=" Purpose CRLF
820
821   This changes the circuit's purpose. See EXTENDCIRCUIT above for details.
822
823 3.12. SETROUTERPURPOSE
824
825   Sent from the client to the server.  The format is:
826       "SETROUTERPURPOSE" SP NicknameOrKey SP Purpose CRLF
827
828   This changes the descriptor's purpose. See +POSTDESCRIPTOR below
829   for details.
830
831   NOTE: This command was disabled and made obsolete as of Tor
832   0.2.0.8-alpha. It doesn't exist anymore, and is listed here only for
833   historical interest.
834
835 3.13. ATTACHSTREAM
836
837   Sent from the client to the server.  The syntax is:
838      "ATTACHSTREAM" SP StreamID SP CircuitID [SP "HOP=" HopNum] CRLF
839
840   This message informs the server that the specified stream should be
841   associated with the specified circuit.  Each stream may be associated with
842   at most one circuit, and multiple streams may share the same circuit.
843   Streams can only be attached to completed circuits (that is, circuits that
844   have sent a circuit status 'BUILT' event or are listed as built in a
845   GETINFO circuit-status request).
846
847   If the circuit ID is 0, responsibility for attaching the given stream is
848   returned to Tor.
849
850   If HOP=HopNum is specified, Tor will choose the HopNumth hop in the
851   circuit as the exit node, rather than the last node in the circuit.
852   Hops are 1-indexed; generally, it is not permitted to attach to hop 1.
853
854   Tor responds with "250 OK" if it can attach the stream, 552 if the
855   circuit or stream didn't exist, 555 if the stream isn't in an
856   appropriate state to be attached (e.g. it's already open), or 551 if
857   the stream couldn't be attached for another reason.
858
859   {Implementation note: Tor will close unattached streams by itself,
860   roughly two minutes after they are born. Let the developers know if
861   that turns out to be a problem.}
862
863   {Implementation note: By default, Tor automatically attaches streams to
864   circuits itself, unless the configuration variable
865   "__LeaveStreamsUnattached" is set to "1".  Attempting to attach streams
866   via TC when "__LeaveStreamsUnattached" is false may cause a race between
867   Tor and the controller, as both attempt to attach streams to circuits.}
868
869   {Implementation note: You can try to attachstream to a stream that
870   has already sent a connect or resolve request but hasn't succeeded
871   yet, in which case Tor will detach the stream from its current circuit
872   before proceeding with the new attach request.}
873
874 3.14. POSTDESCRIPTOR
875
876   Sent from the client to the server. The syntax is:
877     "+POSTDESCRIPTOR" [SP "purpose=" Purpose] [SP "cache=" Cache]
878                       CRLF Descriptor CRLF "." CRLF
879
880   This message informs the server about a new descriptor. If Purpose is
881   specified, it must be either "general", "controller", or "bridge",
882   else we return a 552 error. The default is "general".
883
884   If Cache is specified, it must be either "no" or "yes", else we
885   return a 552 error. If Cache is not specified, Tor will decide for
886   itself whether it wants to cache the descriptor, and controllers
887   must not rely on its choice.
888
889   The descriptor, when parsed, must contain a number of well-specified
890   fields, including fields for its nickname and identity.
891
892   If there is an error in parsing the descriptor, the server must send a
893   "554 Invalid descriptor" reply. If the descriptor is well-formed but
894   the server chooses not to add it, it must reply with a 251 message
895   whose body explains why the server was not added. If the descriptor
896   is added, Tor replies with "250 OK".
897
898 3.15. REDIRECTSTREAM
899
900   Sent from the client to the server. The syntax is:
901     "REDIRECTSTREAM" SP StreamID SP Address [SP Port] CRLF
902
903   Tells the server to change the exit address on the specified stream.  If
904   Port is specified, changes the destination port as well.  No remapping
905   is performed on the new provided address.
906
907   To be sure that the modified address will be used, this event must be sent
908   after a new stream event is received, and before attaching this stream to
909   a circuit.
910
911   Tor replies with "250 OK" on success.
912
913 3.16. CLOSESTREAM
914
915   Sent from the client to the server.  The syntax is:
916
917     "CLOSESTREAM" SP StreamID SP Reason *(SP Flag) CRLF
918
919   Tells the server to close the specified stream.  The reason should be one
920   of the Tor RELAY_END reasons given in tor-spec.txt, as a decimal.  Flags is
921   not used currently; Tor servers SHOULD ignore unrecognized flags.  Tor may
922   hold the stream open for a while to flush any data that is pending.
923
924   Tor replies with "250 OK" on success, or a 512 if there aren't enough
925   arguments, or a 552 if it doesn't recognize the StreamID or reason.
926
927 3.17. CLOSECIRCUIT
928
929    The syntax is:
930      "CLOSECIRCUIT" SP CircuitID *(SP Flag) CRLF
931      Flag = "IfUnused"
932
933   Tells the server to close the specified circuit.   If "IfUnused" is
934   provided, do not close the circuit unless it is unused.
935
936   Other flags may be defined in the future; Tor SHOULD ignore unrecognized
937   flags.
938
939   Tor replies with "250 OK" on success, or a 512 if there aren't enough
940   arguments, or a 552 if it doesn't recognize the CircuitID.
941
942 3.18. QUIT
943
944   Tells the server to hang up on this controller connection. This command
945   can be used before authenticating.
946
947 3.19. USEFEATURE
948
949   Adding additional features to the control protocol sometimes will break
950   backwards compatibility. Initially such features are added into Tor and
951   disabled by default. USEFEATURE can enable these additional features.
952
953   The syntax is:
954
955     "USEFEATURE" *(SP FeatureName) CRLF
956     FeatureName = 1*(ALPHA / DIGIT / "_" / "-")
957
958   Feature names are case-insensitive.
959
960   Once enabled, a feature stays enabled for the duration of the connection
961   to the controller. A new connection to the controller must be opened to
962   disable an enabled feature.
963
964   Features are a forward-compatibility mechanism; each feature will eventually
965   become a standard part of the control protocol. Once a feature becomes part
966   of the protocol, it is always-on. Each feature documents the version it was
967   introduced as a feature and the version in which it became part of the
968   protocol.
969
970   Tor will ignore a request to use any feature that is always-on. Tor will give
971   a 552 error in response to an unrecognized feature.
972
973   EXTENDED_EVENTS
974
975      Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to
976      request the extended event syntax.
977
978      This feature was first introduced in 0.1.2.3-alpha.  It is always-on
979      and part of the protocol in Tor 0.2.2.1-alpha and later.
980
981   VERBOSE_NAMES
982
983      Replaces ServerID with LongName in events and GETINFO results. LongName
984      provides a Fingerprint for all routers, an indication of Named status,
985      and a Nickname if one is known. LongName is strictly more informative
986      than ServerID, which only provides either a Fingerprint or a Nickname.
987
988      This feature was first introduced in 0.1.2.2-alpha. It is always-on and
989      part of the protocol in Tor 0.2.2.1-alpha and later.
990
991 3.20. RESOLVE
992
993   The syntax is
994     "RESOLVE" *Option *Address CRLF
995     Option = "mode=reverse"
996     Address = a hostname or IPv4 address
997
998   This command launches a remote hostname lookup request for every specified
999   request (or reverse lookup if "mode=reverse" is specified).  Note that the
1000   request is done in the background: to see the answers, your controller will
1001   need to listen for ADDRMAP events; see 4.1.7 below.
1002
1003   [Added in Tor 0.2.0.3-alpha]
1004
1005 3.21. PROTOCOLINFO
1006
1007   The syntax is:
1008     "PROTOCOLINFO" *(SP PIVERSION) CRLF
1009
1010   The server reply format is:
1011     "250-PROTOCOLINFO" SP PIVERSION CRLF *InfoLine "250 OK" CRLF
1012
1013     InfoLine = AuthLine / VersionLine / OtherLine
1014
1015      AuthLine = "250-AUTH" SP "METHODS=" AuthMethod *("," AuthMethod)
1016                        *(SP "COOKIEFILE=" AuthCookieFile) CRLF
1017      VersionLine = "250-VERSION" SP "Tor=" TorVersion OptArguments CRLF
1018
1019      AuthMethod =
1020       "NULL"           / ; No authentication is required
1021       "HASHEDPASSWORD" / ; A controller must supply the original password
1022       "COOKIE"         / ; A controller must supply the contents of a cookie
1023       "SAFECOOKIE"       ; A controller must prove knowledge of a cookie
1024
1025      AuthCookieFile = QuotedString
1026      TorVersion = QuotedString
1027
1028      OtherLine = "250-" Keyword OptArguments CRLF
1029
1030     PIVERSION: 1*DIGIT
1031
1032   Tor MAY give its InfoLines in any order; controllers MUST ignore InfoLines
1033   with keywords they do not recognize.  Controllers MUST ignore extraneous
1034   data on any InfoLine.
1035
1036   PIVERSION is there in case we drastically change the syntax one day. For
1037   now it should always be "1".  Controllers MAY provide a list of the
1038   protocolinfo versions they support; Tor MAY select a version that the
1039   controller does not support.
1040
1041   AuthMethod is used to specify one or more control authentication
1042   methods that Tor currently accepts.
1043
1044   AuthCookieFile specifies the absolute path and filename of the
1045   authentication cookie that Tor is expecting and is provided iff the
1046   METHODS field contains the method "COOKIE" and/or "SAFECOOKIE".
1047   Controllers MUST handle escape sequences inside this string.
1048
1049   All authentication cookies are 32 bytes long.  Controllers MUST NOT
1050   use the contents of a non-32-byte-long file as an authentication
1051   cookie.
1052
1053   If the METHODS field contains the method "SAFECOOKIE", every
1054   AuthCookieFile must contain the same authentication cookie.
1055
1056   The COOKIE authentication method exposes the user running a
1057   controller to an unintended information disclosure attack whenever
1058   the controller has greater filesystem read access than the process
1059   that it has connected to.  (Note that a controller may connect to a
1060   process other than Tor.)  It is almost never safe to use, even if
1061   the controller's user has explicitly specified which filename to
1062   read an authentication cookie from.  For this reason, the COOKIE
1063   authentication method has been deprecated and will be removed from
1064   a future version of Tor.
1065
1066   The VERSION line contains the Tor version.
1067
1068   [Unlike other commands besides AUTHENTICATE, PROTOCOLINFO may be used (but
1069   only once!) before AUTHENTICATE.]
1070
1071   [PROTOCOLINFO was not supported before Tor 0.2.0.5-alpha.]
1072
1073 3.22. LOADCONF
1074
1075   The syntax is:
1076     "+LOADCONF" CRLF ConfigText CRLF "." CRLF
1077
1078   This command allows a controller to upload the text of a config file
1079   to Tor over the control port.  This config file is then loaded as if
1080   it had been read from disk.
1081
1082   [LOADCONF was added in Tor 0.2.1.1-alpha.]
1083
1084 3.23. TAKEOWNERSHIP
1085
1086   The syntax is:
1087     "TAKEOWNERSHIP" CRLF
1088
1089   This command instructs Tor to shut down when this control
1090   connection is closed.  This command affects each control connection
1091   that sends it independently; if multiple control connections send
1092   the TAKEOWNERSHIP command to a Tor instance, Tor will shut down when
1093   any of those connections closes.
1094
1095   (As of Tor 0.2.5.2-alpha, Tor does not wait a while for circuits to
1096   close when shutting down because of an exiting controller.  If you
1097   want to ensure a clean shutdown--and you should!--then send "SIGNAL
1098   SHUTDOWN" and wait for the Tor process to close.)
1099
1100   This command is intended to be used with the
1101   __OwningControllerProcess configuration option.  A controller that
1102   starts a Tor process which the user cannot easily control or stop
1103   should 'own' that Tor process:
1104
1105     * When starting Tor, the controller should specify its PID in an
1106       __OwningControllerProcess on Tor's command line.  This will
1107       cause Tor to poll for the existence of a process with that PID,
1108       and exit if it does not find such a process.  (This is not a
1109       completely reliable way to detect whether the 'owning
1110       controller' is still running, but it should work well enough in
1111       most cases.)
1112
1113     * Once the controller has connected to Tor's control port, it
1114       should send the TAKEOWNERSHIP command along its control
1115       connection.  At this point, *both* the TAKEOWNERSHIP command and
1116       the __OwningControllerProcess option are in effect: Tor will
1117       exit when the control connection ends *and* Tor will exit if it
1118       detects that there is no process with the PID specified in the
1119       __OwningControllerProcess option.
1120
1121     * After the controller has sent the TAKEOWNERSHIP command, it
1122       should send "RESETCONF __OwningControllerProcess" along its
1123       control connection.  This will cause Tor to stop polling for the
1124       existence of a process with its owning controller's PID; Tor
1125       will still exit when the control connection ends.
1126
1127   [TAKEOWNERSHIP was added in Tor 0.2.2.28-beta.]
1128
1129 3.24. AUTHCHALLENGE
1130
1131   The syntax is:
1132     "AUTHCHALLENGE" SP "SAFECOOKIE"
1133                     SP ClientNonce
1134                     CRLF
1135
1136     ClientNonce = 2*HEXDIG / QuotedString
1137
1138   If the server accepts the command, the server reply format is:
1139     "250 AUTHCHALLENGE"
1140             SP "SERVERHASH=" ServerHash
1141             SP "SERVERNONCE=" ServerNonce
1142             CRLF
1143
1144     ServerHash = 64*64HEXDIG
1145     ServerNonce = 64*64HEXDIG
1146
1147   The ClientNonce, ServerHash, and ServerNonce values are
1148   encoded/decoded in the same way as the argument passed to the
1149   AUTHENTICATE command.  ServerNonce MUST be 32 bytes long.
1150
1151   ServerHash is computed as:
1152     HMAC-SHA256("Tor safe cookie authentication server-to-controller hash",
1153                 CookieString | ClientNonce | ServerNonce)
1154   (with the HMAC key as its first argument)
1155
1156   After a controller sends a successful AUTHCHALLENGE command, the
1157   next command sent on the connection must be an AUTHENTICATE command,
1158   and the only authentication string which that AUTHENTICATE command
1159   will accept is:
1160     HMAC-SHA256("Tor safe cookie authentication controller-to-server hash",
1161                 CookieString | ClientNonce | ServerNonce)
1162
1163   [Unlike other commands besides AUTHENTICATE, AUTHCHALLENGE may be
1164   used (but only once!) before AUTHENTICATE.]
1165
1166   [AUTHCHALLENGE was added in Tor FIXME.]
1167
1168 3.25. DROPGUARDS
1169
1170   The syntax is:
1171     "DROPGUARDS" CRLF
1172
1173   Tells the server to drop all guard nodes. Do not invoke this command
1174   lightly; it can increase vulnerability to tracking attacks over time.
1175
1176   Tor replies with "250 OK" on success.
1177
1178   [DROPGUARDS was added in Tor 0.2.5.2-alpha.]
1179
1180 4. Replies
1181
1182   Reply codes follow the same 3-character format as used by SMTP, with the
1183   first character defining a status, the second character defining a
1184   subsystem, and the third designating fine-grained information.
1185
1186   The TC protocol currently uses the following first characters:
1187
1188     2yz   Positive Completion Reply
1189        The command was successful; a new request can be started.
1190
1191     4yz   Temporary Negative Completion reply
1192        The command was unsuccessful but might be reattempted later.
1193
1194     5yz   Permanent Negative Completion Reply
1195        The command was unsuccessful; the client should not try exactly
1196        that sequence of commands again.
1197
1198     6yz   Asynchronous Reply
1199        Sent out-of-order in response to an earlier SETEVENTS command.
1200
1201   The following second characters are used:
1202
1203     x0z   Syntax
1204        Sent in response to ill-formed or nonsensical commands.
1205
1206     x1z   Protocol
1207        Refers to operations of the Tor Control protocol.
1208
1209     x5z   Tor
1210        Refers to actual operations of Tor system.
1211
1212   The following codes are defined:
1213
1214      250 OK
1215      251 Operation was unnecessary
1216          [Tor has declined to perform the operation, but no harm was done.]
1217
1218      451 Resource exhausted
1219
1220      500 Syntax error: protocol
1221
1222      510 Unrecognized command
1223      511 Unimplemented command
1224      512 Syntax error in command argument
1225      513 Unrecognized command argument
1226      514 Authentication required
1227      515 Bad authentication
1228
1229      550 Unspecified Tor error
1230
1231      551 Internal error
1232                [Something went wrong inside Tor, so that the client's
1233                 request couldn't be fulfilled.]
1234
1235      552 Unrecognized entity
1236                [A configuration key, a stream ID, circuit ID, event,
1237                 mentioned in the command did not actually exist.]
1238
1239      553 Invalid configuration value
1240          [The client tried to set a configuration option to an
1241            incorrect, ill-formed, or impossible value.]
1242
1243      554 Invalid descriptor
1244
1245      555 Unmanaged entity
1246
1247      650 Asynchronous event notification
1248
1249   Unless specified to have specific contents, the human-readable messages
1250   in error replies should not be relied upon to match those in this document.
1251
1252 4.1. Asynchronous events
1253
1254   These replies can be sent after a corresponding SETEVENTS command has been
1255   received.  They will not be interleaved with other Reply elements, but they
1256   can not appear between a command and its corresponding reply.  For example,
1257   this sequence is possible:
1258
1259      C: SETEVENTS CIRC
1260      S: 250 OK
1261      C: GETCONF SOCKSPORT ORPORT
1262      S: 650 CIRC 1000 EXTENDED moria1,moria2
1263      S: 250-SOCKSPORT=9050
1264      S: 250 ORPORT=0
1265
1266   But this sequence is disallowed:
1267      C: SETEVENTS CIRC
1268      S: 250 OK
1269      C: GETCONF SOCKSPORT ORPORT
1270      S: 250-SOCKSPORT=9050
1271      S: 650 CIRC 1000 EXTENDED moria1,moria2
1272      S: 250 ORPORT=0
1273
1274   Clients MUST tolerate more arguments in an asynchronous reply than
1275   expected, and MUST tolerate more lines in an asynchronous reply than
1276   expected.  For instance, a client that expects a CIRC message like:
1277       650 CIRC 1000 EXTENDED moria1,moria2
1278   must tolerate:
1279       650-CIRC 1000 EXTENDED moria1,moria2 0xBEEF
1280       650-EXTRAMAGIC=99
1281       650 ANONYMITY=high
1282
1283   If clients receives extended events (selected by USEFEATUERE
1284   EXTENDED_EVENTS in Tor 0.1.2.2-alpha..Tor-0.2.1.x, and always-on in
1285   Tor 0.2.2.x and later), then each event line as specified below may be
1286   followed by additional arguments and additional lines.  Additional
1287   lines will be of the form:
1288       "650" ("-"/" ") KEYWORD ["=" ARGUMENTS] CRLF
1289   Additional arguments will be of the form
1290       SP KEYWORD ["=" ( QuotedString / * NonSpDquote ) ]
1291
1292   Clients MUST tolerate events with arguments and keywords they do not
1293   recognize, and SHOULD process those events as if any unrecognized
1294   arguments and keywords were not present.
1295
1296   Clients SHOULD NOT depend on the order of keyword=value arguments,
1297   and SHOULD NOT depend on there being no new keyword=value arguments
1298   appearing between existing keyword=value arguments, though as of this
1299   writing (Jun 2011) some do.  Thus, extensions to this protocol should
1300   add new keywords only after the existing keywords, until all
1301   controllers have been fixed.  At some point this "SHOULD NOT" might
1302   become a "MUST NOT".
1303
1304 4.1.1. Circuit status changed
1305
1306    The syntax is:
1307
1308      "650" SP "CIRC" SP CircuitID SP CircStatus [SP Path]
1309           [SP "BUILD_FLAGS=" BuildFlags] [SP "PURPOSE=" Purpose]
1310           [SP "HS_STATE=" HSState] [SP "REND_QUERY=" HSAddress]
1311           [SP "TIME_CREATED=" TimeCreated]
1312           [SP "REASON=" Reason [SP "REMOTE_REASON=" Reason]] CRLF
1313
1314       CircStatus =
1315                "LAUNCHED" / ; circuit ID assigned to new circuit
1316                "BUILT"    / ; all hops finished, can now accept streams
1317                "EXTENDED" / ; one more hop has been completed
1318                "FAILED"   / ; circuit closed (was not built)
1319                "CLOSED"     ; circuit closed (was built)
1320
1321       Path = LongName *("," LongName)
1322         ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
1323         ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, Path
1324         ; is as follows:
1325         ; Path = ServerID *("," ServerID)
1326
1327       BuildFlags = BuildFlag *("," BuildFlag)
1328       BuildFlag = "ONEHOP_TUNNEL" / "IS_INTERNAL" /
1329                   "NEED_CAPACITY" / "NEED_UPTIME"
1330
1331       Purpose = "GENERAL" / "HS_CLIENT_INTRO" / "HS_CLIENT_REND" /
1332                 "HS_SERVICE_INTRO" / "HS_SERVICE_REND" / "TESTING" /
1333                 "CONTROLLER" / "MEASURE_TIMEOUT"
1334
1335       HSState = "HSCI_CONNECTING" / "HSCI_INTRO_SENT" / "HSCI_DONE" /
1336                 "HSCR_CONNECTING" / "HSCR_ESTABLISHED_IDLE" /
1337                 "HSCR_ESTABLISHED_WAITING" / "HSCR_JOINED" /
1338                 "HSSI_CONNECTING" / "HSSI_ESTABLISHED" /
1339                 "HSSR_CONNECTING" / "HSSR_JOINED"
1340
1341       HSAddress = 16*Base32Character
1342       Base32Character = ALPHA / "2" / "3" / "4" / "5" / "6" / "7"
1343
1344       TimeCreated = ISOTime2Frac
1345       Seconds = 1*DIGIT
1346       Microseconds = 1*DIGIT
1347
1348       Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" /
1349                "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" /
1350                "OR_IDENTITY" / "OR_CONN_CLOSED" / "TIMEOUT" /
1351                "FINISHED" / "DESTROYED" / "NOPATH" / "NOSUCHSERVICE" /
1352                "MEASUREMENT_EXPIRED"
1353
1354    The path is provided only when the circuit has been extended at least one
1355    hop.
1356
1357    The "BUILD_FLAGS" field is provided only in versions 0.2.3.11-alpha
1358    and later.  Clients MUST accept build flags not listed above.
1359    Build flags are defined as follows:
1360
1361       ONEHOP_TUNNEL   (one-hop circuit, used for tunneled directory conns)
1362       IS_INTERNAL     (internal circuit, not to be used for exiting streams)
1363       NEED_CAPACITY   (this circuit must use only high-capacity nodes)
1364       NEED_UPTIME     (this circuit must use only high-uptime nodes)
1365
1366    The "PURPOSE" field is provided only in versions 0.2.1.6-alpha and
1367    later, and only if extended events are enabled (see 3.19).  Clients
1368    MUST accept purposes not listed above.  Purposes are defined as
1369    follows:
1370
1371       GENERAL         (circuit for AP and/or directory request streams)
1372       HS_CLIENT_INTRO (HS client-side introduction-point circuit)
1373       HS_CLIENT_REND  (HS client-side rendezvous circuit; carries AP streams)
1374       HS_SERVICE_INTRO (HS service-side introduction-point circuit)
1375       HS_SERVICE_REND (HS service-side rendezvous circuit)
1376       TESTING         (reachability-testing circuit; carries no traffic)
1377       CONTROLLER      (circuit built by a controller)
1378       MEASURE_TIMEOUT (circuit being kept around to see how long it takes)
1379
1380    The "HS_STATE" field is provided only for hidden-service circuits,
1381    and only in versions 0.2.3.11-alpha and later.  Clients MUST accept
1382    hidden-service circuit states not listed above.  Hidden-service
1383    circuit states are defined as follows:
1384
1385       HSCI_*      (client-side introduction-point circuit states)
1386         HSCI_CONNECTING          (connecting to intro point)
1387         HSCI_INTRO_SENT          (sent INTRODUCE1; waiting for reply from IP)
1388         HSCI_DONE                (received reply from IP relay; closing)
1389
1390       HSCR_*      (client-side rendezvous-point circuit states)
1391         HSCR_CONNECTING          (connecting to or waiting for reply from RP)
1392         HSCR_ESTABLISHED_IDLE    (established RP; waiting for introduction)
1393         HSCR_ESTABLISHED_WAITING (introduction sent to HS; waiting for rend)
1394         HSCR_JOINED              (connected to HS)
1395
1396       HSSI_*      (service-side introduction-point circuit states)
1397         HSSI_CONNECTING          (connecting to intro point)
1398         HSSI_ESTABLISHED         (established intro point)
1399
1400       HSSR_*      (service-side rendezvous-point circuit states)
1401         HSSR_CONNECTING          (connecting to client's rend point)
1402         HSSR_JOINED              (connected to client's RP circuit)
1403
1404    The "REND_QUERY" field is provided only for hidden-service-related
1405    circuits, and only in versions 0.2.3.11-alpha and later.  Clients
1406    MUST accept hidden service addresses in formats other than that
1407    specified above.
1408
1409    The "TIME_CREATED" field is provided only in versions 0.2.3.11-alpha and
1410    later.  TIME_CREATED is the time at which the circuit was created or
1411    cannibalized.
1412
1413    The "REASON" field is provided only for FAILED and CLOSED events, and only
1414    if extended events are enabled (see 3.19).  Clients MUST accept reasons
1415    not listed above.  Reasons are as given in tor-spec.txt, except for:
1416
1417       NOPATH              (Not enough nodes to make circuit)
1418       MEASUREMENT_EXPIRED (As "TIMEOUT", except that we had left the circuit
1419                            open for measurement purposes to see how long it
1420                            would take to finish.)
1421
1422    The "REMOTE_REASON" field is provided only when we receive a DESTROY or
1423    TRUNCATE cell, and only if extended events are enabled.  It contains the
1424    actual reason given by the remote OR for closing the circuit. Clients MUST
1425    accept reasons not listed above.  Reasons are as listed in tor-spec.txt.
1426
1427 4.1.2. Stream status changed
1428
1429     The syntax is:
1430
1431       "650" SP "STREAM" SP StreamID SP StreamStatus SP CircuitID SP Target
1432           [SP "REASON=" Reason [ SP "REMOTE_REASON=" Reason ]]
1433           [SP "SOURCE=" Source] [ SP "SOURCE_ADDR=" Address ":" Port ]
1434           [SP "PURPOSE=" Purpose]
1435           CRLF
1436
1437       StreamStatus =
1438                "NEW"          / ; New request to connect
1439                "NEWRESOLVE"   / ; New request to resolve an address
1440                "REMAP"        / ; Address re-mapped to another
1441                "SENTCONNECT"  / ; Sent a connect cell along a circuit
1442                "SENTRESOLVE"  / ; Sent a resolve cell along a circuit
1443                "SUCCEEDED"    / ; Received a reply; stream established
1444                "FAILED"       / ; Stream failed and not retriable
1445                "CLOSED"       / ; Stream closed
1446                "DETACHED"       ; Detached from circuit; still retriable
1447
1448        Target = TargetAddress ":" Port
1449        Port = an integer from 0 to 65535 inclusive
1450        TargetAddress = Address / "(Tor_internal)"
1451
1452   The circuit ID designates which circuit this stream is attached to.  If
1453   the stream is unattached, the circuit ID "0" is given.  The target
1454   indicates the address which the stream is meant to resolve or connect to;
1455   it can be "(Tor_internal)" for a virtual stream created by the Tor program
1456   to talk to itself.
1457
1458       Reason = "MISC" / "RESOLVEFAILED" / "CONNECTREFUSED" /
1459                "EXITPOLICY" / "DESTROY" / "DONE" / "TIMEOUT" /
1460                "NOROUTE" / "HIBERNATING" / "INTERNAL"/ "RESOURCELIMIT" /
1461                "CONNRESET" / "TORPROTOCOL" / "NOTDIRECTORY" / "END" /
1462                "PRIVATE_ADDR"
1463
1464    The "REASON" field is provided only for FAILED, CLOSED, and DETACHED
1465    events, and only if extended events are enabled (see 3.19).  Clients MUST
1466    accept reasons not listed above.  Reasons are as given in tor-spec.txt,
1467    except for:
1468
1469       END          (We received a RELAY_END cell from the other side of this
1470                     stream.)
1471       PRIVATE_ADDR (The client tried to connect to a private address like
1472                     127.0.0.1 or 10.0.0.1 over Tor.)
1473       [XXXX document more. -NM]
1474
1475    The "REMOTE_REASON" field is provided only when we receive a RELAY_END
1476    cell, and only if extended events are enabled.  It contains the actual
1477    reason given by the remote OR for closing the stream. Clients MUST accept
1478    reasons not listed above.  Reasons are as listed in tor-spec.txt.
1479
1480    "REMAP" events include a Source if extended events are enabled:
1481       Source = "CACHE" / "EXIT"
1482    Clients MUST accept sources not listed above.  "CACHE" is given if
1483    the Tor client decided to remap the address because of a cached
1484    answer, and "EXIT" is given if the remote node we queried gave us
1485    the new address as a response.
1486
1487    The "SOURCE_ADDR" field is included with NEW and NEWRESOLVE events if
1488    extended events are enabled.  It indicates the address and port
1489    that requested the connection, and can be (e.g.) used to look up the
1490    requesting program.
1491
1492       Purpose = "DIR_FETCH" / "DIR_UPLOAD" / "DNS_REQUEST" /
1493                 "USER" /  "DIRPORT_TEST"
1494
1495    The "PURPOSE" field is provided only for NEW and NEWRESOLVE events, and
1496    only if extended events are enabled (see 3.19).  Clients MUST accept
1497    purposes not listed above.  The purposes above are defined as:
1498
1499        "DIR_FETCH" -- This stream is generated internally to Tor for
1500          fetching directory information.
1501        "DIR_UPLOAD" -- An internal stream for uploading information to
1502          a directory authority.
1503        "DIRPORT_TEST" -- A stream we're using to test our own directory
1504          port to make sure it's reachable.
1505        "DNS_REQUEST" -- A user-initiated DNS request.
1506        "USER" -- This stream is handling user traffic, OR it's internal
1507          to Tor, but it doesn't match one of the purposes above.
1508
1509 4.1.3. OR Connection status changed
1510
1511   The syntax is:
1512
1513     "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON="
1514              Reason ] [ SP "NCIRCS=" NumCircuits ] [ SP "ID=" ConnID ] CRLF
1515
1516     ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"
1517
1518         ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
1519         ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, OR
1520         ; Connection is as follows:
1521         "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON="
1522                  Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
1523
1524   NEW is for incoming connections, and LAUNCHED is for outgoing
1525   connections. CONNECTED means the TLS handshake has finished (in
1526   either direction). FAILED means a connection is being closed that
1527   hasn't finished its handshake, and CLOSED is for connections that
1528   have handshaked.
1529
1530   A LongName or ServerID is specified unless it's a NEW connection, in
1531   which case we don't know what server it is yet, so we use Address:Port.
1532
1533   If extended events are enabled (see 3.19), optional reason and
1534   circuit counting information is provided for CLOSED and FAILED
1535   events.
1536
1537       Reason = "MISC" / "DONE" / "CONNECTREFUSED" /
1538                "IDENTITY" / "CONNECTRESET" / "TIMEOUT" / "NOROUTE" /
1539                "IOERROR" / "RESOURCELIMIT" / "PT_MISSING"
1540
1541   NumCircuits counts both established and pending circuits.
1542
1543   The ORStatus values are as follows:
1544      NEW -- We have received a new incoming OR connection, and are starting
1545        the server-side handshake.
1546      LAUNCHED -- We have launched a new outgoing OR connection, and are
1547        starting the client-side handshake.
1548      CONNECTED -- The OR connection has been connected and the handshake is
1549        done.
1550      FAILED -- Our attempt to open the OR connection failed.
1551      CLOSED -- The OR connection closed in an unremarkable way.
1552
1553   The Reason values for closed/failed OR connections are:
1554      DONE -- The OR connection has shut down cleanly.
1555      CONNECTREFUSED -- We got an ECONNREFUSED while connecting to the target
1556         OR.
1557      IDENTITY -- We connected to the OR, but found that its identity was
1558         not what we expected.
1559      CONNECTRESET -- We got an ECONNRESET or similar IO error from the
1560         connection with the OR.
1561      TIMEOUT -- We got an ETIMEOUT or similar IO error from the connection
1562         with the OR, or we're closing the connection for being idle for too
1563         long.
1564      NOROUTE -- We got an ENOTCONN, ENETUNREACH, ENETDOWN, EHOSTUNREACH, or
1565         similar error while connecting to the OR.
1566      IOERROR -- We got some other IO error on our connection to the OR.
1567      RESOURCELIMIT -- We don't have enough operating system resources (file
1568         descriptors, buffers, etc) to connect to the OR.
1569      PT_MISSING -- No pluggable transport was available.
1570      MISC -- The OR connection closed for some other reason.
1571
1572   [First added ID parameter in 0.2.5.2-alpha]
1573
1574 4.1.4. Bandwidth used in the last second
1575
1576   The syntax is:
1577      "650" SP "BW" SP BytesRead SP BytesWritten *(SP Type "=" Num) CRLF
1578      BytesRead = 1*DIGIT
1579      BytesWritten = 1*DIGIT
1580      Type = "DIR" / "OR" / "EXIT" / "APP" / ...
1581      Num = 1*DIGIT
1582
1583   BytesRead and BytesWritten are the totals. [In a future Tor version,
1584   we may also include a breakdown of the connection types that used
1585   bandwidth this second (not implemented yet).]
1586
1587 4.1.5. Log messages
1588
1589   The syntax is:
1590      "650" SP Severity SP ReplyText CRLF
1591   or
1592      "650+" Severity CRLF Data 650 SP "OK" CRLF
1593
1594      Severity = "DEBUG" / "INFO" / "NOTICE" / "WARN"/ "ERR"
1595
1596 4.1.6. New descriptors available
1597
1598   Syntax:
1599      "650" SP "NEWDESC" 1*(SP LongName) CRLF
1600         ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
1601         ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, it
1602         ; is as follows:
1603         "650" SP "NEWDESC" 1*(SP ServerID) CRLF
1604
1605 4.1.7. New Address mapping
1606
1607   These events are generated when a new address mapping is entered in
1608   Tor's address map cache, or when the answer for a RESOLVE command is
1609   found.  Entries can be created by a successful or failed DNS lookup,
1610   a successful or failed connection attempt, a RESOLVE command,
1611   a MAPADDRESS command, the AutomapHostsOnResolve feature, or the
1612   TrackHostExits feature.
1613
1614   Syntax:
1615      "650" SP "ADDRMAP" SP Address SP NewAddress SP Expiry
1616        [SP "error=" ErrorCode] [SP "EXPIRES=" UTCExpiry] [SP "CACHED=" Cached]
1617        CRLF
1618
1619      NewAddress = Address / "<error>"
1620      Expiry = DQUOTE ISOTime DQUOTE / "NEVER"
1621
1622      ErrorCode = "yes" / "internal" / "Unable to launch resolve request"
1623      UTCExpiry = DQUOTE IsoTime DQUOTE
1624
1625      Cached = DQUOTE "YES" DQUOTE / DQUOTE "NO" DQUOTE
1626
1627   Error and UTCExpiry are only provided if extended events are enabled.
1628   The values for Error are mostly useless.  Future values will be
1629   chosen to match 1*(ALNUM / "_"); the "Unable to launch resolve request"
1630   value is a bug in Tor before 0.2.4.7-alpha.
1631
1632   Expiry is expressed as the local time (rather than UTC).  This is a bug,
1633   left in for backward compatibility; new code should look at UTCExpiry
1634   instead.  (If Expiry is "NEVER", UTCExpiry is omitted.)
1635
1636   Cached indicates whether the mapping will be stored until it expires, or if
1637   it is just a notification in response to a RESOLVE command.
1638
1639 4.1.8. Descriptors uploaded to us in our role as authoritative dirserver
1640
1641   Tor generates this event when it's an directory authority, and
1642   somebody has just uploaded a router descriptor.
1643
1644   Syntax:
1645      "650" "+" "AUTHDIR_NEWDESCS" CRLF Action CRLF Message CRLF
1646        Descriptor CRLF "." CRLF "650" SP "OK" CRLF
1647      Action = "ACCEPTED" / "DROPPED" / "REJECTED"
1648      Message = Text
1649
1650   The Descriptor field is the text of the router descriptor; the Action
1651   field is "ACCEPTED" if we're accepting the descriptor as the new
1652   best valid descriptor for its router, "REJECTED" if we aren't taking
1653   the descriptor and we're complaining to the uploading relay about
1654   it, and "DROPPED" if we decide to drop the descriptor without
1655   complaining.  The Message field is a human-readable string
1656   explaining why we chose the Action.  (It doesn't contain newlines.)
1657
1658 4.1.9. Our descriptor changed
1659
1660   Syntax:
1661      "650" SP "DESCCHANGED" CRLF
1662
1663   [First added in 0.1.2.2-alpha.]
1664
1665 4.1.10. Status events
1666
1667   Status events (STATUS_GENERAL, STATUS_CLIENT, and STATUS_SERVER) are sent
1668   based on occurrences in the Tor process pertaining to the general state of
1669   the program.  Generally, they correspond to log messages of severity Notice
1670   or higher.  They differ from log messages in that their format is a
1671   specified interface.
1672
1673   Syntax:
1674      "650" SP StatusType SP StatusSeverity SP StatusAction
1675                                          [SP StatusArguments] CRLF
1676
1677      StatusType = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"
1678      StatusSeverity = "NOTICE" / "WARN" / "ERR"
1679      StatusAction = 1*ALPHA
1680      StatusArguments = StatusArgument *(SP StatusArgument)
1681      StatusArgument = StatusKeyword '=' StatusValue
1682      StatusKeyword = 1*(ALNUM / "_")
1683      StatusValue = 1*(ALNUM / '_')  / QuotedString
1684
1685      StatusAction is a string, and StatusArguments is a series of
1686      keyword=value pairs on the same line.  Values may be space-terminated
1687      strings, or quoted strings.
1688
1689      These events are always produced with EXTENDED_EVENTS and
1690      VERBOSE_NAMES; see the explanations in the USEFEATURE section
1691      for details.
1692
1693      Controllers MUST tolerate unrecognized actions, MUST tolerate
1694      unrecognized arguments, MUST tolerate missing arguments, and MUST
1695      tolerate arguments that arrive in any order.
1696
1697      Each event description below is accompanied by a recommendation for
1698      controllers.  These recommendations are suggestions only; no controller
1699      is required to implement them.
1700
1701   Compatibility note: versions of Tor before 0.2.0.22-rc incorrectly
1702   generated "STATUS_SERVER" as "STATUS_SEVER".  To be compatible with those
1703   versions, tools should accept both.
1704
1705   Actions for STATUS_GENERAL events can be as follows:
1706
1707      CLOCK_JUMPED
1708      "TIME=NUM"
1709        Tor spent enough time without CPU cycles that it has closed all
1710        its circuits and will establish them anew. This typically
1711        happens when a laptop goes to sleep and then wakes up again. It
1712        also happens when the system is swapping so heavily that Tor is
1713        starving. The "time" argument specifies the number of seconds Tor
1714        thinks it was unconscious for (or alternatively, the number of
1715        seconds it went back in time).
1716
1717        This status event is sent as NOTICE severity normally, but WARN
1718        severity if Tor is acting as a server currently.
1719
1720        {Recommendation for controller: ignore it, since we don't really
1721        know what the user should do anyway. Hm.}
1722
1723      DANGEROUS_VERSION
1724      "CURRENT=version"
1725      "REASON=NEW/OBSOLETE/UNRECOMMENDED"
1726      "RECOMMENDED=\"version, version, ...\""
1727        Tor has found that directory servers don't recommend its version of
1728        the Tor software.  RECOMMENDED is a comma-and-space-separated string
1729        of Tor versions that are recommended.  REASON is NEW if this version
1730        of Tor is newer than any recommended version, OBSOLETE if
1731        this version of Tor is older than any recommended version, and
1732        UNRECOMMENDED if some recommended versions of Tor are newer and
1733        some are older than this version. (The "OBSOLETE" reason was called
1734        "OLD" from Tor 0.1.2.3-alpha up to and including 0.2.0.12-alpha.)
1735
1736        {Controllers may want to suggest that the user upgrade OLD or
1737        UNRECOMMENDED versions.  NEW versions may be known-insecure, or may
1738        simply be development versions.}
1739
1740      TOO_MANY_CONNECTIONS
1741      "CURRENT=NUM"
1742        Tor has reached its ulimit -n or whatever the native limit is on file
1743        descriptors or sockets.  CURRENT is the number of sockets Tor
1744        currently has open.  The user should really do something about
1745        this. The "current" argument shows the number of connections currently
1746        open.
1747
1748        {Controllers may recommend that the user increase the limit, or
1749        increase it for them.  Recommendations should be phrased in an
1750        OS-appropriate way and automated when possible.}
1751
1752      BUG
1753      "REASON=STRING"
1754        Tor has encountered a situation that its developers never expected,
1755        and the developers would like to learn that it happened. Perhaps
1756        the controller can explain this to the user and encourage her to
1757        file a bug report?
1758
1759        {Controllers should log bugs, but shouldn't annoy the user in case a
1760        bug appears frequently.}
1761
1762      CLOCK_SKEW
1763        SKEW="+" / "-" SECONDS
1764        MIN_SKEW="+" / "-" SECONDS.
1765        SOURCE="DIRSERV:" IP ":" Port /
1766               "NETWORKSTATUS:" IP ":" Port /
1767               "OR:" IP ":" Port /
1768               "CONSENSUS"
1769          If "SKEW" is present, it's an estimate of how far we are from the
1770          time declared in the source.  (In other words, if we're an hour in
1771          the past, the value is -3600.)  "MIN_SKEW" is present, it's a lower
1772          bound.  If the source is a DIRSERV, we got the current time from a
1773          connection to a dirserver.  If the source is a NETWORKSTATUS, we
1774          decided we're skewed because we got a v2 networkstatus from far in
1775          the future.  If the source is OR, the skew comes from a NETINFO
1776          cell from a connection to another relay.  If the source is
1777          CONSENSUS, we decided we're skewed because we got a networkstatus
1778          consensus from the future.
1779
1780          {Tor should send this message to controllers when it thinks the
1781          skew is so high that it will interfere with proper Tor operation.
1782          Controllers shouldn't blindly adjust the clock, since the more
1783          accurate source of skew info (DIRSERV) is currently
1784          unauthenticated.}
1785
1786      BAD_LIBEVENT
1787      "METHOD=" libevent method
1788      "VERSION=" libevent version
1789      "BADNESS=" "BROKEN" / "BUGGY" / "SLOW"
1790      "RECOVERED=" "NO" / "YES"
1791         Tor knows about bugs in using the configured event method in this
1792         version of libevent.  "BROKEN" libevents won't work at all;
1793         "BUGGY" libevents might work okay; "SLOW" libevents will work
1794         fine, but not quickly.  If "RECOVERED" is YES, Tor managed to
1795         switch to a more reliable (but probably slower!) libevent method.
1796
1797         {Controllers may want to warn the user if this event occurs, though
1798         generally it's the fault of whoever built the Tor binary and there's
1799         not much the user can do besides upgrade libevent or upgrade the
1800         binary.}
1801
1802      DIR_ALL_UNREACHABLE
1803        Tor believes that none of the known directory servers are
1804        reachable -- this is most likely because the local network is
1805        down or otherwise not working, and might help to explain for the
1806        user why Tor appears to be broken.
1807
1808        {Controllers may want to warn the user if this event occurs; further
1809        action is generally not possible.}
1810
1811      CONSENSUS_ARRIVED
1812         Tor has received and validated a new consensus networkstatus.
1813         (This event can be delayed a little while after the consensus
1814         is received, if Tor needs to fetch certificates.)
1815
1816   Actions for STATUS_CLIENT events can be as follows:
1817
1818      BOOTSTRAP
1819      "PROGRESS=" num
1820      "TAG=" Keyword
1821      "SUMMARY=" String
1822      ["WARNING=" String
1823       "REASON=" Keyword
1824       "COUNT=" num
1825       "RECOMMENDATION=" Keyword
1826      ]
1827
1828        Tor has made some progress at establishing a connection to the
1829        Tor network, fetching directory information, or making its first
1830        circuit; or it has encountered a problem while bootstrapping. This
1831        status event is especially useful for users with slow connections
1832        or with connectivity problems.
1833
1834        "Progress" gives a number between 0 and 100 for how far through
1835        the bootstrapping process we are. "Summary" is a string that can
1836        be displayed to the user to describe the *next* task that Tor
1837        will tackle, i.e., the task it is working on after sending the
1838        status event. "Tag" is a string that controllers can use to
1839        recognize bootstrap phases, if they want to do something smarter
1840        than just blindly displaying the summary string; see Section 5
1841        for the current tags that Tor issues.
1842
1843        The StatusSeverity describes whether this is a normal bootstrap
1844        phase (severity notice) or an indication of a bootstrapping
1845        problem (severity warn).
1846
1847        For bootstrap problems, we include the same progress, tag, and
1848        summary values as we would for a normal bootstrap event, but we
1849        also include "warning", "reason", "count", and "recommendation"
1850        key/value combos. The "count" number tells how many bootstrap
1851        problems there have been so far at this phase. The "reason"
1852        string lists one of the reasons allowed in the ORCONN event. The
1853        "warning" argument string with any hints Tor has to offer about
1854        why it's having troubles bootstrapping.
1855
1856        The "reason" values are long-term-stable controller-facing tags to
1857        identify particular issues in a bootstrapping step.  The warning
1858        strings, on the other hand, are human-readable. Controllers
1859        SHOULD NOT rely on the format of any warning string. Currently
1860        the possible values for "recommendation" are either "ignore" or
1861        "warn" -- if ignore, the controller can accumulate the string in
1862        a pile of problems to show the user if the user asks; if warn,
1863        the controller should alert the user that Tor is pretty sure
1864        there's a bootstrapping problem.
1865
1866        Currently Tor uses recommendation=ignore for the first
1867        nine bootstrap problem reports for a given phase, and then
1868        uses recommendation=warn for subsequent problems at that
1869        phase. Hopefully this is a good balance between tolerating
1870        occasional errors and reporting serious problems quickly.
1871
1872      ENOUGH_DIR_INFO
1873        Tor now knows enough network-status documents and enough server
1874        descriptors that it's going to start trying to build circuits now.
1875
1876        {Controllers may want to use this event to decide when to indicate
1877        progress to their users, but should not interrupt the user's browsing
1878        to tell them so.}
1879
1880      NOT_ENOUGH_DIR_INFO
1881        We discarded expired statuses and router descriptors to fall
1882        below the desired threshold of directory information. We won't
1883        try to build any circuits until ENOUGH_DIR_INFO occurs again.
1884
1885        {Controllers may want to use this event to decide when to indicate
1886        progress to their users, but should not interrupt the user's browsing
1887        to tell them so.}
1888
1889      CIRCUIT_ESTABLISHED
1890        Tor is able to establish circuits for client use. This event will
1891        only be sent if we just built a circuit that changed our mind --
1892        that is, prior to this event we didn't know whether we could
1893        establish circuits.
1894
1895        {Suggested use: controllers can notify their users that Tor is
1896        ready for use as a client once they see this status event. [Perhaps
1897        controllers should also have a timeout if too much time passes and
1898        this event hasn't arrived, to give tips on how to troubleshoot.
1899        On the other hand, hopefully Tor will send further status events
1900        if it can identify the problem.]}
1901
1902      CIRCUIT_NOT_ESTABLISHED
1903      "REASON=" "EXTERNAL_ADDRESS" / "DIR_ALL_UNREACHABLE" / "CLOCK_JUMPED"
1904        We are no longer confident that we can build circuits. The "reason"
1905        keyword provides an explanation: which other status event type caused
1906        our lack of confidence.
1907
1908        {Controllers may want to use this event to decide when to indicate
1909        progress to their users, but should not interrupt the user's browsing
1910        to do so.}
1911        [Note: only REASON=CLOCK_JUMPED is implemented currently.]
1912
1913      DANGEROUS_PORT
1914      "PORT=" port
1915      "RESULT=" "REJECT" / "WARN"
1916        A stream was initiated to a port that's commonly used for
1917        vulnerable-plaintext protocols. If the Result is "reject", we
1918        refused the connection; whereas if it's "warn", we allowed it.
1919
1920        {Controllers should warn their users when this occurs, unless they
1921        happen to know that the application using Tor is in fact doing so
1922        correctly (e.g., because it is part of a distributed bundle). They
1923        might also want some sort of interface to let the user configure
1924        their RejectPlaintextPorts and WarnPlaintextPorts config options.}
1925
1926      DANGEROUS_SOCKS
1927      "PROTOCOL=" "SOCKS4" / "SOCKS5"
1928      "ADDRESS=" IP:port
1929        A connection was made to Tor's SOCKS port using one of the SOCKS
1930        approaches that doesn't support hostnames -- only raw IP addresses.
1931        If the client application got this address from gethostbyname(),
1932        it may be leaking target addresses via DNS.
1933
1934        {Controllers should warn their users when this occurs, unless they
1935        happen to know that the application using Tor is in fact doing so
1936        correctly (e.g., because it is part of a distributed bundle).}
1937
1938      SOCKS_UNKNOWN_PROTOCOL
1939        "DATA=string"
1940        A connection was made to Tor's SOCKS port that tried to use it
1941        for something other than the SOCKS protocol. Perhaps the user is
1942        using Tor as an HTTP proxy?   The DATA is the first few characters
1943        sent to Tor on the SOCKS port.
1944
1945        {Controllers may want to warn their users when this occurs: it
1946        indicates a misconfigured application.}
1947
1948      SOCKS_BAD_HOSTNAME
1949       "HOSTNAME=QuotedString"
1950        Some application gave us a funny-looking hostname. Perhaps
1951        it is broken? In any case it won't work with Tor and the user
1952        should know.
1953
1954        {Controllers may want to warn their users when this occurs: it
1955        usually indicates a misconfigured application.}
1956
1957   Actions for STATUS_SERVER can be as follows:
1958
1959      EXTERNAL_ADDRESS
1960      "ADDRESS=IP"
1961      "HOSTNAME=NAME"
1962      "METHOD=CONFIGURED/DIRSERV/RESOLVED/INTERFACE/GETHOSTNAME"
1963        Our best idea for our externally visible IP has changed to 'IP'.
1964        If 'HOSTNAME' is present, we got the new IP by resolving 'NAME'.  If the
1965        method is 'CONFIGURED', the IP was given verbatim as a configuration
1966        option.  If the method is 'RESOLVED', we resolved the Address
1967        configuration option to get the IP.  If the method is 'GETHOSTNAME',
1968        we resolved our hostname to get the IP.  If the method is 'INTERFACE',
1969        we got the address of one of our network interfaces to get the IP.  If
1970        the method is 'DIRSERV', a directory server told us a guess for what
1971        our IP might be.
1972
1973        {Controllers may want to record this info and display it to the user.}
1974
1975      CHECKING_REACHABILITY
1976      "ORADDRESS=IP:port"
1977      "DIRADDRESS=IP:port"
1978        We're going to start testing the reachability of our external OR port
1979        or directory port.
1980
1981        {This event could affect the controller's idea of server status, but
1982        the controller should not interrupt the user to tell them so.}
1983
1984      REACHABILITY_SUCCEEDED
1985      "ORADDRESS=IP:port"
1986      "DIRADDRESS=IP:port"
1987        We successfully verified the reachability of our external OR port or
1988        directory port (depending on which of ORADDRESS or DIRADDRESS is
1989        given.)
1990
1991        {This event could affect the controller's idea of server status, but
1992        the controller should not interrupt the user to tell them so.}
1993
1994      GOOD_SERVER_DESCRIPTOR
1995        We successfully uploaded our server descriptor to at least one
1996        of the directory authorities, with no complaints.
1997
1998        {Originally, the goal of this event was to declare "every authority
1999        has accepted the descriptor, so there will be no complaints
2000        about it." But since some authorities might be offline, it's
2001        harder to get certainty than we had thought. As such, this event
2002        is equivalent to ACCEPTED_SERVER_DESCRIPTOR below. Controllers
2003        should just look at ACCEPTED_SERVER_DESCRIPTOR and should ignore
2004        this event for now.}
2005
2006      SERVER_DESCRIPTOR_STATUS
2007      "STATUS=" "LISTED" / "UNLISTED"
2008        We just got a new networkstatus consensus, and whether we're in
2009        it or not in it has changed. Specifically, status is "listed"
2010        if we're listed in it but previous to this point we didn't know
2011        we were listed in a consensus; and status is "unlisted" if we
2012        thought we should have been listed in it (e.g. we were listed in
2013        the last one), but we're not.
2014
2015        {Moving from listed to unlisted is not necessarily cause for
2016        alarm. The relay might have failed a few reachability tests,
2017        or the Internet might have had some routing problems. So this
2018        feature is mainly to let relay operators know when their relay
2019        has successfully been listed in the consensus.}
2020
2021        [Not implemented yet. We should do this in 0.2.2.x. -RD]
2022
2023      NAMESERVER_STATUS
2024      "NS=addr"
2025      "STATUS=" "UP" / "DOWN"
2026      "ERR=" message
2027         One of our nameservers has changed status.
2028
2029         {This event could affect the controller's idea of server status, but
2030         the controller should not interrupt the user to tell them so.}
2031
2032      NAMESERVER_ALL_DOWN
2033         All of our nameservers have gone down.
2034
2035         {This is a problem; if it happens often without the nameservers
2036         coming up again, the user needs to configure more or better
2037         nameservers.}
2038
2039      DNS_HIJACKED
2040         Our DNS provider is providing an address when it should be saying
2041         "NOTFOUND"; Tor will treat the address as a synonym for "NOTFOUND".
2042
2043         {This is an annoyance; controllers may want to tell admins that their
2044         DNS provider is not to be trusted.}
2045
2046      DNS_USELESS
2047         Our DNS provider is giving a hijacked address instead of well-known
2048         websites; Tor will not try to be an exit node.
2049
2050         {Controllers could warn the admin if the relay is running as an
2051         exit node: the admin needs to configure a good DNS server.
2052         Alternatively, this happens a lot in some restrictive environments
2053         (hotels, universities, coffeeshops) when the user hasn't registered.}
2054
2055      BAD_SERVER_DESCRIPTOR
2056      "DIRAUTH=addr:port"
2057      "REASON=string"
2058         A directory authority rejected our descriptor.  Possible reasons
2059         include malformed descriptors, incorrect keys, highly skewed clocks,
2060         and so on.
2061
2062         {Controllers should warn the admin, and try to cope if they can.}
2063
2064      ACCEPTED_SERVER_DESCRIPTOR
2065      "DIRAUTH=addr:port"
2066         A single directory authority accepted our descriptor.
2067         // actually notice
2068
2069        {This event could affect the controller's idea of server status, but
2070        the controller should not interrupt the user to tell them so.}
2071
2072      REACHABILITY_FAILED
2073      "ORADDRESS=IP:port"
2074      "DIRADDRESS=IP:port"
2075        We failed to connect to our external OR port or directory port
2076        successfully.
2077
2078        {This event could affect the controller's idea of server status.  The
2079        controller should warn the admin and suggest reasonable steps to take.}
2080
2081 4.1.11. Our set of guard nodes has changed
2082
2083   Syntax:
2084      "650" SP "GUARD" SP Type SP Name SP Status ... CRLF
2085      Type = "ENTRY"
2086      Name = ServerSpec
2087        (Identifies the guard affected)
2088      Status = "NEW" | "UP" | "DOWN" | "BAD" | "GOOD" | "DROPPED"
2089
2090   The ENTRY type indicates a guard used for connections to the Tor
2091   network.
2092
2093   The Status values are:
2094     "NEW"  -- This node was not previously used as a guard; now we have
2095               picked it as one.
2096     "DROPPED" -- This node is one we previously picked as a guard; we
2097               no longer consider it to be a member of our guard list.
2098     "UP"   -- The guard now seems to be reachable.
2099     "DOWN" -- The guard now seems to be unreachable.
2100     "BAD"  -- Because of flags set in the consensus and/or values in the
2101               configuration, this node is now unusable as a guard.
2102     "GOOD" -- Because of flags set in the consensus and/or values in the
2103               configuration, this node is now usable as a guard.
2104
2105   Controllers must accept unrecognized types and unrecognized statuses.
2106
2107 4.1.12. Network status has changed
2108
2109   Syntax:
2110      "650" "+" "NS" CRLF 1*NetworkStatus "." CRLF "650" SP "OK" CRLF
2111
2112   The event is used whenever our local view of a relay status changes.
2113   This happens when we get a new v3 consensus (in which case the entries
2114   we see are a duplicate of what we see in the NEWCONSENSUS event,
2115   below), but it also happens when we decide to mark a relay as up or
2116   down in our local status, for example based on connection attempts.
2117
2118   [First added in 0.1.2.3-alpha]
2119
2120 4.1.13. Bandwidth used on an application stream
2121
2122   The syntax is:
2123      "650" SP "STREAM_BW" SP StreamID SP BytesWritten SP BytesRead CRLF
2124      BytesWritten = 1*DIGIT
2125      BytesRead = 1*DIGIT
2126
2127   BytesWritten and BytesRead are the number of bytes written and read
2128   by the application since the last STREAM_BW event on this stream.
2129
2130   Note that from Tor's perspective, *reading* a byte on a stream means
2131   that the application *wrote* the byte. That's why the order of "written"
2132   vs "read" is opposite for stream_bw events compared to bw events.
2133
2134   These events are generated about once per second per stream; no events
2135   are generated for streams that have not written or read. These events
2136   apply only to streams entering Tor (such as on a SOCKSPort, TransPort,
2137   or so on). They are not generated for exiting streams.
2138
2139 4.1.14. Per-country client stats
2140
2141   The syntax is:
2142      "650" SP "CLIENTS_SEEN" SP TimeStarted SP CountrySummary SP
2143      IPVersions CRLF
2144
2145   We just generated a new summary of which countries we've seen clients
2146   from recently. The controller could display this for the user, e.g.
2147   in their "relay" configuration window, to give them a sense that they
2148   are actually being useful.
2149
2150   Currently only bridge relays will receive this event, but once we figure
2151   out how to sufficiently aggregate and sanitize the client counts on
2152   main relays, we might start sending these events in other cases too.
2153
2154   TimeStarted is a quoted string indicating when the reported summary
2155   counts from (in UTCS).
2156
2157   The CountrySummary keyword has as its argument a comma-separated,
2158   possibly empty set of "countrycode=count" pairs. For example (without
2159   linebreak),
2160   650-CLIENTS_SEEN TimeStarted="2008-12-25 23:50:43"
2161   CountrySummary=us=16,de=8,uk=8
2162
2163   The IPVersions keyword has as its argument a comma-separated set of
2164   "protocol-family=count" pairs. For example,
2165   IPVersions=v4=16,v6=40
2166
2167 4.1.15. New consensus networkstatus has arrived
2168
2169   The syntax is:
2170      "650" "+" "NEWCONSENSUS" CRLF 1*NetworkStatus "." CRLF "650" SP
2171      "OK" CRLF
2172
2173   A new consensus networkstatus has arrived. We include NS-style lines for
2174   every relay in the consensus. NEWCONSENSUS is a separate event from the
2175   NS event, because the list here represents every usable relay: so any
2176   relay *not* mentioned in this list is implicitly no longer recommended.
2177
2178   [First added in 0.2.1.13-alpha]
2179
2180 4.1.16. New circuit buildtime has been set
2181
2182   The syntax is:
2183      "650" SP "BUILDTIMEOUT_SET" SP Type SP "TOTAL_TIMES=" Total SP
2184         "TIMEOUT_MS=" Timeout SP "XM=" Xm SP "ALPHA=" Alpha SP
2185         "CUTOFF_QUANTILE=" Quantile SP "TIMEOUT_RATE=" TimeoutRate SP
2186         "CLOSE_MS=" CloseTimeout SP "CLOSE_RATE=" CloseRate
2187         CRLF
2188      Type = "COMPUTED" / "RESET" / "SUSPENDED" / "DISCARD" / "RESUME"
2189      Total = Integer count of timeouts stored
2190      Timeout = Integer timeout in milliseconds
2191      Xm = Estimated integer Pareto parameter Xm in milliseconds
2192      Alpha = Estimated floating point Paredo paremter alpha
2193      Quantile = Floating point CDF quantile cutoff point for this timeout
2194      TimeoutRate = Floating point ratio of circuits that timeout
2195      CloseTimeout = How long to keep measurement circs in milliseconds
2196      CloseRate = Floating point ratio of measurement circuits that are closed
2197
2198   A new circuit build timeout time has been set. If Type is "COMPUTED",
2199   Tor has computed the value based on historical data. If Type is "RESET",
2200   initialization or drastic network changes have caused Tor to reset
2201   the timeout back to the default, to relearn again. If Type is
2202   "SUSPENDED", Tor has detected a loss of network connectivity and has
2203   temporarily changed the timeout value to the default until the network
2204   recovers. If type is "DISCARD", Tor has decided to discard timeout
2205   values that likely happened while the network was down. If type is
2206   "RESUME", Tor has decided to resume timeout calculation.
2207
2208   The Total value is the count of circuit build times Tor used in
2209   computing this value. It is capped internally at the maximum number
2210   of build times Tor stores (NCIRCUITS_TO_OBSERVE).
2211
2212   The Timeout itself is provided in milliseconds. Internally, Tor rounds
2213   this value to the nearest second before using it.
2214
2215   [First added in 0.2.2.7-alpha]
2216
2217 4.1.17. Signal received
2218
2219   The syntax is:
2220      "650" SP "SIGNAL" SP Signal CRLF
2221
2222      Signal = "RELOAD" / "DUMP" / "DEBUG" / "NEWNYM" / "CLEARDNSCACHE"
2223
2224   A signal has been received and actions taken by Tor. The meaning of each
2225   signal, and the mapping to Unix signals, is as defined in section 3.7.
2226   Future versions of Tor MAY generate signals other than those listed here;
2227   controllers MUST be able to accept them.
2228
2229   If Tor chose to ignore a signal (such as NEWNYM), this event will not be
2230   sent.  Note that some options (like ReloadTorrcOnSIGHUP) may affect the
2231   semantics of the signals here.
2232
2233   Note that the HALT (SIGTERM) and SHUTDOWN (SIGINT) signals do not currently
2234   generate any event.
2235
2236   [First added in 0.2.3.1-alpha]
2237
2238 4.1.18. Configuration changed
2239
2240   The syntax is:
2241      StartReplyLine *(MidReplyLine) EndReplyLine
2242
2243      StartReplyLine = "650-CONF_CHANGED" CRLF
2244      MidReplyLine = "650-" KEYWORD ["=" VALUE] CRLF
2245      EndReplyLine = "650 OK"
2246
2247   Tor configuration options have changed (such as via a SETCONF or RELOAD
2248   signal). KEYWORD and VALUE specify the configuration option that was changed.
2249   Undefined configuration options contain only the KEYWORD.
2250
2251 4.1.19. Circuit status changed slightly
2252
2253   The syntax is:
2254
2255     "650" SP "CIRC_MINOR" SP CircuitID SP CircEvent [SP Path]
2256           [SP "BUILD_FLAGS=" BuildFlags] [SP "PURPOSE=" Purpose]
2257           [SP "HS_STATE=" HSState] [SP "REND_QUERY=" HSAddress]
2258           [SP "TIME_CREATED=" TimeCreated]
2259           [SP "OLD_PURPOSE=" Purpose [SP "OLD_HS_STATE=" HSState]] CRLF
2260
2261     CircEvent =
2262              "PURPOSE_CHANGED" / ; circuit purpose or HS-related state changed
2263              "CANNIBALIZED"      ; circuit cannibalized
2264
2265   Clients MUST accept circuit events not listed above.
2266
2267   The "OLD_PURPOSE" field is provided for both PURPOSE_CHANGED and
2268   CANNIBALIZED events.  The "OLD_HS_STATE" field is provided whenever
2269   the "OLD_PURPOSE" field is provided and is a hidden-service-related
2270   purpose.
2271
2272   Other fields are as specified in section 4.1.1 above.
2273
2274   [First added in 0.2.3.11-alpha]
2275
2276 4.1.20. Pluggable transport launched
2277
2278   The syntax is:
2279
2280     "650" SP "TRANSPORT_LAUNCHED" SP Type SP Name SP TransportAddress SP Port
2281     Type = "server" | "client"
2282     Name = The name of the pluggable transport
2283     TransportAddress = An IPv4 or IPv6 address on which the pluggable
2284                        transport is listening for connections
2285     Port = The TCP port on which it is listening for connections.
2286
2287     A pluggable transport called 'Name' of type 'Type' was launched
2288     successfully and is now listening for connections on 'Address':'Port'.
2289
2290 4.1.21. Bandwidth used on an OR or DIR or EXIT connection
2291
2292   The syntax is:
2293      "650" SP "CONN_BW" SP "ID=" ConnID SP "TYPE=" ConnType
2294               SP "READ=" BytesRead SP "WRITTEN=" BytesWritten CRLF
2295
2296      ConnType = "OR" /  ; Carrying traffic within the tor network. This can
2297                           either be our own (client) traffic or traffic we're
2298                           relaying within the network.
2299                 "DIR" / ; Fetching tor descriptor data, or transmitting
2300                           descriptors we're mirroring.
2301                 "EXIT"  ; Carrying traffic between the tor network and an
2302                           external destination.
2303
2304      BytesRead = 1*DIGIT
2305      BytesWritten = 1*DIGIT
2306
2307   Controllers MUST tolerate unrecognized connection types.
2308
2309   BytesWritten and BytesRead are the number of bytes written and read
2310   by Tor since the last CONN_BW event on this connection.
2311
2312   These events are generated about once per second per connection; no
2313   events are generated for connections that have not read or written.
2314   These events are only generated if TestingTorNetwork is set.
2315
2316   [First added in 0.2.5.2-alpha]
2317
2318 4.1.22. Bandwidth used by all streams attached to a circuit
2319
2320   The syntax is:
2321      "650" SP "CIRC_BW" SP "ID=" CircuitID SP "READ=" BytesRead SP
2322               "WRITTEN=" BytesWritten CRLF
2323      BytesRead = 1*DIGIT
2324      BytesWritten = 1*DIGIT
2325
2326   BytesRead and BytesWritten are the number of bytes read and written by
2327   all applications with streams attached to this circuit since the last
2328   CIRC_BW event.
2329
2330   These events are generated about once per second per circuit; no events
2331   are generated for circuits that had no attached stream writing or
2332   reading.
2333
2334   [First added in 0.2.5.2-alpha]
2335
2336 4.1.23. Per-circuit cell stats
2337
2338   The syntax is:
2339      "650" SP "CELL_STATS"
2340               [ SP "ID=" CircuitID ]
2341               [ SP "InboundQueue=" QueueID SP "InboundConn=" ConnID ]
2342               [ SP "InboundAdded=" CellsByType ]
2343               [ SP "InboundRemoved=" CellsByType SP
2344                    "InboundTime=" MsecByType ]
2345               [ SP "OutboundQueue=" QueueID SP "OutboundConn=" ConnID ]
2346               [ SP "OutboundAdded=" CellsByType ]
2347               [ SP "OutboundRemoved=" CellsByType SP
2348                    "OutboundTime=" MsecByType ] CRLF
2349      CellsByType, MsecByType = CellType ":" 1*DIGIT
2350                                0*( "," CellType ":" 1*DIGIT )
2351      CellType = 1*( "a" - "z" / "0" - "9" / "_" )
2352
2353   Examples are:
2354      650 CELL_STATS ID=14 OutboundQueue=19403 OutboundConn=15
2355          OutboundAdded=create_fast:1,relay_early:2
2356          OutboundRemoved=create_fast:1,relay_early:2
2357          OutboundTime=create_fast:0,relay_early:0
2358      650 CELL_STATS InboundQueue=19403 InboundConn=32
2359          InboundAdded=relay:1,created_fast:1
2360          InboundRemoved=relay:1,created_fast:1
2361          InboundTime=relay:0,created_fast:0
2362          OutboundQueue=6710 OutboundConn=18
2363          OutboundAdded=create:1,relay_early:1
2364          OutboundRemoved=create:1,relay_early:1
2365          OutboundTime=create:0,relay_early:0
2366
2367   ID is the locally unique circuit identifier that is only included if the
2368   circuit originates at this node.
2369
2370   Inbound and outbound refer to the direction of cell flow through the
2371   circuit which is either to origin (inbound) or from origin (outbound).
2372
2373   InboundQueue and OutboundQueue are identifiers of the inbound and
2374   outbound circuit queues of this circuit.  These identifiers are only
2375   unique per OR connection.  OutboundQueue is chosen by this node and
2376   matches InboundQueue of the next node in the circuit.
2377
2378   InboundConn and OutboundConn are locally unique IDs of inbound and
2379   outbound OR connection.  OutboundConn does not necessarily match
2380   InboundConn of the next node in the circuit.
2381
2382   InboundQueue and InboundConn are not present if the circuit originates
2383   at this node.  OutboundQueue and OutboundConn are not present if the
2384   circuit (currently) ends at this node.
2385
2386   InboundAdded and OutboundAdded are total number of cells by cell type
2387   added to inbound and outbound queues.  Only present if at least one cell
2388   was added to a queue.
2389
2390   InboundRemoved and OutboundRemoved are total number of cells by
2391   cell type processed from inbound and outbound queues.  InboundTime and
2392   OutboundTime are total waiting times in milliseconds of all processed
2393   cells by cell type.  Only present if at least one cell was removed from
2394   a queue.
2395
2396   These events are generated about once per second per circuit; no
2397   events are generated for circuits that have not added or processed any
2398   cell.  These events are only generated if TestingTorNetwork is set.
2399
2400   [First added in 0.2.5.2-alpha]
2401
2402 4.1.24. Token buckets refilled
2403
2404   The syntax is:
2405      "650" SP "TB_EMPTY" SP BucketName [ SP "ID=" ConnID ] SP
2406               "READ=" ReadBucketEmpty SP "WRITTEN=" WriteBucketEmpty SP
2407               "LAST=" LastRefill CRLF
2408
2409      BucketName = "GLOBAL" / "RELAY" / "ORCONN"
2410      ReadBucketEmpty = 1*DIGIT
2411      WriteBucketEmpty = 1*DIGIT
2412      LastRefill = 1*DIGIT
2413
2414   Examples are:
2415      650 TB_EMPTY ORCONN ID=16 READ=0 WRITTEN=0 LAST=100
2416      650 TB_EMPTY GLOBAL READ=93 WRITTEN=93 LAST=100
2417      650 TB_EMPTY RELAY READ=93 WRITTEN=93 LAST=100
2418
2419   This event is generated when refilling a previously empty token
2420   bucket.  BucketNames "GLOBAL" and "RELAY" keywords are used for the
2421   global or relay token buckets, BucketName "ORCONN" is used for the
2422   token buckets of an OR connection.  Controllers MUST tolerate
2423   unrecognized bucket names.
2424
2425   ConnID is only included if the BucketName is "ORCONN".
2426
2427   If both global and relay buckets and/or the buckets of one or more OR
2428   connections run out of tokens at the same time, multiple separate
2429   events are generated.
2430
2431   ReadBucketEmpty (WriteBucketEmpty) is the time in millis that the read
2432   (write) bucket was empty since the last refill.  LastRefill is the
2433   time in millis since the last refill.
2434
2435   If a bucket went negative and if refilling tokens didn't make it go
2436   positive again, there will be multiple consecutive TB_EMPTY events for
2437   each refill interval during which the bucket contained zero tokens or
2438   less.  In such a case, ReadBucketEmpty or WriteBucketEmpty are capped
2439   at LastRefill in order not to report empty times more than once.
2440
2441   These events are only generated if TestingTorNetwork is set.
2442
2443   [First added in 0.2.5.2-alpha]
2444
2445 4.1.25. HiddenService descriptors
2446
2447   The syntax is:
2448
2449     "650" SP "HS_DESC" SP Action SP HSAddress SP AuthType SP HsDir [SP DescriptorID]
2450
2451     Action =  "REQUESTED" / "RECEIVED" / "IGNORE" / "FAILED"
2452     HSAddress = 16*Base32Character
2453     AuthType = "NO_AUTH" / "BASIC_AUTH" / "STEALTH_AUTH" / "UNKNOWN"
2454     HsDir = LongName / Fingerprint
2455     DescriptorID = 32*Base32Character
2456
2457     These events will be triggerred when required HiddenService descriptor is
2458     not found in the cache and a fetch from network is performed.
2459
2460     If we already had the v0 descriptor, the newly fected v2 descriptor will be
2461     ignored and a "HS_DESC" event with "IGNORE" action will be generated.
2462
2463     For HsDir, LongName is always prefered. If HsDir cannot be found in node
2464     list at the time event is sent, Fingerprint will be used instead.
2465
2466
2467 5. Implementation notes
2468
2469 5.1. Authentication
2470
2471   If the control port is open and no authentication operation is enabled, Tor
2472   trusts any local user that connects to the control port.  This is generally
2473   a poor idea.
2474
2475   If the 'CookieAuthentication' option is true, Tor writes a "magic
2476   cookie" file named "control_auth_cookie" into its data directory (or
2477   to another file specified in the 'CookieAuthFile' option).  To
2478   authenticate, the controller must demonstrate that it can read the
2479   contents of the cookie file:
2480
2481   * Current versions of Tor support cookie authentication
2482     using the "COOKIE" authentication method: the controller sends the
2483     contents of the cookie file, encoded in hexadecimal.  This
2484     authentication method exposes the user running a controller to an
2485     unintended information disclosure attack whenever the controller
2486     has greater filesystem read access than the process that it has
2487     connected to.  (Note that a controller may connect to a process
2488     other than Tor.)  It is almost never safe to use, even if the
2489     controller's user has explicitly specified which filename to read
2490     an authentication cookie from.  For this reason, the COOKIE
2491     authentication method has been deprecated and will be removed from
2492     Tor before some future version of Tor.
2493
2494   * 0.2.2.x versions of Tor starting with 0.2.2.36, and all versions of
2495     Tor after 0.2.3.12-alpha, support cookie authentication using the
2496     "SAFECOOKIE" authentication method, which discloses much less
2497     information about the contents of the cookie file.
2498
2499   If the 'HashedControlPassword' option is set, it must contain the salted
2500   hash of a secret password.  The salted hash is computed according to the
2501   S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier.
2502   This is then encoded in hexadecimal, prefixed by the indicator sequence
2503   "16:".  Thus, for example, the password 'foo' could encode to:
2504      16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2
2505         ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2506            salt                       hashed value
2507                        indicator
2508   You can generate the salt of a password by calling
2509            'tor --hash-password <password>'
2510   or by using the example code in the Python and Java controller libraries.
2511   To authenticate under this scheme, the controller sends Tor the original
2512   secret that was used to generate the password, either as a quoted string
2513   or encoded in hexadecimal.
2514
2515 5.2. Don't let the buffer get too big.
2516
2517   If you ask for lots of events, and 16MB of them queue up on the buffer,
2518   the Tor process will close the socket.
2519
2520 5.3. Backward compatibility with v0 control protocol.
2521
2522   The 'version 0' control protocol was replaced in Tor 0.1.1.x. Support
2523   was removed in Tor 0.2.0.x. Every non-obsolete version of Tor now
2524   supports the version 1 control protocol.
2525
2526   For backward compatibility with the "version 0" control protocol,
2527   Tor used to check whether the third octet of the first command is zero.
2528   (If it was, Tor assumed that version 0 is in use.)
2529
2530   This compatibility was removed in Tor 0.1.2.16 and 0.2.0.4-alpha.
2531
2532 5.4. Tor config options for use by controllers
2533
2534   Tor provides a few special configuration options for use by controllers.
2535   These options can be set and examined by the SETCONF and GETCONF commands,
2536   but are not saved to disk by SAVECONF.
2537
2538   Generally, these options make Tor unusable by disabling a portion of Tor's
2539   normal operations.  Unless a controller provides replacement functionality
2540   to fill this gap, Tor will not correctly handle user requests.
2541
2542   __AllDirActionsPrivate
2543
2544     If true, Tor will try to launch all directory operations through
2545     anonymous connections.  (Ordinarily, Tor only tries to anonymize
2546     requests related to hidden services.)  This option will slow down
2547     directory access, and may stop Tor from working entirely if it does not
2548     yet have enough directory information to build circuits.
2549
2550     (Boolean. Default: "0".)
2551
2552   __DisablePredictedCircuits
2553
2554     If true, Tor will not launch preemptive "general-purpose" circuits for
2555     streams to attach to.  (It will still launch circuits for testing and
2556     for hidden services.)
2557
2558     (Boolean. Default: "0".)
2559
2560   __LeaveStreamsUnattached
2561
2562     If true, Tor will not automatically attach new streams to circuits;
2563     instead, the controller must attach them with ATTACHSTREAM.  If the
2564     controller does not attach the streams, their data will never be routed.
2565
2566     (Boolean. Default: "0".)
2567
2568   __HashedControlSessionPassword
2569
2570     As HashedControlPassword, but is not saved to the torrc file by
2571     SAVECONF.  Added in Tor 0.2.0.20-rc.
2572
2573   __ReloadTorrcOnSIGHUP
2574
2575     If this option is true (the default), we reload the torrc from disk
2576     every time we get a SIGHUP (from the controller or via a signal).
2577     Otherwise, we don't.  This option exists so that controllers can keep
2578     their options from getting overwritten when a user sends Tor a HUP for
2579     some other reason (for example, to rotate the logs).
2580
2581     (Boolean.  Default: "1")
2582
2583   __OwningControllerProcess
2584
2585     If this option is set to a process ID, Tor will periodically check
2586     whether a process with the specified PID exists, and exit if one
2587     does not.  Added in Tor 0.2.2.28-beta.  This option's intended use
2588     is documented in section 3.23 with the related TAKEOWNERSHIP
2589     command.
2590
2591     Note that this option can only specify a single process ID, unlike
2592     the TAKEOWNERSHIP command which can be sent along multiple control
2593     connections.
2594
2595     (String.  Default: unset.)
2596
2597 5.5. Phases from the Bootstrap status event.
2598
2599   This section describes the various bootstrap phases currently reported
2600   by Tor. Controllers should not assume that the percentages and tags
2601   listed here will continue to match up, or even that the tags will stay
2602   in the same order. Some phases might also be skipped (not reported)
2603   if the associated bootstrap step is already complete, or if the phase
2604   no longer is necessary. Only "starting" and "done" are guaranteed to
2605   exist in all future versions.
2606
2607   Current Tor versions enter these phases in order, monotonically.
2608   Future Tors MAY revisit earlier stages.
2609
2610   Phase 0:
2611   tag=starting summary="Starting"
2612
2613   Tor starts out in this phase.
2614
2615   Phase 5:
2616   tag=conn_dir summary="Connecting to directory mirror"
2617
2618   Tor sends this event as soon as Tor has chosen a directory mirror --
2619   e.g. one of the authorities if bootstrapping for the first time or
2620   after a long downtime, or one of the relays listed in its cached
2621   directory information otherwise.
2622
2623   Tor will stay at this phase until it has successfully established
2624   a TCP connection with some directory mirror. Problems in this phase
2625   generally happen because Tor doesn't have a network connection, or
2626   because the local firewall is dropping SYN packets.
2627
2628   Phase 10:
2629   tag=handshake_dir summary="Finishing handshake with directory mirror"
2630
2631   This event occurs when Tor establishes a TCP connection with a relay used
2632   as a directory mirror (or its https proxy if it's using one). Tor remains
2633   in this phase until the TLS handshake with the relay is finished.
2634
2635   Problems in this phase generally happen because Tor's firewall is
2636   doing more sophisticated MITM attacks on it, or doing packet-level
2637   keyword recognition of Tor's handshake.
2638
2639   Phase 15:
2640   tag=onehop_create summary="Establishing one-hop circuit for dir info"
2641
2642   Once TLS is finished with a relay, Tor will send a CREATE_FAST cell
2643   to establish a one-hop circuit for retrieving directory information.
2644   It will remain in this phase until it receives the CREATED_FAST cell
2645   back, indicating that the circuit is ready.
2646
2647   Phase 20:
2648   tag=requesting_status summary="Asking for networkstatus consensus"
2649
2650   Once we've finished our one-hop circuit, we will start a new stream
2651   for fetching the networkstatus consensus. We'll stay in this phase
2652   until we get the 'connected' relay cell back, indicating that we've
2653   established a directory connection.
2654
2655   Phase 25:
2656   tag=loading_status summary="Loading networkstatus consensus"
2657
2658   Once we've established a directory connection, we will start fetching
2659   the networkstatus consensus document. This could take a while; this
2660   phase is a good opportunity for using the "progress" keyword to indicate
2661   partial progress.
2662
2663   This phase could stall if the directory mirror we picked doesn't
2664   have a copy of the networkstatus consensus so we have to ask another,
2665   or it does give us a copy but we don't find it valid.
2666
2667   Phase 40:
2668   tag=loading_keys summary="Loading authority key certs"
2669
2670   Sometimes when we've finished loading the networkstatus consensus,
2671   we find that we don't have all the authority key certificates for the
2672   keys that signed the consensus. At that point we put the consensus we
2673   fetched on hold and fetch the keys so we can verify the signatures.
2674
2675   Phase 45
2676   tag=requesting_descriptors summary="Asking for relay descriptors"
2677
2678   Once we have a valid networkstatus consensus and we've checked all
2679   its signatures, we start asking for relay descriptors. We stay in this
2680   phase until we have received a 'connected' relay cell in response to
2681   a request for descriptors.
2682
2683   Phase 50:
2684   tag=loading_descriptors summary="Loading relay descriptors"
2685
2686   We will ask for relay descriptors from several different locations,
2687   so this step will probably make up the bulk of the bootstrapping,
2688   especially for users with slow connections. We stay in this phase until
2689   we have descriptors for at least 1/4 of the usable relays listed in
2690   the networkstatus consensus. This phase is also a good opportunity to
2691   use the "progress" keyword to indicate partial steps.
2692
2693   Phase 80:
2694   tag=conn_or summary="Connecting to entry guard"
2695
2696   Once we have a valid consensus and enough relay descriptors, we choose
2697   some entry guards and start trying to build some circuits. This step
2698   is similar to the "conn_dir" phase above; the only difference is
2699   the context.
2700
2701   If a Tor starts with enough recent cached directory information,
2702   its first bootstrap status event will be for the conn_or phase.
2703
2704   Phase 85:
2705   tag=handshake_or summary="Finishing handshake with entry guard"
2706
2707   This phase is similar to the "handshake_dir" phase, but it gets reached
2708   if we finish a TCP connection to a Tor relay and we have already reached
2709   the "conn_or" phase. We'll stay in this phase until we complete a TLS
2710   handshake with a Tor relay.
2711
2712   Phase 90:
2713   tag=circuit_create summary="Establishing circuits"
2714
2715   Once we've finished our TLS handshake with an entry guard, we will
2716   set about trying to make some 3-hop circuits in case we need them soon.
2717
2718   Phase 100:
2719   tag=done summary="Done"
2720
2721   A full 3-hop exit circuit has been established. Tor is ready to handle
2722   application connections now.
2723