1 files changed, 35 insertions, 0 deletions
diff --git a/doc/config-debugging.rst b/doc/config-debugging.rst
new file mode 100644
index 0000000..520c2db
--- /dev/null
+++ b/doc/config-debugging.rst
@@ -0,0 +1,35 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Debugging options
+=================
+
+In case the resolver crashes, it is often helpful to collect a coredump from
+the crashed process. Configuring the system to collect coredump from crashed
+process is out of the scope of this documentation, but some tips can be found
+`here <https://lists.nic.cz/hyperkitty/list/knot-resolver-users@lists.nic.cz/message/GUHW4JSDXZ6SZUAYYQ3U2WWOZEIVVF2S/>`_.
+
+Kresd uses its own mechanism for assertions. They are checks that should always
+pass and indicate some weird or unexpected state if they don't. In such cases,
+they show up in the log as errors. By default, the process recovers from those
+states if possible, but the behaviour can be changed with the following options
+to aid further debugging.
+
+.. envvar:: debugging.assertion_abort = false|true
+
+   :return: boolean (default: false in meson's release mode, true otherwise)
+
+   Allow the process to be aborted in case it encounters a failed assertion.
+   (Some critical conditions always lead to abortion, regardless of settings.)
+
+.. envvar:: debugging.assertion_fork = milliseconds
+
+   :return: int (default: 5 minutes in meson's release mode, 0 otherwise)
+
+   If a process should be aborted, it can be done in two ways. When this is
+   set to nonzero (default), a child is forked and aborted to obtain a coredump,
+   while the parent process recovers and keeps running. This can be useful to
+   debug a rare issue that occurs in production, since it doesn't affect the
+   main process.
+
+   As the dumping can be costly, the value is a lower bound on delay between
+   consecutive coredumps of each process.  It is randomized by +-25% each time.