@node Troubleshooting, Statement Index, Running Knot DNS, Top
@chapter Troubleshooting

@menu
* Submitting a bugreport:: 
* Generating backtrace::  
* Debug messages::
@end menu

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

@node Submitting a bugreport
@section 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 
@url{mailto:knot-dns@@labs.nic.cz, knot-dns@@labs.nic.cz}. All other bugs 
and questions may be directed to the Knot DNS users mailinglist 
(@url{mailto:knot-dns-users@@lists.nic.cz, knot-dns-users@@lists.nic.cz}).

The bugreport should contain at least:
@itemize
@item Knot DNS version and type of installation (source, package, etc.),
@item type and version of your operating system,
@item basic hardware information,
@item description of the bug,
@item log output of all messages (category @code{any}) with severity Info 
and higher (severities @code{info, notice, warning, error}, or @code{any} if debug messages are not turned on (see below)),
@item steps to reproduce the bug (if known),
@item backtrace (if the bug caused a crash; see next section).
@end itemize

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

@node Generating backtrace
@section 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.

@example
$ 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
@end example

If the error is repeatable, you can run the binary in a @code{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.
@example
$ knotc -c knot.conf start
$ sudo gdb --pid <KNOT_PID>
(gdb) continue
...
(gdb) thread apply all bt
(gdb) q
@end example



@node Debug messages
@section Debug messages

@menu
* Enabling debug messages in server::
@end menu

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 (@pxref{log}). 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.

@node Enabling debug messages in server
@subsection Enabling debug messages in server

@menu
* Debug messages Example::
@end menu

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

@itemize
@item
The @code{--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:

@itemize
@item @code{server} - Messages related to networking, threads and low-level 
      journal handling.
@item @code{zones} - All operations with zones - loading, updating, saving, 
      timers, high-level journal management.
@item @code{xfr} - AXFR, IXFR and NOTIFY handling.
@item @code{packet} - Packet parsing and response creation.
@item @code{dname} - Parsing, comparing and other operations on domain names.
@item @code{rr} - Details of processed resource records.
@item @code{ns} - Query processing, high-level handling of all requests 
      (transfers, NOTIFY, normal queries).
@item @code{hash} - Details of hash table (the main data structure) operation.
@item @code{compiler} - Zone file compilation.
@end itemize

@item
The @code{--enable-debuglevel} option is used to specify the verbosity of the
debug output. Be careful with this, as the @code{details} verbosity may produce
really large logs (in order of GBs). There are three levels of verbosity: 
@code{brief}, @code{verbose} and @code{details}.

@end itemize

@node Debug messages Example
@subsubsection Example

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