Troubleshooting

First of all, check the logs (log Statement). By default, Knot DNS logs all error messages to syslog. Enabling at least the warning message severity may help you identify some problems.

Submitting a bugreport

If you are unable to solve the problem by yourselves, you can submit a bugreport to the Knot DNS team. For security issues (e.g. crash) do not use the public mailinglist. Instead, write to knot-dns@labs.nic.cz. All other bugs and questions may be directed to the Knot DNS users mailinglist (knot-dns-users@lists.nic.cz).

The bugreport should contain at least:

  • Knot DNS version and type of installation (source, package, etc.),
  • type and version of your operating system,
  • basic hardware information,
  • description of the bug,
  • log output of all messages (category any) with severity Info and higher (severities info, notice, warning, error, or any if debug messages are not turned on (see below)),
  • steps to reproduce the bug (if known),
  • backtrace (if the bug caused a crash; see next section).

If it is possible, the actual configuration file and/or zone file(s) will be very useful as well.

Generating backtrace

There are several ways to achieve that, the most common way is to leave core dumps and then extract a backtrace from it. This doesn’t affect any server operation, you just need to make sure the OS is configured to generate them:

$ ulimit -c unlimited # enable unlimited core dump size
...
$ gdb $(which knotd) core.<KNOT_PID>   # start gdb on a core dump
(gdb) thread apply all bt    # extract backtrace from all threads
(gdb) q

If the error is repeatable, you can run the binary in a gdb debugger or attach the debugger to the running process. The backtrace from a running process is generally useful when debugging problems like stuck process and similar:

$ knotc -c knot.conf start
$ sudo gdb --pid <KNOT_PID>
(gdb) continue
...
(gdb) thread apply all bt
(gdb) q

Debug messages

In some cases the aforementioned information may not be enough to find and fix the bug. In these cases it may be useful to turn on debug messages.

Two steps are required in order to log debug messages. First you need to allow the debug messages in the server. Then the logging must be configured to log debug messages (log Statement). It is recommended to log these messages to a file. Firstly, the debug output may be rather large and secondly, it is easier to use the data for debugging.

Enabling debug messages in server

Allowing debug messages in the server is possible only when configuring the sources. Two configure options are required to do this:

  • The --enable-debug option specifies the server modules for which you want to enable debug messages. One or more of the following modules may be listed, separated by commas:
    • server - Messages related to networking, threads and low-level journal handling.
    • zones - All operations with zones - loading, updating, saving, timers, high-level journal management.
    • xfr - AXFR, IXFR and NOTIFY handling.
    • packet - Packet parsing and response creation.
    • rr - Details of processed resource records.
    • ns - Query processing, high-level handling of all requests (transfers, NOTIFY, normal queries).
    • loader - Zone loading and semantic checks.
    • dnssec - DNSSEC operations.
  • The --enable-debuglevel option is used to specify the verbosity of the debug output. Be careful with this, as the details verbosity may produce really large logs (in order of GBs). There are three levels of verbosity: brief, verbose and details.

Debug messages Example

$ ./configure --enable-debug=server,zones --enable-debuglevel=verbose

Table Of Contents

Previous topic

Running Knot DNS

Next topic

Knot DNS Configuration Reference

This Page