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