kresd.systemd(7)

NAME
kresd.systemd - managing Knot Resolver @version@ through systemd.

SYNOPSIS
kresd@.service
kresd.socket
kresd-tls.socket
kresd-control@.socket
kresd-doh.socket
kresd-webmgmt.socket
kresd.target
system-kresd.slice

DESCRIPTION

This manual page describes how to manage kresd using systemd units. QUICKSTART
    systemctl start kresd@1 - single instance of kresd, responding on localhost
SOCKET ACTIVATION kresd 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. Network configuration has to take place in systemd.socket(5), which can be done using drop-in files. Each instance of kresd@.service may have these systemd sockets associated with it:
    kresd.socket - UDP/TCP network socket (default: localhost:53)
    kresd-tls.socket - network socket for DNS-over-TLS (default: localhost:853)
    kresd-control@.socket - UNIX socket with control terminal
    kresd-doh.socket - DNS-over-HTTPS (with http module: localhost:44353)
    kresd-webmgmt.socket - web management and APIs (with http module: localhost:8453)
CONFIGURING NETWORK INTERFACES By default, kresd is configured to listen on localhost (see ports above). You MUST NOT repeat these defaults in the following drop-in overrides, otherwise the socket will fail to start with "Address in use" error. To view the entire socket configuration, including any drop-ins, use systemctl cat. To configure kresd to listen on public interfaces, drop-in files (see systemd.unit(5)) should be used. These can be created with:
    systemctl edit kresd.socket
    systemctl edit kresd-tls.socket
    systemctl edit kresd-doh.socket
If you change network interfaces of systemd sockets for already running kresd instance, make sure to call systemctl restart system-kresd.slice for these changes to take effect. For example, to configure kresd to listen on 192.0.2.115 on ports 53 and 853, the drop-in files would look like:
    # /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
To configure kresd to listen on all IPv4 and IPv6 interfaces, use empty ListenDatagram= and ListenStream= directives to remove the default localhost address and then specify port to bind to. If you've disabled IPv6 support in kernel, use the 0.0.0.0:port syntax instead.
    # /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
Please note that using IPv6 to bind to IPv4 interfaces is currently not compatible with IPv4 syntax in view:addr() when using the view module. For possible workarounds, see https://gitlab.labs.nic.cz/knot/knot-resolver/issues/445 To configure socket for DNS-over-HTTPS, make sure you have kresd-doh.socket installed (it might be part of a separate knot-resolver-module-http package). Then, you can configure its network interfaces as above. Also, don't forget to load http module in configuration file, otherwise the socket won't have any function. For example, to remove the default localhost:44353 and listen on all interfaces on port 443, create the following drop-in file for kresd-doh.socket:
    # /etc/systemd/system/kresd-doh.socket.d/override.conf
    [Socket]
    ListenStream=
    ListenStream=443
Make sure no other service is using port 443, as that will result in unpredictable behaviour. Alternately, you can use port 44353 where a collision is unlikely. For more detailed socket configuration, see systemd.socket(5). CONCURRENT DAEMONS kresd daemon can be executed in multiple independent processes, which are managed with systemd via systemd templates (see systemd.unit(5)). Each systemd service instance of kresd (kresd@.service) represents a single, independent kresd process. The systemd-managed kresd service set is grouped in the system-kresd.slice slice. The slice includes one or more running daemons (instances of kresd@.service), network sockets kresd.socket and kresd-tls.socket (shared by all instances) and a dedicated control kresd-control@.socket for each running daemon. If you have more than one CPU core available, a single running kresd daemon will only be able to make use of one core at a time, leaving the other cores idle. If you want kresd 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 kresd@.service as you have cores. Typically, each instance is just named kresd@N.service, where N is a decimal number. To enable 3 concurrent daemons:
    systemctl enable --now kresd@1.service kresd@2.service kresd@3.service

NOTES

*   When an instance of kresd@.service 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 kresd@1.service will be automatically activated when a request arrives.

EXAMPLES
To start the service:
    systemctl start kresd@1.service
To start the service at boot:
    systemctl enable kresd@1.service
To delay the service startup until some traffic arrives, start (or enable) just the sockets:
    systemctl start kresd.socket
    systemctl start kresd-tls.socket
To disable optional sockets, you can mask them. For example, to disable DNS-over-TLS socket:
    systemctl mask kresd-tls.socket
Using system-kresd.slice and kresd.target The easiest way to view the status of multiple kresd instances is to use the system-kresd.slice:
    systemctl status system-kresd.slice
You can also use the slice to restart all sockets as well as daemons:
    systemctl restart system-kresd.slice
Alternatively, to restart just kresd daemons, you can use Brace Expansion:
    systemctl enable kresd@{1..4}.service
Or you can use it to stop kresd altogether (e.g. during package removal):
    systemctl stop system-kresd.slice
To start all enabled kresd daemons, use the provided kresd.target:
    systemctl start kresd.target

SEE ALSO
kresd(8), systemd.unit(5), systemd.socket(5), https://knot-resolver.readthedocs.io/en/v@version@/

AUTHORS
kresd developers are mentioned in the AUTHORS file in the distribution.