[tor-bugs] #25248 [Core Tor/Tor]: DoS mitgation: improve documentation

[Tor Bug Tracker & Wiki]

#25248: DoS mitgation: improve documentation
------------------------------+---------------------------------------
     Reporter:  cypherpunks   |      Owner:  (none)
         Type:  enhancement   |     Status:  new
     Priority:  Medium        |  Milestone:
    Component:  Core Tor/Tor  |    Version:
     Severity:  Normal        |   Keywords:  tor-dos, manpage, tor-doc
Actual Points:                |  Parent ID:
       Points:                |   Reviewer:
      Sponsor:                |
------------------------------+---------------------------------------
 (some reason for opening this is: a relay operator seemed confused and
 started to modify the source instead of using these torrc settings)
 https://lists.torproject.org/pipermail/tor-
 relays/2018-February/014503.html

 building on top of #25236

 Lets add a high level overview of available DoS mitigations at the
 beginning of the section next to "The following options are useful only
 for a public relay. They control the Denial of Service mitigation
 subsystem."
 as you did in the changelog already before going into the specific
 settings.

 We could start by using a copy from your changelog:
 https://gitweb.torproject.org/tor.git/tree/ChangeLog?h=tor-0.3.3.2-alpha#n8

 something like:
 "
 Tor has 3 build-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:
  * First: if a single client address makes too many concurrent connections
 (~~>100~~ "too many" is configurable via XXX), hang up on further
 connections.
  * Second: if a
       single client IP address (v4 and v6 or does it just work with IPv4?)
 makes circuits too quickly (more than 3 per
       second, with an allowed burst of 90) while also having too many
       connections open (3), refuse new create cells for the next while
       (1-2 hours).
  * Third: if a client asks to establish a rendezvous
       point to you directly, ignore the request. These defenses can be
       manually controlled by new torrc options, but relays will also
       take guidance from consensus parameters, so there's no need to
       configure anything manually.
 "
 instead of the static values add the config options in brackets.


 https://www.torproject.org/docs/tor-manual-
 dev.html.en#DoSCircuitCreationEnabled

 Does not say what 0 and 1 means. Maybe use the same wording as you use for
 most other boolean settings:
 "If this option is set to 1, ...


 * The section "DENIAL OF SERVICE MITIGATION OPTIONS" refers to the
 consensus
 for default values, lets tell the operator how to find the current
 consensus values so he has actually some information where they can say
 "that value is to low for me my system is idle" or "oh that is not defined
 in consensus" -> #25236

 will these values show on https://consensus-health.torprojec.org?

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/25248>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online