10 files changed, 367 insertions, 0 deletions
diff --git a/distro/common/systemd/README.md b/distro/common/systemd/README.md
new file mode 100644
index 0000000..433f92f
--- /dev/null
+++ b/distro/common/systemd/README.md
@@ -0,0 +1,31 @@
+Running Knot Resolver under systemd (or equivalent) socket activation
+=====================================================================
+
+You can use the files in this directory to run kresd under supervision
+by systemd (or any supervisor that provides equivalent file descriptor
+initialization via the interface supported by
+sd_listen_fds_with_names(3)).
+
+Usage and Configuration
+-----------------------
+
+See kresd.systemd(7) for details.
+
+Compatibility with older systemd
+--------------------------------
+
+If you're using systemd prior to version 227, use the systemd-compat.conf
+drop-in file to use manual activation. In this case, socket files shouldn't
+be packaged, because they won't be used.
+
+Notes
+-----
+
+*  If you're using the upstream systemd unit files, don't forget to also include
+   kresd.systemd.7 manual page in the package.
+*  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.
+*  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.
diff --git a/distro/common/systemd/drop-in/listen-tls.conf b/distro/common/systemd/drop-in/listen-tls.conf
new file mode 100644
index 0000000..6c798f0
--- /dev/null
+++ b/distro/common/systemd/drop-in/listen-tls.conf
@@ -0,0 +1,7 @@
+# /etc/systemd/system/kresd-tls.socket.d/override.conf
+
+# Configure which interfaces should kresd listen on.
+# ListenStream can be added multiple times.
+
+[Socket]
+ListenStream=192.0.2.115:853
diff --git a/distro/common/systemd/drop-in/listen-udp-tcp.conf b/distro/common/systemd/drop-in/listen-udp-tcp.conf
new file mode 100644
index 0000000..480767a
--- /dev/null
+++ b/distro/common/systemd/drop-in/listen-udp-tcp.conf
@@ -0,0 +1,8 @@
+# /etc/systemd/system/kresd.socket.d/override.conf
+
+# Configure which interfaces should kresd listen on.
+# ListenDatagram and ListenStream can be added multiple times.
+
+[Socket]
+ListenDatagram=192.0.2.115:53
+ListenStream=192.0.2.115:53
diff --git a/distro/common/systemd/drop-in/systemd-compat.conf b/distro/common/systemd/drop-in/systemd-compat.conf
new file mode 100644
index 0000000..d251c41
--- /dev/null
+++ b/distro/common/systemd/drop-in/systemd-compat.conf
@@ -0,0 +1,17 @@
+# /usr/lib/systemd/system/kresd@.service.d/override.conf
+
+# If systemd.227+ isn't available (e.g. CentOS 7), socket activation can't be used
+# and the following modifications are required to use the service with
+# manual activation.
+
+# CAP_NET_BIND_SERVICE is necessary to be able to bind to a well-known port
+# as an unprivilidged user.
+
+# Explicit --forks=1 turns off interactive mode.
+
+[Service]
+Type=simple
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+ExecStart=
+ExecStart=/usr/sbin/kresd --config=/etc/knot-resolver/kresd.conf --forks=1
+Sockets=
diff --git a/distro/common/systemd/kresd-control@.socket b/distro/common/systemd/kresd-control@.socket
new file mode 100644
index 0000000..6937436
--- /dev/null
+++ b/distro/common/systemd/kresd-control@.socket
@@ -0,0 +1,16 @@
+[Unit]
+Description=Knot Resolver control socket
+Documentation=man:kresd.systemd(7)
+Documentation=man:kresd(8)
+Before=sockets.target
+PartOf=kresd@%i.service
+
+[Socket]
+Service=kresd@%i.service
+ListenStream=/run/knot-resolver/control@%i
+FileDescriptorName=control
+SocketMode=0660
+Slice=system-kresd.slice
+
+[Install]
+WantedBy=sockets.target
diff --git a/distro/common/systemd/kresd-tls.socket b/distro/common/systemd/kresd-tls.socket
new file mode 100644
index 0000000..ab16c81
--- /dev/null
+++ b/distro/common/systemd/kresd-tls.socket
@@ -0,0 +1,16 @@
+[Unit]
+Description=Knot Resolver TLS network listener
+Documentation=man:kresd.systemd(7)
+Documentation=man:kresd(8)
+Before=sockets.target
+
+[Socket]
+FreeBind=true
+FileDescriptorName=tls
+ListenStream=[::1]:853
+ListenStream=127.0.0.1:853
+Service=kresd@1.service
+Slice=system-kresd.slice
+
+[Install]
+WantedBy=sockets.target
diff --git a/distro/common/systemd/kresd.socket b/distro/common/systemd/kresd.socket
new file mode 100644
index 0000000..9dd9424
--- /dev/null
+++ b/distro/common/systemd/kresd.socket
@@ -0,0 +1,17 @@
+[Unit]
+Description=Knot Resolver network listeners
+Documentation=man:kresd.systemd(7)
+Documentation=man:kresd(8)
+Before=sockets.target
+
+[Socket]
+FreeBind=true
+ListenDatagram=[::1]:53
+ListenStream=[::1]:53
+ListenDatagram=127.0.0.1:53
+ListenStream=127.0.0.1:53
+Service=kresd@1.service
+Slice=system-kresd.slice
+
+[Install]
+WantedBy=sockets.target
diff --git a/distro/common/systemd/kresd.systemd.7 b/distro/common/systemd/kresd.systemd.7
new file mode 100644
index 0000000..420b110
--- /dev/null
+++ b/distro/common/systemd/kresd.systemd.7
@@ -0,0 +1,230 @@
+.TH "kresd.systemd" "7" "2018-06-04" "CZ.NIC" "Knot Resolver Systemd Units"
+.\"
+.\" kresd.systemd.7 -- man page for systemd units for kresd
+.\"
+.\" Copyright (c) 2018, CZ.NIC. All rights reserved.
+.\"
+.\" See COPYING for the license.
+.\"
+.\"
+.SH "NAME"
+kresd.systemd
+\- managing Knot Resolver through systemd.
+
+.SH "SYNOPSIS"
+.nf
+kresd@.service
+kresd.socket
+kresd-tls.socket
+kresd-control@.socket
+kresd.target
+system-kresd.slice
+.fi
+
+.SH "DESCRIPTION"
+.P
+This manual page describes how to manage \fBkresd\fR using \fBsystemd\fR
+units. Depending on your distribution, this can be either be done with
+socket-based activation or without it. The following assumes socket-based activation.
+For differences see \fINOTES\fR below.
+
+\fBkresd\fR daemon can be executed in multiple independent processes, which can be
+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.
+
+The systemd-managed \fBkresd\fR service set is grouped in the
+\fIsystem-kresd.slice\fR slice.  The slice includes one or more
+running daemons (instances of \fIkresd@.service\fR), public listening
+sockets (the same listening sockets are shared by all daemons) and a
+dedicated control socket for each running daemon.
+
+Each instance of \fIkresd@.service\fR has three systemd sockets (see
+\fBsystemd.socket(5)\fR) associated with it:
+
+.nf
+.RS
+\fIkresd.socket\fR - UDP/TCP network socket (default: localhost:53), shared with other instances
+\fIkresd-tls.socket\fR - network socket for DNS-over-TLS (default: localhost:853), shared with other instances
+\fIkresd-control@.socket\fR - UNIX socket with control terminal, dedicated
+.RE
+.fi
+
+.B Configuring network interfaces
+
+When using socket-based activation, the daemon requires neither root privileges
+nor any special capabilities, because the sockets are created by \fBsystemd\fR and
+passed to \fBkresd\fR. This means \fBkresd\fR can't bind to ports below 1024 when
+configured in \fI/etc/knot-resolver/kresd.conf\fR.
+
+To configure \fBkresd\fR to listen on public interfaces, drop-in files (see
+\fBsystemd.unit\fR(5)) should be used. These can be created with:
+
+.nf
+.RS 4n
+.B systemctl edit kresd.socket
+.B systemctl edit kresd-tls.socket
+.RE
+.fi
+
+For example, to configure \fBkresd\fR to listen on 192.0.2.115 on ports 53 and
+853, the drop-in files would look like:
+
+.nf
+.RS 4n
+# /etc/systemd/system/kresd.socket.d/override.conf
+[Socket]
+ListenDatagram=192.0.2.115:53
+ListenStream=192.0.2.115:53
+
+# /etc/systemd/system/kresd-tls.socket.d/override.conf
+[Socket]
+ListenStream=192.0.2.115:853
+.RE
+.fi
+
+For more detailed socket configuration, see \fBsystemd.socket\fR(5).
+
+.B Concurrent daemons
+
+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 public
+listening ports, 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.  To enable 3 concurrent daemons:
+
+.nf
+.RS 4n
+.B systemctl enable --now kresd@1.service kresd@2.service kresd@3.service
+.RE
+.fi
+
+.B Using system-kresd.slice and kresd.target
+
+The following commands may not work with older systemd (e.g. on CentOS 7).
+See notes for more info.
+
+The easiest way to view the status of systemd-supervised \fBkresd\fR
+instances is to use the \fIsystem-kresd.slice\fR:
+
+.nf
+.RS 4n
+.B systemctl status system-kresd.slice
+.RE
+.fi
+
+You can also use the slice to restart all sockets as well as daemons:
+
+.nf
+.RS 4n
+.B systemctl restart system-kresd.slice
+.RE
+.fi
+
+Or you can use it to stop kresd altogether (e.g. during package removal):
+
+.nf
+.RS 4n
+.B systemctl stop system-kresd.slice
+.RE
+.fi
+
+To start all enabled kresd daemons, use the provided \fIkresd.target\fR:
+
+.nf
+.RS 4n
+.B systemctl start kresd.target
+.RE
+.fi
+
+.SH "NOTES"
+
+.IP * 2
+When an instance of \fIkresd@.service\fR is started, stopped or
+restarted, its associated control socket is also automatically
+started, stopped or restarted, but the public listening sockets remain
+open.  As long as either of the public sockets are listening, at least
+\fIkresd@1.service\fR will be automatically activated when a request arrives.
+
+.IP * 2
+If your distribution doesn't use socket-based activation, you can configure the
+network interfaces for \fBkresd\fR in \fI/etc/knot-resolver/kresd.conf\fR.  The
+service can be started or enabled in the same way as in the examples below, but
+it doesn't have any sockets associated with it.
+
+.IP * 2
+Controlling the service with \fIsystem-kresd.slice\fR requires newer systemd.
+It may not work in some distributions, notably CentOS 7. To control multiple
+kresd instances, use \fIkresd@*.service\fR or \fIBrace Expansion\fR mentioned
+below.
+
+.SH "EXAMPLES"
+
+.B Single instance
+.RS 4n
+
+To start the service:
+.nf
+.RS 4n
+.B systemctl start kresd@1.service
+.RE
+.fi
+
+To start the service at boot:
+.nf
+.RS 4n
+.B systemctl enable kresd@1.service
+.RE
+.fi
+
+To delay the service startup until some traffic arrives, start (or enable) just
+the sockets:
+.nf
+.RS 4n
+.B systemctl start kresd.socket
+.B systemctl start kresd-tls.socket
+.RE
+.fi
+
+To disable the TLS socket, you can mask it:
+
+.RS 4n
+.B systemctl mask kresd-tls.socket
+.RE
+
+.RE
+
+.B Multiple instances
+.RS 4n
+
+Multiple instances can be handled with the use of \fIBrace Expansion\fR (see
+\fBbash\fR(1)).
+
+To enable multiple concurrent daemons, for example 16:
+.nf
+.RS
+.B systemctl enable kresd@{1..16}.service
+.RE
+.fi
+
+To start all enabled daemons:
+.nf
+.RS
+.B systemctl start kresd.target
+.RE
+.fi
+
+.RE
+
+.SH "SEE ALSO"
+\fIkresd(8)\fR,
+\fIsystemd.unit(5)\fR,
+\fIsystemd.socket(5)\fR,
+\fIhttps://knot-resolver.readthedocs.io\fR
+
+.SH "AUTHORS"
+.B kresd
+developers are mentioned in the AUTHORS file in the distribution.
diff --git a/distro/common/systemd/kresd.target b/distro/common/systemd/kresd.target
new file mode 100644
index 0000000..9b524da
--- /dev/null
+++ b/distro/common/systemd/kresd.target
@@ -0,0 +1,8 @@
+[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/distro/common/systemd/kresd@.service b/distro/common/systemd/kresd@.service
new file mode 100644
index 0000000..048aee0
--- /dev/null
+++ b/distro/common/systemd/kresd@.service
@@ -0,0 +1,17 @@
+[Unit]
+Description=Knot Resolver daemon
+Documentation=man:kresd.systemd(7)
+Documentation=man:kresd(8)
+
+[Service]
+Type=notify
+WorkingDirectory=/var/cache/knot-resolver
+ExecStart=/usr/sbin/kresd --config=/etc/knot-resolver/kresd.conf
+User=knot-resolver
+Restart=on-failure
+Sockets=kresd.socket
+Sockets=kresd-tls.socket
+Sockets=kresd-control@%i.socket
+
+[Install]
+WantedBy=kresd.target