From 86ac4f591b27a87964bc8c7a31d92553156e3fe5 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Oto=20=C5=A0=C5=A5=C3=A1va?= Date: Fri, 15 Mar 2024 14:24:29 +0100 Subject: [PATCH] doc: various fixes Fix cross-references, heading levels, etc. --- daemon/bindings/cache.rst | 6 +++--- daemon/bindings/net_dns_tweaks.rst | 2 +- daemon/scripting.rst | 10 +++++----- doc/dev/architecture-manager.rst | 13 +++++-------- doc/dev/architecture.rst | 4 ++-- doc/dev/build.rst | 2 +- doc/dev/config-lua-logging-monitoring.rst | 4 +--- doc/dev/config-lua-network.rst | 1 - doc/dev/index.rst | 3 ++- doc/dev/lib.rst | 2 +- doc/dev/logging_api.rst | 9 +++++++++ doc/user/config-forward.rst | 5 ++--- doc/user/config-logging-monitoring.rst | 2 +- lib/README.rst | 6 +++++- modules/stats/README.rst | 4 ++-- systemd/multiinst.rst | 4 ++-- tests/README.rst | 12 ++++++------ 17 files changed, 48 insertions(+), 41 deletions(-) create mode 100644 doc/dev/logging_api.rst diff --git a/daemon/bindings/cache.rst b/daemon/bindings/cache.rst index 36114d226..879bc6e32 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 4cfeba64d..b1f67139f 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 742aa955e..3861fb422 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 1a0381af4..4e3371a92 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 `_. 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 `_. 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 `_. 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 `_. +The code is contained mainly in a `single kres_manager.py source code file `_. 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 `_. 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 `_ 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 `_ 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 ba281f9d3..79084e5b2 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 `_. -.. 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 4e2156e08..b6bfd9f43 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 8a2a25b65..c0b026b33 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 `. All groups +:ref:`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 8bd67eefb..241b67ff7 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 406c68441..389876f28 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 2378f5668..89e29df56 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 000000000..09b705c8b --- /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 051f7119c..5e4bf14c0 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 ` 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 081fac75b..a181f05ba 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: - 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 1c8cf7b22..b631fe7b9 100644 --- a/lib/README.rst +++ b/lib/README.rst @@ -30,7 +30,11 @@ The resolution process starts with the functions in :ref:`resolve.c