From: Tomas Krizek Date: Fri, 8 Feb 2019 14:17:25 +0000 (+0100) Subject: meson: systemd/nosocket - update man X-Git-Tag: v4.0.0~24^2~157 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8e4fda460ad28130decb851b9c820e435ced3d06;p=thirdparty%2Fknot-resolver.git meson: systemd/nosocket - update man --- diff --git a/systemd/nosocket/kresd.systemd.nosocket.7 b/systemd/nosocket/kresd.systemd.nosocket.7 deleted file mode 100644 index 3b0433e9b..000000000 --- a/systemd/nosocket/kresd.systemd.nosocket.7 +++ /dev/null @@ -1,256 +0,0 @@ -.TH "kresd.systemd" "7" "2019-01-28" "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 - -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 - -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. diff --git a/systemd/nosocket/kresd.systemd.nosocket.7.in b/systemd/nosocket/kresd.systemd.nosocket.7.in new file mode 100644 index 000000000..0110c7a19 --- /dev/null +++ b/systemd/nosocket/kresd.systemd.nosocket.7.in @@ -0,0 +1,127 @@ +.TH "kresd.systemd" "7" "@date@" "CZ.NIC" "Knot Resolver @version@ Systemd Units" +.\" +.\" kresd.systemd.nosocket.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.nosocket +\- managing Knot Resolver @version@ through systemd without socket activation + +.SH "SYNOPSIS" +.nf +kresd@.service +kresd.target +system-kresd.slice +.fi + +.SH "DESCRIPTION" +.P +This manual page describes how to manage \fBkresd\fR using \fBsystemd\fR +units without socket activation support. + +.B Concurrent daemons + +\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 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 +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 + +.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 + +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/en/v@version@/\fR + +.SH "AUTHORS" +.B kresd +developers are mentioned in the AUTHORS file in the distribution. diff --git a/systemd/nosocket/meson.build b/systemd/nosocket/meson.build index 5cc1cdccf..383b912e0 100644 --- a/systemd/nosocket/meson.build +++ b/systemd/nosocket/meson.build @@ -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(