kresd.systemd man page

kresd.systemd — managing Knot Resolver 4.2.2 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

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/v4.2.2/

Authors

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

Referenced By

kresd(8).

2019-10-07 CZ.NIC Knot Resolver 4.2.2 Systemd Units