9 files changed, 343 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..e92613e
--- /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) 2018, 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..f43fb77
--- /dev/null
+++ b/systemd/kresd@.service.in
@@ -0,0 +1,28 @@
+# 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
+
+[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..bcf4cb2
--- /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 incomming 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 miliseconds 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@       -   -