From a9010bbeee3fdd29b6e2ba48dc9c06049fb46057 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ale=C5=A1=20Mr=C3=A1zek?= Date: Wed, 20 Sep 2023 15:19:48 +0200 Subject: [PATCH 1/2] doc/upgrading-to-6.rst: guide improvements Lua config moved to developers chapter as internal Lua config. --- doc/config-lua.rst | 11 ----- doc/config-overview.rst | 2 + doc/index.rst | 3 +- doc/internal-lua-config.rst | 18 ++++++++ doc/upgrading-to-6.rst | 89 ++++++++++++++++++++++++++++++------- 5 files changed, 96 insertions(+), 27 deletions(-) create mode 100644 doc/internal-lua-config.rst diff --git a/doc/config-lua.rst b/doc/config-lua.rst index d299fc191..bc1eeefd4 100644 --- a/doc/config-lua.rst +++ b/doc/config-lua.rst @@ -59,14 +59,3 @@ In the declarative configuration there is a ``lua`` section where you can insert .. note:: The script is applied after the declarative configuration, so it can change the configuration defined in it. - -.. toctree:: - :maxdepth: 2 - - config-lua-overview - config-lua-network - config-lua-performance - config-lua-policy - config-lua-logging-monitoring - config-lua-dnssec - config-lua-experimental diff --git a/doc/config-overview.rst b/doc/config-overview.rst index a037527da..15cb9f629 100644 --- a/doc/config-overview.rst +++ b/doc/config-overview.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-3.0-or-later +.. _config-overview: + ********************** Configuration Overview ********************** diff --git a/doc/index.rst b/doc/index.rst index f879a9673..15ecf9120 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -8,7 +8,7 @@ Welcome to Knot Resolver's documentation! Knot Resolver is an open-source implementation of a caching validating DNS resolver. Modular architecture keeps the core tiny and efficient, and it also provides a state-machine like API for extensions. -If you are a new user, please start with chapter for :ref:`getting started `. +If you are completely a new user or new to version 6, please start with chapters for :ref:`getting started ` and :ref:`upgrading guide `. .. toctree:: :caption: Getting Started @@ -67,6 +67,7 @@ If you are a new user, please start with chapter for :ref:`getting started ` in YAML language that can be validated before running +* :ref:`manager-api` to change configuration on the fly without downtime +* new :ref:`manager-client` to help with configuration validation and more -Now, you might be worried about the future of ``kresd``. No worries, you can use ``kresd`` directly the same way you did before, nothing changes there right now. However, in the long run, we might make breaking changes in the way ``kresd`` is configured and using it directly is from now on considered advanced. +Since version 6, Knot Resolver uses the new systemd integration ``knot-resolver.service`` instead of ``kresd@.service``. +So you can control the resolver using this systemd service. -With the release of version 6, there is a new way to configure and control your running ``kresd`` instances -so that you don't have to configure multiple systemd services. The new Knot Resolver Manager handles it for you. -In the table below, you can find comparison of how things were done before and how they can be done now. +.. code-block:: bash + $ systemctl start knot-resolver # you can also use: stop, restart, reload or enable/disable -Command rosetta -=============== +There is no need for managing multiple instances of ``kresd@.service`` like before version 6. +However, ``kresd`` processes still run in the background as separate workers and are managed by new process ``knot-resolver-manager``. + +Number of ``kresd`` workers can be configured directly in the new declarative configuration file. +Knot Resolver's new configuration is by default located in ``/etc/knot-resolver/config.yaml``. + +.. code-block:: yaml + + # /etc/knot-resolver/config.yaml + + workers: 4 + +See more in :ref:`multiple workers ` documentation. + +.. note:: + + You might be worried about the future of ``kresd``. + No worries, you can use ``kresd`` directly the same way you did before, nothing changes there right now. + However, in the long run, we can make major changes to the way ``kresd`` is configured and using it directly is considered advanced from now on. + +Configuration +============= + +Knot Resolver is able to run without any additional configuration, that is, configuration file ``/etc/knot-resolver/config.yaml`` is empty. +The resolver then listens on localhost with standard unencrypted DNS protocol port 53. + +To write a configuration you can start with :ref:`getting started chapter for configuration `. + +If you need to rewrite the old Lua configuration to the new declarative one, +it's a good idea to find the option you want to convert in the :ref:`internal Lua configuration `, +and the equivalent option will very likely be in the :ref:`new declarative configuration ` documentation in a similar place. +The documentation structure is basically the same. +Otherwise, you will have to search for the option in the documentation separately. + +If you have some custom Lua code in your configuration, you can use it in :ref:`lua section ` of declarativ configuration. +However, it has some limitations and we cannot guarantee 100% functionality. +For example, a configuration based on the systemd instance name will not work. + +Reconfiguration +--------------- + +To load the modified configuration without, just use ``reload`` and all running workers should be reconfigured without the resolver downtime. +This was not possible before version 6. It was necessary to manually restart all running ``kresd@`` instances. + +.. code-block:: bash + + $ systemctl reload knot-resolver + +It is also possible to use :ref:`manager-api` and :ref:`manager-client` for runtime reconfiguration. + +Some configuration changes are not safe to load at runtime and the resolver needs to be fully restarted. +You should get a relevant error message if this happens during the resolver reload process. + +.. code-block:: bash + + $ systemctl restart knot-resolver + +Useful commands rosetta +======================= In the table below, you can compare the way Knot Resolver was used before and how it can be used now. @@ -33,7 +92,7 @@ start resolver with 4 worker processes set ``/workers`` to 4 in the config rolling restart after updating config ``systemctl reload knot-resolver`` (or use API or ``kresctl``) manually restart individual ``kresd@`` services one by one open logs of all instances ``journalctl -u knot-resolver`` ``journalctl -u system-kresd.slice`` open log of a single kresd instances ``journalctl -u knot-resolver _PID=xxx`` ``journalctl -u kresd@1`` -updating config programatically use HTTP API or ``kresctl`` command write a custom tool to generate new config and restart ``kresd``'s +updating config programmatically use HTTP API or ``kresctl`` command write a custom tool to generate new config and restart ``kresd``'s handling errors during config changes HTTP API just reports error, resolver keeps running with previous config custom tools for every user validate new config ``kresctl validate path/to/new/config.yaml`` (not fully bullet proof), then try to run it run ``kresd`` with the config and see if it fails look at the Lua config ``kresctl convert path/to/new/config.yaml`` ``cat /path/to/config.conf`` From efac43e6f0f59dc40ecc353f23e8a20bcaa89965 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ale=C5=A1=20Mr=C3=A1zek?= Date: Wed, 20 Sep 2023 15:21:41 +0200 Subject: [PATCH 2/2] doc/upgrading.rst: better reference upgrading-to-6 --- doc/upgrading-to-6.rst | 6 +++--- doc/upgrading.rst | 5 +++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/upgrading-to-6.rst b/doc/upgrading-to-6.rst index 7f2ce8d10..f8247d031 100644 --- a/doc/upgrading-to-6.rst +++ b/doc/upgrading-to-6.rst @@ -24,7 +24,7 @@ So you can control the resolver using this systemd service. There is no need for managing multiple instances of ``kresd@.service`` like before version 6. However, ``kresd`` processes still run in the background as separate workers and are managed by new process ``knot-resolver-manager``. -Number of ``kresd`` workers can be configured directly in the new declarative configuration file. +The number of ``kresd`` workers can be configured directly in the new declarative configuration file. Knot Resolver's new configuration is by default located in ``/etc/knot-resolver/config.yaml``. .. code-block:: yaml @@ -55,14 +55,14 @@ and the equivalent option will very likely be in the :ref:`new declarative confi The documentation structure is basically the same. Otherwise, you will have to search for the option in the documentation separately. -If you have some custom Lua code in your configuration, you can use it in :ref:`lua section ` of declarativ configuration. +If you have some custom Lua code in your configuration, you can use it in :ref:`lua section ` of declarative configuration. However, it has some limitations and we cannot guarantee 100% functionality. For example, a configuration based on the systemd instance name will not work. Reconfiguration --------------- -To load the modified configuration without, just use ``reload`` and all running workers should be reconfigured without the resolver downtime. +To load the modified configuration, just use ``reload`` and all running workers should be reconfigured without the resolver downtime. This was not possible before version 6. It was necessary to manually restart all running ``kresd@`` instances. .. code-block:: bash diff --git a/doc/upgrading.rst b/doc/upgrading.rst index 4aa409c6e..a2d721780 100644 --- a/doc/upgrading.rst +++ b/doc/upgrading.rst @@ -29,10 +29,11 @@ newer versions when they are released. .. _`supervisord`: http://supervisord.org/ -5.x to 6.0 +5.x to 6.x ========== -* `detailed upgrade guide ` +* see the more detailed guide for `upgrading to version 6.x ` + 5.4 to 5.5 ==========