diff options
Diffstat (limited to 'distro/common/systemd/kresd.systemd.7')
| -rw-r--r-- | distro/common/systemd/kresd.systemd.7 | 230 |
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. |