From: Aleš Mrázek Date: Tue, 3 Dec 2024 10:40:45 +0000 (+0100) Subject: doc: debugging with kresctl moved to dev X-Git-Tag: v6.0.10~9^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cefe42bc85f2414b623112e8dc92e8b630b5ab6b;p=thirdparty%2Fknot-resolver.git doc: debugging with kresctl moved to dev --- diff --git a/doc/dev/debugging-with-kresctl.rst b/doc/dev/debugging-with-kresctl.rst new file mode 100644 index 000000000..53fcddd11 --- /dev/null +++ b/doc/dev/debugging-with-kresctl.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +.. _debugging-with-kresctl: + +********************** +Debugging with kresctl +********************** + +Knot Resolver is made up of several independent components, +so it can be difficult to debug the individual parts. +To help with this, there is an option in the kresctl utility +that can run GDB-compatible debugger on a specific component of the resolver, see the ``debug`` command. + +.. program:: kresctl + +.. option:: pids + + Lists the PIDs of the Manager's subprocesses, separated by newlines. + + .. option:: --json + + Makes the output more verbose, in JSON. In addition to the subprocesses' + PIDs, it also prints their types and statuses. + + .. option:: [proc_type] + + :default: all + + Optional. The type of process to query. See :ref:`Subprocess types + ` for more info. + + +.. option:: debug + + Executes a GDB-compatible debugger and attaches it to the Manager's + subprocesses. By default, the debugger is ``gdb`` and the subprocesses are + only the ``kresd`` workers. + + .. warning:: + + The ``debug`` command is a utility for Knot Resolver developers and is + not intended to be used by end-users. Running this command **will** make + your resolver unresponsive. + + .. note:: + + Modern kernels will prevent debuggers from tracing processes that are + not their descendants, which is exactly the scenario that happens with + ``kresctl debug``. There are three ways to work around this, listed in + the order in which they are preferred in terms of security: + + 1. Grant the debugger the ``cap_sys_ptrace`` capability + (**recommended**) + + * For ``gdb``, this may be achieved by using the ``setcap`` + command like so: + + .. code-block:: bash + + sudo setcap cap_sys_ptrace=eip /usr/bin/gdb + + 2. Run the debugger as root + + * You may use the ``--sudo`` option to achieve this + + 3. Set ``/proc/sys/kernel/yama/ptrace_scope`` to ``0`` + + * This will allow **all** programs in your current session to + trace each other. Handle with care! + + .. note:: + + This command will only work if executed on the same machine where Knot + Resolver is running. Remote debugging is currently not supported. + + .. option:: [proc_type] + + :default: kresd + + Optional. The type of process to debug. See :ref:`Subprocess types + ` for more info. + + .. option:: --sudo + + Run the debugger with sudo. + + .. option:: --gdb + + Use a custom GDB executable. This may be a command on ``PATH``, or an + absolute path to an executable. + + .. option:: --print-only + + Prints the GDB command line into ``stderr`` as a Python array, does not + execute GDB. + + +.. _debugging-with-kresctl-subprocess-types: + +Subprocess types +---------------- + +Some of ``kresctl``'s commands (like :option:`pids` and :option:`debug`) take a subprocess +type value determining which subprocesses will be affected by them. The possible +values are as follows: + +* ``kresd`` -- the worker daemons +* ``gc`` -- the cache garbage collector +* ``all`` -- all of the Manager's subprocesses diff --git a/doc/dev/index.rst b/doc/dev/index.rst index a13e3d616..f0d557630 100644 --- a/doc/dev/index.rst +++ b/doc/dev/index.rst @@ -30,6 +30,13 @@ Welcome to Knot Resolver's documentation for developers and advanced users! manager-dev-code layered-protocols +.. toctree:: + :caption: Debugging + :name: debugging-chapter + :maxdepth: 1 + + debugging-with-kresctl + .. toctree:: :caption: Lua configuration :name: configuration-lua-chapter diff --git a/doc/user/manager-client.rst b/doc/user/manager-client.rst index 7d43a07f1..abeab2c93 100644 --- a/doc/user/manager-client.rst +++ b/doc/user/manager-client.rst @@ -304,99 +304,3 @@ single ``kresctl`` command. command is run. Requires a connection to the management API. - - -.. option:: pids - - Lists the PIDs of the Manager's subprocesses, separated by newlines. - - .. option:: --json - - Makes the output more verbose, in JSON. In addition to the subprocesses' - PIDs, it also prints their types and statuses. - - .. option:: [proc_type] - - :default: ``all`` - - Optional. The type of process to query. See :ref:`Subprocess types - ` for more info. - - -.. option:: debug - - Executes a GDB-compatible debugger and attaches it to the Manager's - subprocesses. By default, the debugger is ``gdb`` and the subprocesses are - only the ``kresd`` workers. - - .. warning:: - - The ``debug`` command is a utility for Knot Resolver developers and is - not intended to be used by end-users. Running this command **will** make - your resolver unresponsive. - - .. note:: - - Modern kernels will prevent debuggers from tracing processes that are - not their descendants, which is exactly the scenario that happens with - ``kresctl debug``. There are three ways to work around this, listed in - the order in which they are preferred in terms of security: - - 1. Grant the debugger the ``cap_sys_ptrace`` capability - (**recommended**) - - * For ``gdb``, this may be achieved by using the ``setcap`` - command like so: - - .. code-block:: bash - - sudo setcap cap_sys_ptrace=eip /usr/bin/gdb - - 2. Run the debugger as root - - * You may use the ``--sudo`` option to achieve this - - 3. Set ``/proc/sys/kernel/yama/ptrace_scope`` to ``0`` - - * This will allow **all** programs in your current session to - trace each other. Handle with care! - - .. note:: - - This command will only work if executed on the same machine where Knot - Resolver is running. Remote debugging is currently not supported. - - .. option:: [proc_type] - - :default: ``kresd`` - - Optional. The type of process to debug. See :ref:`Subprocess types - ` for more info. - - .. option:: --sudo - - Run the debugger with sudo. - - .. option:: --gdb - - Use a custom GDB executable. This may be a command on ``PATH``, or an - absolute path to an executable. - - .. option:: --print-only - - Prints the GDB command line into ``stderr`` as a Python array, does not - execute GDB. - - -.. _manager-client-subprocess-types: - -Subprocess types ----------------- - -Some of ``kresctl``'s commands (like :option:`pids` and :option:`debug`) take a subprocess -type value determining which subprocesses will be affected by them. The possible -values are as follows: - -* ``kresd`` -- the worker daemons -* ``gc`` -- the cache garbage collector -* ``all`` -- all of the Manager's subprocesses