[tor-commits] [tor/master] doc: Improve DoS section of the man page tor.1

[nickm at torproject.org]

commit 119b053a8ad9cf8139a159cda30e04d2a3887914
Author: David Goulet <dgoulet at torproject.org>
Date:   Wed Apr 4 10:22:13 2018 -0400

    doc: Improve DoS section of the man page tor.1
    
    Add to the Denial of Service section of the man page an explanation about the
    three different mitigation Tor has.
    
    Fixes #25248.
    
    Signed-off-by: David Goulet <dgoulet at torproject.org>
---
 changes/ticket25248 |  4 ++++
 doc/tor.1.txt       | 57 ++++++++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 49 insertions(+), 12 deletions(-)

diff --git a/changes/ticket25248 b/changes/ticket25248
new file mode 100644
index 000000000..67ccdb631
--- /dev/null
+++ b/changes/ticket25248
@@ -0,0 +1,4 @@
+  o Documentation (manpage, denial of service):
+    - Better detail the denial of service options by listing the different
+      mitigation in place. Closes ticket 25248.
+
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 9aad3af98..8bb27fa5a 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -2755,17 +2755,49 @@ The following options are used to configure a hidden service.
 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 are:
+
+  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, 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, an 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.
+Denial of Service mitigation subsystem described above.
 
 [[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.
+    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__::
@@ -2809,14 +2841,15 @@ Denial of Service mitigation subsystem.
     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)
+    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.
+    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__::