commit 86f880d756013e0f4455ffcf27b938d945f72535 Author: David Goulet dgoulet@torproject.org Date: Thu Sep 9 14:30:52 2021 -0400
man: Detail onion service DDoS mitigation measure
Move the options into the DDoS section with a series of explanations.
Closes #40456
Signed-off-by: David Goulet dgoulet@torproject.org --- doc/man/tor.1.txt | 100 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 71 insertions(+), 29 deletions(-)
diff --git a/doc/man/tor.1.txt b/doc/man/tor.1.txt index 2b5a1d9df7..88160dec64 100644 --- a/doc/man/tor.1.txt +++ b/doc/man/tor.1.txt @@ -2833,11 +2833,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 @@ -2988,6 +2992,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 @@ -3266,30 +3332,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