Commit d5c09e1d authored by Tomas Krizek's avatar Tomas Krizek

meson: systemd - update kresd.systemd.7

parent 5abc23a5
......@@ -9,7 +9,7 @@
.\"
.SH "NAME"
.B kresd
\- full caching Knot Resolver @version@.
\- full caching DNSSEC-enabled Knot Resolver @version@.
.SH "SYNOPSIS"
.B kresd
.RB [ \-a | \-\-addr
......
.TH "kresd.systemd" "7" "2019-01-28" "CZ.NIC" "Knot Resolver Systemd Units"
.TH "kresd.systemd" "7" "@date@" "CZ.NIC" "Knot Resolver @version@ Systemd Units"
.\"
.\" kresd.systemd.7 -- man page for systemd units for kresd
.\"
......@@ -9,7 +9,7 @@
.\"
.SH "NAME"
kresd.systemd
\- managing Knot Resolver through systemd.
\- managing Knot Resolver @version@ through systemd.
.SH "SYNOPSIS"
.nf
......@@ -24,41 +24,31 @@ system-kresd.slice
.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.
units.
\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.
.B Socket activation
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.
\fBkresd\fR integration with systemd takes advantage of socket activation,
which enables the daemon to run without super user priviledges or any
additional capabilities. The network interface sockets are created by systemd
and then passed to the daemon.
Each instance of \fIkresd@.service\fR has three systemd sockets (see
\fBsystemd.socket(5)\fR) associated with it:
Network configuration has to take place in \fIsystemd.socket(5)\fR, which can
be done using drop-in files. Each instance of \fIkresd@.service\fR has three
systemd sockets 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
\fIkresd.socket\fR - UDP/TCP network socket (default: localhost:53)
\fIkresd-tls.socket\fR - network socket for DNS-over-TLS (default: localhost:853)
\fIkresd-control@.socket\fR - UNIX socket with control terminal
.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:
\fIsystemd.unit\fR(5)) should be used. These can be created with:
.nf
.RS 4n
......@@ -83,10 +73,10 @@ ListenStream=192.0.2.115:853
.RE
.fi
To configure \fBkresd\fR to listen on all IPv4 and IPv6 interfaces, you can
remove the default localhost address by using an empty \fIListenDatagram=\fR,
\fIListenStream=\fR directive and then bind to the [::] address. If you've
disabled IPv6 support in kernel, use the 0.0.0.0 address instead.
To configure \fBkresd\fR to listen on all IPv4 and IPv6 interfaces, use empty
\fIListenDatagram=\fR and \fIListenStream=\fR directives to remove the default
localhost address and then bind to the [::] address. If you've disabled IPv6
support in kernel, use the 0.0.0.0 address instead.
.nf
.RS 4n
......@@ -113,6 +103,17 @@ For more detailed socket configuration, see \fBsystemd.socket\fR(5).
.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.
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), network sockets \fIkresd.socket\fR and
\fIkresd-tls.socket\fR (shared by all instances) and a dedicated control
\fIkresd-control@.socket\fR for each running daemon.
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
......@@ -128,44 +129,6 @@ number. To enable 3 concurrent daemons:
.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
......@@ -175,23 +138,8 @@ 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
......@@ -221,24 +169,45 @@ To disable the TLS socket, you can mask it:
.B systemctl mask kresd-tls.socket
.RE
.B Using system-kresd.slice and kresd.target
The easiest way to view the status of multiple \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
Alternatively, to restart just kresd daemons, you can use \fIBrace Expansion\fR:
.B Multiple instances
.nf
.RS 4n
.B systemctl enable kresd@{1..4}.service
.RE
.fi
Multiple instances can be handled with the use of \fIBrace Expansion\fR (see
\fBbash\fR(1)).
Or you can use it to stop kresd altogether (e.g. during package removal):
To enable multiple concurrent daemons, for example 16:
.nf
.RS
.B systemctl enable kresd@{1..16}.service
.RS 4n
.B systemctl stop system-kresd.slice
.RE
.fi
To start all enabled daemons:
To start all enabled kresd daemons, use the provided \fIkresd.target\fR:
.nf
.RS
.RS 4n
.B systemctl start kresd.target
.RE
.fi
......@@ -249,7 +218,7 @@ To start all enabled daemons:
\fIkresd(8)\fR,
\fIsystemd.unit(5)\fR,
\fIsystemd.socket(5)\fR,
\fIhttps://knot-resolver.readthedocs.io\fR
\fIhttps://knot-resolver.readthedocs.io/en/v@version@/\fR
.SH "AUTHORS"
.B kresd
......
......@@ -20,7 +20,7 @@ systemd_config.set('run_dir', run_dir)
# TODO Restart=on-abnormal
if systemd_socket
# unit files
## unit files
kresd_service = configure_file(
input: 'kresd@.service.in',
output: 'kresd@.service',
......@@ -33,7 +33,6 @@ if systemd_socket
configuration: systemd_config,
install_dir: systemd_unit_dir,
)
install_data(
sources: [
'kresd.socket',
......@@ -43,9 +42,15 @@ if systemd_socket
install_dir: systemd_unit_dir,
)
install_man('kresd.systemd.7') # TODO amend man page + configure
## 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
tmpfiles = configure_file(
input: 'tmpfiles.d/knot-resolver.conf.in',
output: 'knot-resolver.conf',
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment