diff options
Diffstat (limited to 'doc/tor.1.txt')
| -rw-r--r-- | doc/tor.1.txt | 248 |
1 files changed, 191 insertions, 57 deletions
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index e136bd0f7e..5ea5623952 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -274,7 +274,7 @@ GENERAL OPTIONS all sockets will be set to this limit. Must be a value between 2048 and 262144, in 1024 byte increments. Default of 8192 is recommended. -[[ControlPort]] **ControlPort** __PORT__|**unix:**__path__|**auto**:: +[[ControlPort]] **ControlPort** __PORT__|**unix:**__path__|**auto** [__flags__]:: If set, Tor will accept connections on this port and allow those connections to control the Tor process using the Tor Control Protocol (described in control-spec.txt). Note: unless you also specify one or @@ -284,6 +284,14 @@ GENERAL OPTIONS method is sufficient to authenticate to Tor.) This option is required for many Tor controllers; most use the value of 9051. Set it to "auto" to have Tor pick a port for you. (Default: 0) + + + Recognized flags are:: + **GroupWritable**;; + Unix domain sockets only: makes the socket get created as + group-writable. + **WorldWritable**;; + Unix domain sockets only: makes the socket get created as + world-writable. [[ControlListenAddress]] **ControlListenAddress** __IP__[:__PORT__]:: Bind the controller listener to this address. If you specify a port, bind @@ -371,12 +379,6 @@ GENERAL OPTIONS chosen with their regular weights, multiplied by this number, which should be 1.0 or less. (Default: 1.0) -[[DynamicDHGroups]] **DynamicDHGroups** **0**|**1**:: - If this option is set to 1, when running as a server, generate our - own Diffie-Hellman group instead of using the one from Apache's mod_ssl. - This option may help circumvent censorship based on static - Diffie-Hellman parameters. (Default: 0) - [[AlternateDirAuthority]] **AlternateDirAuthority** [__nickname__] [**flags**] __address__:__port__ __fingerprint__ + [[AlternateBridgeAuthority]] **AlternateBridgeAuthority** [__nickname__] [**flags**] __address__:__port__ __ fingerprint__:: @@ -932,7 +934,9 @@ The following options are useful only for clients (that is, if Feel free to reuse a circuit that was first used at most NUM seconds ago, but never attach a new stream to a circuit that is too old. For hidden services, this applies to the __last__ time a circuit was used, not the - first. (Default: 10 minutes) + first. Circuits with streams constructed with SOCKS authentication via + SocksPorts that have **KeepAliveIsolateSOCKSAuth** ignore this value. + (Default: 10 minutes) [[MaxClientCircuitsPending]] **MaxClientCircuitsPending** __NUM__:: Do not allow more than NUM circuits to be pending at a time for handling @@ -961,6 +965,13 @@ The following options are useful only for clients (that is, if you. This directive can be specified multiple times to bind to multiple addresses/ports. (Default: 9050) + + + NOTE: Although this option allows you to specify an IP address + other than localhost, you should do so only with extreme caution. + The SOCKS protocol is unencrypted and (as we use it) + unauthenticated, so exposing it in this way could leak your + information to anybody watching your network, and allow anybody + to use your computer as an open proxy. + + + The _isolation flags_ arguments give Tor rules for which streams received on this SOCKSPort are allowed to share circuits with one another. Recognized isolation flags are: @@ -982,6 +993,9 @@ The following options are useful only for clients (that is, if **IsolateDestAddr**;; Don't share circuits with streams targeting a different destination address. + **KeepAliveIsolateSOCKSAuth**;; + If **IsolateSOCKSAuth** is enabled, keep alive circuits that have + streams with SOCKS authentication set indefinitely. **SessionGroup=**__INT__;; If no other isolation rules would prevent it, allow streams on this port to share circuits with streams from every other @@ -1001,20 +1015,18 @@ The following options are useful only for clients (that is, if **PreferIPv6**;; Tells exits that, if a host has both an IPv4 and an IPv6 address, we would prefer to connect to it via IPv6. (IPv4 is the default.) + - + - NOTE: Although this option allows you to specify an IP address - other than localhost, you should do so only with extreme caution. - The SOCKS protocol is unencrypted and (as we use it) - unauthenticated, so exposing it in this way could leak your - information to anybody watching your network, and allow anybody - to use your computer as an open proxy. + - + **CacheIPv4DNS**;; Tells the client to remember IPv4 DNS answers we receive from exit nodes via this connection. (On by default.) **CacheIPv6DNS**;; Tells the client to remember IPv6 DNS answers we receive from exit nodes via this connection. + **GroupWritable**;; + Unix domain sockets only: makes the socket get created as + group-writable. + **WorldWritable**;; + Unix domain sockets only: makes the socket get created as + world-writable. **CacheDNS**;; Tells the client to remember all DNS answers we receive from exit nodes via this connection. @@ -1311,7 +1323,7 @@ The following options are useful only for clients (that is, if [[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**:: If true, Tor downloads and caches "extra-info" documents. These documents contain information about servers other than the information in their - regular router descriptors. Tor does not use this information for anything + regular server descriptors. Tor does not use this information for anything itself; to save bandwidth, leave this option turned off. (Default: 0) [[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__:: @@ -1490,8 +1502,8 @@ is non-zero): [[BridgeRelay]] **BridgeRelay** **0**|**1**:: Sets the relay to act as a "bridge" with respect to relaying connections from bridge users to the Tor network. It mainly causes Tor to publish a - server descriptor to the bridge database, rather than publishing a relay - descriptor to the public directory authorities. + server descriptor to the bridge database, rather than + to the public directory authorities. [[ContactInfo]] **ContactInfo** __email_address__:: Administrative contact information for this relay or bridge. This line @@ -1517,22 +1529,41 @@ is non-zero): [[ExitPolicy]] **ExitPolicy** __policy__,__policy__,__...__:: Set an exit policy for this server. Each policy is of the form - "**accept**|**reject** __ADDR__[/__MASK__][:__PORT__]". If /__MASK__ is + "**accept[6]**|**reject[6]** __ADDR__[/__MASK__][:__PORT__]". If /__MASK__ is omitted then this policy just applies to the host given. Instead of giving - a host or network you can also use "\*" to denote the universe (0.0.0.0/0). + a host or network you can also use "\*" to denote the universe (0.0.0.0/0 + and ::/128), or \*4 to denote all IPv4 addresses, and \*6 to denote all + IPv6 addresses. __PORT__ can be a single port number, an interval of ports "__FROM_PORT__-__TO_PORT__", or "\*". If __PORT__ is omitted, that means "\*". + + For example, "accept 18.7.22.69:\*,reject 18.0.0.0/8:\*,accept \*:\*" would - reject any traffic destined for MIT except for web.mit.edu, and accept - anything else. + + reject any IPv4 traffic destined for MIT except for web.mit.edu, and accept + any other IPv4 or IPv6 traffic. + + + + Tor also allows IPv6 exit policy entries. For instance, "reject6 [FC00::]/7:\*" + rejects all destinations that share 7 most significant bit prefix with + address FC00::. Respectively, "accept6 [C000::]/3:\*" accepts all destinations + that share 3 most significant bit prefix with address C000::. + + + + accept6 and reject6 only produce IPv6 exit policy entries. Using an IPv4 + address with accept6 or reject6 is ignored and generates a warning. + accept/reject allows either IPv4 or IPv6 addresses. Use \*4 as an IPv4 + wildcard address, and \*6 as an IPv6 wildcard address. accept/reject * + expands to matching IPv4 and IPv6 wildcard address rules. + + + + To specify all IPv4 and IPv6 internal and link-local networks (including + 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, + 172.16.0.0/12, [::]/8, [FC00::]/7, [FE80::]/10, [FEC0::]/10, [FF00::]/8, + and [::]/127), you can use the "private" alias instead of an address. + ("private" always produces rules for IPv4 and IPv6 addresses, even when + used with accept6/reject6.) + + - To specify all internal and link-local networks (including 0.0.0.0/8, - 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, and - 172.16.0.0/12), you can use the "private" alias instead of an address. - These addresses are rejected by default (at the beginning of your exit - policy), along with your public IP address, unless you set the + Private addresses are rejected by default (at the beginning of your exit + policy), along with the configured primary public IPv4 and IPv6 addresses, + and any public IPv4 and IPv6 addresses on any interface on the relay. + These private addresses are rejected unless you set the ExitPolicyRejectPrivate config option to 0. For example, once you've done that, you could allow HTTP to 127.0.0.1 and block all other connections to internal networks with "accept 127.0.0.1:80,reject private:\*", though that @@ -1540,18 +1571,17 @@ is non-zero): public (external) IP address. See RFC 1918 and RFC 3330 for more details about internal and reserved IP address space. + + - Tor also allow IPv6 exit policy entries. For instance, "reject6 [FC00::]/7:*" - rejects all destinations that share 7 most significant bit prefix with - address FC00::. Respectively, "accept6 [C000::]/3:*" accepts all destinations - that share 3 most significant bit prefix with address C000::. + - + This directive can be specified multiple times so you don't have to put it all on one line. + + Policies are considered first to last, and the first match wins. If you - want to \_replace_ the default exit policy, end your exit policy with - either a reject \*:* or an accept \*:*. Otherwise, you're \_augmenting_ - (prepending to) the default exit policy. The default exit policy is: + + want to allow the same ports on IPv4 and IPv6, write your rules using + accept/reject \*. If you want to allow different ports on IPv4 and IPv6, + write your IPv6 rules using accept6/reject6 \*6, and your IPv4 rules using + accept/reject \*4. If you want to \_replace_ the default exit policy, end + your exit policy with either a reject \*:* or an accept \*:*. Otherwise, + you're \_augmenting_ (prepending to) the default exit policy. The default + exit policy is: + reject *:25 reject *:119 @@ -1565,9 +1595,15 @@ is non-zero): reject *:6881-6999 accept *:* + Since the default exit policy uses accept/reject *, it applies to both + IPv4 and IPv6 addresses. + [[ExitPolicyRejectPrivate]] **ExitPolicyRejectPrivate** **0**|**1**:: - Reject all private (local) networks, along with your own public IP address, - at the beginning of your exit policy. See above entry on ExitPolicy. + Reject all private (local) networks, along with your own configured public + IPv4 and IPv6 addresses, at the beginning of your exit policy. Also reject + any public IPv4 and IPv6 addresses on any interface on the relay. (If + IPv6Exit is not set, all IPv6 addresses will be rejected anyway.) + See above entry on ExitPolicy. (Default: 1) [[IPv6Exit]] **IPv6Exit** **0**|**1**:: @@ -1790,32 +1826,58 @@ is non-zero): (Default: P256) [[CellStatistics]] **CellStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the mean time that - cells spend in circuit queues to disk every 24 hours. (Default: 0) + Relays only. + When this option is enabled, Tor collects statistics about cell + processing (i.e. mean time a cell is spending in a queue, mean + number of cells in a queue and mean number of processed cells per + circuit) and writes them into disk every 24 hours. Onion router + operators may use the statistics for performance monitoring. + If ExtraInfoStatistics is enabled, it will published as part of + extra-info document. (Default: 0) [[DirReqStatistics]] **DirReqStatistics** **0**|**1**:: + Relays and bridges only. When this option is enabled, a Tor directory writes statistics on the number and response time of network status requests to disk every 24 - hours. (Default: 1) + hours. Enables relay and bridge operators to monitor how much their + server is being used by clients to learn about Tor network. + If ExtraInfoStatistics is enabled, it will published as part of + extra-info document. (Default: 1) [[EntryStatistics]] **EntryStatistics** **0**|**1**:: + Relays only. When this option is enabled, Tor writes statistics on the number of - directly connecting clients to disk every 24 hours. (Default: 0) + directly connecting clients to disk every 24 hours. Enables relay + operators to monitor how much inbound traffic that originates from + Tor clients passes through their server to go further down the + Tor network. If ExtraInfoStatistics is enabled, it will be published + as part of extra-info document. (Default: 0) [[ExitPortStatistics]] **ExitPortStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the number of relayed - bytes and opened stream per exit port to disk every 24 hours. (Default: 0) + Exit relays only. + When this option is enabled, Tor writes statistics on the number of + relayed bytes and opened stream per exit port to disk every 24 hours. + Enables exit relay operators to measure and monitor amounts of traffic + that leaves Tor network through their exit node. If ExtraInfoStatistics + is enabled, it will be published as part of extra-info document. + (Default: 0) [[ConnDirectionStatistics]] **ConnDirectionStatistics** **0**|**1**:: - When this option is enabled, Tor writes statistics on the bidirectional use - of connections to disk every 24 hours. (Default: 0) + Relays only. + When this option is enabled, Tor writes statistics on the amounts of + traffic it passes between itself and other relays to disk every 24 + hours. Enables relay operators to monitor how much their relay is + being used as middle node in the circuit. If ExtraInfoStatistics is + enabled, it will be published as part of extra-info document. + (Default: 0) [[HiddenServiceStatistics]] **HiddenServiceStatistics** **0**|**1**:: + Relays only. When this option is enabled, a Tor relay writes obfuscated statistics on its role as hidden-service directory, introduction point, or rendezvous point to disk every 24 hours. If ExtraInfoStatistics is also enabled, these statistics are further - published to the directory authorities. (Default: 0) + published to the directory authorities. (Default: 1) [[ExtraInfoStatistics]] **ExtraInfoStatistics** **0**|**1**:: When this option is enabled, Tor includes previously gathered statistics in @@ -1837,6 +1899,18 @@ is non-zero): this. If this option is set to 0, Tor will try to pick a reasonable default based on your system's physical memory. (Default: 0) +[[SigningKeyLifetime]] **SigningKeyLifetime** __N__ **days**|**weeks**|**months**:: + For how long should each Ed25519 signing key be valid? Tor uses a + permanent master identity key that can be kept offline, and periodically + generates new "signing" keys that it uses online. This option + configures their lifetime. + (Default: 30 days) + +[[OfflineMasterKey]] **OfflineMasterKey** **0**|**1**:: + If non-zero, the Tor relay will never generate or load its master secret + key. Instead, you'll have to use "tor --keygen" to manage the master + secret key. (Default: 0) + DIRECTORY SERVER OPTIONS ------------------------ @@ -1929,7 +2003,7 @@ on the public Tor network. [[BridgeAuthoritativeDir]] **BridgeAuthoritativeDir** **0**|**1**:: When this option is set in addition to **AuthoritativeDirectory**, Tor - accepts and serves router descriptors, but it caches and serves the main + accepts and serves server descriptors, but it caches and serves the main networkstatus documents rather than generating its own. (Default: 0) [[MinUptimeHidServDirectoryV2]] **MinUptimeHidServDirectoryV2** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: @@ -1948,9 +2022,9 @@ on the public Tor network. in the "params" line of its networkstatus vote. [[DirAllowPrivateAddresses]] **DirAllowPrivateAddresses** **0**|**1**:: - If set to 1, Tor will accept router descriptors with arbitrary "Address" + If set to 1, Tor will accept server descriptors with arbitrary "Address" elements. Otherwise, if the address is not an IP address or is a private IP - address, it will reject the router descriptor. (Default: 0) + address, it will reject the server descriptor. (Default: 0) [[AuthDirBadExit]] **AuthDirBadExit** __AddressPattern...__:: Authoritative directories only. A set of address patterns for servers that @@ -2007,6 +2081,13 @@ on the public Tor network. or more is always sufficient to satisfy the bandwidth requirement for the Guard flag. (Default: 250 KBytes) +[[AuthDirPinKeys]] **AuthDirPinKeys** **0**|**1**:: + Authoritative directories only. If non-zero, do not allow any relay to + publish a descriptor if any other relay has reserved its <Ed25519,RSA> + identity keypair. In all cases, Tor records every keypair it accepts + in a journal if it is new, or if it differs from the most recently + accepted pinning for one of the keys it contains. (Default: 0) + [[BridgePassword]] **BridgePassword** __Password__:: If set, contains an HTTP authenticator that tells a bridge authority to serve all requested bridge information. Used by the (only partially @@ -2095,8 +2176,8 @@ The following options are used to configure a hidden service. option multiple times; each time applies to the service using the most recent HiddenServiceDir. By default, this option maps the virtual port to the same port on 127.0.0.1 over TCP. You may override the target port, - address, or both by specifying a target of addr, port, or addr:port. - (You can specify an IPv6 target as [addr]:port.) + address, or both by specifying a target of addr, port, addr:port, or + **unix:**__path__. (You can specify an IPv6 target as [addr]:port.) You may also have multiple lines with the same VIRTPORT: when a user connects to that VIRTPORT, one of the TARGETs from those lines will be chosen at random. @@ -2129,6 +2210,16 @@ The following options are used to configure a hidden service. not an authorization mechanism; it is instead meant to be a mild inconvenience to port-scanners.) (Default: 0) +[[HiddenServiceMaxStreams]] **HiddenServiceMaxStreams** __N__:: + The maximum number of simultaneous streams (connections) per rendezvous + circuit. (Setting this to 0 will allow an unlimited number of simultanous + streams.) (Default: 0) + +[[HiddenServiceMaxStreamsCloseCircuit]] **HiddenServiceMaxStreamsCloseCircuit** **0**|**1**:: + If set to 1, then exceeding **HiddenServiceMaxStreams** will cause the + offending rendezvous circuit to be torn down, as opposed to stream creation + requests that exceed the limit being silently ignored. (Default: 0) + [[RendPostPeriod]] **RendPostPeriod** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**:: Every time the specified period elapses, Tor uploads any rendezvous service descriptors to the directory servers. This information is also @@ -2140,6 +2231,10 @@ The following options are used to configure a hidden service. only owner is able to read the hidden service directory. (Default: 0) Has no effect on Windows. +[[HiddenServiceNumIntroductionPoints]] **HiddenServiceNumIntroductionPoints** __NUM__:: + Number of introduction points the hidden service will have. You can't + have more than 10. (Default: 3) + TESTING NETWORK OPTIONS ----------------------- @@ -2212,7 +2307,7 @@ The following options are used for running a testing Tor network. that **TestingTorNetwork** is set. (Default: 30 minutes) [[TestingEstimatedDescriptorPropagationTime]] **TestingEstimatedDescriptorPropagationTime** __N__ **minutes**|**hours**:: - Clients try downloading router descriptors from directory caches after this + Clients try downloading server descriptors from directory caches after this time. Changing this requires that **TestingTorNetwork** is set. (Default: 10 minutes) @@ -2260,7 +2355,7 @@ The following options are used for running a testing Tor network. this requires that **TestingTorNetwork** is set. (Default: 8) [[TestingDescriptorMaxDownloadTries]] **TestingDescriptorMaxDownloadTries** __NUM__:: - Try this often to download a router descriptor before giving up. + Try this often to download a server descriptor before giving up. Changing this requires that **TestingTorNetwork** is set. (Default: 8) [[TestingMicrodescMaxDownloadTries]] **TestingMicrodescMaxDownloadTries** __NUM__:: @@ -2281,6 +2376,14 @@ The following options are used for running a testing Tor network. has to be set. See the **ExcludeNodes** option for more information on how to specify nodes. +[[TestingDirAuthVoteExitIsStrict]] **TestingDirAuthVoteExitIsStrict** **0**|**1** :: + If True (1), a node will never receive the Exit flag unless it is specified + in the **TestingDirAuthVoteExit** list, regardless of its uptime, bandwidth, + or exit policy. + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + [[TestingDirAuthVoteGuard]] **TestingDirAuthVoteGuard** __node__,__node__,__...__:: A list of identity fingerprints and country codes and address patterns of nodes to vote Guard for regardless of their @@ -2290,15 +2393,29 @@ The following options are used for running a testing Tor network. In order for this option to have any effect, **TestingTorNetwork** has to be set. +[[TestingDirAuthVoteGuardIsStrict]] **TestingDirAuthVoteGuardIsStrict** **0**|**1** :: + If True (1), a node will never receive the Guard flag unless it is specified + in the **TestingDirAuthVoteGuard** list, regardless of its uptime and bandwidth. + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + [[TestingDirAuthVoteHSDir]] **TestingDirAuthVoteHSDir** __node__,__node__,__...__:: A list of identity fingerprints and country codes and address patterns of nodes to vote HSDir for regardless of their - uptime and ORPort connectivity. See the **ExcludeNodes** option for more + uptime and DirPort. See the **ExcludeNodes** option for more information on how to specify nodes. + In order for this option to have any effect, **TestingTorNetwork** and **VoteOnHidServDirectoriesV2** both have to be set. +[[TestingDirAuthVoteHSDirIsStrict]] **TestingDirAuthVoteHSDirIsStrict** **0**|**1** :: + If True (1), a node will never receive the HSDir flag unless it is specified + in the **TestingDirAuthVoteHSDir** list, regardless of its uptime and DirPort. + + + In order for this option to have any effect, **TestingTorNetwork** + has to be set. + [[TestingEnableConnBwEvent]] **TestingEnableConnBwEvent** **0**|**1**:: If this option is set, then Tor controllers may register for CONN_BW events. Changing this requires that **TestingTorNetwork** is set. @@ -2319,6 +2436,23 @@ The following options are used for running a testing Tor network. authority on a testing network. Overrides the usual default lower bound of 4 KB. (Default: 0) +[[TestingLinkCertLifetime]] **TestingLinkCertifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: + Overrides the default lifetime for the certificates used to authenticate + our X509 link cert with our ed25519 signing key. + (Default: 2 days) + +[[TestingAuthKeyLifetime]] **TestingAuthKeyLifetime** __N__ **seconds**|**minutes**|**hours**|**days**|**weeks**|**months**:: + Overrides the default lifetime for a signing Ed25519 TLS Link authentication + key. + (Default: 2 days) + +[[TestingLinkKeySlop]] **TestingLinkKeySlop** __N__ **seconds**|**minutes**|**hours**:: +[[TestingAuthKeySlop]] **TestingAuthKeySlop** __N__ **seconds**|**minutes**|**hours**:: +[[TestingSigningKeySlop]] **TestingSigningKeySlop** __N__ **seconds**|**minutes**|**hours**:: + How early before the official expiration of a an Ed25519 signing key do + we replace it and issue a new key? + (Default: 3 hours for link and auth; 1 day for signing.) + SIGNALS ------- @@ -2402,7 +2536,7 @@ __DataDirectory__**/state**:: below). - When the file was last written - What version of Tor generated the state file - - A short history of bandwidth usage, as produced in the router + - A short history of bandwidth usage, as produced in the server descriptors. __DataDirectory__**/bw_accounting**:: @@ -2447,7 +2581,7 @@ __DataDirectory__**/unverified-microdesc-consensus**:: to check yet. __DataDirectory__**/unparseable-desc**:: - Onion router descriptors that Tor was unable to parse are dumped to this + Onion server descriptors that Tor was unable to parse are dumped to this file. Only used for debugging. __DataDirectory__**/router-stability**:: |