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. (Version 0 is used by Tor
16 versions 0.1.0.x; the protocol in this document only works with Tor
17 versions in the 0.1.1.x series and later.)
21 TC is a bidirectional message-based protocol. It assumes an underlying
22 stream for communication between a controlling process (the "client"
23 or "controller") and a Tor process (or "server"). The stream may be
24 implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on,
25 but it must provide reliable in-order delivery. For security, the
26 stream should not be accessible by untrusted parties.
28 In TC, the client and server send typed messages to each other over the
29 underlying stream. The client sends "commands" and the server sends
32 By default, all messages from the server are in response to messages from
33 the client. Some client requests, however, will cause the server to send
34 messages to the client indefinitely far into the future. Such
35 "asynchronous" replies are marked as such.
37 Servers respond to messages in the order messages are received.
41 2.1. Description format
43 The message formats listed below use ABNF as described in RFC2234.
44 The protocol itself is loosely based on SMTP (see RFC 2821).
46 We use the following nonterminals from RFC2822: atom, qcontent
48 We define the following general-use nonterminals:
50 String = DQUOTE *qcontent DQUOTE
52 There are explicitly no limits on line length. All 8-bit characters are
53 permitted unless explicitly disallowed.
55 2.2. Commands from controller to Tor
57 Command = Keyword Arguments CRLF / "+" Keyword Arguments CRLF Data
59 Arguments = *(SP / VCHAR)
61 Specific commands and their arguments are described below in section 3.
63 2.3. Replies from Tor to the controller
65 Reply = *(MidReplyLine / DataReplyLine) EndReplyLine
67 MidReplyLine = "-" ReplyLine
68 DataReplyLine = "+" ReplyLine Data
69 EndReplyLine = SP ReplyLine
70 ReplyLine = StatusCode [ SP ReplyText ] CRLF
74 Specific replies are mentioned below in section 3, and described more fully
77 2.4. General-use tokens
79 ; Identifiers for servers.
80 ServerID = Nickname / Fingerprint
81 Nickname = 1*19 NicknameChar
82 NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
83 Fingerprint = "$" 40*HEXDIG
85 ; Unique identifiers for streams or circuits. Currently, Tor only
86 ; uses digits, but this may change
87 StreamID = 1*16 IDChar
88 CircuitID = 1*16 IDChar
89 IDChar = ALPHA / DIGIT
91 Address = ip4-address / ip6-address / hostname (XXXX Define these)
93 ; A "Data" section is a sequence of octets concluded by the terminating
94 ; sequence CRLF "." CRLF. The terminating sequence may not appear in the
95 ; body of the data. Leading periods on lines in the data are escaped with
96 ; an additional leading period as in RFC2821 section 4.5.2
97 Data = *DataLine "." CRLF
98 DataLine = CRLF / "." 1*LineItem CRLF / NonDotItem *LineItem CRLF
99 LineItem = NonCR / 1*CR NonCRLF
100 NonDotItem = NonDotCR / 1*CR NonCRLF
104 All commands and other keywords are case-insensitive.
108 Change the value of one or more configuration variables. The syntax is:
110 "SETCONF" 1*(SP keyword ["=" String]) CRLF
112 Tor behaves as though it had just read each of the key-value pairs
113 from its configuration file. Keywords with no corresponding values have
114 their configuration values reset to 0 or NULL (use RESETCONF if you want
115 to set it back to its default). SETCONF is all-or-nothing: if there
116 is an error in any of the configuration settings, Tor sets none of them.
118 Tor responds with a "250 configuration values set" reply on success.
119 If some of the listed keywords can't be found, Tor replies with a
120 "552 Unrecognized option" message. Otherwise, Tor responds with a
121 "513 syntax error in configuration values" reply on syntax error, or a
122 "553 impossible configuration setting" reply on a semantic error.
124 When a configuration option takes multiple values, or when multiple
125 configuration keys form a context-sensitive group (see GETCONF below), then
126 setting _any_ of the options in a SETCONF command is taken to reset all of
127 the others. For example, if two ORBindAddress values are configured, and a
128 SETCONF command arrives containing a single ORBindAddress value, the new
129 command's value replaces the two old values.
133 Remove all settings for a given configuration option entirely, assign
134 its default value (if any), and then assign the String provided.
135 Typically the String is left empty, to simply set an option back to
136 its default. The syntax is:
138 "RESETCONF" 1*(SP keyword ["=" String]) CRLF
140 Otherwise it behaves like SETCONF above.
144 Request the value of a configuration variable. The syntax is:
146 "GETCONF" 1*(SP keyword) CRLF
148 If all of the listed keywords exist in the Tor configuration, Tor replies
149 with a series of reply lines of the form:
151 If any option is set to a 'default' value semantically different from an
152 empty string, Tor may reply with a reply line of the form:
155 If some of the listed keywords can't be found, Tor replies with a
156 "552 unknown configuration keyword" message.
158 If an option appears multiple times in the configuration, all of its
159 key-value pairs are returned in order.
161 Some options are context-sensitive, and depend on other options with
162 different keywords. These cannot be fetched directly. Currently there
163 is only one such option: clients should use the "HiddenServiceOptions"
164 virtual keyword to get all HiddenServiceDir, HiddenServicePort,
165 HiddenServiceNodes, and HiddenServiceExcludeNodes option settings.
169 Request the server to inform the client about interesting events. The
172 "SETEVENTS" [SP "EXTENDED"] *(SP EventCode) CRLF
174 EventCode = "CIRC" / "STREAM" / "ORCONN" / "BW" / "DEBUG" /
175 "INFO" / "NOTICE" / "WARN" / "ERR" / "NEWDESC" / "ADDRMAP" /
178 Any events *not* listed in the SETEVENTS line are turned off; thus, sending
179 SETEVENTS with an empty body turns off all event reporting.
181 The server responds with a "250 OK" reply on success, and a "552
182 Unrecognized event" reply if one of the event codes isn't recognized. (On
183 error, the list of active event codes isn't changed.)
185 If the flag string "EXTENDED" is provided, Tor may provide extra
186 information with events for this connection; see 4.1 for more information.
187 NOTE: All events on a given connection will be provided in extended format,
189 NOTE: "EXTENDED" is only supported in Tor 0.1.1.9-alpha or later.
193 Sent from the client to the server. The syntax is:
194 "AUTHENTICATE" [ SP 1*HEXDIG / QuotedString ] CRLF
196 The server responds with "250 OK" on success or "515 Bad authentication" if
197 the authentication cookie is incorrect.
199 The format of the 'cookie' is implementation-dependent; see 5.1 below for
200 information on how the standard Tor implementation handles it.
202 If Tor requires authentication and the controller has not yet sent an
203 AUTHENTICATE message, Tor sends a "514 authentication required" reply to
204 any other kind of message.
208 Sent from the client to the server. The syntax is:
211 Instructs the server to write out its config options into its torrc. Server
212 returns "250 OK" if successful, or "551 Unable to write configuration
213 to disk" if it can't write the file or some other error occurs.
217 Sent from the client to the server. The syntax is:
219 "SIGNAL" SP Signal CRLF
221 Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" /
222 "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM"
224 The meaning of the signals are:
226 RELOAD -- Reload: reload config items, refetch directory. (like HUP)
227 SHUTDOWN -- Controlled shutdown: if server is an OP, exit immediately.
228 If it's an OR, close listeners and exit after 30 seconds.
230 DUMP -- Dump stats: log information about open connections and
231 circuits. (like USR1)
232 DEBUG -- Debug: switch all open logs to loglevel debug. (like USR2)
233 HALT -- Immediate shutdown: clean up and exit now. (like TERM)
234 NEWNYM -- Switch to clean circuits, so new application requests
235 don't share any circuits with old ones.
237 The server responds with "250 OK" if the signal is recognized (or simply
238 closes the socket if it was asked to close immediately), or "552
239 Unrecognized signal" if the signal is unrecognized.
243 Sent from the client to the server. The syntax is:
245 "MAPADDRESS" 1*(Address "=" Address SP) CRLF
247 The first address in each pair is an "original" address; the second is a
248 "replacement" address. The client sends this message to the server in
249 order to tell it that future SOCKS requests for connections to the original
250 address should be replaced with connections to the specified replacement
251 address. If the addresses are well-formed, and the server is able to
252 fulfill the request, the server replies with a 250 message:
253 250-OldAddress1=NewAddress1
254 250 OldAddress2=NewAddress2
256 containing the source and destination addresses. If request is
257 malformed, the server replies with "512 syntax error in command
258 argument". If the server can't fulfill the request, it replies with
259 "451 resource exhausted".
261 The client may decline to provide a body for the original address, and
262 instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
263 "." for hostname), signifying that the server should choose the original
264 address itself, and return that address in the reply. The server
265 should ensure that it returns an element of address space that is unlikely
266 to be in actual use. If there is already an address mapped to the
267 destination address, the server may reuse that mapping.
269 If the original address is already mapped to a different address, the old
270 mapping is removed. If the original address and the destination address
271 are the same, the server removes any mapping in place for the original
275 C: MAPADDRESS 0.0.0.0=tor.eff.org 1.2.3.4=tor.freehaven.net
276 S: 250-127.192.10.10=tor.eff.org
277 S: 250 1.2.3.4=tor.freehaven.net
279 {Note: This feature is designed to be used to help Tor-ify applications
280 that need to use SOCKS4 or hostname-less SOCKS5. There are three
281 approaches to doing this:
282 1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
283 2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
284 feature) to resolve the hostname remotely. This doesn't work
285 with special addresses like x.onion or x.y.exit.
286 3. Use MAPADDRESS to map an IP address to the desired hostname, and then
287 arrange to fool the application into thinking that the hostname
288 has resolved to that IP.
289 This functionality is designed to help implement the 3rd approach.}
291 Mappings set by the controller last until the Tor process exits:
292 they never expire. If the controller wants the mapping to last only
293 a certain time, then it must explicitly un-map the address when that
298 Sent from the client to the server. The syntax is as for GETCONF:
299 "GETINFO" 1*(SP keyword) CRLF
300 one or more NL-terminated strings. The server replies with an INFOVALUE
301 message, or a 551 or 552 error.
303 Unlike GETCONF, this message is used for data that are not stored in the Tor
304 configuration file, and that may be longer than a single line. On success,
305 one ReplyLine is sent for each requested value, followed by a final 250 OK
306 ReplyLine. If a value fits on a single line, the format is:
308 If a value must be split over multiple lines, the format is:
312 Recognized keys and their values include:
314 "version" -- The version of the server's software, including the name
315 of the software. (example: "Tor 0.0.9.4")
317 "config-file" -- The location of Tor's configuration file ("torrc").
319 "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest server
320 descriptor for a given OR, NUL-terminated. If no such OR is known, the
321 corresponding value is an empty string.
323 "desc/all-recent" -- the latest server descriptor for every router that
326 "network-status" -- a space-separated list of all known OR identities.
327 This is in the same format as the router-status line in directories;
328 see tor-spec.txt for details.
331 "addr-mappings/config"
332 "addr-mappings/cache"
333 "addr-mappings/control" -- a space-separated list of address
334 mappings, each in the form of "from-address=to-address".
335 The 'config' key returns those address mappings set in the
336 configuration; the 'cache' key returns the mappings in the
337 client-side DNS cache; the 'control' key returns the mappings set
338 via the control interface; the 'all' target returns the mappings
339 set through any mechanism.
342 A series of lines as for a circuit status event. Each line is of
344 CircuitID SP CircStatus SP Path CRLF
347 A series of lines as for a stream status event. Each is of the form:
348 StreamID SP StreamStatus SP CircID SP Target CRLF
351 A series of lines as for an OR connection status event. Each is of the
353 ServerID SP ORStatus CRLF
356 A series of lines listing the currently chosen entry guards, if any.
358 ServerID SP (Status-with-time / Status) CRLF
360 Status-with-time = ("down" / "unlisted") SP ISOTime
361 Status = ("up" / "never-connected")
363 [From 0.1.1.4-alpha to 0.1.1.10-alpha, this was called "helper-nodes".
364 Tor still supports calling it that for now, but support will be
365 removed in the future.]
368 "accounting/hibernating"
370 "accounting/bytes-left"
371 "accounting/interval-start"
372 "accounting/interval-wake"
373 "accounting/interval-end"
374 Information about accounting status. If accounting is enabled,
375 "enabled" is 1; otherwise it is 0. The "hibernating" field is "hard"
376 if we are accepting no data; "soft" if we're accepting no new
377 connections, and "awake" if we're not hibernating at all. The "bytes"
378 and "bytes-left" fields contain (read-bytes SP write-bytes), for the
379 start and the rest of the interval respectively. The 'interval-start'
380 and 'interval-end' fields are the borders of the current interval; the
381 'interval-wake' field is the time within the current interval (if any)
382 where we plan[ned] to start being active.
385 A series of lines listing the available configuration options. Each is
387 OptionName SP OptionType [ SP Documentation ] CRLF
389 OptionType = "Integer" / "TimeInterval" / "DataSize" / "Float" /
390 "Boolean" / "Time" / "CommaList" / "Dependant" / "Virtual" /
391 "String" / "LineList"
395 A series of lines listing the available GETINFO options. Each is of
397 OptionName SP Documentation CRLF
398 OptionPrefix SP Documentation CRLF
399 OptionPrefix = OptionName "/*"
401 "dir/status/authority"
403 "dir/status/fp/<F1>+<F2>+<F3>"
406 "dir/server/fp/<F1>+<F2>+<F3>"
408 "dir/server/d/<D1>+<D2>+<D3>"
409 "dir/server/authority"
411 [DRAFT] [Not Implemented] A series of lines listing directory
412 contents, provided according to the specification for the URLs listed
413 in Section 4.4 of dir-spec.txt. Note that Tor MUST NOT provide
414 private information, such as descriptors for routers not marked as
415 general-purpose. When asked for 'authority' information for which this
416 Tor is not authoritative, Tor replies with an empty string.
419 C: GETINFO version desc/name/moria1
420 S: 250+desc/name/moria=
421 S: [Descriptor for moria]
423 S: 250-version=Tor 0.1.1.0-alpha-cvs
428 Sent from the client to the server. The format is:
429 "EXTENDCIRCUIT" SP CircuitID SP
430 ServerID *("," ServerID) SP
431 ("purpose=" Purpose) CRLF
433 This request takes one of two forms: either the CircuitID is zero, in
434 which case it is a request for the server to build a new circuit according
435 to the specified path, or the CircuitID is nonzero, in which case it is a
436 request for the server to extend an existing circuit with that ID according
437 to the specified path.
439 If CircuitID is 0 and "purpose=" is specified, then the circuit's
440 purpose is set. Two choices are recognized: "general" and
441 "controller". If not specified, circuits are created as "general".
443 If the request is successful, the server sends a reply containing a
444 message body consisting of the CircuitID of the (maybe newly created)
445 circuit. The syntax is "250" SP "EXTENDED" SP CircuitID CRLF.
447 3.11. SETCIRCUITPURPOSE
449 Sent from the client to the server. The format is:
450 "SETCIRCUITPURPOSE" SP CircuitID SP Purpose CRLF
452 This changes the circuit's purpose. See EXTENDCIRCUIT above for details.
454 3.12. SETROUTERPURPOSE
456 Sent from the client to the server. The format is:
457 "SETROUTERPURPOSE" SP NicknameOrKey SP Purpose CRLF
459 This changes the descriptor's purpose. See +POSTDESCRIPTOR below
464 Sent from the client to the server. The syntax is:
465 "ATTACHSTREAM" SP StreamID SP CircuitID CRLF
467 This message informs the server that the specified stream should be
468 associated with the specified circuit. Each stream may be associated with
469 at most one circuit, and multiple streams may share the same circuit.
470 Streams can only be attached to completed circuits (that is, circuits that
471 have sent a circuit status 'BUILT' event or are listed as built in a
472 GETINFO circuit-status request).
474 If the circuit ID is 0, responsibility for attaching the given stream is
477 Tor responds with "250 OK" if it can attach the stream, 552 if the circuit
478 or stream didn't exist, or 551 if the stream couldn't be attached for
481 {Implementation note: Tor will close unattached streams by itself,
482 roughly two minutes after they are born. Let the developers know if
483 that turns out to be a problem.}
485 {Implementation note: By default, Tor automatically attaches streams to
486 circuits itself, unless the configuration variable
487 "__LeaveStreamsUnattached" is set to "1". Attempting to attach streams
488 via TC when "__LeaveStreamsUnattached" is false may cause a race between
489 Tor and the controller, as both attempt to attach streams to circuits.}
491 {Implementation note: You can try to attachstream to a stream that
492 has already sent a connect or resolve request but hasn't succeeded
493 yet, in which case Tor will detach the stream from its current circuit
494 before proceeding with the new attach request.}
498 Sent from the client to the server. The syntax is:
499 "+POSTDESCRIPTOR" ("purpose=" Purpose) CRLF Descriptor CRLF "." CRLF
501 This message informs the server about a new descriptor. If Purpose is
502 specified, it must be either "general" or "controller", else we
505 The descriptor, when parsed, must contain a number of well-specified
506 fields, including fields for its nickname and identity.
508 If there is an error in parsing the descriptor, the server must send a "554
509 Invalid descriptor" reply. If the descriptor is well-formed but the server
510 chooses not to add it, it must reply with a 251 message whose body explains
511 why the server was not added. If the descriptor is added, Tor replies with
516 Sent from the client to the server. The syntax is:
517 "REDIRECTSTREAM" SP StreamID SP Address (SP Port) CRLF
519 Tells the server to change the exit address on the specified stream. If
520 Port is specified, changes the destination port as well. No remapping
521 is performed on the new provided address.
523 To be sure that the modified address will be used, this event must be sent
524 after a new stream event is received, and before attaching this stream to
527 Tor replies with "250 OK" on success.
531 Sent from the client to the server. The syntax is:
533 "CLOSESTREAM" SP StreamID SP Reason *(SP Flag) CRLF
535 Tells the server to close the specified stream. The reason should be one
536 of the Tor RELAY_END reasons given in tor-spec.txt, as a decimal. Flags is
537 not used currently; Tor servers SHOULD ignore unrecognized flags. Tor may
538 hold the stream open for a while to flush any data that is pending.
540 Tor replies with "250 OK" on success, or a 512 if there aren't enough
541 arguments, or a 552 if it doesn't recognize the StreamID or reason.
546 CLOSECIRCUIT SP CircuitID *(SP Flag) CRLF
549 Tells the server to close the specified circuit. If "IfUnused" is
550 provided, do not close the circuit unless it is unused.
552 Other flags may be defined in the future; Tor SHOULD ignore unrecognized
555 Tor replies with "250 OK" on success, or a 512 if there aren't enough
556 arguments, or a 552 if it doesn't recognize the CircuitID.
560 Tells the server to hang up on this controller connection. This command
561 can be used before authenticating.
565 Reply codes follow the same 3-character format as used by SMTP, with the
566 first character defining a status, the second character defining a
567 subsystem, and the third designating fine-grained information.
569 The TC protocol currently uses the following first characters:
571 2yz Positive Completion Reply
572 The command was successful; a new request can be started.
574 4yz Temporary Negative Completion reply
575 The command was unsuccessful but might be reattempted later.
577 5yz Permanent Negative Completion Reply
578 The command was unsuccessful; the client should not try exactly
579 that sequence of commands again.
581 6yz Asynchronous Reply
582 Sent out-of-order in response to an earlier SETEVENTS command.
584 The following second characters are used:
587 Sent in response to ill-formed or nonsensical commands.
590 Refers to operations of the Tor Control protocol.
593 Refers to actual operations of Tor system.
595 The following codes are defined:
598 251 Operation was unnecessary
599 [Tor has declined to perform the operation, but no harm was done.]
601 451 Resource exhausted
603 500 Syntax error: protocol
605 510 Unrecognized command
606 511 Unimplemented command
607 512 Syntax error in command argument
608 513 Unrecognized command argument
609 514 Authentication required
610 515 Bad authentication
612 550 Unspecified Tor error
615 [Something went wrong inside Tor, so that the client's
616 request couldn't be fulfilled.]
618 552 Unrecognized entity
619 [A configuration key, a stream ID, circuit ID, event,
620 mentioned in the command did not actually exist.]
622 553 Invalid configuration value
623 [The client tried to set a configuration option to an
624 incorrect, ill-formed, or impossible value.]
626 554 Invalid descriptor
630 650 Asynchronous event notification
632 Unless specified to have specific contents, the human-readable messages
633 in error replies should not be relied upon to match those in this document.
635 4.1. Asynchronous events
637 These replies can be sent after a corresponding SETEVENTS command has been
638 received. They will not be interleaved with other Reply elements, but they
639 can appear between a command and its corresponding reply. For example,
640 this sequence is possible:
644 C: GETCONF SOCKSPORT ORPORT
645 S: 650 CIRC 1000 EXTENDED moria1,moria2
646 S: 250-SOCKSPORT=9050
649 But this sequence is disallowed:
652 C: GETCONF SOCKSPORT ORPORT
653 S: 250-SOCKSPORT=9050
654 S: 650 CIRC 1000 EXTENDED moria1,moria2
657 Clients SHOULD tolerate more arguments in an asynchonous reply than
658 expected, and SHOULD tolerate more lines in an asynchronous reply than
659 expected. For instance, a client that expects a CIRC message like:
660 650 CIRC 1000 EXTENDED moria1,moria2
662 650-CIRC 1000 EXTENDED moria1,moria2 0xBEEF
666 If clients ask for extended events, then each event line as specified below
667 will be followed by additional extensions. Clients that do so MUST
668 tolerate additional arguments and lines. Additional lines will be of the
670 "650" ("-"/" ") KEYWORD ["=" ARGUMENTS] CRLF
671 Additional arguments will be of the form
672 SP KEYWORD ["=" ( QuotedString / * NonSpDquote ) ]
673 Such clients MUST tolerate lines with keywords they do not recognize.
675 4.1.1. Circuit status changed
679 "650" SP "CIRC" SP CircuitID SP CircStatus SP Path
682 "LAUNCHED" / ; circuit ID assigned to new circuit
683 "BUILT" / ; all hops finished, can now accept streams
684 "EXTENDED" / ; one more hop has been completed
685 "FAILED" / ; circuit closed (was not built)
686 "CLOSED" ; circuit closed (was built)
688 Path = ServerID *("," ServerID)
690 4.1.2. Stream status changed
694 "650" SP "STREAM" SP StreamID SP StreamStatus SP CircID SP Target
697 "NEW" / ; New request to connect
698 "NEWRESOLVE" / ; New request to resolve an address
699 "SENTCONNECT" / ; Sent a connect cell along a circuit
700 "SENTRESOLVE" / ; Sent a resolve cell along a circuit
701 "SUCCEEDED" / ; Received a reply; stream established
702 "FAILED" / ; Stream failed and not retriable
703 "CLOSED" / ; Stream closed
704 "DETACHED" ; Detached from circuit; still retriable
706 Target = Address ":" Port
708 The circuit ID designates which circuit this stream is attached to. If
709 the stream is unattached, the circuit ID "0" is given.
711 4.1.3. OR Connection status changed
714 "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus
716 ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"
718 NEW is for incoming connections, and LAUNCHED is for outgoing
719 connections. CONNECTED means the TLS handshake has finished (in
720 either direction). FAILED means a connection is being closed that
721 hasn't finished its handshake, and CLOSED is for connections that
724 A ServerID is specified unless it's a NEW connection, in which
725 case we don't know what server it is yet, so we use Address:Port.
727 4.1.4. Bandwidth used in the last second
730 "650" SP "BW" SP BytesRead SP BytesWritten
732 BytesWritten = 1*DIGIT
737 "650" SP Severity SP ReplyText
739 "650+" Severity CRLF Data
741 Severity = "DEBUG" / "INFO" / "NOTICE" / "WARN"/ "ERR"
743 4.1.6. New descriptors available
746 "650" SP "NEWDESC" 1*(SP ServerID)
748 4.1.7. New Address mapping
751 "650" SP "ADDRMAP" SP Address SP Address SP Expiry
752 Expiry = DQOUTE ISOTime DQUOTE / "NEVER"
754 4.1.8. Descriptors uploaded to us in our role as authoritative dirserver
757 "650" "+" "AUTHDIR_NEWDESCS" CRLF Action CRLF Message CRLF
758 Descriptor CRLF "." CRLF
759 Action = "ACCEPTED" / "DROPPED" / "REJECTED"
762 5. Implementation notes
766 By default, the current Tor implementation trusts all local users.
768 If the 'CookieAuthentication' option is true, Tor writes a "magic cookie"
769 file named "control_auth_cookie" into its data directory. To authenticate,
770 the controller must send the contents of this file.
772 If the 'HashedControlPassword' option is set, it must contain the salted
773 hash of a secret password. The salted hash is computed according to the
774 S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier.
775 This is then encoded in hexadecimal, prefixed by the indicator sequence
776 "16:". Thus, for example, the password 'foo' could encode to:
777 16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2
778 ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
781 You can generate the salt of a password by calling
782 'tor --hash-password <password>'
783 or by using the example code in the Python and Java controller libraries.
784 To authenticate under this scheme, the controller sends Tor the original
785 secret that was used to generate the password.
787 5.2. Don't let the buffer get too big.
789 If you ask for lots of events, and 16MB of them queue up on the buffer,
790 the Tor process will close the socket.
792 5.3. Backward compatibility
794 For backward compatibility with the "version 0" control protocol, Tor checks
795 whether the third octet the first command is zero. If it is, Tor
796 assumes that version 0 is in use. This feature is deprecated, and will be
797 removed in the 0.1.2.x Tor development series.
799 In order to detect which version of the protocol is supported controllers
800 should send the sequence [00 00 0D 0A]. This is a valid and unrecognized
801 command in both protocol versions, and implementations can detect which
802 error they have received.