2 TC: A Tor control protocol (Version 1)
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
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.)
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
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.
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
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.
41 Servers respond to messages in the order messages are received.
43 1.1. Forward-compatibility
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:
54 * Adding a new field to a message:
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.
66 * Adding a new possible value to a list of alternatives:
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.
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.
86 2.1. Description format
88 The message formats listed below use ABNF as described in RFC 2234.
89 The protocol itself is loosely based on SMTP (see RFC 2821).
91 We use the following nonterminals from RFC 2822: atom, qcontent
93 We define the following general-use nonterminals:
95 String = DQUOTE *qcontent DQUOTE
97 There are explicitly no limits on line length. All 8-bit characters are
98 permitted unless explicitly disallowed.
100 Wherever CRLF is specified to be accepted from the controller, Tor MAY also
101 accept LF. Tor, however, MUST NOT generate LF instead of CRLF.
102 Controllers SHOULD always send CRLF.
104 2.2. Commands from controller to Tor
106 Command = Keyword OptArguments CRLF / "+" Keyword OptArguments CRLF CmdData
108 OptArguments = [ SP *(SP / VCHAR) ]
110 A command is either a single line containing a Keyword and arguments, or a
111 multiline command whose initial keyword begins with +, and whose data
112 section ends with a single "." on a line of its own. (We use a special
113 character to distinguish multiline commands so that Tor can correctly parse
114 multi-line commands that it does not recognize.) Specific commands and
115 their arguments are described below in section 3.
117 2.3. Replies from Tor to the controller
119 Reply = SyncReply / AsyncReply
120 SyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
121 AsyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
123 MidReplyLine = StatusCode "-" ReplyLine
124 DataReplyLine = StatusCode "+" ReplyLine Data
125 EndReplyLine = StatusCode SP ReplyLine
126 ReplyLine = [ReplyText] CRLF
130 Specific replies are mentioned below in section 3, and described more fully
133 [Compatibility note: versions of Tor before 0.2.0.3-alpha sometimes
134 generate AsyncReplies of the form "*(MidReplyLine / DataReplyLine)".
135 This is incorrect, but controllers that need to work with these
136 versions of Tor should be prepared to get multi-line AsyncReplies with
137 the final line (usually "650 OK") omitted.]
139 2.4. General-use tokens
141 ; CRLF means, "the ASCII Carriage Return character (decimal value 13)
142 ; followed by the ASCII Linefeed character (decimal value 10)."
145 ; How a controller tells Tor about a particular OR. There are four
147 ; $Fingerprint -- The router whose identity key hashes to the fingerprint.
148 ; This is the preferred way to refer to an OR.
149 ; $Fingerprint~Nickname -- The router whose identity key hashes to the
150 ; given fingerprint, but only if the router has the given nickname.
151 ; $Fingerprint=Nickname -- The router whose identity key hashes to the
152 ; given fingerprint, but only if the router is Named and has the given
154 ; Nickname -- The Named router with the given nickname, or, if no such
155 ; router exists, any router whose nickname matches the one given.
156 ; This is not a safe way to refer to routers, since Named status
157 ; could under some circumstances change over time.
159 ; The tokens that implement the above follow:
161 ServerSpec = LongName / Nickname
162 LongName = Fingerprint [ ( "=" / "~" ) Nickname ]
164 Fingerprint = "$" 40*HEXDIG
165 NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
166 Nickname = 1*19 NicknameChar
168 ; What follows is an outdated way to refer to ORs.
169 ; Feature VERBOSE_NAMES replaces ServerID with LongName in events and
170 ; GETINFO results. VERBOSE_NAMES can be enabled starting in Tor version
171 ; 0.1.2.2-alpha and it is always-on in 0.2.2.1-alpha and later.
172 ServerID = Nickname / Fingerprint
175 ; Unique identifiers for streams or circuits. Currently, Tor only
176 ; uses digits, but this may change
177 StreamID = 1*16 IDChar
178 CircuitID = 1*16 IDChar
179 IDChar = ALPHA / DIGIT
181 Address = ip4-address / ip6-address / hostname (XXXX Define these)
183 ; A "CmdData" section is a sequence of octets concluded by the terminating
184 ; sequence CRLF "." CRLF. The terminating sequence may not appear in the
185 ; body of the data. Leading periods on lines in the data are escaped with
186 ; an additional leading period as in RFC 2821 section 4.5.2.
187 CmdData = *DataLine "." CRLF
188 DataLine = CRLF / "." 1*LineItem CRLF / NonDotItem *LineItem CRLF
189 LineItem = NonCR / 1*CR NonCRLF
190 NonDotItem = NonDotCR / 1*CR NonCRLF
194 All commands are case-insensitive, but most keywords are case-sensitive.
198 Change the value of one or more configuration variables. The syntax is:
200 "SETCONF" 1*(SP keyword ["=" value]) CRLF
201 value = String / QuotedString
203 Tor behaves as though it had just read each of the key-value pairs
204 from its configuration file. Keywords with no corresponding values have
205 their configuration values reset to 0 or NULL (use RESETCONF if you want
206 to set it back to its default). SETCONF is all-or-nothing: if there
207 is an error in any of the configuration settings, Tor sets none of them.
209 Tor responds with a "250 configuration values set" reply on success.
210 If some of the listed keywords can't be found, Tor replies with a
211 "552 Unrecognized option" message. Otherwise, Tor responds with a
212 "513 syntax error in configuration values" reply on syntax error, or a
213 "553 impossible configuration setting" reply on a semantic error.
215 When a configuration option takes multiple values, or when multiple
216 configuration keys form a context-sensitive group (see GETCONF below), then
217 setting _any_ of the options in a SETCONF command is taken to reset all of
218 the others. For example, if two ORBindAddress values are configured, and a
219 SETCONF command arrives containing a single ORBindAddress value, the new
220 command's value replaces the two old values.
222 Sometimes it is not possible to change configuration options solely by
223 issuing a series of SETCONF commands, because the value of one of the
224 configuration options depends on the value of another which has not yet
225 been set. Such situations can be overcome by setting multiple configuration
226 options with a single SETCONF command (e.g. SETCONF ORPort=443
227 ORListenAddress=9001).
231 Remove all settings for a given configuration option entirely, assign
232 its default value (if any), and then assign the String provided.
233 Typically the String is left empty, to simply set an option back to
234 its default. The syntax is:
236 "RESETCONF" 1*(SP keyword ["=" String]) CRLF
238 Otherwise it behaves like SETCONF above.
242 Request the value of a configuration variable. The syntax is:
244 "GETCONF" 1*(SP keyword) CRLF
246 If all of the listed keywords exist in the Tor configuration, Tor replies
247 with a series of reply lines of the form:
249 If any option is set to a 'default' value semantically different from an
250 empty string, Tor may reply with a reply line of the form:
253 Value may be a raw value or a quoted string. Tor will try to use
254 unquoted values except when the value could be misinterpreted through
257 If some of the listed keywords can't be found, Tor replies with a
258 "552 unknown configuration keyword" message.
260 If an option appears multiple times in the configuration, all of its
261 key-value pairs are returned in order.
263 Some options are context-sensitive, and depend on other options with
264 different keywords. These cannot be fetched directly. Currently there
265 is only one such option: clients should use the "HiddenServiceOptions"
266 virtual keyword to get all HiddenServiceDir, HiddenServicePort,
267 HiddenServiceVersion, and HiddenserviceAuthorizeClient option settings.
271 Request the server to inform the client about interesting events. The
274 "SETEVENTS" [SP "EXTENDED"] *(SP EventCode) CRLF
276 EventCode = "CIRC" / "STREAM" / "ORCONN" / "BW" / "DEBUG" /
277 "INFO" / "NOTICE" / "WARN" / "ERR" / "NEWDESC" / "ADDRMAP" /
278 "AUTHDIR_NEWDESCS" / "DESCCHANGED" / "STATUS_GENERAL" /
279 "STATUS_CLIENT" / "STATUS_SERVER" / "GUARD" / "NS" / "STREAM_BW" /
280 "CLIENTS_SEEN" / "NEWCONSENSUS" / "BUILDTIMEOUT_SET" / "SIGNAL"
282 Any events *not* listed in the SETEVENTS line are turned off; thus, sending
283 SETEVENTS with an empty body turns off all event reporting.
285 The server responds with a "250 OK" reply on success, and a "552
286 Unrecognized event" reply if one of the event codes isn't recognized. (On
287 error, the list of active event codes isn't changed.)
289 If the flag string "EXTENDED" is provided, Tor may provide extra
290 information with events for this connection; see 4.1 for more information.
291 NOTE: All events on a given connection will be provided in extended format,
293 NOTE: "EXTENDED" was first supported in Tor 0.1.1.9-alpha; it is
294 always-on in Tor 0.2.2.1-alpha and later.
296 Each event is described in more detail in Section 4.1.
300 Sent from the client to the server. The syntax is:
301 "AUTHENTICATE" [ SP 1*HEXDIG / QuotedString ] CRLF
303 The server responds with "250 OK" on success or "515 Bad authentication" if
304 the authentication cookie is incorrect. Tor closes the connection on an
305 authentication failure.
307 The authentication token can be specified as either a quoted ASCII string,
308 or as an unquoted hexadecimal encoding of that same string (to avoid escaping
311 For information on how the implementation securely stores authentication
312 information on disk, see section 5.1.
314 Before the client has authenticated, no command other than PROTOCOLINFO,
315 AUTHENTICATE, or QUIT is valid. If the controller sends any other command,
316 or sends a malformed command, or sends an unsuccessful AUTHENTICATE
317 command, or sends PROTOCOLINFO more than once, Tor sends an error reply and
318 closes the connection.
320 To prevent some cross-protocol attacks, the AUTHENTICATE command is still
321 required even if all authentication methods in Tor are disabled. In this
322 case, the controller should just send "AUTHENTICATE" CRLF.
324 (Versions of Tor before 0.1.2.16 and 0.2.0.4-alpha did not close the
325 connection after an authentication failure.)
329 Sent from the client to the server. The syntax is:
332 Instructs the server to write out its config options into its torrc. Server
333 returns "250 OK" if successful, or "551 Unable to write configuration
334 to disk" if it can't write the file or some other error occurs.
336 See also the "getinfo config-text" command, if the controller wants
337 to write the torrc file itself.
341 Sent from the client to the server. The syntax is:
343 "SIGNAL" SP Signal CRLF
345 Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" /
346 "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" /
349 The meaning of the signals are:
351 RELOAD -- Reload: reload config items. (like HUP)
352 SHUTDOWN -- Controlled shutdown: if server is an OP, exit immediately.
353 If it's an OR, close listeners and exit after
354 ShutdownWaitLength seconds. (like INT)
355 DUMP -- Dump stats: log information about open connections and
356 circuits. (like USR1)
357 DEBUG -- Debug: switch all open logs to loglevel debug. (like USR2)
358 HALT -- Immediate shutdown: clean up and exit now. (like TERM)
359 CLEARDNSCACHE -- Forget the client-side cached IPs for all hostnames.
360 NEWNYM -- Switch to clean circuits, so new application requests
361 don't share any circuits with old ones. Also clears
362 the client-side DNS cache. (Tor MAY rate-limit its
363 response to this signal.)
365 The server responds with "250 OK" if the signal is recognized (or simply
366 closes the socket if it was asked to close immediately), or "552
367 Unrecognized signal" if the signal is unrecognized.
371 Sent from the client to the server. The syntax is:
373 "MAPADDRESS" 1*(Address "=" Address SP) CRLF
375 The first address in each pair is an "original" address; the second is a
376 "replacement" address. The client sends this message to the server in
377 order to tell it that future SOCKS requests for connections to the original
378 address should be replaced with connections to the specified replacement
379 address. If the addresses are well-formed, and the server is able to
380 fulfill the request, the server replies with a 250 message:
381 250-OldAddress1=NewAddress1
382 250 OldAddress2=NewAddress2
384 containing the source and destination addresses. If request is
385 malformed, the server replies with "512 syntax error in command
386 argument". If the server can't fulfill the request, it replies with
387 "451 resource exhausted".
389 The client may decline to provide a body for the original address, and
390 instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
391 "." for hostname), signifying that the server should choose the original
392 address itself, and return that address in the reply. The server
393 should ensure that it returns an element of address space that is unlikely
394 to be in actual use. If there is already an address mapped to the
395 destination address, the server may reuse that mapping.
397 If the original address is already mapped to a different address, the old
398 mapping is removed. If the original address and the destination address
399 are the same, the server removes any mapping in place for the original
403 C: MAPADDRESS 0.0.0.0=torproject.org 1.2.3.4=tor.freehaven.net
404 S: 250-127.192.10.10=torproject.org
405 S: 250 1.2.3.4=tor.freehaven.net
407 {Note: This feature is designed to be used to help Tor-ify applications
408 that need to use SOCKS4 or hostname-less SOCKS5. There are three
409 approaches to doing this:
410 1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
411 2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
412 feature) to resolve the hostname remotely. This doesn't work
413 with special addresses like x.onion or x.y.exit.
414 3. Use MAPADDRESS to map an IP address to the desired hostname, and then
415 arrange to fool the application into thinking that the hostname
416 has resolved to that IP.
417 This functionality is designed to help implement the 3rd approach.}
419 Mappings set by the controller last until the Tor process exits:
420 they never expire. If the controller wants the mapping to last only
421 a certain time, then it must explicitly un-map the address when that
426 Sent from the client to the server. The syntax is as for GETCONF:
427 "GETINFO" 1*(SP keyword) CRLF
428 one or more NL-terminated strings. The server replies with an INFOVALUE
429 message, or a 551 or 552 error.
431 Unlike GETCONF, this message is used for data that are not stored in the Tor
432 configuration file, and that may be longer than a single line. On success,
433 one ReplyLine is sent for each requested value, followed by a final 250 OK
434 ReplyLine. If a value fits on a single line, the format is:
436 If a value must be split over multiple lines, the format is:
440 Recognized keys and their values include:
442 "version" -- The version of the server's software, including the name
443 of the software. (example: "Tor 0.0.9.4")
445 "config-file" -- The location of Tor's configuration file ("torrc").
447 "config-text" -- The contents that Tor would write if you send it
448 a SAVECONF command, so the controller can write the file to
449 disk itself. [First implemented in 0.2.2.7-alpha.]
451 ["exit-policy/prepend" -- The default exit policy lines that Tor will
452 *prepend* to the ExitPolicy config option.
453 -- Never implemented. Useful?]
455 "exit-policy/default" -- The default exit policy lines that Tor will
456 *append* to the ExitPolicy config option.
458 "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest
459 server descriptor for a given OR, NUL-terminated.
461 "desc-annotations/id/<OR identity>" -- outputs the annotations string
462 (source, timestamp of arrival, purpose, etc) for the corresponding
463 descriptor. [First implemented in 0.2.0.13-alpha.]
465 "extra-info/digest/<digest>" -- the extrainfo document whose digest (in
466 hex) is <digest>. Only available if we're downloading extra-info
469 "ns/id/<OR identity>" or "ns/name/<OR nickname>" -- the latest router
470 status info (v2 directory style) for a given OR. Router status
472 dir-spec.txt, and reflects the current beliefs of this Tor about the
473 router in question. Like directory clients, controllers MUST
474 tolerate unrecognized flags and lines. The published date and
475 descriptor digest are those believed to be best by this Tor,
476 not necessarily those for a descriptor that Tor currently has.
477 [First implemented in 0.1.2.3-alpha.]
479 "ns/all" -- Router status info (v2 directory style) for all ORs we
480 have an opinion about, joined by newlines. [First implemented
483 "ns/purpose/<purpose>" -- Router status info (v2 directory style)
484 for all ORs of this purpose. Mostly designed for /ns/purpose/bridge
485 queries. [First implemented in 0.2.0.13-alpha.]
487 "desc/all-recent" -- the latest server descriptor for every router that
490 "network-status" -- a space-separated list (v1 directory style)
491 of all known OR identities. This is in the same format as the
492 router-status line in v1 directories; see dir-spec-v1.txt section
493 3 for details. (If VERBOSE_NAMES is enabled, the output will
494 not conform to dir-spec-v1.txt; instead, the result will be a
495 space-separated list of LongName, each preceded by a "!" if it is
496 believed to be not running.) This option is deprecated; use
499 "address-mappings/all"
500 "address-mappings/config"
501 "address-mappings/cache"
502 "address-mappings/control" -- a \r\n-separated list of address
503 mappings, each in the form of "from-address to-address expiry".
504 The 'config' key returns those address mappings set in the
505 configuration; the 'cache' key returns the mappings in the
506 client-side DNS cache; the 'control' key returns the mappings set
507 via the control interface; the 'all' target returns the mappings
508 set through any mechanism.
509 Expiry is formatted as with ADDRMAP events, except that "expiry" is
510 always a time in GMT or the string "NEVER"; see section 4.1.7.
511 First introduced in 0.2.0.3-alpha.
513 "addr-mappings/*" -- as for address-mappings/*, but without the
514 expiry portion of the value. Use of this value is deprecated
515 since 0.2.0.3-alpha; use address-mappings instead.
517 "address" -- the best guess at our external IP address. If we
518 have no guess, return a 551 error. (Added in 0.1.2.2-alpha)
520 "fingerprint" -- the contents of the fingerprint file that Tor
521 writes as a relay, or a 551 if we're not a relay currently.
522 (Added in 0.1.2.3-alpha)
525 A series of lines as for a circuit status event. Each line is of
526 the form described in section 4.1.1, omitting the initial
527 "650 CIRC ". Note that clients must be ready to accept additional
528 arguments as described in section 4.1.
531 A series of lines as for a stream status event. Each is of the form:
532 StreamID SP StreamStatus SP CircID SP Target CRLF
535 A series of lines as for an OR connection status event. In Tor
536 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
537 0.2.2.1-alpha and later by default, each line is of the form:
538 LongName SP ORStatus CRLF
540 In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
541 VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line
543 ServerID SP ORStatus CRLF
546 A series of lines listing the currently chosen entry guards, if any.
547 In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
548 0.2.2.1-alpha and later by default, each line is of the form:
549 LongName SP Status [SP ISOTime] CRLF
551 In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
552 VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line
554 ServerID2 SP Status [SP ISOTime] CRLF
555 ServerID2 = Nickname / 40*HEXDIG
557 The definition of Status is the same for both:
558 Status = "up" / "never-connected" / "down" /
559 "unusable" / "unlisted"
561 [From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called
562 "helper-nodes". Tor still supports calling "helper-nodes", but it
563 is deprecated and should not be used.]
565 [Older versions of Tor (before 0.1.2.x-final) generated 'down' instead
566 of unlisted/unusable. Current Tors never generate 'down'.]
568 [XXXX ServerID2 differs from ServerID in not prefixing fingerprints
569 with a $. This is an implementation error. It would be nice to add
570 the $ back in if we can do so without breaking compatibility.]
572 "traffic/read" -- Total bytes read (downloaded).
574 "traffic/written" -- Total bytes written (uploaded).
577 "accounting/hibernating"
579 "accounting/bytes-left"
580 "accounting/interval-start"
581 "accounting/interval-wake"
582 "accounting/interval-end"
583 Information about accounting status. If accounting is enabled,
584 "enabled" is 1; otherwise it is 0. The "hibernating" field is "hard"
585 if we are accepting no data; "soft" if we're accepting no new
586 connections, and "awake" if we're not hibernating at all. The "bytes"
587 and "bytes-left" fields contain (read-bytes SP write-bytes), for the
588 start and the rest of the interval respectively. The 'interval-start'
589 and 'interval-end' fields are the borders of the current interval; the
590 'interval-wake' field is the time within the current interval (if any)
591 where we plan[ned] to start being active. The times are GMT.
594 A series of lines listing the available configuration options. Each is
596 OptionName SP OptionType [ SP Documentation ] CRLF
598 OptionType = "Integer" / "TimeInterval" / "TimeMsecInterval" /
599 "DataSize" / "Float" / "Boolean" / "Time" / "CommaList" /
600 "Dependant" / "Virtual" / "String" / "LineList"
604 A series of lines listing the available GETINFO options. Each is of
606 OptionName SP Documentation CRLF
607 OptionPrefix SP Documentation CRLF
608 OptionPrefix = OptionName "/*"
611 A space-separated list of all the events supported by this version of
615 A space-separated list of all the events supported by this version of
619 Maps IP addresses to 2-letter country codes. For example,
620 "GETINFO ip-to-country/18.0.0.1" should give "US".
622 "next-circuit/IP:port"
625 "process/pid" -- Process id belonging to the main tor process.
626 "process/uid" -- User id running the tor process, -1 if unknown (this is
627 unimplemented on Windows, returning -1).
628 "process/user" -- Username under which the tor process is running,
629 providing an empty string if none exists (this is unimplemented on
630 Windows, returning an empty string).
631 "process/descriptor-limit" -- Upper bound on the file descriptor limit, -1
634 "dir/status-vote/current/consensus" [added in Tor 0.2.1.6-alpha]
635 "dir/status/authority"
637 "dir/status/fp/<F1>+<F2>+<F3>"
640 "dir/server/fp/<F1>+<F2>+<F3>"
642 "dir/server/d/<D1>+<D2>+<D3>"
643 "dir/server/authority"
645 A series of lines listing directory contents, provided according to the
646 specification for the URLs listed in Section 4.4 of dir-spec.txt. Note
647 that Tor MUST NOT provide private information, such as descriptors for
648 routers not marked as general-purpose. When asked for 'authority'
649 information for which this Tor is not authoritative, Tor replies with
652 "status/circuit-established"
653 "status/enough-dir-info"
654 "status/good-server-descriptor"
655 "status/accepted-server-descriptor"
657 These provide the current internal Tor values for various Tor
658 states. See Section 4.1.10 for explanations. (Only a few of the
659 status events are available as getinfo's currently. Let us know if
660 you want more exposed.)
661 "status/reachability-succeeded/or"
662 0 or 1, depending on whether we've found our ORPort reachable.
663 "status/reachability-succeeded/dir"
664 0 or 1, depending on whether we've found our DirPort reachable.
665 "status/reachability-succeeded"
666 "OR=" ("0"/"1") SP "DIR=" ("0"/"1")
667 Combines status/reachability-succeeded/*; controllers MUST ignore
668 unrecognized elements in this entry.
669 "status/bootstrap-phase"
670 Returns the most recent bootstrap phase status event
671 sent. Specifically, it returns a string starting with either
672 "NOTICE BOOTSTRAP ..." or "WARN BOOTSTRAP ...". Controllers should
673 use this getinfo when they connect or attach to Tor to learn its
674 current bootstrap state.
675 "status/version/recommended"
676 List of currently recommended versions.
677 "status/version/current"
678 Status of the current version. One of: new, old, unrecommended,
679 recommended, new in series, obsolete, unknown.
680 "status/clients-seen"
681 A summary of which countries we've seen clients from recently,
682 formatted the same as the CLIENTS_SEEN status event described in
683 Section 4.1.14. This GETINFO option is currently available only
688 "net/listeners/socks"
689 "net/listeners/trans"
692 "net/listeners/control"
693 A space-separated list of the addresses at which Tor is listening for
694 connections of each specified type. [New in Tor 0.2.2.26-beta.]
697 C: GETINFO version desc/name/moria1
698 S: 250+desc/name/moria=
699 S: [Descriptor for moria]
701 S: 250-version=Tor 0.1.1.0-alpha-cvs
706 Sent from the client to the server. The format is:
707 "EXTENDCIRCUIT" SP CircuitID
708 [SP ServerSpec *("," ServerSpec)
709 SP "purpose=" Purpose] CRLF
711 This request takes one of two forms: either the CircuitID is zero, in
712 which case it is a request for the server to build a new circuit,
713 or the CircuitID is nonzero, in which case it is a request for the
714 server to extend an existing circuit with that ID according to the
717 If the CircuitID is 0, the controller has the option of providing
718 a path for Tor to use to build the circuit. If it does not provide
719 a path, Tor will select one automatically from high capacity nodes
720 according to path-spec.txt.
722 If CircuitID is 0 and "purpose=" is specified, then the circuit's
723 purpose is set. Two choices are recognized: "general" and
724 "controller". If not specified, circuits are created as "general".
726 If the request is successful, the server sends a reply containing a
727 message body consisting of the CircuitID of the (maybe newly created)
728 circuit. The syntax is "250" SP "EXTENDED" SP CircuitID CRLF.
730 3.11. SETCIRCUITPURPOSE
732 Sent from the client to the server. The format is:
733 "SETCIRCUITPURPOSE" SP CircuitID SP Purpose CRLF
735 This changes the circuit's purpose. See EXTENDCIRCUIT above for details.
737 3.12. SETROUTERPURPOSE
739 Sent from the client to the server. The format is:
740 "SETROUTERPURPOSE" SP NicknameOrKey SP Purpose CRLF
742 This changes the descriptor's purpose. See +POSTDESCRIPTOR below
745 NOTE: This command was disabled and made obsolete as of Tor
746 0.2.0.8-alpha. It doesn't exist anymore, and is listed here only for
751 Sent from the client to the server. The syntax is:
752 "ATTACHSTREAM" SP StreamID SP CircuitID [SP "HOP=" HopNum] CRLF
754 This message informs the server that the specified stream should be
755 associated with the specified circuit. Each stream may be associated with
756 at most one circuit, and multiple streams may share the same circuit.
757 Streams can only be attached to completed circuits (that is, circuits that
758 have sent a circuit status 'BUILT' event or are listed as built in a
759 GETINFO circuit-status request).
761 If the circuit ID is 0, responsibility for attaching the given stream is
764 If HOP=HopNum is specified, Tor will choose the HopNumth hop in the
765 circuit as the exit node, rather than the last node in the circuit.
766 Hops are 1-indexed; generally, it is not permitted to attach to hop 1.
768 Tor responds with "250 OK" if it can attach the stream, 552 if the circuit
769 or stream didn't exist, or 551 if the stream couldn't be attached for
772 {Implementation note: Tor will close unattached streams by itself,
773 roughly two minutes after they are born. Let the developers know if
774 that turns out to be a problem.}
776 {Implementation note: By default, Tor automatically attaches streams to
777 circuits itself, unless the configuration variable
778 "__LeaveStreamsUnattached" is set to "1". Attempting to attach streams
779 via TC when "__LeaveStreamsUnattached" is false may cause a race between
780 Tor and the controller, as both attempt to attach streams to circuits.}
782 {Implementation note: You can try to attachstream to a stream that
783 has already sent a connect or resolve request but hasn't succeeded
784 yet, in which case Tor will detach the stream from its current circuit
785 before proceeding with the new attach request.}
789 Sent from the client to the server. The syntax is:
790 "+POSTDESCRIPTOR" [SP "purpose=" Purpose] [SP "cache=" Cache]
791 CRLF Descriptor CRLF "." CRLF
793 This message informs the server about a new descriptor. If Purpose is
794 specified, it must be either "general", "controller", or "bridge",
795 else we return a 552 error. The default is "general".
797 If Cache is specified, it must be either "no" or "yes", else we
798 return a 552 error. If Cache is not specified, Tor will decide for
799 itself whether it wants to cache the descriptor, and controllers
800 must not rely on its choice.
802 The descriptor, when parsed, must contain a number of well-specified
803 fields, including fields for its nickname and identity.
805 If there is an error in parsing the descriptor, the server must send a
806 "554 Invalid descriptor" reply. If the descriptor is well-formed but
807 the server chooses not to add it, it must reply with a 251 message
808 whose body explains why the server was not added. If the descriptor
809 is added, Tor replies with "250 OK".
813 Sent from the client to the server. The syntax is:
814 "REDIRECTSTREAM" SP StreamID SP Address [SP Port] CRLF
816 Tells the server to change the exit address on the specified stream. If
817 Port is specified, changes the destination port as well. No remapping
818 is performed on the new provided address.
820 To be sure that the modified address will be used, this event must be sent
821 after a new stream event is received, and before attaching this stream to
824 Tor replies with "250 OK" on success.
828 Sent from the client to the server. The syntax is:
830 "CLOSESTREAM" SP StreamID SP Reason *(SP Flag) CRLF
832 Tells the server to close the specified stream. The reason should be one
833 of the Tor RELAY_END reasons given in tor-spec.txt, as a decimal. Flags is
834 not used currently; Tor servers SHOULD ignore unrecognized flags. Tor may
835 hold the stream open for a while to flush any data that is pending.
837 Tor replies with "250 OK" on success, or a 512 if there aren't enough
838 arguments, or a 552 if it doesn't recognize the StreamID or reason.
843 "CLOSECIRCUIT" SP CircuitID *(SP Flag) CRLF
846 Tells the server to close the specified circuit. If "IfUnused" is
847 provided, do not close the circuit unless it is unused.
849 Other flags may be defined in the future; Tor SHOULD ignore unrecognized
852 Tor replies with "250 OK" on success, or a 512 if there aren't enough
853 arguments, or a 552 if it doesn't recognize the CircuitID.
857 Tells the server to hang up on this controller connection. This command
858 can be used before authenticating.
862 Adding additional features to the control protocol sometimes will break
863 backwards compatibility. Initially such features are added into Tor and
864 disabled by default. USEFEATURE can enable these additional features.
868 "USEFEATURE" *(SP FeatureName) CRLF
869 FeatureName = 1*(ALPHA / DIGIT / "_" / "-")
871 Feature names are case-insensitive.
873 Once enabled, a feature stays enabled for the duration of the connection
874 to the controller. A new connection to the controller must be opened to
875 disable an enabled feature.
877 Features are a forward-compatibility mechanism; each feature will eventually
878 become a standard part of the control protocol. Once a feature becomes part
879 of the protocol, it is always-on. Each feature documents the version it was
880 introduced as a feature and the version in which it became part of the
883 Tor will ignore a request to use any feature that is always-on. Tor will give
884 a 552 error in response to an unrecognized feature.
888 Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to
889 request the extended event syntax.
891 This feature was first introduced in 0.1.2.3-alpha. It is always-on
892 and part of the protocol in Tor 0.2.2.1-alpha and later.
896 Replaces ServerID with LongName in events and GETINFO results. LongName
897 provides a Fingerprint for all routers, an indication of Named status,
898 and a Nickname if one is known. LongName is strictly more informative
899 than ServerID, which only provides either a Fingerprint or a Nickname.
901 This feature was first introduced in 0.1.2.2-alpha. It is always-on and
902 part of the protocol in Tor 0.2.2.1-alpha and later.
907 "RESOLVE" *Option *Address CRLF
908 Option = "mode=reverse"
909 Address = a hostname or IPv4 address
911 This command launches a remote hostname lookup request for every specified
912 request (or reverse lookup if "mode=reverse" is specified). Note that the
913 request is done in the background: to see the answers, your controller will
914 need to listen for ADDRMAP events; see 4.1.7 below.
916 [Added in Tor 0.2.0.3-alpha]
921 "PROTOCOLINFO" *(SP PIVERSION) CRLF
923 The server reply format is:
924 "250-PROTOCOLINFO" SP PIVERSION CRLF *InfoLine "250 OK" CRLF
926 InfoLine = AuthLine / VersionLine / OtherLine
928 AuthLine = "250-AUTH" SP "METHODS=" AuthMethod *("," AuthMethod)
929 *(SP "COOKIEFILE=" AuthCookieFile) CRLF
930 VersionLine = "250-VERSION" SP "Tor=" TorVersion OptArguments CRLF
933 "NULL" / ; No authentication is required
934 "HASHEDPASSWORD" / ; A controller must supply the original password
935 "COOKIE" / ; A controller must supply the contents of a cookie
937 AuthCookieFile = QuotedString
938 TorVersion = QuotedString
940 OtherLine = "250-" Keyword OptArguments CRLF
944 Tor MAY give its InfoLines in any order; controllers MUST ignore InfoLines
945 with keywords they do not recognize. Controllers MUST ignore extraneous
946 data on any InfoLine.
948 PIVERSION is there in case we drastically change the syntax one day. For
949 now it should always be "1". Controllers MAY provide a list of the
950 protocolinfo versions they support; Tor MAY select a version that the
951 controller does not support.
953 AuthMethod is used to specify one or more control authentication
954 methods that Tor currently accepts.
956 AuthCookieFile specifies the absolute path and filename of the
957 authentication cookie that Tor is expecting and is provided iff
958 the METHODS field contains the method "COOKIE". Controllers MUST handle
959 escape sequences inside this string.
961 The VERSION line contains the Tor version.
963 [Unlike other commands besides AUTHENTICATE, PROTOCOLINFO may be used (but
964 only once!) before AUTHENTICATE.]
966 [PROTOCOLINFO was not supported before Tor 0.2.0.5-alpha.]
971 "+LOADCONF" CRLF ConfigText CRLF "." CRLF
973 This command allows a controller to upload the text of a config file
974 to Tor over the control port. This config file is then loaded as if
975 it had been read from disk.
977 [LOADCONF was added in Tor 0.2.1.1-alpha.]
984 This command instructs Tor to shut down (as if it had received
985 SIGINT or a "SIGNAL INT" controller command) when this control
986 connection is closed. This command affects each control connection
987 that sends it independently; if multiple control connections send
988 the TAKEOWNERSHIP command to a Tor instance, Tor will shut down when
989 any of those connections closes.
991 This command is intended to be used with the
992 __OwningControllerProcess configuration option. A controller that
993 starts a Tor process which the user cannot easily control or stop
994 should 'own' that Tor process:
996 * When starting Tor, the controller should specify its PID in an
997 __OwningControllerProcess on Tor's command line. This will
998 cause Tor to poll for the existence of a process with that PID,
999 and exit if it does not find such a process. (This is not a
1000 completely reliable way to detect whether the 'owning
1001 controller' is still running, but it should work well enough in
1004 * Once the controller has connected to Tor's control port, it
1005 should send the TAKEOWNERSHIP command along its control
1006 connection. At this point, *both* the TAKEOWNERSHIP command and
1007 the __OwningControllerProcess option are in effect: Tor will
1008 exit when the control connection ends *and* Tor will exit if it
1009 detects that there is no process with the PID specified in the
1010 __OwningControllerProcess option.
1012 * After the controller has sent the TAKEOWNERSHIP command, it
1013 should send "RESETCONF __OwningControllerProcess" along its
1014 control connection. This will cause Tor to stop polling for the
1015 existence of a process with its owning controller's PID; Tor
1016 will still exit when the control connection ends.
1018 [TAKEOWNERSHIP was added in Tor 0.2.2.28-beta.]
1022 Reply codes follow the same 3-character format as used by SMTP, with the
1023 first character defining a status, the second character defining a
1024 subsystem, and the third designating fine-grained information.
1026 The TC protocol currently uses the following first characters:
1028 2yz Positive Completion Reply
1029 The command was successful; a new request can be started.
1031 4yz Temporary Negative Completion reply
1032 The command was unsuccessful but might be reattempted later.
1034 5yz Permanent Negative Completion Reply
1035 The command was unsuccessful; the client should not try exactly
1036 that sequence of commands again.
1038 6yz Asynchronous Reply
1039 Sent out-of-order in response to an earlier SETEVENTS command.
1041 The following second characters are used:
1044 Sent in response to ill-formed or nonsensical commands.
1047 Refers to operations of the Tor Control protocol.
1050 Refers to actual operations of Tor system.
1052 The following codes are defined:
1055 251 Operation was unnecessary
1056 [Tor has declined to perform the operation, but no harm was done.]
1058 451 Resource exhausted
1060 500 Syntax error: protocol
1062 510 Unrecognized command
1063 511 Unimplemented command
1064 512 Syntax error in command argument
1065 513 Unrecognized command argument
1066 514 Authentication required
1067 515 Bad authentication
1069 550 Unspecified Tor error
1072 [Something went wrong inside Tor, so that the client's
1073 request couldn't be fulfilled.]
1075 552 Unrecognized entity
1076 [A configuration key, a stream ID, circuit ID, event,
1077 mentioned in the command did not actually exist.]
1079 553 Invalid configuration value
1080 [The client tried to set a configuration option to an
1081 incorrect, ill-formed, or impossible value.]
1083 554 Invalid descriptor
1085 555 Unmanaged entity
1087 650 Asynchronous event notification
1089 Unless specified to have specific contents, the human-readable messages
1090 in error replies should not be relied upon to match those in this document.
1092 4.1. Asynchronous events
1094 These replies can be sent after a corresponding SETEVENTS command has been
1095 received. They will not be interleaved with other Reply elements, but they
1096 can appear between a command and its corresponding reply. For example,
1097 this sequence is possible:
1101 C: GETCONF SOCKSPORT ORPORT
1102 S: 650 CIRC 1000 EXTENDED moria1,moria2
1103 S: 250-SOCKSPORT=9050
1106 But this sequence is disallowed:
1109 C: GETCONF SOCKSPORT ORPORT
1110 S: 250-SOCKSPORT=9050
1111 S: 650 CIRC 1000 EXTENDED moria1,moria2
1114 Clients MUST tolerate more arguments in an asynchronous reply than
1115 expected, and MUST tolerate more lines in an asynchronous reply than
1116 expected. For instance, a client that expects a CIRC message like:
1117 650 CIRC 1000 EXTENDED moria1,moria2
1119 650-CIRC 1000 EXTENDED moria1,moria2 0xBEEF
1123 If clients receives extended events (selected by USEFEATUERE
1124 EXTENDED_EVENTS in Tor 0.1.2.2-alpha..Tor-0.2.1.x, and always-on in
1125 Tor 0.2.2.x and later), then each event line as specified below may be
1126 followed by additional arguments and additional lines. Additional
1127 lines will be of the form:
1128 "650" ("-"/" ") KEYWORD ["=" ARGUMENTS] CRLF
1129 Additional arguments will be of the form
1130 SP KEYWORD ["=" ( QuotedString / * NonSpDquote ) ]
1132 Clients MUST tolerate events with arguments and keywords they do not
1133 recognize, and SHOULD process those events as if any unrecognized
1134 arguments and keywords were not present.
1136 Clients SHOULD NOT depend on the order of keywords=value arguments,
1137 and SHOULD NOT depend on there being no new keyword=value arguments
1138 appearing between existing keyword=value arguments, though as of this
1139 writing (Jun 2011) some do. Thus, extensions to this protocol should
1140 add new keywords only after the existing keywords, until all
1141 controllers have been fixed. At some point this "SHOULD NOT" might
1142 become a "MUST NOT".
1144 4.1.1. Circuit status changed
1148 "650" SP "CIRC" SP CircuitID SP CircStatus [SP Path]
1149 [SP "REASON=" Reason [SP "REMOTE_REASON=" Reason]] CRLF
1152 "LAUNCHED" / ; circuit ID assigned to new circuit
1153 "BUILT" / ; all hops finished, can now accept streams
1154 "EXTENDED" / ; one more hop has been completed
1155 "FAILED" / ; circuit closed (was not built)
1156 "CLOSED" ; circuit closed (was built)
1158 Path = LongName *("," LongName)
1159 ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
1160 ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, Path
1162 Path = ServerID *("," ServerID)
1164 Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" /
1165 "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" /
1166 "OR_IDENTITY" / "OR_CONN_CLOSED" / "TIMEOUT" /
1167 "FINISHED" / "DESTROYED" / "NOPATH" / "NOSUCHSERVICE" /
1168 "MEASUREMENT_EXPIRED"
1170 The path is provided only when the circuit has been extended at least one
1173 The "REASON" field is provided only for FAILED and CLOSED events, and only
1174 if extended events are enabled (see 3.19). Clients MUST accept reasons
1175 not listed above. Reasons are as given in tor-spec.txt, except for:
1177 NOPATH (Not enough nodes to make circuit)
1179 The "REMOTE_REASON" field is provided only when we receive a DESTROY or
1180 TRUNCATE cell, and only if extended events are enabled. It contains the
1181 actual reason given by the remote OR for closing the circuit. Clients MUST
1182 accept reasons not listed above. Reasons are as listed in tor-spec.txt.
1184 4.1.2. Stream status changed
1188 "650" SP "STREAM" SP StreamID SP StreamStatus SP CircID SP Target
1189 [SP "REASON=" Reason [ SP "REMOTE_REASON=" Reason ]]
1190 [SP "SOURCE=" Source] [ SP "SOURCE_ADDR=" Address ":" Port ]
1191 [SP "PURPOSE=" Purpose]
1195 "NEW" / ; New request to connect
1196 "NEWRESOLVE" / ; New request to resolve an address
1197 "REMAP" / ; Address re-mapped to another
1198 "SENTCONNECT" / ; Sent a connect cell along a circuit
1199 "SENTRESOLVE" / ; Sent a resolve cell along a circuit
1200 "SUCCEEDED" / ; Received a reply; stream established
1201 "FAILED" / ; Stream failed and not retriable
1202 "CLOSED" / ; Stream closed
1203 "DETACHED" ; Detached from circuit; still retriable
1205 Target = Address ":" Port
1207 The circuit ID designates which circuit this stream is attached to. If
1208 the stream is unattached, the circuit ID "0" is given.
1210 Reason = "MISC" / "RESOLVEFAILED" / "CONNECTREFUSED" /
1211 "EXITPOLICY" / "DESTROY" / "DONE" / "TIMEOUT" /
1212 "NOROUTE" / "HIBERNATING" / "INTERNAL"/ "RESOURCELIMIT" /
1213 "CONNRESET" / "TORPROTOCOL" / "NOTDIRECTORY" / "END" /
1216 The "REASON" field is provided only for FAILED, CLOSED, and DETACHED
1217 events, and only if extended events are enabled (see 3.19). Clients MUST
1218 accept reasons not listed above. Reasons are as given in tor-spec.txt,
1221 END (We received a RELAY_END cell from the other side of this
1223 PRIVATE_ADDR (The client tried to connect to a private address like
1224 127.0.0.1 or 10.0.0.1 over Tor.)
1225 [XXXX document more. -NM]
1227 The "REMOTE_REASON" field is provided only when we receive a RELAY_END
1228 cell, and only if extended events are enabled. It contains the actual
1229 reason given by the remote OR for closing the stream. Clients MUST accept
1230 reasons not listed above. Reasons are as listed in tor-spec.txt.
1232 "REMAP" events include a Source if extended events are enabled:
1233 Source = "CACHE" / "EXIT"
1234 Clients MUST accept sources not listed above. "CACHE" is given if
1235 the Tor client decided to remap the address because of a cached
1236 answer, and "EXIT" is given if the remote node we queried gave us
1237 the new address as a response.
1239 The "SOURCE_ADDR" field is included with NEW and NEWRESOLVE events if
1240 extended events are enabled. It indicates the address and port
1241 that requested the connection, and can be (e.g.) used to look up the
1244 Purpose = "DIR_FETCH" / "UPLOAD_DESC" / "DNS_REQUEST" /
1245 "USER" / "DIRPORT_TEST"
1247 The "PURPOSE" field is provided only for NEW and NEWRESOLVE events, and
1248 only if extended events are enabled (see 3.19). Clients MUST accept
1249 purposes not listed above.
1251 4.1.3. OR Connection status changed
1255 "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON="
1256 Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
1258 ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"
1260 ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
1261 ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, OR
1262 ; Connection is as follows:
1263 "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON="
1264 Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
1266 NEW is for incoming connections, and LAUNCHED is for outgoing
1267 connections. CONNECTED means the TLS handshake has finished (in
1268 either direction). FAILED means a connection is being closed that
1269 hasn't finished its handshake, and CLOSED is for connections that
1272 A LongName or ServerID is specified unless it's a NEW connection, in
1273 which case we don't know what server it is yet, so we use Address:Port.
1275 If extended events are enabled (see 3.19), optional reason and
1276 circuit counting information is provided for CLOSED and FAILED
1279 Reason = "MISC" / "DONE" / "CONNECTREFUSED" /
1280 "IDENTITY" / "CONNECTRESET" / "TIMEOUT" / "NOROUTE" /
1281 "IOERROR" / "RESOURCELIMIT"
1283 NumCircuits counts both established and pending circuits.
1285 4.1.4. Bandwidth used in the last second
1288 "650" SP "BW" SP BytesRead SP BytesWritten *(SP Type "=" Num) CRLF
1290 BytesWritten = 1*DIGIT
1291 Type = "DIR" / "OR" / "EXIT" / "APP" / ...
1294 BytesRead and BytesWritten are the totals. [In a future Tor version,
1295 we may also include a breakdown of the connection types that used
1296 bandwidth this second (not implemented yet).]
1301 "650" SP Severity SP ReplyText CRLF
1303 "650+" Severity CRLF Data 650 SP "OK" CRLF
1305 Severity = "DEBUG" / "INFO" / "NOTICE" / "WARN"/ "ERR"
1307 4.1.6. New descriptors available
1310 "650" SP "NEWDESC" 1*(SP LongName) CRLF
1311 ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
1312 ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, it
1314 "650" SP "NEWDESC" 1*(SP ServerID) CRLF
1316 4.1.7. New Address mapping
1319 "650" SP "ADDRMAP" SP Address SP NewAddress SP Expiry
1320 [SP Error] SP GMTExpiry CRLF
1322 NewAddress = Address / "<error>"
1323 Expiry = DQUOTE ISOTime DQUOTE / "NEVER"
1325 Error = "error=" ErrorCode
1327 GMTExpiry = "EXPIRES=" DQUOTE IsoTime DQUOTE
1329 Error and GMTExpiry are only provided if extended events are enabled.
1331 Expiry is expressed as the local time (rather than GMT). This is a bug,
1332 left in for backward compatibility; new code should look at GMTExpiry
1335 These events are generated when a new address mapping is entered in the
1336 cache, or when the answer for a RESOLVE command is found.
1338 4.1.8. Descriptors uploaded to us in our role as authoritative dirserver
1341 "650" "+" "AUTHDIR_NEWDESCS" CRLF Action CRLF Message CRLF
1342 Descriptor CRLF "." CRLF "650" SP "OK" CRLF
1343 Action = "ACCEPTED" / "DROPPED" / "REJECTED"
1346 4.1.9. Our descriptor changed
1349 "650" SP "DESCCHANGED" CRLF
1351 [First added in 0.1.2.2-alpha.]
1353 4.1.10. Status events
1355 Status events (STATUS_GENERAL, STATUS_CLIENT, and STATUS_SERVER) are sent
1356 based on occurrences in the Tor process pertaining to the general state of
1357 the program. Generally, they correspond to log messages of severity Notice
1358 or higher. They differ from log messages in that their format is a
1359 specified interface.
1362 "650" SP StatusType SP StatusSeverity SP StatusAction
1363 [SP StatusArguments] CRLF
1365 StatusType = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"
1366 StatusSeverity = "NOTICE" / "WARN" / "ERR"
1367 StatusAction = 1*ALPHA
1368 StatusArguments = StatusArgument *(SP StatusArgument)
1369 StatusArgument = StatusKeyword '=' StatusValue
1370 StatusKeyword = 1*(ALNUM / "_")
1371 StatusValue = 1*(ALNUM / '_') / QuotedString
1373 StatusAction is a string, and StatusArguments is a series of
1374 keyword=value pairs on the same line. Values may be space-terminated
1375 strings, or quoted strings.
1377 These events are always produced with EXTENDED_EVENTS and
1378 VERBOSE_NAMES; see the explanations in the USEFEATURE section
1381 Controllers MUST tolerate unrecognized actions, MUST tolerate
1382 unrecognized arguments, MUST tolerate missing arguments, and MUST
1383 tolerate arguments that arrive in any order.
1385 Each event description below is accompanied by a recommendation for
1386 controllers. These recommendations are suggestions only; no controller
1387 is required to implement them.
1389 Compatibility note: versions of Tor before 0.2.0.22-rc incorrectly
1390 generated "STATUS_SERVER" as "STATUS_SEVER". To be compatible with those
1391 versions, tools should accept both.
1393 Actions for STATUS_GENERAL events can be as follows:
1397 Tor spent enough time without CPU cycles that it has closed all
1398 its circuits and will establish them anew. This typically
1399 happens when a laptop goes to sleep and then wakes up again. It
1400 also happens when the system is swapping so heavily that Tor is
1401 starving. The "time" argument specifies the number of seconds Tor
1402 thinks it was unconscious for (or alternatively, the number of
1403 seconds it went back in time).
1405 This status event is sent as NOTICE severity normally, but WARN
1406 severity if Tor is acting as a server currently.
1408 {Recommendation for controller: ignore it, since we don't really
1409 know what the user should do anyway. Hm.}
1413 "REASON=NEW/OBSOLETE/UNRECOMMENDED"
1414 "RECOMMENDED=\"version, version, ...\""
1415 Tor has found that directory servers don't recommend its version of
1416 the Tor software. RECOMMENDED is a comma-and-space-separated string
1417 of Tor versions that are recommended. REASON is NEW if this version
1418 of Tor is newer than any recommended version, OBSOLETE if
1419 this version of Tor is older than any recommended version, and
1420 UNRECOMMENDED if some recommended versions of Tor are newer and
1421 some are older than this version. (The "OBSOLETE" reason was called
1422 "OLD" from Tor 0.1.2.3-alpha up to and including 0.2.0.12-alpha.)
1424 {Controllers may want to suggest that the user upgrade OLD or
1425 UNRECOMMENDED versions. NEW versions may be known-insecure, or may
1426 simply be development versions.}
1428 TOO_MANY_CONNECTIONS
1430 Tor has reached its ulimit -n or whatever the native limit is on file
1431 descriptors or sockets. CURRENT is the number of sockets Tor
1432 currently has open. The user should really do something about
1433 this. The "current" argument shows the number of connections currently
1436 {Controllers may recommend that the user increase the limit, or
1437 increase it for them. Recommendations should be phrased in an
1438 OS-appropriate way and automated when possible.}
1442 Tor has encountered a situation that its developers never expected,
1443 and the developers would like to learn that it happened. Perhaps
1444 the controller can explain this to the user and encourage her to
1447 {Controllers should log bugs, but shouldn't annoy the user in case a
1448 bug appears frequently.}
1451 SKEW="+" / "-" SECONDS
1452 MIN_SKEW="+" / "-" SECONDS.
1453 SOURCE="DIRSERV:" IP ":" Port /
1454 "NETWORKSTATUS:" IP ":" Port /
1457 If "SKEW" is present, it's an estimate of how far we are from the
1458 time declared in the source. (In other words, if we're an hour in
1459 the past, the value is -3600.) "MIN_SKEW" is present, it's a lower
1460 bound. If the source is a DIRSERV, we got the current time from a
1461 connection to a dirserver. If the source is a NETWORKSTATUS, we
1462 decided we're skewed because we got a v2 networkstatus from far in
1463 the future. If the source is OR, the skew comes from a NETINFO
1464 cell from a connection to another relay. If the source is
1465 CONSENSUS, we decided we're skewed because we got a networkstatus
1466 consensus from the future.
1468 {Tor should send this message to controllers when it thinks the
1469 skew is so high that it will interfere with proper Tor operation.
1470 Controllers shouldn't blindly adjust the clock, since the more
1471 accurate source of skew info (DIRSERV) is currently
1475 "METHOD=" libevent method
1476 "VERSION=" libevent version
1477 "BADNESS=" "BROKEN" / "BUGGY" / "SLOW"
1478 "RECOVERED=" "NO" / "YES"
1479 Tor knows about bugs in using the configured event method in this
1480 version of libevent. "BROKEN" libevents won't work at all;
1481 "BUGGY" libevents might work okay; "SLOW" libevents will work
1482 fine, but not quickly. If "RECOVERED" is YES, Tor managed to
1483 switch to a more reliable (but probably slower!) libevent method.
1485 {Controllers may want to warn the user if this event occurs, though
1486 generally it's the fault of whoever built the Tor binary and there's
1487 not much the user can do besides upgrade libevent or upgrade the
1491 Tor believes that none of the known directory servers are
1492 reachable -- this is most likely because the local network is
1493 down or otherwise not working, and might help to explain for the
1494 user why Tor appears to be broken.
1496 {Controllers may want to warn the user if this event occurs; further
1497 action is generally not possible.}
1500 Tor has received and validated a new consensus networkstatus.
1501 (This event can be delayed a little while after the consensus
1502 is received, if Tor needs to fetch certificates.)
1504 Actions for STATUS_CLIENT events can be as follows:
1513 "RECOMMENDATION=" Keyword
1516 Tor has made some progress at establishing a connection to the
1517 Tor network, fetching directory information, or making its first
1518 circuit; or it has encountered a problem while bootstrapping. This
1519 status event is especially useful for users with slow connections
1520 or with connectivity problems.
1522 "Progress" gives a number between 0 and 100 for how far through
1523 the bootstrapping process we are. "Summary" is a string that can
1524 be displayed to the user to describe the *next* task that Tor
1525 will tackle, i.e., the task it is working on after sending the
1526 status event. "Tag" is a string that controllers can use to
1527 recognize bootstrap phases, if they want to do something smarter
1528 than just blindly displaying the summary string; see Section 5
1529 for the current tags that Tor issues.
1531 The StatusSeverity describes whether this is a normal bootstrap
1532 phase (severity notice) or an indication of a bootstrapping
1533 problem (severity warn).
1535 For bootstrap problems, we include the same progress, tag, and
1536 summary values as we would for a normal bootstrap event, but we
1537 also include "warning", "reason", "count", and "recommendation"
1538 key/value combos. The "count" number tells how many bootstrap
1539 problems there have been so far at this phase. The "reason"
1540 string lists one of the reasons allowed in the ORCONN event. The
1541 "warning" argument string with any hints Tor has to offer about
1542 why it's having troubles bootstrapping.
1544 The "reason" values are long-term-stable controller-facing tags to
1545 identify particular issues in a bootstrapping step. The warning
1546 strings, on the other hand, are human-readable. Controllers
1547 SHOULD NOT rely on the format of any warning string. Currently
1548 the possible values for "recommendation" are either "ignore" or
1549 "warn" -- if ignore, the controller can accumulate the string in
1550 a pile of problems to show the user if the user asks; if warn,
1551 the controller should alert the user that Tor is pretty sure
1552 there's a bootstrapping problem.
1554 Currently Tor uses recommendation=ignore for the first
1555 nine bootstrap problem reports for a given phase, and then
1556 uses recommendation=warn for subsequent problems at that
1557 phase. Hopefully this is a good balance between tolerating
1558 occasional errors and reporting serious problems quickly.
1561 Tor now knows enough network-status documents and enough server
1562 descriptors that it's going to start trying to build circuits now.
1564 {Controllers may want to use this event to decide when to indicate
1565 progress to their users, but should not interrupt the user's browsing
1569 We discarded expired statuses and router descriptors to fall
1570 below the desired threshold of directory information. We won't
1571 try to build any circuits until ENOUGH_DIR_INFO occurs again.
1573 {Controllers may want to use this event to decide when to indicate
1574 progress to their users, but should not interrupt the user's browsing
1578 Tor is able to establish circuits for client use. This event will
1579 only be sent if we just built a circuit that changed our mind --
1580 that is, prior to this event we didn't know whether we could
1583 {Suggested use: controllers can notify their users that Tor is
1584 ready for use as a client once they see this status event. [Perhaps
1585 controllers should also have a timeout if too much time passes and
1586 this event hasn't arrived, to give tips on how to troubleshoot.
1587 On the other hand, hopefully Tor will send further status events
1588 if it can identify the problem.]}
1590 CIRCUIT_NOT_ESTABLISHED
1591 "REASON=" "EXTERNAL_ADDRESS" / "DIR_ALL_UNREACHABLE" / "CLOCK_JUMPED"
1592 We are no longer confident that we can build circuits. The "reason"
1593 keyword provides an explanation: which other status event type caused
1594 our lack of confidence.
1596 {Controllers may want to use this event to decide when to indicate
1597 progress to their users, but should not interrupt the user's browsing
1599 [Note: only REASON=CLOCK_JUMPED is implemented currently.]
1603 "RESULT=" "REJECT" / "WARN"
1604 A stream was initiated to a port that's commonly used for
1605 vulnerable-plaintext protocols. If the Result is "reject", we
1606 refused the connection; whereas if it's "warn", we allowed it.
1608 {Controllers should warn their users when this occurs, unless they
1609 happen to know that the application using Tor is in fact doing so
1610 correctly (e.g., because it is part of a distributed bundle). They
1611 might also want some sort of interface to let the user configure
1612 their RejectPlaintextPorts and WarnPlaintextPorts config options.}
1615 "PROTOCOL=" "SOCKS4" / "SOCKS5"
1617 A connection was made to Tor's SOCKS port using one of the SOCKS
1618 approaches that doesn't support hostnames -- only raw IP addresses.
1619 If the client application got this address from gethostbyname(),
1620 it may be leaking target addresses via DNS.
1622 {Controllers should warn their users when this occurs, unless they
1623 happen to know that the application using Tor is in fact doing so
1624 correctly (e.g., because it is part of a distributed bundle).}
1626 SOCKS_UNKNOWN_PROTOCOL
1628 A connection was made to Tor's SOCKS port that tried to use it
1629 for something other than the SOCKS protocol. Perhaps the user is
1630 using Tor as an HTTP proxy? The DATA is the first few characters
1631 sent to Tor on the SOCKS port.
1633 {Controllers may want to warn their users when this occurs: it
1634 indicates a misconfigured application.}
1637 "HOSTNAME=QuotedString"
1638 Some application gave us a funny-looking hostname. Perhaps
1639 it is broken? In any case it won't work with Tor and the user
1642 {Controllers may want to warn their users when this occurs: it
1643 usually indicates a misconfigured application.}
1645 Actions for STATUS_SERVER can be as follows:
1650 "METHOD=CONFIGURED/DIRSERV/RESOLVED/INTERFACE/GETHOSTNAME"
1651 Our best idea for our externally visible IP has changed to 'IP'.
1652 If 'HOSTNAME' is present, we got the new IP by resolving 'NAME'. If the
1653 method is 'CONFIGURED', the IP was given verbatim as a configuration
1654 option. If the method is 'RESOLVED', we resolved the Address
1655 configuration option to get the IP. If the method is 'GETHOSTNAME',
1656 we resolved our hostname to get the IP. If the method is 'INTERFACE',
1657 we got the address of one of our network interfaces to get the IP. If
1658 the method is 'DIRSERV', a directory server told us a guess for what
1661 {Controllers may want to record this info and display it to the user.}
1663 CHECKING_REACHABILITY
1665 "DIRADDRESS=IP:port"
1666 We're going to start testing the reachability of our external OR port
1669 {This event could affect the controller's idea of server status, but
1670 the controller should not interrupt the user to tell them so.}
1672 REACHABILITY_SUCCEEDED
1674 "DIRADDRESS=IP:port"
1675 We successfully verified the reachability of our external OR port or
1676 directory port (depending on which of ORADDRESS or DIRADDRESS is
1679 {This event could affect the controller's idea of server status, but
1680 the controller should not interrupt the user to tell them so.}
1682 GOOD_SERVER_DESCRIPTOR
1683 We successfully uploaded our server descriptor to at least one
1684 of the directory authorities, with no complaints.
1686 {Originally, the goal of this event was to declare "every authority
1687 has accepted the descriptor, so there will be no complaints
1688 about it." But since some authorities might be offline, it's
1689 harder to get certainty than we had thought. As such, this event
1690 is equivalent to ACCEPTED_SERVER_DESCRIPTOR below. Controllers
1691 should just look at ACCEPTED_SERVER_DESCRIPTOR and should ignore
1692 this event for now.}
1694 SERVER_DESCRIPTOR_STATUS
1695 "STATUS=" "LISTED" / "UNLISTED"
1696 We just got a new networkstatus consensus, and whether we're in
1697 it or not in it has changed. Specifically, status is "listed"
1698 if we're listed in it but previous to this point we didn't know
1699 we were listed in a consensus; and status is "unlisted" if we
1700 thought we should have been listed in it (e.g. we were listed in
1701 the last one), but we're not.
1703 {Moving from listed to unlisted is not necessarily cause for
1704 alarm. The relay might have failed a few reachability tests,
1705 or the Internet might have had some routing problems. So this
1706 feature is mainly to let relay operators know when their relay
1707 has successfully been listed in the consensus.}
1709 [Not implemented yet. We should do this in 0.2.2.x. -RD]
1713 "STATUS=" "UP" / "DOWN"
1715 One of our nameservers has changed status.
1717 {This event could affect the controller's idea of server status, but
1718 the controller should not interrupt the user to tell them so.}
1721 All of our nameservers have gone down.
1723 {This is a problem; if it happens often without the nameservers
1724 coming up again, the user needs to configure more or better
1728 Our DNS provider is providing an address when it should be saying
1729 "NOTFOUND"; Tor will treat the address as a synonym for "NOTFOUND".
1731 {This is an annoyance; controllers may want to tell admins that their
1732 DNS provider is not to be trusted.}
1735 Our DNS provider is giving a hijacked address instead of well-known
1736 websites; Tor will not try to be an exit node.
1738 {Controllers could warn the admin if the relay is running as an
1739 exit node: the admin needs to configure a good DNS server.
1740 Alternatively, this happens a lot in some restrictive environments
1741 (hotels, universities, coffeeshops) when the user hasn't registered.}
1743 BAD_SERVER_DESCRIPTOR
1746 A directory authority rejected our descriptor. Possible reasons
1747 include malformed descriptors, incorrect keys, highly skewed clocks,
1750 {Controllers should warn the admin, and try to cope if they can.}
1752 ACCEPTED_SERVER_DESCRIPTOR
1754 A single directory authority accepted our descriptor.
1757 {This event could affect the controller's idea of server status, but
1758 the controller should not interrupt the user to tell them so.}
1762 "DIRADDRESS=IP:port"
1763 We failed to connect to our external OR port or directory port
1766 {This event could affect the controller's idea of server status. The
1767 controller should warn the admin and suggest reasonable steps to take.}
1769 4.1.11. Our set of guard nodes has changed
1772 "650" SP "GUARD" SP Type SP Name SP Status ... CRLF
1774 Name = The (possibly verbose) nickname of the guard affected.
1775 Status = "NEW" | "UP" | "DOWN" | "BAD" | "GOOD" | "DROPPED"
1777 [explain states. XXX]
1779 4.1.12. Network status has changed
1782 "650" "+" "NS" CRLF 1*NetworkStatus "." CRLF "650" SP "OK" CRLF
1784 The event is used whenever our local view of a relay status changes.
1785 This happens when we get a new v3 consensus (in which case the entries
1786 we see are a duplicate of what we see in the NEWCONSENSUS event,
1787 below), but it also happens when we decide to mark a relay as up or
1788 down in our local status, for example based on connection attempts.
1790 [First added in 0.1.2.3-alpha]
1792 4.1.13. Bandwidth used on an application stream
1795 "650" SP "STREAM_BW" SP StreamID SP BytesWritten SP BytesRead CRLF
1796 BytesWritten = 1*DIGIT
1799 BytesWritten and BytesRead are the number of bytes written and read
1800 by the application since the last STREAM_BW event on this stream.
1802 Note that from Tor's perspective, *reading* a byte on a stream means
1803 that the application *wrote* the byte. That's why the order of "written"
1804 vs "read" is opposite for stream_bw events compared to bw events.
1806 These events are generated about once per second per stream; no events
1807 are generated for streams that have not written or read. These events
1808 apply only to streams entering Tor (such as on a SOCKSPort, TransPort,
1809 or so on). They are not generated for exiting streams.
1811 4.1.14. Per-country client stats
1814 "650" SP "CLIENTS_SEEN" SP TimeStarted SP CountrySummary CRLF
1816 We just generated a new summary of which countries we've seen clients
1817 from recently. The controller could display this for the user, e.g.
1818 in their "relay" configuration window, to give them a sense that they
1819 are actually being useful.
1821 Currently only bridge relays will receive this event, but once we figure
1822 out how to sufficiently aggregate and sanitize the client counts on
1823 main relays, we might start sending these events in other cases too.
1825 TimeStarted is a quoted string indicating when the reported summary
1826 counts from (in GMT).
1828 The CountrySummary keyword has as its argument a comma-separated,
1829 possibly empty set of "countrycode=count" pairs. For example (without
1831 650-CLIENTS_SEEN TimeStarted="2008-12-25 23:50:43"
1832 CountrySummary=us=16,de=8,uk=8
1834 4.1.15. New consensus networkstatus has arrived
1837 "650" "+" "NEWCONSENSUS" CRLF 1*NetworkStatus "." CRLF "650" SP
1840 A new consensus networkstatus has arrived. We include NS-style lines for
1841 every relay in the consensus. NEWCONSENSUS is a separate event from the
1842 NS event, because the list here represents every usable relay: so any
1843 relay *not* mentioned in this list is implicitly no longer recommended.
1845 [First added in 0.2.1.13-alpha]
1847 4.1.16. New circuit buildtime has been set
1850 "650" SP "BUILDTIMEOUT_SET" SP Type SP "TOTAL_TIMES=" Total SP
1851 "TIMEOUT_MS=" Timeout SP "XM=" Xm SP "ALPHA=" Alpha SP
1852 "CUTOFF_QUANTILE=" Quantile SP "TIMEOUT_RATE=" TimeoutRate SP
1853 "CLOSE_MS=" CloseTimeout SP "CLOSE_RATE=" CloseRate
1855 Type = "COMPUTED" / "RESET" / "SUSPENDED" / "DISCARD" / "RESUME"
1856 Total = Integer count of timeouts stored
1857 Timeout = Integer timeout in milliseconds
1858 Xm = Estimated integer Pareto parameter Xm in milliseconds
1859 Alpha = Estimated floating point Paredo paremter alpha
1860 Quantile = Floating point CDF quantile cutoff point for this timeout
1861 TimeoutRate = Floating point ratio of circuits that timeout
1862 CloseTimeout = How long to keep measurement circs in milliseconds
1863 CloseRate = Floating point ratio of measurement circuits that are closed
1865 A new circuit build timeout time has been set. If Type is "COMPUTED",
1866 Tor has computed the value based on historical data. If Type is "RESET",
1867 initialization or drastic network changes have caused Tor to reset
1868 the timeout back to the default, to relearn again. If Type is
1869 "SUSPENDED", Tor has detected a loss of network connectivity and has
1870 temporarily changed the timeout value to the default until the network
1871 recovers. If type is "DISCARD", Tor has decided to discard timeout
1872 values that likely happened while the network was down. If type is
1873 "RESUME", Tor has decided to resume timeout calculation.
1875 The Total value is the count of circuit build times Tor used in
1876 computing this value. It is capped internally at the maximum number
1877 of build times Tor stores (NCIRCUITS_TO_OBSERVE).
1879 The Timeout itself is provided in milliseconds. Internally, Tor rounds
1880 this value to the nearest second before using it.
1882 [First added in 0.2.2.7-alpha]
1884 4.1.17. Signal received
1887 "650" SP "SIGNAL" SP Signal CRLF
1889 Signal = "RELOAD" / "DUMP" / "DEBUG" / "NEWNYM" / "CLEARDNSCACHE"
1891 A signal has been received and actions taken by Tor. The meaning of each
1892 signal, and the mapping to Unix signals, is as defined in section 3.7.
1893 Future versions of Tor MAY generate signals other than those listed here;
1894 controllers MUST be able to accept them.
1896 If Tor chose to ignore a signal (such as NEWNYM), this event will not be
1897 sent. Note that some options (like ReloadTorrcOnSIGHUP) may affect the
1898 semantics of the signals here.
1900 Note that the HALT (SIGTERM) and SHUTDOWN (SIGINT) signals do not currently
1903 [First added in 0.2.3.1-alpha]
1905 4.1.18. Configuration changed
1908 StartReplyLine *(MidReplyLine) EndReplyLine
1910 StartReplyLine = "650-CONF_CHANGED" CRLF
1911 MidReplyLine = "650-" KEYWORD ["=" VALUE] CRLF
1912 EndReplyLine = "650 OK"
1914 Tor configuration options have changed (such as via a SETCONF or RELOAD
1915 signal). KEYWORD and VALUE specify the configuration option that was changed.
1916 Undefined configuration options contain only the KEYWORD.
1918 5. Implementation notes
1922 If the control port is open and no authentication operation is enabled, Tor
1923 trusts any local user that connects to the control port. This is generally
1926 If the 'CookieAuthentication' option is true, Tor writes a "magic cookie"
1927 file named "control_auth_cookie" into its data directory. To authenticate,
1928 the controller must send the contents of this file, encoded in hexadecimal.
1930 If the 'HashedControlPassword' option is set, it must contain the salted
1931 hash of a secret password. The salted hash is computed according to the
1932 S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier.
1933 This is then encoded in hexadecimal, prefixed by the indicator sequence
1934 "16:". Thus, for example, the password 'foo' could encode to:
1935 16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2
1936 ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1939 You can generate the salt of a password by calling
1940 'tor --hash-password <password>'
1941 or by using the example code in the Python and Java controller libraries.
1942 To authenticate under this scheme, the controller sends Tor the original
1943 secret that was used to generate the password, either as a quoted string
1944 or encoded in hexadecimal.
1946 5.2. Don't let the buffer get too big.
1948 If you ask for lots of events, and 16MB of them queue up on the buffer,
1949 the Tor process will close the socket.
1951 5.3. Backward compatibility with v0 control protocol.
1953 The 'version 0' control protocol was replaced in Tor 0.1.1.x. Support
1954 was removed in Tor 0.2.0.x. Every non-obsolete version of Tor now
1955 supports the version 1 control protocol.
1957 For backward compatibility with the "version 0" control protocol,
1958 Tor used to check whether the third octet of the first command is zero.
1959 (If it was, Tor assumed that version 0 is in use.)
1961 This compatibility was removed in Tor 0.1.2.16 and 0.2.0.4-alpha.
1963 5.4. Tor config options for use by controllers
1965 Tor provides a few special configuration options for use by controllers.
1966 These options can be set and examined by the SETCONF and GETCONF commands,
1967 but are not saved to disk by SAVECONF.
1969 Generally, these options make Tor unusable by disabling a portion of Tor's
1970 normal operations. Unless a controller provides replacement functionality
1971 to fill this gap, Tor will not correctly handle user requests.
1973 __AllDirActionsPrivate
1975 If true, Tor will try to launch all directory operations through
1976 anonymous connections. (Ordinarily, Tor only tries to anonymize
1977 requests related to hidden services.) This option will slow down
1978 directory access, and may stop Tor from working entirely if it does not
1979 yet have enough directory information to build circuits.
1981 (Boolean. Default: "0".)
1983 __DisablePredictedCircuits
1985 If true, Tor will not launch preemptive "general-purpose" circuits for
1986 streams to attach to. (It will still launch circuits for testing and
1987 for hidden services.)
1989 (Boolean. Default: "0".)
1991 __LeaveStreamsUnattached
1993 If true, Tor will not automatically attach new streams to circuits;
1994 instead, the controller must attach them with ATTACHSTREAM. If the
1995 controller does not attach the streams, their data will never be routed.
1997 (Boolean. Default: "0".)
1999 __HashedControlSessionPassword
2001 As HashedControlPassword, but is not saved to the torrc file by
2002 SAVECONF. Added in Tor 0.2.0.20-rc.
2004 __ReloadTorrcOnSIGHUP
2006 If this option is true (the default), we reload the torrc from disk
2007 every time we get a SIGHUP (from the controller or via a signal).
2008 Otherwise, we don't. This option exists so that controllers can keep
2009 their options from getting overwritten when a user sends Tor a HUP for
2010 some other reason (for example, to rotate the logs).
2012 (Boolean. Default: "1")
2014 __OwningControllerProcess
2016 If this option is set to a process ID, Tor will periodically check
2017 whether a process with the specified PID exists, and exit if one
2018 does not. Added in Tor 0.2.2.28-beta. This option's intended use
2019 is documented in section 3.23 with the related TAKEOWNERSHIP
2022 Note that this option can only specify a single process ID, unlike
2023 the TAKEOWNERSHIP command which can be sent along multiple control
2026 (String. Default: unset.)
2028 5.5. Phases from the Bootstrap status event.
2030 This section describes the various bootstrap phases currently reported
2031 by Tor. Controllers should not assume that the percentages and tags
2032 listed here will continue to match up, or even that the tags will stay
2033 in the same order. Some phases might also be skipped (not reported)
2034 if the associated bootstrap step is already complete, or if the phase
2035 no longer is necessary. Only "starting" and "done" are guaranteed to
2036 exist in all future versions.
2038 Current Tor versions enter these phases in order, monotonically.
2039 Future Tors MAY revisit earlier stages.
2042 tag=starting summary="Starting"
2044 Tor starts out in this phase.
2047 tag=conn_dir summary="Connecting to directory mirror"
2049 Tor sends this event as soon as Tor has chosen a directory mirror --
2050 e.g. one of the authorities if bootstrapping for the first time or
2051 after a long downtime, or one of the relays listed in its cached
2052 directory information otherwise.
2054 Tor will stay at this phase until it has successfully established
2055 a TCP connection with some directory mirror. Problems in this phase
2056 generally happen because Tor doesn't have a network connection, or
2057 because the local firewall is dropping SYN packets.
2060 tag=handshake_dir summary="Finishing handshake with directory mirror"
2062 This event occurs when Tor establishes a TCP connection with a relay used
2063 as a directory mirror (or its https proxy if it's using one). Tor remains
2064 in this phase until the TLS handshake with the relay is finished.
2066 Problems in this phase generally happen because Tor's firewall is
2067 doing more sophisticated MITM attacks on it, or doing packet-level
2068 keyword recognition of Tor's handshake.
2071 tag=onehop_create summary="Establishing one-hop circuit for dir info"
2073 Once TLS is finished with a relay, Tor will send a CREATE_FAST cell
2074 to establish a one-hop circuit for retrieving directory information.
2075 It will remain in this phase until it receives the CREATED_FAST cell
2076 back, indicating that the circuit is ready.
2079 tag=requesting_status summary="Asking for networkstatus consensus"
2081 Once we've finished our one-hop circuit, we will start a new stream
2082 for fetching the networkstatus consensus. We'll stay in this phase
2083 until we get the 'connected' relay cell back, indicating that we've
2084 established a directory connection.
2087 tag=loading_status summary="Loading networkstatus consensus"
2089 Once we've established a directory connection, we will start fetching
2090 the networkstatus consensus document. This could take a while; this
2091 phase is a good opportunity for using the "progress" keyword to indicate
2094 This phase could stall if the directory mirror we picked doesn't
2095 have a copy of the networkstatus consensus so we have to ask another,
2096 or it does give us a copy but we don't find it valid.
2099 tag=loading_keys summary="Loading authority key certs"
2101 Sometimes when we've finished loading the networkstatus consensus,
2102 we find that we don't have all the authority key certificates for the
2103 keys that signed the consensus. At that point we put the consensus we
2104 fetched on hold and fetch the keys so we can verify the signatures.
2107 tag=requesting_descriptors summary="Asking for relay descriptors"
2109 Once we have a valid networkstatus consensus and we've checked all
2110 its signatures, we start asking for relay descriptors. We stay in this
2111 phase until we have received a 'connected' relay cell in response to
2112 a request for descriptors.
2115 tag=loading_descriptors summary="Loading relay descriptors"
2117 We will ask for relay descriptors from several different locations,
2118 so this step will probably make up the bulk of the bootstrapping,
2119 especially for users with slow connections. We stay in this phase until
2120 we have descriptors for at least 1/4 of the usable relays listed in
2121 the networkstatus consensus. This phase is also a good opportunity to
2122 use the "progress" keyword to indicate partial steps.
2125 tag=conn_or summary="Connecting to entry guard"
2127 Once we have a valid consensus and enough relay descriptors, we choose
2128 some entry guards and start trying to build some circuits. This step
2129 is similar to the "conn_dir" phase above; the only difference is
2132 If a Tor starts with enough recent cached directory information,
2133 its first bootstrap status event will be for the conn_or phase.
2136 tag=handshake_or summary="Finishing handshake with entry guard"
2138 This phase is similar to the "handshake_dir" phase, but it gets reached
2139 if we finish a TCP connection to a Tor relay and we have already reached
2140 the "conn_or" phase. We'll stay in this phase until we complete a TLS
2141 handshake with a Tor relay.
2144 tag=circuit_create summary="Establishing circuits"
2146 Once we've finished our TLS handshake with an entry guard, we will
2147 set about trying to make some 3-hop circuits in case we need them soon.
2150 tag=done summary="Done"
2152 A full 3-hop exit circuit has been established. Tor is ready to handle
2153 application connections now.