path: root/distro/common/systemd/kresd.systemd.7

.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.