3 TC: A Tor control protocol (Version 1)
7 This document describes an implementation-specific protocol that is used
8 for other programs (such as frontend user-interfaces) to communicate with a
9 locally running Tor process. It is not part of the Tor onion routing
12 This protocol replaces version 0 of TC, which is now deprecated. For
13 reference, TC is described in "control-spec-v0.txt". Implementors are
14 recommended to avoid using TC directly, but instead to use a library that
15 can easily be updated to use the newer protocol.
19 TC is a bidirectional message-based protocol. It assumes an underlying
20 stream for communication between a controlling process (the "client"
21 or "controller") and a Tor process (or "server"). The stream may be
22 implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on,
23 but it must provide reliable in-order delivery. For security, the
24 stream should not be accessible by untrusted parties.
26 In TC, the client and server send typed messages to each other over the
27 underlying stream. The client sends "commands" and the server sends
30 By default, all messages from the server are in response to messages from
31 the client. Some client requests, however, will cause the server to send
32 messages to the client indefinitely far into the future. Such
33 "asynchronous" replies are marked as such.
35 Servers respond to messages in the order messages are received.
39 2.1 Description format
41 The message formats listed below use ABNF as described in RFC2234.
42 The protocol itself is loosely based on SMTP (see RFC 2821).
44 We use the following nonterminals from RFC2822: atom, qcontent
46 We define the following general-use nonterminals:
48 String = DQUOTE *qcontent DQUOTE
50 There are explicitly no limits on line length. All 8-bit characters are
51 permitted unless explicitly disallowed.
53 2.2 Commands from controller to Tor
55 Command = Keyword Arguments CRLF / "+" Keyword Arguments CRLF Data
57 Arguments = *(SP / VCHAR)
59 Specific commands and their arguments are described below in section 3.
61 2.3 Replies from Tor to the controller
63 Reply = *(MidReplyLine / DataReplyLine) EndReplyLine
65 MidReplyLine = "-" ReplyLine
66 DataReplyLine = "+" ReplyLine Data
67 EndReplyLine = SP ReplyLine
68 ReplyLine = StatusCode [ SP ReplyText ] CRLF
72 Specific replies are mentioned below in section 3, and described more fully
75 2.4 General-use tokens
77 ; Identifiers for servers.
78 ServerID = Nickname / Fingerprint
79 Nickname = 1*19 NicknameChar
80 NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
81 Fingerprint = "$" 40*HEXDIG
83 ; Unique identifiers for streams or circuits. Currently, Tor only
84 ; uses digits, but this may change
85 StreamID = 1*16 IDChar
86 CircuitID = 1*16 IDChar
87 IDChar = ALPHA / DIGIT
89 Address = ip4-address / ip6-address / hostname (XXXX Define these)
92 ; A "Data" section is a sequence of octets concluded by the terminating
93 ; sequence CRLF "." CRLF. The terminating sequence may not appear in the
94 ; body of the data. Leading periods on lines in the data are escaped with
95 ; an additional leading period as in RFC2821 section 4.5.2
96 Data = *DataLine "." CRLF
97 DataLine = CRLF / "." 1*LineItem CRLF/ NonDotItem *LineItem CRLF
98 LineItem = NonCR / 1*CR NonCRLF
99 NonDotItem = NonDotCR / 1*CR NonCRLF
103 All commands and other keywords are case-insensitive.
107 Change the value of one or more configuration variables. The syntax is:
109 "SETCONF" 1*(SP keyword ["=" String]) CRLF
111 Tor behaves as though it had just read each of the key-value pairs
112 from its configuration file. Keywords with no corresponding values have
113 their configuration values reset to their defaults. SETCONF is
114 all-or-nothing: if there is an error in any of the configuration settings,
115 Tor sets none of them.
117 Tor responds with a "250 configuration values set" reply on success.
118 Tor responds with a "513 syntax error in configuration values" reply on
119 syntax error, or a "553 impossible configuration setting" reply on a
122 When a configuration option takes multiple values, or when multiple
123 configuration keys form a context-sensitive group (see GETCONF below), then
124 setting _any_ of the options in a SETCONF command is taken to reset all of
125 the others. For example, if two ORBindAddress values are configured, and a
126 SETCONF command arrives containing a single ORBindAddress value, the new
127 command's value replaces the two old values.
129 To _remove_ all settings for a given option entirely (and go back to its
130 default value), send a single line containing the key and no value.
134 Request the value of a configuration variable. The syntax is:
136 "GETCONF" 1*(SP keyword) CRLF
138 If all of the listed keywords exist in the Tor configuration, Tor replies
139 with a series of reply lines of the form:
141 If any option is set to a 'default' value semantically different from an
142 empty string, Tor may reply with a reply line of the form:
145 If some of the listed keywords can't be found, Tor replies with a
146 "552 unknown configuration keyword" message.
148 If an option appears multiple times in the configuration, all of its
149 key-value pairs are returned in order.
151 Some options are context-sensitive, and depend on other options with
152 different keywords. These cannot be fetched directly. Currently there
153 is only one such option: clients should use the "HiddenServiceOptions"
154 virtual keyword to get all HiddenServiceDir, HiddenServicePort,
155 HiddenServiceNodes, and HiddenServiceExcludeNodes option settings.
159 Request the server to inform the client about interesting events. The
162 "SETEVENTS" *(SP EventCode) CRLF
164 EventCode = "CIRC" / "STREAM" / "ORCONN" / "BW" / "DEBUG" /
165 "INFO" / "NOTICE" / "WARN" / "ERR" / "NEWDESC" / "ADDRMAP"
167 Any events *not* listed in the SETEVENTS line are turned off; thus, sending
168 SETEVENTS with an empty body turns off all event reporting.
170 The server responds with a "250 OK" reply on success, and a "552
171 Unrecognized event" reply if one of the event codes isn't recognized. (On
172 error, the list of active event codes isn't changed.)
176 Sent from the client to the server. The syntax is:
177 "AUTHENTICATE" [ SP 1*HEXDIG / QuotedString ] CRLF
179 The server responds with "250 OK" on success or "515 Bad authentication" if
180 the authentication cookie is incorrect.
182 The format of the 'cookie' is implementation-dependent; see 5.1 below for
183 information on how the standard Tor implementation handles it.
185 If Tor requires authentication and the controller has not yet sent an
186 AUTHENTICATE message, Tor sends a "514 authentication required" reply to
187 any other kind of message.
191 Sent from the client to the server. The syntax is:
194 Instructs the server to write out its config options into its torrc. Server
195 returns "250 OK" if successful, or "551 Unable to write configuration
196 to disk" if it can't write the file or some other error occurs.
200 Sent from the client to the server. The syntax is:
202 "SIGNAL" SP Signal CRLF
204 Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" /
205 "HUP" / "INT" / "USR1" / "USR2" / "TERM"
207 The meaning of the signals are:
209 RELOAD -- Reload: reload config items, refetch directory. (like HUP)
210 SHUTDOWN -- Controlled shutdown: if server is an OP, exit immediately.
211 If it's an OR, close listeners and exit after 30 seconds.
213 DUMP -- Dump stats: log information about open connections and
214 circuits. (like USR1)
215 DEBUG -- Debug: switch all open logs to loglevel debug. (like USR2)
216 HALT -- Immediate shutdown: clean up and exit now. (like TERM)
218 The server responds with "250 OK" if the signal is recognized (or simply
219 closes the socket if it was asked to close immediately), or "552
220 Unrecognized signal" if the signal is unrecognized.
224 Sent from the client to the server. The syntax is:
226 "MAPADDRESS" 1*(Address "=" Address SP) CRLF
228 The first address in each pair is an "original" address; the second is a
229 "replacement" address. The client sends this message to the server in
230 order to tell it that future SOCKS requests for connections to the original
231 address should be replaced with connections to the specified replacement
232 address. If the addresses are well-formed, and the server is able to
233 fulfill the request, the server replies with a 250 message:
234 250-OldAddress1=NewAddress1
235 250 OldAddress2=NewAddress2
237 containing the source and destination addresses. If request is malformed,
238 the server replies with "512 syntax error in command argument". If the server
239 can't fulfill the request, it replies with "451 resource exhausted."
241 The client may decline to provide a body for the original address, and
242 instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
243 "." for hostname), signifying that the server should choose the original
244 address itself, and return that address in the reply. The server
245 should ensure that it returns an element of address space that is unlikely
246 to be in actual use. If there is already an address mapped to the
247 destination address, the server may reuse that mapping.
249 If the original address is already mapped to a different address, the old
250 mapping is removed. If the original address and the destination address
251 are the same, the server removes any mapping in place for the original
255 C: MAPADDRESS 0.0.0.0=tor.eff.org 1.2.3.4=tor.freehaven.net
256 S: 250-127.192.10.10=tor.eff.org
257 S: 250 1.2.3.4=tor.freehaven.net
259 {Note: This feature is designed to be used to help Tor-ify applications
260 that need to use SOCKS4 or hostname-less SOCKS5. There are three
261 approaches to doing this:
262 1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
263 2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
264 feature) to resolve the hostname remotely. This doesn't work
265 with special addresses like x.onion or x.y.exit.
266 3. Use MAPADDRESS to map an IP address to the desired hostname, and then
267 arrange to fool the application into thinking that the hostname
268 has resolved to that IP.
269 This functionality is designed to help implement the 3rd approach.}
271 Mappings set by the controller last until the Tor process exits:
272 they never expire. If the controller wants the mapping to last only
273 a certain time, then it must explicitly un-map the address when that
278 Sent from the client to the server. The syntax is as for GETCONF:
279 "GETINFO" 1*(SP keyword) CRLF
280 one or more NL-terminated strings. The server replies with an INFOVALUE
283 Unlike GETCONF, this message is used for data that are not stored in the Tor
284 configuration file, and that may be longer than a single line. On success,
285 one ReplyLine is sent for each requested value, followed by a final 250 OK
286 ReplyLine. If a value fits on a single line, the format is:
288 If avalue must be split over multiple lines, the format is:
292 Recognized key and their values include:
294 "version" -- The version of the server's software, including the name
295 of the software. (example: "Tor 0.0.9.4")
297 "config-file" -- The location of Tor's configuration file ("torrc").
299 "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest server
300 descriptor for a given OR, NUL-terminated. If no such OR is known, the
301 corresponding value is an empty string.
303 "network-status" -- a space-separated list of all known OR identities.
304 This is in the same format as the router-status line in directories;
305 see tor-spec.txt for details.
308 "addr-mappings/config"
309 "addr-mappings/cache"
310 "addr-mappings/control" -- a space-separated list of address mappings, each
311 in the form of "from-address=to-address". The 'config' key
312 returns those address mappings set in the configuration; the 'cache'
313 key returns the mappings in the client-side DNS cache; the 'control'
314 key returns the mappings set via the control interface; the 'all'
315 target returns the mappings set through any mechanism.
318 A series of lines as for a circuit status event. Each line is of the form:
319 CircuitID SP CircStatus SP Path CRLF
322 A series of lines as for a stream status event. Each is of the form:
323 StreamID SP StreamStatus SP CircID SP Target CRLF
326 A series of lines as for an OR connection status event. Each is of the
328 ServerID SP ORStatus CRLF
331 A series of lines listing the currently chosen helper nodes, if any.
333 ServerID SP ((("down" / "unlisted") ISOTime) / "up") CRLF
336 "accounting/hibernating"
338 "accounting/bytes-left"
339 "accounting/interval-start"
340 "accounting/interval-wake"
341 "accounting/interval-end"
342 Information about accounting status. If accounting is enabled,
343 "enabled" is 1; otherwise it is 0. The "hibernating" field is "hard"
344 if we are accepting no data; "soft" if we're accepting no new
345 connections, and "awake" if we're not hibernating at all. The "bytes"
346 and "bytes-left" fields contain (read-bytes SP write-bytes), for the
347 start and the rest of the interval respectively. The 'interval-start'
348 and 'interval-end' fields are the borders of the current interval; the
349 'interval-wake' field is the time within the current interval (if any)
350 where we plan[ned] to start being active.
353 A series of lines listing the available configuration options. Each is
355 OptionName SP OptionType [ SP Documentation ] CRLF
357 OptionType = "Integer" / "TimeInterval" / "DataSize" / "Float" /
358 "Boolean" / "Time" / "CommaList" / "Dependant" / "Virtual" /
359 "String" / "LineList"
363 A series of lines listing the available GETINFO options. Each is of
365 OptionName SP Documentation CRLF
366 OptionPrefix SP Documentation CRLF
367 OptionPrefix = OptionName "/*"
370 C: GETINFO version desc/name/moria1
371 S: 250+desc/name/moria=
372 S: [Descriptor for moria]
374 S: 250-version=Tor 0.1.1.0-alpha-cvs
379 Sent from the client to the server. The format is:
380 "EXTENDCIRCUIT" SP CircuitID SP ServerID *("," ServerID) CRLF
382 This request takes one of two forms: either the Circuit ID is zero, in
383 which case it is a request for the server to build a new circuit according
384 to the specified path, or the Circuit ID is nonzero, in which case it is a
385 request for the server to extend an existing circuit with that ID according
386 to the specified path.
388 If the request is successful, the server sends a reply containing a message
389 body consisting of the Circuit ID of the (maybe newly created) circuit.
390 The syntax is "250" SP "EXTENDED" SP CircuitID CRLF.
394 Sent from the client to the server. The syntax is:
395 "ATTACHSTREAM" SP StreamID SP CircuitID CRLF
397 This message informs the server that the specified stream should be
398 associated with the specified circuit. Each stream may be associated with
399 at most one circuit, and multiple streams may share the same circuit.
400 Streams can only be attached to completed circuits (that is, circuits that
401 have sent a circuit status 'BUILT' event or are listed as built in a
402 GETINFO circuit-status request).
404 If the circuit ID is 0, responsibility for attaching the given stream is
407 Tor responds with "250 OK" if it can attach the stream, 552 if the circuit
408 or stream didn't exist, or 551 if the stream couldn't be attached for
411 {Implementation note: By default, Tor automatically attaches streams to
412 circuits itself, unless the configuration variable
413 "__LeaveStreamsUnattached" is set to "1". Attempting to attach streams
414 via TC when "__LeaveStreamsUnattached" is false may cause a race between
415 Tor and the controller, as both attempt to attach streams to circuits.}
419 Sent from the client to the server. The syntax is:
420 "+POSTDESCRIPTOR" CRLF Descriptor CRLF "." CRLF
422 This message informs the server about a new descriptor.
424 The descriptor, when parsed, must contain a number of well-specified
425 fields, including fields for its nickname and identity.
427 If there is an error in parsing the descriptor, the server must send a "554
428 Invalid descriptor" reply. If the descriptor is well-formed but the server
429 chooses not to add it, it must reply with a 251 message whose body explains
430 why the server was not added. If the descriptor is added, Tor replies with
435 Sent from the client to the server. The syntax is:
436 "REDIRECTSTREAM" SP StreamID SP Address CRLF
438 Tells the server to change the exit address on the specified stream. No
439 remapping is performed on the new provided address.
441 To be sure that the modified address will be used, this event must be sent
442 after a new stream event is received, and before attaching this stream to
445 Tor replies with "250 OK" on success.
449 Sent from the client to the server. The syntax is:
451 "CLOSESTREAM" SP StreamID SP Reason *(SP Flag) CRLF
453 Tells the server to close the specified stream. The reason should be one
454 of the Tor RELAY_END reasons given in tor-spec.txt, as a decimal. Flags is
455 not used currently; Tor servers SHOULD ignore unrecognized flags. Tor may
456 hold the stream open for a while to flush any data that is pending.
461 CLOSECIRCUIT SP CircuitID *(SP Flag) CRLF
464 Tells the server to close the specified circuit. If "IfUnused" is
465 provided, do not close the circuit unless it is unused.
467 Other flags may be defined in the future; Tor SHOULD ignore unrecognized
472 Tells the server to hang up on this controller connection. This command
473 can be used before authenticating.
477 Reply codes follow the same 3-character format as used by SMTP, with the
478 first character defining a status, the second character defining a
479 subsystem, and the third designating fine-grained information.
481 The TC protocol currently uses the following first characters:
483 2yz Positive Completion Reply
484 The command was successful; a new request can be started.
486 4yz Temporary Negative Completion reply
487 The command was unsuccessful but might be reattempted later.
489 5yz Permanent Negative Completion Reply
490 The command was unsuccessful; the client should not try exactly
491 that sequence of commands again.
493 6yz Asynchronous Reply
494 Sent out-of-order in response to an earlier SETEVENTS command.
496 The following second characters are used:
499 Sent in response to ill-formed or nonsensical commands.
502 Refers to operations of the Tor Control protocol.
505 Refers to actual operations of Tor system.
507 The following codes are defined:
510 251 Operation was unnecessary
511 [Tor has declined to perform the operation, but no harm was done.]
513 451 Resource exhausted
515 500 Syntax error: protocol
517 510 Unrecognized command
518 511 Unimplemented command
519 512 Syntax error in command argument
520 513 Unrecognized command argument
521 514 Authentication required
522 515 Bad authentication
524 550 Unspecified Tor error
527 [Something went wrong inside Tor, so that the client's
528 request couldn't be fulfilled.]
530 552 Unrecognized entity
531 [A configuration key, a stream ID, circuit ID, event,
532 mentioned in the command did not actually exist.]
534 553 Invalid configuration value
535 [The client tried to set a configuration option to an
536 incorrect, ill-formed, or impossible value.]
538 554 Invalid descriptor
542 650 Asynchronous event notification
544 Unless specified to have specific contents, the human-readable messages
545 in error replies should not be relied upon to match those in this document.
547 4.1 Asynchronous events
549 These replies can be sent after a corresponding SETEVENTS command has been
550 received. They will not be interleaved with other Reply elements, but they
551 can appear between a command and its corresponding reply. For example,
552 this sequence is possible:
556 C: GETCONF SOCKSPORT ORPORT
557 S: 650 CIRC 1000 EXTENDED moria1,moria2
558 S: 250-SOCKSPORT=9050
561 But this sequence is disallowed:
564 C: GETCONF SOCKSPORT ORPORT
565 S: 250-SOCKSPORT=9050
566 S: 650 CIRC 1000 EXTENDED moria1,moria2
569 Clients SHOULD tolerate more arguments in an asynchonous reply than
570 expected, and SHOULD tolerate more lines in an asynchronous reply than
571 expected. For instance, a client that expects a CIRC message like:
572 650 CIRC 1000 EXTENDED moria1,moria2
574 650+CIRC 1000 EXTENDED moria1,moria2 0xBEEF
578 4.1.1 Circuit status changed
582 "650" SP "CIRC" SP CircuitID SP CircStatus SP Path
585 "LAUNCHED" / ; circuit ID assigned to new circuit
586 "BUILT" / ; all hops finished, can now accept streams
587 "EXTENDED" / ; one more hop has been completed
588 "FAILED" / ; circuit closed (was not built)
589 "CLOSED" ; circuit closed (was built)
591 Path = ServerID *("," ServerID)
593 4.1.2. Stream status changed
597 "650" SP "STREAM" SP StreamID SP StreamStatus SP CircID SP Target SP
600 "NEW" / ; New request to connect
601 "NEWRESOLVE" / ; New request to resolve an address
602 "SENTCONNECT" / ; Sent a connect cell along a circuit
603 "SENTRESOLVE" / ; Sent a resolve cell along a circuit
604 "SUCCEEDED" / ; Received a reply; stream established
605 "FAILED" / ; Stream failed and not retriable.
606 "CLOSED" / ; Stream closed
607 "DETACHED" ; Detached from circuit; still retriable.
609 Target = Address ":" Port
611 The circuit ID designates which circuit this stream is attached to. If
612 the stream is unattached, the circuit ID "0" is given.
614 4.1.3 OR Connection status changed
617 "650" SP "ORCONN" SP ServerID SP ORStatus
619 ORStatus = "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"
621 4.1.3 Bandwidth used in the last second
624 "650" SP "BW" SP BytesRead SP BytesWritten
626 BytesWritten = 1*DIGIT
631 "650" SP Severity SP ReplyText
633 "650+" Severity CRLF Data
635 Severity = "DEBUG" / "INFO" / "NOTICE" / "WARN"/ "ERR"
637 4.1.5 New descriptors available
640 "650" SP "NEWDESC" 1*(SP ServerID)
642 4.1.6 New Address mapping
645 "650" SP "ADDRMAP" SP Address SP Address SP Expiry
646 Expiry = DQOUTE ISOTime DQUOTE / "NEVER"
648 5. Implementation notes
652 By default, the current Tor implementation trusts all local users.
654 If the 'CookieAuthentication' option is true, Tor writes a "magic cookie"
655 file named "control_auth_cookie" into its data directory. To authenticate,
656 the controller must send the contents of this file.
658 If the 'HashedControlPassword' option is set, it must contain the salted
659 hash of a secret password. The salted hash is computed according to the
660 S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier.
661 This is then encoded in hexadecimal, prefixed by the indicator sequence
662 "16:". Thus, for example, the password 'foo' could encode to:
663 16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2
664 ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
667 You can generate the salt of a password by calling
668 'tor --hash-password <password>'
669 or by using the example code in the Python and Java controller libraries.
670 To authenticate under this scheme, the controller sends Tor the original
671 secret that was used to generate the password.
673 5.2. Don't let the buffer get too big.
675 If you ask for lots of events, and 16MB of them queue up on the buffer,
676 the Tor process will close the socket.
678 5.3. Backward compatibility
680 For backward compatibility with the "version 0" control protocol, Tor checks
681 whether the third octet the first command is zero. If it is, Tor
682 assumes that version 0 is in use. This feature is deprecated, and will be
683 removed in the 0.1.2.x Tor development series.
685 In order to detect which version of the protocol is supported controllers
686 should send the sequence [00 00 0D 0A]. This is a valid and unrecognized
687 command in both protocol versions, and implementations can detect which
688 error they have received.