Add note about "total-quota" parameter

Signed-off-by: Daniel Calviño Sánchez <danxuliu@gmail.com>

1 files changed, 9 insertions, 1 deletions

diff --git a/docs/TURN.md b/docs/TURN.md
index 761e22719..b0a04f1fb 100644
--- a/docs/TURN.md
+++ b/docs/TURN.md
@@ -60,7 +60,7 @@ lt-cred-mech # Only on coTURN below v4.5.0.8!
 use-auth-secret
 static-auth-secret=<yourChosen/GeneratedSecret>
 realm=your.domain.org
-total-quota=100
+total-quota=0
 bps-capacity=0
 stale-nonce
 no-loopback-peers # Only on coTURN below v4.5.1.0!
@@ -74,6 +74,14 @@ no-multicast-peers
     - [https://github.com/coturn/coturn/issues/33](https://github.com/coturn/coturn/issues/33)
     - [https://github.com/nextcloud/spreed/issues/257](https://github.com/nextcloud/spreed/issues/257)
 
+- The `total-quota` parameter limits the number of allowed simultaneous connections to the TURN server. Along with [`max-bps` and `bps-capacity`](https://github.com/coturn/coturn/blob/upstream/4.5.1.3/README.turnserver#L414-L423) it can be used to limit the effects of a [DoS attack against the TURN server](https://tools.ietf.org/html/rfc8656#section-21.3.1). The value of _0_ shown above means _unlimited_; if a connection limit is desired it should be adjusted depending on your specific setup.
+
+  Please note that the number of allowed simultaneous connections limited by `total-quota` are not only fully established connections, but also the connections being tested during the negotiation phase used to establish the actual connection. During the negotiation phase each peer generates several candidates (an IP address and port) that can be used to establish a connection with that peer. Then the peers try to establish a connection between them with different candidate combinations until a valid one is found. If there is a TURN server then the client will connect to the TURN server too and it will generate additional candidates with the IP address of the TURN server (the so called "relay" candidates). Each of those relay candidates will try to connect to the candidates of the other peer, and each of those connection attempts allocates a slot in the available quota of the TURN server. If there are no more available slots "Allocation Quota Reached" message is written to coTURN logs.
+
+  In most cases the candidates that will be generated, and thus the connections to the TURN server during the negotiation phase, can not be known beforehand. When Janus is used the number of candidate combinations is reduced, as the Janus candidates can be known, but the number of relay candidates that will be generated by the client may still be unknown. For example, it seems that browsers generate one relay candidate for each host candidate. Host candidates are those with the IP address known to the client, so typically there will be one for each network device in the system; in the case of Firefox host candidates are also generated for the IP addresses of local bridge network devices.
+
+  You should take all that into account if you intend to set a specific value to the `total-quota` parameter, but for maximum availability an unlimited quota is recommended.
+
 - If your TURN server is running **not behind a NAT**, but with direct www connection and **static public IP**, than you can limit the IPs it listens at and answers with, by setting those as `listening-ip` and `relay-ip`. On larger deployments it is recommended to run your TURN server on a dedicated machine that is directly accessible from the internet.
 
 - The following settings can be used to adjust the **logging behaviour**. On SBCs with SDcards you may want to adjust this, as by default coTURN logs very verbose. The config file explains everything very well: