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

@@ -2833,11 +2833,15 @@ details.)
 
 == DENIAL OF SERVICE MITIGATION OPTIONS
 
-Tor has three built-in mitigation options that can be individually
+Tor has a series of built-in denial of service mitigation options that can be
-enabled/disabled and fine-tuned, but by default Tor directory authorities will
+individually enabled/disabled and fine-tuned, but by default Tor directory
-define reasonable values for relays and no explicit configuration is required
+authorities will define reasonable values for the network and no explicit
-to make use of these protections. The mitigations take place at relays,
+configuration is required to make use of these protections.
-and are as follows:
+
+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