release v5.7.3

content/documentation/stable

-v5.7.2
\ No newline at end of file
+v5.7.3
\ No newline at end of file

content/documentation/v5.7.3/.buildinfo

+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: aebb3028c63d0fb97dac04c2bee0b2ba
+tags: 645f666f9bcd5a90fca523b33c5a78b7

content/documentation/v5.7.3/_sources/NEWS.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _release_notes:
+
+*************
+Release notes
+*************
+
+Version numbering
+=================
+Version number format is ``major.minor.patch``.
+Knot Resolver does not use semantic versioning even though the version number looks similar.
+
+Leftmost number which was changed signalizes what to expect when upgrading:
+
+Major version
+    * Manual upgrade steps might be necessary, please follow instructions in :ref:`Upgrading` section.
+    * Major releases may contain significant changes including changes to configuration format.
+    * We might release a new major also when internal implementation details change significantly.
+
+Minor version
+   * Configuration stays compatible with the previous version, except for undocumented or very obscure options.
+   * Upgrade should be seamless for users who use modules shipped as part of Knot Resolver distribution.
+   * Incompatible changes in internal APIs are allowed in minor versions. Users who develop or use custom modules
+     (i.e. modules not distributed together with Knot Resolver) need to double check their modules for incompatibilities.
+     :ref:`Upgrading` section should contain hints for module authors.
+
+Patch version
+    * Everything should be compatible with the previous version.
+    * API for modules should be stable on best effort basis, i.e. API is very unlikely to break in patch releases.
+    * Custom modules might need to be recompiled, i.e. ABI compatibility is not guaranteed.
+
+This definition is not applicable to versions older than 5.2.0.
+
+.. include:: ../NEWS
+

content/documentation/v5.7.3/_sources/build.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _build:
+
+Building from sources
+=====================
+
+.. note:: Latest up-to-date packages for various distribution can be obtained
+   from web `<https://knot-resolver.cz/download/>`_.
+
+Knot Resolver is written for UNIX-like systems using modern C standards.
+Beware that some 64-bit systems with LuaJIT 2.1 may be affected by
+`a problem <https://github.com/LuaJIT/LuaJIT/blob/v2.1.0-beta3/doc/status.html#L100>`_
+-- Linux on x86_64 is unaffected but `Linux on aarch64 is
+<https://gitlab.nic.cz/knot/knot-resolver/issues/216>`_.
+
+.. code-block:: bash
+
+   $ git clone --recursive https://gitlab.nic.cz/knot/knot-resolver.git
+
+Dependencies
+------------
+
+.. note:: This section lists basic requirements. Individual modules
+   might have additional build or runtime dependencies.
+
+The following dependencies are needed to build and run Knot Resolver:
+
+.. csv-table::
+   :header: "Requirement", "Notes"
+
+   "ninja", "*build only*"
+   "meson >= 0.49", "*build only* [#]_"
+   "C and C++ compiler", "*build only* [#]_"
+   "`pkg-config`_", "*build only* [#]_"
+   "libknot_ 3.0.2+", "Knot DNS libraries"
+   "LuaJIT_ 2.0+", "Embedded scripting language"
+   "libuv_ 1.7+", "Multiplatform I/O and services"
+   "lmdb", "Memory-mapped database for cache"
+   "GnuTLS", "TLS"
+
+There are also *optional* packages that enable specific functionality in Knot
+Resolver:
+
+.. TODO cqueues is really used on multiple places, sometimes indirectly
+
+.. csv-table::
+   :header: "Optional", "Needed for", "Notes"
+
+   "jemalloc_", "``daemon``", "Improve long-term memory consumption."
+   "nghttp2_", "``daemon``", "DNS over HTTPS support."
+   "libsystemd_", "``daemon``", "Systemd watchdog support."
+   "`libcap-ng`_", "``daemon``", "Linux capabilities: support dropping them."
+   "`lua-basexx`_", "``config tests``", "Number base encoding/decoding for Lua."
+   "`lua-http`_", "``modules/http``", "HTTP/2 client/server for Lua."
+   "`lua-cqueues`_", "some lua modules", ""
+   "cmocka_", "``unit tests``", "Unit testing framework."
+   "dnsdist_", "``proxyv2 test``", "DNS proxy server"
+   "Doxygen_", "``documentation``", "Generating API documentation."
+   "Sphinx_ and sphinx_rtd_theme_", "``documentation``", "Building this
+   documentation."
+   "Texinfo_", "``documentation``", "Generating this documentation in Info
+   format."
+   "breathe_", "``documentation``", "Exposing Doxygen API doc to Sphinx."
+   "libprotobuf_ 3.0+", "``modules/dnstap``", "Protocol Buffers support for
+   dnstap_."
+   "`libprotobuf-c`_ 1.0+", "``modules/dnstap``", "C bindings for Protobuf."
+   "libfstrm_ 0.2+", "``modules/dnstap``", "Frame Streams data transport
+   protocol."
+   "luacheck_", "``lint-lua``", "Syntax and static analysis checker for Lua."
+   "`clang-tidy`_", "``lint-c``", "Syntax and static analysis checker for C."
+   "luacov_", "``check-config``", "Code coverage analysis for Lua modules."
+
+.. [#] If ``meson >= 0.49`` isn't available for your distro, check backports
+   repository or use python pip to install it.
+.. [#] Requires ``__attribute__((cleanup))`` and ``-MMD -MP`` for
+   dependency file generation. We test GCC and Clang, and ICC is likely to work as well.
+.. [#] You can use variables ``<dependency>_CFLAGS`` and ``<dependency>_LIBS``
+   to configure dependencies manually (i.e. ``libknot_CFLAGS`` and
+   ``libknot_LIBS``).
+
+Packaged dependencies
+~~~~~~~~~~~~~~~~~~~~~
+
+.. note:: Some build dependencies can be found in
+   `home:CZ-NIC:knot-resolver-build
+   <https://build.opensuse.org/project/show/home:CZ-NIC:knot-resolver-build>`_.
+
+On reasonably new systems most of the dependencies can be resolved from packages,
+here's an overview for several platforms.
+
+* **Debian/Ubuntu** - Current stable doesn't have new enough Meson
+  and libknot. Use repository above or build them yourself. Fresh list of dependencies can be found in `Debian control file in our repo <https://gitlab.nic.cz/knot/knot-resolver/blob/master/distro/deb/control>`_, search for "Build-Depends".
+
+* **CentOS/Fedora/RHEL/openSUSE** - Fresh list of dependencies can be found in `RPM spec file in our repo <https://gitlab.nic.cz/knot/knot-resolver/blob/master/distro/rpm/knot-resolver.spec>`_, search for "BuildRequires".
+
+* **FreeBSD** - when installing from ports, all dependencies will install
+  automatically, corresponding to the selected options.
+* **Mac OS X** - the dependencies can be obtained from `Homebrew formula <https://formulae.brew.sh/formula/knot-resolver>`_.
+
+Compilation
+-----------
+
+.. note::
+
+   Knot Resolver uses `Meson Build system <https://mesonbuild.com/>`_.
+   Shell snippets below should be sufficient for basic usage
+   but users unfamiliar with Meson Build might want to read introductory
+   article `Using Meson <https://mesonbuild.com/Quick-guide.html>`_.
+
+Following example script will:
+
+  - create new build directory named ``build_dir``
+  - configure installation path ``/tmp/kr``
+  - enable static build (to allow installation to non-standard path)
+  - build Knot Resolver
+  - install it into the previously configured path
+
+.. code-block:: bash
+
+   $ meson setup build_dir --prefix=/tmp/kr --default-library=static
+   $ ninja -C build_dir
+   $ ninja install -C build_dir
+
+At this point you can execute the newly installed binary using path ``/tmp/kr/sbin/kresd``.
+
+.. note:: When compiling on OS X, creating a shared library is currently not
+   possible when using luajit package from Homebrew due to `#37169
+   <https://github.com/Homebrew/homebrew-core/issues/37169>`_.
+
+Build options
+~~~~~~~~~~~~~
+
+It's possible to change the compilation with build options. These are useful to
+packagers or developers who wish to customize the daemon behaviour, run
+extended test suites etc.  By default, these are all set to sensible values.
+
+For complete list of build options create a build directory and run:
+
+.. code-block:: bash
+
+   $ meson setup build_dir
+   $ meson configure build_dir
+
+To customize project build options, use ``-Doption=value`` when creating
+a build directory:
+
+.. code-block:: bash
+
+   $ meson setup build_dir -Ddoc=enabled
+
+... or change options in an already existing build directory:
+
+.. code-block:: bash
+
+   $ meson configure build_dir -Ddoc=enabled
+
+
+.. _build-custom-flags:
+
+Customizing compiler flags
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you'd like to use customize the build, see meson's `built-in options
+<https://mesonbuild.com/Builtin-options.html>`_. For hardening, see ``b_pie``.
+
+For complete control over the build flags, use ``--buildtype=plain`` and set
+``CFLAGS``, ``LDFLAGS`` when creating the build directory with ``meson``
+command.
+
+.. include:: ../tests/README.rst
+
+.. _build-html-doc:
+
+Documentation
+-------------
+
+To check for documentation dependencies and allow its installation, use
+``-Ddoc=enabled``. The documentation doesn't build automatically. Instead,
+target ``doc`` must be called explicitly.
+
+.. code-block:: bash
+
+   $ meson configure build_dir -Ddoc=enabled
+   $ ninja -C build_dir doc
+
+Tarball
+-------
+
+Released tarballs are available from `<https://knot-resolver.cz/download/>`_
+
+To make a release tarball from git, use the following command. The
+
+.. code-block:: bash
+
+   $ ninja -C build_dir dist
+
+It's also possible to make a development snapshot tarball:
+
+.. code-block:: bash
+
+   $ ./scripts/make-archive.sh
+
+.. _packaging:
+
+Packaging
+---------
+
+Recommended build options for packagers:
+
+* ``--buildtype=release`` for default flags (optimization, asserts, ...). For complete control over flags, use ``plain`` and see :ref:`build-custom-flags`.
+* ``--prefix=/usr`` to customize
+  prefix, other directories can be set in a similar fashion, see ``meson setup
+  --help``
+* ``-Dsystemd_files=enabled`` for systemd unit files
+* ``-Ddoc=enabled`` for offline documentation (see :ref:`build-html-doc`)
+* ``-Dinstall_kresd_conf=enabled`` to install default config file
+* ``-Dclient=enabled`` to force build of kresc
+* ``-Dunit_tests=enabled`` to force build of unit tests
+
+Systemd
+~~~~~~~
+
+It's recommended to use the upstream system unit files. If any customizations
+are required, drop-in files should be used, instead of patching/changing the
+unit files themselves.
+
+To install systemd unit files, use the ``-Dsystemd_files=enabled`` build option.
+
+To support enabling services after boot, you must also link ``kresd.target`` to
+``multi-user.target.wants``:
+
+.. code-block:: bash
+
+   ln -s ../kresd.target /usr/lib/systemd/system/multi-user.target.wants/kresd.target
+
+Trust anchors
+~~~~~~~~~~~~~
+
+If the target distro has externally managed (read-only) DNSSEC trust anchors
+or root hints use this:
+
+* ``-Dkeyfile_default=/usr/share/dns/root.key``
+* ``-Droot_hints=/usr/share/dns/root.hints``
+* ``-Dmanaged_ta=disabled``
+
+In case you want to have automatically managed DNSSEC trust anchors instead,
+set ``-Dmanaged_ta=enabled`` and make sure both ``keyfile_default`` file and
+its parent directories are writable by kresd process (after package installation!).
+
+Docker image
+------------
+
+Visit `hub.docker.com/r/cznic/knot-resolver
+<https://hub.docker.com/r/cznic/knot-resolver/>`_ for instructions how to run
+the container.
+
+For development, it's possible to build the container directly from your git tree:
+
+.. code-block:: bash
+
+   $ docker build -t knot-resolver .
+
+
+.. _jemalloc: https://jemalloc.net
+.. _libuv: https://github.com/libuv/libuv
+.. _LuaJIT: http://luajit.org/luajit.html
+.. _Doxygen: https://www.doxygen.nl/manual/index.html
+.. _breathe: https://github.com/michaeljones/breathe
+.. _Sphinx: http://sphinx-doc.org/
+.. _sphinx_rtd_theme: https://pypi.python.org/pypi/sphinx_rtd_theme
+.. _Texinfo: https://www.gnu.org/software/texinfo/
+.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
+.. _libknot: https://gitlab.nic.cz/knot/knot-dns
+.. _cmocka: https://cmocka.org/
+.. _dnsdist: https://dnsdist.org/
+.. _lua-basexx: https://github.com/aiq/basexx
+.. _lua-http: https://luarocks.org/modules/daurnimator/http
+.. _lua-cqueues: https://25thandclement.com/~william/projects/cqueues.html
+.. _deckard: https://gitlab.nic.cz/knot/deckard
+.. _nghttp2: https://nghttp2.org/
+.. _libsystemd: https://www.freedesktop.org/wiki/Software/systemd/
+.. _`libcap-ng`: https://people.redhat.com/sgrubb/libcap-ng/
+.. _dnstap: http://dnstap.info/
+.. _libprotobuf: https://developers.google.com/protocol-buffers/
+.. _libprotobuf-c: https://github.com/protobuf-c/protobuf-c/wiki
+.. _libfstrm: https://github.com/farsightsec/fstrm
+.. _luacheck: http://luacheck.readthedocs.io
+.. _clang-tidy: http://clang.llvm.org/extra/clang-tidy/index.html
+.. _luacov: https://lunarmodules.github.io/luacov/
+.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php

content/documentation/v5.7.3/_sources/config-answer-reordering.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Answer reordering
+=================
+Certain clients are "dumb" and always connect to first IP address or name found
+in a DNS answer received from resolver instead of picking randomly.
+As a workaround for such broken clients it is possible to randomize
+order of records in DNS answers sent by resolver:
+
+.. function:: reorder_RR([true | false])
+
+   :param boolean new_value: ``true`` to enable or ``false`` to disable randomization *(optional)*
+   :return: The (new) value of the option
+
+   If set, resolver will vary the order of resource records within RR sets.
+   It is enabled by default since 5.3.0.
+

content/documentation/v5.7.3/_sources/config-debugging.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Debugging options
+=================
+
+In case the resolver crashes, it is often helpful to collect a coredump from
+the crashed process. Configuring the system to collect coredump from crashed
+process is out of the scope of this documentation, but some tips can be found
+`here <https://lists.nic.cz/hyperkitty/list/knot-resolver-users@lists.nic.cz/message/GUHW4JSDXZ6SZUAYYQ3U2WWOZEIVVF2S/>`_.
+
+Kresd uses its own mechanism for assertions. They are checks that should always
+pass and indicate some weird or unexpected state if they don't. In such cases,
+they show up in the log as errors. By default, the process recovers from those
+states if possible, but the behaviour can be changed with the following options
+to aid further debugging.
+
+.. envvar:: debugging.assertion_abort = false|true
+
+   :return: boolean (default: false in meson's release mode, true otherwise)
+
+   Allow the process to be aborted in case it encounters a failed assertion.
+   (Some critical conditions always lead to abortion, regardless of settings.)
+
+.. envvar:: debugging.assertion_fork = milliseconds
+
+   :return: int (default: 5 minutes in meson's release mode, 0 otherwise)
+
+   If a process should be aborted, it can be done in two ways. When this is
+   set to nonzero (default), a child is forked and aborted to obtain a coredump,
+   while the parent process recovers and keeps running. This can be useful to
+   debug a rare issue that occurs in production, since it doesn't affect the
+   main process.
+
+   As the dumping can be costly, the value is a lower bound on delay between
+   consecutive coredumps of each process.  It is randomized by +-25% each time.

content/documentation/v5.7.3/_sources/config-dnssec.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _dnssec-config:
+
+*************************
+DNSSEC, data verification
+*************************
+
+Good news! Knot Resolver uses secure configuration by default, and this configuration
+should not be changed unless absolutely necessary, so feel free to skip over this section.
+
+.. include:: ../daemon/lua/trust_anchors.rst
+
+DNSSEC is main technology to protect data, but it is also possible to change how strictly
+resolver checks data from insecure DNS zones:
+
+.. include:: ../lib/layer/mode.rst

content/documentation/v5.7.3/_sources/config-experimental.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+*********************
+Experimental features
+*********************
+
+Following functionality and APIs are in continuous development.
+Features in this section may changed, replaced or dropped in any release.
+
+.. toctree::
+   :maxdepth: 1
+
+   daemon-scripting
+   modules-experimental_dot_auth

content/documentation/v5.7.3/_sources/config-logging-header.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Logging API
+===========
+
+.. _config_log_groups:
+
+.. doxygenfile:: lib/log.h
+    :project: libkres

content/documentation/v5.7.3/_sources/config-logging-monitoring.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+********************************
+Logging, monitoring, diagnostics
+********************************
+
+To read service logs use commands usual for your distribution.
+E.g. on distributions using systemd-journald use command ``journalctl -u kresd@* -f``.
+
+Knot Resolver supports 6 logging levels - ``crit``, ``err``, ``warning``,
+``notice``, ``info``, ``debug``. All levels with the same meaning as is defined
+in ``syslog.h``. It is possible change logging level using
+:func:`log_level` function.
+
+.. code-block:: lua
+
+  log_level('debug') -- too verbose for normal usage
+
+Logging level ``notice`` is set after start by default,
+so logs from Knot Resolver should contain only couple lines a day.
+For debugging purposes it is possible to use the very verbose ``debug`` level,
+but that is generally not usable unless restricted in some way (see below).
+
+In addition to levels, logging is also divided into the
+:ref:`groups <config_log_groups>`. All groups
+are logged by default, but you can enable ``debug`` level for selected groups using
+:func:`log_groups` function. Other groups are logged to the log level
+set by :func:`log_level`.
+
+It is also possible to enable ``debug`` logging level for particular requests,
+with :ref:`policies <mod-policy-logging>` or as :ref:`an HTTP service <mod-http-trace>`.
+
+Less verbose logging for DNSSEC validation errors can be enabled by using :ref:`mod-bogus_log` module.
+
+.. py:function:: log_level([level])
+
+  :param: string ``'crit'``, ``'err'``, ``'warning'``, ``'notice'``,
+   ``'info'`` or ``'debug'``
+  :return: string Current logging level.
+
+  Pass a string to set the global logging level.
+
+  .. py:function:: verbose([true | false])
+
+     .. deprecated:: 5.4.0
+        Use :func:`log_level` instead.
+
+     :param: ``true`` enable ``debug`` level, ``false`` switch to default level (``notice``).
+     :return: boolean ``true`` when ``debug`` level is enabled.
+
+     Toggle between ``debug`` and ``notice`` log level. Use only for debugging purposes.
+     On busy systems verbose logging can produce several MB of logs per
+     second and will slow down operation.
+
+.. py:function:: log_target(target)
+
+  :param: string ``'syslog'``, ``'stderr'``, ``'stdout'``
+  :return: string Current logging target.
+
+   Knot Resolver logs to standard error stream by default,
+   but typical systemd units change that to ``'syslog'``.
+   That setting logs directly through systemd's facilities
+   (if available) to preserve more meta-data.
+
+.. py:function:: log_groups([table])
+
+  :param: table of string(s) representing :ref:`log groups <config_log_groups>`
+  :return: table of string with currently set log groups
+
+  Use to turn-on debug logging for the selected groups regardless of the global
+  log level. Calling with no argument lists the currently active log groups. To
+  remove all log groups, call the function with an empty table.
+
+  .. code-block:: lua
+
+     log_groups({'io', 'tls'}  -- turn on debug logging for io and tls groups
+     log_groups()              -- list active log groups
+     log_groups({})            -- remove all log groups
+
+Various statistics for monitoring purposes are available in :ref:`mod-stats` module, including export to central systems like Graphite, Metronome, InfluxDB, or Prometheus format.
+
+Resolver :ref:`mod-watchdog` is tool to detect and recover from potential bugs that cause the resolver to stop responding properly to queries.
+
+Additional monitoring and debugging methods are described below. If none of these options fits your deployment or if you have special needs you can configure your own checks and exports using :ref:`async-events`.
+
+.. toctree::
+   :maxdepth: 1
+
+   modules-bogus_log
+   modules-stats
+   daemon-bindings-worker
+   modules-nsid
+   modules-http-trace
+   modules-watchdog
+   modules-dnstap
+   modules-ta_sentinel
+   modules-ta_signal_query
+   modules-detect_time_skew
+   modules-detect_time_jump
+   config-debugging
+   config-logging-header

content/documentation/v5.7.3/_sources/config-network-forwarding.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Forwarding
+----------
+
+*Forwarding* configuration instructs resolver to forward cache-miss queries from clients to manually specified DNS resolvers *(upstream servers)*. In other words the *forwarding* mode does exact opposite of the default *recursive* mode because resolver in *recursive* mode automatically selects which servers to ask.
+
+Main use-cases are:
+
+  - Building a tree structure of DNS resolvers to improve performance (by improving cache hit rate).
+  - Accessing domains which are not available using recursion (e.g. if internal company servers return different answers than public ones).
+  - Forwarding through a central DNS traffic filter.
+
+Forwarding implementation in Knot Resolver has following properties:
+
+  - Answers from *upstream* servers are cached.
+  - Answers from *upstream* servers are locally DNSSEC-validated, unless :func:`policy.STUB` is used.
+  - Resolver automatically selects which IP address from given set of IP addresses will be used (based on performance characteristics).
+  - Forwarding can use either unencrypted DNS protocol, or :ref:`tls-forwarding`.
+
+.. warning::
+
+        We strongly discourage use of "fake top-level domains" like ``corp.`` because these made-up domains are indistinguishable from an attack, so DNSSEC validation will prevent such domains from working. If you *really* need a variant of forwarding which does not DNSSEC-validate received data please see chapter :ref:`dns-graft`. In long-term it is better to migrate data into a legitimate, properly delegated domains which do not suffer from these security problems.
+
+
+Simple examples for **unencrypted** forwarding:
+
+.. code-block:: lua
+
+        -- forward all traffic to specified IP addresses (selected automatically)
+        policy.add(policy.all(policy.FORWARD({'2001:db8::1', '192.0.2.1'})))
+
+        -- forward only queries for names under domain example.com to a single IP address
+        policy.add(policy.suffix(policy.FORWARD('192.0.2.1'), {todname('example.com.')}))
+
+To configure encrypted version please see chapter :ref:`tls-forwarding`.
+
+Forwarding is documented in depth together with rest of :ref:`mod-policy`.

content/documentation/v5.7.3/_sources/config-network.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _network-configuration:
+
+************************
+Networking and protocols
+************************
+
+This section describes configuration of network interfaces
+and protocols. Please keep in mind that DNS resolvers act
+as *DNS server* and *DNS client* at the same time,
+and that these roles require different configuration.
+
+This picture illustrates different actors involved DNS resolution process,
+supported protocols, and clarifies what we call *server configuration*
+and *client configuration*.
+
+.. image:: server_terminology.svg
+
+*Attribution: Icons by Bernar Novalyi from the Noun Project*
+
+For *resolver's clients* the resolver itself acts as a DNS server.
+
+After receiving a query the resolver will attempt to find
+answer in its cache. If the data requested by resolver's
+client is not available in resolver's cache (so-called *cache-miss*)
+the resolver will attempt to obtain the data from servers *upstream*
+(closer to the source of information), so at this point the resolver
+itself acts like a DNS client and will send DNS query to other servers.
+
+By default the Knot Resolver works in recursive mode, i.e.
+the resolver will contact authoritative servers on the Internet.
+Optionally it can be configured in forwarding mode,
+where cache-miss queries are *forwarded to another DNS resolver*
+for processing.
+
+Server (communication with clients)
+===================================
+
+.. toctree::
+   :maxdepth: 2
+
+   daemon-bindings-net_server
+   daemon-bindings-net_tlssrv
+   modules-http
+
+Client (retrieving answers from servers)
+========================================
+
+Following chapters describe basic configuration of how resolver retrieves data from other *(upstream)* servers. Data processing is also affected by configured policies, see chapter :ref:`policies` for more advanced usage.
+
+.. toctree::
+   :maxdepth: 2
+
+   daemon-bindings-net_client
+   config-network-forwarding
+
+DNS protocol tweaks
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   daemon-bindings-net_dns_tweaks

content/documentation/v5.7.3/_sources/config-no-systemd-privileges.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Privileges and capabilities
+===========================
+
+The kresd daemon requires privileges when it is configured to bind to
+well-known ports. There are multiple ways to achieve this.
+
+Using capabilities
+^^^^^^^^^^^^^^^^^^
+
+The most secure and recommended way is to use capabilities and execute kresd as
+an unprivileged user.
+
+* ``CAP_NET_BIND_SERVICE`` is required to bind to well-known ports.
+* ``CAP_SETPCAP`` when this capability is available, kresd drops any extra
+  capabilities after the daemon successfully starts when running as
+  a non-root user.
+
+Running as non-privileged user
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Another possibility is to start the process as privileged user and then switch
+to a non-privileged user after binding to network interfaces.
+
+.. function:: user(name, [group])
+
+   :param string name: user name
+   :param string group: group name (optional)
+   :return: boolean
+
+   Drop privileges and start running as given user (and group, if provided).
+
+   .. tip:: Note that you should bind to required network addresses before
+      changing user. At the same time, you should open the cache **AFTER** you
+      change the user (so it remains accessible). A good practice is to divide
+      configuration in two parts:
+
+      .. code-block:: lua
+
+         -- privileged
+         net.listen('127.0.0.1')
+         net.listen('::1')
+         user('knot-resolver', 'netgrp')
+         -- unprivileged
+         cache.size = 100*MB
+
+   Example output:
+
+   .. code-block:: lua
+
+      > user('baduser')
+      invalid user name
+      > user('knot-resolver', 'netgrp')
+      true
+      > user('root')
+      Operation not permitted
+
+Running as root
+^^^^^^^^^^^^^^^
+
+.. warning:: Executing processes as root is generally insecure, as these
+   processes have unconstrained access to the complete system at runtime.
+
+While not recommended, it is also possible to run kresd directly as root.

content/documentation/v5.7.3/_sources/config-no-systemd-processes.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Process management
+==================
+
+There following should be taken into consideration when running without systemd:
+
+* To utilize multiple CPUs, kresd has to be executed as several independent
+  processes.
+* Maintenance daemon(s) have to be executed separately.
+* If a process crashes, it might be useful to restart it.
+* Using some mechanism similar to :ref:`mod-watchdog` might be desirable to
+  recover in case a process becomes unresponsive.
+
+Please note, systemd isn't the only process manager and other solutions exist,
+such as supervisord_. Configuring these is out of the scope of this
+document. Please refer to their respective documentations.
+
+It is also possible to use kresd without any process management at all, which
+may be suitable for some purposes (such as low-traffic local / home network resolver,
+testing, development or debugging).
+
+.. include:: ../utils/cache_gc/README.rst
+
+.. _`supervisord`: http://supervisord.org/

content/documentation/v5.7.3/_sources/config-no-systemd.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _usage-without-systemd:
+
+*********************
+Usage without systemd
+*********************
+
+.. tip:: Our upstream packages use systemd integration, which is the recommended
+   way to run kresd. This section is only relevant if you choose to use kresd
+   without systemd integration.
+
+Knot Resolver is designed to be a single process without the use of threads.
+While the cache is shared, the individual processes are independent.  This
+approach has several benefits, but it also comes with a few downsides, in
+particular:
+
+* Without the use of threads or forking (deprecated, see `#529`_), multiple
+  processes aren't managed in any way by kresd.
+* There is no maintenance thread and these tasks have to be handled by separate
+  daemon(s) (such as :ref:`garbage-collector`).
+
+To offset these these disadvantages without implementing process management in
+kresd (and reinventing the wheel), Knot Resolver provides integration with
+systemd, which is widely used across GNU/Linux distributions.
+
+If your use-case doesn't support systemd (e.g. using macOS, FreeBSD, Docker,
+OpenWrt, Turris), this section describes the differences and things to keep in
+mind when configuring and running kresd without systemd integration.
+
+.. toctree::
+   :maxdepth: 2
+
+   config-no-systemd-processes
+   config-no-systemd-privileges
+
+.. _`#529`: https://gitlab.nic.cz/knot/knot-resolver/issues/529

content/documentation/v5.7.3/_sources/config-overview.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+**********************
+Configuration Overview
+**********************
+
+Configuration file is named ``/etc/knot-resolver/kresd.conf`` and is read when
+you execute Knot Resolver using systemd commands described in section
+:ref:`quickstart-startup`. [#]_
+
+.. _config-syntax:
+
+Syntax
+======
+
+The configuration file syntax allows you to specify different kinds of data:
+
+  - ``group.option = 123456``
+  - ``group.option = "string value"``
+  - ``group.command(123456, "string value")``
+  - ``group.command({ key1 = "value1", key2 = 222, key3 = "third value" })``
+  - ``globalcommand(a_parameter_1, a_parameter_2, a_parameter_3, etc)``
+  - ``-- any text after -- sign is ignored till end of line``
+
+Following **configuration file snippet** starts listening for unencrypted and also encrypted DNS queries on IP address 192.0.2.1, and sets cache size.
+
+.. code-block:: lua
+
+        -- this is a comment: listen for unencrypted queries
+        net.listen('192.0.2.1')
+        -- another comment: listen for queries encrypted using TLS on port 853
+        net.listen('192.0.2.1', 853, { kind = 'tls' })
+        -- 10 MB cache is suitable for a very small deployment
+        cache.size = 10 * MB
+
+.. tip::
+   When copy&pasting examples from this manual please pay close
+   attention to brackets and also line ordering - order of lines matters.
+
+   The configuration language is in fact Lua script, so you can use full power
+   of this programming language. See article
+   `Learn Lua in 15 minutes`_ for a syntax overview.
+
+When you modify configuration file on disk restart resolver process to get
+changes into effect. See chapter :ref:`systemd-zero-downtime-restarts` if even short
+outages are not acceptable for your deployment.
+
+.. [#] If you decide to run binary ``/usr/sbin/kresd`` manually (instead of
+   using systemd) do not forget to specify ``-c`` option with path to
+   configuration file, otherwise ``kresd`` will read file named ``config`` from
+   its current working directory.
+
+Documentation Conventions
+=========================
+
+Besides text configuration file, Knot Resolver also supports interactive and dynamic configuration using scripts or external systems, which is described in chapter :ref:`runtime-cfg`. Through this manual we present examples for both usage types - static configuration in a text file (see above) and also the interactive mode.
+
+The **interactive prompt** is denoted by ``>``, so all examples starting with ``>`` character are transcripts of user (or script) interaction with Knot Resolver and resolver's responses. For example:
+
+.. code-block:: lua
+
+        > -- this is a comment entered into interactive prompt
+        > -- comments have no effect here
+        > -- the next line shows a command entered interactively and its output
+        > log_level()
+        'notice'
+        > -- the previous line without > character is output from log_level() command
+
+Following example demonstrates how to interactively list all currently loaded modules, and includes multi-line output:
+
+.. code-block:: lua
+
+        > modules.list()
+        {
+            'iterate',
+            'validate',
+            'cache',
+            'ta_update',
+            'ta_signal_query',
+            'policy',
+            'priming',
+            'detect_time_skew',
+            'detect_time_jump',
+            'ta_sentinel',
+            'edns_keepalive',
+            'refuse_nord',
+            'watchdog',
+        }
+
+
+Before we dive into configuring features, let us explain modularization basics.
+
+.. include:: ../daemon/bindings/modules.rst
+
+Now you know what configuration file to modify, how to read examples and what modules are so you are ready for a real configuration work!
+
+.. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
+

content/documentation/v5.7.3/_sources/config-performance.rst.txt

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _performance:
+
+**************************
+Performance and resiliency
+**************************
+
+For DNS resolvers, the most important parameter from performance perspective
+is cache hit rate, i.e. percentage of queries answered from resolver's cache.
+Generally the higher cache hit rate the better.
+
+Performance tunning should start with cache :ref:`cache_sizing`
+and :ref:`cache_persistence`.
+
+It is also recommended to run :ref:`systemd-multiple-instances` (even on a
+single machine!) because it allows to utilize multiple CPU threads and
+increases overall resiliency.
+
+Other features described in this section can be used for fine-tunning
+performance and resiliency of the resolver but generally have much smaller
+impact than cache settings and number of instances.
+
+.. toctree::
+   :maxdepth: 1
+
+   daemon-bindings-cache
+   systemd-multiinst
+   modules-predict
+   modules-prefill
+   modules-serve_stale
+   modules-rfc7706
+   modules-priming
+   modules-edns_keepalive
+   daemon-bindings-net_xdpsrv
+