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.

pids

Lists the PIDs of the Manager’s subprocesses, separated by newlines.

--json

Makes the output more verbose, in JSON. In addition to the subprocesses’ PIDs, it also prints their types and statuses.

[proc_type]
Default:

all

Optional. The type of process to query. See Subprocess types for more info.

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:

      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.

[proc_type]
Default:

kresd

Optional. The type of process to debug. See Subprocess types for more info.

--sudo

Run the debugger with sudo.

--gdb <command>

Use a custom GDB executable. This may be a command on PATH, or an absolute path to an executable.

--print-only

Prints the GDB command line into stderr as a Python array, does not execute GDB.

Subprocess types

Some of kresctl’s commands (like pids and 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