diff options
| author | Nick Mathewson <nickm@torproject.org> | 2023-10-12 12:27:58 -0400 |
|---|---|---|
| committer | Nick Mathewson <nickm@torproject.org> | 2023-10-12 12:27:58 -0400 |
| commit | e4e0d93d56ee8c1aec4c2efaa7046b651f0fe55c (patch) | |
| tree | 15a085da265ae3b2b70f29a70f910a5371059a78 /control-spec.txt | |
| parent | b719a373934d3e79ef833446c6aeeb19be485510 (diff) | |
| download | torspec-e4e0d93d56ee8c1aec4c2efaa7046b651f0fe55c.tar.gz torspec-e4e0d93d56ee8c1aec4c2efaa7046b651f0fe55c.zip | |
Move all text-only specifications into the OLD_TXT directory.
Diffstat (limited to 'control-spec.txt')
| -rw-r--r-- | control-spec.txt | 4418 |
1 files changed, 0 insertions, 4418 deletions
diff --git a/control-spec.txt b/control-spec.txt deleted file mode 100644 index 52e11a0..0000000 --- a/control-spec.txt +++ /dev/null @@ -1,4418 +0,0 @@ - - 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.] |