Adding upstream version 3.2.1.upstream/3.2.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 230 insertions, 0 deletions

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.