From: Aleš Mrázek Date: Wed, 20 Sep 2023 13:19:48 +0000 (+0200) Subject: doc/upgrading-to-6.rst: guide improvements X-Git-Tag: v6.0.5~19^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a9010bbeee3fdd29b6e2ba48dc9c06049fb46057;p=thirdparty%2Fknot-resolver.git doc/upgrading-to-6.rst: guide improvements Lua config moved to developers chapter as internal Lua config. --- 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``