From: Lukáš Ondráček <lukas.ondracek@nic.cz>
Date: Mon, 6 Jan 2025 15:18:37 +0000 (+0100)
Subject: doc: add defer section
X-Git-Tag: v6.0.10~6^2~9
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5eae92e24de79cd8f0bef4fa2d97ff80cb83527d;p=thirdparty%2Fknot-resolver.git

doc: add defer section
---

diff --git a/doc/user/config-defer.rst b/doc/user/config-defer.rst
new file mode 100644
index 000000000..8b09c84d5
--- /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 b09b4a92b..43b15c538 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