doc: add defer section

2 files changed, 59 insertions, 0 deletions

diff --git a/doc/user/config-defer.rst b/doc/user/config-defer.rst
new file mode 100644
index 00000000..8b09c84d
--- /dev/null
+++ b/doc/user/config-defer.rst
@@ -0,0 +1,58 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _config-defer:
+
+Request prioritization (defer)
+==============================
+
+Defer tries to mitigate DoS attacks by measuring cpu time consumption of different hosts and networks
+and deferring future requests from the same origin.
+If there is not enough time to process all the requests, the lowest priority ones are dropped.
+
+The time measurements are taken into account only for TCP,
+as the source address of plain UDP can be forged.
+We aim to spend half of the time for UDP without prioritization
+and half of the time for TCP with prioritization,
+if there are enough requests of both types.
+
+Internally, defer uses similar approach as :ref:`rate limiting <config-rate-limiting>`,
+except that cpu time is measured instead of number of requests.
+There are four main priority levels with assigned rate and instant limits for individual hosts
+and their multiples for networks -- the same prefix lengths and multipliers are used as for rate limiting.
+Within a priority level, requests are ordered by the longest prefix length,
+on which it falls into that level,
+so that we first process requests that are on that level only as part of a larger network
+and then requests that fall there also due to a smaller subnetwork,
+which possibly caused deprioritization of the larger network.
+Further ordering is according to the time of arrival.
+
+If a request is deferred for too long, it is dropped.
+This can happen also for UDP requests,
+which are stored in a single queue ordered by the time of their arrival.
+
+We note that the data of all deferred queries may occupy 64 MiB of memory per worker... TODO
+
+The detailed configuration is printed by ``defer`` group on ``info`` level on startup (unless disabled).
+
+
+.. option:: defer/enabled: true|false
+
+    :default: true
+
+    Enable request prioritization.
+
+    If disabled, requests are processed in order of their arrival
+    and their possible dropping in case of overloading
+    is caused only by the overflow of kernel queues.
+
+
+.. option:: defer/log-period: <time ms|s|m|h|d>
+
+    :default: 0s
+
+    Minimal time between two log messages, or ``0s`` to disable logging.
+
+    If a response is dropped after being deferred for too long, the address is logged
+    and logging is disabled for the :option:`log-period <defer/log-period: <time ms|s|m|h|d>`.
+    As long as dropping is needed, one source is logged each period
+    and sources with more dropped queries have greater probability to be chosen.
diff --git a/doc/user/config-performance.rst b/doc/user/config-performance.rst
index b09b4a92..43b15c53 100644
--- a/doc/user/config-performance.rst
+++ b/doc/user/config-performance.rst
@@ -33,3 +33,4 @@ impact than cache settings and number of instances.
    config-priming
    config-edns-keepalive
    config-rate-limiting
+   config-defer