bionic (7) kresd.systemd.7.gz

NAME

       kresd.systemd - managing Knot DNS Resolver through systemd.

SYNOPSIS

       kresd@.service
       kresd.socket
       kresd-tls.socket
       kresd-control@.socket
       system-kresd.slice

DESCRIPTION

       This  manual page describes how to manage kresd using systemd 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 NOTES below.

       kresd  daemon  can  be  executed in multiple independent processes, which can be 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),  public  listening  sockets  (the  same  listening
       sockets are shared by all daemons) and a dedicated control socket for each running daemon.

       Each instance of kresd@.service has three systemd sockets (see systemd.socket(5)) associated with it:

              kresd.socket - UDP/TCP network socket (default: localhost:53), shared with other instances
              kresd-tls.socket - network socket for DNS-over-TLS (default: localhost:853), shared with other instances
              kresd-control@.socket - UNIX socket with control terminal, dedicated

       Configuring network interfaces

       When  using  socket-based  activation,  the  daemon  requires  neither  root  privileges  nor any special
       capabilities, because the sockets are created by systemd and passed to kresd. This means kresd can't bind
       to ports below 1024 when configured in /etc/knot-resolver/kresd.conf.

       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

       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

       Concurrent daemons

       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

       Using system-kresd.slice

       The  easiest  way  to  view  the  status  of  systemd-supervised  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

       Or you can use it to stop kresd altogether (e.g. during package removal):

           systemctl stop system-kresd.slice

       Note that systemctl start system-kresd.slice does not automatically start the  sockets  or  the  daemons,
       though.  To ensure that all enabled daemons are started and running, do:

           systemctl start 'kresd@*.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.

       * If your distribution doesn't use socket-based activation, you can configure the network interfaces  for
         kresd  in  /etc/knot-resolver/kresd.conf.   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.

EXAMPLES

       Single instance

           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 the TLS socket, you can mask it:

               systemctl mask kresd-tls.socket

       Multiple instances

           Multiple instances can be handled with the use of Brace Expansion (see bash(1)).

           To enable multiple concurrent daemons, for example 16:
                  systemctl enable kresd@{1..16}.service

           To start all enabled daemons:
                  systemctl start 'kresd@*.service'

SEE ALSO

       kresd(8), systemd.unit(5), systemd.socket(5), https://knot-resolver.readthedocs.io

AUTHORS

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