1kresd.systemd(7) Knot Resolver 4.3.0 Systemd Units kresd.systemd(7)
2
6 kresd.systemd - managing Knot Resolver 4.3.0 through systemd.
7
10 kresd@.service
11 kresd.socket
12 kresd-tls.socket
13 kresd-control@.socket
14 kresd-doh.socket
15 kresd-webmgmt.socket
16 kresd.target
17 system-kresd.slice
18
21 This manual page describes how to manage kresd using systemd units.
22 QUICKSTART
24 systemctl start kresd@1 - single instance of kresd, responding on localhost
26 SOCKET ACTIVATION
28 kresd integration with systemd takes advantage of socket activation,
30 which enables the daemon to run without super user priviledges or any
31 additional capabilities. The network interface sockets are created by
32 systemd and then passed to the daemon.
33 Network configuration has to take place in systemd.socket(5), which can
35 be done using drop-in files. Each instance of kresd@.service may have
36 these systemd sockets associated with it:
37 kresd.socket - UDP/TCP network socket (default: localhost:53)
39 kresd-tls.socket - network socket for DNS-over-TLS (default: localhost:853)
40 kresd-control@.socket - UNIX socket with control terminal
41 kresd-doh.socket - DNS-over-HTTPS (with http module: localhost:44353)
42 kresd-webmgmt.socket - web management and APIs (with http module: localhost:8453)
43 CONFIGURING NETWORK INTERFACES
45 By default, kresd is configured to listen on localhost (see ports
47 above). You MUST NOT repeat these defaults in the following drop-in
48 overrides, otherwise the socket will fail to start with "Address in
49 use" error. To view the entire socket configuration, including any
50 drop-ins, use systemctl cat.
51 To configure kresd to listen on public interfaces, drop-in files (see
53 systemd.unit(5)) should be used. These can be created with:
54 systemctl edit kresd.socket
56 systemctl edit kresd-tls.socket
57 systemctl edit kresd-doh.socket
58 If you change network interfaces of systemd sockets for already running
60 kresd instance, make sure to call systemctl restart system-kresd.slice
61 for these changes to take effect.
62 For example, to configure kresd to listen on 192.0.2.115 on ports 53
64 and 853, the drop-in files would look like:
65 # /etc/systemd/system/kresd.socket.d/override.conf
67 [Socket]
68 ListenDatagram=192.0.2.115:53
69 ListenStream=192.0.2.115:53
70 # /etc/systemd/system/kresd-tls.socket.d/override.conf
72 [Socket]
73 ListenStream=192.0.2.115:853
74 To configure kresd to listen on all IPv4 and IPv6 interfaces, use empty
76 ListenDatagram= and ListenStream= directives to remove the default
77 localhost address and then specify port to bind to. If you've disabled
78 IPv6 support in kernel, use the 0.0.0.0:port syntax instead.
79 # /etc/systemd/system/kresd.socket.d/override.conf
81 [Socket]
82 ListenDatagram=
83 ListenStream=
84 ListenDatagram=53
85 ListenStream=53
86 # /etc/systemd/system/kresd-tls.socket.d/override.conf
88 [Socket]
89 ListenStream=
90 ListenStream=853
91 Please note that using IPv6 to bind to IPv4 interfaces is currently not
93 compatible with IPv4 syntax in view:addr() when using the view module.
94 For possible workarounds, see https://gitlab.labs.nic.cz/knot/knot-
95 resolver/issues/445
96 To configure socket for DNS-over-HTTPS, make sure you have kresd-
98 doh.socket installed (it might be part of a separate knot-resolver-mod‐
99 ule-http package). Then, you can configure its network interfaces as
100 above. Also, don't forget to load http module in configuration file,
101 otherwise the socket won't have any function.
102 For example, to remove the default localhost:44353 and listen on all
104 interfaces on port 443, create the following drop-in file for kresd-
105 doh.socket:
106 # /etc/systemd/system/kresd-doh.socket.d/override.conf
108 [Socket]
109 ListenStream=
110 ListenStream=443
111 Make sure no other service is using port 443, as that will result in
113 unpredictable behaviour. Alternately, you can use port 44353 where a
114 collision is unlikely.
115 For more detailed socket configuration, see systemd.socket(5).
117 CONCURRENT DAEMONS
119 kresd daemon can be executed in multiple independent processes, which
121 are managed with systemd via systemd templates (see systemd.unit(5)).
122 Each systemd service instance of kresd (kresd@.service) represents a
123 single, independent kresd process.
124 The systemd-managed kresd service set is grouped in the system-
126 kresd.slice slice. The slice includes one or more running daemons
127 (instances of kresd@.service), network sockets kresd.socket and kresd-
128 tls.socket (shared by all instances) and a dedicated control kresd-con‐
129 trol@.socket for each running daemon.
130 If you have more than one CPU core available, a single running kresd
132 daemon will only be able to make use of one core at a time, leaving the
133 other cores idle. If you want kresd to take advantage of all available
134 cores, while sharing both cache and public listening ports, you should
135 enable and start as many instances of the kresd@.service as you have
136 cores. Typically, each instance is just named kresd@N.service, where N
137 is a decimal number. To enable 3 concurrent daemons:
138 systemctl enable --now kresd@1.service kresd@2.service kresd@3.service
140
143 * When an instance of kresd@.service is started, stopped or restarted,
144 its associated control socket is also automatically started, stopped
145 or restarted, but the public listening sockets remain open. As long
146 as either of the public sockets are listening, at least kresd@1.ser‐
147 vice will be automatically activated when a request arrives.
148
151 To start the service:
152 systemctl start kresd@1.service
153 To start the service at boot:
155 systemctl enable kresd@1.service
156 To delay the service startup until some traffic arrives, start (or
158 enable) just the sockets:
159 systemctl start kresd.socket
160 systemctl start kresd-tls.socket
161 To disable optional sockets, you can mask them. For example, to disable
163 DNS-over-TLS socket:
164 systemctl mask kresd-tls.socket
166 Using system-kresd.slice and kresd.target
168 The easiest way to view the status of multiple kresd instances is to
170 use the system-kresd.slice:
171 systemctl status system-kresd.slice
173 You can also use the slice to restart all sockets as well as daemons:
175 systemctl restart system-kresd.slice
177 Alternatively, to restart just kresd daemons, you can use Brace Expan‐
179 sion:
180 systemctl enable kresd@{1..4}.service
182 Or you can use it to stop kresd altogether (e.g. during package
184 removal):
185 systemctl stop system-kresd.slice
187 To start all enabled kresd daemons, use the provided kresd.target:
189 systemctl start kresd.target
191
195 kresd(8), systemd.unit(5), systemd.socket(5), https://knot-
196 resolver.readthedocs.io/en/v4.3.0/
197
200 kresd developers are mentioned in the AUTHORS file in the distribution.
201CZ.NIC 2019-12-04 kresd.systemd(7)