troubleshooting.rst 3.86 KB
Newer Older
1
.. highlight:: console
2 3
.. _Troubleshooting:

4 5 6 7
***************
Troubleshooting
***************

8 9 10
First of all, check the logs. Enabling at least the ``warning`` message
severity may help you to identify some problems. See the :ref:`Logging section`
for details.
11 12 13

..  _Submitting a bugreport:

14
Reporting bugs
15
==============
16

17
If you are unable to solve the problem by yourself, you can submit a
18 19 20
bugreport to the Knot DNS developers. For security or sensitive issues
contact the developers directly on
`knot-dns@labs.nic.cz <mailto:knot-dns@labs.nic.cz>`_.
21
All other bugs and questions may be directed to the public Knot DNS users
22
mailing list
23 24 25
(`knot-dns-users@lists.nic.cz <mailto:knot-dns-users@lists.nic.cz>`_) or
may be entered into the
`issue tracking system <https://gitlab.labs.nic.cz/labs/knot/issues>`_.
26

27
Before anything else, please try to answer the following questions:
28

29 30 31 32 33 34 35 36 37
* Has it been working?
* What has changed? System configuration, software updates, network
  configuration, firewall rules modification, hardware replacement, etc.

The bugreport should contain the answers for the previous questions and in
addition at least the following information:

* Knot DNS version and type of installation (distribution package, from source,
  etc.)
38
* Operating system, platform, kernel version
39 40
* Relevant basic hardware information (processor, amount of memory, available
  network devices, etc.)
41
* Description of the bug
42
* Log output with the highest verbosity (category ``any``, severity ``debug``)
43
* Steps to reproduce the bug (if known)
44
* Backtrace (if the bug caused a crash or a hang; see the next section)
45

46 47
If possible, please provide a minimal configuration file and zone files which
can be used to reproduce the bug.
48 49 50 51 52 53

..  _Generating backtrace:

Generating backtrace
====================

54 55 56 57 58 59 60 61 62
Backtrace carries basic information about the state of the program and how
the program got where it is. It helps determining the location of the bug in
the source code.

If you run Knot DNS from distribution packages, make sure the debugging
symbols for the package are installed. The symbols are usually distributed
in a separate package.

There are several ways to get the backtrace. One possible way is to extract
63
the backtrace from a core dump file. Core dump is a memory snapshot generated
64 65
by the operating system when a process crashes. The generating of core dumps
must be usually enabled::
66

67
    $ ulimit -c unlimited                  # Enable unlimited core dump size
68
    $ knotd ...                            # Reproduce the crash
69
    ...
70
    $ gdb knotd <core-dump-file>           # Start gdb on the core dump
71 72
    (gdb) info threads                     # Get a summary of all threads
    (gdb) thread apply all bt full         # Extract backtrace from all threads
73
    (gdb) quit
74

75
To save the backtrace into a file, the following GDB commands can be used::
76

77 78 79
    (gdb) set pagination off
    (gdb) set logging file backtrace.txt
    (gdb) set logging on
80 81
    (gdb) info threads
    (gdb) thread apply all bt full
82 83 84 85 86 87
    (gdb) set logging off

To generate a core dump of a running process, the `gcore` utility can be used::

    $ gcore -o <output-file> $(pidof knotd)

88
Please note that core dumps can be intercepted by an error-collecting system
89
service (systemd-coredump, ABRT, Apport, etc.). If you are using such a service,
90
consult its documentation about core dump retrieval.
91 92 93

If the error is reproducible, it is also possible to start and inspect the
server directly in the debugger::
94

95 96 97 98
    $ gdb --args knotd -c /etc/knot.conf
    (gdb) run
    ...

99 100
Alternatively, the debugger can be attached to a running server
process. This is generally useful when troubleshooting a stuck process::
101 102 103 104 105

    $ knotd ...
    $ gdb --pid $(pidof knotd)
    (gdb) continue
    ...
106 107 108 109 110

If you fail to get a backtrace of a running process using the previous method,
you may try the single-purpose ``pstack`` utility::

    $ pstack $(pidof knotd) > backtrace.txt