1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
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
<debugging-with-kresctl-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
<debugging-with-kresctl-subprocess-types>` for more info.
.. option:: --sudo
Run the debugger with sudo.
.. option:: --gdb <command>
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
|
