diff options
Diffstat (limited to 'doc/tor.1.txt')
| -rw-r--r-- | doc/tor.1.txt | 658 |
1 files changed, 460 insertions, 198 deletions
diff --git a/doc/tor.1.txt b/doc/tor.1.txt index d7884968e6..f894061808 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -231,12 +231,15 @@ GENERAL OPTIONS usage for \_relayed traffic_ on this node to the specified number of bytes per second, and the average outgoing bandwidth usage to that same value. Relayed traffic currently is calculated to include answers to directory - requests, but that may change in future versions. (Default: 0) + requests, but that may change in future versions. They do not include directory + fetches by the relay (from authority or other relays), because that is considered + "client" activity. (Default: 0) [[RelayBandwidthBurst]] **RelayBandwidthBurst** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: If not 0, limit the maximum token bucket size (also known as the burst) for \_relayed traffic_ to the given number of bytes in each direction. - (Default: 0) + They do not include directory fetches by the relay (from authority + or other relays), because that is considered "client" activity. (Default: 0) [[PerConnBWRate]] **PerConnBWRate** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: If this option is set manually, or via the "perconnbwrate" consensus @@ -415,6 +418,16 @@ GENERAL OPTIONS DataDirectory. If the option is set to 1, make the DataDirectory readable by the default GID. (Default: 0) +[[CacheDirectory]] **CacheDirectory** __DIR__:: + Store cached directory data in DIR. Can not be changed while tor is + running. + (Default: uses the value of DataDirectory.) + +[[CacheDirectoryGroupReadable]] **CacheDirectoryGroupReadable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read the + CacheDirectory. If the option is set to 1, make the CacheDirectory readable + by the default GID. (Default: 0) + [[FallbackDir]] **FallbackDir** __ipv4address__:__port__ orport=__port__ id=__fingerprint__ [weight=__num__] [ipv6=**[**__ipv6address__**]**:__orport__]:: When we're unable to connect to any directory cache for directory info (usually because we don't know about any yet) we try a directory authority. @@ -527,13 +540,21 @@ GENERAL OPTIONS (Default: 1) [[FetchUselessDescriptors]] **FetchUselessDescriptors** **0**|**1**:: - If set to 1, Tor will fetch every consensus flavor, descriptor, and - certificate that it hears about. Otherwise, it will avoid fetching useless - descriptors: flavors that it is not using to build circuits, and authority - certificates it does not trust. This option is useful if you're using a + If set to 1, Tor will fetch every consensus flavor, and all server + descriptors and authority certificates referenced by those consensuses, + except for extra info descriptors. When this option is 1, Tor will also + keep fetching descriptors, even when idle. + If set to 0, Tor will avoid fetching useless descriptors: flavors that it + is not using to build circuits, and authority certificates it does not + trust. When Tor hasn't built any application circuits, it will go idle, + and stop fetching descriptors. This option is useful if you're using a tor client with an external parser that uses a full consensus. - This option fetches all documents, **DirCache** fetches and serves - all documents. (Default: 0) + This option fetches all documents except extrainfo descriptors, + **DirCache** fetches and serves all documents except extrainfo + descriptors, **DownloadExtraInfo*** fetches extrainfo documents, and serves + them if **DirCache** is on, and **UseMicrodescriptors** changes the + flavour of consensues and descriptors that is fetched and used for + building circuits. (Default: 0) [[HTTPProxy]] **HTTPProxy** __host__[:__port__]:: Tor will make all its directory requests through this host:port (or host:80 @@ -595,10 +616,10 @@ GENERAL OPTIONS in accordance to RFC 1929. Both username and password must be between 1 and 255 characters. -[[SocksSocketsGroupWritable]] **SocksSocketsGroupWritable** **0**|**1**:: +[[UnixSocksGroupWritable]] **UnixSocksGroupWritable** **0**|**1**:: If this option is set to 0, don't allow the filesystem group to read and - write unix sockets (e.g. SocksSocket). If the option is set to 1, make - the SocksSocket socket readable and writable by the default GID. (Default: 0) + write unix sockets (e.g. SocksPort unix:). If the option is set to 1, make + the Unix socket readable and writable by the default GID. (Default: 0) [[KeepalivePeriod]] **KeepalivePeriod** __NUM__:: To keep firewalls from expiring connections, send a padding keepalive cell @@ -637,7 +658,8 @@ GENERAL OPTIONS + The currently recognized domains are: general, crypto, net, config, fs, protocol, mm, http, app, control, circ, rend, bug, dir, dirserv, or, edge, - acct, hist, and handshake. Domain names are case-insensitive. + + acct, hist, handshake, heartbeat, channel, sched, guard, consdiff, and dos. + Domain names are case-insensitive. + + For example, "`Log [handshake]debug [~net,~mm]info notice stdout`" sends to stdout: all handshake messages of any severity, all info-and-higher @@ -663,7 +685,7 @@ GENERAL OPTIONS be used twice, once with an IPv4 address and once with an IPv6 address. IPv6 addresses should be wrapped in square brackets. This setting will be ignored for connections to the loopback addresses - (127.0.0.0/8 and ::1). + (127.0.0.0/8 and ::1), and is not used for DNS requests as well. [[OutboundBindAddressOR]] **OutboundBindAddressOR** __IP__:: Make all outbound non-exit (relay and other) connections @@ -715,6 +737,11 @@ GENERAL OPTIONS log entries are marked with "Tor-__tag__". Can not be changed while tor is running. (Default: none) +[[AndroidIdentityTag]] **AndroidIdentityTag** __tag__:: + When logging to Android's logging subsystem, adds a tag to the log identity + such that log entries are marked with "Tor-__tag__". Can not be changed while + tor is running. (Default: none) + [[SafeLogging]] **SafeLogging** **0**|**1**|**relay**:: Tor can scrub potentially sensitive strings from log messages (e.g. addresses) by replacing them with the string [scrubbed]. This way logs can @@ -1184,6 +1211,7 @@ The following options are useful only for clients (that is, if on different SocksPorts, TransPorts, etc are always isolated from one another. This option overrides that behavior.) +// Anchor only for formatting, not visible in the man page. [[OtherSocksPortFlags]]:: Other recognized __flags__ for a SocksPort are: **NoIPv4Traffic**;; @@ -1209,7 +1237,7 @@ The following options are useful only for clients (that is, if flag is not supported. **CacheIPv4DNS**;; Tells the client to remember IPv4 DNS answers we receive from exit - nodes via this connection. (On by default.) + nodes via this connection. **CacheIPv6DNS**;; Tells the client to remember IPv6 DNS answers we receive from exit nodes via this connection. @@ -1224,8 +1252,8 @@ The following options are useful only for clients (that is, if nodes via this connection. **UseIPv4Cache**;; Tells the client to use any cached IPv4 DNS answers we have when making - requests via this connection. (NOTE: This option, along UseIPv6Cache - and UseDNSCache, can harm your anonymity, and probably + requests via this connection. (NOTE: This option, or UseIPv6Cache + or UseDNSCache, can harm your anonymity, and probably won't help performance as much as you might expect. Use with care!) **UseIPv6Cache**;; Tells the client to use any cached IPv6 DNS answers we have when making @@ -1248,6 +1276,7 @@ The following options are useful only for clients (that is, if authentication" when IsolateSOCKSAuth is disabled, or when this option is set. +// Anchor only for formatting, not visible in the man page. [[SocksPortFlagsMisc]]:: Flags are processed left to right. If flags conflict, the last flag on the line is used, and all earlier flags are ignored. No error is issued for @@ -1513,14 +1542,107 @@ The following options are useful only for clients (that is, if If no nodes in Tor2webRendezvousPoints are currently available for use, Tor will choose a random node when building HS circuits. +[[HSLayer2Nodes]] **HSLayer2Nodes** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, country codes, and + address patterns of nodes that are allowed to be used as the + second hop in all client or service-side Onion Service circuits. + This option mitigates attacks where the adversary runs middle nodes + and induces your client or service to create many circuits, in order + to discover your primary guard node. + (Default: Any node in the network may be used in the second hop.) + + + (Example: + HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + + + When this is set, the resulting hidden service paths will + look like: + + + C - G - L2 - M - Rend + + C - G - L2 - M - HSDir + + C - G - L2 - M - Intro + + S - G - L2 - M - Rend + + S - G - L2 - M - HSDir + + S - G - L2 - M - Intro + + + + where C is this client, S is the service, G is the Guard node, + L2 is a node from this option, and M is a random middle node. + Rend, HSDir, and Intro point selection is not affected by this + option. + + + This option may be combined with HSLayer3Nodes to create + paths of the form: + + + C - G - L2 - L3 - Rend + + C - G - L2 - L3 - M - HSDir + + C - G - L2 - L3 - M - Intro + + S - G - L2 - L3 - M - Rend + + S - G - L2 - L3 - HSDir + + S - G - L2 - L3 - Intro + + + + ExcludeNodes have higher priority than HSLayer2Nodes, + which means that nodes specified in ExcludeNodes will not be + picked. + + + This option is meant to be managed by a Tor controller such as + https://github.com/mikeperry-tor/vanguards that selects and + updates this set of nodes for you. Hence it does not do load + balancing if fewer than 20 nodes are selected, and if no nodes in + HSLayer2Nodes are currently available for use, Tor will not work. + Please use extreme care if you are setting this option manually. + +[[HSLayer3Nodes]] **HSLayer3Nodes** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, country codes, and + address patterns of nodes that are allowed to be used as the + third hop in all client and service-side Onion Service circuits. + This option mitigates attacks where the adversary runs middle nodes + and induces your client or service to create many circuits, in order + to discover your primary or Layer2 guard nodes. + (Default: Any node in the network may be used in the third hop.) + + + (Example: + HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + + + When this is set by itself, the resulting hidden service paths + will look like: + + C - G - M - L3 - Rend + + C - G - M - L3 - M - HSDir + + C - G - M - L3 - M - Intro + + S - G - M - L3 - M - Rend + + S - G - M - L3 - HSDir + + S - G - M - L3 - Intro + + where C is this client, S is the service, G is the Guard node, + L2 is a node from this option, and M is a random middle node. + Rend, HSDir, and Intro point selection is not affected by this + option. + + + While it is possible to use this option by itself, it should be + combined with HSLayer2Nodes to create paths of the form: + + + C - G - L2 - L3 - Rend + + C - G - L2 - L3 - M - HSDir + + C - G - L2 - L3 - M - Intro + + S - G - L2 - L3 - M - Rend + + S - G - L2 - L3 - HSDir + + S - G - L2 - L3 - Intro + + + + ExcludeNodes have higher priority than HSLayer3Nodes, + which means that nodes specified in ExcludeNodes will not be + picked. + + + This option is meant to be managed by a Tor controller such as + https://github.com/mikeperry-tor/vanguards that selects and + updates this set of nodes for you. Hence it does not do load + balancing if fewer than 20 nodes are selected, and if no nodes in + HSLayer3Nodes are currently available for use, Tor will not work. + Please use extreme care if you are setting this option manually. + [[UseMicrodescriptors]] **UseMicrodescriptors** **0**|**1**|**auto**:: Microdescriptors are a smaller version of the information that Tor needs in order to build its circuits. Using microdescriptors makes Tor clients download less directory information, thus saving bandwidth. Directory caches need to fetch regular descriptors and microdescriptors, so this - option doesn't save any bandwidth for them. If this option is set to - "auto" (recommended) then it is on for all clients that do not set - FetchUselessDescriptors. (Default: auto) + option doesn't save any bandwidth for them. For legacy reasons, auto is + accepted, but it has the same effect as 1. (Default: auto) [[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ + @@ -1645,14 +1767,6 @@ The following options are useful only for clients (that is, if which are advanced by connection failures. (Default: 0, 3, 7, 3600, 10800, 25200, 54000, 111600, 262800) -[[ClientBootstrapConsensusMaxDownloadTries]] **ClientBootstrapConsensusMaxDownloadTries** __NUM__:: - Try this many times to download a consensus while bootstrapping using - fallback directory mirrors before giving up. (Default: 7) - -[[ClientBootstrapConsensusAuthorityOnlyMaxDownloadTries]] **ClientBootstrapConsensusAuthorityOnlyMaxDownloadTries** __NUM__:: - Try this many times to download a consensus while bootstrapping using - authorities before giving up. (Default: 4) - [[ClientBootstrapConsensusMaxInProgressTries]] **ClientBootstrapConsensusMaxInProgressTries** __NUM__:: Try this many simultaneous connections to download a consensus before waiting for one to complete, timeout, or error out. (Default: 3) @@ -1728,8 +1842,8 @@ is non-zero): "**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 - and ::/128), or \*4 to denote all IPv4 addresses, and \*6 to denote all - IPv6 addresses. + and ::/0), 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 "\*". + @@ -1777,8 +1891,15 @@ is non-zero): 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: + + you're \_augmenting_ (prepending to) the default exit policy. + + + + If you want to use a reduced exit policy rather than the default exit + policy, set "ReducedExitPolicy 1". If you want to _replace_ the default + exit policy with your custom exit policy, end your exit policy with either + a reject *:* or an accept *:*. Otherwise, you’re _augmenting_ (prepending + to) the default or reduced exit policy. + + + + The default exit policy is: reject *:25 reject *:119 @@ -1792,6 +1913,7 @@ is non-zero): reject *:6881-6999 accept *:* +// Anchor only for formatting, not visible in the man page. [[ExitPolicyDefault]]:: Since the default exit policy uses accept/reject *, it applies to both IPv4 and IPv6 addresses. @@ -1814,6 +1936,99 @@ is non-zero): to disclose. (Default: 0) +[[ReducedExitPolicy]] **ReducedExitPolicy** **0**|**1**:: + If set, use a reduced exit policy rather than the default one. + + + + The reduced exit policy is an alternative to the default exit policy. It + allows as many Internet services as possible while still blocking the + majority of TCP ports. Currently, the policy allows approximately 65 ports. + This reduces the odds that your node will be used for peer-to-peer + applications. + + + + The reduced exit policy is: + + accept *:20-21 + accept *:22 + accept *:23 + accept *:43 + accept *:53 + accept *:79 + accept *:80-81 + accept *:88 + accept *:110 + accept *:143 + accept *:194 + accept *:220 + accept *:389 + accept *:443 + accept *:464 + accept *:465 + accept *:531 + accept *:543-544 + accept *:554 + accept *:563 + accept *:587 + accept *:636 + accept *:706 + accept *:749 + accept *:873 + accept *:902-904 + accept *:981 + accept *:989-990 + accept *:991 + accept *:992 + accept *:993 + accept *:994 + accept *:995 + accept *:1194 + accept *:1220 + accept *:1293 + accept *:1500 + accept *:1533 + accept *:1677 + accept *:1723 + accept *:1755 + accept *:1863 + accept *:2082 + accept *:2083 + accept *:2086-2087 + accept *:2095-2096 + accept *:2102-2104 + accept *:3128 + accept *:3389 + accept *:3690 + accept *:4321 + accept *:4643 + accept *:5050 + accept *:5190 + accept *:5222-5223 + accept *:5228 + accept *:5900 + accept *:6660-6669 + accept *:6679 + accept *:6697 + accept *:8000 + accept *:8008 + accept *:8074 + accept *:8080 + accept *:8082 + accept *:8087-8088 + accept *:8232-8233 + accept *:8332-8333 + accept *:8443 + accept *:8888 + accept *:9418 + accept *:9999 + accept *:10000 + accept *:11371 + accept *:19294 + accept *:19638 + accept *:50002 + accept *:64738 + reject *:* + + (Default: 0) + [[IPv6Exit]] **IPv6Exit** **0**|**1**:: If set, and we are an exit node, allow clients to use us for IPv6 traffic. (Default: 0) @@ -1874,6 +2089,7 @@ is non-zero): If the address is absent, or resolves to both an IPv4 and an IPv6 address, only listen to the IPv6 address. +// Anchor only for formatting, not visible in the man page. [[ORPortFlagsExclusive]]:: For obvious reasons, NoAdvertise and NoListen are mutually exclusive, and IPv4Only and IPv6Only are mutually exclusive. @@ -1923,6 +2139,11 @@ is non-zero): to 0 will disable the heartbeat. Otherwise, it must be at least 30 minutes. (Default: 6 hours) +[[MainloopStats]] **MainloopStats** **0**|**1**:: + Log main loop statistics every **HeartbeatPeriod** seconds. This is a log + level __notice__ message designed to help developers instrumenting Tor's + main event loop. (Default: 0) + [[AccountingMax]] **AccountingMax** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: Limits the max number of bytes sent and received within a set time period using a given calculation rule (see: AccountingStart, AccountingRule). @@ -1953,15 +2174,16 @@ is non-zero): (Default: max) [[AccountingStart]] **AccountingStart** **day**|**week**|**month** [__day__] __HH:MM__:: - Specify how long accounting periods last. If **month** is given, each - accounting period runs from the time __HH:MM__ on the __dayth__ day of one - month to the same day and time of the next. (The day must be between 1 and - 28.) If **week** is given, each accounting period runs from the time __HH:MM__ - of the __dayth__ day of one week to the same day and time of the next week, - with Monday as day 1 and Sunday as day 7. If **day** is given, each - accounting period runs from the time __HH:MM__ each day to the same time on - the next day. All times are local, and given in 24-hour time. (Default: - "month 1 0:00") + Specify how long accounting periods last. If **month** is given, + each accounting period runs from the time __HH:MM__ on the __dayth__ day of one + month to the same day and time of the next. The relay will go at full speed, + use all the quota you specify, then hibernate for the rest of the period. (The + day must be between 1 and 28.) If **week** is given, each accounting period + runs from the time __HH:MM__ of the __dayth__ day of one week to the same day + and time of the next week, with Monday as day 1 and Sunday as day 7. If **day** + is given, each accounting period runs from the time __HH:MM__ each day to the + same time on the next day. All times are local, and given in 24-hour time. + (Default: "month 1 0:00") [[RefuseUnknownExits]] **RefuseUnknownExits** **0**|**1**|**auto**:: Prevent nodes that don't appear in the consensus from exiting using this @@ -2136,6 +2358,17 @@ is non-zero): ed25519 master identity key, as well as the corresponding temporary signing keys and certificates. (Default: 0) +[[KeyDirectory]] **KeyDirectory** __DIR__:: + Store secret keys in DIR. Can not be changed while tor is + running. + (Default: the "keys" subdirectory of DataDirectory.) + +[[KeyDirectoryGroupReadable]] **KeyDirectoryGroupReadable** **0**|**1**:: + If this option is set to 0, don't allow the filesystem group to read the + KeywDirectory. If the option is set to 1, make the KeyDirectory readable + by the default GID. (Default: 0) + + DIRECTORY SERVER OPTIONS ------------------------ @@ -2164,10 +2397,12 @@ details.) some entry in the policy is accepted. [[DirCache]] **DirCache** **0**|**1**:: - When this option is set, Tor caches all current directory documents and - accepts client requests for them. Setting DirPort is not required for this, - because clients connect via the ORPort by default. Setting either DirPort - or BridgeRelay and setting DirCache to 0 is not supported. (Default: 1) + When this option is set, Tor caches all current directory documents except + extra info documents, and accepts client requests for them. If + **DownloadExtraInfo** is set, cached extra info documents are also cached. + Setting **DirPort** is not required for **DirCache**, because clients + connect via the ORPort by default. Setting either DirPort or BridgeRelay + and setting DirCache to 0 is not supported. (Default: 1) [[MaxConsensusAgeForDiffs]] **MaxConsensusAgeForDiffs** __N__ **minutes**|**hours**|**days**|**weeks**:: When this option is nonzero, Tor caches will not try to generate @@ -2180,6 +2415,136 @@ details.) (Default: 0) +DENIAL OF SERVICE MITIGATION OPTIONS +------------------------------------ + +Tor has three built-in mitigation options that can be individually +enabled/disabled and fine-tuned, but by default Tor directory authorities will +define reasonable values for relays and no explicit configuration is required +to make use of these protections. The mitigations take place at relays, +and are as follows: + + 1. If a single client address makes too many concurrent connections (this is + configurable via DoSConnectionMaxConcurrentCount), hang up on further + connections. + + + 2. If a single client IP address (v4 or v6) makes circuits too quickly + (default values are more than 3 per second, with an allowed burst of 90, + see DoSCircuitCreationRate and DoSCircuitCreationBurst) while also having + too many connections open (default is 3, see + DoSCircuitCreationMinConnections), tor will refuse any new circuit (CREATE + cells) for the next while (random value between 1 and 2 hours). + + + 3. If a client asks to establish a rendezvous point to you directly (ex: + Tor2Web client), ignore the request. + +These defenses can be manually controlled by torrc options, but relays will +also take guidance from consensus parameters using these same names, so there's +no need to configure anything manually. In doubt, do not change those values. + +The values set by the consensus, if any, can be found here: +https://consensus-health.torproject.org/#consensusparams + +If any of the DoS mitigations are enabled, a heartbeat message will appear in +your log at NOTICE level which looks like: + + DoS mitigation since startup: 429042 circuits rejected, 17 marked addresses. + 2238 connections closed. 8052 single hop clients refused. + +The following options are useful only for a public relay. They control the +Denial of Service mitigation subsystem described above. + +[[DoSCircuitCreationEnabled]] **DoSCircuitCreationEnabled** **0**|**1**|**auto**:: + + Enable circuit creation DoS mitigation. If set to 1 (enabled), tor will + cache client IPs along with statistics in order to detect circuit DoS + attacks. If an address is positively identified, tor will activate + defenses against the address. See the DoSCircuitCreationDefenseType option + for more details. This is a client to relay detection only. "auto" means + use the consensus parameter. If not defined in the consensus, the value is 0. + (Default: auto) + +[[DoSCircuitCreationMinConnections]] **DoSCircuitCreationMinConnections** __NUM__:: + + Minimum threshold of concurrent connections before a client address can be + flagged as executing a circuit creation DoS. In other words, once a client + address reaches the circuit rate and has a minimum of NUM concurrent + connections, a detection is positive. "0" means use the consensus + parameter. If not defined in the consensus, the value is 3. + (Default: 0) + +[[DoSCircuitCreationRate]] **DoSCircuitCreationRate** __NUM__:: + + The allowed circuit creation rate per second applied per client IP + address. If this option is 0, it obeys a consensus parameter. If not + defined in the consensus, the value is 3. + (Default: 0) + +[[DoSCircuitCreationBurst]] **DoSCircuitCreationBurst** __NUM__:: + + The allowed circuit creation burst per client IP address. If the circuit + rate and the burst are reached, a client is marked as executing a circuit + creation DoS. "0" means use the consensus parameter. If not defined in the + consensus, the value is 90. + (Default: 0) + +[[DoSCircuitCreationDefenseType]] **DoSCircuitCreationDefenseType** __NUM__:: + + This is the type of defense applied to a detected client address. The + possible values are: + + + 1: No defense. + + + 2: Refuse circuit creation for the DoSCircuitCreationDefenseTimePeriod period of time. + + + "0" means use the consensus parameter. If not defined in the consensus, the value is 2. + (Default: 0) + +[[DoSCircuitCreationDefenseTimePeriod]] **DoSCircuitCreationDefenseTimePeriod** __N__ **seconds**|**minutes**|**hours**:: + + The base time period in seconds that the DoS defense is activated for. The + actual value is selected randomly for each activation from N+1 to 3/2 * N. + "0" means use the consensus parameter. If not defined in the consensus, + the value is 3600 seconds (1 hour). + (Default: 0) + +[[DoSConnectionEnabled]] **DoSConnectionEnabled** **0**|**1**|**auto**:: + + Enable the connection DoS mitigation. If set to 1 (enabled), for client + address only, this allows tor to mitigate against large number of + concurrent connections made by a single IP address. "auto" means use the + consensus parameter. If not defined in the consensus, the value is 0. + (Default: auto) + +[[DoSConnectionMaxConcurrentCount]] **DoSConnectionMaxConcurrentCount** __NUM__:: + + The maximum threshold of concurrent connection from a client IP address. + Above this limit, a defense selected by DoSConnectionDefenseType is + applied. "0" means use the consensus parameter. If not defined in the + consensus, the value is 100. + (Default: 0) + +[[DoSConnectionDefenseType]] **DoSConnectionDefenseType** __NUM__:: + + This is the type of defense applied to a detected client address for the + connection mitigation. The possible values are: + + + 1: No defense. + + + 2: Immediately close new connections. + + + "0" means use the consensus parameter. If not defined in the consensus, the value is 2. + (Default: 0) + +[[DoSRefuseSingleHopClientRendezvous]] **DoSRefuseSingleHopClientRendezvous** **0**|**1**|**auto**:: + + Refuse establishment of rendezvous points for single hop clients. In other + words, if a client directly connects to the relay and sends an + ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto" means use the + consensus parameter. If not defined in the consensus, the value is 0. + (Default: auto) + + DIRECTORY AUTHORITY SERVER OPTIONS ---------------------------------- @@ -2379,9 +2744,29 @@ on the public Tor network. [[AuthDirHasIPv6Connectivity]] **AuthDirHasIPv6Connectivity** **0**|**1**:: Authoritative directories only. When set to 0, OR ports with an - IPv6 address are being accepted without reachability testing. - When set to 1, IPv6 OR ports are being tested just like IPv4 OR - ports. (Default: 0) + IPv6 address are not included in the authority's votes. When set to 1, + IPv6 OR ports are tested for reachability like IPv4 OR ports. If the + reachability test succeeds, the authority votes for the IPv6 ORPort, and + votes Running for the relay. If the reachability test fails, the authority + does not vote for the IPv6 ORPort, and does not vote Running (Default: 0) + ++ + The content of the consensus depends on the number of voting authorities + that set AuthDirHasIPv6Connectivity: + + If no authorities set AuthDirHasIPv6Connectivity 1, there will be no + IPv6 ORPorts in the consensus. + + If a minority of authorities set AuthDirHasIPv6Connectivity 1, + unreachable IPv6 ORPorts will be removed from the consensus. But the + majority of IPv4-only authorities will still vote the relay as Running. + Reachable IPv6 ORPort lines will be included in the consensus + + If a majority of voting authorities set AuthDirHasIPv6Connectivity 1, + relays with unreachable IPv6 ORPorts will not be listed as Running. + Reachable IPv6 ORPort lines will be included in the consensus + (To ensure that any valid majority will vote relays with unreachable + IPv6 ORPorts not Running, 75% of authorities must set + AuthDirHasIPv6Connectivity 1.) [[MinMeasuredBWsForAuthToIgnoreAdvertised]] **MinMeasuredBWsForAuthToIgnoreAdvertised** __N__:: A total value, in abstract bandwidth units, describing how much @@ -2422,7 +2807,7 @@ The following options are used to configure a hidden service. you're using a Tor controller that handles hidserv publishing for you. (Default: 1) -[[HiddenServiceVersion]] **HiddenServiceVersion** __version__,__version__,__...__:: +[[HiddenServiceVersion]] **HiddenServiceVersion** **2**|**3**:: A list of rendezvous service descriptor versions to publish for the hidden service. Currently, versions 2 and 3 are supported. (Default: 2) @@ -2436,7 +2821,8 @@ The following options are used to configure a hidden service. spaces). If this option is set, the hidden service is not accessible for clients without authorization any more. Generated authorization data can be found in the hostname file. Clients need to put this authorization data in - their configuration file using **HidServAuth**. + their configuration file using **HidServAuth**. This option is only for v2 + services. [[HiddenServiceAllowUnknownPorts]] **HiddenServiceAllowUnknownPorts** **0**|**1**:: If set to 1, then connections to unrecognized ports do not cause the @@ -2447,7 +2833,7 @@ The following options are used to configure a hidden service. [[HiddenServiceMaxStreams]] **HiddenServiceMaxStreams** __N__:: The maximum number of simultaneous streams (connections) per rendezvous circuit. The maximum value allowed is 65535. (Setting this to 0 will allow - an unlimited number of simultanous streams.) (Default: 0) + an unlimited number of simultaneous streams.) (Default: 0) [[HiddenServiceMaxStreamsCloseCircuit]] **HiddenServiceMaxStreamsCloseCircuit** **0**|**1**:: If set to 1, then exceeding **HiddenServiceMaxStreams** will cause the @@ -2458,7 +2844,8 @@ The following options are used to configure a hidden service. Every time the specified period elapses, Tor uploads any rendezvous service descriptors to the directory servers. This information is also uploaded whenever it changes. Minimum value allowed is 10 minutes and - maximum is 3.5 days. (Default: 1 hour) + maximum is 3.5 days. This option is only for v2 services. + (Default: 1 hour) [[HiddenServiceDirGroupReadable]] **HiddenServiceDirGroupReadable** **0**|**1**:: If this option is set to 1, allow the filesystem group to read the @@ -2504,101 +2891,6 @@ The following options are used to configure a hidden service. including setting SOCKSPort to "0". Can not be changed while tor is running. (Default: 0) -DENIAL OF SERVICE MITIGATION OPTIONS ------------------------------------- - -The following options are useful only for a public relay. They control the -Denial of Service mitigation subsystem. - -[[DoSCircuitCreationEnabled]] **DoSCircuitCreationEnabled** **0**|**1**|**auto**:: - - Enable circuit creation DoS mitigation. If enabled, tor will cache client - IPs along with statistics in order to detect circuit DoS attacks. If an - address is positively identified, tor will activate defenses against the - address. See the DoSCircuitCreationDefenseType option for more details. - This is a client to relay detection only. "auto" means use the consensus - parameter. If not defined in the consensus, the value is 0. - (Default: auto) - -[[DoSCircuitCreationMinConnections]] **DoSCircuitCreationMinConnections** __NUM__:: - - Minimum threshold of concurrent connections before a client address can be - flagged as executing a circuit creation DoS. In other words, once a client - address reaches the circuit rate and has a minimum of NUM concurrent - connections, a detection is positive. "0" means use the consensus - parameter. If not defined in the consensus, the value is 3. - (Default: 0) - -[[DoSCircuitCreationRate]] **DoSCircuitCreationRate** __NUM__:: - - The allowed circuit creation rate per second applied per client IP - address. If this option is 0, it obeys a consensus parameter. If not - defined in the consensus, the value is 3. - (Default: 0) - -[[DoSCircuitCreationBurst]] **DoSCircuitCreationBurst** __NUM__:: - - The allowed circuit creation burst per client IP address. If the circuit - rate and the burst are reached, a client is marked as executing a circuit - creation DoS. "0" means use the consensus parameter. If not defined in the - consensus, the value is 90. - (Default: 0) - -[[DoSCircuitCreationDefenseType]] **DoSCircuitCreationDefenseType** __NUM__:: - - This is the type of defense applied to a detected client address. The - possible values are: - - 1: No defense. - 2: Refuse circuit creation for the DoSCircuitCreationDefenseTimePeriod period of time. -+ - "0" means use the consensus parameter. If not defined in the consensus, - the value is 2. - (Default: 0) - -[[DoSCircuitCreationDefenseTimePeriod]] **DoSCircuitCreationDefenseTimePeriod** __N__ **seconds**|**minutes**|**hours**:: - - The base time period in seconds that the DoS defense is activated for. The - actual value is selected randomly for each activation from N+1 to 3/2 * N. - "0" means use the consensus parameter. If not defined in the consensus, - the value is 3600 seconds (1 hour). (Default: 0) - -[[DoSConnectionEnabled]] **DoSConnectionEnabled** **0**|**1**|**auto**:: - - Enable the connection DoS mitigation. For client address only, this allows - tor to mitigate against large number of concurrent connections made by a - single IP address. "auto" means use the consensus parameter. If not - defined in the consensus, the value is 0. - (Default: auto) - -[[DoSConnectionMaxConcurrentCount]] **DoSConnectionMaxConcurrentCount** __NUM__:: - - The maximum threshold of concurrent connection from a client IP address. - Above this limit, a defense selected by DoSConnectionDefenseType is - applied. "0" means use the consensus parameter. If not defined in the - consensus, the value is 100. - (Default: 0) - -[[DoSConnectionDefenseType]] **DoSConnectionDefenseType** __NUM__:: - - This is the type of defense applied to a detected client address for the - connection mitigation. The possible values are: - - 1: No defense. - 2: Immediately close new connections. -+ - "0" means use the consensus parameter. If not defined in the consensus, - the value is 2. - (Default: 0) - -[[DoSRefuseSingleHopClientRendezvous]] **DoSRefuseSingleHopClientRendezvous** **0**|**1**|**auto**:: - - Refuse establishment of rendezvous points for single hop clients. In other - words, if a client directly connects to the relay and sends an - ESTABLISH_RENDEZVOUS cell, it is silently dropped. "auto" means use the - consensus parameter. If not defined in the consensus, the value is 0. - (Default: auto) - TESTING NETWORK OPTIONS ----------------------- @@ -2623,8 +2915,6 @@ The following options are used for running a testing Tor network. 4 (for 40 seconds), 8, 16, 32, 60 ClientBootstrapConsensusAuthorityOnlyDownloadSchedule 0, 1, 4 (for 40 seconds), 8, 16, 32, 60 - ClientBootstrapConsensusMaxDownloadTries 80 - ClientBootstrapConsensusAuthorityOnlyMaxDownloadTries 80 ClientDNSRejectInternalAddresses 0 ClientRejectInternalAddresses 0 CountPrivateBandwidth 1 @@ -2647,10 +2937,6 @@ The following options are used for running a testing Tor network. TestingBridgeBootstrapDownloadSchedule 0, 0, 5, 10, 15, 20, 30, 60 TestingClientMaxIntervalWithoutRequest 5 seconds TestingDirConnectionMaxStall 30 seconds - TestingConsensusMaxDownloadTries 80 - TestingDescriptorMaxDownloadTries 80 - TestingMicrodescMaxDownloadTries 80 - TestingCertMaxDownloadTries 80 TestingEnableConnBwEvent 1 TestingEnableCellStatsEvent 1 TestingEnableTbEmptyEvent 1 @@ -2731,22 +3017,6 @@ The following options are used for running a testing Tor network. Changing this requires that **TestingTorNetwork** is set. (Default: 5 minutes) -[[TestingConsensusMaxDownloadTries]] **TestingConsensusMaxDownloadTries** __NUM__:: - Try this many times to download a consensus before giving up. Changing - this requires that **TestingTorNetwork** is set. (Default: 8) - -[[TestingDescriptorMaxDownloadTries]] **TestingDescriptorMaxDownloadTries** __NUM__:: - Try this often to download a server descriptor before giving up. - Changing this requires that **TestingTorNetwork** is set. (Default: 8) - -[[TestingMicrodescMaxDownloadTries]] **TestingMicrodescMaxDownloadTries** __NUM__:: - Try this often to download a microdesc descriptor before giving up. - Changing this requires that **TestingTorNetwork** is set. (Default: 8) - -[[TestingCertMaxDownloadTries]] **TestingCertMaxDownloadTries** __NUM__:: - Try this often to download a v3 authority certificate before giving up. - Changing this requires that **TestingTorNetwork** is set. (Default: 8) - [[TestingDirAuthVoteExit]] **TestingDirAuthVoteExit** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address patterns of nodes to vote Exit for regardless of their @@ -2895,40 +3165,35 @@ FILES **@LOCALSTATEDIR@/lib/tor/**:: The tor process stores keys and other data here. -__DataDirectory__**/cached-status/**:: - The most recently downloaded network status document for each authority. - Each file holds one such document; the filenames are the hexadecimal - identity key fingerprints of the directory authorities. Obsolete; - no longer in use. -__DataDirectory__**/cached-certs**:: +__CacheDirectory__**/cached-certs**:: This file holds downloaded directory key certificates that are used to verify authenticity of documents generated by Tor directory authorities. -__DataDirectory__**/cached-consensus** and/or **cached-microdesc-consensus**:: +__CacheDirectory__**/cached-consensus** and/or **cached-microdesc-consensus**:: The most recent consensus network status document we've downloaded. -__DataDirectory__**/cached-descriptors** and **cached-descriptors.new**:: +__CacheDirectory__**/cached-descriptors** and **cached-descriptors.new**:: These files hold downloaded router statuses. Some routers may appear more than once; if so, the most recently published descriptor is used. Lines beginning with @-signs are annotations that contain more information about a given router. The ".new" file is an append-only journal; when it gets too large, all entries are merged into a new cached-descriptors file. -__DataDirectory__**/cached-extrainfo** and **cached-extrainfo.new**:: +__CacheDirectory__**/cached-extrainfo** and **cached-extrainfo.new**:: As "cached-descriptors", but holds optionally-downloaded "extra-info" documents. Relays use these documents to send inessential information about statistics, bandwidth history, and network health to the authorities. They aren't fetched by default; see the DownloadExtraInfo option for more info. -__DataDirectory__**/cached-microdescs** and **cached-microdescs.new**:: +__CacheDirectory__**/cached-microdescs** and **cached-microdescs.new**:: These files hold downloaded microdescriptors. Lines beginning with @-signs are annotations that contain more information about a given router. The ".new" file is an append-only journal; when it gets too large, all entries are merged into a new cached-microdescs file. -__DataDirectory__**/cached-routers** and **cached-routers.new**:: +__CacheDirectory__**/cached-routers** and **cached-routers.new**:: Obsolete versions of cached-descriptors and cached-descriptors.new. When Tor can't find the newer files, it looks here instead. @@ -2946,11 +3211,11 @@ __DataDirectory__**/sr-state**:: Authority only. State file used to record information about the current status of the shared-random-value voting state. -__DataDirectory__**/diff-cache**:: +__CacheDirectory__**/diff-cache**:: Directory cache only. Holds older consensuses, and diffs from older consensuses to the most recent consensus of each type, compressed in various ways. Each file contains a set of key-value arguments - decribing its contents, followed by a single NUL byte, followed by the + describing its contents, followed by a single NUL byte, followed by the main file contents. __DataDirectory__**/bw_accounting**:: @@ -2976,63 +3241,60 @@ __DataDirectory__**/key-pinning-journal**:: or factoring the RSA1024 key will no longer let an attacker impersonate the relay. -__DataDirectory__**/keys/***:: - Only used by servers. Holds identity keys and onion keys. - -__DataDirectory__**/keys/authority_identity_key**:: +__KeyDirectory__**/authority_identity_key**:: A v3 directory authority's master identity key, used to authenticate its signing key. Tor doesn't use this while it's running. The tor-gencert program uses this. If you're running an authority, you should keep this key offline, and not actually put it here. -__DataDirectory__**/keys/authority_certificate**:: +__KeyDirectory__**/authority_certificate**:: A v3 directory authority's certificate, which authenticates the authority's current vote- and consensus-signing key using its master identity key. Only directory authorities use this file. -__DataDirectory__**/keys/authority_signing_key**:: +__KeyDirectory__**/authority_signing_key**:: A v3 directory authority's signing key, used to sign votes and consensuses. Only directory authorities use this file. Corresponds to the **authority_certificate** cert. -__DataDirectory__**/keys/legacy_certificate**:: +__KeyDirectory__**/legacy_certificate**:: As authority_certificate: used only when V3AuthUseLegacyKey is set. See documentation for V3AuthUseLegacyKey. -__DataDirectory__**/keys/legacy_signing_key**:: +__KeyDirectory__**/legacy_signing_key**:: As authority_signing_key: used only when V3AuthUseLegacyKey is set. See documentation for V3AuthUseLegacyKey. -__DataDirectory__**/keys/secret_id_key**:: +__KeyDirectory__**/secret_id_key**:: A relay's RSA1024 permanent identity key, including private and public components. Used to sign router descriptors, and to sign other keys. -__DataDirectory__**/keys/ed25519_master_id_public_key**:: +__KeyDirectory__**/ed25519_master_id_public_key**:: The public part of a relay's Ed25519 permanent identity key. -__DataDirectory__**/keys/ed25519_master_id_secret_key**:: +__KeyDirectory__**/ed25519_master_id_secret_key**:: The private part of a relay's Ed25519 permanent identity key. This key is used to sign the medium-term ed25519 signing key. This file can be kept offline, or kept encrypted. If so, Tor will not be able to generate new signing keys itself; you'll need to use tor --keygen yourself to do so. -__DataDirectory__**/keys/ed25519_signing_secret_key**:: +__KeyDirectory__**/ed25519_signing_secret_key**:: The private and public components of a relay's medium-term Ed25519 signing key. This key is authenticated by the Ed25519 master key, in turn authenticates other keys (and router descriptors). -__DataDirectory__**/keys/ed25519_signing_cert**:: +__KeyDirectory__**/ed25519_signing_cert**:: The certificate which authenticates "ed25519_signing_secret_key" as having been signed by the Ed25519 master key. -__DataDirectory__**/keys/secret_onion_key** and **secret_onion_key.old**:: +__KeyDirectory__**/secret_onion_key** and **secret_onion_key.old**:: A relay's RSA1024 short-term onion key. Used to decrypt old-style ("TAP") circuit extension requests. The ".old" file holds the previously generated key, which the relay uses to handle any requests that were made by clients that didn't have the new one. -__DataDirectory__**/keys/secret_onion_key_ntor** and **secret_onion_key_ntor.old**:: +__KeyDirectory__**/secret_onion_key_ntor** and **secret_onion_key_ntor.old**:: A relay's Curve25519 short-term onion key. Used to handle modern ("ntor") circuit extension requests. The ".old" file holds the previously generated key, which the relay uses to handle any requests that were @@ -3059,11 +3321,11 @@ __DataDirectory__**/v3-status-votes**:: Only for v3 authoritative directory servers. This file contains status votes from all the authoritative directory servers. -__DataDirectory__**/unverified-consensus**:: +__CacheDirectory__**/unverified-consensus**:: This file contains a network consensus document that has been downloaded, but which we didn't have the right certificates to check yet. -__DataDirectory__**/unverified-microdesc-consensus**:: +__CacheDirectory__**/unverified-microdesc-consensus**:: This file contains a microdescriptor-flavored network consensus document that has been downloaded, but which we didn't have the right certificates to check yet. |