diff options
Diffstat (limited to 'doc/man/tor.1.txt')
| -rw-r--r-- | doc/man/tor.1.txt | 180 |
1 files changed, 125 insertions, 55 deletions
diff --git a/doc/man/tor.1.txt b/doc/man/tor.1.txt index 0af9a9c03d..1814801b71 100644 --- a/doc/man/tor.1.txt +++ b/doc/man/tor.1.txt @@ -71,7 +71,7 @@ The following options in this section are only recognized on the Specify a new configuration file to contain further Tor configuration options, or pass *-* to make Tor read its configuration from standard input. (Default: **`@CONFDIR@/torrc`**, or **`$HOME/.torrc`** if - that file is not found) + that file is not found.) [[opt-allow-missing-torrc]] **`--allow-missing-torrc`**:: Allow the configuration file specified by **`-f`** to be missing, @@ -101,7 +101,7 @@ The following options in this section are only recognized on the [[opt-dump-config]] **`--dump-config`** **`short`**|**`full`**:: Write a list of Tor's configured options to standard output. When the `short` flag is selected, only write the options that - are different from their default values + are different from their default values. When `full` is selected, write every option. [[opt-serviceinstall]] **`--service install`** [**`--options`** __command-line options__]:: @@ -988,20 +988,20 @@ forward slash (/) in the configuration file and on the command line. running. (Default: none) [[TCPProxy]] **TCPProxy** __protocol__ __host__:__port__:: - Tor will use the given protocol to make all its OR (SSL) connections through - a TCP proxy on host:port, rather than connecting directly to servers. You may - want to set **FascistFirewall** to restrict the set of ports you might try to - connect to, if your proxy only allows connecting to certain ports. There is no - equivalent option for directory connections, because all Tor client versions - that support this option download directory documents via OR connections. + + Tor will use the given protocol to make all its OR (SSL) connections through + a TCP proxy on host:port, rather than connecting directly to servers. You may + want to set **FascistFirewall** to restrict the set of ports you might try to + connect to, if your proxy only allows connecting to certain ports. There is no + equivalent option for directory connections, because all Tor client versions + that support this option download directory documents via OR connections. + + - The only protocol supported right now 'haproxy'. This option is only for - clients. (Default: none) + + The only protocol supported right now 'haproxy'. This option is only for + clients. (Default: none) + + - The HAProxy version 1 proxy protocol is described in detail at - https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt + + The HAProxy version 1 proxy protocol is described in detail at + https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt + + - Both source IP address and source port will be set to zero. + Both source IP address and source port will be set to zero. [[TruncateLogFile]] **TruncateLogFile** **0**|**1**:: If 1, Tor will overwrite logs at startup and in response to a HUP signal, @@ -1749,6 +1749,13 @@ The following options are useful only for clients (that is, if the guard-n-primary-guards consensus parameter, and default to 3 if the consensus parameter isn't set. (Default: 0) +[[VanguardsLiteEnabled]] **VanguardsLiteEnabled** **0**|**1**|**auto**:: + This option specifies whether clients should use the vanguards-lite + subsystem to protect against guard discovery attacks. If it's set to + 'auto', clients will do what the vanguards-lite-enabled consensus parameter + tells them to do, and will default to enable the subsystem if the consensus + parameter isn't set. (Default: auto) + [[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 @@ -2847,11 +2854,15 @@ details.) == 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: +Tor has a series of built-in denial of service mitigation options that can be +individually enabled/disabled and fine-tuned, but by default Tor directory +authorities will define reasonable values for the network and no explicit +configuration is required to make use of these protections. + +The following is a series of configuration options for relays and then options +for onion services and how they work. + +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 @@ -3002,6 +3013,68 @@ Denial of Service mitigation subsystem described above. (Default: auto) +As for onion services, only one possible mitigation exists. It was intended to +protect the network first and thus do not help the service availability or +reachability. + +The mitigation we put in place is a rate limit of the amount of introduction +that happens at the introduction point for a service. In other words, it rates +limit the number of clients that are attempting to reach the service at the +introduction point instead of at the service itself. + +The following options are per onion service: + +[[HiddenServiceEnableIntroDoSDefense]] **HiddenServiceEnableIntroDoSDefense** **0**|**1**:: + Enable DoS defense at the intropoint level. When this is enabled, the + rate and burst parameter (see below) will be sent to the intro point which + will then use them to apply rate limiting for introduction request to this + service. + + + The introduction point honors the consensus parameters except if this is + specifically set by the service operator using this option. The service + never looks at the consensus parameters in order to enable or disable this + defense. (Default: 0) + +//Out of order because it logically belongs after HiddenServiceEnableIntroDoSDefense. +[[HiddenServiceEnableIntroDoSBurstPerSec]] **HiddenServiceEnableIntroDoSBurstPerSec** __NUM__:: + The allowed client introduction burst per second at the introduction + point. If this option is 0, it is considered infinite and thus if + **HiddenServiceEnableIntroDoSDefense** is set, it then effectively + disables the defenses. (Default: 200) + +[[HiddenServiceEnableIntroDoSRatePerSec]] **HiddenServiceEnableIntroDoSRatePerSec** __NUM__:: + The allowed client introduction rate per second at the introduction + point. If this option is 0, it is considered infinite and thus if + **HiddenServiceEnableIntroDoSDefense** is set, it then effectively + disables the defenses. (Default: 25) + +The rate is the maximum number of clients a service will ask its introduction +points to allow every seconds. And the burst is a parameter that allows that +many within one second. + +For example, the default values of 25 and 200 respectively means that for every +introduction points a service has (default 3 but can be configured with +**HiddenServiceNumIntroductionPoints**), 25 clients per seconds will be allowed +to reach the service and 200 at most within 1 second as a burst. This means +that if 200 clients are seen within 1 second, it will take 8 seconds (200/25) +for another client to be able to be allowed to introduce due to the rate of 25 +per second. + +This might be too much for your use case or not, fine tuning these values is +hard and are likely different for each service operator. + +Why is this not helping reachability of the service? Because the defenses are +at the introduction point, an attacker can easily flood all introduction point +rendering the service unavailable due to no client being able to pass through. +But, the service itself is not overwhelmed with connetions allowing it to +function properly for the few clients that were able to go through or other any +services running on the same tor instance. + +The bottom line is that this protects the network by preventing an onion +service to flood the network with new rendezvous circuits that is reducing load +on the network. + + == DIRECTORY AUTHORITY SERVER OPTIONS The following options enable operation as a directory authority, and @@ -3039,6 +3112,11 @@ on the public Tor network. is the same as for exit policies, except that you don't need to say "accept" or "reject", and ports are not needed.) +[[AuthDirMiddleOnly]] **AuthMiddleOnly** __AddressPattern...__:: + Authoritative directories only. A set of address patterns for servers that + will be listed as middle-only in any network status document this authority + publishes, if **AuthDirListMiddleOnly** is set. + + [[AuthDirFastGuarantee]] **AuthDirFastGuarantee** __N__ **bytes**|**KBytes**|**MBytes**|**GBytes**|**TBytes**|**KBits**|**MBits**|**GBits**|**TBits**:: Authoritative directories only. If non-zero, always vote the Fast flag for any relay advertising this amount of capacity or @@ -3086,6 +3164,13 @@ on the public Tor network. 1 unless you plan to list non-functioning exits as bad; otherwise, you are effectively voting in favor of every declared exit as an exit.) +[[AuthDirListMiddleOnly]] **AuthDirListMiddleOnly** **0**|**1**:: + Authoritative directories only. If set to 1, this directory has some + opinion about which nodes should only be used in the middle position. + (Do not set this to 1 unless you plan to list questionable relays + as "middle only"; otherwise, you are effectively voting _against_ + middle-only status for every relay.) + [[AuthDirMaxServersPerAddr]] **AuthDirMaxServersPerAddr** __NUM__:: Authoritative directories only. The maximum number of servers that we will list as acceptable on a single IP address. Set this to "0" for "no limit". @@ -3104,18 +3189,20 @@ on the public Tor network. authority publishes, or accepted as an OR address in any descriptor submitted for publication by this authority. +[[AuthDirRejectRequestsUnderLoad]] **AuthDirRejectRequestsUnderLoad** **0**|**1**:: + If set, the directory authority will start rejecting directory requests + from non relay connections by sending a 503 error code if it is under + bandwidth pressure (reaching the configured limit if any). Relays will + always tried to be answered even if this is on. (Default: 1) + //Out of order because it logically belongs with the other CCs options. [[AuthDirBadExitCCs]] **AuthDirBadExitCCs** __CC__,... + //Out of order because it logically belongs with the other CCs options. [[AuthDirInvalidCCs]] **AuthDirInvalidCCs** __CC__,... + - -[[AuthDirRejectRequestsUnderLoad]] **AuthDirRejectRequestsUnderLoad** **0**|**1**:: - If set, the directory authority will start rejecting directory requests - from non relay connections by sending a 503 error code if it is under - bandwidth pressure (reaching the configured limit if any). Relays will - always tried to be answered even if this is on. (Default: 1) +//Out of order because it logically belongs with the other CCs options. +[[AuthDirMiddleOnlytCCs]] **AuthDirMiddleOnlyCCs** __CC__,... + [[AuthDirRejectCCs]] **AuthDirRejectCCs** __CC__,...:: Authoritative directories only. These options contain a comma-separated @@ -3280,30 +3367,6 @@ The next section describes the per service options that can only be set only owner is able to read the hidden service directory. (Default: 0) Has no effect on Windows. -[[HiddenServiceEnableIntroDoSDefense]] **HiddenServiceEnableIntroDoSDefense** **0**|**1**:: - Enable DoS defense at the intropoint level. When this is enabled, the - rate and burst parameter (see below) will be sent to the intro point which - will then use them to apply rate limiting for introduction request to this - service. - + - The introduction point honors the consensus parameters except if this is - specifically set by the service operator using this option. The service - never looks at the consensus parameters in order to enable or disable this - defense. (Default: 0) - -//Out of order because it logically belongs after HiddenServiceEnableIntroDoSDefense. -[[HiddenServiceEnableIntroDoSBurstPerSec]] **HiddenServiceEnableIntroDoSBurstPerSec** __NUM__:: - The allowed client introduction burst per second at the introduction - point. If this option is 0, it is considered infinite and thus if - **HiddenServiceEnableIntroDoSDefense** is set, it then effectively - disables the defenses. (Default: 200) - -[[HiddenServiceEnableIntroDoSRatePerSec]] **HiddenServiceEnableIntroDoSRatePerSec** __NUM__:: - The allowed client introduction rate per second at the introduction - point. If this option is 0, it is considered infinite and thus if - **HiddenServiceEnableIntroDoSDefense** is set, it then effectively - disables the defenses. (Default: 25) - [[HiddenServiceExportCircuitID]] **HiddenServiceExportCircuitID** __protocol__:: The onion service will use the given protocol to expose the global circuit identifier of each inbound client circuit. The only @@ -3514,14 +3577,15 @@ The following options are used for running a testing Tor network. [[TestingAuthKeySlop]] **TestingAuthKeySlop** __N__ **seconds**|**minutes**|**hours** + [[TestingBridgeBootstrapDownloadInitialDelay]] **TestingBridgeBootstrapDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download each bridge descriptor when they - have just started, or when they can not contact any of their bridges. + Initial delay in seconds for how long clients should wait before + downloading a bridge descriptor for a new bridge. Changing this requires that **TestingTorNetwork** is set. (Default: 0) [[TestingBridgeDownloadInitialDelay]] **TestingBridgeDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download each bridge descriptor when they - know that one or more of their configured bridges are running. Changing - this requires that **TestingTorNetwork** is set. (Default: 10800) + How long to wait (in seconds) once clients have successfully + downloaded a bridge descriptor, before trying another download for + that same bridge. Changing this requires that **TestingTorNetwork** + is set. (Default: 10800) [[TestingClientConsensusDownloadInitialDelay]] **TestingClientConsensusDownloadInitialDelay** __N__:: Initial delay in seconds for when clients should download consensuses. Changing this @@ -3840,7 +3904,12 @@ __KeyDirectory__/**`secret_onion_key_ntor`** and **`secret_onion_key_ntor.old`** by clients that didn't have the new one. __DataDirectory__/**`fingerprint`**:: - Only used by servers. Contains the fingerprint of the server's identity key. + Only used by servers. Contains the fingerprint of the server's RSA + identity key. + +__DataDirectory__/**`fingerprint-ed25519`**:: + Only used by servers. Contains the fingerprint of the server's ed25519 + identity key. __DataDirectory__/**`hashed-fingerprint`**:: Only used by bridges. Contains the hashed fingerprint of the bridge's @@ -3856,7 +3925,8 @@ __DataDirectory__/**`approved-routers`**:: descriptors are accepted, but marked in the vote as not valid. If it is **!badexit**, then the authority will vote for it to receive a BadExit flag, indicating that it shouldn't be used for traffic leaving - the Tor network. + the Tor network. If it is **!middleonly**, then the authority will + vote for it to only be used in the middle of circuits. (Neither rejected nor invalid relays are included in the consensus.) __DataDirectory__/**`v3-status-votes`**:: |