The daemon also supports `systemd socket activation`_, it is automatically detected and requires no configuration on users's side.
+See ``kresd.systemd(8)`` for details.
+
Enabling DNSSEC
===============
.PP
.nf
.RS 6n
-# Create a basic forwarder configuration
+# Create a basic forwarder configuration
$ cat << EOF > config
modules = { 'policy' }
policy.add(policy.all(policy.FORWARD('192.168.1.1')))
.B \-V
Show the version.
.SH "SEE ALSO"
-\fIdaemon/README.md\fR,
+\fIkresd.systemd(8)\fR,
\fIhttps://knot-resolver.readthedocs.io\fR
.SH "AUTHORS"
.B kresd
--- /dev/null
+.TH "kresd.systemd" "8" "2018-01-30" "CZ.NIC" "Knot DNS Resolver Systemd Units"
+.\"
+.\" kresd.systemd.8 -- 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 DNS Resolver through systemd.
+
+.SH "SYNOPSIS"
+.nf
+kresd@.service
+kresd@.socket
+kresd-tls@.socket
+kresd-control@.socket
+.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.
+
+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)
+\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 doesn't require root privileges
+nor any 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
+
+.SH "NOTES"
+
+.IP * 2
+When \fIkresd@.service\fR is started, stopped or restarted, its associated
+sockets are also automatically started, stopped or restarted.
+
+.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.
+
+.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@1.socket
+.B systemctl start kresd-tls@1.socket
+.RE
+.fi
+
+To disable the TLS socket, you can mask it:
+
+.RS 4n
+.B systemctl mask kresd-tls@1.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 start multiple instances, for example 16:
+.nf
+.RS
+.B systemctl start kresd@{1..16}.service
+.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.
# associated sockets *are* enabled however, so the kresd service will
# be started as soon as anything connects to one of the listening
# sockets.
-disable kresd.service
+disable kresd@1.service
initialization via the interface supported by
sd_listen_fds_with_names(3)).
-Distributors of systems using systemd may wish to place
-./90-kresd.preset in /lib/systemd/systemd-preset/90-kresd.preset if
-they want to delay daemon launch until it is accessed. (see
-systemd.preset(5)).
+Usage and Configuration
+-----------------------
-When run in this configuration:
+See kresd.systemd(8) for details.
- * it will be run under a non-privileged user, which means it will not
- be able to open any new non-privileged ports.
+Manual activation
+-----------------
- * it will use a single process (implicitly uses --forks=1, and will
- fail if that configuration variable is set to a different value).
- If you want multiple daemons to listen on these ports publicly
- concurrently, you'll need the supervisor to manage them
- differently, for example via a systemd generator:
+If you wish to use manual activation without sockets, you have to grant
+the service the capability to bind to well-known ports. You can use a drop-in
+file.
- https://www.freedesktop.org/software/systemd/man/systemd.generator.html
+ # /etc/systemd/system/kresd@.service.d/override.conf
+ [Service]
+ AmbientCapabilities=CAP_NET_BIND_SERVICE
- If you have a useful systemd generator for multiple concurrent
- processes, please contribute it upstream!
+Notes
+-----
-Administrators who wish to make kresd listen on a public network
-interface can use:
+* If you're using systemd prior to version 227, use a drop-in file to change
+ the service type to simple. See drop-in/systemd-compat.conf.
- systemctl edit kresd.socket
+* Distributors of systems using systemd may wish to place
+ ./90-kresd.preset in /lib/systemd/systemd-preset/90-kresd.preset if
+ they want to delay daemon launch until it is accessed. (see
+ systemd.preset(5)).
-to add an override file that indicates where they want it to listen.
-For example:
-
- # /etc/systemd/system/kresd.socket.d/override.conf
- [Socket]
- ListenDatagram=192.0.2.115:53
- ListenStream=192.0.2.115:53
+* Symlinks pointing from @1 to the systemd template are not necessary. They
+ are only useful to provide users unfamiliar with kresd instances a hint
+ when using bash completion.
--- /dev/null
+# /etc/systemd/system/kresd-tls@.socket.d/override.conf
+
+# Configure which interfaces should kresd listen on.
+# ListenStream can be added multiple times.
+
+[Socket]
+ListenStream=192.0.2.115:853
--- /dev/null
+# /etc/systemd/system/kresd@.socket.d/override.conf
+
+# Configure which interfaces should kresd listen on.
+# ListenDatagram and ListenStream can be added multiple times.
+
+[Socket]
+ListenDatagram=192.0.2.115:53
+ListenStream=192.0.2.115:53
--- /dev/null
+# /etc/systemd/system/kresd@.service.d/override.conf
+
+# If socket activation isn't used, the CAP_NET_BIND_SERVICE is necessary
+# to be able to bind to a well-known port as an unprivilidged user.
+
+[Service]
+AmbientCapabilities=CAP_NET_BIND_SERVICE
--- /dev/null
+# /etc/systemd/system/kresd@.service.d/override.conf
+
+# If systemd.227+ isn't available (e.g. CentOS 7), change the service type.
+
+[Service]
+Type=simple
Description=Knot DNS Resolver control socket
Documentation=man:kresd(8)
Before=sockets.target
-PartOf=kresd.socket
-Alias=knot-resolver-control.socket
+Service=kresd@%i.service
+PartOf=kresd@%i.service
[Socket]
-ListenStream=/run/knot-resolver/control
+ListenStream=/run/knot-resolver/control@%i
FileDescriptorName=control
-Service=kresd.service
SocketMode=0660
[Install]
--- /dev/null
+kresd-control@.socket
\ No newline at end of file
Description=Knot DNS Resolver TLS network listener
Documentation=man:kresd(8)
Before=sockets.target
-PartOf=kresd.socket
-Alias=knot-resolver-tls.socket
+Service=kresd@%i.service
+PartOf=kresd@%i.service
[Socket]
-ListenStream=853
+ReusePort=true
+FreeBind=true
FileDescriptorName=tls
-Service=kresd.service
+ListenStream=[::1]:853
+ListenStream=127.0.0.1:853
[Install]
WantedBy=sockets.target
--- /dev/null
+kresd-tls@.socket
\ No newline at end of file
[Unit]
Description=Knot DNS Resolver daemon
Documentation=man:kresd(8)
-Alias=knot-resolver.service
+Wants=kresd@%i.socket
+Wants=kresd-control@%i.socket
+Wants=kresd-tls@%i.socket
[Service]
Type=notify
ExecStart=/usr/sbin/kresd $KRESD_ARGS
User=knot-resolver
Restart=on-failure
-# CAP_NET_BIND_SERVICE capability is needed for manual service activation
-AmbientCapabilities=CAP_NET_BIND_SERVICE
Description=Knot DNS Resolver network listeners
Documentation=man:kresd(8)
Before=sockets.target
-Alias=knot-resolver.socket
+Service=kresd@%i.service
+PartOf=kresd@%i.service
[Socket]
-ListenStream=[::1]:53
+ReusePort=true
+FreeBind=true
ListenDatagram=[::1]:53
-ListenStream=127.0.0.1:53
+ListenStream=[::1]:53
ListenDatagram=127.0.0.1:53
-FreeBind=true
+ListenStream=127.0.0.1:53
[Install]
WantedBy=sockets.target
--- /dev/null
+kresd@.socket
\ No newline at end of file
projects / thirdparty / knot-resolver.git / commitdiff
