commit 119b053a8ad9cf8139a159cda30e04d2a3887914 Author: David Goulet dgoulet@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@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__::