DoS mitgation: improve documentation
(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 legacy/trac#25236 (moved)
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.
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" -> legacy/trac#25236 (moved)
will these values show on https://consensus-health.torprojec.org?