diff options
Diffstat (limited to 'doc/troubleshooting.rst')
| -rw-r--r-- | doc/troubleshooting.rst | 80 |
1 files changed, 37 insertions, 43 deletions
diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst index 4a1ea03cb..83e692345 100644 --- a/doc/troubleshooting.rst +++ b/doc/troubleshooting.rst @@ -1,37 +1,36 @@ .. meta:: :description: reStructuredText plaintext markup language +.. _Troubleshooting: + *************** Troubleshooting *************** -First of all, check the logs (:ref:`log`). By default, Knot DNS logs -all error messages to syslog. Enabling at least the ``warning`` -message severity may help you identify some problems. +First of all, check the logs (:ref:`Logging section`). Enabling at least +the ``warning`` message severity may help you identify some problems. .. _Submitting a bugreport: 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 <mailto:knot-dns@labs.nic.cz>`_. All other bugs -and questions may be directed to the Knot DNS users mailinglist +If you are unable to solve the problem by yourself, you can submit a +bugreport to the Knot DNS team. For security issues (e.g. crash) do +not use the public mailing list. Instead, write to +`knot-dns@labs.nic.cz <mailto:knot-dns@labs.nic.cz>`_. All other bugs +and questions may be directed to the Knot DNS users mailing list (`knot-dns-users@lists.nic.cz <mailto: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). +* 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``, severity ``info``) +* 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. @@ -42,22 +41,22 @@ 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 +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 + $ 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 $(which knotd) core.<KNOT_PID> # Start gdb on the 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 +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 + $ knotd -c knot.conf $ sudo gdb --pid <KNOT_PID> (gdb) continue ... @@ -70,49 +69,44 @@ 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 +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 (:ref:`log`). It is recommended to -log these messages to a file. Firstly, the debug output may be rather +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 (:ref:`Logging section`). 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: +.. _Enabling debug messages: -Enabling debug messages in server ---------------------------------- +Enabling debug messages +----------------------- Allowing debug messages in the server is possible only when -configuring the sources. Two ``configure`` options are required +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 + 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. + * ``zones`` - All operations with zones (loading, updating, saving, + timers, high-level journal management). * ``ns`` - Query processing, high-level handling of all requests - (transfers, NOTIFY, normal queries). + (transfers, notifies, 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`` + 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: +Example: -Debug messages Example ----------------------- :: $ ./configure --enable-debug=server,zones --enable-debuglevel=verbose |