1nsd.conf(5) nsd 4.3.8 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:, key:, pattern:, zone:, tls-auth:, and
65 remote-control: are allowed. These are followed by their attributes or
66 a new top-level keyword. The zone: attribute is followed by zone op‐
67 tions. The server: attribute is followed by global options for the NSD
68 server. A key: attribute is used to define keys for authentication. The
69 pattern: attribute is followed by the zone options for zones that use
70 the pattern. A tls-auth: attribute is used to define credentials for
71 authenticating an outgoing TLS connection used for XFR-over-TLS.
72 Files can be included using the include: directive. It can appear any‐
74 where, and takes a single filename as an argument. Processing continues
75 as if the text from the included file was copied into the config file
76 at that point. If a chroot is used an absolute filename is needed
77 (with the chroot prepended), so that the include can be parsed before
78 and after application of the chroot (and the knowledge of what that ch‐
79 root is). You can use '*' to include a wildcard match of files, eg.
80 "foo/nsd.d/*.conf". Also '?', '{}', '[]', and '~' work, see glob(7).
81 If no files match the pattern, this is not an error.
82 Server Options
84 The global options (if not overridden from the NSD commandline) are
85 taken from the server: clause. There may only be one server: clause.
86 ip-address: <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
88 NSD will bind to the listed ip-address. Can be given multiple
89 times to bind multiple ip-addresses. Optionally, a port number
90 can be given. If none are given NSD listens to the wildcard in‐
91 terface. Same as commandline option -a.
92 To limit which NSD server(s) listen on the given interface,
94 specify one or more servers separated by whitespace after
95 <ip>[@port]. Ranges can be used as a shorthand to specify multi‐
96 ple consecutive servers. By default every server will listen.
97 If an interface name is used instead of ip4 or ip6, the list of
99 IP addresses associated with that interface is picked up and
100 used at server start.
101 For servers with multiple IP addresses that can be used to send
103 traffic to the internet, list them one by one, or the source ad‐
104 dress of replies could be wrong. This is because if the udp
105 socket associates a source address of 0.0.0.0 then the kernel
106 picks an ip-address with which to send to the internet, and it
107 picks the wrong one. Typically needed for anycast instances.
108 Use ip-transparent to be able to list addresses that turn on
109 later (typical for certain load-balancing).
110 interface: <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
112 Same as ip-address (for ease of compatibility with un‐
113 bound.conf).
114 ip-transparent: <yes or no>
116 Allows NSD to bind to non local addresses. This is useful to
117 have NSD listen to IP addresses that are not (yet) added to the
118 network interface, so that it can answer immediately when the
119 address is added. Default is no.
120 ip-freebind: <yes or no>
122 Set the IP_FREEBIND option to bind to nonlocal addresses and in‐
123 terfaces that are down. Similar to ip-transparent. Default is
124 no.
125 reuseport: <yes or no>
127 Use the SO_REUSEPORT socket option, and create file descriptors
128 for every server in the server-count. This improves performance
129 of the network stack. Only really useful if you also configure
130 a server-count higher than 1 (such as, equal to the number of
131 cpus). The default is no. It works on Linux, but does not work
132 on FreeBSD, and likely does not work on other systems.
133 send-buffer-size: <number>
135 Set the send buffer size for query-servicing sockets. Set to 0
136 to use the default settings.
137 receive-buffer-size: <number>
139 Set the receive buffer size for query-servicing sockets. Set to
140 0 to use the default settings.
141 debug-mode: <yes or no>
143 Turns on debugging mode for nsd, does not fork a daemon process.
144 Default is no. Same as commandline option -d. If set to yes it
145 does not fork and stays in the foreground, which can be helpful
146 for commandline debugging, but is also used by certain server
147 supervisor processes to ascertain that the server is running.
148 do-ip4: <yes or no>
150 If yes, NSD listens to IPv4 connections. Default yes.
151 do-ip6: <yes or no>
153 If yes, NSD listens to IPv6 connections. Default yes.
154 database: <filename>
156 By default '' is used. The specified file is used to store the
157 compiled zone information. Same as commandline option -f. If
158 set to "" then no database is used. This uses less memory but
159 zone updates are not (immediately) spooled to disk.
160 zonelistfile: <filename>
162 By default /var/lib/nsd/zone.list is used. The specified file is
163 used to store the dynamically added list of zones. The list is
164 written to by NSD to add and delete zones. It is a text file
165 with a zone-name and pattern-name on each line. This file is
166 used for the nsd-control addzone and delzone commands.
167 identity: <string>
169 Returns the specified identity when asked for CH TXT ID.SERVER.
170 Default is the name as returned by gethostname(3). Same as com‐
171 mandline option -i. See hide-identity to set the server to not
172 respond to such queries.
173 version: <string>
175 Returns the specified version string when asked for CH TXT ver‐
176 sion.server, and version.bind queries. Default is the compiled
177 package version. See hide-version to set the server to not re‐
178 spond to such queries.
179 nsid: <string>
181 Add the specified nsid to the EDNS section of the answer when
182 queried with an NSID EDNS enabled packet. As a sequence of hex
183 characters or with ascii_ prefix and then an ascii string. Same
184 as commandline option -I.
185 logfile: <filename>
187 Log messages to the logfile. The default is to log to stderr and
188 syslog (with facility LOG_DAEMON). Same as commandline option
189 -l.
190 log-only-syslog: <yes or no>
192 Log messages only to syslog. Useful with systemd so that print
193 to stderr does not cause duplicate log strings in journald. Be‐
194 fore syslog has been opened, the server uses stderr. Stderr is
195 also used if syslog is not available. Default is no.
196 server-count: <number>
198 Start this many NSD servers. Default is 1. Same as commandline
199 option -N.
200 cpu-affinity: <number> <number> ...
202 Overall CPU affinity for NSD server(s). Default is no affinity.
203 -n.
204 server-N-cpu-affinity: <number>
206 Bind NSD server specified by N to a specific core. Default is to
207 have affinity set to every core specified in cpu-affinity. This
208 setting only takes effect if cpu-affinity is enabled. -n
209 xfrd-cpu-affinity: <number>
211 Bind xfrd to a specific core. Default is to have affinity set to
212 every core specified in cpu-affinity. This setting only takes
213 effect if cpu-affinity is enabled. -n
214 tcp-count: <number>
216 The maximum number of concurrent, active TCP connections by each
217 server. Default is 100. Same as commandline option -n.
218 tcp-reject-overflow: <yes or no>
220 If set to yes, TCP connections made beyond the maximum set by
221 tcp-count will be dropped immediately (accepted and closed).
222 Default is no.
223 tcp-query-count: <number>
225 The maximum number of queries served on a single TCP connection.
226 Default is 0, meaning there is no maximum.
227 tcp-timeout: <number>
229 Overrides the default TCP timeout. This also affects zone trans‐
230 fers over TCP. The default is 120 seconds.
231 tcp-mss: <number>
233 Maximum segment size (MSS) of TCP socket on which the server re‐
234 sponds to queries. Value lower than common MSS on Ethernet (1220
235 for example) will address path MTU problem. Note that not all
236 platform supports socket option to set MSS (TCP_MAXSEG). De‐
237 fault is system default MSS determined by interface MTU and ne‐
238 gotiation between server and client.
239 outgoing-tcp-mss: <number>
241 Maximum segment size (MSS) of TCP socket for outgoing XFR re‐
242 quest to other namesevers. Value lower than common MSS on Ether‐
243 net (1220 for example) will address path MTU problem. Note that
244 not all platform supports socket option to set MSS (TCP_MAXSEG).
245 Default is system default MSS determined by interface MTU and
246 negotiation between NSD and other servers.
247 ipv4-edns-size: <number>
249 Preferred EDNS buffer size for IPv4. Default 1232.
250 ipv6-edns-size: <number>
252 Preferred EDNS buffer size for IPv6. Default 1232.
253 pidfile: <filename>
255 Use the pid file instead of the platform specific default, usu‐
256 ally . Same as commandline option -P. With "" there is no pid‐
257 file, for some startup management setups, where a pidfile is not
258 useful to have.
259 port: <number>
261 Answer queries on the specified port. Default is 53. Same as
262 commandline option -p.
263 statistics: <number>
265 If not present no statistics are dumped. Statistics are produced
266 every number seconds. Same as commandline option -s.
267 chroot: <directory>
269 NSD will chroot on startup to the specified directory. Note that
270 if elsewhere in the configuration you specify an absolute path‐
271 name to a file inside the chroot, you have to prepend the chroot
272 path. That way, you can switch the chroot option on and off
273 without having to modify anything else in the configuration. Set
274 the value to "" (the empty string) to disable the chroot. By de‐
275 fault "" is used. Same as commandline option -t.
276 username: <username>
278 After binding the socket, drop user privileges and assume the
279 username. Can be username, id or id.gid. Same as commandline op‐
280 tion -u.
281 zonesdir: <directory>
283 Change the working directory to the specified directory before
284 accessing zone files. Also, NSD will access database, zonelist‐
285 file, logfile, pidfile, xfrdfile, xfrdir, server-key-file,
286 server-cert-file, control-key-file and control-cert-file rela‐
287 tive to this directory. Set the value to "" (the empty string)
288 to disable the change of working directory. By default
289 "/etc/nsd" is used.
290 difffile: <filename>
292 Ignored, for compatibility with NSD3 config files.
293 xfrdfile: <filename>
295 The soa timeout and zone transfer daemon in NSD will save its
296 state to this file. State is read back after a restart. The
297 state file can be deleted without too much harm, but timestamps
298 of zones will be gone. If it is configured as "", the state
299 file is not used, all slave zones are checked for updates upon
300 startup. For more details see the section on zone expiry behav‐
301 ior of NSD. Default is /var/lib/nsd/ixfr.state.
302 xfrdir: <directory>
304 The zone transfers are stored here before they are processed. A
305 directory is created here that is removed when NSD exits. De‐
306 fault is /tmp.
307 xfrd-reload-timeout: <number>
309 If this value is -1, xfrd will not trigger a reload after a zone
310 transfer. If positive xfrd will trigger a reload after a zone
311 transfer, then it will wait for the number of seconds before it
312 will trigger a new reload. Setting this value throttles the
313 reloads to once per the number of seconds. The default is 1 sec‐
314 ond.
315 verbosity: <level>
317 This value specifies the verbosity level for (non-debug) log‐
318 ging. Default is 0. 1 gives more information about incoming no‐
319 tifies and zone transfers. 2 lists soft warnings that are en‐
320 countered. 3 prints more information.
321 Verbosity 0 will print warnings and errors, and other events
323 that are important to keep NSD running.
324 Verbosity 1 prints additionally messages of interest. Success‐
326 ful notifies, successful incoming zone transfer (the zone is up‐
327 dated), failed incoming zone transfers or the inability to
328 process zone updates.
329 Verbosity 2 prints additionally soft errors, like connection re‐
331 sets over TCP. And notify refusal, and axfr request refusals.
332 hide-version: <yes or no>
334 Prevent NSD from replying with the version string on CHAOS class
335 queries. Default is no.
336 hide-identity: <yes or no>
338 Prevent NSD from replying with the identity string on CHAOS
339 class queries. Default is no.
340 drop-updates: <yes or no>
342 If set to yes, drop received packets with the UPDATE opcode.
343 Default is no.
344 use-systemd: <yes or no>
346 This option is deprecated and ignored. If compiled with libsys‐
347 temd, NSD signals readiness to systemd and use of the option is
348 not necessary.
349 log-time-ascii: <yes or no>
351 Log time in ascii, if "no" then in seconds epoch. Default is
352 yes. This chooses the format when logging to file. The print‐
353 out via syslog has a timestamp formatted by syslog.
354 round-robin: <yes or no>
356 Enable round robin rotation of records in the answer. This
357 changes the order of records in the answer and this may balance
358 load across them. The default is no.
359 minimal-responses: <yes or no>
361 Enable minimal responses for smaller answers. This makes pack‐
362 ets smaller. Extra data is only added for referrals, when it is
363 really necessary. This is different from the --enable-minimal-
364 responses configure time option, that reduces packets, but ex‐
365 actly to the fragmentation length, the nsd.conf option reduces
366 packets as small as possible. The default is no.
367 confine-to-zone: <yes or no>
369 If set to yes, additional information will not be added to the
370 response if the apex zone of the additional information does not
371 match the apex zone of the initial query (E.G. CNAME resolu‐
372 tion). Default is no.
373 refuse-any: <yes or no>
375 Refuse queries of type ANY. This is useful to stop query floods
376 trying to get large responses. Note that rrl ratelimiting also
377 has type ANY as a ratelimiting type. It sends truncation in re‐
378 sponse to UDP type ANY queries, and it allows TCP type ANY
379 queries like normal. The default is no.
380 zonefiles-check: <yes or no>
382 Make NSD check the mtime of zone files on start and sighup. If
383 you disable it it starts faster (less disk activity in case of a
384 lot of zones). The default is yes. The nsd-control reload com‐
385 mand reloads zone files regardless of this option.
386 zonefiles-write: <seconds>
388 Write changed secondary zones to their zonefile every N seconds.
389 If the zone (pattern) configuration has "" zonefile, it is not
390 written. Zones that have received zone transfer updates are
391 written to their zonefile. Default is 0 (disabled) when there
392 is a database, and 3600 (1 hour) when database is "". The data‐
393 base also commits zone transfer contents. You can configure it
394 away from the default by putting the config statement for zone‐
395 files-write: after the database: statement in the config file.
396 rrl-size: <numbuckets>
398 This option gives the size of the hashtable. Default 1000000.
399 More buckets use more memory, and reduce the chance of hash col‐
400 lisions.
401 rrl-ratelimit: <qps>
403 The max qps allowed (from one query source). Default is on (with
404 a suggested 200 qps). If set to 0 then it is disabled (unlimited
405 rate), also set the whitelist-ratelimit to 0 to disable rate‐
406 limit processing. If you set verbosity to 2 the blocked and un‐
407 blocked subnets are logged. Blocked queries are blocked and
408 some receive TCP fallback replies. Once the rate limit is
409 reached, NSD begins dropping responses. However, one in every
410 "rrl-slip" number of responses is allowed, with the TC bit set.
411 If slip is set to 2, the outgoing response rate will be halved.
412 If it's set to 3, the outgoing response rate will be one-third,
413 and so on. If you set rrl-slip to 10, traffic is reduced to
414 1/10th. Ratelimit options rrl-ratelimit, rrl-size and
415 rrl-whitelist-ratelimit are updated when nsd-control reconfig is
416 done (also the zone-specific ratelimit options are updated).
417 rrl-slip: <numpackets>
419 This option controls the number of packets discarded before we
420 send back a SLIP response (a response with "truncated" bit set
421 to one). 0 disables the sending of SLIP packets, 1 means every
422 query will get a SLIP response. Default is 2, cuts traffic in
423 half and legit users have a fair chance to get a +TC response.
424 rrl-ipv4-prefix-length: <subnet>
426 IPv4 prefix length. Addresses are grouped by netblock. Default
427 24.
428 rrl-ipv6-prefix-length: <subnet>
430 IPv6 prefix length. Addresses are grouped by netblock. Default
431 64.
432 rrl-whitelist-ratelimit: <qps>
434 The max qps for query sorts for a source, which have been
435 whitelisted. Default on (with a suggested 2000 qps). With the
436 rrl-whitelist option you can set specific queries to receive
437 this qps limit instead of the normal limit. With the value 0
438 the rate is unlimited.
439 answer-cookie: <yes or no>
441 Enable to answer to requests containig DNS Cookies as specified
442 in RFC7873. Default is no.
443 cookie-secret: <128 bit hex string>
445 Servers in an anycast deployment need to be able to verify
446 each other's DNS Server Cookies. For this they need to share
447 the secret used to construct and verify the DNS Cookies. De‐
448 fault is a 128 bits random secret generated at startup time.
449 This option is ignored if a cookie-secret-file is present. In
450 that case the secrets from that file are used in DNS Cookie cal‐
451 culations.
452 cookie-secret-file: <filename>
454 File from which the secrets are read used in DNS Cookie calcula‐
455 tions. When this file exists, the secrets in this file are used
456 and the secret specified by the cookie-secret option is ignored.
457 Default is /etc/nsd/nsd_cookiesecrets.txt
458 The content of this file must be manipulated with the
460 add_cookie_secret, drop_cookie_secret and activate_cookie_secret
461 commands to the nsd-control(8) tool. Please see that manpage how
462 to perform a safe cookie secret rollover.
463 tls-service-key: <filename>
465 If enabled, the server provides TLS service on TCP sockets with
466 the TLS service port number. The port number (853) is config‐
467 ured with tls-port. To turn it on, create an interface: option
468 line in config with @port appended to the IP-address. This cre‐
469 ates the extra socket on which the DNS over TLS service is pro‐
470 vided.
471 The file is the private key for the TLS session. The public cer‐
473 tificate is in the tls-service-pem file. Default is "", turned
474 off. Requires a restart (a reload is not enough) if changed, be‐
475 cause the private key is read while root permissions are held
476 and before chroot (if any).
477 tls-service-pem: <filename>
479 The public key certificate pem file for the tls service. Default
480 is "", turned off.
481 tls-service-ocsp: <filename>
483 The ocsp pem file for the tls service, for OCSP stapling. De‐
484 fault is "", turned off. An external process prepares and up‐
485 dates the OCSP stapling data. Like this,
486 openssl ocsp -no_nonce \
487 -respout /path/to/ocsp.pem \
488 -CAfile /path/to/ca_and_any_intermediate.pem \
489 -issuer /path/to/direct_issuer.pem \
490 -cert /path/to/cert.pem \
491 -url "$( openssl x509 -noout -text -in /path/to/cert.pem |
492 grep 'OCSP - URI:' | cut -d: -f2,3 )"
493 tls-port: <number>
495 The port number on which to provide TCP TLS service, default is
496 853, only interfaces configured with that port number as @number
497 get DNS over TLS service.
498 tls-cert-bundle: <filename>
500 If null or "", the default verify locations are used. Set it to
501 the certificate bundle file, for example "/etc/pki/tls/certs/ca-
502 bundle.crt". These certificates are used for authenticating
503 Transfer over TLS (XoT) connections.
504 Remote Control
506 The remote-control: clause is used to set options for using the
507 nsd-control(8) tool to give commands to the running NSD server. It is
508 disabled by default, and listens for localhost by default. It uses TLS
509 over TCP where the server and client authenticate to each other with
510 self-signed certificates. The self-signed certificates can be gener‐
511 ated with the nsd-control-setup tool. The key files are read by NSD
512 before the chroot and before dropping user permissions, so they can be
513 outside the chroot and readable by the superuser only.
514 control-enable: <yes or no>
516 Enable remote control, default is no.
517 control-interface: <ip4 or ip6 | interface name | absolute path>
519 NSD will bind to the listed addresses to service control re‐
520 quests (on TCP). Can be given multiple times to bind multiple
521 ip-addresses. Use 0.0.0.0 and ::0 to service the wildcard in‐
522 terface. If none are given NSD listens to the localhost
523 127.0.0.1 and ::1 interfaces for control, if control is enabled
524 with control-enable.
525 If an interface name is used instead of ip4 or ip6, the list of
527 IP addresses associated with that interface is picked up and
528 used at server start.
529 With an absolute path, a unix local named pipe is used for con‐
531 trol. The file is created with user and group that is config‐
532 ured and access bits are set to allow members of the group ac‐
533 cess. Further access can be controlled by setting permissions
534 on the directory containing the control socket file. The key
535 and cert files are not used when control is via the named pipe,
536 because access control is via file and directory permission.
537 control-port: <number>
539 The port number for remote control service. 8952 by default.
540 server-key-file: <filename>
542 Path to the server private key, by default
543 /etc/nsd/nsd_server.key. This file is generated by the nsd-con‐
544 trol-setup utility. This file is used by the nsd server, but
545 not by nsd-control.
546 server-cert-file: <filename>
548 Path to the server self signed certificate, by default
549 /etc/nsd/nsd_server.pem. This file is generated by the nsd-con‐
550 trol-setup utility. This file is used by the nsd server, and
551 also by nsd-control.
552 control-key-file: <filename>
554 Path to the control client private key, by default
555 /etc/nsd/nsd_control.key. This file is generated by the
556 nsd-control-setup utility. This file is used by nsd-control.
557 control-cert-file: <filename>
559 Path to the control client certificate, by default
560 /etc/nsd/nsd_control.pem. This certificate has to be signed
561 with the server certificate. This file is generated by the
562 nsd-control-setup utility. This file is used by nsd-control.
563 Pattern Options
565 The pattern: clause is used to denote a set of options to apply to some
566 zones. The same zone options as for a zone are allowed.
567 name: <string>
569 The name of the pattern. This is a (case sensitive) string.
570 The pattern names that start with "_implicit_" are used inter‐
571 nally for zones that have no pattern (they are defined in
572 nsd.conf directly).
573 include-pattern: <pattern-name>
575 The options from the given pattern are included at this point in
576 this pattern. The referenced pattern must be defined above this
577 one.
578 <zone option>: <value>
580 The zone options such as zonefile, allow-query, allow-notify,
581 request-xfr, allow-axfr-fallback, notify, notify-retry, pro‐
582 vide-xfr, zonestats, and outgoing-interface can be given. They
583 are applied to the patterns and zones that include this pattern.
584 Zone Options
586 For every zone the options need to be specified in one zone: clause.
587 The access control list elements can be given multiple times to add
588 multiple servers. These elements need to be added explicitly.
589 For zones that are configured in the nsd.conf config file their set‐
591 tings are hardcoded (in an implicit pattern for themselves only) and
592 they cannot be deleted via delzone, but remove them from the config
593 file and repattern.
594 name: <string>
596 The name of the zone. This is the domain name of the apex of the
597 zone. May end with a '.' (in FQDN notation). For example "exam‐
598 ple.com", "sub.example.net.". This attribute must be present in
599 each zone.
600 zonefile: <filename>
602 The file containing the zone information. If this attribute is
603 present it is used to read and write the zone contents. If the
604 attribute is absent it prevents writing out of the zone.
605 The string is processed so that one string can be used (in a
607 pattern) for a lot of different zones. If the label or charac‐
608 ter does not exist the percent-character is replaced with a pe‐
609 riod for output (i.e. for the third character in a two letter
610 domain name).
611 %s is replaced with the zone name.
613 %1 is replaced with the first character of the zone name.
615 %2 is replaced with the second character of the zone name.
617 %3 is replaced with the third character of the zone name.
619 %z is replaced with the toplevel domain name of the zone.
621 %y is replaced with the next label under the toplevel domain.
623 %x is replaced with the next-next label under the toplevel do‐
625 main.
626 allow-query: <ip-spec> <key-name | NOKEY | BLOCKED>
628 Access control list. When at least one allow-query option is
629 specified, then the in the allow-query options specified ad‐
630 dresses are are allowed to query the server for the zone.
631 Queries from unlisted or specifically BLOCKED addresses are dis‐
632 carded. If NOKEY is given no TSIG signature is required.
633 BLOCKED supersedes other entries, other entries are scanned for
634 a match in the order of the statements. Without allow-query op‐
635 tions, queries are allowed from any IP address without TSIG key
636 (which is the default).
637 The ip-spec is either a plain IP address (IPv4 or IPv6), or can
639 be a subnet of the form 1.2.3.4/24, or masked like
640 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25.
641 Note the ip-spec ranges do not use spaces around the /, &, @ and
642 - symbols.
643 allow-notify: <ip-spec> <key-name | NOKEY | BLOCKED>
645 Access control list. The listed (primary) address is allowed to
646 send notifies to this (secondary) server. Notifies from unlisted
647 or specifically BLOCKED addresses are discarded. If NOKEY is
648 given no TSIG signature is required. BLOCKED supersedes other
649 entries, other entries are scanned for a match in the order of
650 the statements.
651 The ip-spec is either a plain IP address (IPv4 or IPv6), or can
653 be a subnet of the form 1.2.3.4/24, or masked like
654 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25.
655 A port number can be added using a suffix of @number, for exam‐
656 ple 1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. Note the
657 ip-spec ranges do not use spaces around the /, &, @ and - sym‐
658 bols.
659 request-xfr: [AXFR|UDP] <ip-address> <key-name | NOKEY> [tls-auth-name]
661 Access control list. The listed address (the master) is queried
662 for AXFR/IXFR on update. A port number can be added using a suf‐
663 fix of @number, for example 1.2.3.4@5300. The specified key is
664 used during AXFR/IXFR. If tls-auth-name is included, the speci‐
665 fied tls-auth clause will be used to perform authenticated XFR-
666 over-TLS.
667 If the AXFR option is given, the server will not be contacted
669 with IXFR queries but only AXFR requests will be made to the
670 server. This allows an NSD secondary to have a master server
671 that runs NSD. If the AXFR option is left out then both IXFR and
672 AXFR requests are made to the master server.
673 If the UDP option is given, the secondary will use UDP to trans‐
675 mit the IXFR requests. You should deploy TSIG when allowing UDP
676 transport, to authenticate notifies and zone transfers. Other‐
677 wise, NSD is more vulnerable for Kaminsky-style attacks. If the
678 UDP option is left out then IXFR will be transmitted using TCP.
679 If a tls-auth-name is given then TLS (by default on port 853)
681 will be used for all zone transfers for the zone. If authentica‐
682 tion of the master based on the specified tls-auth authentica‐
683 tion information fails, the XFR request will not be sent. Sup‐
684 port for TLS 1.3 is required for XFR-over-TLS.
685 allow-axfr-fallback: <yes or no>
687 This option should be accompanied by request-xfr. It (dis)allows
688 NSD (as secondary) to fallback to AXFR if the primary name
689 server does not support IXFR. Default is yes.
690 size-limit-xfr: <number>
692 This option should be accompanied by request-xfr. It specifies
693 XFR temporary file size limit. It can be used to stop very
694 large zone retrieval, that could otherwise use up a lot of mem‐
695 ory and disk space. If this option is 0, unlimited. Default
696 value is 0.
697 notify: <ip-address> <key-name | NOKEY>
699 Access control list. The listed address (a secondary) is noti‐
700 fied of updates to this zone. A port number can be added using a
701 suffix of @number, for example 1.2.3.4@5300. The specified key
702 is used to sign the notify. Only on secondary configurations
703 will NSD be able to detect zone updates (as it gets notified it‐
704 self, or refreshes after a time).
705 notify-retry: <number>
707 This option should be accompanied by notify. It sets the number
708 of retries when sending notifies.
709 provide-xfr: <ip-spec> <key-name | NOKEY | BLOCKED>
711 Access control list. The listed address (a secondary) is allowed
712 to request AXFR from this server. Zone data will be provided to
713 the address. The specified key is used during AXFR. For unlisted
714 or BLOCKED addresses no data is provided, requests are dis‐
715 carded. BLOCKED supersedes other entries, other entries are
716 scanned for a match in the order of the statements. NSD pro‐
717 vides AXFR for its secondaries, but IXFR is not implemented
718 (IXFR is implemented for request-xfr, but not for provide-xfr).
719 The ip-spec is either a plain IP address (IPv4 or IPv6), or can
721 be a subnet of the form 1.2.3.4/24, or masked like
722 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25.
723 A port number can be added using a suffix of @number, for exam‐
724 ple 1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. Note the
725 ip-spec ranges do not use spaces around the /, &, @ and - sym‐
726 bols.
727 outgoing-interface: <ip-address>
729 Access control list. The listed address is used to request
730 AXFR|IXFR (in case of a secondary) or used to send notifies (in
731 case of a primary).
732 The ip-address is a plain IP address (IPv4 or IPv6). A port
734 number can be added using a suffix of @number, for example
735 1.2.3.4@5300.
736 max-refresh-time: <seconds>
738 Limit refresh time for secondary zones. This is the timer which
739 checks to see if the zone has to be refetched when it expires.
740 Normally the value from the SOA record is used, but this option
741 restricts that value.
742 min-refresh-time: <seconds>
744 Limit refresh time for secondary zones.
745 max-retry-time: <seconds>
747 Limit retry time for secondary zones. This is the timer which
748 retries after a failed fetch attempt for the zone. Normally the
749 value from the SOA record is used, followed by an exponential
750 backoff, but this option restricts that value.
751 min-retry-time: <seconds>
753 Limit retry time for secondary zones.
754 min-expire-time: <seconds or refresh+retry+1>
756 Limit expire time for secondary zones. The value can be ex‐
757 pressed either by a number of seconds, or the string "re‐
758 fresh+retry+1". With the latter the expire time will be lower
759 bound to the refresh plus the retry value from the SOA record,
760 plus 1. The refresh and retry values will be subject to the
761 bounds configured with max-refresh-time, min-refresh-time,
762 max-retry-time and min-retry-time if given.
763 zonestats: <name>
765 When compiled with --enable-zone-stats NSD can collect statis‐
766 tics per zone. This name gives the group where statistics are
767 added to. The groups are output from nsd-control stats and
768 stats_noreset. Default is "". You can use "%s" to use the name
769 of the zone to track its statistics. If not compiled in, the
770 option can be given but is ignored.
771 include-pattern: <pattern-name>
773 The options from the given pattern are included at this point.
774 The referenced pattern must be defined above this zone.
775 rrl-whitelist: <rrltype>
777 This option causes queries of this rrltype to be whitelisted,
778 for this zone. They receive the whitelist-ratelimit. You can
779 give multiple lines, each enables a new rrltype to be
780 whitelisted for the zone. Default has none whitelisted. The rrl‐
781 type is the query classification that the NSD RRL employs to
782 make different types not interfere with one another. The types
783 are logged in the loglines when a subnet is blocked (in ver‐
784 bosity 2). The RRL classification types are: nxdomain, error,
785 referral, any, rrsig, wildcard, nodata, dnskey, positive, all.
786 multi-master-check: <yes or no>
788 Default no. If enabled, checks all masters for the last ver‐
789 sion. It uses the higher version of all the configured masters.
790 Useful if you have multiple masters that have different version
791 numbers served.
792 Key Declarations
794 The key: clause establishes a key for use in access control lists. It
795 has the following attributes.
796 name: <string>
798 The key name. Used to refer to this key in the access control
799 list. The key name has to be correct for tsig to work. This is
800 because the key name is output on the wire.
801 algorithm: <string>
803 Authentication algorithm for this key. Such as hmac-md5,
804 hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384 and
805 hmac-sha512. Can also be abbreviated as 'sha1', 'sha256'. De‐
806 fault is sha256. Algorithms are only available when they were
807 compiled in (available in the crypto library).
808 secret: <base64 blob>
810 The base64 encoded shared secret. It is possible to put the se‐
811 cret: declaration (and base64 blob) into a different file, and
812 then to include: that file. In this way the key secret and the
813 rest of the configuration file, which may have different secu‐
814 rity policies, can be split apart. The content of the secret is
815 the agreed base64 secret content. To make it up, enter a pass‐
816 word (its length must be a multiple of 4 characters, A-Za-z0-9),
817 or use dev-random output through a base64 encode filter.
818 TLS Auth Declarations
820 The tls-auth: clause establishes authentication attributes to use when
821 authenticating the far end of an outgoing TLS connection used in access
822 control lists for XFR-over-TLS. It has the following attributes.
823 name: <string>
825 The tls-auth name. Used to refer to this TLS authentication in‐
826 formation in the access control list.
827 auth-domain-name: <string>
829 The authentication domain name as defined in RFC8310.
830 client-cert: <file name of clientcert.pem>
832 If you want to use mutual TLS authentication, this is where the
833 client certificates can be configured that NSD uses to connect
834 to the upstream server to download the zone. The client public
835 key pem cert file can be configured here. Also configure a pri‐
836 vate key with client-key.
837 client-key: <file name of clientkey.key>
839 If you want to use mutual TLS authentication, the private key
840 file can be configured here for the client authentication.
841 client-key-pw: <string>
843 If the client-key file uses a password to decrypt the key before
844 it can be used, then the password can be specified here as a
845 string. It is possible to include other config files with the
846 include: option, and this can be used to move that sensitive
847 data to another file, if you wish.
848 DNSTAP Logging Options
850 DNSTAP support, when compiled in, is enabled in the dnstap: section.
851 This starts a collector process that writes the log information to the
852 destination.
853 dnstap-enable: <yes or no>
855 If dnstap is enabled. Default no. If yes, it connects to the
856 dnstap server and if any of the dnstap-log-..-messages options
857 is enabled it sends logs for those messages to the server.
858 dnstap-socket-path: <file name>
860 Sets the unix socket file name for connecting to the server that
861 is listening on that socket. Default is "/var/run/nsd-
862 dnstap.sock".
863 dnstap-send-identity: <yes or no>
865 If enabled, the server identity is included in the log messages.
866 Default is no.
867 dnstap-send-version: <yes or no>
869 If enabled, the server version if included in the log messages.
870 Default is no.
871 dnstap-identity: <string>
873 The identity to send with messages, if "" the hostname is used.
874 Default is "".
875 dnstap-version: <string>
877 The version to send with messages, if "" the package version is
878 used. Default is "".
879 dnstap-log-auth-query-messages: <yes or no>
881 Enable to log auth query messages. Default is no. These are
882 client queries to NSD.
883 dnstap-log-auth-response-messages: <yes or no>
885 Enable to log auth response messages. Default is no. These are
886 responses from NSD to clients.
887
889 BIND9 is a name server implementation with its own configuration file
890 format, named.conf(5). BIND9 types zones as 'Master' or 'Slave'.
891 Slave zones
893 For a slave zone, the master servers are listed. The master servers are
894 queried for zone data, and are listened to for update notifications.
895 In NSD these two properties need to be configured separately, by list‐
896 ing the master address in allow-notify and request-xfr statements.
897 In BIND9 you only need to provide allow-notify elements for any extra
899 sources of notifications (i.e. the operators), NSD needs to have al‐
900 low-notify for both masters and operators. BIND9 allows additional
901 transfer sources, in NSD you list those as request-xfr.
902 Here is an example of a slave zone in BIND9 syntax.
904 # Config file for example.org options {
906 dnssec-enable yes;
907 };
908 key tsig.example.org. {
910 algorithm hmac-md5;
911 secret "aaaaaabbbbbbccccccdddddd";
912 };
913 server 162.0.4.49 {
915 keys { tsig.example.org. ; };
916 };
917 zone "example.org" {
919 type slave;
920 file "secondary/example.org.signed";
921 masters { 162.0.4.49; };
922 };
923 For NSD, DNSSEC is enabled automatically for zones that are signed. The
925 dnssec-enable statement in the options clause is not needed. In NSD
926 keys are associated with an IP address in the access control list
927 statement, therefore the server{} statement is not needed. Below is the
928 same example in an NSD config file.
929 # Config file for example.org
931 key:
932 name: tsig.example.org.
933 algorithm: hmac-md5
934 secret: "aaaaaabbbbbbccccccdddddd"
935 zone:
937 name: "example.org"
938 zonefile: "secondary/example.org.signed"
939 # the master is allowed to notify and will provide zone data.
940 allow-notify: 162.0.4.49 NOKEY
941 request-xfr: 162.0.4.49 tsig.example.org.
942 Notice that the master is listed twice, once to allow it to send noti‐
944 fies to this slave server and once to tell the slave server where to
945 look for updates zone data. More allow-notify and request-xfr lines can
946 be added to specify more masters.
947 It is possible to specify extra allow-notify lines for addresses that
949 are also allowed to send notifications to this slave server.
950 Master zones
952 For a master zone in BIND9, the slave servers are listed. These slave
953 servers are sent notifications of updated and are allowed to request
954 transfer of the zone data. In NSD these two properties need to be con‐
955 figured separately.
956 Here is an example of a master zone in BIND9 syntax.
958 zone "example.nl" {
960 type master;
961 file "example.nl";
962 };
963 In NSD syntax this becomes:
965 zone:
967 name: "example.nl"
968 zonefile: "example.nl"
969 # allow anybody to request xfr.
970 provide-xfr: 0.0.0.0/0 NOKEY
971 provide-xfr: ::0/0 NOKEY
972 # to list a slave server you would in general give
974 # provide-xfr: 1.2.3.4 tsig-key.name.
975 # notify: 1.2.3.4 NOKEY
976 Other
978 NSD is an authoritative only DNS server. This means that it is meant as
979 a primary or secondary server for zones, providing DNS data to DNS re‐
980 solvers and caches. BIND9 can function as an authoritative DNS server,
981 the configuration options for that are compared with those for NSD in
982 this section. However, BIND9 can also function as a resolver or cache.
983 The configuration options that BIND9 has for the resolver or caching
984 thus have no equivalents for NSD.
985
987 "" default NSD database
988 /etc/nsd/nsd.conf
990 default NSD configuration file
991
993 nsd(8), nsd-checkconf(8), nsd-control(8)
994
996 NSD was written by NLnet Labs and RIPE NCC joint team. Please see CRED‐
997 ITS file in the distribution for further details.
998
1000 nsd.conf is parsed by a primitive parser, error messages may not be to
1001 the point.
1002NLnet Labs Oct 12, 2021 nsd.conf(5)