Adding upstream version 3.3.4.upstream/3.3.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 110 insertions, 0 deletions

diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst
new file mode 100644
index 0000000..3d7c359
--- /dev/null
+++ b/doc/troubleshooting.rst
@@ -0,0 +1,110 @@
+.. highlight:: none
+.. _Troubleshooting:
+
+***************
+Troubleshooting
+***************
+
+First of all, check the logs. Enabling at least the ``warning`` message
+severity may help you to identify some problems. See the :ref:`log section`
+for details.
+
+..  _Submitting a bugreport:
+
+Reporting bugs
+==============
+
+If you are unable to solve the problem by yourself, you can submit a
+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>`_.
+All other bugs and questions may be directed to the public Knot DNS users
+mailing list
+(`knot-dns-users@lists.nic.cz <mailto:knot-dns-users@lists.nic.cz>`_) or
+may be entered into the
+`issue tracking system <https://gitlab.nic.cz/knot/knot-dns/issues>`_.
+
+Before anything else, please try to answer the following questions:
+
+* 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.)
+* Operating system, platform, kernel version
+* Relevant basic hardware information (processor, amount of memory, available
+  network devices, etc.)
+* Description of the bug
+* Log output with the highest verbosity (category ``any``, severity ``debug``)
+* Steps to reproduce the bug (if known)
+* Backtrace (if the bug caused a crash or a hang; see the next section)
+
+If possible, please provide a minimal configuration file and zone files which
+can be used to reproduce the bug.
+
+..  _Generating backtrace:
+
+Generating backtrace
+====================
+
+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
+the backtrace from a core dump file. Core dump is a memory snapshot generated
+by the operating system when a process crashes. The generating of core dumps
+must be usually enabled::
+
+    $ ulimit -c unlimited                  # Enable unlimited core dump size
+    $ knotd ...                            # Reproduce the crash
+    ...
+    $ gdb knotd <core-dump-file>           # Start gdb on the core dump
+    (gdb) info threads                     # Get a summary of all threads
+    (gdb) thread apply all bt full         # Extract backtrace from all threads
+    (gdb) quit
+
+To save the backtrace into a file, the following GDB commands can be used::
+
+    (gdb) set pagination off
+    (gdb) set logging file backtrace.txt
+    (gdb) set logging on
+    (gdb) info threads
+    (gdb) thread apply all bt full
+    (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)
+
+Please note that core dumps can be intercepted by an error-collecting system
+service (systemd-coredump, ABRT, Apport, etc.). If you are using such a service,
+consult its documentation about core dump retrieval.
+
+If the error is reproducible, it is also possible to start and inspect the
+server directly in the debugger::
+
+    $ gdb --args knotd -c /etc/knot.conf
+    (gdb) run
+    ...
+
+Alternatively, the debugger can be attached to a running server
+process. This is generally useful when troubleshooting a stuck process::
+
+    $ knotd ...
+    $ gdb --pid $(pidof knotd)
+    (gdb) continue
+    ...
+
+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