Fix cross-references, heading levels, etc.
cache.size = cache.fssize() - 10*MB
-.. note:: The :ref:`garbage-collector` can be used to periodically trim the
- cache. It is enabled and configured by default when running kresd with
- systemd integration.
+.. note:: The `cache garbage collector <../deployment-advanced-no-systemd-processes.html#garbage-collector>`_
+ can be used to periodically trim the cache. It is enabled and configured by
+ default when running kresd with systemd integration.
.. _`cache_persistence`:
4096 -- result # 1
1232 -- result # 2
-.. include:: ../modules/workarounds/README.rst
+.. include:: ../../modules/workarounds/README.rst
:ref:`systemd-multiple-instances`.
When Knot Resolver is started using Systemd (see section
-:ref:`gettingstarted-startup`) it creates a control socket in path
-``/run/knot-resolver/control/$ID``. Connection to the socket can
-be made from command line using e.g. ``socat``:
+`Startup <../gettingstarted-startup.html>`_) it creates a control socket in path
+``/run/knot-resolver/control/$ID``. Connection to the socket can be made from
+command line using e.g. ``socat``:
.. code-block:: bash
end
end)
-.. include:: ../daemon/bindings/event.rst
+.. include:: ../../daemon/bindings/event.rst
-.. include:: ../modules/etcd/README.rst
+.. include:: ../../modules/etcd/README.rst
.. _closures: https://www.lua.org/pil/6.1.html
.. _cqueues: https://25thandclement.com/~william/projects/cqueues.html
``kres-manager``
****************
-.. note::
- This guide is intended for advanced users and developers. You don't have to know and understand any of this to use Knot Resolver.
-
The manager is a component written in Python and a bit of C used for native extension modules. The main goal of the manager is to ensure the system is set up according to a given configuration, provide a user-friendly interface. Performance is only secondary to correctness.
The manager is mostly modelled around config processing pipeline:
-.. image:: ../architecture-config.svg
+.. image:: ../architecture-manager.svg
:width: 100%
:alt: Diagram showing a configuration change request processing pipeline inside of the manager. The request goes first through an API server, then through parsing, validation and normalization steps, then into an actual system manager, which commands supervisord and other system components such as kresd.
The API server is implemented using `aiohttp <https://docs.aiohttp.org/en/stable>`_. This framework provides the application skeleton and manages application runtime. The manager is actually a normal web application with the slight difference that we don't save the data in a database but rather modify state of other processes.
-Code of the API server is located only in a `single source code file <https://gitlab.nic.cz/knot/knot-resolver/-/blob/manager/manager/knot_resolver_manager/server.py>`_. It also contains description of the manager's startup procedure.
+Code of the API server is located only in a `single server.py source code file <https://gitlab.nic.cz/knot/knot-resolver/-/blob/manager/manager/knot_resolver_manager/server.py>`_. It also contains description of the manager's startup procedure.
Config processing
=================
The actual core of the whole application is originally named the manager. It keeps a high-level view of the systems state and performs all necessary operations to change the state to the desired one. In other words, manager is the component handling rolling restarts, config update logic and more.
-The code is contained mainly in a `single source code file <https://gitlab.nic.cz/knot/knot-resolver/-/blob/manager/manager/knot_resolver_manager/kres_manager.py>`_.
+The code is contained mainly in a `single kres_manager.py source code file <https://gitlab.nic.cz/knot/knot-resolver/-/blob/manager/manager/knot_resolver_manager/kres_manager.py>`_.
Interactions with supervisord
First, we `generate supervisord's configuration file <https://gitlab.nic.cz/knot/knot-resolver/-/blob/manager/manager/knot_resolver_manager/kresd_controller/supervisord/supervisord.conf.j2>`_. The configuration file sets stage for further communication by specifying location of the pidfile and API Unix socket. It prepares configuration for subprocesses and most significantly, it loads our custom extensions.
-`The extensions <https://gitlab.nic.cz/knot/knot-resolver/-/tree/manager/manager/knot_resolver_manager/kresd_controller/supervisord/plugin>`_ don't use a lot of code. There are four of them - the simplest one provides a speedier XMLRPC API for starting processes, it removes delays that are not necessary for our usecase. Another one implements systemd's ``sd_notify()`` API for supervisord, so we can track the lifecycle of ``kresd``s more precisely. Another extension changes the way logging works and the last extension monitors the lifecycle of the manager and forwards some signals.
+`The extensions <https://gitlab.nic.cz/knot/knot-resolver/-/tree/manager/manager/knot_resolver_manager/kresd_controller/supervisord/plugin>`_ don't use a lot of code. There are four of them - the simplest one provides a speedier XMLRPC API for starting processes, it removes delays that are not necessary for our usecase. Another one implements systemd's ``sd_notify()`` API for supervisord, so we can track the lifecycle of ``kresd`` instances more precisely. Another extension changes the way logging works and the last extension monitors the lifecycle of the manager and forwards some signals.
.. note::
The extensions mentioned above use monkeypatching to achieve their design goals. We settled for this approach, because supervisord's codebase appears mostly stable. The code we patch has not been changed for years. Other option would be forking supervisord and vendoring it. We decided against that mainly due to packaging complications it would cause with major Linux distributions.
-For executing subprocesses, we don't actually change the configuration file, we only use XMLRPC API and tell supervisord to start already configured programs. For one specific call though, we use our extension instead of the build-in method of starting processes as it is significantly faster.
\ No newline at end of file
+For executing subprocesses, we don't actually change the configuration file, we only use XMLRPC API and tell supervisord to start already configured programs. For one specific call though, we use our extension instead of the build-in method of starting processes as it is significantly faster.
Knot Resolver is split into several components, namely the manager, ``kresd`` and the garbage collector. In addition to these custom components, we also rely on `supervisord <http://supervisord.org/>`_.
-.. image:: architecture-supervisor.svg
+.. image:: ../architecture-schema.svg
:width: 100%
:alt: Diagram showing process tree and contol relationship between Knot Resolver components. Supervisord is a parent to all processes, namely manager, kresd instances and gc. Manager on the other hand controls every other component and what it does.
architecture-manager
architecture-kresd
- architecture-gc
\ No newline at end of file
+ architecture-gc
``CFLAGS``, ``LDFLAGS`` when creating the build directory with ``meson``
command.
-.. include:: ../tests/README.rst
+.. include:: ../../tests/README.rst
.. _build-html-doc:
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
+:ref:`log 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`.
modules-ta_signal_query
modules-detect_time_skew
modules-detect_time_jump
- config-debugging
- config-logging-header
:maxdepth: 2
daemon-bindings-net_client
- config-network-forwarding
DNS protocol tweaks
===================
.. toctree::
:caption: Modules and worker API, Lib
- :name: configuration-lua-chapter
+ :name: modules-api-lib-chapter
:maxdepth: 1
lib
modules_api
worker_api
+ logging_api
.. toctree::
:caption: Architecture
.. _lib_generics:
-.. include:: ../lib/generic/README.rst
+.. include:: ../../lib/generic/README.rst
--- /dev/null
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Logging API reference
+=====================
+
+.. _config_log_groups:
+
+.. doxygenfile:: lib/log.h
+ :project: libkres
* Answers from *upstream* servers are cached.
* Answers from *upstream* servers are locally DNSSEC-validated, unless dnssec is disabled.
* Resolver automatically selects which IP address from given set of IP addresses will be used (based on performance characteristics).
- * :ref:`Forwarding <config-forward>` can use either encrypted or unencrypted DNS protocol.
+ * Forwarding can use either encrypted or unencrypted DNS protocol.
.. 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.
+ In the long-term it is better to migrate data into a legitimate, properly delegated domains which do not suffer from these security problems.
.. code-block:: yaml
.. option:: groups: <list of logging groups>
- Use to turn-on ``debug`` logging for the selected `groups <./dev/config-logging-header.html>`_
+ Use to turn-on ``debug`` logging for the selected `groups <./dev/logging_api.html>`_
regardless of the global log level. Other groups are logged to the log based on the initial level.
.. It is also possible to enable ``debug`` logging level for particular requests,
This is the *driver*. The driver is not meant to know *"how"* the query resolves, but rather *"when"* to execute *"what"*.
-.. image:: ../doc/resolution.png
+..
+ Paths are resolved relative to the document that includes this, so this is
+ kind of a mess. (This is included in `/doc/dev/lib.rst`)
+
+.. image:: ../resolution.png
:align: center
On the other side are *layers*. They are responsible for dissecting the packets and informing the driver about the results. For example, a *produce* layer generates query, a *consume* layer validates answer.
Clear the list of most frequent iterative queries.
-.. include:: ../modules/graphite/README.rst
-.. include:: ../modules/http/prometheus.rst
+.. include:: ../../modules/graphite/README.rst
+.. include:: ../../modules/http/prometheus.rst
Multiple instances
==================
-.. note:: This section describes the usage of kresd when running under systemd.
- For other uses, please refer to :ref:`deployment-no-systemd`.
+.. note:: This section describes the usage of kresd when running under systemd
+ without Manager.
Knot Resolver can utilize multiple CPUs running in multiple independent instances (processes), where each process utilizes at most single CPU core on your machine. If your machine handles a lot of DNS traffic run multiple instances.
.. SPDX-License-Identifier: GPL-3.0-or-later
Tests
------
+=====
The following is a non-comprehensitve lists of various tests that can be found
in this repo. These can be enabled by the build system.
Unit tests
-~~~~~~~~~~
+----------
The unit tests depend on cmocka_ and can easily be executed after compilation.
They are enabled by default (if ``cmocka`` is found).
$ meson test -C build_dir --suite unit
Postinstall tests
-~~~~~~~~~~~~~~~~~
+-----------------
There following tests require a working installation of kresd. The
binary ``kresd`` found in ``$PATH`` will be tested. When testing through meson,
$ ninja install -C build_dir
Config tests
-~~~~~~~~~~~~
+------------
Config tests utilize the kresd's lua config file to execute arbitrary tests,
typically testing various modules, their API etc.
$ meson test -C build_dir --suite config
Extra tests
-~~~~~~~~~~~
+-----------
The extra tests require a large set of additional dependencies and executing
them outside of upstream development is probably redundant.
$ meson test -C build_dir --suite pytests
Useful meson commands
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
It's possible to run only specific test suite or a test.
projects / thirdparty / knot-resolver.git / commitdiff
