diff options
| -rw-r--r-- | daemon/bindings/cache.rst | 6 | ||||
| -rw-r--r-- | daemon/bindings/net_dns_tweaks.rst | 2 | ||||
| -rw-r--r-- | daemon/scripting.rst | 10 | ||||
| -rw-r--r-- | doc/dev/architecture-manager.rst | 13 | ||||
| -rw-r--r-- | doc/dev/architecture.rst | 4 | ||||
| -rw-r--r-- | doc/dev/build.rst | 2 | ||||
| -rw-r--r-- | doc/dev/config-lua-logging-monitoring.rst | 4 | ||||
| -rw-r--r-- | doc/dev/config-lua-network.rst | 1 | ||||
| -rw-r--r-- | doc/dev/index.rst | 3 | ||||
| -rw-r--r-- | doc/dev/lib.rst | 2 | ||||
| -rw-r--r-- | doc/dev/logging_api.rst | 9 | ||||
| -rw-r--r-- | doc/user/config-forward.rst | 5 | ||||
| -rw-r--r-- | doc/user/config-logging-monitoring.rst | 2 | ||||
| -rw-r--r-- | lib/README.rst | 6 | ||||
| -rw-r--r-- | modules/stats/README.rst | 4 | ||||
| -rw-r--r-- | systemd/multiinst.rst | 4 | ||||
| -rw-r--r-- | tests/README.rst | 12 |
17 files changed, 48 insertions, 41 deletions
diff --git a/daemon/bindings/cache.rst b/daemon/bindings/cache.rst index 36114d22..879bc6e3 100644 --- a/daemon/bindings/cache.rst +++ b/daemon/bindings/cache.rst @@ -51,9 +51,9 @@ to leave some free space for special files, such as locks.: 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`: diff --git a/daemon/bindings/net_dns_tweaks.rst b/daemon/bindings/net_dns_tweaks.rst index 4cfeba64..b1f67139 100644 --- a/daemon/bindings/net_dns_tweaks.rst +++ b/daemon/bindings/net_dns_tweaks.rst @@ -32,4 +32,4 @@ Default values should not be changed except for very special cases. 4096 -- result # 1 1232 -- result # 2 -.. include:: ../modules/workarounds/README.rst +.. include:: ../../modules/workarounds/README.rst diff --git a/daemon/scripting.rst b/daemon/scripting.rst index 742aa955..3861fb42 100644 --- a/daemon/scripting.rst +++ b/daemon/scripting.rst @@ -30,9 +30,9 @@ another program, e.g. a maintenance script. :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 @@ -389,9 +389,9 @@ see the cqueues documentation for more information. Here is an simple example: 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 diff --git a/doc/dev/architecture-manager.rst b/doc/dev/architecture-manager.rst index 1a0381af..4e3371a9 100644 --- a/doc/dev/architecture-manager.rst +++ b/doc/dev/architecture-manager.rst @@ -2,14 +2,11 @@ ``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. @@ -19,7 +16,7 @@ API 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 ================= @@ -36,7 +33,7 @@ Actual manager 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 @@ -49,9 +46,9 @@ Communication with supervisord happens on pretty much all possible levels. We ed 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. diff --git a/doc/dev/architecture.rst b/doc/dev/architecture.rst index ba281f9d..79084e5b 100644 --- a/doc/dev/architecture.rst +++ b/doc/dev/architecture.rst @@ -4,7 +4,7 @@ System architecture 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. @@ -45,4 +45,4 @@ You can learn more about architecture of individual Resolver components in the f architecture-manager architecture-kresd - architecture-gc
\ No newline at end of file + architecture-gc diff --git a/doc/dev/build.rst b/doc/dev/build.rst index 4e2156e0..b6bfd9f4 100644 --- a/doc/dev/build.rst +++ b/doc/dev/build.rst @@ -228,7 +228,7 @@ 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 +.. include:: ../../tests/README.rst .. _build-html-doc: diff --git a/doc/dev/config-lua-logging-monitoring.rst b/doc/dev/config-lua-logging-monitoring.rst index 8a2a25b6..c0b026b3 100644 --- a/doc/dev/config-lua-logging-monitoring.rst +++ b/doc/dev/config-lua-logging-monitoring.rst @@ -22,7 +22,7 @@ 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 +: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`. @@ -97,5 +97,3 @@ Additional monitoring and debugging methods are described below. If none of thes modules-ta_signal_query modules-detect_time_skew modules-detect_time_jump - config-debugging - config-logging-header diff --git a/doc/dev/config-lua-network.rst b/doc/dev/config-lua-network.rst index 8bd67eef..241b67ff 100644 --- a/doc/dev/config-lua-network.rst +++ b/doc/dev/config-lua-network.rst @@ -53,7 +53,6 @@ Following chapters describe basic configuration of how resolver retrieves data f :maxdepth: 2 daemon-bindings-net_client - config-network-forwarding DNS protocol tweaks =================== diff --git a/doc/dev/index.rst b/doc/dev/index.rst index 406c6844..389876f2 100644 --- a/doc/dev/index.rst +++ b/doc/dev/index.rst @@ -36,12 +36,13 @@ Welcome to Knot Resolver's documentation for developers and advanced users! .. 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 diff --git a/doc/dev/lib.rst b/doc/dev/lib.rst index 2378f566..89e29df5 100644 --- a/doc/dev/lib.rst +++ b/doc/dev/lib.rst @@ -73,4 +73,4 @@ Utilities .. _lib_generics: -.. include:: ../lib/generic/README.rst +.. include:: ../../lib/generic/README.rst diff --git a/doc/dev/logging_api.rst b/doc/dev/logging_api.rst new file mode 100644 index 00000000..09b705c8 --- /dev/null +++ b/doc/dev/logging_api.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +Logging API reference +===================== + +.. _config_log_groups: + +.. doxygenfile:: lib/log.h + :project: libkres diff --git a/doc/user/config-forward.rst b/doc/user/config-forward.rst index 051f7119..5e4bf14c 100644 --- a/doc/user/config-forward.rst +++ b/doc/user/config-forward.rst @@ -19,13 +19,12 @@ Forwarding implementation in Knot Resolver has following properties: * 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 diff --git a/doc/user/config-logging-monitoring.rst b/doc/user/config-logging-monitoring.rst index 081fac75..a181f05b 100644 --- a/doc/user/config-logging-monitoring.rst +++ b/doc/user/config-logging-monitoring.rst @@ -34,7 +34,7 @@ E.g. on distributions using systemd-journald use command ``journalctl -eu knot-r .. 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, diff --git a/lib/README.rst b/lib/README.rst index 1c8cf7b2..b631fe7b 100644 --- a/lib/README.rst +++ b/lib/README.rst @@ -30,7 +30,11 @@ The resolution process starts with the functions in :ref:`resolve.c <lib_api_rpl 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. diff --git a/modules/stats/README.rst b/modules/stats/README.rst index 014c9f06..1def925c 100644 --- a/modules/stats/README.rst +++ b/modules/stats/README.rst @@ -209,5 +209,5 @@ and include subrequests. The list maximum size is 5000 entries, make diffs if yo 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 diff --git a/systemd/multiinst.rst b/systemd/multiinst.rst index 00b18029..9884f5b7 100644 --- a/systemd/multiinst.rst +++ b/systemd/multiinst.rst @@ -5,8 +5,8 @@ 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. diff --git a/tests/README.rst b/tests/README.rst index 69393dcc..37867b38 100644 --- a/tests/README.rst +++ b/tests/README.rst @@ -1,13 +1,13 @@ .. 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). @@ -18,7 +18,7 @@ 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, @@ -30,7 +30,7 @@ kresd first. $ 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. @@ -46,7 +46,7 @@ the build dir). $ 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. @@ -82,7 +82,7 @@ example TCP, TLS and its connection management. $ meson test -C build_dir --suite pytests Useful meson commands -~~~~~~~~~~~~~~~~~~~~~ +--------------------- It's possible to run only specific test suite or a test. |