diff options
Diffstat (limited to 'attic/text_formats/control-spec.txt')
| -rw-r--r-- | attic/text_formats/control-spec.txt | 4418 |
1 files changed, 4418 insertions, 0 deletions
diff --git a/attic/text_formats/control-spec.txt b/attic/text_formats/control-spec.txt new file mode 100644 index 0000000..52e11a0 --- /dev/null +++ b/attic/text_formats/control-spec.txt @@ -0,0 +1,4418 @@ + + TC: A Tor control protocol (Version 1) + +Table of Contents + + 0. Scope + 1. Protocol outline + 1.1. Forward-compatibility + 2. Message format + 2.1. Description format + 2.1.1. Notes on an escaping bug + 2.2. Commands from controller to Tor + 2.3. Replies from Tor to the controller + 2.4. General-use tokens + 3. Commands + 3.1. SETCONF + 3.2. RESETCONF + 3.3. GETCONF + 3.4. SETEVENTS + 3.5. AUTHENTICATE + 3.6. SAVECONF + 3.7. SIGNAL + 3.8. MAPADDRESS + 3.9. GETINFO + 3.10. EXTENDCIRCUIT + 3.11. SETCIRCUITPURPOSE + 3.12. SETROUTERPURPOSE + 3.13. ATTACHSTREAM + 3.14. POSTDESCRIPTOR + 3.15. REDIRECTSTREAM + 3.16. CLOSESTREAM + 3.17. CLOSECIRCUIT + 3.18. QUIT + 3.19. USEFEATURE + 3.20. RESOLVE + 3.21. PROTOCOLINFO + 3.22. LOADCONF + 3.23. TAKEOWNERSHIP + 3.24. AUTHCHALLENGE + 3.25. DROPGUARDS + 3.26. HSFETCH + 3.27. ADD_ONION + 3.28. DEL_ONION + 3.29. HSPOST + 3.30. ONION_CLIENT_AUTH_ADD + 3.31. ONION_CLIENT_AUTH_REMOVE + 3.32. ONION_CLIENT_AUTH_VIEW + 3.33. DROPOWNERSHIP + 3.34. DROPTIMEOUTS + 4. Replies + 4.1. Asynchronous events + 4.1.1. Circuit status changed + 4.1.2. Stream status changed + 4.1.3. OR Connection status changed + 4.1.4. Bandwidth used in the last second + 4.1.5. Log messages + 4.1.6. New descriptors available + 4.1.7. New Address mapping + 4.1.8. Descriptors uploaded to us in our role as authoritative dirserver + 4.1.9. Our descriptor changed + 4.1.10. Status events + 4.1.11. Our set of guard nodes has changed + 4.1.12. Network status has changed + 4.1.13. Bandwidth used on an application stream + 4.1.14. Per-country client stats + 4.1.15. New consensus networkstatus has arrived + 4.1.16. New circuit buildtime has been set + 4.1.17. Signal received + 4.1.18. Configuration changed + 4.1.19. Circuit status changed slightly + 4.1.20. Pluggable transport launched + 4.1.21. Bandwidth used on an OR or DIR or EXIT connection + 4.1.22. Bandwidth used by all streams attached to a circuit + 4.1.23. Per-circuit cell stats + 4.1.24. Token buckets refilled + 4.1.25. HiddenService descriptors + 4.1.26. HiddenService descriptors content + 4.1.27. Network liveness has changed + 4.1.28. Pluggable Transport Logs + 4.1.29. Pluggable Transport Status + 5. Implementation notes + 5.1. Authentication + 5.2. Don't let the buffer get too big + 5.3. Backward compatibility with v0 control protocol + 5.4. Tor config options for use by controllers + 5.5. Phases from the Bootstrap status event + 5.5.1. Overview of Bootstrap reporting. + 5.5.2. Phases in Bootstrap Stage 1 + 5.5.3. Phases in Bootstrap Stage 2 + 5.5.4. Phases in Bootstrap Stage 3 + 5.6 Bootstrap phases reported by older versions of Tor + +0. Scope + + This document describes an implementation-specific protocol that is used + for other programs (such as frontend user-interfaces) to communicate with a + locally running Tor process. It is not part of the Tor onion routing + protocol. + + This protocol replaces version 0 of TC, which is now deprecated. For + reference, TC is described in "control-spec-v0.txt". Implementors are + recommended to avoid using TC directly, but instead to use a library that + can easily be updated to use the newer protocol. (Version 0 is used by Tor + versions 0.1.0.x; the protocol in this document only works with Tor + versions in the 0.1.1.x series and later.) + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL + NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + RFC 2119. + +1. Protocol outline + + TC is a bidirectional message-based protocol. It assumes an underlying + stream for communication between a controlling process (the "client" + or "controller") and a Tor process (or "server"). The stream may be + implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on, + but it must provide reliable in-order delivery. For security, the + stream should not be accessible by untrusted parties. + + In TC, the client and server send typed messages to each other over the + underlying stream. The client sends "commands" and the server sends + "replies". + + By default, all messages from the server are in response to messages from + the client. Some client requests, however, will cause the server to send + messages to the client indefinitely far into the future. Such + "asynchronous" replies are marked as such. + + Servers respond to messages in the order messages are received. + +1.1. Forward-compatibility + + This is an evolving protocol; new client and server behavior will be + allowed in future versions. To allow new backward-compatible behavior + on behalf of the client, we may add new commands and allow existing + commands to take new arguments in future versions. To allow new + backward-compatible server behavior, we note various places below + where servers speaking a future version of this protocol may insert + new data, and note that clients should/must "tolerate" unexpected + elements in these places. There are two ways that we do this: + + * Adding a new field to a message: + + For example, we might say "This message has three space-separated + fields; clients MUST tolerate more fields." This means that a + client MUST NOT crash or otherwise fail to parse the message or + other subsequent messages when there are more than three fields, and + that it SHOULD function at least as well when more fields are + provided as it does when it only gets the fields it accepts. The + most obvious way to do this is by ignoring additional fields; the + next-most-obvious way is to report additional fields verbatim to the + user, perhaps as part of an expert UI. + + * Adding a new possible value to a list of alternatives: + + For example, we might say "This field will be OPEN, CLOSED, or + CONNECTED. Clients MUST tolerate unexpected values." This means + that a client MUST NOT crash or otherwise fail to parse the message + or other subsequent messages when there are unexpected values, and + that it SHOULD try to handle the rest of the message as well as it + can. The most obvious way to do this is by pretending that each + list of alternatives has an additional "unrecognized value" element, + and mapping any unrecognized values to that element; the + next-most-obvious way is to create a separate "unrecognized value" + element for each unrecognized value. + + Clients SHOULD NOT "tolerate" unrecognized alternatives by + pretending that the message containing them is absent. For example, + a stream closed for an unrecognized reason is nevertheless closed, + and should be reported as such. + + (If some list of alternatives is given, and there isn't an explicit + statement that clients must tolerate unexpected values, clients still + must tolerate unexpected values. The only exception would be if there + were an explicit statement that no future values will ever be added.) + +2. Message format + +2.1. Description format + + The message formats listed below use ABNF as described in RFC 2234. + The protocol itself is loosely based on SMTP (see RFC 2821). + + We use the following nonterminals from RFC 2822: atom, qcontent + + We define the following general-use nonterminals: + + QuotedString = DQUOTE *qcontent DQUOTE + + There are explicitly no limits on line length. All 8-bit characters + are permitted unless explicitly disallowed. In QuotedStrings, + backslashes and quotes must be escaped; other characters need not be + escaped. + + Wherever CRLF is specified to be accepted from the controller, Tor MAY also + accept LF. Tor, however, MUST NOT generate LF instead of CRLF. + Controllers SHOULD always send CRLF. + +2.1.1. Notes on an escaping bug + + CString = DQUOTE *qcontent DQUOTE + + Note that although these nonterminals have the same grammar, they + are interpreted differently. In a QuotedString, a backslash + followed by any character represents that character. But + in a CString, the escapes "\n", "\t", "\r", and the octal escapes + "\0" ... "\377" represent newline, tab, carriage return, and the + 256 possible octet values respectively. + + The use of CString in this document reflects a bug in Tor; + they should have been QuotedString instead. In the future, they + may migrate to use QuotedString instead. If they do, the + QuotedString implementation will never place a backslash before a + "n", "t", "r", or digit, to ensure that old controllers don't get + confused. + + For future-proofing, controller implementors MAY use the following + rules to be compatible with buggy Tor implementations and with + future ones that implement the spec as intended: + + Read \n \t \r and \0 ... \377 as C escapes. + Treat a backslash followed by any other character as that character. + + Currently, many of the QuotedString instances below that Tor + outputs are in fact CStrings. We intend to fix this in future + versions of Tor, and document which ones were broken. (See + bugtracker ticket #14555 for a bit more information.) + + Note that this bug exists only in strings generated by Tor for the + Tor controller; Tor should parse input QuotedStrings from the + controller correctly. + + +2.2. Commands from controller to Tor + + Command = Keyword OptArguments CRLF / "+" Keyword OptArguments CRLF CmdData + Keyword = 1*ALPHA + OptArguments = [ SP *(SP / VCHAR) ] + + A command is either a single line containing a Keyword and arguments, or a + multiline command whose initial keyword begins with +, and whose data + section ends with a single "." on a line of its own. (We use a special + character to distinguish multiline commands so that Tor can correctly parse + multi-line commands that it does not recognize.) Specific commands and + their arguments are described below in section 3. + +2.3. Replies from Tor to the controller + + Reply = SyncReply / AsyncReply + SyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine + AsyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine + + MidReplyLine = StatusCode "-" ReplyLine + DataReplyLine = StatusCode "+" ReplyLine CmdData + EndReplyLine = StatusCode SP ReplyLine + ReplyLine = [ReplyText] CRLF + ReplyText = XXXX + StatusCode = 3DIGIT + + Unless specified otherwise, multiple lines in a single reply from + Tor to the controller are guaranteed to share the same status + code. Specific replies are mentioned below in section 3, and + described more fully in section 4. + + [Compatibility note: versions of Tor before 0.2.0.3-alpha sometimes + generate AsyncReplies of the form "*(MidReplyLine / DataReplyLine)". + This is incorrect, but controllers that need to work with these + versions of Tor should be prepared to get multi-line AsyncReplies with + the final line (usually "650 OK") omitted.] + +2.4. General-use tokens + + ; CRLF means, "the ASCII Carriage Return character (decimal value 13) + ; followed by the ASCII Linefeed character (decimal value 10)." + CRLF = CR LF + + ; How a controller tells Tor about a particular OR. There are four + ; possible formats: + ; $Fingerprint -- The router whose identity key hashes to the fingerprint. + ; This is the preferred way to refer to an OR. + ; $Fingerprint~Nickname -- The router whose identity key hashes to the + ; given fingerprint, but only if the router has the given nickname. + ; $Fingerprint=Nickname -- The router whose identity key hashes to the + ; given fingerprint, but only if the router is Named and has the given + ; nickname. + ; Nickname -- The Named router with the given nickname, or, if no such + ; router exists, any router whose nickname matches the one given. + ; This is not a safe way to refer to routers, since Named status + ; could under some circumstances change over time. + ; + ; The tokens that implement the above follow: + + ServerSpec = LongName / Nickname + LongName = Fingerprint [ "~" Nickname ] + + ; For tors older than 0.3.1.3-alpha, LongName may have included an equal + ; sign ("=") in lieu of a tilde ("~"). The presence of an equal sign + ; denoted that the OR possessed the "Named" flag: + + LongName = Fingerprint [ ( "=" / "~" ) Nickname ] + + Fingerprint = "$" 40*HEXDIG + NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9" + Nickname = 1*19 NicknameChar + + ; What follows is an outdated way to refer to ORs. + ; Feature VERBOSE_NAMES replaces ServerID with LongName in events and + ; GETINFO results. VERBOSE_NAMES can be enabled starting in Tor version + ; 0.1.2.2-alpha and it is always-on in 0.2.2.1-alpha and later. + ServerID = Nickname / Fingerprint + + + ; Unique identifiers for streams or circuits. Currently, Tor only + ; uses digits, but this may change + StreamID = 1*16 IDChar + CircuitID = 1*16 IDChar + ConnID = 1*16 IDChar + QueueID = 1*16 IDChar + IDChar = ALPHA / DIGIT + + Address = ip4-address / ip6-address / hostname (XXXX Define these) + + ; A "CmdData" section is a sequence of octets concluded by the terminating + ; sequence CRLF "." CRLF. The terminating sequence may not appear in the + ; body of the data. Leading periods on lines in the data are escaped with + ; an additional leading period as in RFC 2821 section 4.5.2. + CmdData = *DataLine "." CRLF + DataLine = CRLF / "." 1*LineItem CRLF / NonDotItem *LineItem CRLF + LineItem = NonCR / 1*CR NonCRLF + NonDotItem = NonDotCR / 1*CR NonCRLF + + ; ISOTime, ISOTime2, and ISOTime2Frac are time formats as specified in + ; ISO8601. + ; example ISOTime: "2012-01-11 12:15:33" + ; example ISOTime2: "2012-01-11T12:15:33" + ; example ISOTime2Frac: "2012-01-11T12:15:33.51" + IsoDatePart = 4*DIGIT "-" 2*DIGIT "-" 2*DIGIT + IsoTimePart = 2*DIGIT ":" 2*DIGIT ":" 2*DIGIT + ISOTime = IsoDatePart " " IsoTimePart + ISOTime2 = IsoDatePart "T" IsoTimePart + ISOTime2Frac = IsoTime2 [ "." 1*DIGIT ] + + ; Numbers + LeadingDigit = "1" - "9" + UInt = LeadingDigit *Digit + +3. Commands + + All commands are case-insensitive, but most keywords are case-sensitive. + +3.1. SETCONF + + Change the value of one or more configuration variables. The syntax is: + + "SETCONF" 1*(SP keyword ["=" value]) CRLF + value = String / QuotedString + + Tor behaves as though it had just read each of the key-value pairs + from its configuration file. Keywords with no corresponding values have + their configuration values reset to 0 or NULL (use RESETCONF if you want + to set it back to its default). SETCONF is all-or-nothing: if there + is an error in any of the configuration settings, Tor sets none of them. + + Tor responds with a "250 OK" reply on success. + If some of the listed keywords can't be found, Tor replies with a + "552 Unrecognized option" message. Otherwise, Tor responds with a + "513 syntax error in configuration values" reply on syntax error, or a + "553 impossible configuration setting" reply on a semantic error. + + Some configuration options (e.g. "Bridge") take multiple values. Also, + some configuration keys (e.g. for hidden services and for entry + guard lists) form a context-sensitive group where order matters (see + GETCONF below). In these cases, setting _any_ of the options in a + SETCONF command is taken to reset all of the others. For example, + if two ORListenAddress values are configured, and a SETCONF command + arrives containing a single ORListenAddress value, the new command's + value replaces the two old values. + + Sometimes it is not possible to change configuration options solely by + issuing a series of SETCONF commands, because the value of one of the + configuration options depends on the value of another which has not yet + been set. Such situations can be overcome by setting multiple configuration + options with a single SETCONF command (e.g. SETCONF ORPort=443 + ORListenAddress=9001). + +3.2. RESETCONF + + Remove all settings for a given configuration option entirely, assign + its default value (if any), and then assign the String provided. + Typically the String is left empty, to simply set an option back to + its default. The syntax is: + + "RESETCONF" 1*(SP keyword ["=" String]) CRLF + + Otherwise it behaves like SETCONF above. + +3.3. GETCONF + + Request the value of zero or more configuration variable(s). + The syntax is: + + "GETCONF" *(SP keyword) CRLF + + If all of the listed keywords exist in the Tor configuration, Tor replies + with a series of reply lines of the form: + + 250 keyword=value + + If any option is set to a 'default' value semantically different from an + empty string, Tor may reply with a reply line of the form: + + 250 keyword + + Value may be a raw value or a quoted string. Tor will try to use unquoted + values except when the value could be misinterpreted through not being + quoted. (Right now, Tor supports no such misinterpretable values for + configuration options.) + + If some of the listed keywords can't be found, Tor replies with a + "552 unknown configuration keyword" message. + + If an option appears multiple times in the configuration, all of its + key-value pairs are returned in order. + + If no keywords were provided, Tor responds with "250 OK" message. + + Some options are context-sensitive, and depend on other options with + different keywords. These cannot be fetched directly. Currently there + is only one such option: clients should use the "HiddenServiceOptions" + virtual keyword to get all HiddenServiceDir, HiddenServicePort, + HiddenServiceVersion, and HiddenserviceAuthorizeClient option settings. + +3.4. SETEVENTS + + Request the server to inform the client about interesting events. The + syntax is: + + "SETEVENTS" [SP "EXTENDED"] *(SP EventCode) CRLF + + EventCode = 1*(ALPHA / "_") (see section 4.1.x for event types) + + Any events *not* listed in the SETEVENTS line are turned off; thus, sending + SETEVENTS with an empty body turns off all event reporting. + + The server responds with a "250 OK" reply on success, and a "552 + Unrecognized event" reply if one of the event codes isn't recognized. (On + error, the list of active event codes isn't changed.) + + If the flag string "EXTENDED" is provided, Tor may provide extra + information with events for this connection; see 4.1 for more information. + NOTE: All events on a given connection will be provided in extended format, + or none. + NOTE: "EXTENDED" was first supported in Tor 0.1.1.9-alpha; it is + always-on in Tor 0.2.2.1-alpha and later. + + Each event is described in more detail in Section 4.1. + +3.5. AUTHENTICATE + + Sent from the client to the server. The syntax is: + + "AUTHENTICATE" [ SP 1*HEXDIG / QuotedString ] CRLF + + This command is used to authenticate to the server. The provided string is + one of the following: + + * (For the HASHEDPASSWORD authentication method; see 3.21) + The original password represented as a QuotedString. + + * (For the COOKIE is authentication method; see 3.21) + The contents of the cookie file, formatted in hexadecimal + + * (For the SAFECOOKIE authentication method; see 3.21) + The HMAC based on the AUTHCHALLENGE message, in hexadecimal. + + The server responds with "250 OK" on success or "515 Bad authentication" if + the authentication cookie is incorrect. Tor closes the connection on an + authentication failure. + + The authentication token can be specified as either a quoted ASCII string, + or as an unquoted hexadecimal encoding of that same string (to avoid escaping + issues). + + For information on how the implementation securely stores authentication + information on disk, see section 5.1. + + Before the client has authenticated, no command other than + PROTOCOLINFO, AUTHCHALLENGE, AUTHENTICATE, or QUIT is valid. If the + controller sends any other command, or sends a malformed command, or + sends an unsuccessful AUTHENTICATE command, or sends PROTOCOLINFO or + AUTHCHALLENGE more than once, Tor sends an error reply and closes + the connection. + + To prevent some cross-protocol attacks, the AUTHENTICATE command is still + required even if all authentication methods in Tor are disabled. In this + case, the controller should just send "AUTHENTICATE" CRLF. + + (Versions of Tor before 0.1.2.16 and 0.2.0.4-alpha did not close the + connection after an authentication failure.) + +3.6. SAVECONF + + Sent from the client to the server. The syntax is: + + "SAVECONF" [SP "FORCE"] CRLF + + Instructs the server to write out its config options into its torrc. Server + returns "250 OK" if successful, or "551 Unable to write configuration + to disk" if it can't write the file or some other error occurs. + + If the %include option is used on torrc, SAVECONF will not write the + configuration to disk. If the flag string "FORCE" is provided, the + configuration will be overwritten even if %include is used. Using %include + on defaults-torrc does not affect SAVECONF. (Introduced in 0.3.1.1-alpha.) + + See also the "getinfo config-text" command, if the controller wants + to write the torrc file itself. + + See also the "getinfo config-can-saveconf" command, to tell if the FORCE + flag will be required. (Also introduced in 0.3.1.1-alpha.) + +3.7. SIGNAL + + Sent from the client to the server. The syntax is: + + "SIGNAL" SP Signal CRLF + + Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" / + "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" / + "CLEARDNSCACHE" / "HEARTBEAT" / "ACTIVE" / "DORMANT" + + The meaning of the signals are: + + RELOAD -- Reload: reload config items. + SHUTDOWN -- Controlled shutdown: if server is an OP, exit immediately. + If it's an OR, close listeners and exit after + ShutdownWaitLength seconds. + DUMP -- Dump stats: log information about open connections and + circuits. + DEBUG -- Debug: switch all open logs to loglevel debug. + HALT -- Immediate shutdown: clean up and exit now. + CLEARDNSCACHE -- Forget the client-side cached IPs for all hostnames. + NEWNYM -- Switch to clean circuits, so new application requests + don't share any circuits with old ones. Also clears + the client-side DNS cache. (Tor MAY rate-limit its + response to this signal.) + HEARTBEAT -- Make Tor dump an unscheduled Heartbeat message to log. + DORMANT -- Tell Tor to become "dormant". A dormant Tor will + try to avoid CPU and network usage until it receives + user-initiated network request. (Don't use this + on relays or hidden services yet!) + ACTIVE -- Tell Tor to stop being "dormant", as if it had received + a user-initiated network request. + + The server responds with "250 OK" if the signal is recognized (or simply + closes the socket if it was asked to close immediately), or "552 + Unrecognized signal" if the signal is unrecognized. + + Note that not all of these signals have POSIX signal equivalents. The + ones that do are as below. You may also use these POSIX names for the + signal that have them. + + RELOAD: HUP + SHUTDOWN: INT + HALT: TERM + DUMP: USR1 + DEBUG: USR2 + + [SIGNAL DORMANT and SIGNAL ACTIVE were added in 0.4.0.1-alpha.] + +3.8. MAPADDRESS + + Sent from the client to the server. The syntax is: + + "MAPADDRESS" 1*(Address "=" Address SP) CRLF + + The first address in each pair is an "original" address; the second is a + "replacement" address. The client sends this message to the server in + order to tell it that future SOCKS requests for connections to the original + address should be replaced with connections to the specified replacement + address. If the addresses are well-formed, and the server is able to + fulfill the request, the server replies with a 250 message: + + 250-OldAddress1=NewAddress1 + 250 OldAddress2=NewAddress2 + + containing the source and destination addresses. If request is + malformed, the server replies with "512 syntax error in command + argument". If the server can't fulfill the request, it replies with + "451 resource exhausted". + + The client may decline to provide a body for the original address, and + instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or + "." for hostname), signifying that the server should choose the original + address itself, and return that address in the reply. The server + should ensure that it returns an element of address space that is unlikely + to be in actual use. If there is already an address mapped to the + destination address, the server may reuse that mapping. + + If the original address is already mapped to a different address, the old + mapping is removed. If the original address and the destination address + are the same, the server removes any mapping in place for the original + address. + + Example: + + C: MAPADDRESS 1.2.3.4=torproject.org + S: 250 1.2.3.4=torproject.org + + C: GETINFO address-mappings/control + S: 250-address-mappings/control=1.2.3.4 torproject.org NEVER + S: 250 OK + + C: MAPADDRESS 1.2.3.4=1.2.3.4 + S: 250 1.2.3.4=1.2.3.4 + + C: GETINFO address-mappings/control + S: 250-address-mappings/control= + S: 250 OK + + {Note: This feature is designed to be used to help Tor-ify applications + that need to use SOCKS4 or hostname-less SOCKS5. There are three + approaches to doing this: + + 1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead. + 2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS + feature) to resolve the hostname remotely. This doesn't work + with special addresses like x.onion or x.y.exit. + 3. Use MAPADDRESS to map an IP address to the desired hostname, and then + arrange to fool the application into thinking that the hostname + has resolved to that IP. + + This functionality is designed to help implement the 3rd approach.} + + Mappings set by the controller last until the Tor process exits: + they never expire. If the controller wants the mapping to last only + a certain time, then it must explicitly un-map the address when that + time has elapsed. + + MapAddress replies MAY contain mixed status codes. + + Example: + + C: MAPADDRESS xxx=@@@ 0.0.0.0=bogus1.google.com + S: 512-syntax error: invalid address '@@@' + S: 250 127.199.80.246=bogus1.google.com + +3.9. GETINFO + + Sent from the client to the server. The syntax is as for GETCONF: + + "GETINFO" 1*(SP keyword) CRLF + + Unlike GETCONF, this message is used for data that are not stored in the Tor + configuration file, and that may be longer than a single line. On success, + one ReplyLine is sent for each requested value, followed by a final 250 OK + ReplyLine. If a value fits on a single line, the format is: + + 250-keyword=value + If a value must be split over multiple lines, the format is: + + 250+keyword= + value + . + The server sends a 551 or 552 error on failure. + + Recognized keys and their values include: + + "version" -- The version of the server's software, which MAY include the + name of the software, such as "Tor 0.0.9.4". The name of the software, + if absent, is assumed to be "Tor". + + "config-file" -- The location of Tor's configuration file ("torrc"). + + "config-defaults-file" -- The location of Tor's configuration + defaults file ("torrc.defaults"). This file gets parsed before + torrc, and is typically used to replace Tor's default + configuration values. [First implemented in 0.2.3.9-alpha.] + + "config-text" -- The contents that Tor would write if you send it + a SAVECONF command, so the controller can write the file to + disk itself. [First implemented in 0.2.2.7-alpha.] + + "exit-policy/default" -- The default exit policy lines that Tor will + *append* to the ExitPolicy config option. + + "exit-policy/reject-private/default" -- The default exit policy lines + that Tor will *prepend* to the ExitPolicy config option when + ExitPolicyRejectPrivate is 1. + + "exit-policy/reject-private/relay" -- The relay-specific exit policy + lines that Tor will *prepend* to the ExitPolicy config option based + on the current values of ExitPolicyRejectPrivate and + ExitPolicyRejectLocalInterfaces. These lines are based on the public + addresses configured in the torrc and present on the relay's + interfaces. Will send 552 error if the server is not running as + onion router. Will send 551 on internal error which may be transient. + + "exit-policy/ipv4" + "exit-policy/ipv6" + "exit-policy/full" -- This OR's exit policy, in IPv4-only, IPv6-only, or + all-entries flavors. Handles errors in the same way as "exit-policy/ + reject-private/relay" does. + + "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest + server descriptor for a given OR. (Note that modern Tor clients + do not download server descriptors by default, but download + microdescriptors instead. If microdescriptors are enabled, you'll + need to use "md" instead.) + + "md/all" -- all known microdescriptors for the entire Tor network. + Each microdescriptor is terminated by a newline. + [First implemented in 0.3.5.1-alpha] + + "md/id/<OR identity>" or "md/name/<OR nickname>" -- the latest + microdescriptor for a given OR. Empty if we have no microdescriptor for + that OR (because we haven't downloaded one, or it isn't in the + consensus). [First implemented in 0.2.3.8-alpha.] + + "desc/download-enabled" -- "1" if we try to download router descriptors; + "0" otherwise. [First implemented in 0.3.2.1-alpha] + + "md/download-enabled" -- "1" if we try to download microdescriptors; + "0" otherwise. [First implemented in 0.3.2.1-alpha] + + "dormant" -- A nonnegative integer: zero if Tor is currently active and + building circuits, and nonzero if Tor has gone idle due to lack of use + or some similar reason. [First implemented in 0.2.3.16-alpha] + + "desc-annotations/id/<OR identity>" -- outputs the annotations string + (source, timestamp of arrival, purpose, etc) for the corresponding + descriptor. [First implemented in 0.2.0.13-alpha.] + + "extra-info/digest/<digest>" -- the extrainfo document whose digest (in + hex) is <digest>. Only available if we're downloading extra-info + documents. + + "ns/id/<OR identity>" or "ns/name/<OR nickname>" -- the latest router + status info (v3 directory style) for a given OR. Router status + info is as given in dir-spec.txt, and reflects the latest + consensus opinion about the + router in question. Like directory clients, controllers MUST + tolerate unrecognized flags and lines. The published date and + descriptor digest are those believed to be best by this Tor, + not necessarily those for a descriptor that Tor currently has. + [First implemented in 0.1.2.3-alpha.] + [In 0.2.0.9-alpha this switched from v2 directory style to v3] + + "ns/all" -- Router status info (v3 directory style) for all ORs we + that the consensus has an opinion about, joined by newlines. + [First implemented in 0.1.2.3-alpha.] + [In 0.2.0.9-alpha this switched from v2 directory style to v3] + + "ns/purpose/<purpose>" -- Router status info (v3 directory style) + for all ORs of this purpose. Mostly designed for /ns/purpose/bridge + queries. + [First implemented in 0.2.0.13-alpha.] + [In 0.2.0.9-alpha this switched from v2 directory style to v3] + [In versions before 0.4.1.1-alpha we set the Running flag on + bridges when /ns/purpose/bridge is accessed] + [In 0.4.1.1-alpha we set the Running flag on bridges when the + bridge networkstatus file is written to disk] + + "desc/all-recent" -- the latest server descriptor for every router that + Tor knows about. (See md note about "desc/id" and "desc/name" above.) + + "network-status" -- [Deprecated in 0.3.1.1-alpha, removed + in 0.4.5.1-alpha.] + + "address-mappings/all" + "address-mappings/config" + "address-mappings/cache" + "address-mappings/control" -- a \r\n-separated list of address + mappings, each in the form of "from-address to-address expiry". + The 'config' key returns those address mappings set in the + configuration; the 'cache' key returns the mappings in the + client-side DNS cache; the 'control' key returns the mappings set + via the control interface; the 'all' target returns the mappings + set through any mechanism. + Expiry is formatted as with ADDRMAP events, except that "expiry" is + always a time in UTC or the string "NEVER"; see section 4.1.7. + First introduced in 0.2.0.3-alpha. + + "addr-mappings/*" -- as for address-mappings/*, but without the + expiry portion of the value. Use of this value is deprecated + since 0.2.0.3-alpha; use address-mappings instead. + + "address" -- the best guess at our external IP address. If we + have no guess, return a 551 error. (Added in 0.1.2.2-alpha) + + "address/v4" + "address/v6" + the best guess at our respective external IPv4 or IPv6 address. + If we have no guess, return a 551 error. (Added in 0.4.5.1-alpha) + + "fingerprint" -- the contents of the fingerprint file that Tor + writes as a relay, or a 551 if we're not a relay currently. + (Added in 0.1.2.3-alpha) + + "circuit-status" + A series of lines as for a circuit status event. Each line is of + the form described in section 4.1.1, omitting the initial + "650 CIRC ". Note that clients must be ready to accept additional + arguments as described in section 4.1. + + "stream-status" + A series of lines as for a stream status event. Each is of the form: + StreamID SP StreamStatus SP CircuitID SP Target CRLF + + "orconn-status" + A series of lines as for an OR connection status event. In Tor + 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor + 0.2.2.1-alpha and later by default, each line is of the form: + LongName SP ORStatus CRLF + + In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line + is of the form: + ServerID SP ORStatus CRLF + + "entry-guards" + A series of lines listing the currently chosen entry guards, if any. + In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor + 0.2.2.1-alpha and later by default, each line is of the form: + LongName SP Status [SP ISOTime] CRLF + + In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, each line + is of the form: + ServerID2 SP Status [SP ISOTime] CRLF + ServerID2 = Nickname / 40*HEXDIG + + The definition of Status is the same for both: + Status = "up" / "never-connected" / "down" / + "unusable" / "unlisted" + + [From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called + "helper-nodes". Tor still supports calling "helper-nodes", but it + is deprecated and should not be used.] + + [Older versions of Tor (before 0.1.2.x-final) generated 'down' instead + of unlisted/unusable. Between 0.1.2.x-final and 0.2.6.3-alpha, + 'down' was never generated.] + + [XXXX ServerID2 differs from ServerID in not prefixing fingerprints + with a $. This is an implementation error. It would be nice to add + the $ back in if we can do so without breaking compatibility.] + + "traffic/read" -- Total bytes read (downloaded). + + "traffic/written" -- Total bytes written (uploaded). + + "uptime" -- Uptime of the Tor daemon (in seconds). Added in + 0.3.5.1-alpha. + + "accounting/enabled" + "accounting/hibernating" + "accounting/bytes" + "accounting/bytes-left" + "accounting/interval-start" + "accounting/interval-wake" + "accounting/interval-end" + Information about accounting status. If accounting is enabled, + "enabled" is 1; otherwise it is 0. The "hibernating" field is "hard" + if we are accepting no data; "soft" if we're accepting no new + connections, and "awake" if we're not hibernating at all. The "bytes" + and "bytes-left" fields contain (read-bytes SP write-bytes), for the + start and the rest of the interval respectively. The 'interval-start' + and 'interval-end' fields are the borders of the current interval; the + 'interval-wake' field is the time within the current interval (if any) + where we plan[ned] to start being active. The times are UTC. + + "config/names" + A series of lines listing the available configuration options. Each is + of the form: + OptionName SP OptionType [ SP Documentation ] CRLF + OptionName = Keyword + OptionType = "Integer" / "TimeInterval" / "TimeMsecInterval" / + "DataSize" / "Float" / "Boolean" / "Time" / "CommaList" / + "Dependent" / "Virtual" / "String" / "LineList" + Documentation = Text + Note: The incorrect spelling "Dependant" was used from the time this key + was introduced in Tor 0.1.1.4-alpha until it was corrected in Tor + 0.3.0.2-alpha. It is recommended that clients accept both spellings. + + "config/defaults" + A series of lines listing default values for each configuration + option. Options which don't have a valid default don't show up + in the list. Introduced in Tor 0.2.4.1-alpha. + OptionName SP OptionValue CRLF + OptionName = Keyword + OptionValue = Text + + "info/names" + A series of lines listing the available GETINFO options. Each is of + one of these forms: + OptionName SP Documentation CRLF + OptionPrefix SP Documentation CRLF + OptionPrefix = OptionName "/*" + The OptionPrefix form indicates a number of options beginning with the + prefix. So if "config/*" is listed, other options beginning with + "config/" will work, but "config/*" itself is not an option. + + "events/names" + A space-separated list of all the events supported by this version of + Tor's SETEVENTS. + + "features/names" + A space-separated list of all the features supported by this version + of Tor's USEFEATURE. + + "signal/names" + A space-separated list of all the values supported by the SIGNAL + command. + + "ip-to-country/ipv4-available" + "ip-to-country/ipv6-available" + "1" if the relevant geoip or geoip6 database is present; "0" otherwise. + This field was added in Tor 0.3.2.1-alpha. + + "ip-to-country/*" + Maps IP addresses to 2-letter country codes. For example, + "GETINFO ip-to-country/18.0.0.1" should give "US". + + "process/pid" -- Process id belonging to the main tor process. + "process/uid" -- User id running the tor process, -1 if unknown (this is + unimplemented on Windows, returning -1). + "process/user" -- Username under which the tor process is running, + providing an empty string if none exists (this is unimplemented on + Windows, returning an empty string). + "process/descriptor-limit" -- Upper bound on the file descriptor limit, -1 + if unknown + + "dir/status-vote/current/consensus" [added in Tor 0.2.1.6-alpha] + "dir/status-vote/current/consensus-microdesc" [added in Tor 0.4.3.1-alpha] + "dir/status/authority" + "dir/status/fp/<F>" + "dir/status/fp/<F1>+<F2>+<F3>" + "dir/status/all" + "dir/server/fp/<F>" + "dir/server/fp/<F1>+<F2>+<F3>" + "dir/server/d/<D>" + "dir/server/d/<D1>+<D2>+<D3>" + "dir/server/authority" + "dir/server/all" + A series of lines listing directory contents, provided according to the + specification for the URLs listed in Section 4.4 of dir-spec.txt. Note + that Tor MUST NOT provide private information, such as descriptors for + routers not marked as general-purpose. When asked for 'authority' + information for which this Tor is not authoritative, Tor replies with + an empty string. + + Note that, as of Tor 0.2.3.3-alpha, Tor clients don't download server + descriptors anymore, but microdescriptors. So, a "551 Servers + unavailable" reply to all "GETINFO dir/server/*" requests is actually + correct. If you have an old program which absolutely requires server + descriptors to work, try setting UseMicrodescriptors 0 or + FetchUselessDescriptors 1 in your client's torrc. + + "status/circuit-established" + "status/enough-dir-info" + "status/good-server-descriptor" + "status/accepted-server-descriptor" + "status/..." + These provide the current internal Tor values for various Tor + states. See Section 4.1.10 for explanations. (Only a few of the + status events are available as getinfo's currently. Let us know if + you want more exposed.) + "status/reachability-succeeded/or" + 0 or 1, depending on whether we've found our ORPort reachable. + "status/reachability-succeeded/dir" + 0 or 1, depending on whether we've found our DirPort reachable. + 1 if there is no DirPort, and therefore no need for a reachability + check. + "status/reachability-succeeded" + "OR=" ("0"/"1") SP "DIR=" ("0"/"1") + Combines status/reachability-succeeded/*; controllers MUST ignore + unrecognized elements in this entry. + "status/bootstrap-phase" + Returns the most recent bootstrap phase status event + sent. Specifically, it returns a string starting with either + "NOTICE BOOTSTRAP ..." or "WARN BOOTSTRAP ...". Controllers should + use this getinfo when they connect or attach to Tor to learn its + current bootstrap state. + "status/version/recommended" + List of currently recommended versions. + "status/version/current" + Status of the current version. One of: new, old, unrecommended, + recommended, new in series, obsolete, unknown. + "status/clients-seen" + A summary of which countries we've seen clients from recently, + formatted the same as the CLIENTS_SEEN status event described in + Section 4.1.14. This GETINFO option is currently available only + for bridge relays. + "status/fresh-relay-descs" + Provides fresh server and extra-info descriptors for our relay. Note + this is *not* the latest descriptors we've published, but rather what we + would generate if we needed to make a new descriptor right now. + + "net/listeners/*" + + A quoted, space-separated list of the locations where Tor is listening + for connections of the specified type. These can contain IPv4 + network address... + + "127.0.0.1:9050" "127.0.0.1:9051" + + ... or local unix sockets... + + "unix:/home/my_user/.tor/socket" + + ... or IPv6 network addresses: + + "[2001:0db8:7000:0000:0000:dead:beef:1234]:9050" + + [New in Tor 0.2.2.26-beta.] + + "net/listeners/or" + + Listeners for OR connections. Talks Tor protocol as described in + tor-spec.txt. + + "net/listeners/dir" + + Listeners for Tor directory protocol, as described in dir-spec.txt. + + "net/listeners/socks" + + Listeners for onion proxy connections that talk SOCKS4/4a/5 protocol. + + "net/listeners/trans" + + Listeners for transparent connections redirected by firewall, such as + pf or netfilter. + + "net/listeners/natd" + + Listeners for transparent connections redirected by natd. + + "net/listeners/dns" + + Listeners for a subset of DNS protocol that Tor network supports. + + "net/listeners/control" + + Listeners for Tor control protocol, described herein. + + "net/listeners/extor" + + Listeners corresponding to Extended ORPorts for integration with + pluggable transports. See proposals 180 and 196. + + "net/listeners/httptunnel" + + Listeners for onion proxy connections that leverage HTTP CONNECT + tunnelling. + + [The extor and httptunnel lists were added in 0.3.2.12, 0.3.3.10, and + 0.3.4.6-rc.] + + "dir-usage" + A newline-separated list of how many bytes we've served to answer + each type of directory request. The format of each line is: + Keyword 1*SP Integer 1*SP Integer + where the first integer is the number of bytes written, and the second + is the number of requests answered. + + [This feature was added in Tor 0.2.2.1-alpha, and removed in + Tor 0.2.9.1-alpha. Even when it existed, it only provided + useful output when the Tor client was built with either the + INSTRUMENT_DOWNLOADS or RUNNING_DOXYGEN compile-time options.] + + "bw-event-cache" + A space-separated summary of recent BW events in chronological order + from oldest to newest. Each event is represented by a comma-separated + tuple of "R,W", R is the number of bytes read, and W is the number of + bytes written. These entries each represent about one second's worth + of traffic. + [New in Tor 0.2.6.3-alpha] + + "consensus/valid-after" + "consensus/fresh-until" + "consensus/valid-until" + Each of these produces an ISOTime describing part of the lifetime of + the current (valid, accepted) consensus that Tor has. + [New in Tor 0.2.6.3-alpha] + + "hs/client/desc/id/<ADDR>" + Prints the content of the hidden service descriptor corresponding to + the given <ADDR> which is an onion address without the ".onion" part. + The client's cache is queried to find the descriptor. The format of + the descriptor is described in section 1.3 of the rend-spec.txt + document. + + If <ADDR> is unrecognized or if not found in the cache, a 551 error is + returned. + + [New in Tor 0.2.7.1-alpha] + [HS v3 support added 0.3.3.1-alpha] + + "hs/service/desc/id/<ADDR>" + Prints the content of the hidden service descriptor corresponding to + the given <ADDR> which is an onion address without the ".onion" part. + The service's local descriptor cache is queried to find the descriptor. + The format of the descriptor is described in section 1.3 of the + rend-spec.txt document. + + If <ADDR> is unrecognized or if not found in the cache, a 551 error is + returned. + + [New in Tor 0.2.7.2-alpha] + [HS v3 support added 0.3.3.1-alpha] + + "onions/current" + "onions/detached" + A newline-separated list of the Onion ("Hidden") Services created + via the "ADD_ONION" command. The 'current' key returns Onion Services + belonging to the current control connection. The 'detached' key + returns Onion Services detached from the parent control connection + (as in, belonging to no control connection). + The format of each line is: + HSAddress + [New in Tor 0.2.7.1-alpha.] + [HS v3 support added 0.3.3.1-alpha] + + "network-liveness" + The string "up" or "down", indicating whether we currently believe the + network is reachable. + + "downloads/" + The keys under downloads/ are used to query download statuses; they all + return either a sequence of newline-terminated hex encoded digests, or + a "serialized download status" as follows: + + SerializedDownloadStatus = + -- when do we plan to next attempt to download this object? + "next-attempt-at" SP ISOTime CRLF + -- how many times have we failed since the last success? + "n-download-failures" SP UInt CRLF + -- how many times have we tried to download this? + "n-download-attempts" SP UInt CRLF + -- according to which schedule rule will we download this? + "schedule" SP DownloadSchedule CRLF + -- do we want to fetch this from an authority, or will any cache do? + "want-authority" SP DownloadWantAuthority CRLF + -- do we increase our download delay whenever we fail to fetch this, + -- or whenever we attempt fetching this? + "increment-on" SP DownloadIncrementOn CRLF + -- do we increase the download schedule deterministically, or at + -- random? + "backoff" SP DownloadBackoff CRLF + [ + -- with an exponential backoff, where are we in the schedule? + "last-backoff-position" Uint CRLF + -- with an exponential backoff, what was our last delay? + "last-delay-used UInt CRLF + ] + + where + + DownloadSchedule = + "DL_SCHED_GENERIC" / "DL_SCHED_CONSENSUS" / "DL_SCHED_BRIDGE" + DownloadWantAuthority = + "DL_WANT_ANY_DIRSERVER" / "DL_WANT_AUTHORITY" + DownloadIncrementOn = + "DL_SCHED_INCREMENT_FAILURE" / "DL_SCHED_INCREMENT_ATTEMPT" + DownloadBackoff = + "DL_SCHED_DETERMINISTIC" / "DL_SCHED_RANDOM_EXPONENTIAL" + + The optional last two lines must be present if DownloadBackoff is + "DL_SCHED_RANDOM_EXPONENTIAL" and must be absent if DownloadBackoff + is "DL_SCHED_DETERMINISTIC". + + In detail, the keys supported are: + + "downloads/networkstatus/ns" + The SerializedDownloadStatus for the NS-flavored consensus for + whichever bootstrap state Tor is currently in. + + "downloads/networkstatus/ns/bootstrap" + The SerializedDownloadStatus for the NS-flavored consensus at + bootstrap time, regardless of whether we are currently bootstrapping. + + "downloads/networkstatus/ns/running" + + The SerializedDownloadStatus for the NS-flavored consensus when + running, regardless of whether we are currently bootstrapping. + + "downloads/networkstatus/microdesc" + The SerializedDownloadStatus for the microdesc-flavored consensus for + whichever bootstrap state Tor is currently in. + + "downloads/networkstatus/microdesc/bootstrap" + The SerializedDownloadStatus for the microdesc-flavored consensus at + bootstrap time, regardless of whether we are currently bootstrapping. + + "downloads/networkstatus/microdesc/running" + The SerializedDownloadStatus for the microdesc-flavored consensus when + running, regardless of whether we are currently bootstrapping. + + "downloads/cert/fps" + + A newline-separated list of hex-encoded digests for authority + certificates for which we have download status available. + + "downloads/cert/fp/<Fingerprint>" + A SerializedDownloadStatus for the default certificate for the + identity digest <Fingerprint> returned by the downloads/cert/fps key. + + "downloads/cert/fp/<Fingerprint>/sks" + A newline-separated list of hex-encoded signing key digests for the + authority identity digest <Fingerprint> returned by the + downloads/cert/fps key. + + "downloads/cert/fp/<Fingerprint>/<SKDigest>" + A SerializedDownloadStatus for the certificate for the identity + digest <Fingerprint> returned by the downloads/cert/fps key and signing + key digest <SKDigest> returned by the downloads/cert/fp/<Fingerprint>/ + sks key. + + "downloads/desc/descs" + A newline-separated list of hex-encoded router descriptor digests + [note, not identity digests - the Tor process may not have seen them + yet while downloading router descriptors]. If the Tor process is not + using a NS-flavored consensus, a 551 error is returned. + + "downloads/desc/<Digest>" + A SerializedDownloadStatus for the router descriptor with digest + <Digest> as returned by the downloads/desc/descs key. If the Tor + process is not using a NS-flavored consensus, a 551 error is returned. + + "downloads/bridge/bridges" + A newline-separated list of hex-encoded bridge identity digests. If + the Tor process is not using bridges, a 551 error is returned. + + "downloads/bridge/<Digest>" + A SerializedDownloadStatus for the bridge descriptor with identity + digest <Digest> as returned by the downloads/bridge/bridges key. If + the Tor process is not using bridges, a 551 error is returned. + + "sr/current" + "sr/previous" + The current or previous shared random value, as received in the + consensus, base-64 encoded. An empty value means that either + the consensus has no shared random value, or Tor has no consensus. + + "current-time/local" + "current-time/utc" + The current system or UTC time, as returned by the system, in ISOTime2 + format. (Introduced in 0.3.4.1-alpha.) + + "stats/ntor/requested" + "stats/ntor/assigned" + The NTor circuit onion handshake rephist values which are requested or + assigned. (Introduced in 0.4.5.1-alpha) + + "stats/tap/requested" + "stats/tap/assigned" + The TAP circuit onion handshake rephist values which are requested or + assigned. (Introduced in 0.4.5.1-alpha) + + "config-can-saveconf" + 0 or 1, depending on whether it is possible to use SAVECONF without the + FORCE flag. (Introduced in 0.3.1.1-alpha.) + + "limits/max-mem-in-queues" + The amount of memory that Tor's out-of-memory checker will allow + Tor to allocate (in places it can see) before it starts freeing memory + and killing circuits. See the MaxMemInQueues option for more + details. Unlike the option, this value reflects Tor's actual limit, and + may be adjusted depending on the available system memory rather than on + the MaxMemInQueues option. (Introduced in 0.2.5.4-alpha) + + Examples: + + C: GETINFO version desc/name/moria1 + S: 250+desc/name/moria= + S: [Descriptor for moria] + S: . + S: 250-version=Tor 0.1.1.0-alpha-cvs + S: 250 OK + +3.10. EXTENDCIRCUIT + + Sent from the client to the server. The format is: + + "EXTENDCIRCUIT" SP CircuitID + [SP ServerSpec *("," ServerSpec)] + [SP "purpose=" Purpose] CRLF + + This request takes one of two forms: either the CircuitID is zero, in + which case it is a request for the server to build a new circuit, + or the CircuitID is nonzero, in which case it is a request for the + server to extend an existing circuit with that ID according to the + specified path. + + If the CircuitID is 0, the controller has the option of providing + a path for Tor to use to build the circuit. If it does not provide + a path, Tor will select one automatically from high capacity nodes + according to path-spec.txt. + + If CircuitID is 0 and "purpose=" is specified, then the circuit's + purpose is set. Two choices are recognized: "general" and + "controller". If not specified, circuits are created as "general". + + If the request is successful, the server sends a reply containing a + message body consisting of the CircuitID of the (maybe newly created) + circuit. The syntax is "250" SP "EXTENDED" SP CircuitID CRLF. + +3.11. SETCIRCUITPURPOSE + + Sent from the client to the server. The format is: + + "SETCIRCUITPURPOSE" SP CircuitID SP "purpose=" Purpose CRLF + + This changes the circuit's purpose. See EXTENDCIRCUIT above for details. + +3.12. SETROUTERPURPOSE + + Sent from the client to the server. The format is: + + "SETROUTERPURPOSE" SP NicknameOrKey SP Purpose CRLF + + This changes the descriptor's purpose. See +POSTDESCRIPTOR below + for details. + + NOTE: This command was disabled and made obsolete as of Tor + 0.2.0.8-alpha. It doesn't exist anymore, and is listed here only for + historical interest. + +3.13. ATTACHSTREAM + + Sent from the client to the server. The syntax is: + + "ATTACHSTREAM" SP StreamID SP CircuitID [SP "HOP=" HopNum] CRLF + + This message informs the server that the specified stream should be + associated with the specified circuit. Each stream may be associated with + at most one circuit, and multiple streams may share the same circuit. + Streams can only be attached to completed circuits (that is, circuits that + have sent a circuit status 'BUILT' event or are listed as built in a + GETINFO circuit-status request). + + If the circuit ID is 0, responsibility for attaching the given stream is + returned to Tor. + + If HOP=HopNum is specified, Tor will choose the HopNumth hop in the + circuit as the exit node, rather than the last node in the circuit. + Hops are 1-indexed; generally, it is not permitted to attach to hop 1. + + Tor responds with "250 OK" if it can attach the stream, 552 if the + circuit or stream didn't exist, 555 if the stream isn't in an + appropriate state to be attached (e.g. it's already open), or 551 if + the stream couldn't be attached for another reason. + + {Implementation note: Tor will close unattached streams by itself, + roughly two minutes after they are born. Let the developers know if + that turns out to be a problem.} + + {Implementation note: By default, Tor automatically attaches streams to + circuits itself, unless the configuration variable + "__LeaveStreamsUnattached" is set to "1". Attempting to attach streams + via TC when "__LeaveStreamsUnattached" is false may cause a race between + Tor and the controller, as both attempt to attach streams to circuits.} + + {Implementation note: You can try to attachstream to a stream that + has already sent a connect or resolve request but hasn't succeeded + yet, in which case Tor will detach the stream from its current circuit + before proceeding with the new attach request.} + +3.14. POSTDESCRIPTOR + + Sent from the client to the server. The syntax is: + + "+POSTDESCRIPTOR" [SP "purpose=" Purpose] [SP "cache=" Cache] + CRLF Descriptor CRLF "." CRLF + + This message informs the server about a new descriptor. If Purpose is + specified, it must be either "general", "controller", or "bridge", + else we return a 552 error. The default is "general". + + If Cache is specified, it must be either "no" or "yes", else we + return a 552 error. If Cache is not specified, Tor will decide for + itself whether it wants to cache the descriptor, and controllers + must not rely on its choice. + + The descriptor, when parsed, must contain a number of well-specified + fields, including fields for its nickname and identity. + + If there is an error in parsing the descriptor, the server must send a + "554 Invalid descriptor" reply. If the descriptor is well-formed but + the server chooses not to add it, it must reply with a 251 message + whose body explains why the server was not added. If the descriptor + is added, Tor replies with "250 OK". + +3.15. REDIRECTSTREAM + + Sent from the client to the server. The syntax is: + + "REDIRECTSTREAM" SP StreamID SP Address [SP Port] CRLF + + Tells the server to change the exit address on the specified stream. If + Port is specified, changes the destination port as well. No remapping + is performed on the new provided address. + + To be sure that the modified address will be used, this event must be sent + after a new stream event is received, and before attaching this stream to + a circuit. + + Tor replies with "250 OK" on success. + +3.16. CLOSESTREAM + + Sent from the client to the server. The syntax is: + + "CLOSESTREAM" SP StreamID SP Reason *(SP Flag) CRLF + + Tells the server to close the specified stream. The reason should be one + of the Tor RELAY_END reasons given in tor-spec.txt, as a decimal. Flags is + not used currently; Tor servers SHOULD ignore unrecognized flags. Tor may + hold the stream open for a while to flush any data that is pending. + + Tor replies with "250 OK" on success, or a 512 if there aren't enough + arguments, or a 552 if it doesn't recognize the StreamID or reason. + +3.17. CLOSECIRCUIT + + The syntax is: + + "CLOSECIRCUIT" SP CircuitID *(SP Flag) CRLF + Flag = "IfUnused" + + Tells the server to close the specified circuit. If "IfUnused" is + provided, do not close the circuit unless it is unused. + + Other flags may be defined in the future; Tor SHOULD ignore unrecognized + flags. + + Tor replies with "250 OK" on success, or a 512 if there aren't enough + arguments, or a 552 if it doesn't recognize the CircuitID. + +3.18. QUIT + + Tells the server to hang up on this controller connection. This command + can be used before authenticating. + +3.19. USEFEATURE + + Adding additional features to the control protocol sometimes will break + backwards compatibility. Initially such features are added into Tor and + disabled by default. USEFEATURE can enable these additional features. + + The syntax is: + + "USEFEATURE" *(SP FeatureName) CRLF + FeatureName = 1*(ALPHA / DIGIT / "_" / "-") + + Feature names are case-insensitive. + + Once enabled, a feature stays enabled for the duration of the connection + to the controller. A new connection to the controller must be opened to + disable an enabled feature. + + Features are a forward-compatibility mechanism; each feature will eventually + become a standard part of the control protocol. Once a feature becomes part + of the protocol, it is always-on. Each feature documents the version it was + introduced as a feature and the version in which it became part of the + protocol. + + Tor will ignore a request to use any feature that is always-on. Tor will give + a 552 error in response to an unrecognized feature. + + EXTENDED_EVENTS + + Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to + request the extended event syntax. + + This feature was first introduced in 0.1.2.3-alpha. It is always-on + and part of the protocol in Tor 0.2.2.1-alpha and later. + + VERBOSE_NAMES + + Replaces ServerID with LongName in events and GETINFO results. LongName + provides a Fingerprint for all routers, an indication of Named status, + and a Nickname if one is known. LongName is strictly more informative + than ServerID, which only provides either a Fingerprint or a Nickname. + + This feature was first introduced in 0.1.2.2-alpha. It is always-on and + part of the protocol in Tor 0.2.2.1-alpha and later. + +3.20. RESOLVE + + The syntax is + + "RESOLVE" *Option *Address CRLF + Option = "mode=reverse" + Address = a hostname or IPv4 address + + This command launches a remote hostname lookup request for every specified + request (or reverse lookup if "mode=reverse" is specified). Note that the + request is done in the background: to see the answers, your controller will + need to listen for ADDRMAP events; see 4.1.7 below. + + [Added in Tor 0.2.0.3-alpha] + +3.21. PROTOCOLINFO + + The syntax is: + + "PROTOCOLINFO" *(SP PIVERSION) CRLF + + The server reply format is: + + "250-PROTOCOLINFO" SP PIVERSION CRLF *InfoLine "250 OK" CRLF + + InfoLine = AuthLine / VersionLine / OtherLine + + AuthLine = "250-AUTH" SP "METHODS=" AuthMethod *("," AuthMethod) + *(SP "COOKIEFILE=" AuthCookieFile) CRLF + VersionLine = "250-VERSION" SP "Tor=" TorVersion OptArguments CRLF + + AuthMethod = + "NULL" / ; No authentication is required + "HASHEDPASSWORD" / ; A controller must supply the original password + "COOKIE" / ; ... or supply the contents of a cookie file + "SAFECOOKIE" ; ... or prove knowledge of a cookie file's contents + + AuthCookieFile = QuotedString + TorVersion = QuotedString + + OtherLine = "250-" Keyword OptArguments CRLF + + PIVERSION: 1*DIGIT + + This command tells the controller what kinds of authentication are + supported. + + Tor MAY give its InfoLines in any order; controllers MUST ignore InfoLines + with keywords they do not recognize. Controllers MUST ignore extraneous + data on any InfoLine. + + PIVERSION is there in case we drastically change the syntax one day. For + now it should always be "1". Controllers MAY provide a list of the + protocolinfo versions they support; Tor MAY select a version that the + controller does not support. + + AuthMethod is used to specify one or more control authentication + methods that Tor currently accepts. + + AuthCookieFile specifies the absolute path and filename of the + authentication cookie that Tor is expecting and is provided iff the + METHODS field contains the method "COOKIE" and/or "SAFECOOKIE". + Controllers MUST handle escape sequences inside this string. + + All authentication cookies are 32 bytes long. Controllers MUST NOT + use the contents of a non-32-byte-long file as an authentication + cookie. + + If the METHODS field contains the method "SAFECOOKIE", every + AuthCookieFile must contain the same authentication cookie. + + The COOKIE authentication method exposes the user running a + controller to an unintended information disclosure attack whenever + the controller has greater filesystem read access than the process + that it has connected to. (Note that a controller may connect to a + process other than Tor.) It is almost never safe to use, even if + the controller's user has explicitly specified which filename to + read an authentication cookie from. For this reason, the COOKIE + authentication method has been deprecated and will be removed from + a future version of Tor. + + The VERSION line contains the Tor version. + + [Unlike other commands besides AUTHENTICATE, PROTOCOLINFO may be used (but + only once!) before AUTHENTICATE.] + + [PROTOCOLINFO was not supported before Tor 0.2.0.5-alpha.] + +3.22. LOADCONF + + The syntax is: + + "+LOADCONF" CRLF ConfigText CRLF "." CRLF + + This command allows a controller to upload the text of a config file + to Tor over the control port. This config file is then loaded as if + it had been read from disk. + + [LOADCONF was added in Tor 0.2.1.1-alpha.] + +3.23. TAKEOWNERSHIP + + The syntax is: + + "TAKEOWNERSHIP" CRLF + + This command instructs Tor to shut down when this control + connection is closed. This command affects each control connection + that sends it independently; if multiple control connections send + the TAKEOWNERSHIP command to a Tor instance, Tor will shut down when + any of those connections closes. + + (As of Tor 0.2.5.2-alpha, Tor does not wait a while for circuits to + close when shutting down because of an exiting controller. If you + want to ensure a clean shutdown--and you should!--then send "SIGNAL + SHUTDOWN" and wait for the Tor process to close.) + + This command is intended to be used with the + __OwningControllerProcess configuration option. A controller that + starts a Tor process which the user cannot easily control or stop + should 'own' that Tor process: + + * When starting Tor, the controller should specify its PID in an + __OwningControllerProcess on Tor's command line. This will + cause Tor to poll for the existence of a process with that PID, + and exit if it does not find such a process. (This is not a + completely reliable way to detect whether the 'owning + controller' is still running, but it should work well enough in + most cases.) + + * Once the controller has connected to Tor's control port, it + should send the TAKEOWNERSHIP command along its control + connection. At this point, *both* the TAKEOWNERSHIP command and + the __OwningControllerProcess option are in effect: Tor will + exit when the control connection ends *and* Tor will exit if it + detects that there is no process with the PID specified in the + __OwningControllerProcess option. + + * After the controller has sent the TAKEOWNERSHIP command, it + should send "RESETCONF __OwningControllerProcess" along its + control connection. This will cause Tor to stop polling for the + existence of a process with its owning controller's PID; Tor + will still exit when the control connection ends. + + [TAKEOWNERSHIP was added in Tor 0.2.2.28-beta.] + +3.24. AUTHCHALLENGE + + The syntax is: + + "AUTHCHALLENGE" SP "SAFECOOKIE" + SP ClientNonce + CRLF + + ClientNonce = 2*HEXDIG / QuotedString + + This command is used to begin the authentication routine for the + SAFECOOKIE method of authentication. + + If the server accepts the command, the server reply format is: + + "250 AUTHCHALLENGE" + SP "SERVERHASH=" ServerHash + SP "SERVERNONCE=" ServerNonce + CRLF + + ServerHash = 64*64HEXDIG + ServerNonce = 64*64HEXDIG + + The ClientNonce, ServerHash, and ServerNonce values are + encoded/decoded in the same way as the argument passed to the + AUTHENTICATE command. ServerNonce MUST be 32 bytes long. + + ServerHash is computed as: + + HMAC-SHA256("Tor safe cookie authentication server-to-controller hash", + CookieString | ClientNonce | ServerNonce) + + (with the HMAC key as its first argument) + + After a controller sends a successful AUTHCHALLENGE command, the + next command sent on the connection must be an AUTHENTICATE command, + and the only authentication string which that AUTHENTICATE command + will accept is: + + HMAC-SHA256("Tor safe cookie authentication controller-to-server hash", + CookieString | ClientNonce | ServerNonce) + + [Unlike other commands besides AUTHENTICATE, AUTHCHALLENGE may be + used (but only once!) before AUTHENTICATE.] + + [AUTHCHALLENGE was added in Tor 0.2.3.13-alpha.] + +3.25. DROPGUARDS + + The syntax is: + + "DROPGUARDS" CRLF + + Tells the server to drop all guard nodes. Do not invoke this command + lightly; it can increase vulnerability to tracking attacks over time. + + Tor replies with "250 OK" on success. + + [DROPGUARDS was added in Tor 0.2.5.2-alpha.] + +3.26. HSFETCH + + The syntax is: + + "HSFETCH" SP (HSAddress / "v" Version "-" DescId) + *[SP "SERVER=" Server] CRLF + + HSAddress = 16*Base32Character / 56*Base32Character + Version = "2" / "3" + DescId = 32*Base32Character + Server = LongName + + This command launches hidden service descriptor fetch(es) for the given + HSAddress or DescId. + + HSAddress can be version 2 or version 3 addresses. DescIDs can only be + version 2 IDs. Version 2 addresses consist of 16*Base32Character and + version 3 addresses consist of 56*Base32Character. + + If a DescId is specified, at least one Server MUST also be provided, + otherwise a 512 error is returned. If no DescId and Server(s) are specified, + it behaves like a normal Tor client descriptor fetch. If one or more + Server are given, they are used instead triggering a fetch on each of them + in parallel. + + The caching behavior when fetching a descriptor using this command is + identical to normal Tor client behavior. + + Details on how to compute a descriptor id (DescId) can be found in + rend-spec.txt section 1.3. + + If any values are unrecognized, a 513 error is returned and the command is + stopped. On success, Tor replies "250 OK" then Tor MUST eventually follow + this with both a HS_DESC and HS_DESC_CONTENT events with the results. If + SERVER is specified then events are emitted for each location. + + Examples are: + + C: HSFETCH v2-gezdgnbvgy3tqolbmjrwizlgm5ugs2tl + SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31 + S: 250 OK + + C: HSFETCH ajkhdsfuygaesfaa + S: 250 OK + + C: HSFETCH vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd + S: 250 OK + + [HSFETCH was added in Tor 0.2.7.1-alpha] + [HS v3 support added 0.4.1.1-alpha] + +3.27. ADD_ONION + + The syntax is: + + "ADD_ONION" SP KeyType ":" KeyBlob + [SP "Flags=" Flag *("," Flag)] + [SP "MaxStreams=" NumStreams] + 1*(SP "Port=" VirtPort ["," Target]) + *(SP "ClientAuth=" ClientName [":" ClientBlob]) CRLF + *(SP "ClientAuthV3=" V3Key) CRLF + + KeyType = + "NEW" / ; The server should generate a key of algorithm KeyBlob + "RSA1024" / ; The server should use the 1024 bit RSA key provided + in as KeyBlob (v2). + "ED25519-V3"; The server should use the ed25519 v3 key provided in as + KeyBlob (v3). + + KeyBlob = + "BEST" / ; The server should generate a key using the "best" + supported algorithm (KeyType == "NEW"). + [As of 0.4.2.3-alpha, ED25519-V3 is used] + "RSA1024" / ; The server should generate a 1024 bit RSA key + (KeyType == "NEW") (v2). + "ED25519-V3"; The server should generate an ed25519 private key + (KeyType == "NEW") (v3). + String ; A serialized private key (without whitespace) + + Flag = + "DiscardPK" / ; The server should not include the newly generated + private key as part of the response. + "Detach" / ; Do not associate the newly created Onion Service + to the current control connection. + "BasicAuth" / ; Client authorization is required using the "basic" + method (v2 only). + "V3Auth" / ; Version 3 client authorization is required (v3 only). + + "NonAnonymous" /; Add a non-anonymous Single Onion Service. Tor + checks this flag matches its configured hidden + service anonymity mode. + "MaxStreamsCloseCircuit"; Close the circuit is the maximum streams + allowed is reached. + + NumStreams = A value between 0 and 65535 which is used as the maximum + streams that can be attached on a rendezvous circuit. Setting + it to 0 means unlimited which is also the default behavior. + + VirtPort = The virtual TCP Port for the Onion Service (As in the + HiddenServicePort "VIRTPORT" argument). + + Target = The (optional) target for the given VirtPort (As in the + optional HiddenServicePort "TARGET" argument). + + ClientName = An identifier 1 to 16 characters long, using only + characters in A-Za-z0-9+-_ (no spaces) (v2 only). + + ClientBlob = Authorization data for the client, in an opaque format + specific to the authorization method (v2 only). + + V3Key = The client's base32-encoded x25519 public key, using only the key + part of rend-spec-v3.txt section G.1.2 (v3 only). + + The server reply format is: + + "250-ServiceID=" ServiceID CRLF + ["250-PrivateKey=" KeyType ":" KeyBlob CRLF] + *("250-ClientAuth=" ClientName ":" ClientBlob CRLF) + "250 OK" CRLF + + ServiceID = The Onion Service address without the trailing ".onion" + suffix + + Tells the server to create a new Onion ("Hidden") Service, with the + specified private key and algorithm. If a KeyType of "NEW" is selected, + the server will generate a new keypair using the selected algorithm. + The "Port" argument's VirtPort and Target values have identical + semantics to the corresponding HiddenServicePort configuration values. + + The server response will only include a private key if the server was + requested to generate a new keypair, and also the "DiscardPK" flag was + not specified. (Note that if "DiscardPK" flag is specified, there is no + way to recreate the generated keypair and the corresponding Onion + Service at a later date). + + If client authorization is enabled using the "BasicAuth" flag (which is v2 + only), the service will not be accessible to clients without valid + authorization data (configured with the "HidServAuth" option). The list of + authorized clients is specified with one or more "ClientAuth" parameters. + If "ClientBlob" is not specified for a client, a new credential will be + randomly generated and returned. + + Tor instances can either be in anonymous hidden service mode, or + non-anonymous single onion service mode. All hidden services on the same + tor instance have the same anonymity. To guard against unexpected loss + of anonymity, Tor checks that the ADD_ONION "NonAnonymous" flag matches + the current hidden service anonymity mode. The hidden service anonymity + mode is configured using the Tor options HiddenServiceSingleHopMode and + HiddenServiceNonAnonymousMode. If both these options are 1, the + "NonAnonymous" flag must be provided to ADD_ONION. If both these options + are 0 (the Tor default), the flag must NOT be provided. + + Once created the new Onion Service will remain active until either the + Onion Service is removed via "DEL_ONION", the server terminates, or the + control connection that originated the "ADD_ONION" command is closed. + It is possible to override disabling the Onion Service on control + connection close by specifying the "Detach" flag. + + It is the Onion Service server application's responsibility to close + existing client connections if desired after the Onion Service is + removed. + + (The KeyBlob format is left intentionally opaque, however for "RSA1024" + keys it is currently the Base64 encoded DER representation of a PKCS#1 + RSAPrivateKey, with all newlines removed. For a "ED25519-V3" key is + the Base64 encoding of the concatenation of the 32-byte ed25519 secret + scalar in little-endian and the 32-byte ed25519 PRF secret.) + + [Note: The ED25519-V3 format is not the same as, e.g., SUPERCOP + ed25519/ref, which stores the concatenation of the 32-byte ed25519 + hash seed concatenated with the 32-byte public key, and which derives + the secret scalar and PRF secret by expanding the hash seed with + SHA-512. Our key blinding scheme is incompatible with storing + private keys as seeds, so we store the secret scalar alongside the + PRF secret, and just pay the cost of recomputing the public key when + importing an ED25519-V3 key.] + + Examples: + + C: ADD_ONION NEW:BEST Flags=DiscardPK Port=80 + S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad + S: 250 OK + + C: ADD_ONION RSA1024:[Blob Redacted] Port=80,192.168.1.1:8080 + S: 250-ServiceID=sampleonion12456 + S: 250 OK + + C: ADD_ONION NEW:BEST Port=22 Port=80,8080 + S: 250-ServiceID=sampleonion4t2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad + S: 250-PrivateKey=ED25519-V3:[Blob Redacted] + S: 250 OK + + C: ADD_ONION NEW:RSA1024 Flags=DiscardPK,BasicAuth Port=22 + ClientAuth=alice:[Blob Redacted] ClientAuth=bob + S: 250-ServiceID=testonion1234567 + S: 250-ClientAuth=bob:[Blob Redacted] + S: 250 OK + + C: ADD_ONION NEW:ED25519-V3 ClientAuthV3=[Blob Redacted] Port=22 + S: 250-ServiceID=n35etu3yjxrqjpntmfziom5sjwspoydchmelc4xleoy4jk2u4lziz2yd + S: 250-ClientAuthV3=[Blob Redacted] + S: 250 OK + + Examples with Tor in anonymous onion service mode: + + C: ADD_ONION NEW:BEST Flags=DiscardPK Port=22 + S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad + S: 250 OK + + C: ADD_ONION NEW:BEST Flags=DiscardPK,NonAnonymous Port=22 + S: 512 Tor is in anonymous hidden service mode + + Examples with Tor in non-anonymous onion service mode: + + C: ADD_ONION NEW:BEST Flags=DiscardPK Port=22 + S: 512 Tor is in non-anonymous hidden service mode + + C: ADD_ONION NEW:BEST Flags=DiscardPK,NonAnonymous Port=22 + S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad + S: 250 OK + + [ADD_ONION was added in Tor 0.2.7.1-alpha.] + [MaxStreams and MaxStreamsCloseCircuit were added in Tor 0.2.7.2-alpha] + [ClientAuth was added in Tor 0.2.9.1-alpha. It is v2 only.] + [NonAnonymous was added in Tor 0.2.9.3-alpha.] + [HS v3 support added 0.3.3.1-alpha] + [ClientV3Auth support added 0.4.6.1-alpha] + +3.28. DEL_ONION + + The syntax is: + + "DEL_ONION" SP ServiceID CRLF + + ServiceID = The Onion Service address without the trailing ".onion" + suffix + + Tells the server to remove an Onion ("Hidden") Service, that was + previously created via an "ADD_ONION" command. It is only possible to + remove Onion Services that were created on the same control connection + as the "DEL_ONION" command, and those that belong to no control + connection in particular (The "Detach" flag was specified at creation). + + If the ServiceID is invalid, or is neither owned by the current control + connection nor a detached Onion Service, the server will return a 552. + + It is the Onion Service server application's responsibility to close + existing client connections if desired after the Onion Service has been + removed via "DEL_ONION". + + Tor replies with "250 OK" on success, or a 512 if there are an invalid + number of arguments, or a 552 if it doesn't recognize the ServiceID. + + [DEL_ONION was added in Tor 0.2.7.1-alpha.] + [HS v3 support added 0.3.3.1-alpha] + +3.29. HSPOST + + The syntax is: + + "+HSPOST" *[SP "SERVER=" Server] [SP "HSADDRESS=" HSAddress] + CRLF Descriptor CRLF "." CRLF + + Server = LongName + HSAddress = 56*Base32Character + Descriptor = The text of the descriptor formatted as specified + in rend-spec.txt section 1.3. + + The "HSAddress" key is optional and only applies for v3 descriptors. A 513 + error is returned if used with v2. + + This command launches a hidden service descriptor upload to the specified + HSDirs. If one or more Server arguments are provided, an upload is triggered + on each of them in parallel. If no Server options are provided, it behaves + like a normal HS descriptor upload and will upload to the set of responsible + HS directories. + + If any value is unrecognized, a 552 error is returned and the command is + stopped. If there is an error in parsing the descriptor, the server + must send a "554 Invalid descriptor" reply. + + On success, Tor replies "250 OK" then Tor MUST eventually follow + this with a HS_DESC event with the result for each upload location. + + Examples are: + + C: +HSPOST SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31 + [DESCRIPTOR] + . + S: 250 OK + + [HSPOST was added in Tor 0.2.7.1-alpha] + +3.30. ONION_CLIENT_AUTH_ADD + + The syntax is: + + "ONION_CLIENT_AUTH_ADD" SP HSAddress + SP KeyType ":" PrivateKeyBlob + [SP "ClientName=" Nickname] + [SP "Flags=" TYPE] CRLF + + HSAddress = 56*Base32Character + KeyType = "x25519" is the only one supported right now + PrivateKeyBlob = base64 encoding of x25519 key + + Tells the connected Tor to add client-side v3 client auth credentials for the + onion service with "HSAddress". The "PrivateKeyBlob" is the x25519 private + key that should be used for this client, and "Nickname" is an optional + nickname for the client. + + FLAGS is a comma-separated tuple of flags for this new client. For now, the + currently supported flags are: + + "Permanent" - This client's credentials should be stored in the filesystem. + If this is not set, the client's credentials are ephemeral + and stored in memory. + + If client auth credentials already existed for this service, replace them + with the new ones. + + If Tor has cached onion service descriptors that it has been unable to + decrypt in the past (due to lack of client auth credentials), attempt to + decrypt those descriptors as soon as this command succeeds. + + On success, "250 OK" is returned. Otherwise, the following error codes exist: + + 251 - Client auth credentials for this onion service already existed and replaced. + 252 - Added client auth credentials and successfully decrypted a cached descriptor. + 451 - We reached authorized client capacity + 512 - Syntax error in "HSAddress", or "PrivateKeyBlob" or "Nickname" + 551 - Client with with this "Nickname" already exists + 552 - Unrecognized KeyType + + [ONION_CLIENT_AUTH_ADD was added in Tor 0.4.3.1-alpha] + +3.31. ONION_CLIENT_AUTH_REMOVE + + The syntax is: + + "ONION_CLIENT_AUTH_REMOVE" SP HSAddress + + KeyType = "x25519" is the only one supported right now + + Tells the connected Tor to remove the client-side v3 client auth credentials + for the onion service with "HSAddress". + + On success "250 OK" is returned. Otherwise, the following error codes exist: + + 512 - Syntax error in "HSAddress". + 251 - Client credentials for "HSAddress" did not exist. + + [ONION_CLIENT_AUTH_REMOVE was added in Tor 0.4.3.1-alpha] + +3.32. ONION_CLIENT_AUTH_VIEW + + The syntax is: + + "ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF + + Tells the connected Tor to list all the stored client-side v3 client auth + credentials for "HSAddress". If no "HSAddress" is provided, list all the + stored client-side v3 client auth credentials. + + The server reply format is: + + "250-ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF + *("250-CLIENT" SP HSAddress SP KeyType ":" PrivateKeyBlob + [SP "ClientName=" Nickname] + [SP "Flags=" FLAGS] CRLF) + "250 OK" CRLF + + HSAddress = The onion address under which this credential is stored + KeyType = "x25519" is the only one supported right now + PrivateKeyBlob = base64 encoding of x25519 key + + "Nickname" is an optional nickname for this client, which can be set either + through the ONION_CLIENT_AUTH_ADD command, or it's the filename of this + client if the credentials are stored in the filesystem. + + FLAGS is a comma-separated field of flags for this client, the currently + supported flags are: + + "Permanent" - This client's credentials are stored in the filesystem. + + On success "250 OK" is returned. Otherwise, the following error codes exist: + + 512 - Syntax error in "HSAddress". + + [ONION_CLIENT_AUTH_VIEW was added in Tor 0.4.3.1-alpha] + +3.33. DROPOWNERSHIP + + The syntax is: + + "DROPOWNERSHIP" CRLF + + This command instructs Tor to relinquish ownership of its control + connection. As such tor will not shut down when this control + connection is closed. + + This method is idempotent. If the control connection does not + already have ownership this method returns successfully, and + does nothing. + + The controller can call TAKEOWNERSHIP again to re-establish + ownership. + + [DROPOWNERSHIP was added in Tor 0.4.0.0-alpha] + +3.34. DROPTIMEOUTS + + The syntax is: + "DROPTIMEOUTS" CRLF + + Tells the server to drop all circuit build times. Do not invoke this command + lightly; it can increase vulnerability to tracking attacks over time. + + Tor replies with "250 OK" on success. Tor also emits the BUILDTIMEOUT_SET + RESET event right after this "250 OK". + + [DROPTIMEOUTS was added in Tor 0.4.5.0-alpha.] + +4. Replies + + Reply codes follow the same 3-character format as used by SMTP, with the + first character defining a status, the second character defining a + subsystem, and the third designating fine-grained information. + + The TC protocol currently uses the following first characters: + + 2yz Positive Completion Reply + The command was successful; a new request can be started. + + 4yz Temporary Negative Completion reply + The command was unsuccessful but might be reattempted later. + + 5yz Permanent Negative Completion Reply + The command was unsuccessful; the client should not try exactly + that sequence of commands again. + + 6yz Asynchronous Reply + Sent out-of-order in response to an earlier SETEVENTS command. + + The following second characters are used: + + x0z Syntax + Sent in response to ill-formed or nonsensical commands. + + x1z Protocol + Refers to operations of the Tor Control protocol. + + x5z Tor + Refers to actual operations of Tor system. + + The following codes are defined: + + 250 OK + 251 Operation was unnecessary + [Tor has declined to perform the operation, but no harm was done.] + + 451 Resource exhausted + + 500 Syntax error: protocol + + 510 Unrecognized command + 511 Unimplemented command + 512 Syntax error in command argument + 513 Unrecognized command argument + 514 Authentication required + 515 Bad authentication + + 550 Unspecified Tor error + + 551 Internal error + [Something went wrong inside Tor, so that the client's + request couldn't be fulfilled.] + + 552 Unrecognized entity + [A configuration key, a stream ID, circuit ID, event, + mentioned in the command did not actually exist.] + + 553 Invalid configuration value + [The client tried to set a configuration option to an + incorrect, ill-formed, or impossible value.] + + 554 Invalid descriptor + + 555 Unmanaged entity + + 650 Asynchronous event notification + + Unless specified to have specific contents, the human-readable messages + in error replies should not be relied upon to match those in this document. + +4.1. Asynchronous events + + These replies can be sent after a corresponding SETEVENTS command has been + received. They will not be interleaved with other Reply elements, but they + can appear between a command and its corresponding reply. For example, + this sequence is possible: + + C: SETEVENTS CIRC + S: 250 OK + C: GETCONF SOCKSPORT ORPORT + S: 650 CIRC 1000 EXTENDED moria1,moria2 + S: 250-SOCKSPORT=9050 + S: 250 ORPORT=0 + + But this sequence is disallowed: + + C: SETEVENTS CIRC + S: 250 OK + C: GETCONF SOCKSPORT ORPORT + S: 250-SOCKSPORT=9050 + S: 650 CIRC 1000 EXTENDED moria1,moria2 + S: 250 ORPORT=0 + + Clients MUST tolerate more arguments in an asynchronous reply than + expected, and MUST tolerate more lines in an asynchronous reply than + expected. For instance, a client that expects a CIRC message like: + + 650 CIRC 1000 EXTENDED moria1,moria2 + + must tolerate: + + 650-CIRC 1000 EXTENDED moria1,moria2 0xBEEF + 650-EXTRAMAGIC=99 + 650 ANONYMITY=high + + If clients receives extended events (selected by USEFEATUERE + EXTENDED_EVENTS in Tor 0.1.2.2-alpha..Tor-0.2.1.x, and always-on in + Tor 0.2.2.x and later), then each event line as specified below may be + followed by additional arguments and additional lines. Additional + lines will be of the form: + + "650" ("-"/" ") KEYWORD ["=" ARGUMENTS] CRLF + + Additional arguments will be of the form + + SP KEYWORD ["=" ( QuotedString / * NonSpDquote ) ] + + Clients MUST tolerate events with arguments and keywords they do not + recognize, and SHOULD process those events as if any unrecognized + arguments and keywords were not present. + + Clients SHOULD NOT depend on the order of keyword=value arguments, + and SHOULD NOT depend on there being no new keyword=value arguments + appearing between existing keyword=value arguments, though as of this + writing (Jun 2011) some do. Thus, extensions to this protocol should + add new keywords only after the existing keywords, until all + controllers have been fixed. At some point this "SHOULD NOT" might + become a "MUST NOT". + +4.1.1. Circuit status changed + + The syntax is: + + "650" SP "CIRC" SP CircuitID SP CircStatus [SP Path] + [SP "BUILD_FLAGS=" BuildFlags] [SP "PURPOSE=" Purpose] + [SP "HS_STATE=" HSState] [SP "REND_QUERY=" HSAddress] + [SP "TIME_CREATED=" TimeCreated] + [SP "REASON=" Reason [SP "REMOTE_REASON=" Reason]] + [SP "SOCKS_USERNAME=" EscapedUsername] + [SP "SOCKS_PASSWORD=" EscapedPassword] + [SP "HS_POW=" HSPoW ] + CRLF + + CircStatus = + "LAUNCHED" / ; circuit ID assigned to new circuit + "BUILT" / ; all hops finished, can now accept streams + "GUARD_WAIT" / ; all hops finished, waiting to see if a + ; circuit with a better guard will be usable. + "EXTENDED" / ; one more hop has been completed + "FAILED" / ; circuit closed (was not built) + "CLOSED" ; circuit closed (was built) + + Path = LongName *("," LongName) + ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, Path + ; is as follows: + ; Path = ServerID *("," ServerID) + + BuildFlags = BuildFlag *("," BuildFlag) + BuildFlag = "ONEHOP_TUNNEL" / "IS_INTERNAL" / + "NEED_CAPACITY" / "NEED_UPTIME" + + Purpose = "GENERAL" / "HS_CLIENT_INTRO" / "HS_CLIENT_REND" / + "HS_SERVICE_INTRO" / "HS_SERVICE_REND" / "TESTING" / + "CONTROLLER" / "MEASURE_TIMEOUT" / + "HS_VANGUARDS" / "PATH_BIAS_TESTING" / + "CIRCUIT_PADDING" + + HSState = "HSCI_CONNECTING" / "HSCI_INTRO_SENT" / "HSCI_DONE" / + "HSCR_CONNECTING" / "HSCR_ESTABLISHED_IDLE" / + "HSCR_ESTABLISHED_WAITING" / "HSCR_JOINED" / + "HSSI_CONNECTING" / "HSSI_ESTABLISHED" / + "HSSR_CONNECTING" / "HSSR_JOINED" + + HSPoWType = "v1" + HSPoWEffort = 1*DIGIT + HSPoW = HSPoWType "," HSPoWEffort + + EscapedUsername = QuotedString + EscapedPassword = QuotedString + + HSAddress = 16*Base32Character / 56*Base32Character + Base32Character = ALPHA / "2" / "3" / "4" / "5" / "6" / "7" + + TimeCreated = ISOTime2Frac + Seconds = 1*DIGIT + Microseconds = 1*DIGIT + + Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" / + "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" / + "OR_IDENTITY" / "OR_CONN_CLOSED" / "TIMEOUT" / + "FINISHED" / "DESTROYED" / "NOPATH" / "NOSUCHSERVICE" / + "MEASUREMENT_EXPIRED" + + The path is provided only when the circuit has been extended at least one + hop. + + The "BUILD_FLAGS" field is provided only in versions 0.2.3.11-alpha + and later. Clients MUST accept build flags not listed above. + Build flags are defined as follows: + + ONEHOP_TUNNEL (one-hop circuit, used for tunneled directory conns) + IS_INTERNAL (internal circuit, not to be used for exiting streams) + NEED_CAPACITY (this circuit must use only high-capacity nodes) + NEED_UPTIME (this circuit must use only high-uptime nodes) + + The "PURPOSE" field is provided only in versions 0.2.1.6-alpha and + later, and only if extended events are enabled (see 3.19). Clients + MUST accept purposes not listed above. Purposes are defined as + follows: + + GENERAL (circuit for AP and/or directory request streams) + HS_CLIENT_INTRO (HS client-side introduction-point circuit) + HS_CLIENT_REND (HS client-side rendezvous circuit; carries AP streams) + HS_SERVICE_INTRO (HS service-side introduction-point circuit) + HS_SERVICE_REND (HS service-side rendezvous circuit) + TESTING (reachability-testing circuit; carries no traffic) + CONTROLLER (circuit built by a controller) + MEASURE_TIMEOUT (circuit being kept around to see how long it takes) + HS_VANGUARDS (circuit created ahead of time when using + HS vanguards, and later repurposed as needed) + PATH_BIAS_TESTING (circuit used to probe whether our circuits are + being deliberately closed by an attacker) + CIRCUIT_PADDING (circuit that is being held open to disguise its + true close time) + + The "HS_STATE" field is provided only for hidden-service circuits, + and only in versions 0.2.3.11-alpha and later. Clients MUST accept + hidden-service circuit states not listed above. Hidden-service + circuit states are defined as follows: + + HSCI_* (client-side introduction-point circuit states) + HSCI_CONNECTING (connecting to intro point) + HSCI_INTRO_SENT (sent INTRODUCE1; waiting for reply from IP) + HSCI_DONE (received reply from IP relay; closing) + + HSCR_* (client-side rendezvous-point circuit states) + HSCR_CONNECTING (connecting to or waiting for reply from RP) + HSCR_ESTABLISHED_IDLE (established RP; waiting for introduction) + HSCR_ESTABLISHED_WAITING (introduction sent to HS; waiting for rend) + HSCR_JOINED (connected to HS) + + HSSI_* (service-side introduction-point circuit states) + HSSI_CONNECTING (connecting to intro point) + HSSI_ESTABLISHED (established intro point) + + HSSR_* (service-side rendezvous-point circuit states) + HSSR_CONNECTING (connecting to client's rend point) + HSSR_JOINED (connected to client's RP circuit) + + The "SOCKS_USERNAME" and "SOCKS_PASSWORD" fields indicate the credentials + that were used by a SOCKS client to connect to Tor's SOCKS port and + initiate this circuit. (Streams for SOCKS clients connected with different + usernames and/or passwords are isolated on separate circuits if the + IsolateSOCKSAuth flag is active; see Proposal 171.) [Added in Tor + 0.4.3.1-alpha.] + + The "REND_QUERY" field is provided only for hidden-service-related + circuits, and only in versions 0.2.3.11-alpha and later. Clients + MUST accept hidden service addresses in formats other than that + specified above. [Added in Tor 0.4.3.1-alpha.] + + The "TIME_CREATED" field is provided only in versions 0.2.3.11-alpha and + later. TIME_CREATED is the time at which the circuit was created or + cannibalized. [Added in Tor 0.4.3.1-alpha.] + + The "REASON" field is provided only for FAILED and CLOSED events, and only + if extended events are enabled (see 3.19). Clients MUST accept reasons + not listed above. [Added in Tor 0.4.3.1-alpha.] Reasons are as given in + tor-spec.txt, except for: + + NOPATH (Not enough nodes to make circuit) + MEASUREMENT_EXPIRED (As "TIMEOUT", except that we had left the circuit + open for measurement purposes to see how long it + would take to finish.) + IP_NOW_REDUNDANT (Closing a circuit to an introduction point that + has become redundant, since some other circuit + opened in parallel with it has succeeded.) + + The "REMOTE_REASON" field is provided only when we receive a DESTROY or + TRUNCATE cell, and only if extended events are enabled. It contains the + actual reason given by the remote OR for closing the circuit. Clients MUST + accept reasons not listed above. Reasons are as listed in tor-spec.txt. + [Added in Tor 0.4.3.1-alpha.] + +4.1.2. Stream status changed + + The syntax is: + + "650" SP "STREAM" SP StreamID SP StreamStatus SP CircuitID SP Target + [SP "REASON=" Reason [ SP "REMOTE_REASON=" Reason ]] + [SP "SOURCE=" Source] [ SP "SOURCE_ADDR=" Address ":" Port ] + [SP "PURPOSE=" Purpose] [SP "SOCKS_USERNAME=" EscapedUsername] + [SP "SOCKS_PASSWORD=" EscapedPassword] + [SP "CLIENT_PROTOCOL=" ClientProtocol] [SP "NYM_EPOCH=" NymEpoch] + [SP "SESSION_GROUP=" SessionGroup] [SP "ISO_FIELDS=" IsoFields] + CRLF + + StreamStatus = + "NEW" / ; New request to connect + "NEWRESOLVE" / ; New request to resolve an address + "REMAP" / ; Address re-mapped to another + "SENTCONNECT" / ; Sent a connect cell along a circuit + "SENTRESOLVE" / ; Sent a resolve cell along a circuit + "SUCCEEDED" / ; Received a reply; stream established + "FAILED" / ; Stream failed and not retriable + "CLOSED" / ; Stream closed + "DETACHED" / ; Detached from circuit; still retriable + "CONTROLLER_WAIT" ; Waiting for controller to use ATTACHSTREAM + ; (new in 0.4.5.1-alpha) + "XOFF_SENT" ; XOFF has been sent for this stream + ; (new in 0.4.7.5-alpha) + "XOFF_RECV" ; XOFF has been received for this stream + ; (new in 0.4.7.5-alpha) + "XON_SENT" ; XON has been sent for this stream + ; (new in 0.4.7.5-alpha) + "XON_RECV" ; XON has been received for this stream + ; (new in 0.4.7.5-alpha) + + Target = TargetAddress ":" Port + Port = an integer from 0 to 65535 inclusive + TargetAddress = Address / "(Tor_internal)" + + EscapedUsername = QuotedString + EscapedPassword = QuotedString + + ClientProtocol = + "SOCKS4" / + "SOCKS5" / + "TRANS" / + "NATD" / + "DNS" / + "HTTPCONNECT" / + "UNKNOWN" + + NymEpoch = a nonnegative integer + SessionGroup = an integer + + IsoFields = a comma-separated list of IsoField values + + IsoField = + "CLIENTADDR" / + "CLIENTPORT" / + "DESTADDR" / + "DESTPORT" / + the name of a field that is valid for STREAM events + + The circuit ID designates which circuit this stream is attached to. If + the stream is unattached, the circuit ID "0" is given. The target + indicates the address which the stream is meant to resolve or connect to; + it can be "(Tor_internal)" for a virtual stream created by the Tor program + to talk to itself. + + Reason = "MISC" / "RESOLVEFAILED" / "CONNECTREFUSED" / + "EXITPOLICY" / "DESTROY" / "DONE" / "TIMEOUT" / + "NOROUTE" / "HIBERNATING" / "INTERNAL"/ "RESOURCELIMIT" / + "CONNRESET" / "TORPROTOCOL" / "NOTDIRECTORY" / "END" / + "PRIVATE_ADDR" + + The "REASON" field is provided only for FAILED, CLOSED, and DETACHED + events, and only if extended events are enabled (see 3.19). Clients MUST + accept reasons not listed above. Reasons are as given in tor-spec.txt, + except for: + + END (We received a RELAY_END cell from the other side of this + stream.) + PRIVATE_ADDR (The client tried to connect to a private address like + 127.0.0.1 or 10.0.0.1 over Tor.) + [XXXX document more. -NM] + + The "REMOTE_REASON" field is provided only when we receive a RELAY_END + cell, and only if extended events are enabled. It contains the actual + reason given by the remote OR for closing the stream. Clients MUST accept + reasons not listed above. Reasons are as listed in tor-spec.txt. + + "REMAP" events include a Source if extended events are enabled: + + Source = "CACHE" / "EXIT" + + Clients MUST accept sources not listed above. "CACHE" is given if + the Tor client decided to remap the address because of a cached + answer, and "EXIT" is given if the remote node we queried gave us + the new address as a response. + + The "SOURCE_ADDR" field is included with NEW and NEWRESOLVE events if + extended events are enabled. It indicates the address and port + that requested the connection, and can be (e.g.) used to look up the + requesting program. + + Purpose = "DIR_FETCH" / "DIR_UPLOAD" / "DNS_REQUEST" / + "USER" / "DIRPORT_TEST" + + The "PURPOSE" field is provided only for NEW and NEWRESOLVE events, and + only if extended events are enabled (see 3.19). Clients MUST accept + purposes not listed above. The purposes above are defined as: + + "DIR_FETCH" -- This stream is generated internally to Tor for + fetching directory information. + "DIR_UPLOAD" -- An internal stream for uploading information to + a directory authority. + "DIRPORT_TEST" -- A stream we're using to test our own directory + port to make sure it's reachable. + "DNS_REQUEST" -- A user-initiated DNS request. + "USER" -- This stream is handling user traffic, OR it's internal + to Tor, but it doesn't match one of the purposes above. + + The "SOCKS_USERNAME" and "SOCKS_PASSWORD" fields indicate the credentials + that were used by a SOCKS client to connect to Tor's SOCKS port and + initiate this stream. (Streams for SOCKS clients connected with different + usernames and/or passwords are isolated on separate circuits if the + IsolateSOCKSAuth flag is active; see Proposal 171.) + + The "CLIENT_PROTOCOL" field indicates the protocol that was used by a client + to initiate this stream. (Streams for clients connected with different + protocols are isolated on separate circuits if the IsolateClientProtocol + flag is active.) Controllers MUST tolerate unrecognized client protocols. + + The "NYM_EPOCH" field indicates the nym epoch that was active when a client + initiated this stream. The epoch increments when the NEWNYM signal is + received. (Streams with different nym epochs are isolated on separate + circuits.) + + The "SESSION_GROUP" field indicates the session group of the listener port + that a client used to initiate this stream. By default, the session group is + different for each listener port, but this can be overridden for a listener + via the "SessionGroup" option in torrc. (Streams with different session + groups are isolated on separate circuits.) + + The "ISO_FIELDS" field indicates the set of STREAM event fields for which + stream isolation is enabled for the listener port that a client used to + initiate this stream. The special values "CLIENTADDR", "CLIENTPORT", + "DESTADDR", and "DESTPORT", if their correspondingly named fields are not + present, refer to the Address and Port components of the "SOURCE_ADDR" and + Target fields. + +4.1.3. OR Connection status changed + + The syntax is: + + "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON=" + Reason ] [ SP "NCIRCS=" NumCircuits ] [ SP "ID=" ConnID ] CRLF + + ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED" + + ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, OR + ; Connection is as follows: + "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON=" + Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF + + NEW is for incoming connections, and LAUNCHED is for outgoing + connections. CONNECTED means the TLS handshake has finished (in + either direction). FAILED means a connection is being closed that + hasn't finished its handshake, and CLOSED is for connections that + have handshaked. + + A LongName or ServerID is specified unless it's a NEW connection, in + which case we don't know what server it is yet, so we use Address:Port. + + If extended events are enabled (see 3.19), optional reason and + circuit counting information is provided for CLOSED and FAILED + events. + + Reason = "MISC" / "DONE" / "CONNECTREFUSED" / + "IDENTITY" / "CONNECTRESET" / "TIMEOUT" / "NOROUTE" / + "IOERROR" / "RESOURCELIMIT" / "PT_MISSING" + + NumCircuits counts both established and pending circuits. + + The ORStatus values are as follows: + + NEW -- We have received a new incoming OR connection, and are starting + the server-side handshake. + LAUNCHED -- We have launched a new outgoing OR connection, and are + starting the client-side handshake. + CONNECTED -- The OR connection has been connected and the handshake is + done. + FAILED -- Our attempt to open the OR connection failed. + CLOSED -- The OR connection closed in an unremarkable way. + + The Reason values for closed/failed OR connections are: + + DONE -- The OR connection has shut down cleanly. + CONNECTREFUSED -- We got an ECONNREFUSED while connecting to the target + OR. + IDENTITY -- We connected to the OR, but found that its identity was + not what we expected. + CONNECTRESET -- We got an ECONNRESET or similar IO error from the + connection with the OR. + TIMEOUT -- We got an ETIMEOUT or similar IO error from the connection + with the OR, or we're closing the connection for being idle for too + long. + NOROUTE -- We got an ENOTCONN, ENETUNREACH, ENETDOWN, EHOSTUNREACH, or + similar error while connecting to the OR. + IOERROR -- We got some other IO error on our connection to the OR. + RESOURCELIMIT -- We don't have enough operating system resources (file + descriptors, buffers, etc) to connect to the OR. + PT_MISSING -- No pluggable transport was available. + MISC -- The OR connection closed for some other reason. + + [First added ID parameter in 0.2.5.2-alpha] + +4.1.4. Bandwidth used in the last second + + The syntax is: + + "650" SP "BW" SP BytesRead SP BytesWritten *(SP Type "=" Num) CRLF + BytesRead = 1*DIGIT + BytesWritten = 1*DIGIT + Type = "DIR" / "OR" / "EXIT" / "APP" / ... + Num = 1*DIGIT + + BytesRead and BytesWritten are the totals. [In a future Tor version, + we may also include a breakdown of the connection types that used + bandwidth this second (not implemented yet).] + +4.1.5. Log messages + + The syntax is: + + "650" SP Severity SP ReplyText CRLF + + or + + "650+" Severity CRLF Data 650 SP "OK" CRLF + + Severity = "DEBUG" / "INFO" / "NOTICE" / "WARN"/ "ERR" + + Some low-level logs may be sent from signal handlers, so their destination + logs must be signal-safe. These low-level logs include backtraces, + logging function errors, and errors in code called by logging functions. + Signal-safe logs are never sent as control port log events. + + Control port message trace debug logs are never sent as control port log + events, to avoid modifying control output when debugging. + +4.1.6. New descriptors available + + This event is generated when new router descriptors (not microdescs or + extrainfos or anything else) are received. + + Syntax: + + "650" SP "NEWDESC" 1*(SP LongName) CRLF + ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature + ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, it + ; is as follows: + "650" SP "NEWDESC" 1*(SP ServerID) CRLF + +4.1.7. New Address mapping + + These events are generated when a new address mapping is entered in + Tor's address map cache, or when the answer for a RESOLVE command is + found. Entries can be created by a successful or failed DNS lookup, + a successful or failed connection attempt, a RESOLVE command, + a MAPADDRESS command, the AutomapHostsOnResolve feature, or the + TrackHostExits feature. + + Syntax: + + "650" SP "ADDRMAP" SP Address SP NewAddress SP Expiry + [SP "error=" ErrorCode] [SP "EXPIRES=" UTCExpiry] [SP "CACHED=" Cached] + [SP "STREAMID=" StreamId] CRLF + + NewAddress = Address / "<error>" + Expiry = DQUOTE ISOTime DQUOTE / "NEVER" + + ErrorCode = "yes" / "internal" / "Unable to launch resolve request" + UTCExpiry = DQUOTE IsoTime DQUOTE + + Cached = DQUOTE "YES" DQUOTE / DQUOTE "NO" DQUOTE + StreamId = DQUOTE StreamId DQUOTE + + Error and UTCExpiry are only provided if extended events are enabled. + The values for Error are mostly useless. Future values will be + chosen to match 1*(ALNUM / "_"); the "Unable to launch resolve request" + value is a bug in Tor before 0.2.4.7-alpha. + + Expiry is expressed as the local time (rather than UTC). This is a bug, + left in for backward compatibility; new code should look at UTCExpiry + instead. (If Expiry is "NEVER", UTCExpiry is omitted.) + + Cached indicates whether the mapping will be stored until it expires, or if + it is just a notification in response to a RESOLVE command. + + StreamId is the global stream identifier of the stream or circuit from which + the address was resolved. + +4.1.8. Descriptors uploaded to us in our role as authoritative dirserver + + [NOTE: This feature was removed in Tor 0.3.2.1-alpha.] + + Tor generates this event when it's a directory authority, and + somebody has just uploaded a server descriptor. + + Syntax: + + "650" "+" "AUTHDIR_NEWDESCS" CRLF Action CRLF Message CRLF + Descriptor CRLF "." CRLF "650" SP "OK" CRLF + Action = "ACCEPTED" / "DROPPED" / "REJECTED" + Message = Text + + The Descriptor field is the text of the server descriptor; the Action + field is "ACCEPTED" if we're accepting the descriptor as the new + best valid descriptor for its router, "REJECTED" if we aren't taking + the descriptor and we're complaining to the uploading relay about + it, and "DROPPED" if we decide to drop the descriptor without + complaining. The Message field is a human-readable string + explaining why we chose the Action. (It doesn't contain newlines.) + +4.1.9. Our descriptor changed + + Syntax: + + "650" SP "DESCCHANGED" CRLF + + [First added in 0.1.2.2-alpha.] + +4.1.10. Status events + + Status events (STATUS_GENERAL, STATUS_CLIENT, and STATUS_SERVER) are sent + based on occurrences in the Tor process pertaining to the general state of + the program. Generally, they correspond to log messages of severity Notice + or higher. They differ from log messages in that their format is a + specified interface. + + Syntax: + + "650" SP StatusType SP StatusSeverity SP StatusAction + [SP StatusArguments] CRLF + + StatusType = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER" + StatusSeverity = "NOTICE" / "WARN" / "ERR" + StatusAction = 1*ALPHA + StatusArguments = StatusArgument *(SP StatusArgument) + StatusArgument = StatusKeyword '=' StatusValue + StatusKeyword = 1*(ALNUM / "_") + StatusValue = 1*(ALNUM / '_') / QuotedString + + StatusAction is a string, and StatusArguments is a series of + keyword=value pairs on the same line. Values may be space-terminated + strings, or quoted strings. + + These events are always produced with EXTENDED_EVENTS and + VERBOSE_NAMES; see the explanations in the USEFEATURE section + for details. + + Controllers MUST tolerate unrecognized actions, MUST tolerate + unrecognized arguments, MUST tolerate missing arguments, and MUST + tolerate arguments that arrive in any order. + + Each event description below is accompanied by a recommendation for + controllers. These recommendations are suggestions only; no controller + is required to implement them. + + Compatibility note: versions of Tor before 0.2.0.22-rc incorrectly + generated "STATUS_SERVER" as "STATUS_SEVER". To be compatible with those + versions, tools should accept both. + + Actions for STATUS_GENERAL events can be as follows: + + CLOCK_JUMPED + "TIME=NUM" + Tor spent enough time without CPU cycles that it has closed all + its circuits and will establish them anew. This typically + happens when a laptop goes to sleep and then wakes up again. It + also happens when the system is swapping so heavily that Tor is + starving. The "time" argument specifies the number of seconds Tor + thinks it was unconscious for (or alternatively, the number of + seconds it went back in time). + + This status event is sent as NOTICE severity normally, but WARN + severity if Tor is acting as a server currently. + + {Recommendation for controller: ignore it, since we don't really + know what the user should do anyway. Hm.} + + DANGEROUS_VERSION + "CURRENT=version" + "REASON=NEW/OBSOLETE/UNRECOMMENDED" + "RECOMMENDED=\"version, version, ...\"" + Tor has found that directory servers don't recommend its version of + the Tor software. RECOMMENDED is a comma-and-space-separated string + of Tor versions that are recommended. REASON is NEW if this version + of Tor is newer than any recommended version, OBSOLETE if + this version of Tor is older than any recommended version, and + UNRECOMMENDED if some recommended versions of Tor are newer and + some are older than this version. (The "OBSOLETE" reason was called + "OLD" from Tor 0.1.2.3-alpha up to and including 0.2.0.12-alpha.) + + {Controllers may want to suggest that the user upgrade OLD or + UNRECOMMENDED versions. NEW versions may be known-insecure, or may + simply be development versions.} + + TOO_MANY_CONNECTIONS + "CURRENT=NUM" + Tor has reached its ulimit -n or whatever the native limit is on file + descriptors or sockets. CURRENT is the number of sockets Tor + currently has open. The user should really do something about + this. The "current" argument shows the number of connections currently + open. + + {Controllers may recommend that the user increase the limit, or + increase it for them. Recommendations should be phrased in an + OS-appropriate way and automated when possible.} + + BUG + "REASON=STRING" + Tor has encountered a situation that its developers never expected, + and the developers would like to learn that it happened. Perhaps + the controller can explain this to the user and encourage her to + file a bug report? + + {Controllers should log bugs, but shouldn't annoy the user in case a + bug appears frequently.} + + CLOCK_SKEW + SKEW="+" / "-" SECONDS + MIN_SKEW="+" / "-" SECONDS. + SOURCE="DIRSERV:" IP ":" Port / + "NETWORKSTATUS:" IP ":" Port / + "OR:" IP ":" Port / + "CONSENSUS" + If "SKEW" is present, it's an estimate of how far we are from the + time declared in the source. (In other words, if we're an hour in + the past, the value is -3600.) "MIN_SKEW" is present, it's a lower + bound. If the source is a DIRSERV, we got the current time from a + connection to a dirserver. If the source is a NETWORKSTATUS, we + decided we're skewed because we got a v2 networkstatus from far in + the future. If the source is OR, the skew comes from a NETINFO + cell from a connection to another relay. If the source is + CONSENSUS, we decided we're skewed because we got a networkstatus + consensus from the future. + + {Tor should send this message to controllers when it thinks the + skew is so high that it will interfere with proper Tor operation. + Controllers shouldn't blindly adjust the clock, since the more + accurate source of skew info (DIRSERV) is currently + unauthenticated.} + + BAD_LIBEVENT + "METHOD=" libevent method + "VERSION=" libevent version + "BADNESS=" "BROKEN" / "BUGGY" / "SLOW" + "RECOVERED=" "NO" / "YES" + Tor knows about bugs in using the configured event method in this + version of libevent. "BROKEN" libevents won't work at all; + "BUGGY" libevents might work okay; "SLOW" libevents will work + fine, but not quickly. If "RECOVERED" is YES, Tor managed to + switch to a more reliable (but probably slower!) libevent method. + + {Controllers may want to warn the user if this event occurs, though + generally it's the fault of whoever built the Tor binary and there's + not much the user can do besides upgrade libevent or upgrade the + binary.} + + DIR_ALL_UNREACHABLE + Tor believes that none of the known directory servers are + reachable -- this is most likely because the local network is + down or otherwise not working, and might help to explain for the + user why Tor appears to be broken. + + {Controllers may want to warn the user if this event occurs; further + action is generally not possible.} + + Actions for STATUS_CLIENT events can be as follows: + + BOOTSTRAP + "PROGRESS=" num + "TAG=" Keyword + "SUMMARY=" String + ["WARNING=" String] + ["REASON=" Keyword] + ["COUNT=" num] + ["RECOMMENDATION=" Keyword] + ["HOST=" QuotedString] + ["HOSTADDR=" QuotedString] + + Tor has made some progress at establishing a connection to the + Tor network, fetching directory information, or making its first + circuit; or it has encountered a problem while bootstrapping. This + status event is especially useful for users with slow connections + or with connectivity problems. + + "Progress" gives a number between 0 and 100 for how far through + the bootstrapping process we are. "Summary" is a string that can + be displayed to the user to describe the *next* task that Tor + will tackle, i.e., the task it is working on after sending the + status event. "Tag" is a string that controllers can use to + recognize bootstrap phases, if they want to do something smarter + than just blindly displaying the summary string; see Section 5 + for the current tags that Tor issues. + + The StatusSeverity describes whether this is a normal bootstrap + phase (severity notice) or an indication of a bootstrapping + problem (severity warn). + + For bootstrap problems, we include the same progress, tag, and + summary values as we would for a normal bootstrap event, but we + also include "warning", "reason", "count", and "recommendation" + key/value combos. The "count" number tells how many bootstrap + problems there have been so far at this phase. The "reason" + string lists one of the reasons allowed in the ORCONN event. The + "warning" argument string with any hints Tor has to offer about + why it's having troubles bootstrapping. + + The "reason" values are long-term-stable controller-facing tags to + identify particular issues in a bootstrapping step. The warning + strings, on the other hand, are human-readable. Controllers + SHOULD NOT rely on the format of any warning string. Currently + the possible values for "recommendation" are either "ignore" or + "warn" -- if ignore, the controller can accumulate the string in + a pile of problems to show the user if the user asks; if warn, + the controller should alert the user that Tor is pretty sure + there's a bootstrapping problem. + + The "host" value is the identity digest (in hex) of the node we're + trying to connect to; the "hostaddr" is an address:port combination, + where 'address' is an ipv4 or ipv6 address. + + Currently Tor uses recommendation=ignore for the first + nine bootstrap problem reports for a given phase, and then + uses recommendation=warn for subsequent problems at that + phase. Hopefully this is a good balance between tolerating + occasional errors and reporting serious problems quickly. + + ENOUGH_DIR_INFO + Tor now knows enough network-status documents and enough server + descriptors that it's going to start trying to build circuits now. + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build + both exit and internal circuits. If not, Tor will only build internal + circuits.] + + {Controllers may want to use this event to decide when to indicate + progress to their users, but should not interrupt the user's browsing + to tell them so.} + + NOT_ENOUGH_DIR_INFO + We discarded expired statuses and server descriptors to fall + below the desired threshold of directory information. We won't + try to build any circuits until ENOUGH_DIR_INFO occurs again. + + {Controllers may want to use this event to decide when to indicate + progress to their users, but should not interrupt the user's browsing + to tell them so.} + + CIRCUIT_ESTABLISHED + Tor is able to establish circuits for client use. This event will + only be sent if we just built a circuit that changed our mind -- + that is, prior to this event we didn't know whether we could + establish circuits. + + {Suggested use: controllers can notify their users that Tor is + ready for use as a client once they see this status event. [Perhaps + controllers should also have a timeout if too much time passes and + this event hasn't arrived, to give tips on how to troubleshoot. + On the other hand, hopefully Tor will send further status events + if it can identify the problem.]} + + CIRCUIT_NOT_ESTABLISHED + "REASON=" "EXTERNAL_ADDRESS" / "DIR_ALL_UNREACHABLE" / "CLOCK_JUMPED" + We are no longer confident that we can build circuits. The "reason" + keyword provides an explanation: which other status event type caused + our lack of confidence. + + {Controllers may want to use this event to decide when to indicate + progress to their users, but should not interrupt the user's browsing + to do so.} + [Note: only REASON=CLOCK_JUMPED is implemented currently.] + + CONSENSUS_ARRIVED + Tor has received and validated a new consensus networkstatus. + (This event can be delayed a little while after the consensus + is received, if Tor needs to fetch certificates.) + + DANGEROUS_PORT + "PORT=" port + "RESULT=" "REJECT" / "WARN" + A stream was initiated to a port that's commonly used for + vulnerable-plaintext protocols. If the Result is "reject", we + refused the connection; whereas if it's "warn", we allowed it. + + {Controllers should warn their users when this occurs, unless they + happen to know that the application using Tor is in fact doing so + correctly (e.g., because it is part of a distributed bundle). They + might also want some sort of interface to let the user configure + their RejectPlaintextPorts and WarnPlaintextPorts config options.} + + DANGEROUS_SOCKS + "PROTOCOL=" "SOCKS4" / "SOCKS5" + "ADDRESS=" IP:port + A connection was made to Tor's SOCKS port using one of the SOCKS + approaches that doesn't support hostnames -- only raw IP addresses. + If the client application got this address from gethostbyname(), + it may be leaking target addresses via DNS. + + {Controllers should warn their users when this occurs, unless they + happen to know that the application using Tor is in fact doing so + correctly (e.g., because it is part of a distributed bundle).} + + SOCKS_UNKNOWN_PROTOCOL + "DATA=string" + A connection was made to Tor's SOCKS port that tried to use it + for something other than the SOCKS protocol. Perhaps the user is + using Tor as an HTTP proxy? The DATA is the first few characters + sent to Tor on the SOCKS port. + + {Controllers may want to warn their users when this occurs: it + indicates a misconfigured application.} + + SOCKS_BAD_HOSTNAME + "HOSTNAME=QuotedString" + Some application gave us a funny-looking hostname. Perhaps + it is broken? In any case it won't work with Tor and the user + should know. + + {Controllers may want to warn their users when this occurs: it + usually indicates a misconfigured application.} + + Actions for STATUS_SERVER can be as follows: + + EXTERNAL_ADDRESS + "ADDRESS=IP" + "HOSTNAME=NAME" + "METHOD=CONFIGURED/CONFIGURED_ORPORT/DIRSERV/RESOLVED/ + INTERFACE/GETHOSTNAME" + Our best idea for our externally visible IP has changed to 'IP'. If + 'HOSTNAME' is present, we got the new IP by resolving 'NAME'. If the + method is 'CONFIGURED', the IP was given verbatim as the Address + configuration option. If the method is 'CONFIGURED_ORPORT', the IP was + given verbatim in the ORPort configuration option. If the method is + 'RESOLVED', we resolved the Address configuration option to get the IP. + If the method is 'GETHOSTNAME', we resolved our hostname to get the IP. + If the method is 'INTERFACE', we got the address of one of our network + interfaces to get the IP. If the method is 'DIRSERV', a directory + server told us a guess for what our IP might be. + + {Controllers may want to record this info and display it to the user.} + + CHECKING_REACHABILITY + "ORADDRESS=IP:port" + "DIRADDRESS=IP:port" + We're going to start testing the reachability of our external OR port + or directory port. + + {This event could affect the controller's idea of server status, but + the controller should not interrupt the user to tell them so.} + + REACHABILITY_SUCCEEDED + "ORADDRESS=IP:port" + "DIRADDRESS=IP:port" + We successfully verified the reachability of our external OR port or + directory port (depending on which of ORADDRESS or DIRADDRESS is + given.) + + {This event could affect the controller's idea of server status, but + the controller should not interrupt the user to tell them so.} + + GOOD_SERVER_DESCRIPTOR + We successfully uploaded our server descriptor to at least one + of the directory authorities, with no complaints. + + {Originally, the goal of this event was to declare "every authority + has accepted the descriptor, so there will be no complaints + about it." But since some authorities might be offline, it's + harder to get certainty than we had thought. As such, this event + is equivalent to ACCEPTED_SERVER_DESCRIPTOR below. Controllers + should just look at ACCEPTED_SERVER_DESCRIPTOR and should ignore + this event for now.} + + SERVER_DESCRIPTOR_STATUS + "STATUS=" "LISTED" / "UNLISTED" + We just got a new networkstatus consensus, and whether we're in + it or not in it has changed. Specifically, status is "listed" + if we're listed in it but previous to this point we didn't know + we were listed in a consensus; and status is "unlisted" if we + thought we should have been listed in it (e.g. we were listed in + the last one), but we're not. + + {Moving from listed to unlisted is not necessarily cause for + alarm. The relay might have failed a few reachability tests, + or the Internet might have had some routing problems. So this + feature is mainly to let relay operators know when their relay + has successfully been listed in the consensus.} + + [Not implemented yet. We should do this in 0.2.2.x. -RD] + + NAMESERVER_STATUS + "NS=addr" + "STATUS=" "UP" / "DOWN" + "ERR=" message + One of our nameservers has changed status. + + {This event could affect the controller's idea of server status, but + the controller should not interrupt the user to tell them so.} + + NAMESERVER_ALL_DOWN + All of our nameservers have gone down. + + {This is a problem; if it happens often without the nameservers + coming up again, the user needs to configure more or better + nameservers.} + + DNS_HIJACKED + Our DNS provider is providing an address when it should be saying + "NOTFOUND"; Tor will treat the address as a synonym for "NOTFOUND". + + {This is an annoyance; controllers may want to tell admins that their + DNS provider is not to be trusted.} + + DNS_USELESS + Our DNS provider is giving a hijacked address instead of well-known + websites; Tor will not try to be an exit node. + + {Controllers could warn the admin if the relay is running as an + exit node: the admin needs to configure a good DNS server. + Alternatively, this happens a lot in some restrictive environments + (hotels, universities, coffeeshops) when the user hasn't registered.} + + BAD_SERVER_DESCRIPTOR + "DIRAUTH=addr:port" + "REASON=string" + A directory authority rejected our descriptor. Possible reasons + include malformed descriptors, incorrect keys, highly skewed clocks, + and so on. + + {Controllers should warn the admin, and try to cope if they can.} + + ACCEPTED_SERVER_DESCRIPTOR + "DIRAUTH=addr:port" + A single directory authority accepted our descriptor. + // actually notice + + {This event could affect the controller's idea of server status, but + the controller should not interrupt the user to tell them so.} + + REACHABILITY_FAILED + "ORADDRESS=IP:port" + "DIRADDRESS=IP:port" + We failed to connect to our external OR port or directory port + successfully. + + {This event could affect the controller's idea of server status. The + controller should warn the admin and suggest reasonable steps to take.} + + HIBERNATION_STATUS + "STATUS=" "AWAKE" | "SOFT" | "HARD" + Our bandwidth based accounting status has changed, and we are now + relaying traffic/rejecting new connections/hibernating. + + {This event could affect the controller's idea of server status. The + controller MAY inform the admin, though presumably the accounting was + explicitly enabled for a reason.} + + [This event was added in tor 0.2.9.0-alpha.] + +4.1.11. Our set of guard nodes has changed + + Syntax: + + "650" SP "GUARD" SP Type SP Name SP Status ... CRLF + Type = "ENTRY" + Name = ServerSpec + (Identifies the guard affected) + Status = "NEW" | "UP" | "DOWN" | "BAD" | "GOOD" | "DROPPED" + + The ENTRY type indicates a guard used for connections to the Tor + network. + + The Status values are: + + "NEW" -- This node was not previously used as a guard; now we have + picked it as one. + "DROPPED" -- This node is one we previously picked as a guard; we + no longer consider it to be a member of our guard list. + "UP" -- The guard now seems to be reachable. + "DOWN" -- The guard now seems to be unreachable. + "BAD" -- Because of flags set in the consensus and/or values in the + configuration, this node is now unusable as a guard. + "BAD_L2" -- This layer2 guard has expired or got removed from the + consensus. This node is removed from the layer2 guard set. + "GOOD" -- Because of flags set in the consensus and/or values in the + configuration, this node is now usable as a guard. + + Controllers must accept unrecognized types and unrecognized statuses. + +4.1.12. Network status has changed + + Syntax: + + "650" "+" "NS" CRLF 1*NetworkStatus "." CRLF "650" SP "OK" CRLF + + The event is used whenever our local view of a relay status changes. + This happens when we get a new v3 consensus (in which case the entries + we see are a duplicate of what we see in the NEWCONSENSUS event, + below), but it also happens when we decide to mark a relay as up or + down in our local status, for example based on connection attempts. + + [First added in 0.1.2.3-alpha] + +4.1.13. Bandwidth used on an application stream + + The syntax is: + + "650" SP "STREAM_BW" SP StreamID SP BytesWritten SP BytesRead SP + Time CRLF + BytesWritten = 1*DIGIT + BytesRead = 1*DIGIT + Time = ISOTime2Frac + + BytesWritten and BytesRead are the number of bytes written and read + by the application since the last STREAM_BW event on this stream. + + Note that from Tor's perspective, *reading* a byte on a stream means + that the application *wrote* the byte. That's why the order of "written" + vs "read" is opposite for stream_bw events compared to bw events. + + The Time field is provided only in versions 0.3.2.1-alpha and later. It + records when Tor created the bandwidth event. + + These events are generated about once per second per stream; no events + are generated for streams that have not written or read. These events + apply only to streams entering Tor (such as on a SOCKSPort, TransPort, + or so on). They are not generated for exiting streams. + +4.1.14. Per-country client stats + + The syntax is: + + "650" SP "CLIENTS_SEEN" SP TimeStarted SP CountrySummary SP + IPVersions CRLF + + We just generated a new summary of which countries we've seen clients + from recently. The controller could display this for the user, e.g. + in their "relay" configuration window, to give them a sense that they + are actually being useful. + + Currently only bridge relays will receive this event, but once we figure + out how to sufficiently aggregate and sanitize the client counts on + main relays, we might start sending these events in other cases too. + + TimeStarted is a quoted string indicating when the reported summary + counts from (in UTCS). + + The CountrySummary keyword has as its argument a comma-separated, + possibly empty set of "countrycode=count" pairs. For example (without + linebreak), + 650-CLIENTS_SEEN TimeStarted="2008-12-25 23:50:43" + CountrySummary=us=16,de=8,uk=8 + + The IPVersions keyword has as its argument a comma-separated set of + "protocol-family=count" pairs. For example, + IPVersions=v4=16,v6=40 + + Note that these values are rounded, not exact. The rounding + algorithm is specified in the description of "geoip-client-origins" + in dir-spec.txt. + +4.1.15. New consensus networkstatus has arrived + + The syntax is: + + "650" "+" "NEWCONSENSUS" CRLF 1*NetworkStatus "." CRLF "650" SP + "OK" CRLF + + A new consensus networkstatus has arrived. We include NS-style lines for + every relay in the consensus. NEWCONSENSUS is a separate event from the + NS event, because the list here represents every usable relay: so any + relay *not* mentioned in this list is implicitly no longer recommended. + + [First added in 0.2.1.13-alpha] + +4.1.16. New circuit buildtime has been set + + The syntax is: + + "650" SP "BUILDTIMEOUT_SET" SP Type SP "TOTAL_TIMES=" Total SP + "TIMEOUT_MS=" Timeout SP "XM=" Xm SP "ALPHA=" Alpha SP + "CUTOFF_QUANTILE=" Quantile SP "TIMEOUT_RATE=" TimeoutRate SP + "CLOSE_MS=" CloseTimeout SP "CLOSE_RATE=" CloseRate + CRLF + Type = "COMPUTED" / "RESET" / "SUSPENDED" / "DISCARD" / "RESUME" + Total = Integer count of timeouts stored + Timeout = Integer timeout in milliseconds + Xm = Estimated integer Pareto parameter Xm in milliseconds + Alpha = Estimated floating point Paredo parameter alpha + Quantile = Floating point CDF quantile cutoff point for this timeout + TimeoutRate = Floating point ratio of circuits that timeout + CloseTimeout = How long to keep measurement circs in milliseconds + CloseRate = Floating point ratio of measurement circuits that are closed + + A new circuit build timeout time has been set. If Type is "COMPUTED", + Tor has computed the value based on historical data. If Type is "RESET", + initialization or drastic network changes have caused Tor to reset + the timeout back to the default, to relearn again. If Type is + "SUSPENDED", Tor has detected a loss of network connectivity and has + temporarily changed the timeout value to the default until the network + recovers. If type is "DISCARD", Tor has decided to discard timeout + values that likely happened while the network was down. If type is + "RESUME", Tor has decided to resume timeout calculation. + + The Total value is the count of circuit build times Tor used in + computing this value. It is capped internally at the maximum number + of build times Tor stores (NCIRCUITS_TO_OBSERVE). + + The Timeout itself is provided in milliseconds. Internally, Tor rounds + this value to the nearest second before using it. + + [First added in 0.2.2.7-alpha] + +4.1.17. Signal received + + The syntax is: + + "650" SP "SIGNAL" SP Signal CRLF + + Signal = "RELOAD" / "DUMP" / "DEBUG" / "NEWNYM" / "CLEARDNSCACHE" + + A signal has been received and actions taken by Tor. The meaning of each + signal, and the mapping to Unix signals, is as defined in section 3.7. + Future versions of Tor MAY generate signals other than those listed here; + controllers MUST be able to accept them. + + If Tor chose to ignore a signal (such as NEWNYM), this event will not be + sent. Note that some options (like ReloadTorrcOnSIGHUP) may affect the + semantics of the signals here. + + Note that the HALT (SIGTERM) and SHUTDOWN (SIGINT) signals do not currently + generate any event. + + [First added in 0.2.3.1-alpha] + +4.1.18. Configuration changed + + The syntax is: + + StartReplyLine *(MidReplyLine) EndReplyLine + + StartReplyLine = "650-CONF_CHANGED" CRLF + MidReplyLine = "650-" KEYWORD ["=" VALUE] CRLF + EndReplyLine = "650 OK" + + Tor configuration options have changed (such as via a SETCONF or RELOAD + signal). KEYWORD and VALUE specify the configuration option that was changed. + Undefined configuration options contain only the KEYWORD. + +4.1.19. Circuit status changed slightly + + The syntax is: + + "650" SP "CIRC_MINOR" SP CircuitID SP CircEvent [SP Path] + [SP "BUILD_FLAGS=" BuildFlags] [SP "PURPOSE=" Purpose] + [SP "HS_STATE=" HSState] [SP "REND_QUERY=" HSAddress] + [SP "TIME_CREATED=" TimeCreated] + [SP "OLD_PURPOSE=" Purpose [SP "OLD_HS_STATE=" HSState]] CRLF + + CircEvent = + "PURPOSE_CHANGED" / ; circuit purpose or HS-related state changed + "CANNIBALIZED" ; circuit cannibalized + + Clients MUST accept circuit events not listed above. + + The "OLD_PURPOSE" field is provided for both PURPOSE_CHANGED and + CANNIBALIZED events. The "OLD_HS_STATE" field is provided whenever + the "OLD_PURPOSE" field is provided and is a hidden-service-related + purpose. + + Other fields are as specified in section 4.1.1 above. + + [First added in 0.2.3.11-alpha] + +4.1.20. Pluggable transport launched + + The syntax is: + + "650" SP "TRANSPORT_LAUNCHED" SP Type SP Name SP TransportAddress SP Port + Type = "server" | "client" + Name = The name of the pluggable transport + TransportAddress = An IPv4 or IPv6 address on which the pluggable + transport is listening for connections + Port = The TCP port on which it is listening for connections. + + A pluggable transport called 'Name' of type 'Type' was launched + successfully and is now listening for connections on 'Address':'Port'. + +4.1.21. Bandwidth used on an OR or DIR or EXIT connection + + The syntax is: + + "650" SP "CONN_BW" SP "ID=" ConnID SP "TYPE=" ConnType + SP "READ=" BytesRead SP "WRITTEN=" BytesWritten CRLF + + ConnType = "OR" / ; Carrying traffic within the tor network. This can + either be our own (client) traffic or traffic we're + relaying within the network. + "DIR" / ; Fetching tor descriptor data, or transmitting + descriptors we're mirroring. + "EXIT" ; Carrying traffic between the tor network and an + external destination. + + BytesRead = 1*DIGIT + BytesWritten = 1*DIGIT + + Controllers MUST tolerate unrecognized connection types. + + BytesWritten and BytesRead are the number of bytes written and read + by Tor since the last CONN_BW event on this connection. + + These events are generated about once per second per connection; no + events are generated for connections that have not read or written. + These events are only generated if TestingTorNetwork is set. + + [First added in 0.2.5.2-alpha] + +4.1.22. Bandwidth used by all streams attached to a circuit + + The syntax is: + + "650" SP "CIRC_BW" SP "ID=" CircuitID SP "READ=" BytesRead SP + "WRITTEN=" BytesWritten SP "TIME=" Time SP + "DELIVERED_READ=" DeliveredBytesRead SP + "OVERHEAD_READ=" OverheadBytesRead SP + "DELIVERED_WRITTEN=" DeliveredBytesWritten SP + "OVERHEAD_WRITTEN=" OverheadBytesWritten SP + "SS=" SlowStartState SP + "CWND=" CWNDCells SP + "RTT=" RTTMilliseconds SP + "MIN_RTT=" RTTMilliseconds CRLF + BytesRead = 1*DIGIT + BytesWritten = 1*DIGIT + OverheadBytesRead = 1*DIGIT + OverheadBytesWritten = 1*DIGIT + DeliveredBytesRead = 1*DIGIT + DeliveredBytesWritten = 1*DIGIT + SlowStartState = 0 or 1 + CWNDCells = 1*DIGIT + RTTMilliseconds= 1*DIGIT + Time = ISOTime2Frac + + BytesRead and BytesWritten are the number of bytes read and written + on this circuit since the last CIRC_BW event. These bytes have not + necessarily been validated by Tor, and can include invalid cells, + dropped cells, and ignored cells (such as padding cells). These + values include the relay headers, but not circuit headers. + + Circuit data that has been validated and processed by Tor is further + broken down into two categories: delivered payloads and overhead. + DeliveredBytesRead and DeliveredBytesWritten are the total relay cell + payloads transmitted since the last CIRC_BW event, not counting relay + cell headers or circuit headers. OverheadBytesRead and + OverheadBytesWritten are the extra unused bytes at the end of each + cell in order for it to be the fixed CELL_LEN bytes long. + + The sum of DeliveredBytesRead and OverheadBytesRead MUST be less than + BytesRead, and the same is true for their written counterparts. This + sum represents the total relay cell bytes on the circuit that + have been validated by Tor, not counting relay headers and cell headers. + Subtracting this sum (plus relay cell headers) from the BytesRead + (or BytesWritten) value gives the byte count that Tor has decided to + reject due to protocol errors, or has otherwise decided to ignore. + + The Time field is provided only in versions 0.3.2.1-alpha and later. It + records when Tor created the bandwidth event. + + The SS, CWND, RTT, and MIN_RTT fields are present only if the circuit + has negotiated congestion control to an onion service or Exit hop (any + intermediate leaky pipe congestion control hops are not examined here). + SS provides an indication if the circuit is in slow start (1), or not (0). + CWND is the size of the congestion window in terms of number of cells. + RTT is the N_EWMA smoothed current RTT value, and MIN_RTT is the minimum + RTT value of the circuit. The SS and CWND fields apply only to the + upstream direction of the circuit. The slow start state and CWND values + of the other endpoint may be different. + + These events are generated about once per second per circuit; no events + are generated for circuits that had no attached stream writing or + reading. + + [First added in 0.2.5.2-alpha] + + [DELIVERED_READ, OVERHEAD_READ, DELIVERED_WRITTEN, and OVERHEAD_WRITTEN + were added in Tor 0.3.4.0-alpha] + + [SS, CWND, RTT, and MIN_RTT were added in Tor 0.4.7.5-alpha] + +4.1.23. Per-circuit cell stats + + The syntax is: + + "650" SP "CELL_STATS" + [ SP "ID=" CircuitID ] + [ SP "InboundQueue=" QueueID SP "InboundConn=" ConnID ] + [ SP "InboundAdded=" CellsByType ] + [ SP "InboundRemoved=" CellsByType SP + "InboundTime=" MsecByType ] + [ SP "OutboundQueue=" QueueID SP "OutboundConn=" ConnID ] + [ SP "OutboundAdded=" CellsByType ] + [ SP "OutboundRemoved=" CellsByType SP + "OutboundTime=" MsecByType ] CRLF + CellsByType, MsecByType = CellType ":" 1*DIGIT + 0*( "," CellType ":" 1*DIGIT ) + CellType = 1*( "a" - "z" / "0" - "9" / "_" ) + + Examples are: + + 650 CELL_STATS ID=14 OutboundQueue=19403 OutboundConn=15 + OutboundAdded=create_fast:1,relay_early:2 + OutboundRemoved=create_fast:1,relay_early:2 + OutboundTime=create_fast:0,relay_early:0 + 650 CELL_STATS InboundQueue=19403 InboundConn=32 + InboundAdded=relay:1,created_fast:1 + InboundRemoved=relay:1,created_fast:1 + InboundTime=relay:0,created_fast:0 + OutboundQueue=6710 OutboundConn=18 + OutboundAdded=create:1,relay_early:1 + OutboundRemoved=create:1,relay_early:1 + OutboundTime=create:0,relay_early:0 + + ID is the locally unique circuit identifier that is only included if the + circuit originates at this node. + + Inbound and outbound refer to the direction of cell flow through the + circuit which is either to origin (inbound) or from origin (outbound). + + InboundQueue and OutboundQueue are identifiers of the inbound and + outbound circuit queues of this circuit. These identifiers are only + unique per OR connection. OutboundQueue is chosen by this node and + matches InboundQueue of the next node in the circuit. + + InboundConn and OutboundConn are locally unique IDs of inbound and + outbound OR connection. OutboundConn does not necessarily match + InboundConn of the next node in the circuit. + + InboundQueue and InboundConn are not present if the circuit originates + at this node. OutboundQueue and OutboundConn are not present if the + circuit (currently) ends at this node. + + InboundAdded and OutboundAdded are total number of cells by cell type + added to inbound and outbound queues. Only present if at least one cell + was added to a queue. + + InboundRemoved and OutboundRemoved are total number of cells by + cell type processed from inbound and outbound queues. InboundTime and + OutboundTime are total waiting times in milliseconds of all processed + cells by cell type. Only present if at least one cell was removed from + a queue. + + These events are generated about once per second per circuit; no + events are generated for circuits that have not added or processed any + cell. These events are only generated if TestingTorNetwork is set. + + [First added in 0.2.5.2-alpha] + +4.1.24. Token buckets refilled + + The syntax is: + + "650" SP "TB_EMPTY" SP BucketName [ SP "ID=" ConnID ] SP + "READ=" ReadBucketEmpty SP "WRITTEN=" WriteBucketEmpty SP + "LAST=" LastRefill CRLF + + BucketName = "GLOBAL" / "RELAY" / "ORCONN" + ReadBucketEmpty = 1*DIGIT + WriteBucketEmpty = 1*DIGIT + LastRefill = 1*DIGIT + + Examples are: + + 650 TB_EMPTY ORCONN ID=16 READ=0 WRITTEN=0 LAST=100 + 650 TB_EMPTY GLOBAL READ=93 WRITTEN=93 LAST=100 + 650 TB_EMPTY RELAY READ=93 WRITTEN=93 LAST=100 + + This event is generated when refilling a previously empty token + bucket. BucketNames "GLOBAL" and "RELAY" keywords are used for the + global or relay token buckets, BucketName "ORCONN" is used for the + token buckets of an OR connection. Controllers MUST tolerate + unrecognized bucket names. + + ConnID is only included if the BucketName is "ORCONN". + + If both global and relay buckets and/or the buckets of one or more OR + connections run out of tokens at the same time, multiple separate + events are generated. + + ReadBucketEmpty (WriteBucketEmpty) is the time in millis that the read + (write) bucket was empty since the last refill. LastRefill is the + time in millis since the last refill. + + If a bucket went negative and if refilling tokens didn't make it go + positive again, there will be multiple consecutive TB_EMPTY events for + each refill interval during which the bucket contained zero tokens or + less. In such a case, ReadBucketEmpty or WriteBucketEmpty are capped + at LastRefill in order not to report empty times more than once. + + These events are only generated if TestingTorNetwork is set. + + [First added in 0.2.5.2-alpha] + +4.1.25. HiddenService descriptors + + The syntax is: + + "650" SP "HS_DESC" SP Action SP HSAddress SP AuthType SP HsDir + [SP DescriptorID] [SP "REASON=" Reason] [SP "REPLICA=" Replica] + [SP "HSDIR_INDEX=" HSDirIndex] + + Action = "REQUESTED" / "UPLOAD" / "RECEIVED" / "UPLOADED" / "IGNORE" / + "FAILED" / "CREATED" + HSAddress = 16*Base32Character / 56*Base32Character / "UNKNOWN" + AuthType = "NO_AUTH" / "BASIC_AUTH" / "STEALTH_AUTH" / "UNKNOWN" + HsDir = LongName / Fingerprint / "UNKNOWN" + DescriptorID = 32*Base32Character / 43*Base64Character + Reason = "BAD_DESC" / "QUERY_REJECTED" / "UPLOAD_REJECTED" / "NOT_FOUND" / + "UNEXPECTED" / "QUERY_NO_HSDIR" / "QUERY_RATE_LIMITED" + Replica = 1*DIGIT + HSDirIndex = 64*HEXDIG + + These events will be triggered when required HiddenService descriptor is + not found in the cache and a fetch or upload with the network is performed. + + If the fetch was triggered with only a DescriptorID (using the HSFETCH + command for instance), the HSAddress only appears in the Action=RECEIVED + since there is no way to know the HSAddress from the DescriptorID thus + the value will be "UNKNOWN". + + If we already had the v0 descriptor, the newly fetched v2 descriptor + will be ignored and a "HS_DESC" event with "IGNORE" action will be + generated. + + For HsDir, LongName is always preferred. If HsDir cannot be found in node + list at the time event is sent, Fingerprint will be used instead. + + If Action is "FAILED", Tor SHOULD send Reason field as well. Possible + values of Reason are: + - "BAD_DESC" - descriptor was retrieved, but found to be unparsable. + - "QUERY_REJECTED" - query was rejected by HS directory. + - "UPLOAD_REJECTED" - descriptor was rejected by HS directory. + - "NOT_FOUND" - HS descriptor with given identifier was not found. + - "UNEXPECTED" - nature of failure is unknown. + - "QUERY_NO_HSDIR" - No suitable HSDir were found for the query. + - "QUERY_RATE_LIMITED" - query for this service is rate-limited + + For "QUERY_NO_HSDIR" or "QUERY_RATE_LIMITED", the HsDir will be set to + "UNKNOWN" which was introduced in tor 0.3.1.0-alpha and 0.4.1.0-alpha + respectively. + + If Action is "CREATED", Tor SHOULD send Replica field as well. The Replica + field contains the replica number of the generated descriptor. The Replica + number is specified in rend-spec.txt section 1.3 and determines the + descriptor ID of the descriptor. + + For hidden service v3, the following applies: + + The "HSDIR_INDEX=" is an optional field that is only for version 3 + which contains the computed index of the HsDir the descriptor was + uploaded to or fetched from. + + The "DescriptorID" key is the descriptor blinded key used for the index + value at the "HsDir". + + The "REPLICA=" field is not used for the "CREATED" event because v3 + doesn't use the replica number in the descriptor ID computation. + + Because client authentication is not yet implemented, the "AuthType" + field is always "NO_AUTH". + + [HS v3 support added 0.3.3.1-alpha] + +4.1.26. HiddenService descriptors content + + The syntax is: + + "650" "+" "HS_DESC_CONTENT" SP HSAddress SP DescId SP HsDir CRLF + Descriptor CRLF "." CRLF "650" SP "OK" CRLF + + HSAddress = 16*Base32Character / 56*Base32Character / "UNKNOWN" + DescId = 32*Base32Character / 32*Base64Character + HsDir = LongName / "UNKNOWN" + Descriptor = The text of the descriptor formatted as specified in + rend-spec.txt section 1.3 (v2) or rend-spec-v3.txt + section 2.4 (v3) or empty string on failure. + + This event is triggered when a successfully fetched HS descriptor is + received. The text of that descriptor is then replied. If the HS_DESC + event is enabled, it is replied just after the RECEIVED action. + + If a fetch fails, the Descriptor is an empty string and HSAddress is set + to "UNKNOWN". The HS_DESC event should be used to get more information on + the failed request. + + If the fetch fails for the QUERY_NO_HSDIR or QUERY_RATE_LIMITED reason from + the HS_DESC event, the HsDir is set to "UNKNOWN". This was introduced in + 0.3.1.0-alpha and 0.4.1.0-alpha respectively. + + It's expected to receive a reply relatively fast as in it's the time it + takes to fetch something over the Tor network. This can be between a + couple of seconds up to 60 seconds (not a hard limit). But, in any cases, + this event will reply either the descriptor's content or an empty one. + + [HS_DESC_CONTENT was added in Tor 0.2.7.1-alpha] + [HS v3 support added 0.3.3.1-alpha] + +4.1.27. Network liveness has changed + + Syntax: + + "650" SP "NETWORK_LIVENESS" SP Status CRLF + Status = "UP" / ; The network now seems to be reachable. + "DOWN" / ; The network now seems to be unreachable. + + Controllers MUST tolerate unrecognized status types. + + [NETWORK_LIVENESS was added in Tor 0.2.7.2-alpha] + +4.1.28. Pluggable Transport Logs + + Syntax: + + "650" SP "PT_LOG" SP PT=Program SP Message + + Program = The program path as defined in the *TransportPlugin + configuration option. Tor accepts relative and full path. + Message = The log message that the PT sends back to the tor parent + process minus the "LOG" string prefix. Formatted as + specified in pt-spec.txt section "3.3.4. Pluggable + Transport Log Message". + + This event is triggered when tor receives a log message from the PT. + + Example: + + PT (obfs4): LOG SEVERITY=debug MESSAGE="Connected to bridge A" + + the resulting control port event would be: + + Tor: 650 PT_LOG PT=/usr/bin/obs4proxy SEVERITY=debug MESSAGE="Connected to bridge A" + + [PT_LOG was added in Tor 0.4.0.1-alpha] + +4.1.29. Pluggable Transport Status + + Syntax: + + "650" SP "PT_STATUS" SP PT=Program SP TRANSPORT=Transport SP Message + + Program = The program path as defined in the *TransportPlugin + configuration option. Tor accepts relative and full path. + Transport = This value indicates a hint on what the PT is such as the + name or the protocol used for instance. + Message = The status message that the PT sends back to the tor parent + process minus the "STATUS" string prefix. Formatted as + specified in pt-spec.txt section "3.3.5 Pluggable + Transport Status Message". + + This event is triggered when tor receives a log message from the PT. + + Example: + + PT (obfs4): STATUS TRANSPORT=obfs4 CONNECT=Success + + the resulting control port event would be: + + Tor: 650 PT_STATUS PT=/usr/bin/obs4proxy TRANSPORT=obfs4 CONNECT=Success + + [PT_STATUS was added in Tor 0.4.0.1-alpha] + +5. Implementation notes + +5.1. Authentication + + If the control port is open and no authentication operation is enabled, Tor + trusts any local user that connects to the control port. This is generally + a poor idea. + + If the 'CookieAuthentication' option is true, Tor writes a "magic + cookie" file named "control_auth_cookie" into its data directory (or + to another file specified in the 'CookieAuthFile' option). To + authenticate, the controller must demonstrate that it can read the + contents of the cookie file: + + * Current versions of Tor support cookie authentication + + using the "COOKIE" authentication method: the controller sends the + contents of the cookie file, encoded in hexadecimal. This + authentication method exposes the user running a controller to an + unintended information disclosure attack whenever the controller + has greater filesystem read access than the process that it has + connected to. (Note that a controller may connect to a process + other than Tor.) It is almost never safe to use, even if the + controller's user has explicitly specified which filename to read + an authentication cookie from. For this reason, the COOKIE + authentication method has been deprecated and will be removed from + Tor before some future version of Tor. + + * 0.2.2.x versions of Tor starting with 0.2.2.36, and all versions of + + Tor after 0.2.3.12-alpha, support cookie authentication using the + "SAFECOOKIE" authentication method, which discloses much less + information about the contents of the cookie file. + + If the 'HashedControlPassword' option is set, it must contain the salted + hash of a secret password. The salted hash is computed according to the + S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier. + This is then encoded in hexadecimal, prefixed by the indicator sequence + "16:". Thus, for example, the password 'foo' could encode to: + + 16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2 + ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + salt hashed value + indicator + + You can generate the salt of a password by calling + + 'tor --hash-password <password>' + + or by using the example code in the Python and Java controller libraries. + To authenticate under this scheme, the controller sends Tor the original + secret that was used to generate the password, either as a quoted string + or encoded in hexadecimal. + +5.2. Don't let the buffer get too big. + + With old versions of Tor (before 0.2.0.16-alpha), if you ask for + lots of events, and 16MB of them queue up on the buffer, the Tor + process will close the socket. + + Newer Tor versions do not have this 16 MB buffer limit. However, + if you leave huge numbers of events unread, Tor may still run out + of memory, so you should still be careful about buffer size. + +5.3. Backward compatibility with v0 control protocol. + + The 'version 0' control protocol was replaced in Tor 0.1.1.x. Support + was removed in Tor 0.2.0.x. Every non-obsolete version of Tor now + supports the version 1 control protocol. + + For backward compatibility with the "version 0" control protocol, + Tor used to check whether the third octet of the first command is zero. + (If it was, Tor assumed that version 0 is in use.) + + This compatibility was removed in Tor 0.1.2.16 and 0.2.0.4-alpha. + +5.4. Tor config options for use by controllers + + Tor provides a few special configuration options for use by controllers. + These options are not saved to disk by SAVECONF. Most can be set and + examined by the SETCONF and GETCONF commands, but some (noted below) can + only be given in a torrc file or on the command line. + + Generally, these options make Tor unusable by disabling a portion of Tor's + normal operations. Unless a controller provides replacement functionality + to fill this gap, Tor will not correctly handle user requests. + + __AllDirActionsPrivate + + If true, Tor will try to launch all directory operations through + anonymous connections. (Ordinarily, Tor only tries to anonymize + requests related to hidden services.) This option will slow down + directory access, and may stop Tor from working entirely if it does not + yet have enough directory information to build circuits. + + (Boolean. Default: "0".) + + __DisablePredictedCircuits + + If true, Tor will not launch preemptive "general-purpose" circuits for + streams to attach to. (It will still launch circuits for testing and + for hidden services.) + + (Boolean. Default: "0".) + + __LeaveStreamsUnattached + + If true, Tor will not automatically attach new streams to circuits; + instead, the controller must attach them with ATTACHSTREAM. If the + controller does not attach the streams, their data will never be routed. + + (Boolean. Default: "0".) + + __HashedControlSessionPassword + + As HashedControlPassword, but is not saved to the torrc file by + SAVECONF. Added in Tor 0.2.0.20-rc. + + __ReloadTorrcOnSIGHUP + + If this option is true (the default), we reload the torrc from disk + every time we get a SIGHUP (from the controller or via a signal). + Otherwise, we don't. This option exists so that controllers can keep + their options from getting overwritten when a user sends Tor a HUP for + some other reason (for example, to rotate the logs). + + (Boolean. Default: "1") + + __OwningControllerProcess + + If this option is set to a process ID, Tor will periodically check + whether a process with the specified PID exists, and exit if one + does not. Added in Tor 0.2.2.28-beta. This option's intended use + is documented in section 3.23 with the related TAKEOWNERSHIP + command. + + Note that this option can only specify a single process ID, unlike + the TAKEOWNERSHIP command which can be sent along multiple control + connections. + + (String. Default: unset.) + + __OwningControllerFD + + If this option is a valid socket, Tor will start with an open control + connection on this socket. Added in Tor 0.3.3.1-alpha. + + This socket will be an owning controller, as if it had already called + TAKEOWNERSHIP. It will be automatically authenticated. This option + should only be used by other programs that are starting Tor. + + This option cannot be changed via SETCONF; it must be set in a torrc or + via the command line. + + (Integer. Default: -1.) + + __DisableSignalHandlers + + If this option is set to true during startup, then Tor will not install + any signal handlers to watch for POSIX signals. The SIGNAL controller + command will still work. + + This option is meant for embedding Tor inside another process, when + the controlling process would rather handle signals on its own. + + This option cannot be changed via SETCONF; it must be set in a torrc or + via the command line. + + (Boolean. Default: 0.) + +5.5. Phases from the Bootstrap status event. + + [For the bootstrap phases reported by Tor prior to 0.4.0.x, see + Section 5.6.] + + This section describes the various bootstrap phases currently reported + by Tor. Controllers should not assume that the percentages and tags + listed here will continue to match up, or even that the tags will stay + in the same order. Some phases might also be skipped (not reported) + if the associated bootstrap step is already complete, or if the phase + no longer is necessary. Only "starting" and "done" are guaranteed to + exist in all future versions. + + Current Tor versions enter these phases in order, monotonically. + Future Tors MAY revisit earlier phases, for example, if the network + fails. + +5.5.1. Overview of Bootstrap reporting. + + Bootstrap phases can be viewed as belonging to one of three stages: + + 1. Initial connection to a Tor relay or bridge + 2. Obtaining directory information + 3. Building an application circuit + + Tor doesn't specifically enter Stage 1; that is a side effect of + other actions that Tor is taking. Tor could be making a connection + to a fallback directory server, or it could be making a connection + to a guard candidate. Either one counts as Stage 1 for the purposes + of bootstrap reporting. + + Stage 2 might involve Tor contacting directory servers, or it might + involve reading cached directory information from a previous + session. Large parts of Stage 2 might be skipped if there is already + enough cached directory information to build circuits. Tor will + defer reporting progress in Stage 2 until Stage 1 is complete. + + Tor defers this reporting because Tor can already have enough + directory information to build circuits, yet not be able to connect + to a relay. Without that deferral, a user might misleadingly see Tor + stuck at a large amount of progress when something as fundamental as + making a TCP connection to any relay is failing. + + Tor also doesn't specifically enter Stage 3; that is a side effect + of Tor building circuits for some purpose or other. In a typical + client, Tor builds predicted circuits to provide lower latency for + application connection requests. In Stage 3, Tor might make new + connections to relays or bridges that it did not connect to in Stage + 1. + +5.5.2. Phases in Bootstrap Stage 1. + + Phase 0: + tag=starting summary="Starting" + + Tor starts out in this phase. + + Phase 1: + tag=conn_pt summary="Connecting to pluggable transport" + [This phase is new in 0.4.0.x] + + Tor is making a TCP connection to the transport plugin for a + pluggable transport. Tor will use this pluggable transport to make + its first connection to a bridge. + + Phase 2: + tag=conn_done_pt summary="Connected to pluggable transport" + [New in 0.4.0.x] + + Tor has completed its TCP connection to the transport plugin for the + pluggable transport. + + Phase 3: + tag=conn_proxy summary="Connecting to proxy" + [New in 0.4.0.x] + + Tor is making a TCP connection to a proxy to make its first + connection to a relay or bridge. + + Phase 4: + tag=conn_done_proxy summary="Connected to proxy" + [New in 0.4.0.x] + + Tor has completed its TCP connection to a proxy to make its first + connection to a relay or bridge. + + Phase 5: + tag=conn summary="Connecting to a relay" + [New in 0.4.0.x; prior versions of Tor had a "conn_dir" phase that + sometimes but not always corresponded to connecting to a directory server] + + Tor is making its first connection to a relay. This might be through + a pluggable transport or proxy connection that Tor has already + established. + + Phase 10: + tag=conn_done summary="Connected to a relay" + [New in 0.4.0.x] + + Tor has completed its first connection to a relay. + + Phase 14: + tag=handshake summary="Handshaking with a relay" + [New in 0.4.0.x; prior versions of Tor had a "handshake_dir" phase] + + Tor is in the process of doing a TLS handshake with a relay. + + Phase 15: + tag=handshake_done summary="Handshake with a relay done" + [New in 0.4.0.x] + + Tor has completed its TLS handshake with a relay. + +5.5.3. Phases in Bootstrap Stage 2. + + Phase 20: + tag=onehop_create summary="Establishing an encrypted directory connection" + [prior to 0.4.0.x, this was numbered 15] + + Once TLS is finished with a relay, Tor will send a CREATE_FAST cell + to establish a one-hop circuit for retrieving directory information. + It will remain in this phase until it receives the CREATED_FAST cell + back, indicating that the circuit is ready. + + Phase 25: + tag=requesting_status summary="Asking for networkstatus consensus" + [prior to 0.4.0.x, this was numbered 20] + + Once we've finished our one-hop circuit, we will start a new stream + for fetching the networkstatus consensus. We'll stay in this phase + until we get the 'connected' relay cell back, indicating that we've + established a directory connection. + + Phase 30: + tag=loading_status summary="Loading networkstatus consensus" + [prior to 0.4.0.x, this was numbered 25] + + Once we've established a directory connection, we will start fetching + the networkstatus consensus document. This could take a while; this + phase is a good opportunity for using the "progress" keyword to indicate + partial progress. + + This phase could stall if the directory server we picked doesn't + have a copy of the networkstatus consensus so we have to ask another, + or it does give us a copy but we don't find it valid. + + Phase 40: + tag=loading_keys summary="Loading authority key certs" + + Sometimes when we've finished loading the networkstatus consensus, + we find that we don't have all the authority key certificates for the + keys that signed the consensus. At that point we put the consensus we + fetched on hold and fetch the keys so we can verify the signatures. + + Phase 45 + tag=requesting_descriptors summary="Asking for relay descriptors" + + Once we have a valid networkstatus consensus and we've checked all + its signatures, we start asking for relay descriptors. We stay in this + phase until we have received a 'connected' relay cell in response to + a request for descriptors. + + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] + + Phase 50: + tag=loading_descriptors summary="Loading relay descriptors" + + We will ask for relay descriptors from several different locations, + so this step will probably make up the bulk of the bootstrapping, + especially for users with slow connections. We stay in this phase until + we have descriptors for a significant fraction of the usable relays + listed in the networkstatus consensus (this can be between 25% and 95% + depending on Tor's configuration and network consensus parameters). + This phase is also a good opportunity to use the "progress" keyword to + indicate partial steps. + + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] + + Phase 75: + tag=enough_dirinfo summary="Loaded enough directory info to build + circuits" + [New in 0.4.0.x; previously, Tor would misleadingly report the + "conn_or" tag once it had enough directory info.] + +5.5.4. Phases in Bootstrap Stage 3. + + Phase 76: + tag=ap_conn_pt summary="Connecting to pluggable transport to build + circuits" + [New in 0.4.0.x] + + This is similar to conn_pt, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + + Phase 77: + tag=ap_conn_done_pt summary="Connected to pluggable transport to build circuits" + [New in 0.4.0.x] + + This is similar to conn_done_pt, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + + Phase 78: + tag=ap_conn_proxy summary="Connecting to proxy to build circuits" + [New in 0.4.0.x] + + This is similar to conn_proxy, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + + Phase 79: + tag=ap_conn_done_proxy summary="Connected to proxy to build circuits" + [New in 0.4.0.x] + + This is similar to conn_done_proxy, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + + Phase 80: + tag=ap_conn summary="Connecting to a relay to build circuits" + [New in 0.4.0.x] + + This is similar to conn, except for making connections to additional + relays or bridges that Tor needs to use to build application + circuits. + + Phase 85: + tag=ap_conn_done summary="Connected to a relay to build circuits" + [New in 0.4.0.x] + + This is similar to conn_done, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + + Phase 89: + tag=ap_handshake summary="Finishing handshake with a relay to build circuits" + [New in 0.4.0.x] + + This is similar to handshake, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + + Phase 90: + tag=ap_handshake_done summary="Handshake finished with a relay to build circuits" + [New in 0.4.0.x] + + This is similar to handshake_done, except for making connections to + additional relays or bridges that Tor needs to use to build + application circuits. + + Phase 95: + tag=circuit_create summary="Establishing a[n internal] Tor circuit" + [prior to 0.4.0.x, this was numbered 90] + + Once we've finished our TLS handshake with the first hop of a circuit, + we will set about trying to make some 3-hop circuits in case we need them + soon. + + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] + + Phase 100: + tag=done summary="Done" + + A full 3-hop circuit has been established. Tor is ready to handle + application connections now. + + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] + +5.6. Bootstrap phases reported by older versions of Tor + + These phases were reported by Tor older than 0.4.0.x. For newer + versions of Tor, see Section 5.5. + + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build both + exit and internal circuits. When bootstrap completes, Tor will be ready + to handle an application requesting an exit circuit to services like the + World Wide Web. + + If the consensus does not contain Exits, Tor will only build internal + circuits. In this case, earlier statuses will have included "internal" + as indicated above. When bootstrap completes, Tor will be ready to handle + an application requesting an internal circuit to hidden services at + ".onion" addresses. + + If a future consensus contains Exits, exit circuits may become available.] + + Phase 0: + tag=starting summary="Starting" + + Tor starts out in this phase. + + Phase 5: + tag=conn_dir summary="Connecting to directory server" + + Tor sends this event as soon as Tor has chosen a directory server -- + e.g. one of the authorities if bootstrapping for the first time or + after a long downtime, or one of the relays listed in its cached + directory information otherwise. + + Tor will stay at this phase until it has successfully established + a TCP connection with some directory server. Problems in this phase + generally happen because Tor doesn't have a network connection, or + because the local firewall is dropping SYN packets. + + Phase 10: + tag=handshake_dir summary="Finishing handshake with directory server" + + This event occurs when Tor establishes a TCP connection with a relay or + authority used as a directory server (or its https proxy if it's using + one). Tor remains in this phase until the TLS handshake with the relay + or authority is finished. + + Problems in this phase generally happen because Tor's firewall is + doing more sophisticated MITM attacks on it, or doing packet-level + keyword recognition of Tor's handshake. + + Phase 15: + tag=onehop_create summary="Establishing an encrypted directory connection" + + Once TLS is finished with a relay, Tor will send a CREATE_FAST cell + to establish a one-hop circuit for retrieving directory information. + It will remain in this phase until it receives the CREATED_FAST cell + back, indicating that the circuit is ready. + + Phase 20: + tag=requesting_status summary="Asking for networkstatus consensus" + + Once we've finished our one-hop circuit, we will start a new stream + for fetching the networkstatus consensus. We'll stay in this phase + until we get the 'connected' relay cell back, indicating that we've + established a directory connection. + + Phase 25: + tag=loading_status summary="Loading networkstatus consensus" + + Once we've established a directory connection, we will start fetching + the networkstatus consensus document. This could take a while; this + phase is a good opportunity for using the "progress" keyword to indicate + partial progress. + + This phase could stall if the directory server we picked doesn't + have a copy of the networkstatus consensus so we have to ask another, + or it does give us a copy but we don't find it valid. + + Phase 40: + tag=loading_keys summary="Loading authority key certs" + + Sometimes when we've finished loading the networkstatus consensus, + we find that we don't have all the authority key certificates for the + keys that signed the consensus. At that point we put the consensus we + fetched on hold and fetch the keys so we can verify the signatures. + + Phase 45 + tag=requesting_descriptors summary="Asking for relay descriptors + [ for internal paths]" + + Once we have a valid networkstatus consensus and we've checked all + its signatures, we start asking for relay descriptors. We stay in this + phase until we have received a 'connected' relay cell in response to + a request for descriptors. + + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will ask for + descriptors for both exit and internal paths. If not, Tor will only ask + for descriptors for internal paths. In this case, this status will + include "internal" as indicated above.] + + Phase 50: + tag=loading_descriptors summary="Loading relay descriptors[ for internal + paths]" + + We will ask for relay descriptors from several different locations, + so this step will probably make up the bulk of the bootstrapping, + especially for users with slow connections. We stay in this phase until + we have descriptors for a significant fraction of the usable relays + listed in the networkstatus consensus (this can be between 25% and 95% + depending on Tor's configuration and network consensus parameters). + This phase is also a good opportunity to use the "progress" keyword to + indicate partial steps. + + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will download + descriptors for both exit and internal paths. If not, Tor will only + download descriptors for internal paths. In this case, this status will + include "internal" as indicated above.] + + Phase 80: + tag=conn_or summary="Connecting to the Tor network[ internally]" + + Once we have a valid consensus and enough relay descriptors, we choose + entry guard(s) and start trying to build some circuits. This step + is similar to the "conn_dir" phase above; the only difference is + the context. + + If a Tor starts with enough recent cached directory information, + its first bootstrap status event will be for the conn_or phase. + + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build both + exit and internal circuits. If not, Tor will only build internal circuits. + In this case, this status will include "internal(ly)" as indicated above.] + + Phase 85: + tag=handshake_or summary="Finishing handshake with first hop[ of internal + circuit]" + + This phase is similar to the "handshake_dir" phase, but it gets reached + if we finish a TCP connection to a Tor relay and we have already reached + the "conn_or" phase. We'll stay in this phase until we complete a TLS + handshake with a Tor relay. + + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor may be finishing + a handshake with the first hop if either an exit or internal circuit. In + this case, it won't specify which type. If the consensus contains no Exits, + Tor will only build internal circuits. In this case, this status will + include "internal" as indicated above.] + + Phase 90: + tag=circuit_create summary="Establishing a[n internal] Tor circuit" + + Once we've finished our TLS handshake with the first hop of a circuit, + we will set about trying to make some 3-hop circuits in case we need them + soon. + + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build both + exit and internal circuits. If not, Tor will only build internal circuits. + In this case, this status will include "internal" as indicated above.] + + Phase 100: + tag=done summary="Done" + + A full 3-hop circuit has been established. Tor is ready to handle + application connections now. + + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build both + exit and internal circuits. At this stage, Tor will be ready to handle + an application requesting an exit circuit to services like the World + Wide Web. + + If the consensus does not contain Exits, Tor will only build internal + circuits. In this case, earlier statuses will have included "internal" + as indicated above. At this stage, Tor will be ready to handle an + application requesting an internal circuit to hidden services at ".onion" + addresses. + + If a future consensus contains Exits, exit circuits may become available.] |