1nsd.conf(5) nsd 4.7.0 nsd.conf(5)
2
6 nsd.conf - NSD configuration file
7
9 nsd.conf
10
12 Nsd.conf is used to configure nsd(8). The file format has attributes
13 and values. Some attributes have attributes inside them. The notation
14 is: attribute: value.
15 Comments start with # and last to the end of line. Empty lines are ig‐
17 nored as is whitespace at the beginning of a line. Quotes can be used,
18 for names with spaces, eg. "file name.zone".
19 Nsd.conf specifies options for the nsd server, zone files, primaries
21 and secondaries.
22
24 An example of a short nsd.conf file is below.
25 # Example.com nsd.conf file
27 # This is a comment.
28 server:
30 server-count: 1 # use this number of cpu cores
31 database: "" # or use ""
32 zonelistfile: "/var/lib/nsd/zone.list"
33 username: nsd
34 logfile: "/var/log/nsd.log"
35 pidfile: ""
36 xfrdfile: "/var/lib/nsd/ixfr.state"
37 zone:
39 name: example.com
40 zonefile: /etc/nsd/example.com.zone
41 zone:
43 # this server is master, 192.0.2.1 is the secondary.
44 name: masterzone.com
45 zonefile: /etc/nsd/masterzone.com.zone
46 notify: 192.0.2.1 NOKEY
47 provide-xfr: 192.0.2.1 NOKEY
48 zone:
50 # this server is secondary, 192.0.2.2 is master.
51 name: secondzone.com
52 zonefile: /etc/nsd/secondzone.com.zone
53 allow-notify: 192.0.2.2 NOKEY
54 request-xfr: 192.0.2.2 NOKEY
55 Then, use kill -HUP to reload changes from master zone files. And use
57 kill -TERM to stop the server.
58
60 There must be whitespace between keywords. Attribute keywords end with
61 a colon ':'. An attribute is followed by its containing attributes, or
62 a value.
63 At the top level only server:, verify:, key:, pattern:, zone:, tls-
65 auth:, and remote-control: are allowed. These are followed by their at‐
66 tributes or a new top-level keyword. The zone: attribute is followed by
67 zone options. The server: attribute is followed by global options for
68 the NSD server. The verify: attribute is used to control zone verifica‐
69 tion. A key: attribute is used to define keys for authentication. The
70 pattern: attribute is followed by the zone options for zones that use
71 the pattern. A tls-auth: attribute is used to define credentials for
72 authenticating an outgoing TLS connection used for XFR-over-TLS.
73 Files can be included using the include: directive. It can appear any‐
75 where, and takes a single filename as an argument. Processing continues
76 as if the text from the included file was copied into the config file
77 at that point. If a chroot is used an absolute filename is needed
78 (with the chroot prepended), so that the include can be parsed before
79 and after application of the chroot (and the knowledge of what that ch‐
80 root is). You can use '*' to include a wildcard match of files, eg.
81 "foo/nsd.d/*.conf". Also '?', '{}', '[]', and '~' work, see glob(7).
82 If no files match the pattern, this is not an error.
83 Server Options
85 The global options (if not overridden from the NSD commandline) are
86 taken from the server: clause. There may only be one server: clause.
87 ip-address: <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
89 NSD will bind to the listed ip-address. Can be given multiple
90 times to bind multiple ip-addresses. Optionally, a port number
91 can be given. If none are given NSD listens to the wildcard in‐
92 terface. Same as commandline option -a.
93 To limit which NSD server(s) listen on the given interface,
95 specify one or more servers separated by whitespace after
96 <ip>[@port]. Ranges can be used as a shorthand to specify multi‐
97 ple consecutive servers. By default every server will listen.
98 If an interface name is used instead of ip4 or ip6, the list of
100 IP addresses associated with that interface is picked up and
101 used at server start.
102 For servers with multiple IP addresses that can be used to send
104 traffic to the internet, list them one by one, or the source ad‐
105 dress of replies could be wrong. This is because if the udp
106 socket associates a source address of 0.0.0.0 then the kernel
107 picks an ip-address with which to send to the internet, and it
108 picks the wrong one. Typically needed for anycast instances.
109 Use ip-transparent to be able to list addresses that turn on
110 later (typical for certain load-balancing).
111 interface: <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
113 Same as ip-address (for ease of compatibility with un‐
114 bound.conf).
115 ip-transparent: <yes or no>
117 Allows NSD to bind to non local addresses. This is useful to
118 have NSD listen to IP addresses that are not (yet) added to the
119 network interface, so that it can answer immediately when the
120 address is added. Default is no.
121 ip-freebind: <yes or no>
123 Set the IP_FREEBIND option to bind to nonlocal addresses and in‐
124 terfaces that are down. Similar to ip-transparent. Default is
125 no.
126 reuseport: <yes or no>
128 Use the SO_REUSEPORT socket option, and create file descriptors
129 for every server in the server-count. This improves performance
130 of the network stack. Only really useful if you also configure
131 a server-count higher than 1 (such as, equal to the number of
132 cpus). The default is no. It works on Linux, but does not work
133 on FreeBSD, and likely does not work on other systems.
134 send-buffer-size: <number>
136 Set the send buffer size for query-servicing sockets. Set to 0
137 to use the default settings.
138 receive-buffer-size: <number>
140 Set the receive buffer size for query-servicing sockets. Set to
141 0 to use the default settings.
142 debug-mode: <yes or no>
144 Turns on debugging mode for nsd, does not fork a daemon process.
145 Default is no. Same as commandline option -d. If set to yes it
146 does not fork and stays in the foreground, which can be helpful
147 for commandline debugging, but is also used by certain server
148 supervisor processes to ascertain that the server is running.
149 do-ip4: <yes or no>
151 If yes, NSD listens to IPv4 connections. Default yes.
152 do-ip6: <yes or no>
154 If yes, NSD listens to IPv6 connections. Default yes.
155 database: <filename>
157 By default '' is used. The specified file is used to store the
158 compiled zone information. Same as commandline option -f. If
159 set to "" then no database is used. This uses less memory but
160 zone updates are not (immediately) spooled to disk.
161 zonelistfile: <filename>
163 By default /var/lib/nsd/zone.list is used. The specified file is
164 used to store the dynamically added list of zones. The list is
165 written to by NSD to add and delete zones. It is a text file
166 with a zone-name and pattern-name on each line. This file is
167 used for the nsd-control addzone and delzone commands.
168 identity: <string>
170 Returns the specified identity when asked for CH TXT ID.SERVER.
171 Default is the name as returned by gethostname(3). Same as com‐
172 mandline option -i. See hide-identity to set the server to not
173 respond to such queries.
174 version: <string>
176 Returns the specified version string when asked for CH TXT ver‐
177 sion.server, and version.bind queries. Default is the compiled
178 package version. See hide-version to set the server to not re‐
179 spond to such queries.
180 nsid: <string>
182 Add the specified nsid to the EDNS section of the answer when
183 queried with an NSID EDNS enabled packet. As a sequence of hex
184 characters or with ascii_ prefix and then an ascii string. Same
185 as commandline option -I.
186 logfile: <filename>
188 Log messages to the logfile. The default is to log to stderr and
189 syslog (with facility LOG_DAEMON). Same as commandline option
190 -l.
191 log-only-syslog: <yes or no>
193 Log messages only to syslog. Useful with systemd so that print
194 to stderr does not cause duplicate log strings in journald. Be‐
195 fore syslog has been opened, the server uses stderr. Stderr is
196 also used if syslog is not available. Default is no.
197 server-count: <number>
199 Start this many NSD servers. Default is 1. Same as commandline
200 option -N.
201 cpu-affinity: <number> <number> ...
203 Overall CPU affinity for NSD server(s). Default is no affinity.
204 -n.
205 server-N-cpu-affinity: <number>
207 Bind NSD server specified by N to a specific core. Default is to
208 have affinity set to every core specified in cpu-affinity. This
209 setting only takes effect if cpu-affinity is enabled. -n
210 xfrd-cpu-affinity: <number>
212 Bind xfrd to a specific core. Default is to have affinity set to
213 every core specified in cpu-affinity. This setting only takes
214 effect if cpu-affinity is enabled. -n
215 tcp-count: <number>
217 The maximum number of concurrent, active TCP connections by each
218 server. Default is 100. Same as commandline option -n.
219 tcp-reject-overflow: <yes or no>
221 If set to yes, TCP connections made beyond the maximum set by
222 tcp-count will be dropped immediately (accepted and closed).
223 Default is no.
224 tcp-query-count: <number>
226 The maximum number of queries served on a single TCP connection.
227 Default is 0, meaning there is no maximum.
228 tcp-timeout: <number>
230 Overrides the default TCP timeout. This also affects zone trans‐
231 fers over TCP. The default is 120 seconds.
232 tcp-mss: <number>
234 Maximum segment size (MSS) of TCP socket on which the server re‐
235 sponds to queries. Value lower than common MSS on Ethernet (1220
236 for example) will address path MTU problem. Note that not all
237 platform supports socket option to set MSS (TCP_MAXSEG). De‐
238 fault is system default MSS determined by interface MTU and ne‐
239 gotiation between server and client.
240 outgoing-tcp-mss: <number>
242 Maximum segment size (MSS) of TCP socket for outgoing XFR re‐
243 quest to other nameservers. Value lower than common MSS on Eth‐
244 ernet (1220 for example) will address path MTU problem. Note
245 that not all platform supports socket option to set MSS
246 (TCP_MAXSEG). Default is system default MSS determined by in‐
247 terface MTU and negotiation between NSD and other servers.
248 xfrd-tcp-max: <number>
250 Number of sockets for xfrd to use for outgoing zone transfers.
251 Default 128. Increase it to allow more zone transfer sockets,
252 like to 256. To save memory, this can be lowered, set it lower
253 together with some other settings to have reduced memory foot‐
254 print for NSD. xfrd-tcp-max: 32 and xfrd-tcp-pipeline: 128 and
255 rrl-size: 1000
256 This reduces memory footprint, other memory usage is caused
258 mainly by the server-count setting, the number of server pro‐
259 cesses, and the tcp-count setting, which keeps buffers per
260 server process, and by the size of the zone data.
261 xfrd-tcp-pipeline: <number>
263 Number of simultaneous outgoing zone transfers that are possible
264 on the tcp sockets of xfrd. Max is 65536, default is 128.
265 ipv4-edns-size: <number>
267 Preferred EDNS buffer size for IPv4. Default 1232.
268 ipv6-edns-size: <number>
270 Preferred EDNS buffer size for IPv6. Default 1232.
271 pidfile: <filename>
273 Use the pid file instead of the platform specific default, usu‐
274 ally . Same as commandline option -P. With "" there is no pid‐
275 file, for some startup management setups, where a pidfile is not
276 useful to have.
277 port: <number>
279 Answer queries on the specified port. Default is 53. Same as
280 commandline option -p.
281 statistics: <number>
283 If not present no statistics are dumped. Statistics are produced
284 every number seconds. Same as commandline option -s.
285 chroot: <directory>
287 NSD will chroot on startup to the specified directory. Note that
288 if elsewhere in the configuration you specify an absolute path‐
289 name to a file inside the chroot, you have to prepend the chroot
290 path. That way, you can switch the chroot option on and off
291 without having to modify anything else in the configuration. Set
292 the value to "" (the empty string) to disable the chroot. By de‐
293 fault "" is used. Same as commandline option -t.
294 username: <username>
296 After binding the socket, drop user privileges and assume the
297 username. Can be username, id or id.gid. Same as commandline op‐
298 tion -u.
299 zonesdir: <directory>
301 Change the working directory to the specified directory before
302 accessing zone files. Also, NSD will access database, zonelist‐
303 file, logfile, pidfile, xfrdfile, xfrdir, server-key-file,
304 server-cert-file, control-key-file and control-cert-file rela‐
305 tive to this directory. Set the value to "" (the empty string)
306 to disable the change of working directory. By default
307 "/etc/nsd" is used.
308 difffile: <filename>
310 Ignored, for compatibility with NSD3 config files.
311 xfrdfile: <filename>
313 The soa timeout and zone transfer daemon in NSD will save its
314 state to this file. State is read back after a restart. The
315 state file can be deleted without too much harm, but timestamps
316 of zones will be gone. If it is configured as "", the state
317 file is not used, all slave zones are checked for updates upon
318 startup. For more details see the section on zone expiry behav‐
319 ior of NSD. Default is /var/lib/nsd/ixfr.state.
320 xfrdir: <directory>
322 The zone transfers are stored here before they are processed. A
323 directory is created here that is removed when NSD exits. De‐
324 fault is /tmp.
325 xfrd-reload-timeout: <number>
327 If this value is -1, xfrd will not trigger a reload after a zone
328 transfer. If positive xfrd will trigger a reload after a zone
329 transfer, then it will wait for the number of seconds before it
330 will trigger a new reload. Setting this value throttles the
331 reloads to once per the number of seconds. The default is 1 sec‐
332 ond.
333 verbosity: <level>
335 This value specifies the verbosity level for (non-debug) log‐
336 ging. Default is 0. 1 gives more information about incoming no‐
337 tifies and zone transfers. 2 lists soft warnings that are en‐
338 countered. 3 prints more information.
339 Verbosity 0 will print warnings and errors, and other events
341 that are important to keep NSD running.
342 Verbosity 1 prints additionally messages of interest. Success‐
344 ful notifies, successful incoming zone transfer (the zone is up‐
345 dated), failed incoming zone transfers or the inability to
346 process zone updates.
347 Verbosity 2 prints additionally soft errors, like connection re‐
349 sets over TCP. And notify refusal, and axfr request refusals.
350 hide-version: <yes or no>
352 Prevent NSD from replying with the version string on CHAOS class
353 queries. Default is no.
354 hide-identity: <yes or no>
356 Prevent NSD from replying with the identity string on CHAOS
357 class queries. Default is no.
358 drop-updates: <yes or no>
360 If set to yes, drop received packets with the UPDATE opcode.
361 Default is no.
362 use-systemd: <yes or no>
364 This option is deprecated and ignored. If compiled with libsys‐
365 temd, NSD signals readiness to systemd and use of the option is
366 not necessary.
367 log-time-ascii: <yes or no>
369 Log time in ascii, if "no" then in seconds epoch. Default is
370 yes. This chooses the format when logging to file. The print‐
371 out via syslog has a timestamp formatted by syslog.
372 round-robin: <yes or no>
374 Enable round robin rotation of records in the answer. This
375 changes the order of records in the answer and this may balance
376 load across them. The default is no.
377 minimal-responses: <yes or no>
379 Enable minimal responses for smaller answers. This makes pack‐
380 ets smaller. Extra data is only added for referrals, when it is
381 really necessary. This is different from the --enable-minimal-
382 responses configure time option, that reduces packets, but ex‐
383 actly to the fragmentation length, the nsd.conf option reduces
384 packets as small as possible. The default is no.
385 confine-to-zone: <yes or no>
387 If set to yes, additional information will not be added to the
388 response if the apex zone of the additional information does not
389 match the apex zone of the initial query (E.G. CNAME resolu‐
390 tion). Default is no.
391 refuse-any: <yes or no>
393 Refuse queries of type ANY. This is useful to stop query floods
394 trying to get large responses. Note that rrl ratelimiting also
395 has type ANY as a ratelimiting type. It sends truncation in re‐
396 sponse to UDP type ANY queries, and it allows TCP type ANY
397 queries like normal. The default is no.
398 zonefiles-check: <yes or no>
400 Make NSD check the mtime of zone files on start and sighup. If
401 you disable it it starts faster (less disk activity in case of a
402 lot of zones). The default is yes. The nsd-control reload com‐
403 mand reloads zone files regardless of this option.
404 zonefiles-write: <seconds>
406 Write changed secondary zones to their zonefile every N seconds.
407 If the zone (pattern) configuration has "" zonefile, it is not
408 written. Zones that have received zone transfer updates are
409 written to their zonefile. Default is 0 (disabled) when there
410 is a database, and 3600 (1 hour) when database is "". The data‐
411 base also commits zone transfer contents. You can configure it
412 away from the default by putting the config statement for zone‐
413 files-write: after the database: statement in the config file.
414 rrl-size: <numbuckets>
416 This option gives the size of the hashtable. Default 1000000.
417 More buckets use more memory, and reduce the chance of hash col‐
418 lisions.
419 rrl-ratelimit: <qps>
421 The max qps allowed (from one query source). Default is on (with
422 a suggested 200 qps). If set to 0 then it is disabled (unlimited
423 rate), also set the whitelist-ratelimit to 0 to disable rate‐
424 limit processing. If you set verbosity to 2 the blocked and un‐
425 blocked subnets are logged. Blocked queries are blocked and
426 some receive TCP fallback replies. Once the rate limit is
427 reached, NSD begins dropping responses. However, one in every
428 "rrl-slip" number of responses is allowed, with the TC bit set.
429 If slip is set to 2, the outgoing response rate will be halved.
430 If it's set to 3, the outgoing response rate will be one-third,
431 and so on. If you set rrl-slip to 10, traffic is reduced to
432 1/10th. Ratelimit options rrl-ratelimit, rrl-size and
433 rrl-whitelist-ratelimit are updated when nsd-control reconfig is
434 done (also the zone-specific ratelimit options are updated).
435 rrl-slip: <numpackets>
437 This option controls the number of packets discarded before we
438 send back a SLIP response (a response with "truncated" bit set
439 to one). 0 disables the sending of SLIP packets, 1 means every
440 query will get a SLIP response. Default is 2, cuts traffic in
441 half and legit users have a fair chance to get a +TC response.
442 rrl-ipv4-prefix-length: <subnet>
444 IPv4 prefix length. Addresses are grouped by netblock. Default
445 24.
446 rrl-ipv6-prefix-length: <subnet>
448 IPv6 prefix length. Addresses are grouped by netblock. Default
449 64.
450 rrl-whitelist-ratelimit: <qps>
452 The max qps for query sorts for a source, which have been
453 whitelisted. Default on (with a suggested 2000 qps). With the
454 rrl-whitelist option you can set specific queries to receive
455 this qps limit instead of the normal limit. With the value 0
456 the rate is unlimited.
457 answer-cookie: <yes or no>
459 Enable to answer to requests containing DNS Cookies as specified
460 in RFC7873. Default is no.
461 cookie-secret: <128 bit hex string>
463 Servers in an anycast deployment need to be able to verify
464 each other's DNS Server Cookies. For this they need to share
465 the secret used to construct and verify the DNS Cookies. De‐
466 fault is a 128 bits random secret generated at startup time.
467 This option is ignored if a cookie-secret-file is present. In
468 that case the secrets from that file are used in DNS Cookie cal‐
469 culations.
470 cookie-secret-file: <filename>
472 File from which the secrets are read used in DNS Cookie calcula‐
473 tions. When this file exists, the secrets in this file are used
474 and the secret specified by the cookie-secret option is ignored.
475 Default is /etc/nsd/nsd_cookiesecrets.txt
476 The content of this file must be manipulated with the
478 add_cookie_secret, drop_cookie_secret and activate_cookie_secret
479 commands to the nsd-control(8) tool. Please see that manpage how
480 to perform a safe cookie secret rollover.
481 tls-service-key: <filename>
483 If enabled, the server provides TLS service on TCP sockets with
484 the TLS service port number. The port number (853) is config‐
485 ured with tls-port. To turn it on, create an interface: option
486 line in config with @port appended to the IP-address. This cre‐
487 ates the extra socket on which the DNS over TLS service is pro‐
488 vided.
489 The file is the private key for the TLS session. The public cer‐
491 tificate is in the tls-service-pem file. Default is "", turned
492 off. Requires a restart (a reload is not enough) if changed, be‐
493 cause the private key is read while root permissions are held
494 and before chroot (if any).
495 tls-service-pem: <filename>
497 The public key certificate pem file for the tls service. Default
498 is "", turned off.
499 tls-service-ocsp: <filename>
501 The ocsp pem file for the tls service, for OCSP stapling. De‐
502 fault is "", turned off. An external process prepares and up‐
503 dates the OCSP stapling data. Like this,
504 openssl ocsp -no_nonce \
505 -respout /path/to/ocsp.pem \
506 -CAfile /path/to/ca_and_any_intermediate.pem \
507 -issuer /path/to/direct_issuer.pem \
508 -cert /path/to/cert.pem \
509 -url "$( openssl x509 -noout -text -in /path/to/cert.pem |
510 grep 'OCSP - URI:' | cut -d: -f2,3 )"
511 tls-port: <number>
513 The port number on which to provide TCP TLS service, default is
514 853, only interfaces configured with that port number as @number
515 get DNS over TLS service.
516 tls-cert-bundle: <filename>
518 If null or "", the default verify locations are used. Set it to
519 the certificate bundle file, for example "/etc/pki/tls/certs/ca-
520 bundle.crt". These certificates are used for authenticating
521 Transfer over TLS (XoT) connections.
522 Remote Control
524 The remote-control: clause is used to set options for using the
525 nsd-control(8) tool to give commands to the running NSD server. It is
526 disabled by default, and listens for localhost by default. It uses TLS
527 over TCP where the server and client authenticate to each other with
528 self-signed certificates. The self-signed certificates can be gener‐
529 ated with the nsd-control-setup tool. The key files are read by NSD
530 before the chroot and before dropping user permissions, so they can be
531 outside the chroot and readable by the superuser only.
532 control-enable: <yes or no>
534 Enable remote control, default is no.
535 control-interface: <ip4 or ip6 | interface name | absolute path>
537 NSD will bind to the listed addresses to service control re‐
538 quests (on TCP). Can be given multiple times to bind multiple
539 ip-addresses. Use 0.0.0.0 and ::0 to service the wildcard in‐
540 terface. If none are given NSD listens to the localhost
541 127.0.0.1 and ::1 interfaces for control, if control is enabled
542 with control-enable.
543 If an interface name is used instead of ip4 or ip6, the list of
545 IP addresses associated with that interface is picked up and
546 used at server start.
547 With an absolute path, a unix local named pipe is used for con‐
549 trol. The file is created with user and group that is config‐
550 ured and access bits are set to allow members of the group ac‐
551 cess. Further access can be controlled by setting permissions
552 on the directory containing the control socket file. The key
553 and cert files are not used when control is via the named pipe,
554 because access control is via file and directory permission.
555 control-port: <number>
557 The port number for remote control service. 8952 by default.
558 server-key-file: <filename>
560 Path to the server private key, by default
561 /etc/nsd/nsd_server.key. This file is generated by the nsd-con‐
562 trol-setup utility. This file is used by the nsd server, but
563 not by nsd-control.
564 server-cert-file: <filename>
566 Path to the server self signed certificate, by default
567 /etc/nsd/nsd_server.pem. This file is generated by the nsd-con‐
568 trol-setup utility. This file is used by the nsd server, and
569 also by nsd-control.
570 control-key-file: <filename>
572 Path to the control client private key, by default
573 /etc/nsd/nsd_control.key. This file is generated by the
574 nsd-control-setup utility. This file is used by nsd-control.
575 control-cert-file: <filename>
577 Path to the control client certificate, by default
578 /etc/nsd/nsd_control.pem. This certificate has to be signed
579 with the server certificate. This file is generated by the
580 nsd-control-setup utility. This file is used by nsd-control.
581 Verifier options
583 The verify: clause is used to enable or disable zone verification, con‐
584 figure listen interfaces and control the global defaults.
585 enable: <yes or no>
587 Enable zone verification. Default is no.
588 port: <number>
590 The port to answer verifier queries on. Default is 5347.
591 ip-address:
593 Interfaces to bind for zone verification (default are the local‐
594 host interfaces, usually 127.0.0.1 and ::1). To bind to multiple
595 IP addresses, list them one by one. Optionally, Socket options
596 cannot be specified for verify ip-address
597 verify-zones: <yes or no>
599 Verify zones by default.
600 verifier: <command>
602 When an update is received for the zone (by IXFR or AXFR) this
603 program will be run to assess the zone with the update. When the
604 program exists with a status code of 0, the zone is considered
605 good and will be served. Any other status code will designate
606 the zone bad and the received update will be discarded. The
607 zone will continue to be served but without the update.
608 The following environment variables are available to verifiers:
610 VERIFY_ZONE
612 The domain name of the zone to be verified.
613 VERIZFY_ZONE_ON_STDIN
614 When the zone can be read from standard input
615 (stdin), this variable is set to "yes", otherwise
616 it is set to "no".
617 VERIFY_IP_ADDRESSES
618 The first address on which the zones to be as‐
619 sessed will be served. If IPv6 is available an
620 IPv6 address will be preferred over IPv4.
621 VERIFY_PORT
622 The port number for VERIFY_IP_ADDRESS.
623 VERIFY_IPV6_ADDRESS
624 The first IPv6 address on which the zones to be
625 assessed will be served.
626 VERIFY_IPV6_PORT
627 The port number for VERIFY_IPV6_ADDRESS.
628 VERIFY_IPV4_ADDRESS
629 The first IPv4 address on which the zones to be
630 assessed will be served.
631 VERIFY_IPV4_PORT
632 The port number for VERIFY_IPV4_ADDRESS.
633 verifier-count: <number>
635 Maximum number of verifiers to run concurrently. Default is 1.
636 verifier-feed-zone: <yes or no>
638 Feed the updated zone to the verifier over standard input
639 (stdin).
640 verifier-timeout: <seconds>
642 The maximum number of seconds a verifier is allowed to run for
643 assessing one zone. If the verifier takes longer, it will be
644 terminated and the zone update will be discarded. The default is
645 0 seconds which means the verifier may take as long as it needs.
646 Pattern Options
648 The pattern: clause is used to denote a set of options to apply to some
649 zones. The same zone options as for a zone are allowed.
650 name: <string>
652 The name of the pattern. This is a (case sensitive) string.
653 The pattern names that start with "_implicit_" are used inter‐
654 nally for zones that have no pattern (they are defined in
655 nsd.conf directly).
656 include-pattern: <pattern-name>
658 The options from the given pattern are included at this point in
659 this pattern. The referenced pattern must be defined above this
660 one.
661 <zone option>: <value>
663 The zone options such as zonefile, allow-query, allow-notify,
664 request-xfr, allow-axfr-fallback, notify, notify-retry, pro‐
665 vide-xfr, store-ixfr, ixfr-number, ixfr-size, create-ixfr, zon‐
666 estats, outgoing-interface, verify-zone, verifier, veri‐
667 fier-feed-zone, and verifier-timeout can be given. They are ap‐
668 plied to the patterns and zones that include this pattern.
669 Zone Options
671 For every zone the options need to be specified in one zone: clause.
672 The access control list elements can be given multiple times to add
673 multiple servers. These elements need to be added explicitly.
674 For zones that are configured in the nsd.conf config file their set‐
676 tings are hardcoded (in an implicit pattern for themselves only) and
677 they cannot be deleted via delzone, but remove them from the config
678 file and repattern.
679 name: <string>
681 The name of the zone. This is the domain name of the apex of the
682 zone. May end with a '.' (in FQDN notation). For example "exam‐
683 ple.com", "sub.example.net.". This attribute must be present in
684 each zone.
685 zonefile: <filename>
687 The file containing the zone information. If this attribute is
688 present it is used to read and write the zone contents. If the
689 attribute is absent it prevents writing out of the zone.
690 The string is processed so that one string can be used (in a
692 pattern) for a lot of different zones. If the label or charac‐
693 ter does not exist the percent-character is replaced with a pe‐
694 riod for output (i.e. for the third character in a two letter
695 domain name).
696 %s is replaced with the zone name.
698 %1 is replaced with the first character of the zone name.
700 %2 is replaced with the second character of the zone name.
702 %3 is replaced with the third character of the zone name.
704 %z is replaced with the toplevel domain name of the zone.
706 %y is replaced with the next label under the toplevel domain.
708 %x is replaced with the next-next label under the toplevel do‐
710 main.
711 allow-query: <ip-spec> <key-name | NOKEY | BLOCKED>
713 Access control list. When at least one allow-query option is
714 specified, then the in the allow-query options specified ad‐
715 dresses are are allowed to query the server for the zone.
716 Queries from unlisted or specifically BLOCKED addresses are dis‐
717 carded. If NOKEY is given no TSIG signature is required.
718 BLOCKED supersedes other entries, other entries are scanned for
719 a match in the order of the statements. Without allow-query op‐
720 tions, queries are allowed from any IP address without TSIG key
721 (which is the default).
722 The ip-spec is either a plain IP address (IPv4 or IPv6), or can
724 be a subnet of the form 1.2.3.4/24, or masked like
725 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25.
726 Note the ip-spec ranges do not use spaces around the /, &, @ and
727 - symbols.
728 allow-notify: <ip-spec> <key-name | NOKEY | BLOCKED>
730 Access control list. The listed (primary) address is allowed to
731 send notifies to this (secondary) server. Notifies from unlisted
732 or specifically BLOCKED addresses are discarded. If NOKEY is
733 given no TSIG signature is required. BLOCKED supersedes other
734 entries, other entries are scanned for a match in the order of
735 the statements.
736 The ip-spec is either a plain IP address (IPv4 or IPv6), or can
738 be a subnet of the form 1.2.3.4/24, or masked like
739 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25.
740 A port number can be added using a suffix of @number, for exam‐
741 ple 1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. Note the
742 ip-spec ranges do not use spaces around the /, &, @ and - sym‐
743 bols.
744 request-xfr: [AXFR|UDP] <ip-address> <key-name | NOKEY> [tls-auth-name]
746 Access control list. The listed address (the master) is queried
747 for AXFR/IXFR on update. A port number can be added using a suf‐
748 fix of @number, for example 1.2.3.4@5300. The specified key is
749 used during AXFR/IXFR. If tls-auth-name is included, the speci‐
750 fied tls-auth clause will be used to perform authenticated XFR-
751 over-TLS.
752 If the AXFR option is given, the server will not be contacted
754 with IXFR queries but only AXFR requests will be made to the
755 server. This allows an NSD secondary to have a master server
756 that runs NSD. If the AXFR option is left out then both IXFR and
757 AXFR requests are made to the master server.
758 If the UDP option is given, the secondary will use UDP to trans‐
760 mit the IXFR requests. You should deploy TSIG when allowing UDP
761 transport, to authenticate notifies and zone transfers. Other‐
762 wise, NSD is more vulnerable for Kaminsky-style attacks. If the
763 UDP option is left out then IXFR will be transmitted using TCP.
764 If a tls-auth-name is given then TLS (by default on port 853)
766 will be used for all zone transfers for the zone. If authentica‐
767 tion of the master based on the specified tls-auth authentica‐
768 tion information fails, the XFR request will not be sent. Sup‐
769 port for TLS 1.3 is required for XFR-over-TLS.
770 allow-axfr-fallback: <yes or no>
772 This option should be accompanied by request-xfr. It (dis)allows
773 NSD (as secondary) to fallback to AXFR if the primary name
774 server does not support IXFR. Default is yes.
775 size-limit-xfr: <number>
777 This option should be accompanied by request-xfr. It specifies
778 XFR temporary file size limit. It can be used to stop very
779 large zone retrieval, that could otherwise use up a lot of mem‐
780 ory and disk space. If this option is 0, unlimited. Default
781 value is 0.
782 notify: <ip-address> <key-name | NOKEY>
784 Access control list. The listed address (a secondary) is noti‐
785 fied of updates to this zone. A port number can be added using a
786 suffix of @number, for example 1.2.3.4@5300. The specified key
787 is used to sign the notify. Only on secondary configurations
788 will NSD be able to detect zone updates (as it gets notified it‐
789 self, or refreshes after a time).
790 notify-retry: <number>
792 This option should be accompanied by notify. It sets the number
793 of retries when sending notifies.
794 provide-xfr: <ip-spec> <key-name | NOKEY | BLOCKED>
796 Access control list. The listed address (a secondary) is allowed
797 to request AXFR from this server. Zone data will be provided to
798 the address. The specified key is used during AXFR. For unlisted
799 or BLOCKED addresses no data is provided, requests are dis‐
800 carded. BLOCKED supersedes other entries, other entries are
801 scanned for a match in the order of the statements. NSD pro‐
802 vides AXFR for its secondaries, but IXFR is not implemented
803 (IXFR is implemented for request-xfr, but not for provide-xfr).
804 The ip-spec is either a plain IP address (IPv4 or IPv6), or can
806 be a subnet of the form 1.2.3.4/24, or masked like
807 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25.
808 A port number can be added using a suffix of @number, for exam‐
809 ple 1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. Note the
810 ip-spec ranges do not use spaces around the /, &, @ and - sym‐
811 bols.
812 outgoing-interface: <ip-address>
814 Access control list. The listed address is used to request
815 AXFR|IXFR (in case of a secondary) or used to send notifies (in
816 case of a primary).
817 The ip-address is a plain IP address (IPv4 or IPv6). A port
819 number can be added using a suffix of @number, for example
820 1.2.3.4@5300.
821 store-ixfr: <yes or no>
823 If enabled, IXFR contents are stored and provided to the set of
824 clients specified in the provide-xfr statement. Default is no.
825 IXFR contents is a smaller set of changes that differ between
826 zone versions, where an AXFR contains the full contents of the
827 zone.
828 ixfr-number: <number>
830 The number of IXFR versions to store for this zone, at most. De‐
831 fault is 5.
832 ixfr-size: <number>
834 The max storage to use for IXFR versions for this zone, in
835 bytes. Default is 1048576. A value of 0 means unlimited, if you
836 want to turn off IXFR storage, use the store-ixfr option. NSD
837 does not elide IXFR contents from versions that add and remove
838 the same data, that merges version changes together to shorten
839 the data, but leaves the data and change sequence as it was
840 transmitted by another server.
841 create-ixfr: <yes or no>
843 If enabled, IXFR data is created when a zonefile is read by the
844 server. Also set store-ixfr enabled, so that the contents are
845 stored, when you use this. Default is off. If the server is not
846 running, the nsd-checkzone -i option can be used to create an
847 IXFR file. When an IXFR is created, the server spools a version
848 of the zone to a temporary file, at the location where the ixfr
849 files are stored. This creates IXFR data when the zone is read
850 from file, but not when a zone is read by AXFR transfer from a
851 server, because then the topmost server that originates the data
852 is the one place where ixfr differences are computed and those
853 differences are then transmitted verbatim to all the other
854 servers.
855 max-refresh-time: <seconds>
857 Limit refresh time for secondary zones. This is the timer which
858 checks to see if the zone has to be refetched when it expires.
859 Normally the value from the SOA record is used, but this option
860 restricts that value.
861 min-refresh-time: <seconds>
863 Limit refresh time for secondary zones.
864 max-retry-time: <seconds>
866 Limit retry time for secondary zones. This is the timer which
867 retries after a failed fetch attempt for the zone. Normally the
868 value from the SOA record is used, followed by an exponential
869 backoff, but this option restricts that value.
870 min-retry-time: <seconds>
872 Limit retry time for secondary zones.
873 min-expire-time: <seconds or refresh+retry+1>
875 Limit expire time for secondary zones. The value can be ex‐
876 pressed either by a number of seconds, or the string "re‐
877 fresh+retry+1". With the latter the expire time will be lower
878 bound to the refresh plus the retry value from the SOA record,
879 plus 1. The refresh and retry values will be subject to the
880 bounds configured with max-refresh-time, min-refresh-time,
881 max-retry-time and min-retry-time if given.
882 zonestats: <name>
884 When compiled with --enable-zone-stats NSD can collect statis‐
885 tics per zone. This name gives the group where statistics are
886 added to. The groups are output from nsd-control stats and
887 stats_noreset. Default is "". You can use "%s" to use the name
888 of the zone to track its statistics. If not compiled in, the
889 option can be given but is ignored.
890 include-pattern: <pattern-name>
892 The options from the given pattern are included at this point.
893 The referenced pattern must be defined above this zone.
894 rrl-whitelist: <rrltype>
896 This option causes queries of this rrltype to be whitelisted,
897 for this zone. They receive the whitelist-ratelimit. You can
898 give multiple lines, each enables a new rrltype to be
899 whitelisted for the zone. Default has none whitelisted. The rrl‐
900 type is the query classification that the NSD RRL employs to
901 make different types not interfere with one another. The types
902 are logged in the loglines when a subnet is blocked (in ver‐
903 bosity 2). The RRL classification types are: nxdomain, error,
904 referral, any, rrsig, wildcard, nodata, dnskey, positive, all.
905 multi-master-check: <yes or no>
907 Default no. If enabled, checks all masters for the last ver‐
908 sion. It uses the higher version of all the configured masters.
909 Useful if you have multiple masters that have different version
910 numbers served.
911 verify-zone: <yes or no>
913 Enable or disable verification for this zone. Default is
914 value-zones configured in verify:.
915 verifier: <command>
917 Command to execute to assess this zone. Default is verifier con‐
918 figured in verify:.
919 verifier-feed-zone: <yes or no>
921 Feed updated zone to verifier over standard input. Default is
922 verifier-feed-zone configured in verify:.
923 verifier-timeout: <seconds>
925 Number of seconds before verifier is forcefully terminated.
926 Specify 0 (zero) to not use a specific timeout. Default is veri‐
927 fier-timeout from verify:.
928 Key Declarations
930 The key: clause establishes a key for use in access control lists. It
931 has the following attributes.
932 name: <string>
934 The key name. Used to refer to this key in the access control
935 list. The key name has to be correct for tsig to work. This is
936 because the key name is output on the wire.
937 algorithm: <string>
939 Authentication algorithm for this key. Such as hmac-md5,
940 hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384 and
941 hmac-sha512. Can also be abbreviated as 'sha1', 'sha256'. De‐
942 fault is sha256. Algorithms are only available when they were
943 compiled in (available in the crypto library).
944 secret: <base64 blob>
946 The base64 encoded shared secret. It is possible to put the se‐
947 cret: declaration (and base64 blob) into a different file, and
948 then to include: that file. In this way the key secret and the
949 rest of the configuration file, which may have different secu‐
950 rity policies, can be split apart. The content of the secret is
951 the agreed base64 secret content. To make it up, enter a pass‐
952 word (its length must be a multiple of 4 characters, A-Za-z0-9),
953 or use dev-random output through a base64 encode filter.
954 TLS Auth Declarations
956 The tls-auth: clause establishes authentication attributes to use when
957 authenticating the far end of an outgoing TLS connection used in access
958 control lists for XFR-over-TLS. It has the following attributes.
959 name: <string>
961 The tls-auth name. Used to refer to this TLS authentication in‐
962 formation in the access control list.
963 auth-domain-name: <string>
965 The authentication domain name as defined in RFC8310.
966 client-cert: <file name of clientcert.pem>
968 If you want to use mutual TLS authentication, this is where the
969 client certificates can be configured that NSD uses to connect
970 to the upstream server to download the zone. The client public
971 key pem cert file can be configured here. Also configure a pri‐
972 vate key with client-key.
973 client-key: <file name of clientkey.key>
975 If you want to use mutual TLS authentication, the private key
976 file can be configured here for the client authentication.
977 client-key-pw: <string>
979 If the client-key file uses a password to decrypt the key before
980 it can be used, then the password can be specified here as a
981 string. It is possible to include other config files with the
982 include: option, and this can be used to move that sensitive
983 data to another file, if you wish.
984 DNSTAP Logging Options
986 DNSTAP support, when compiled in, is enabled in the dnstap: section.
987 This starts a collector process that writes the log information to the
988 destination.
989 dnstap-enable: <yes or no>
991 If dnstap is enabled. Default no. If yes, it connects to the
992 dnstap server and if any of the dnstap-log-..-messages options
993 is enabled it sends logs for those messages to the server.
994 dnstap-socket-path: <file name>
996 Sets the unix socket file name for connecting to the server that
997 is listening on that socket. Default is "/var/run/nsd-
998 dnstap.sock".
999 dnstap-ip: <"" or addr[@port]>
1001 If disabled with "", the socket path is used. With a value, like
1002 address or address@port, like "127.0.0.1@3333" TCP or TLS is
1003 used. Default is "".
1004 dnstap-tls: <yes or no>
1006 If enabled, TLS is used to the address specified in dnstap-ip.
1007 Otherwise, TCP is used. Default is yes.
1008 dnstap-tls-server-name: <string>
1010 The name for authenticating the upstream server. With "" dis‐
1011 abled.
1012 dnstap-tls-client-key-file: <file name>
1014 The key file for client authentication, or "" disabled.
1015 dnstap-tls-client-cert-file: <file name>
1017 The cert file for client authentication, or "" disabled.
1018 dnstap-send-identity: <yes or no>
1020 If enabled, the server identity is included in the log messages.
1021 Default is no.
1022 dnstap-send-version: <yes or no>
1024 If enabled, the server version if included in the log messages.
1025 Default is no.
1026 dnstap-identity: <string>
1028 The identity to send with messages, if "" the hostname is used.
1029 Default is "".
1030 dnstap-version: <string>
1032 The version to send with messages, if "" the package version is
1033 used. Default is "".
1034 dnstap-log-auth-query-messages: <yes or no>
1036 Enable to log auth query messages. Default is no. These are
1037 client queries to NSD.
1038 dnstap-log-auth-response-messages: <yes or no>
1040 Enable to log auth response messages. Default is no. These are
1041 responses from NSD to clients.
1042
1044 BIND9 is a name server implementation with its own configuration file
1045 format, named.conf(5). BIND9 types zones as 'Master' or 'Slave'.
1046 Slave zones
1048 For a slave zone, the master servers are listed. The master servers are
1049 queried for zone data, and are listened to for update notifications.
1050 In NSD these two properties need to be configured separately, by list‐
1051 ing the master address in allow-notify and request-xfr statements.
1052 In BIND9 you only need to provide allow-notify elements for any extra
1054 sources of notifications (i.e. the operators), NSD needs to have al‐
1055 low-notify for both masters and operators. BIND9 allows additional
1056 transfer sources, in NSD you list those as request-xfr.
1057 Here is an example of a slave zone in BIND9 syntax.
1059 # Config file for example.org options {
1061 dnssec-enable yes;
1062 };
1063 key tsig.example.org. {
1065 algorithm hmac-md5;
1066 secret "aaaaaabbbbbbccccccdddddd";
1067 };
1068 server 162.0.4.49 {
1070 keys { tsig.example.org. ; };
1071 };
1072 zone "example.org" {
1074 type slave;
1075 file "secondary/example.org.signed";
1076 masters { 162.0.4.49; };
1077 };
1078 For NSD, DNSSEC is enabled automatically for zones that are signed. The
1080 dnssec-enable statement in the options clause is not needed. In NSD
1081 keys are associated with an IP address in the access control list
1082 statement, therefore the server{} statement is not needed. Below is the
1083 same example in an NSD config file.
1084 # Config file for example.org
1086 key:
1087 name: tsig.example.org.
1088 algorithm: hmac-md5
1089 secret: "aaaaaabbbbbbccccccdddddd"
1090 zone:
1092 name: "example.org"
1093 zonefile: "secondary/example.org.signed"
1094 # the master is allowed to notify and will provide zone data.
1095 allow-notify: 162.0.4.49 NOKEY
1096 request-xfr: 162.0.4.49 tsig.example.org.
1097 Notice that the master is listed twice, once to allow it to send noti‐
1099 fies to this slave server and once to tell the slave server where to
1100 look for updates zone data. More allow-notify and request-xfr lines can
1101 be added to specify more masters.
1102 It is possible to specify extra allow-notify lines for addresses that
1104 are also allowed to send notifications to this slave server.
1105 Master zones
1107 For a master zone in BIND9, the slave servers are listed. These slave
1108 servers are sent notifications of updated and are allowed to request
1109 transfer of the zone data. In NSD these two properties need to be con‐
1110 figured separately.
1111 Here is an example of a master zone in BIND9 syntax.
1113 zone "example.nl" {
1115 type master;
1116 file "example.nl";
1117 };
1118 In NSD syntax this becomes:
1120 zone:
1122 name: "example.nl"
1123 zonefile: "example.nl"
1124 # allow anybody to request xfr.
1125 provide-xfr: 0.0.0.0/0 NOKEY
1126 provide-xfr: ::0/0 NOKEY
1127 # to list a slave server you would in general give
1129 # provide-xfr: 1.2.3.4 tsig-key.name.
1130 # notify: 1.2.3.4 NOKEY
1131 Other
1133 NSD is an authoritative only DNS server. This means that it is meant as
1134 a primary or secondary server for zones, providing DNS data to DNS re‐
1135 solvers and caches. BIND9 can function as an authoritative DNS server,
1136 the configuration options for that are compared with those for NSD in
1137 this section. However, BIND9 can also function as a resolver or cache.
1138 The configuration options that BIND9 has for the resolver or caching
1139 thus have no equivalents for NSD.
1140
1142 "" default NSD database
1143 /etc/nsd/nsd.conf
1145 default NSD configuration file
1146
1148 nsd(8), nsd-checkconf(8), nsd-control(8)
1149
1151 NSD was written by NLnet Labs and RIPE NCC joint team. Please see CRED‐
1152 ITS file in the distribution for further details.
1153
1155 nsd.conf is parsed by a primitive parser, error messages may not be to
1156 the point.
1157NLnet Labs Jun 7, 2023 nsd.conf(5)