From: Tomas Krizek Date: Mon, 2 Dec 2019 14:57:00 +0000 (+0100) Subject: doc/operators-guide: multiple instances X-Git-Tag: v5.0.0~8^2~49 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=10d02a286a4fc71d1b84e66aed00d157db5a41c4;p=thirdparty%2Fknot-resolver.git doc/operators-guide: multiple instances - rename tuning guide to operator's guide - refactor multiple instances section - add instance-specific configuration section with examples --- diff --git a/doc/index.rst b/doc/index.rst index f84a7a0bf..a65e715d7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -33,7 +33,7 @@ and it provides a state-machine like API for extensions. :maxdepth: 2 build - tuning + operators-guide .. toctree:: :caption: Developers diff --git a/doc/operators-guide.rst b/doc/operators-guide.rst new file mode 100644 index 000000000..751b789f2 --- /dev/null +++ b/doc/operators-guide.rst @@ -0,0 +1,92 @@ +.. _operator-guide: + +**************** +Operator's Guide +**************** + +The out-of-the box configuration of the upstream Knot Resolver packages is +intended for personal or small-scale use. Any deployment with traffic over 100 +queries per second will likely benefit from the recommendations in this guide. + +Examples in this guide assume systemd is used as a supervisor. However, the +same logic applies for other supervisors (e.g. supervisord_) or when running +kresd without any supervisor. + + +Multiple instances +================== + +The resolver can run in multiple independent processes. All of them can share +the same socket (utilizing ``SO_REUSEPORT``) and cache. + +.. tip:: For maximum performance, there should be as many kresd processes as + there are available CPU threads. + +To run multiple daemons, use a different identifier for each instance, for +example: + +.. code-block:: bash + + $ systemctl start kresd@1.service + $ systemctl start kresd@2.service + $ systemctl start kresd@3.service + $ systemctl start kresd@4.service + +With the use of brace expansion in bash, the equivalent command looks like: + +.. code-block:: bash + + $ systemctl start kresd@{1..4}.service + +For more details, see ``kresd.systemd(7)``. + +.. note:: When using multiple process, it is also possible to do a rolling + restart with zero downtime of the service. This can be done by restarting + only a subset of the processes at a time. + + +.. _instance-specific-configuration: + +Instance-specific configuration +------------------------------- + +It is possible to use arbitraty identifiers for the instances. + +.. code-block:: bash + + $ systemctl start kresd@dns1 + $ systemctl start kresd@dns2 + $ systemctl start kresd@tls + $ systemctl start kresd@doh + +The instance name is subsequently exposed to kresd via the environment variable +``SYSTEMD_INSTANCE``. This can be used to tell the instances apart, e.g. when +using the :ref:`mod-nsid` module. + +.. code-block:: lua + + local systemd_instance = os.getenv("SYSTEMD_INSTANCE") + + modules.load('nsid') + nsid.name(systemd_instance) + +More arcane set-ups are also possible. The following example isolates the +individual services for classic DNS, DoT and DoH from each other. + +.. code-block:: lua + + local systemd_instance = os.getenv("SYSTEMD_INSTANCE") + + if string.match(systemd_instance, '^dns') then + net.listen('127.0.0.1', 53, { kind = 'dns' }) + elseif string.match(systemd_instance, '^tls') then + net.listen('127.0.0.1', 853, { kind = 'tls' }) + elseif string.match(systemd_instance, '^doh') then + net.listen('127.0.0.1', 443, { kind = 'doh' }) + else + panic("Use kresd@dns*, kresd@tls* or kresd@doh* instance names") + end + + + +.. _`supervisord`: http://supervisord.org/ diff --git a/doc/tuning.rst b/doc/tuning.rst deleted file mode 100644 index eb60da9e2..000000000 --- a/doc/tuning.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _tuning: - -************************ -Performance Tuning Guide -************************ - -The out-of-the box configuration of the upstream Knot Resolver packages is -intended for personal or small-scale use. Any deployments with traffic over 100 -queries per second will likely benefit from the recommendations in this guide. - - -Utilizing multiple CPUs -======================= - -The server can run in multiple independent processes, all sharing the same socket and cache. These processes can be started or stopped during runtime based on the load. - -**Using systemd** - -To run multiple daemons using systemd, use a different numeric identifier for -the instance, for example: - -.. code-block:: bash - - $ systemctl start kresd@1.service - $ systemctl start kresd@2.service - $ systemctl start kresd@3.service - $ systemctl start kresd@4.service - -With the use of brace expansion, the equivalent command looks like: - -.. code-block:: bash - - $ systemctl start kresd@{1..4}.service - -For more details, see ``kresd.systemd(7)``. - -**Daemon only** - -.. code-block:: bash - - $ kresd -f 4 rundir > kresd.log & - $ kresd -f 2 rundir > kresd_2.log & # Extra instances - $ pstree $$ -g - bash(3533)─┬─kresd(19212)─┬─kresd(19212) - │ ├─kresd(19212) - │ └─kresd(19212) - ├─kresd(19399)───kresd(19399) - └─pstree(19411) - $ kill 19399 # Kill group 2, former will continue to run - bash(3533)─┬─kresd(19212)─┬─kresd(19212) - │ ├─kresd(19212) - │ └─kresd(19212) - └─pstree(19460) - -.. _daemon-reuseport: - -.. note:: On recent Linux supporting ``SO_REUSEPORT`` (since 3.9, backported to RHEL 2.6.32) it is also able to bind to the same endpoint and distribute the load between the forked processes. If your OS doesn't support it, use only one daemon process. - diff --git a/modules/nsid/README.rst b/modules/nsid/README.rst index ed052c9ac..3ac4c00b4 100644 --- a/modules/nsid/README.rst +++ b/modules/nsid/README.rst @@ -21,6 +21,9 @@ NSID value can be configured in the resolver's configuration file: modules.load('nsid') nsid.name('instance 1') +.. tip:: When dealing with multiple kresd instances managed with + systemd, see :ref:`instance-specific-configuration`. + You can also obtain configured NSID value: .. code-block:: lua