diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 15:26:00 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 15:26:00 +0000 |
commit | 830407e88f9d40d954356c3754f2647f91d5c06a (patch) | |
tree | d6a0ece6feea91f3c656166dbaa884ef8a29740e /systemd | |
parent | Initial commit. (diff) | |
download | knot-resolver-upstream.tar.xz knot-resolver-upstream.zip |
Adding upstream version 5.6.0.upstream/5.6.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'systemd')
-rw-r--r-- | systemd/README.rst | 11 | ||||
-rw-r--r-- | systemd/kres-cache-gc.service.in | 19 | ||||
-rw-r--r-- | systemd/kresd.systemd.7.in | 100 | ||||
-rw-r--r-- | systemd/kresd.target | 9 | ||||
-rw-r--r-- | systemd/kresd@.service.in | 30 | ||||
-rw-r--r-- | systemd/meson.build | 66 | ||||
-rw-r--r-- | systemd/multiinst.rst | 99 | ||||
-rw-r--r-- | systemd/sysusers.d/knot-resolver.conf.in | 5 | ||||
-rw-r--r-- | systemd/tmpfiles.d/knot-resolver.conf.in | 6 |
9 files changed, 345 insertions, 0 deletions
diff --git a/systemd/README.rst b/systemd/README.rst new file mode 100644 index 0000000..1d10a1f --- /dev/null +++ b/systemd/README.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +Notes for packagers +------------------- + +* kresd.target should be enabled by default by linking it to systemd lib/ + directory. Instances of kresd@.service are then added manually to + kresd.target when the user enables them. +* Distributions using systemd-sysv-generator should mask kresd.service to + be consistent with other distributions. Any use of kresd.service instead of + kresd@N.service is discouraged to avoid confusing the users. diff --git a/systemd/kres-cache-gc.service.in b/systemd/kres-cache-gc.service.in new file mode 100644 index 0000000..6e39fcc --- /dev/null +++ b/systemd/kres-cache-gc.service.in @@ -0,0 +1,19 @@ +# SPDX-License-Identifier: CC0-1.0 +[Unit] +Description=Knot Resolver Garbage Collector daemon +Documentation=man:kresd.systemd(7) +Documentation=man:kresd(8) + +[Service] +Type=simple +ExecStart=@sbin_dir@/kres-cache-gc -c @systemd_cache_dir@ -d 1000 +User=@user@ +Group=@group@ +Restart=on-failure +RestartSec=30 +StartLimitInterval=400 +StartLimitBurst=10 +Slice=system-kresd.slice + +[Install] +WantedBy=kresd.target diff --git a/systemd/kresd.systemd.7.in b/systemd/kresd.systemd.7.in new file mode 100644 index 0000000..a602b8e --- /dev/null +++ b/systemd/kresd.systemd.7.in @@ -0,0 +1,100 @@ +.TH "kresd.systemd" "7" "@date@" "CZ.NIC" "Knot Resolver @version@ Systemd Units" +.\" +.\" kresd.systemd.7 -- man page for systemd units for kresd +.\" +.\" Copyright (c) CZ.NIC. All rights reserved. +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.\" +.SH "NAME" +kresd.systemd +\- managing Knot Resolver @version@ through systemd. + +.SH "SYNOPSIS" +.nf +kresd@.service +kresd.target +system-kresd.slice +.fi + +.SH "DESCRIPTION" +.P +This manual page describes how to manage \fBkresd\fR using \fBsystemd\fR +units. + +.B QUICKSTART + +.nf +.RS 4n +\fBsystemctl start kresd@1\fR - single instance of kresd, responding on localhost +.RE +.fi + +.B CONCURRENT DAEMONS + +\fBkresd\fR daemon can be executed in multiple independent processes, which are +managed with \fBsystemd\fR via systemd templates (see \fBsystemd.unit\fR(5)). +Each \fBsystemd\fR service instance of \fBkresd\fR (\fIkresd@.service\fR) +represents a single, independent kresd process. + +If you have more than one CPU core available, a single running \fBkresd\fR +daemon will only be able to make use of one core at a time, leaving the other +cores idle. If you want \fBkresd\fR to take advantage of all available cores, +while sharing both cache and sockets, you should enable and start as many +instances of the \fBkresd@.service\fR as you have cores. Typically, each +instance is just named \fIkresd@\fBN\fI.service\fR, where \fIN\fR is a decimal +number. For example, to enable and start 3 concurrent daemons: + +.nf +.RS 4n +.B systemctl enable --now kresd@1.service kresd@2.service kresd@3.service +.RE +.fi + +The systemd-managed \fBkresd\fR service set is grouped in the +\fIsystem-kresd.slice\fR slice. The slice includes all running daemons +(instances of \fIkresd@.service\fR). + +.SH "EXAMPLES" + +To start a single kresd instance and enable it at boot: +.nf +.RS 4n +.B systemctl enable --now kresd@1.service +.RE +.fi + +To restart (or stop) all running instances, you can use a glob expression. +Please note that glob can't be used to start or enable instances. +.nf +.RS 4n +.B systemctl restart 'kresd@*' +.RE +.fi + +Bash users can also use Brace Expansion to enable or start multiple instances, +instead of listing them manually. +.nf +.RS 4n +.B systemctl enable --now kresd@{1..4}.service +.RE +.fi + +To start all enabled kresd daemons, you can also use the provided \fIkresd.target\fR: +.nf +.RS 4n +.B systemctl start kresd.target +.RE +.fi + +.RE + +.SH "SEE ALSO" +\fIkresd(8)\fR, +\fIsystemd.unit(5)\fR, +\fIhttps://knot-resolver.readthedocs.io/en/v@version@/\fR + +.SH "AUTHORS" +.B kresd +developers are mentioned in the AUTHORS file in the distribution. diff --git a/systemd/kresd.target b/systemd/kresd.target new file mode 100644 index 0000000..5a2d786 --- /dev/null +++ b/systemd/kresd.target @@ -0,0 +1,9 @@ +# SPDX-License-Identifier: CC0-1.0 +[Unit] +Description=Knot Resolver daemons +Documentation=man:kresd.systemd(7) +Documentation=man:kresd(8) +After=network-online.target + +[Install] +WantedBy=multi-user.target diff --git a/systemd/kresd@.service.in b/systemd/kresd@.service.in new file mode 100644 index 0000000..adb303a --- /dev/null +++ b/systemd/kresd@.service.in @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: CC0-1.0 +[Unit] +Description=Knot Resolver daemon +Documentation=man:kresd.systemd(7) +Documentation=man:kresd(8) +Wants=kres-cache-gc.service +Before=kres-cache-gc.service +Wants=network-online.target +After=network-online.target +Before=nss-lookup.target +Wants=nss-lookup.target + +[Service] +Type=notify +Environment="SYSTEMD_INSTANCE=%i" +WorkingDirectory=@systemd_work_dir@ +ExecStart=@sbin_dir@/kresd -c @lib_dir@/distro-preconfig.lua -c @etc_dir@/kresd.conf -n +ExecStopPost=/usr/bin/env rm -f "@run_dir@/control/%i" +User=@user@ +Group=@group@ +CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_SETPCAP +AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_SETPCAP +TimeoutStopSec=10s +WatchdogSec=10s +Restart=on-abnormal +LimitNOFILE=524288 +Slice=system-kresd.slice + +[Install] +WantedBy=kresd.target diff --git a/systemd/meson.build b/systemd/meson.build new file mode 100644 index 0000000..6ca0bac --- /dev/null +++ b/systemd/meson.build @@ -0,0 +1,66 @@ +# systemd +# SPDX-License-Identifier: GPL-3.0-or-later + +## configuration +systemd_config = configuration_data() +systemd_config.set('user', user) +systemd_config.set('group', group) +systemd_config.set('systemd_work_dir', systemd_work_dir) +systemd_config.set('systemd_cache_dir', systemd_cache_dir) +systemd_config.set('sbin_dir', sbin_dir) +systemd_config.set('etc_dir', etc_dir) +systemd_config.set('run_dir', run_dir) +systemd_config.set('lib_dir', lib_dir) + +if systemd_files == 'enabled' + ## unit files + kresd_service = configure_file( + input: 'kresd@.service.in', + output: 'kresd@.service', + configuration: systemd_config, + install_dir: systemd_unit_dir, + ) + kres_cache_gc_service = configure_file( + input: 'kres-cache-gc.service.in', + output: 'kres-cache-gc.service', + configuration: systemd_config, + install_dir: systemd_unit_dir, + ) + install_data( + sources: 'kresd.target', + install_dir: systemd_unit_dir, + ) + + ## man page + kresd_systemd_man = configure_file( + input: 'kresd.systemd.7.in', + output: 'kresd.systemd.7', + configuration: man_config, + ) + install_man(kresd_systemd_man) + + ## tmpfiles + tmpfiles = configure_file( + input: 'tmpfiles.d/knot-resolver.conf.in', + output: 'knot-resolver.tmpfiles', + configuration: systemd_config, + ) + install_data( + tmpfiles, + rename: ['knot-resolver.conf'], + install_dir: systemd_tmpfiles_dir, + ) + + ## sysusers + sysusers = configure_file( + input: 'sysusers.d/knot-resolver.conf.in', + output: 'knot-resolver.sysusers', + configuration: systemd_config, + ) + install_data( + sysusers, + rename: ['knot-resolver.conf'], + install_dir: systemd_sysusers_dir, + ) + +endif diff --git a/systemd/multiinst.rst b/systemd/multiinst.rst new file mode 100644 index 0000000..2a5c63c --- /dev/null +++ b/systemd/multiinst.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +.. _systemd-multiple-instances: + +Multiple instances +================== + +.. note:: This section describes the usage of kresd when running under systemd. + For other uses, please refer to :ref:`usage-without-systemd`. + +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. + +All instances typically share the same configuration and cache, and incoming queries are automatically distributed by operating system among all instances. + +Advantage of using multiple instances is that a problem in a single instance will not affect others, so a single instance crash will not bring whole DNS resolver service down. + +.. tip:: For maximum performance, there should be as many kresd processes as + there are available CPU threads. + +To run multiple instances, use a different identifier after `@` sign 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 this: + +.. code-block:: bash + + $ systemctl start kresd@{1..4}.service + +For more details see ``kresd.systemd(7)``. + + +.. _systemd-zero-downtime-restarts: + +Zero-downtime restarts +---------------------- +Resolver restart normally takes just milliseconds and cache content is persistent to avoid performance drop +after restart. If you want real zero-downtime restarts use `multiple instances`_ and do rolling +restart, i.e. restart only one resolver process at a time. + +On a system with 4 instances run these commands sequentially: + +.. code-block:: bash + + $ systemctl restart kresd@1.service + $ systemctl restart kresd@2.service + $ systemctl restart kresd@3.service + $ systemctl restart kresd@4.service + +At any given time only a single instance is stopped and restarted so remaining three instances continue to service clients. + + +.. _instance-specific-configuration: + +Instance-specific configuration +------------------------------- + +Instances can use arbitrary identifiers for the instances, for example we can name instances like `dns1`, `tls` and so on. + +.. 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 with per-instance configuration: + +.. 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 = 'doh2' }) + else + panic("Use kresd@dns*, kresd@tls* or kresd@doh* instance names") + end diff --git a/systemd/sysusers.d/knot-resolver.conf.in b/systemd/sysusers.d/knot-resolver.conf.in new file mode 100644 index 0000000..ea66e27 --- /dev/null +++ b/systemd/sysusers.d/knot-resolver.conf.in @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC0-1.0 +# sysusers.d(5) file for knot-resolver (kresd) +#Type Name ID GECOS Home directory Shell +u @user@ - "Knot Resolver Daemon User" +g @group@ diff --git a/systemd/tmpfiles.d/knot-resolver.conf.in b/systemd/tmpfiles.d/knot-resolver.conf.in new file mode 100644 index 0000000..204088d --- /dev/null +++ b/systemd/tmpfiles.d/knot-resolver.conf.in @@ -0,0 +1,6 @@ +# SPDX-License-Identifier: CC0-1.0 +# tmpfiles.d(5) directories for knot-resolver (kresd) +#Type Path Mode UID GID Age Argument + d @run_dir@ 0750 @user@ @group@ - - + d @systemd_work_dir@ 0750 @user@ @group@ - - + d @systemd_cache_dir@ 0750 @user@ @group@ - - |