Commit 8e4fda46 authored by Tomas Krizek's avatar Tomas Krizek

meson: systemd/nosocket - update man

parent d5c09e1d
.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
.\" kresd.systemd.nosocket.7 -- man page for systemd units for kresd
.\"
.\" Copyright (c) 2018, CZ.NIC. All rights reserved.
.\"
......@@ -8,15 +8,12 @@
.\"
.\"
.SH "NAME"
kresd.systemd
\- managing Knot Resolver through systemd.
kresd.systemd.nosocket
\- managing Knot Resolver @version@ through systemd without socket activation
.SH "SYNOPSIS"
.nf
kresd@.service
kresd.socket
kresd-tls.socket
kresd-control@.socket
kresd.target
system-kresd.slice
.fi
......@@ -24,94 +21,18 @@ 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 without socket activation support.
\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
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.
.nf
.RS 4n
# /etc/systemd/system/kresd.socket.d/override.conf
[Socket]
ListenDatagram=
ListenStream=
ListenDatagram=[::]:53
ListenStream=[::]:53
# /etc/systemd/system/kresd-tls.socket.d/override.conf
[Socket]
ListenStream=
ListenStream=[::]:853
.RE
.fi
Please note that using IPv6 to bind to IPv4 interfaces is currently not
compatible with IPv4 syntax in \fIview:addr()\fR when using the view module.
For possible workarounds, see
https://gitlab.labs.nic.cz/knot/knot-resolver/issues/445
.B Concurrent daemons
For more detailed socket configuration, see \fBsystemd.socket\fR(5).
\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 Concurrent daemons
The systemd-managed \fBkresd\fR service set is grouped in the
\fIsystem-kresd.slice\fR slice. The slice includes all running daemons
(instances of \fIkresd@.service\fR).
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
......@@ -128,65 +49,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
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
......@@ -243,13 +105,22 @@ To start all enabled daemons:
.RE
.fi
The easiest way to view the status of \fBkresd\fR instances is to use the
\fIsystem-kresd.slice\fR:
.nf
.RS 4n
.B systemctl status system-kresd.slice
.RE
.fi
.RE
.SH "SEE ALSO"
\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
......
......@@ -13,7 +13,13 @@ install_data(
install_dir: systemd_unit_dir,
)
install_man('kresd.systemd.nosocket.7') # TODO amend man page + configure
## man page
kresd_systemd_man = configure_file(
input: 'kresd.systemd.nosocket.7.in',
output: 'kresd.systemd.nosocket.7',
configuration: man_config,
)
install_man(kresd_systemd_man)
# tmpfiles
tmpfiles = configure_file(
......
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