summaryrefslogtreecommitdiffstats
path: root/doc/config-debugging.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/config-debugging.rst35
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.