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.
45 2.1. Description format
47 The message formats listed below use ABNF as described in RFC 2234.
48 The protocol itself is loosely based on SMTP (see RFC 2821).
50 We use the following nonterminals from RFC 2822: atom, qcontent
52 We define the following general-use nonterminals:
54 String = DQUOTE *qcontent DQUOTE
56 There are explicitly no limits on line length. All 8-bit characters are
57 permitted unless explicitly disallowed.
59 Wherever CRLF is specified to be accepted from the controller, Tor MAY also
60 accept LF. Tor, however, MUST NOT generate LF instead of CRLF.
61 Controllers SHOULD always send CRLF.
63 2.2. Commands from controller to Tor
65 Command = Keyword Arguments CRLF / "+" Keyword Arguments CRLF Data
67 Arguments = *(SP / VCHAR)
69 Specific commands and their arguments are described below in section 3.
71 2.3. Replies from Tor to the controller
73 Reply = SyncReply / AsyncReply
74 SyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
75 AsyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
77 MidReplyLine = StatusCode "-" ReplyLine
78 DataReplyLine = StatusCode "+" ReplyLine Data
79 EndReplyLine = StatusCode SP ReplyLine
80 ReplyLine = [ReplyText] CRLF
84 Specific replies are mentioned below in section 3, and described more fully
87 [Compatibility note: versions of Tor before 0.2.0.3-alpha sometimes
88 generate AsyncReplies of the form "*(MidReplyLine / DataReplyLine)".
89 This is incorrect, but controllers that need to work with these
90 versions of Tor should be prepared to get multi-line AsyncReplies with
91 the final line (usually "650 OK") omitted.]
93 2.4. General-use tokens
95 ; CRLF means, "the ASCII Carriage Return character (decimal value 13)
96 ; followed by the ASCII Linefeed character (decimal value 10)."
99 ; How a controller tells Tor about a particular OR. There are four
101 ; $Fingerprint -- The router whose identity key hashes to the fingerprint.
102 ; This is the preferred way to refer to an OR.
103 ; $Fingerprint~Nickname -- The router whose identity key hashes to the
104 ; given fingerprint, but only if the router has the given nickname.
105 ; $Fingerprint=Nickname -- The router whose identity key hashes to the
106 ; given fingerprint, but only if the router is Named and has the given
108 ; Nickname -- The Named router with the given nickname, or, if no such
109 ; router exists, any router whose nickname matches the one given.
110 ; This is not a safe way to refer to routers, since Named status
111 ; could under some circumstances change over time.
113 ; The tokens that implement the above follow:
115 ServerSpec = LongName / Nickname
116 LongName = Fingerprint [ ( "=" / "~" ) Nickname ]
118 Fingerprint = "$" 40*HEXDIG
119 NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
120 Nickname = 1*19 NicknameChar
122 ; What follows is an outdated way to refer to ORs.
123 ; Feature VERBOSE_NAMES replaces ServerID with LongName in events and
124 ; GETINFO results. VERBOSE_NAMES can be enabled starting in Tor version
125 ; 0.1.2.2-alpha and it is always-on in 0.2.2.1-alpha and later.
126 ServerID = Nickname / Fingerprint
129 ; Unique identifiers for streams or circuits. Currently, Tor only
130 ; uses digits, but this may change
131 StreamID = 1*16 IDChar
132 CircuitID = 1*16 IDChar
133 IDChar = ALPHA / DIGIT
135 Address = ip4-address / ip6-address / hostname (XXXX Define these)
137 ; A "Data" section is a sequence of octets concluded by the terminating
138 ; sequence CRLF "." CRLF. The terminating sequence may not appear in the
139 ; body of the data. Leading periods on lines in the data are escaped with
140 ; an additional leading period as in RFC 2821 section 4.5.2.
141 Data = *DataLine "." CRLF
142 DataLine = CRLF / "." 1*LineItem CRLF / NonDotItem *LineItem CRLF
143 LineItem = NonCR / 1*CR NonCRLF
144 NonDotItem = NonDotCR / 1*CR NonCRLF
148 All commands are case-insensitive, but most keywords are case-sensitive.
152 Change the value of one or more configuration variables. The syntax is:
154 "SETCONF" 1*(SP keyword ["=" value]) CRLF
155 value = String / QuotedString
157 Tor behaves as though it had just read each of the key-value pairs
158 from its configuration file. Keywords with no corresponding values have
159 their configuration values reset to 0 or NULL (use RESETCONF if you want
160 to set it back to its default). SETCONF is all-or-nothing: if there
161 is an error in any of the configuration settings, Tor sets none of them.
163 Tor responds with a "250 configuration values set" reply on success.
164 If some of the listed keywords can't be found, Tor replies with a
165 "552 Unrecognized option" message. Otherwise, Tor responds with a
166 "513 syntax error in configuration values" reply on syntax error, or a
167 "553 impossible configuration setting" reply on a semantic error.
169 When a configuration option takes multiple values, or when multiple
170 configuration keys form a context-sensitive group (see GETCONF below), then
171 setting _any_ of the options in a SETCONF command is taken to reset all of
172 the others. For example, if two ORBindAddress values are configured, and a
173 SETCONF command arrives containing a single ORBindAddress value, the new
174 command's value replaces the two old values.
176 Sometimes it is not possible to change configuration options solely by
177 issuing a series of SETCONF commands, because the value of one of the
178 configuration options depends on the value of another which has not yet
179 been set. Such situations can be overcome by setting multiple configuration
180 options with a single SETCONF command (e.g. SETCONF ORPort=443
181 ORListenAddress=9001).
185 Remove all settings for a given configuration option entirely, assign
186 its default value (if any), and then assign the String provided.
187 Typically the String is left empty, to simply set an option back to
188 its default. The syntax is:
190 "RESETCONF" 1*(SP keyword ["=" String]) CRLF
192 Otherwise it behaves like SETCONF above.
196 Request the value of a configuration variable. The syntax is:
198 "GETCONF" 1*(SP keyword) CRLF
200 If all of the listed keywords exist in the Tor configuration, Tor replies
201 with a series of reply lines of the form:
203 If any option is set to a 'default' value semantically different from an
204 empty string, Tor may reply with a reply line of the form:
207 Value may be a raw value or a quoted string. Tor will try to use
208 unquoted values except when the value could be misinterpreted through
211 If some of the listed keywords can't be found, Tor replies with a
212 "552 unknown configuration keyword" message.
214 If an option appears multiple times in the configuration, all of its
215 key-value pairs are returned in order.
217 Some options are context-sensitive, and depend on other options with
218 different keywords. These cannot be fetched directly. Currently there
219 is only one such option: clients should use the "HiddenServiceOptions"
220 virtual keyword to get all HiddenServiceDir, HiddenServicePort,
221 HiddenServiceNodes, and HiddenServiceExcludeNodes option settings.
225 Request the server to inform the client about interesting events. The
228 "SETEVENTS" [SP "EXTENDED"] *(SP EventCode) CRLF
230 EventCode = "CIRC" / "STREAM" / "ORCONN" / "BW" / "DEBUG" /
231 "INFO" / "NOTICE" / "WARN" / "ERR" / "NEWDESC" / "ADDRMAP" /
232 "AUTHDIR_NEWDESCS" / "DESCCHANGED" / "STATUS_GENERAL" /
233 "STATUS_CLIENT" / "STATUS_SERVER" / "GUARD" / "NS" / "STREAM_BW" /
234 "CLIENTS_SEEN" / "NEWCONSENSUS" / "BUILDTIMEOUT_SET"
236 Any events *not* listed in the SETEVENTS line are turned off; thus, sending
237 SETEVENTS with an empty body turns off all event reporting.
239 The server responds with a "250 OK" reply on success, and a "552
240 Unrecognized event" reply if one of the event codes isn't recognized. (On
241 error, the list of active event codes isn't changed.)
243 If the flag string "EXTENDED" is provided, Tor may provide extra
244 information with events for this connection; see 4.1 for more information.
245 NOTE: All events on a given connection will be provided in extended format,
247 NOTE: "EXTENDED" is only supported in Tor 0.1.1.9-alpha or later.
249 Each event is described in more detail in Section 4.1.
253 Sent from the client to the server. The syntax is:
254 "AUTHENTICATE" [ SP 1*HEXDIG / QuotedString ] CRLF
256 The server responds with "250 OK" on success or "515 Bad authentication" if
257 the authentication cookie is incorrect. Tor closes the connection on an
258 authentication failure.
260 The format of the 'cookie' is implementation-dependent; see 5.1 below for
261 information on how the standard Tor implementation handles it.
263 Before the client has authenticated, no command other than PROTOCOLINFO,
264 AUTHENTICATE, or QUIT is valid. If the controller sends any other command,
265 or sends a malformed command, or sends an unsuccessful AUTHENTICATE
266 command, or sends PROTOCOLINFO more than once, Tor sends an error reply and
267 closes the connection.
269 To prevent some cross-protocol attacks, the AUTHENTICATE command is still
270 required even if all authentication methods in Tor are disabled. In this
271 case, the controller should just send "AUTHENTICATE" CRLF.
273 (Versions of Tor before 0.1.2.16 and 0.2.0.4-alpha did not close the
274 connection after an authentication failure.)
278 Sent from the client to the server. The syntax is:
281 Instructs the server to write out its config options into its torrc. Server
282 returns "250 OK" if successful, or "551 Unable to write configuration
283 to disk" if it can't write the file or some other error occurs.
285 See also the "getinfo config-text" command, if the controller wants
286 to write the torrc file itself.
290 Sent from the client to the server. The syntax is:
292 "SIGNAL" SP Signal CRLF
294 Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" /
295 "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" /
298 The meaning of the signals are:
300 RELOAD -- Reload: reload config items, refetch directory. (like HUP)
301 SHUTDOWN -- Controlled shutdown: if server is an OP, exit immediately.
302 If it's an OR, close listeners and exit after 30 seconds.
304 DUMP -- Dump stats: log information about open connections and
305 circuits. (like USR1)
306 DEBUG -- Debug: switch all open logs to loglevel debug. (like USR2)
307 HALT -- Immediate shutdown: clean up and exit now. (like TERM)
308 CLEARDNSCACHE -- Forget the client-side cached IPs for all hostnames.
309 NEWNYM -- Switch to clean circuits, so new application requests
310 don't share any circuits with old ones. Also clears
311 the client-side DNS cache. (Tor MAY rate-limit its
312 response to this signal.)
314 The server responds with "250 OK" if the signal is recognized (or simply
315 closes the socket if it was asked to close immediately), or "552
316 Unrecognized signal" if the signal is unrecognized.
320 Sent from the client to the server. The syntax is:
322 "MAPADDRESS" 1*(Address "=" Address SP) CRLF
324 The first address in each pair is an "original" address; the second is a
325 "replacement" address. The client sends this message to the server in
326 order to tell it that future SOCKS requests for connections to the original
327 address should be replaced with connections to the specified replacement
328 address. If the addresses are well-formed, and the server is able to
329 fulfill the request, the server replies with a 250 message:
330 250-OldAddress1=NewAddress1
331 250 OldAddress2=NewAddress2
333 containing the source and destination addresses. If request is
334 malformed, the server replies with "512 syntax error in command
335 argument". If the server can't fulfill the request, it replies with
336 "451 resource exhausted".
338 The client may decline to provide a body for the original address, and
339 instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
340 "." for hostname), signifying that the server should choose the original
341 address itself, and return that address in the reply. The server
342 should ensure that it returns an element of address space that is unlikely
343 to be in actual use. If there is already an address mapped to the
344 destination address, the server may reuse that mapping.
346 If the original address is already mapped to a different address, the old
347 mapping is removed. If the original address and the destination address
348 are the same, the server removes any mapping in place for the original
352 C: MAPADDRESS 0.0.0.0=torproject.org 1.2.3.4=tor.freehaven.net
353 S: 250-127.192.10.10=torproject.org
354 S: 250 1.2.3.4=tor.freehaven.net
356 {Note: This feature is designed to be used to help Tor-ify applications
357 that need to use SOCKS4 or hostname-less SOCKS5. There are three
358 approaches to doing this:
359 1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
360 2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
361 feature) to resolve the hostname remotely. This doesn't work
362 with special addresses like x.onion or x.y.exit.
363 3. Use MAPADDRESS to map an IP address to the desired hostname, and then
364 arrange to fool the application into thinking that the hostname
365 has resolved to that IP.
366 This functionality is designed to help implement the 3rd approach.}
368 Mappings set by the controller last until the Tor process exits:
369 they never expire. If the controller wants the mapping to last only
370 a certain time, then it must explicitly un-map the address when that
375 Sent from the client to the server. The syntax is as for GETCONF:
376 "GETINFO" 1*(SP keyword) CRLF
377 one or more NL-terminated strings. The server replies with an INFOVALUE
378 message, or a 551 or 552 error.
380 Unlike GETCONF, this message is used for data that are not stored in the Tor
381 configuration file, and that may be longer than a single line. On success,
382 one ReplyLine is sent for each requested value, followed by a final 250 OK
383 ReplyLine. If a value fits on a single line, the format is:
385 If a value must be split over multiple lines, the format is:
389 Recognized keys and their values include:
391 "version" -- The version of the server's software, including the name
392 of the software. (example: "Tor 0.0.9.4")
394 "config-file" -- The location of Tor's configuration file ("torrc").
396 "config-text" -- The contents that Tor would write if you send it
397 a SAVECONF command, so the controller can write the file to
398 disk itself. [First implemented in 0.2.2.7-alpha.]
400 ["exit-policy/prepend" -- The default exit policy lines that Tor will
401 *prepend* to the ExitPolicy config option.
402 -- Never implemented. Useful?]
404 "exit-policy/default" -- The default exit policy lines that Tor will
405 *append* to the ExitPolicy config option.
407 "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest
408 server descriptor for a given OR, NUL-terminated.
410 "desc-annotations/id/<OR identity>" -- outputs the annotations string
411 (source, timestamp of arrival, purpose, etc) for the corresponding
412 descriptor. [First implemented in 0.2.0.13-alpha.]
414 "extra-info/digest/<digest>" -- the extrainfo document whose digest (in
415 hex) is <digest>. Only available if we're downloading extra-info
418 "ns/id/<OR identity>" or "ns/name/<OR nickname>" -- the latest router
419 status info (v2 directory style) for a given OR. Router status
421 dir-spec.txt, and reflects the current beliefs of this Tor about the
422 router in question. Like directory clients, controllers MUST
423 tolerate unrecognized flags and lines. The published date and
424 descriptor digest are those believed to be best by this Tor,
425 not necessarily those for a descriptor that Tor currently has.
426 [First implemented in 0.1.2.3-alpha.]
428 "ns/all" -- Router status info (v2 directory style) for all ORs we
429 have an opinion about, joined by newlines. [First implemented
432 "ns/purpose/<purpose>" -- Router status info (v2 directory style)
433 for all ORs of this purpose. Mostly designed for /ns/purpose/bridge
434 queries. [First implemented in 0.2.0.13-alpha.]
436 "desc/all-recent" -- the latest server descriptor for every router that
439 "network-status" -- a space-separated list (v1 directory style)
440 of all known OR identities. This is in the same format as the
441 router-status line in v1 directories; see dir-spec-v1.txt section
442 3 for details. (If VERBOSE_NAMES is enabled, the output will
443 not conform to dir-spec-v1.txt; instead, the result will be a
444 space-separated list of LongName, each preceded by a "!" if it is
445 believed to be not running.) This option is deprecated; use
448 "address-mappings/all"
449 "address-mappings/config"
450 "address-mappings/cache"
451 "address-mappings/control" -- a \r\n-separated list of address
452 mappings, each in the form of "from-address to-address expiry".
453 The 'config' key returns those address mappings set in the
454 configuration; the 'cache' key returns the mappings in the
455 client-side DNS cache; the 'control' key returns the mappings set
456 via the control interface; the 'all' target returns the mappings
457 set through any mechanism.
458 Expiry is formatted as with ADDRMAP events, except that "expiry" is
459 always a time in GMT or the string "NEVER"; see section 4.1.7.
460 First introduced in 0.2.0.3-alpha.
462 "addr-mappings/*" -- as for address-mappings/*, but without the
463 expiry portion of the value. Use of this value is deprecated
464 since 0.2.0.3-alpha; use address-mappings instead.
466 "address" -- the best guess at our external IP address. If we
467 have no guess, return a 551 error. (Added in 0.1.2.2-alpha)
469 "fingerprint" -- the contents of the fingerprint file that Tor
470 writes as a server, or a 551 if we're not a server currently.
471 (Added in 0.1.2.3-alpha)
474 A series of lines as for a circuit status event. Each line is of
476 CircuitID SP CircStatus [SP Path] CRLF
479 A series of lines as for a stream status event. Each is of the form:
480 StreamID SP StreamStatus SP CircID SP Target CRLF
483 A series of lines as for an OR connection status event. In Tor
484 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
485 0.2.2.1-alpha and later by default, each line is of the form:
486 LongName SP ORStatus CRLF
488 In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
489 VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line
491 ServerID SP ORStatus CRLF
494 A series of lines listing the currently chosen entry guards, if any.
495 In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor
496 0.2.2.1-alpha and later by default, each line is of the form:
497 LongName SP Status [SP ISOTime] CRLF
499 In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
500 VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line
502 ServerID2 SP Status [SP ISOTime] CRLF
503 ServerID2 = Nickname / 40*HEXDIG
505 The definition of Status is the same for both:
506 Status = "up" / "never-connected" / "down" /
507 "unusable" / "unlisted"
509 [From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called
510 "helper-nodes". Tor still supports calling "helper-nodes", but it
511 is deprecated and should not be used.]
513 [Older versions of Tor (before 0.1.2.x-final) generated 'down' instead
514 of unlisted/unusable. Current Tors never generate 'down'.]
516 [XXXX ServerID2 differs from ServerID in not prefixing fingerprints
517 with a $. This is an implementation error. It would be nice to add
518 the $ back in if we can do so without breaking compatibility.]
521 "accounting/hibernating"
523 "accounting/bytes-left"
524 "accounting/interval-start"
525 "accounting/interval-wake"
526 "accounting/interval-end"
527 Information about accounting status. If accounting is enabled,
528 "enabled" is 1; otherwise it is 0. The "hibernating" field is "hard"
529 if we are accepting no data; "soft" if we're accepting no new
530 connections, and "awake" if we're not hibernating at all. The "bytes"
531 and "bytes-left" fields contain (read-bytes SP write-bytes), for the
532 start and the rest of the interval respectively. The 'interval-start'
533 and 'interval-end' fields are the borders of the current interval; the
534 'interval-wake' field is the time within the current interval (if any)
535 where we plan[ned] to start being active. The times are GMT.
538 A series of lines listing the available configuration options. Each is
540 OptionName SP OptionType [ SP Documentation ] CRLF
542 OptionType = "Integer" / "TimeInterval" / "DataSize" / "Float" /
543 "Boolean" / "Time" / "CommaList" / "Dependant" / "Virtual" /
544 "String" / "LineList"
548 A series of lines listing the available GETINFO options. Each is of
550 OptionName SP Documentation CRLF
551 OptionPrefix SP Documentation CRLF
552 OptionPrefix = OptionName "/*"
555 A space-separated list of all the events supported by this version of
559 A space-separated list of all the events supported by this version of
563 Maps IP addresses to 2-letter country codes. For example,
564 "GETINFO ip-to-country/18.0.0.1" should give "US".
566 "next-circuit/IP:port"
569 "dir/status-vote/current/consensus" [added in Tor 0.2.1.6-alpha]
570 "dir/status/authority"
572 "dir/status/fp/<F1>+<F2>+<F3>"
575 "dir/server/fp/<F1>+<F2>+<F3>"
577 "dir/server/d/<D1>+<D2>+<D3>"
578 "dir/server/authority"
580 A series of lines listing directory contents, provided according to the
581 specification for the URLs listed in Section 4.4 of dir-spec.txt. Note
582 that Tor MUST NOT provide private information, such as descriptors for
583 routers not marked as general-purpose. When asked for 'authority'
584 information for which this Tor is not authoritative, Tor replies with
587 "status/circuit-established"
588 "status/enough-dir-info"
589 "status/good-server-descriptor"
590 "status/accepted-server-descriptor"
592 These provide the current internal Tor values for various Tor
593 states. See Section 4.1.10 for explanations. (Only a few of the
594 status events are available as getinfo's currently. Let us know if
595 you want more exposed.)
596 "status/reachability-succeeded/or"
597 0 or 1, depending on whether we've found our ORPort reachable.
598 "status/reachability-succeeded/dir"
599 0 or 1, depending on whether we've found our DirPort reachable.
600 "status/reachability-succeeded"
601 "OR=" ("0"/"1") SP "DIR=" ("0"/"1")
602 Combines status/reachability-succeeded/*; controllers MUST ignore
603 unrecognized elements in this entry.
604 "status/bootstrap-phase"
605 Returns the most recent bootstrap phase status event
606 sent. Specifically, it returns a string starting with either
607 "NOTICE BOOTSTRAP ..." or "WARN BOOTSTRAP ...". Controllers should
608 use this getinfo when they connect or attach to Tor to learn its
609 current bootstrap state.
610 "status/version/recommended"
611 List of currently recommended versions.
612 "status/version/current"
613 Status of the current version. One of: new, old, unrecommended,
614 recommended, new in series, obsolete, unknown.
615 "status/clients-seen"
616 A summary of which countries we've seen clients from recently,
617 formatted the same as the CLIENTS_SEEN status event described in
618 Section 4.1.14. This GETINFO option is currently available only
622 C: GETINFO version desc/name/moria1
623 S: 250+desc/name/moria=
624 S: [Descriptor for moria]
626 S: 250-version=Tor 0.1.1.0-alpha-cvs
631 Sent from the client to the server. The format is:
632 "EXTENDCIRCUIT" SP CircuitID
633 [SP ServerSpec *("," ServerSpec)
634 SP "purpose=" Purpose] CRLF
636 This request takes one of two forms: either the CircuitID is zero, in
637 which case it is a request for the server to build a new circuit,
638 or the CircuitID is nonzero, in which case it is a request for the
639 server to extend an existing circuit with that ID according to the
642 If the CircuitID is 0, the controller has the option of providing
643 a path for Tor to use to build the circuit. If it does not provide
644 a path, Tor will select one automatically from high capacity nodes
645 according to path-spec.txt.
647 If CircuitID is 0 and "purpose=" is specified, then the circuit's
648 purpose is set. Two choices are recognized: "general" and
649 "controller". If not specified, circuits are created as "general".
651 If the request is successful, the server sends a reply containing a
652 message body consisting of the CircuitID of the (maybe newly created)
653 circuit. The syntax is "250" SP "EXTENDED" SP CircuitID CRLF.
655 3.11. SETCIRCUITPURPOSE
657 Sent from the client to the server. The format is:
658 "SETCIRCUITPURPOSE" SP CircuitID SP Purpose CRLF
660 This changes the circuit's purpose. See EXTENDCIRCUIT above for details.
662 3.12. SETROUTERPURPOSE
664 Sent from the client to the server. The format is:
665 "SETROUTERPURPOSE" SP NicknameOrKey SP Purpose CRLF
667 This changes the descriptor's purpose. See +POSTDESCRIPTOR below
670 NOTE: This command was disabled and made obsolete as of Tor
671 0.2.0.8-alpha. It doesn't exist anymore, and is listed here only for
676 Sent from the client to the server. The syntax is:
677 "ATTACHSTREAM" SP StreamID SP CircuitID [SP "HOP=" HopNum] CRLF
679 This message informs the server that the specified stream should be
680 associated with the specified circuit. Each stream may be associated with
681 at most one circuit, and multiple streams may share the same circuit.
682 Streams can only be attached to completed circuits (that is, circuits that
683 have sent a circuit status 'BUILT' event or are listed as built in a
684 GETINFO circuit-status request).
686 If the circuit ID is 0, responsibility for attaching the given stream is
689 If HOP=HopNum is specified, Tor will choose the HopNumth hop in the
690 circuit as the exit node, rather than the last node in the circuit.
691 Hops are 1-indexed; generally, it is not permitted to attach to hop 1.
693 Tor responds with "250 OK" if it can attach the stream, 552 if the circuit
694 or stream didn't exist, or 551 if the stream couldn't be attached for
697 {Implementation note: Tor will close unattached streams by itself,
698 roughly two minutes after they are born. Let the developers know if
699 that turns out to be a problem.}
701 {Implementation note: By default, Tor automatically attaches streams to
702 circuits itself, unless the configuration variable
703 "__LeaveStreamsUnattached" is set to "1". Attempting to attach streams
704 via TC when "__LeaveStreamsUnattached" is false may cause a race between
705 Tor and the controller, as both attempt to attach streams to circuits.}
707 {Implementation note: You can try to attachstream to a stream that
708 has already sent a connect or resolve request but hasn't succeeded
709 yet, in which case Tor will detach the stream from its current circuit
710 before proceeding with the new attach request.}
714 Sent from the client to the server. The syntax is:
715 "+POSTDESCRIPTOR" [SP "purpose=" Purpose] [SP "cache=" Cache]
716 CRLF Descriptor CRLF "." CRLF
718 This message informs the server about a new descriptor. If Purpose is
719 specified, it must be either "general", "controller", or "bridge",
720 else we return a 552 error. The default is "general".
722 If Cache is specified, it must be either "no" or "yes", else we
723 return a 552 error. If Cache is not specified, Tor will decide for
724 itself whether it wants to cache the descriptor, and controllers
725 must not rely on its choice.
727 The descriptor, when parsed, must contain a number of well-specified
728 fields, including fields for its nickname and identity.
730 If there is an error in parsing the descriptor, the server must send a
731 "554 Invalid descriptor" reply. If the descriptor is well-formed but
732 the server chooses not to add it, it must reply with a 251 message
733 whose body explains why the server was not added. If the descriptor
734 is added, Tor replies with "250 OK".
738 Sent from the client to the server. The syntax is:
739 "REDIRECTSTREAM" SP StreamID SP Address [SP Port] CRLF
741 Tells the server to change the exit address on the specified stream. If
742 Port is specified, changes the destination port as well. No remapping
743 is performed on the new provided address.
745 To be sure that the modified address will be used, this event must be sent
746 after a new stream event is received, and before attaching this stream to
749 Tor replies with "250 OK" on success.
753 Sent from the client to the server. The syntax is:
755 "CLOSESTREAM" SP StreamID SP Reason *(SP Flag) CRLF
757 Tells the server to close the specified stream. The reason should be one
758 of the Tor RELAY_END reasons given in tor-spec.txt, as a decimal. Flags is
759 not used currently; Tor servers SHOULD ignore unrecognized flags. Tor may
760 hold the stream open for a while to flush any data that is pending.
762 Tor replies with "250 OK" on success, or a 512 if there aren't enough
763 arguments, or a 552 if it doesn't recognize the StreamID or reason.
768 CLOSECIRCUIT SP CircuitID *(SP Flag) CRLF
771 Tells the server to close the specified circuit. If "IfUnused" is
772 provided, do not close the circuit unless it is unused.
774 Other flags may be defined in the future; Tor SHOULD ignore unrecognized
777 Tor replies with "250 OK" on success, or a 512 if there aren't enough
778 arguments, or a 552 if it doesn't recognize the CircuitID.
782 Tells the server to hang up on this controller connection. This command
783 can be used before authenticating.
787 Adding additional features to the control protocol sometimes will break
788 backwards compatibility. Initially such features are added into Tor and
789 disabled by default. USEFEATURE can enable these additional features.
793 "USEFEATURE" *(SP FeatureName) CRLF
794 FeatureName = 1*(ALPHA / DIGIT / "_" / "-")
796 Feature names are case-insensitive.
798 Once enabled, a feature stays enabled for the duration of the connection
799 to the controller. A new connection to the controller must be opened to
800 disable an enabled feature.
802 Features are a forward-compatibility mechanism; each feature will eventually
803 become a standard part of the control protocol. Once a feature becomes part
804 of the protocol, it is always-on. Each feature documents the version it was
805 introduced as a feature and the version in which it became part of the
808 Tor will ignore a request to use any feature that is always-on. Tor will give
809 a 552 error in response to an unrecognized feature.
813 Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to
814 request the extended event syntax.
816 This feature was first introduced in 0.1.2.3-alpha. It is always-on
817 and part of the protocol in Tor 0.2.2.1-alpha and later.
821 Replaces ServerID with LongName in events and GETINFO results. LongName
822 provides a Fingerprint for all routers, an indication of Named status,
823 and a Nickname if one is known. LongName is strictly more informative
824 than ServerID, which only provides either a Fingerprint or a Nickname.
826 This feature was first introduced in 0.1.2.2-alpha. It is always-on and
827 part of the protocol in Tor 0.2.2.1-alpha and later.
832 "RESOLVE" *Option *Address CRLF
833 Option = "mode=reverse"
834 Address = a hostname or IPv4 address
836 This command launches a remote hostname lookup request for every specified
837 request (or reverse lookup if "mode=reverse" is specified). Note that the
838 request is done in the background: to see the answers, your controller will
839 need to listen for ADDRMAP events; see 4.1.7 below.
841 [Added in Tor 0.2.0.3-alpha]
846 "PROTOCOLINFO" *(SP PIVERSION) CRLF
848 The server reply format is:
849 "250-PROTOCOLINFO" SP PIVERSION CRLF *InfoLine "250 OK" CRLF
851 InfoLine = AuthLine / VersionLine / OtherLine
853 AuthLine = "250-AUTH" SP "METHODS=" AuthMethod *(",")AuthMethod
854 *(SP "COOKIEFILE=" AuthCookieFile) CRLF
855 VersionLine = "250-VERSION" SP "Tor=" TorVersion [SP Arguments] CRLF
858 "NULL" / ; No authentication is required
859 "HASHEDPASSWORD" / ; A controller must supply the original password
860 "COOKIE" / ; A controller must supply the contents of a cookie
862 AuthCookieFile = QuotedString
863 TorVersion = QuotedString
865 OtherLine = "250-" Keyword [SP Arguments] CRLF
869 Tor MAY give its InfoLines in any order; controllers MUST ignore InfoLines
870 with keywords they do not recognize. Controllers MUST ignore extraneous
871 data on any InfoLine.
873 PIVERSION is there in case we drastically change the syntax one day. For
874 now it should always be "1". Controllers MAY provide a list of the
875 protocolinfo versions they support; Tor MAY select a version that the
876 controller does not support.
878 AuthMethod is used to specify one or more control authentication
879 methods that Tor currently accepts.
881 AuthCookieFile specifies the absolute path and filename of the
882 authentication cookie that Tor is expecting and is provided iff
883 the METHODS field contains the method "COOKIE". Controllers MUST handle
884 escape sequences inside this string.
886 The VERSION line contains the Tor version.
888 [Unlike other commands besides AUTHENTICATE, PROTOCOLINFO may be used (but
889 only once!) before AUTHENTICATE.]
891 [PROTOCOLINFO was not supported before Tor 0.2.0.5-alpha.]
895 Reply codes follow the same 3-character format as used by SMTP, with the
896 first character defining a status, the second character defining a
897 subsystem, and the third designating fine-grained information.
899 The TC protocol currently uses the following first characters:
901 2yz Positive Completion Reply
902 The command was successful; a new request can be started.
904 4yz Temporary Negative Completion reply
905 The command was unsuccessful but might be reattempted later.
907 5yz Permanent Negative Completion Reply
908 The command was unsuccessful; the client should not try exactly
909 that sequence of commands again.
911 6yz Asynchronous Reply
912 Sent out-of-order in response to an earlier SETEVENTS command.
914 The following second characters are used:
917 Sent in response to ill-formed or nonsensical commands.
920 Refers to operations of the Tor Control protocol.
923 Refers to actual operations of Tor system.
925 The following codes are defined:
928 251 Operation was unnecessary
929 [Tor has declined to perform the operation, but no harm was done.]
931 451 Resource exhausted
933 500 Syntax error: protocol
935 510 Unrecognized command
936 511 Unimplemented command
937 512 Syntax error in command argument
938 513 Unrecognized command argument
939 514 Authentication required
940 515 Bad authentication
942 550 Unspecified Tor error
945 [Something went wrong inside Tor, so that the client's
946 request couldn't be fulfilled.]
948 552 Unrecognized entity
949 [A configuration key, a stream ID, circuit ID, event,
950 mentioned in the command did not actually exist.]
952 553 Invalid configuration value
953 [The client tried to set a configuration option to an
954 incorrect, ill-formed, or impossible value.]
956 554 Invalid descriptor
960 650 Asynchronous event notification
962 Unless specified to have specific contents, the human-readable messages
963 in error replies should not be relied upon to match those in this document.
965 4.1. Asynchronous events
967 These replies can be sent after a corresponding SETEVENTS command has been
968 received. They will not be interleaved with other Reply elements, but they
969 can appear between a command and its corresponding reply. For example,
970 this sequence is possible:
974 C: GETCONF SOCKSPORT ORPORT
975 S: 650 CIRC 1000 EXTENDED moria1,moria2
976 S: 250-SOCKSPORT=9050
979 But this sequence is disallowed:
982 C: GETCONF SOCKSPORT ORPORT
983 S: 250-SOCKSPORT=9050
984 S: 650 CIRC 1000 EXTENDED moria1,moria2
987 Clients MUST tolerate more arguments in an asynchonous reply than
988 expected, and MUST tolerate more lines in an asynchronous reply than
989 expected. For instance, a client that expects a CIRC message like:
990 650 CIRC 1000 EXTENDED moria1,moria2
992 650-CIRC 1000 EXTENDED moria1,moria2 0xBEEF
996 If clients ask for extended events, then each event line as specified below
997 will be followed by additional extensions. Additional lines will be of the
999 "650" ("-"/" ") KEYWORD ["=" ARGUMENTS] CRLF
1000 Additional arguments will be of the form
1001 SP KEYWORD ["=" ( QuotedString / * NonSpDquote ) ]
1002 Such clients MUST tolerate lines with keywords they do not recognize.
1004 4.1.1. Circuit status changed
1008 "650" SP "CIRC" SP CircuitID SP CircStatus [SP Path]
1009 [SP "REASON=" Reason [SP "REMOTE_REASON=" Reason]] CRLF
1012 "LAUNCHED" / ; circuit ID assigned to new circuit
1013 "BUILT" / ; all hops finished, can now accept streams
1014 "EXTENDED" / ; one more hop has been completed
1015 "FAILED" / ; circuit closed (was not built)
1016 "CLOSED" ; circuit closed (was built)
1018 Path = LongName *("," LongName)
1019 ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
1020 ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, Path
1022 Path = ServerID *("," ServerID)
1024 Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" /
1025 "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" /
1026 "OR_IDENTITY" / "OR_CONN_CLOSED" / "TIMEOUT" /
1027 "FINISHED" / "DESTROYED" / "NOPATH" / "NOSUCHSERVICE" /
1028 "MEASUREMENT_EXPIRED"
1030 The path is provided only when the circuit has been extended at least one
1033 The "REASON" field is provided only for FAILED and CLOSED events, and only
1034 if extended events are enabled (see 3.19). Clients MUST accept reasons
1035 not listed above. Reasons are as given in tor-spec.txt, except for:
1037 NOPATH (Not enough nodes to make circuit)
1039 The "REMOTE_REASON" field is provided only when we receive a DESTROY or
1040 TRUNCATE cell, and only if extended events are enabled. It contains the
1041 actual reason given by the remote OR for closing the circuit. Clients MUST
1042 accept reasons not listed above. Reasons are as listed in tor-spec.txt.
1044 4.1.2. Stream status changed
1048 "650" SP "STREAM" SP StreamID SP StreamStatus SP CircID SP Target
1049 [SP "REASON=" Reason [ SP "REMOTE_REASON=" Reason ]]
1050 [SP "SOURCE=" Source] [ SP "SOURCE_ADDR=" Address ":" Port ]
1051 [SP "PURPOSE=" Purpose]
1055 "NEW" / ; New request to connect
1056 "NEWRESOLVE" / ; New request to resolve an address
1057 "REMAP" / ; Address re-mapped to another
1058 "SENTCONNECT" / ; Sent a connect cell along a circuit
1059 "SENTRESOLVE" / ; Sent a resolve cell along a circuit
1060 "SUCCEEDED" / ; Received a reply; stream established
1061 "FAILED" / ; Stream failed and not retriable
1062 "CLOSED" / ; Stream closed
1063 "DETACHED" ; Detached from circuit; still retriable
1065 Target = Address ":" Port
1067 The circuit ID designates which circuit this stream is attached to. If
1068 the stream is unattached, the circuit ID "0" is given.
1070 Reason = "MISC" / "RESOLVEFAILED" / "CONNECTREFUSED" /
1071 "EXITPOLICY" / "DESTROY" / "DONE" / "TIMEOUT" /
1072 "NOROUTE" / "HIBERNATING" / "INTERNAL"/ "RESOURCELIMIT" /
1073 "CONNRESET" / "TORPROTOCOL" / "NOTDIRECTORY" / "END"
1075 The "REASON" field is provided only for FAILED, CLOSED, and DETACHED
1076 events, and only if extended events are enabled (see 3.19). Clients MUST
1077 accept reasons not listed above. Reasons are as given in tor-spec.txt,
1080 END (We received a RELAY_END cell from the other side of this
1082 [XXXX document more. -NM]
1084 The "REMOTE_REASON" field is provided only when we receive a RELAY_END
1085 cell, and only if extended events are enabled. It contains the actual
1086 reason given by the remote OR for closing the stream. Clients MUST accept
1087 reasons not listed above. Reasons are as listed in tor-spec.txt.
1089 "REMAP" events include a Source if extended events are enabled:
1090 Source = "CACHE" / "EXIT"
1091 Clients MUST accept sources not listed above. "CACHE" is given if
1092 the Tor client decided to remap the address because of a cached
1093 answer, and "EXIT" is given if the remote node we queried gave us
1094 the new address as a response.
1096 The "SOURCE_ADDR" field is included with NEW and NEWRESOLVE events if
1097 extended events are enabled. It indicates the address and port
1098 that requested the connection, and can be (e.g.) used to look up the
1101 Purpose = "DIR_FETCH" / "UPLOAD_DESC" / "DNS_REQUEST" /
1102 "USER" / "DIRPORT_TEST"
1104 The "PURPOSE" field is provided only for NEW and NEWRESOLVE events, and
1105 only if extended events are enabled (see 3.19). Clients MUST accept
1106 purposes not listed above.
1108 4.1.3. OR Connection status changed
1112 "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON="
1113 Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
1115 ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"
1117 ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
1118 ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, OR
1119 ; Connection is as follows:
1120 "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON="
1121 Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF
1123 NEW is for incoming connections, and LAUNCHED is for outgoing
1124 connections. CONNECTED means the TLS handshake has finished (in
1125 either direction). FAILED means a connection is being closed that
1126 hasn't finished its handshake, and CLOSED is for connections that
1129 A LongName or ServerID is specified unless it's a NEW connection, in
1130 which case we don't know what server it is yet, so we use Address:Port.
1132 If extended events are enabled (see 3.19), optional reason and
1133 circuit counting information is provided for CLOSED and FAILED
1136 Reason = "MISC" / "DONE" / "CONNECTREFUSED" /
1137 "IDENTITY" / "CONNECTRESET" / "TIMEOUT" / "NOROUTE" /
1138 "IOERROR" / "RESOURCELIMIT"
1140 NumCircuits counts both established and pending circuits.
1142 4.1.4. Bandwidth used in the last second
1145 "650" SP "BW" SP BytesRead SP BytesWritten *(SP Type "=" Num) CRLF
1147 BytesWritten = 1*DIGIT
1148 Type = "DIR" / "OR" / "EXIT" / "APP" / ...
1151 BytesRead and BytesWritten are the totals. [In a future Tor version,
1152 we may also include a breakdown of the connection types that used
1153 bandwidth this second (not implemented yet).]
1158 "650" SP Severity SP ReplyText CRLF
1160 "650+" Severity CRLF Data 650 SP "OK" CRLF
1162 Severity = "DEBUG" / "INFO" / "NOTICE" / "WARN"/ "ERR"
1164 4.1.6. New descriptors available
1167 "650" SP "NEWDESC" 1*(SP LongName) CRLF
1168 ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature
1169 ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, it
1171 "650" SP "NEWDESC" 1*(SP ServerID) CRLF
1173 4.1.7. New Address mapping
1176 "650" SP "ADDRMAP" SP Address SP NewAddress SP Expiry
1177 [SP Error] SP GMTExpiry CRLF
1179 NewAddress = Address / "<error>"
1180 Expiry = DQUOTE ISOTime DQUOTE / "NEVER"
1182 Error = "error=" ErrorCode
1184 GMTExpiry = "EXPIRES=" DQUOTE IsoTime DQUOTE
1186 Error and GMTExpiry are only provided if extended events are enabled.
1188 Expiry is expressed as the local time (rather than GMT). This is a bug,
1189 left in for backward compatibility; new code should look at GMTExpiry
1192 These events are generated when a new address mapping is entered in the
1193 cache, or when the answer for a RESOLVE command is found.
1195 4.1.8. Descriptors uploaded to us in our role as authoritative dirserver
1198 "650" "+" "AUTHDIR_NEWDESCS" CRLF Action CRLF Message CRLF
1199 Descriptor CRLF "." CRLF "650" SP "OK" CRLF
1200 Action = "ACCEPTED" / "DROPPED" / "REJECTED"
1203 4.1.9. Our descriptor changed
1206 "650" SP "DESCCHANGED" CRLF
1208 [First added in 0.1.2.2-alpha.]
1210 4.1.10. Status events
1212 Status events (STATUS_GENERAL, STATUS_CLIENT, and STATUS_SERVER) are sent
1213 based on occurrences in the Tor process pertaining to the general state of
1214 the program. Generally, they correspond to log messages of severity Notice
1215 or higher. They differ from log messages in that their format is a
1216 specified interface.
1219 "650" SP StatusType SP StatusSeverity SP StatusAction
1220 [SP StatusArguments] CRLF
1222 StatusType = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"
1223 StatusSeverity = "NOTICE" / "WARN" / "ERR"
1224 StatusAction = 1*ALPHA
1225 StatusArguments = StatusArgument *(SP StatusArgument)
1226 StatusArgument = StatusKeyword '=' StatusValue
1227 StatusKeyword = 1*(ALNUM / "_")
1228 StatusValue = 1*(ALNUM / '_') / QuotedString
1230 Action is a string, and Arguments is a series of keyword=value
1231 pairs on the same line. Values may be space-terminated strings,
1234 These events are always produced with EXTENDED_EVENTS and
1235 VERBOSE_NAMES; see the explanations in the USEFEATURE section
1238 Controllers MUST tolerate unrecognized actions, MUST tolerate
1239 unrecognized arguments, MUST tolerate missing arguments, and MUST
1240 tolerate arguments that arrive in any order.
1242 Each event description below is accompanied by a recommendation for
1243 controllers. These recommendations are suggestions only; no controller
1244 is required to implement them.
1246 Compatibility note: versions of Tor before 0.2.0.22-rc incorrectly
1247 generated "STATUS_SERVER" as "STATUS_SEVER". To be compatible with those
1248 versions, tools should accept both.
1250 Actions for STATUS_GENERAL events can be as follows:
1254 Tor spent enough time without CPU cycles that it has closed all
1255 its circuits and will establish them anew. This typically
1256 happens when a laptop goes to sleep and then wakes up again. It
1257 also happens when the system is swapping so heavily that Tor is
1258 starving. The "time" argument specifies the number of seconds Tor
1259 thinks it was unconscious for (or alternatively, the number of
1260 seconds it went back in time).
1262 This status event is sent as NOTICE severity normally, but WARN
1263 severity if Tor is acting as a server currently.
1265 {Recommendation for controller: ignore it, since we don't really
1266 know what the user should do anyway. Hm.}
1270 "REASON=NEW/OBSOLETE/UNRECOMMENDED"
1271 "RECOMMENDED=\"version, version, ...\""
1272 Tor has found that directory servers don't recommend its version of
1273 the Tor software. RECOMMENDED is a comma-and-space-separated string
1274 of Tor versions that are recommended. REASON is NEW if this version
1275 of Tor is newer than any recommended version, OBSOLETE if
1276 this version of Tor is older than any recommended version, and
1277 UNRECOMMENDED if some recommended versions of Tor are newer and
1278 some are older than this version. (The "OBSOLETE" reason was called
1279 "OLD" from Tor 0.1.2.3-alpha up to and including 0.2.0.12-alpha.)
1281 {Controllers may want to suggest that the user upgrade OLD or
1282 UNRECOMMENDED versions. NEW versions may be known-insecure, or may
1283 simply be development versions.}
1285 TOO_MANY_CONNECTIONS
1287 Tor has reached its ulimit -n or whatever the native limit is on file
1288 descriptors or sockets. CURRENT is the number of sockets Tor
1289 currently has open. The user should really do something about
1290 this. The "current" argument shows the number of connections currently
1293 {Controllers may recommend that the user increase the limit, or
1294 increase it for them. Recommendations should be phrased in an
1295 OS-appropriate way and automated when possible.}
1299 Tor has encountered a situation that its developers never expected,
1300 and the developers would like to learn that it happened. Perhaps
1301 the controller can explain this to the user and encourage her to
1304 {Controllers should log bugs, but shouldn't annoy the user in case a
1305 bug appears frequently.}
1308 SKEW="+" / "-" SECONDS
1309 MIN_SKEW="+" / "-" SECONDS.
1310 SOURCE="DIRSERV:" IP ":" Port /
1311 "NETWORKSTATUS:" IP ":" Port /
1314 If "SKEW" is present, it's an estimate of how far we are from the
1315 time declared in the source. (In other words, if we're an hour in
1316 the past, the value is -3600.) "MIN_SKEW" is present, it's a lower
1317 bound. If the source is a DIRSERV, we got the current time from a
1318 connection to a dirserver. If the source is a NETWORKSTATUS, we
1319 decided we're skewed because we got a v2 networkstatus from far in
1320 the future. If the source is OR, the skew comes from a NETINFO
1321 cell from a connection to another relay. If the source is
1322 CONSENSUS, we decided we're skewed because we got a networkstatus
1323 consensus from the future.
1325 {Tor should send this message to controllers when it thinks the
1326 skew is so high that it will interfere with proper Tor operation.
1327 Controllers shouldn't blindly adjust the clock, since the more
1328 accurate source of skew info (DIRSERV) is currently
1332 "METHOD=" libevent method
1333 "VERSION=" libevent version
1334 "BADNESS=" "BROKEN" / "BUGGY" / "SLOW"
1335 "RECOVERED=" "NO" / "YES"
1336 Tor knows about bugs in using the configured event method in this
1337 version of libevent. "BROKEN" libevents won't work at all;
1338 "BUGGY" libevents might work okay; "SLOW" libevents will work
1339 fine, but not quickly. If "RECOVERED" is YES, Tor managed to
1340 switch to a more reliable (but probably slower!) libevent method.
1342 {Controllers may want to warn the user if this event occurs, though
1343 generally it's the fault of whoever built the Tor binary and there's
1344 not much the user can do besides upgrade libevent or upgrade the
1348 Tor believes that none of the known directory servers are
1349 reachable -- this is most likely because the local network is
1350 down or otherwise not working, and might help to explain for the
1351 user why Tor appears to be broken.
1353 {Controllers may want to warn the user if this event occurs; further
1354 action is generally not possible.}
1357 Tor has received and validated a new consensus networkstatus.
1358 (This event can be delayed a little while after the consensus
1359 is received, if Tor needs to fetch certificates.)
1361 Actions for STATUS_CLIENT events can be as follows:
1370 "RECOMMENDATION=" Keyword
1373 Tor has made some progress at establishing a connection to the
1374 Tor network, fetching directory information, or making its first
1375 circuit; or it has encountered a problem while bootstrapping. This
1376 status event is especially useful for users with slow connections
1377 or with connectivity problems.
1379 "Progress" gives a number between 0 and 100 for how far through
1380 the bootstrapping process we are. "Summary" is a string that can
1381 be displayed to the user to describe the *next* task that Tor
1382 will tackle, i.e., the task it is working on after sending the
1383 status event. "Tag" is a string that controllers can use to
1384 recognize bootstrap phases, if they want to do something smarter
1385 than just blindly displaying the summary string; see Section 5
1386 for the current tags that Tor issues.
1388 The StatusSeverity describes whether this is a normal bootstrap
1389 phase (severity notice) or an indication of a bootstrapping
1390 problem (severity warn).
1392 For bootstrap problems, we include the same progress, tag, and
1393 summary values as we would for a normal bootstrap event, but we
1394 also include "warning", "reason", "count", and "recommendation"
1395 key/value combos. The "count" number tells how many bootstrap
1396 problems there have been so far at this phase. The "reason"
1397 string lists one of the reasons allowed in the ORCONN event. The
1398 "warning" argument string with any hints Tor has to offer about
1399 why it's having troubles bootstrapping.
1401 The "reason" values are long-term-stable controller-facing tags to
1402 identify particular issues in a bootstrapping step. The warning
1403 strings, on the other hand, are human-readable. Controllers
1404 SHOULD NOT rely on the format of any warning string. Currently
1405 the possible values for "recommendation" are either "ignore" or
1406 "warn" -- if ignore, the controller can accumulate the string in
1407 a pile of problems to show the user if the user asks; if warn,
1408 the controller should alert the user that Tor is pretty sure
1409 there's a bootstrapping problem.
1411 Currently Tor uses recommendation=ignore for the first
1412 nine bootstrap problem reports for a given phase, and then
1413 uses recommendation=warn for subsequent problems at that
1414 phase. Hopefully this is a good balance between tolerating
1415 occasional errors and reporting serious problems quickly.
1418 Tor now knows enough network-status documents and enough server
1419 descriptors that it's going to start trying to build circuits now.
1421 {Controllers may want to use this event to decide when to indicate
1422 progress to their users, but should not interrupt the user's browsing
1426 We discarded expired statuses and router descriptors to fall
1427 below the desired threshold of directory information. We won't
1428 try to build any circuits until ENOUGH_DIR_INFO occurs again.
1430 {Controllers may want to use this event to decide when to indicate
1431 progress to their users, but should not interrupt the user's browsing
1435 Tor is able to establish circuits for client use. This event will
1436 only be sent if we just built a circuit that changed our mind --
1437 that is, prior to this event we didn't know whether we could
1440 {Suggested use: controllers can notify their users that Tor is
1441 ready for use as a client once they see this status event. [Perhaps
1442 controllers should also have a timeout if too much time passes and
1443 this event hasn't arrived, to give tips on how to troubleshoot.
1444 On the other hand, hopefully Tor will send further status events
1445 if it can identify the problem.]}
1447 CIRCUIT_NOT_ESTABLISHED
1448 "REASON=" "EXTERNAL_ADDRESS" / "DIR_ALL_UNREACHABLE" / "CLOCK_JUMPED"
1449 We are no longer confident that we can build circuits. The "reason"
1450 keyword provides an explanation: which other status event type caused
1451 our lack of confidence.
1453 {Controllers may want to use this event to decide when to indicate
1454 progress to their users, but should not interrupt the user's browsing
1456 [Note: only REASON=CLOCK_JUMPED is implemented currently.]
1460 "RESULT=" "REJECT" / "WARN"
1461 A stream was initiated to a port that's commonly used for
1462 vulnerable-plaintext protocols. If the Result is "reject", we
1463 refused the connection; whereas if it's "warn", we allowed it.
1465 {Controllers should warn their users when this occurs, unless they
1466 happen to know that the application using Tor is in fact doing so
1467 correctly (e.g., because it is part of a distributed bundle). They
1468 might also want some sort of interface to let the user configure
1469 their RejectPlaintextPorts and WarnPlaintextPorts config options.}
1472 "PROTOCOL=" "SOCKS4" / "SOCKS5"
1474 A connection was made to Tor's SOCKS port using one of the SOCKS
1475 approaches that doesn't support hostnames -- only raw IP addresses.
1476 If the client application got this address from gethostbyname(),
1477 it may be leaking target addresses via DNS.
1479 {Controllers should warn their users when this occurs, unless they
1480 happen to know that the application using Tor is in fact doing so
1481 correctly (e.g., because it is part of a distributed bundle).}
1483 SOCKS_UNKNOWN_PROTOCOL
1485 A connection was made to Tor's SOCKS port that tried to use it
1486 for something other than the SOCKS protocol. Perhaps the user is
1487 using Tor as an HTTP proxy? The DATA is the first few characters
1488 sent to Tor on the SOCKS port.
1490 {Controllers may want to warn their users when this occurs: it
1491 indicates a misconfigured application.}
1494 "HOSTNAME=QuotedString"
1495 Some application gave us a funny-looking hostname. Perhaps
1496 it is broken? In any case it won't work with Tor and the user
1499 {Controllers may want to warn their users when this occurs: it
1500 usually indicates a misconfigured application.}
1502 Actions for STATUS_SERVER can be as follows:
1507 "METHOD=CONFIGURED/DIRSERV/RESOLVED/INTERFACE/GETHOSTNAME"
1508 Our best idea for our externally visible IP has changed to 'IP'.
1509 If 'HOSTNAME' is present, we got the new IP by resolving 'NAME'. If the
1510 method is 'CONFIGURED', the IP was given verbatim as a configuration
1511 option. If the method is 'RESOLVED', we resolved the Address
1512 configuration option to get the IP. If the method is 'GETHOSTNAME',
1513 we resolved our hostname to get the IP. If the method is 'INTERFACE',
1514 we got the address of one of our network interfaces to get the IP. If
1515 the method is 'DIRSERV', a directory server told us a guess for what
1518 {Controllers may want to record this info and display it to the user.}
1520 CHECKING_REACHABILITY
1522 "DIRADDRESS=IP:port"
1523 We're going to start testing the reachability of our external OR port
1526 {This event could affect the controller's idea of server status, but
1527 the controller should not interrupt the user to tell them so.}
1529 REACHABILITY_SUCCEEDED
1531 "DIRADDRESS=IP:port"
1532 We successfully verified the reachability of our external OR port or
1533 directory port (depending on which of ORADDRESS or DIRADDRESS is
1536 {This event could affect the controller's idea of server status, but
1537 the controller should not interrupt the user to tell them so.}
1539 GOOD_SERVER_DESCRIPTOR
1540 We successfully uploaded our server descriptor to at least one
1541 of the directory authorities, with no complaints.
1543 {Originally, the goal of this event was to declare "every authority
1544 has accepted the descriptor, so there will be no complaints
1545 about it." But since some authorities might be offline, it's
1546 harder to get certainty than we had thought. As such, this event
1547 is equivalent to ACCEPTED_SERVER_DESCRIPTOR below. Controllers
1548 should just look at ACCEPTED_SERVER_DESCRIPTOR and should ignore
1549 this event for now.}
1551 SERVER_DESCRIPTOR_STATUS
1552 "STATUS=" "LISTED" / "UNLISTED"
1553 We just got a new networkstatus consensus, and whether we're in
1554 it or not in it has changed. Specifically, status is "listed"
1555 if we're listed in it but previous to this point we didn't know
1556 we were listed in a consensus; and status is "unlisted" if we
1557 thought we should have been listed in it (e.g. we were listed in
1558 the last one), but we're not.
1560 {Moving from listed to unlisted is not necessarily cause for
1561 alarm. The relay might have failed a few reachability tests,
1562 or the Internet might have had some routing problems. So this
1563 feature is mainly to let relay operators know when their relay
1564 has successfully been listed in the consensus.}
1566 [Not implemented yet. We should do this in 0.2.2.x. -RD]
1570 "STATUS=" "UP" / "DOWN"
1572 One of our nameservers has changed status.
1574 {This event could affect the controller's idea of server status, but
1575 the controller should not interrupt the user to tell them so.}
1578 All of our nameservers have gone down.
1580 {This is a problem; if it happens often without the nameservers
1581 coming up again, the user needs to configure more or better
1585 Our DNS provider is providing an address when it should be saying
1586 "NOTFOUND"; Tor will treat the address as a synonym for "NOTFOUND".
1588 {This is an annoyance; controllers may want to tell admins that their
1589 DNS provider is not to be trusted.}
1592 Our DNS provider is giving a hijacked address instead of well-known
1593 websites; Tor will not try to be an exit node.
1595 {Controllers could warn the admin if the server is running as an
1596 exit server: the admin needs to configure a good DNS server.
1597 Alternatively, this happens a lot in some restrictive environments
1598 (hotels, universities, coffeeshops) when the user hasn't registered.}
1600 BAD_SERVER_DESCRIPTOR
1603 A directory authority rejected our descriptor. Possible reasons
1604 include malformed descriptors, incorrect keys, highly skewed clocks,
1607 {Controllers should warn the admin, and try to cope if they can.}
1609 ACCEPTED_SERVER_DESCRIPTOR
1611 A single directory authority accepted our descriptor.
1614 {This event could affect the controller's idea of server status, but
1615 the controller should not interrupt the user to tell them so.}
1619 "DIRADDRESS=IP:port"
1620 We failed to connect to our external OR port or directory port
1623 {This event could affect the controller's idea of server status. The
1624 controller should warn the admin and suggest reasonable steps to take.}
1626 4.1.11. Our set of guard nodes has changed
1629 "650" SP "GUARD" SP Type SP Name SP Status ... CRLF
1631 Name = The (possibly verbose) nickname of the guard affected.
1632 Status = "NEW" | "UP" | "DOWN" | "BAD" | "GOOD" | "DROPPED"
1634 [explain states. XXX]
1636 4.1.12. Network status has changed
1639 "650" "+" "NS" CRLF 1*NetworkStatus "." CRLF "650" SP "OK" CRLF
1641 The event is used whenever our local view of a relay status changes.
1642 This happens when we get a new v3 consensus (in which case the entries
1643 we see are a duplicate of what we see in the NEWCONSENSUS event,
1644 below), but it also happens when we decide to mark a relay as up or
1645 down in our local status, for example based on connection attempts.
1647 [First added in 0.1.2.3-alpha]
1649 4.1.13. Bandwidth used on an application stream
1652 "650" SP "STREAM_BW" SP StreamID SP BytesWritten SP BytesRead CRLF
1653 BytesWritten = 1*DIGIT
1656 BytesWritten and BytesRead are the number of bytes written and read
1657 by the application since the last STREAM_BW event on this stream.
1659 Note that from Tor's perspective, *reading* a byte on a stream means
1660 that the application *wrote* the byte. That's why the order of "written"
1661 vs "read" is opposite for stream_bw events compared to bw events.
1663 These events are generated about once per second per stream; no events
1664 are generated for streams that have not written or read. These events
1665 apply only to streams entering Tor (such as on a SOCKSPort, TransPort,
1666 or so on). They are not generated for exiting streams.
1668 4.1.14. Per-country client stats
1671 "650" SP "CLIENTS_SEEN" SP TimeStarted SP CountrySummary CRLF
1673 We just generated a new summary of which countries we've seen clients
1674 from recently. The controller could display this for the user, e.g.
1675 in their "relay" configuration window, to give them a sense that they
1676 are actually being useful.
1678 Currently only bridge relays will receive this event, but once we figure
1679 out how to sufficiently aggregate and sanitize the client counts on
1680 main relays, we might start sending these events in other cases too.
1682 TimeStarted is a quoted string indicating when the reported summary
1683 counts from (in GMT).
1685 The CountrySummary keyword has as its argument a comma-separated,
1686 possibly empty set of "countrycode=count" pairs. For example (without
1688 650-CLIENTS_SEEN TimeStarted="2008-12-25 23:50:43"
1689 CountrySummary=us=16,de=8,uk=8
1691 4.1.15. New consensus networkstatus has arrived.
1694 "650" "+" "NEWCONSENSUS" CRLF 1*NetworkStatus "." CRLF "650" SP
1697 A new consensus networkstatus has arrived. We include NS-style lines for
1698 every relay in the consensus. NEWCONSENSUS is a separate event from the
1699 NS event, because the list here represents every usable relay: so any
1700 relay *not* mentioned in this list is implicitly no longer recommended.
1702 [First added in 0.2.1.13-alpha]
1704 4.1.16. New circuit buildtime has been set.
1707 "650" SP "BUILDTIMEOUT_SET" SP Type SP "TOTAL_TIMES=" Total SP
1708 "TIMEOUT_MS=" Timeout SP "XM=" Xm SP "ALPHA=" Alpha SP
1709 "CUTOFF_QUANTILE=" Quantile SP "TIMEOUT_RATE=" TimeoutRate SP
1710 "CLOSE_MS=" CloseTimeout SP "CLOSE_RATE=" CloseRate
1712 Type = "COMPUTED" / "RESET" / "SUSPENDED" / "DISCARD" / "RESUME"
1713 Total = Integer count of timeouts stored
1714 Timeout = Integer timeout in milliseconds
1715 Xm = Estimated integer Pareto parameter Xm in milliseconds
1716 Alpha = Estimated floating point Paredo paremter alpha
1717 Quantile = Floating point CDF quantile cutoff point for this timeout
1718 TimeoutRate = Floating point ratio of circuits that timeout
1719 CloseTimeout = How long to keep measurement circs in milliseconds
1720 CloseRate = Floating point ratio of measurement circuits that are closed
1722 A new circuit build timeout time has been set. If Type is "COMPUTED",
1723 Tor has computed the value based on historical data. If Type is "RESET",
1724 initialization or drastic network changes have caused Tor to reset
1725 the timeout back to the default, to relearn again. If Type is
1726 "SUSPENDED", Tor has detected a loss of network connectivity and has
1727 temporarily changed the timeout value to the default until the network
1728 recovers. If type is "DISCARD", Tor has decided to discard timeout
1729 values that likely happened while the network was down. If type is
1730 "RESUME", Tor has decided to resume timeout calculation.
1732 The Total value is the count of circuit build times Tor used in
1733 computing this value. It is capped internally at the maximum number
1734 of build times Tor stores (NCIRCUITS_TO_OBSERVE).
1736 The Timeout itself is provided in milliseconds. Internally, Tor rounds
1737 this value to the nearest second before using it.
1739 [First added in 0.2.2.7-alpha]
1741 5. Implementation notes
1745 If the control port is open and no authentication operation is enabled, Tor
1746 trusts any local user that connects to the control port. This is generally
1749 If the 'CookieAuthentication' option is true, Tor writes a "magic cookie"
1750 file named "control_auth_cookie" into its data directory. To authenticate,
1751 the controller must send the contents of this file, encoded in hexadecimal.
1753 If the 'HashedControlPassword' option is set, it must contain the salted
1754 hash of a secret password. The salted hash is computed according to the
1755 S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier.
1756 This is then encoded in hexadecimal, prefixed by the indicator sequence
1757 "16:". Thus, for example, the password 'foo' could encode to:
1758 16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2
1759 ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1762 You can generate the salt of a password by calling
1763 'tor --hash-password <password>'
1764 or by using the example code in the Python and Java controller libraries.
1765 To authenticate under this scheme, the controller sends Tor the original
1766 secret that was used to generate the password, either as a quoted string
1767 or encoded in hexadecimal.
1769 5.2. Don't let the buffer get too big.
1771 If you ask for lots of events, and 16MB of them queue up on the buffer,
1772 the Tor process will close the socket.
1774 5.3. Backward compatibility with v0 control protocol.
1776 The 'version 0' control protocol was replaced in Tor 0.1.1.x. Support
1777 was removed in Tor 0.2.0.x. Every non-obsolete version of Tor now
1778 supports the version 1 control protocol.
1780 For backward compatibility with the "version 0" control protocol,
1781 Tor used to check whether the third octet of the first command is zero.
1782 (If it was, Tor assumed that version 0 is in use.)
1784 This compatibility was removed in Tor 0.1.2.16 and 0.2.0.4-alpha.
1786 5.4. Tor config options for use by controllers
1788 Tor provides a few special configuration options for use by controllers.
1789 These options can be set and examined by the SETCONF and GETCONF commands,
1790 but are not saved to disk by SAVECONF.
1792 Generally, these options make Tor unusable by disabling a portion of Tor's
1793 normal operations. Unless a controller provides replacement functionality
1794 to fill this gap, Tor will not correctly handle user requests.
1796 __AllDirOptionsPrivate
1798 If true, Tor will try to launch all directory operations through
1799 anonymous connections. (Ordinarily, Tor only tries to anonymize
1800 requests related to hidden services.) This option will slow down
1801 directory access, and may stop Tor from working entirely if it does not
1802 yet have enough directory information to build circuits.
1804 (Boolean. Default: "0".)
1806 __DisablePredictedCircuits
1808 If true, Tor will not launch preemptive "general-purpose" circuits for
1809 streams to attach to. (It will still launch circuits for testing and
1810 for hidden services.)
1812 (Boolean. Default: "0".)
1814 __LeaveStreamsUnattached
1816 If true, Tor will not automatically attach new streams to circuits;
1817 instead, the controller must attach them with ATTACHSTREAM. If the
1818 controller does not attach the streams, their data will never be routed.
1820 (Boolean. Default: "0".)
1822 __HashedControlSessionPassword
1824 As HashedControlPassword, but is not saved to the torrc file by
1825 SAVECONF. Added in Tor 0.2.0.20-rc.
1827 __ReloadTorrcOnSIGHUP
1829 If this option is true (the default), we reload the torrc from disk
1830 every time we get a SIGHUP (from the controller or via a signal).
1831 Otherwise, we don't. This option exists so that controllers can keep
1832 their options from getting overwritten when a user sends Tor a HUP for
1833 some other reason (for example, to rotate the logs).
1835 (Boolean. Default: "1")
1837 5.5. Phases from the Bootstrap status event.
1839 This section describes the various bootstrap phases currently reported
1840 by Tor. Controllers should not assume that the percentages and tags
1841 listed here will continue to match up, or even that the tags will stay
1842 in the same order. Some phases might also be skipped (not reported)
1843 if the associated bootstrap step is already complete, or if the phase
1844 no longer is necessary. Only "starting" and "done" are guaranteed to
1845 exist in all future versions.
1847 Current Tor versions enter these phases in order, monotonically.
1848 Future Tors MAY revisit earlier stages.
1851 tag=starting summary="Starting"
1853 Tor starts out in this phase.
1856 tag=conn_dir summary="Connecting to directory mirror"
1858 Tor sends this event as soon as Tor has chosen a directory mirror --
1859 e.g. one of the authorities if bootstrapping for the first time or
1860 after a long downtime, or one of the relays listed in its cached
1861 directory information otherwise.
1863 Tor will stay at this phase until it has successfully established
1864 a TCP connection with some directory mirror. Problems in this phase
1865 generally happen because Tor doesn't have a network connection, or
1866 because the local firewall is dropping SYN packets.
1869 tag=handshake_dir summary="Finishing handshake with directory mirror"
1871 This event occurs when Tor establishes a TCP connection with a relay used
1872 as a directory mirror (or its https proxy if it's using one). Tor remains
1873 in this phase until the TLS handshake with the relay is finished.
1875 Problems in this phase generally happen because Tor's firewall is
1876 doing more sophisticated MITM attacks on it, or doing packet-level
1877 keyword recognition of Tor's handshake.
1880 tag=onehop_create summary="Establishing one-hop circuit for dir info"
1882 Once TLS is finished with a relay, Tor will send a CREATE_FAST cell
1883 to establish a one-hop circuit for retrieving directory information.
1884 It will remain in this phase until it receives the CREATED_FAST cell
1885 back, indicating that the circuit is ready.
1888 tag=requesting_status summary="Asking for networkstatus consensus"
1890 Once we've finished our one-hop circuit, we will start a new stream
1891 for fetching the networkstatus consensus. We'll stay in this phase
1892 until we get the 'connected' relay cell back, indicating that we've
1893 established a directory connection.
1896 tag=loading_status summary="Loading networkstatus consensus"
1898 Once we've established a directory connection, we will start fetching
1899 the networkstatus consensus document. This could take a while; this
1900 phase is a good opportunity for using the "progress" keyword to indicate
1903 This phase could stall if the directory mirror we picked doesn't
1904 have a copy of the networkstatus consensus so we have to ask another,
1905 or it does give us a copy but we don't find it valid.
1908 tag=loading_keys summary="Loading authority key certs"
1910 Sometimes when we've finished loading the networkstatus consensus,
1911 we find that we don't have all the authority key certificates for the
1912 keys that signed the consensus. At that point we put the consensus we
1913 fetched on hold and fetch the keys so we can verify the signatures.
1916 tag=requesting_descriptors summary="Asking for relay descriptors"
1918 Once we have a valid networkstatus consensus and we've checked all
1919 its signatures, we start asking for relay descriptors. We stay in this
1920 phase until we have received a 'connected' relay cell in response to
1921 a request for descriptors.
1924 tag=loading_descriptors summary="Loading relay descriptors"
1926 We will ask for relay descriptors from several different locations,
1927 so this step will probably make up the bulk of the bootstrapping,
1928 especially for users with slow connections. We stay in this phase until
1929 we have descriptors for at least 1/4 of the usable relays listed in
1930 the networkstatus consensus. This phase is also a good opportunity to
1931 use the "progress" keyword to indicate partial steps.
1934 tag=conn_or summary="Connecting to entry guard"
1936 Once we have a valid consensus and enough relay descriptors, we choose
1937 some entry guards and start trying to build some circuits. This step
1938 is similar to the "conn_dir" phase above; the only difference is
1941 If a Tor starts with enough recent cached directory information,
1942 its first bootstrap status event will be for the conn_or phase.
1945 tag=handshake_or summary="Finishing handshake with entry guard"
1947 This phase is similar to the "handshake_dir" phase, but it gets reached
1948 if we finish a TCP connection to a Tor relay and we have already reached
1949 the "conn_or" phase. We'll stay in this phase until we complete a TLS
1950 handshake with a Tor relay.
1953 tag=circuit_create summary="Establishing circuits"
1955 Once we've finished our TLS handshake with an entry guard, we will
1956 set about trying to make some 3-hop circuits in case we need them soon.
1959 tag=done summary="Done"
1961 A full 3-hop exit circuit has been established. Tor is ready to handle
1962 application connections now.