.SH "SYNOPSIS"
.nf
kresd@.service
-kresd@.socket
-kresd-tls@.socket
+kresd.socket
+kresd-tls.socket
kresd-control@.socket
+system-kresd.slice
+kresd.service
.fi
.SH "DESCRIPTION"
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), a
+dedicated control socket for each running daemon, and one meta-service
+(\fIkresd.service\fR) which can be used to stop or restart all the
+daemons.
+
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
+\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 doesn't require root privileges
-nor any capabilities, because the sockets are created by \fBsystemd\fR and
+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.
.nf
.RS 4n
-.B systemctl edit kresd@.socket
-.B systemctl edit kresd-tls@.socket
+.B systemctl edit kresd.socket
+.B systemctl edit kresd-tls.socket
.RE
.fi
.nf
.RS 4n
-# /etc/systemd/system/kresd@.socket.d/override.conf
+# /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
+# /etc/systemd/system/kresd-tls.socket.d/override.conf
[Socket]
ListenStream=192.0.2.115:853
.RE
.fi
+.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
+
+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
+
+Note that \fBsystemctl start system-kresd.slice\fR does not
+automatically start the sockets or the daemons, though. To ensure
+that all enabled daemons are started and running, do:
+
+.nf
+.RS 4n
+.B systemctl start 'kresd@*.service'
+.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.
+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
the sockets:
.nf
.RS 4n
-.B systemctl start kresd@1.socket
-.B systemctl start kresd-tls@1.socket
+.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@1.socket
+.B systemctl mask kresd-tls.socket
.RE
.RE
Multiple instances can be handled with the use of \fIBrace Expansion\fR (see
\fBbash\fR(1)).
-To start multiple instances, for example 16:
+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@{1..16}.service
+.B systemctl start 'kresd@*.service'
.RE
.fi
\fIhttps://knot-resolver.readthedocs.io\fR
.SH "AUTHORS"
-.B kresd developers are mentioned in the AUTHORS file in the distribution.
+.B kresd
+developers are mentioned in the AUTHORS file in the distribution.
projects / thirdparty / knot-resolver.git / commitdiff
