1nsd.conf(5) nsd 4.2.4 nsd.conf(5)
2
3
4
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
16 Comments start with # and last to the end of line. Empty lines are
17 ignored as is whitespace at the beginning of a line. Quotes can be
18 used, for names with spaces, eg. "file name.zone".
19
20 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
26 # Example.com nsd.conf file
27 # This is a comment.
28
29 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
38 zone:
39 name: example.com
40 zonefile: /etc/nsd/example.com.zone
41
42 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
49 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
56 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
64 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
72 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
78 chroot 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
82 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
86 ip-address: <ip4 or ip6>[@port]
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
90 interface. Same as commandline option -a. For servers with mul‐
91 tiple IP addresses that can be used to send traffic to the
92 internet, list them one by one, or the source address of replies
93 could be wrong. This is because if the udp socket associates a
94 source address of 0.0.0.0 then the kernel picks an ip-address
95 with which to send to the internet, and it picks the wrong one.
96 Typically needed for anycast instances. Use ip-transparent to
97 be able to list addresses that turn on later (typical for cer‐
98 tain load-balancing).
99
100 interface: <ip4 or ip6>[@port]
101 Same as ip-address (for easy of compatibility with
102 unbound.conf).
103
104 ip-transparent: <yes or no>
105 Allows NSD to bind to non local addresses. This is useful to
106 have NSD listen to IP addresses that are not (yet) added to the
107 network interface, so that it can answer immediately when the
108 address is added. Default is no.
109
110 ip-freebind: <yes or no>
111 Set the IP_FREEBIND option to bind to nonlocal addresses and
112 interfaces that are down. Similar to ip-transparent. Default
113 is no.
114
115 reuseport: <yes or no>
116 Use the SO_REUSEPORT socket option, and create file descriptors
117 for every server in the server-count. This improves performance
118 of the network stack. Only really useful if you also configure
119 a server-count higher than 1 (such as, equal to the number of
120 cpus). The default is no. It works on Linux, but does not work
121 on FreeBSD, and likely does not work on other systems.
122
123 send-buffer-size: <number>
124 Set the send buffer size for query-servicing sockets. Set to 0
125 to use the default settings.
126
127 receive-buffer-size: <number>
128 Set the receive buffer size for query-servicing sockets. Set to
129 0 to use the default settings.
130
131 debug-mode: <yes or no>
132 Turns on debugging mode for nsd, does not fork a daemon process.
133 Default is no. Same as commandline option -d. If set to yes it
134 does not fork and stays in the foreground, which can be helpful
135 for commandline debugging, but is also used by certain server
136 supervisor processes to ascertain that the server is running.
137
138 do-ip4: <yes or no>
139 If yes, NSD listens to IPv4 connections. Default yes.
140
141 do-ip6: <yes or no>
142 If yes, NSD listens to IPv6 connections. Default yes.
143
144 database: <filename>
145 By default '' is used. The specified file is used to store the
146 compiled zone information. Same as commandline option -f. If
147 set to "" then no database is used. This uses less memory but
148 zone updates are not (immediately) spooled to disk.
149
150 zonelistfile: <filename>
151 By default /var/lib/nsd/zone.list is used. The specified file is
152 used to store the dynamically added list of zones. The list is
153 written to by NSD to add and delete zones. It is a text file
154 with a zone-name and pattern-name on each line. This file is
155 used for the nsd-control addzone and delzone commands.
156
157 identity: <string>
158 Returns the specified identity when asked for CH TXT ID.SERVER.
159 Default is the name as returned by gethostname(3). Same as com‐
160 mandline option -i. See hide-identity to set the server to not
161 respond to such queries.
162
163 version: <string>
164 Returns the specified version string when asked for CH TXT ver‐
165 sion.server, and version.bind queries. Default is the compiled
166 package version. See hide-version to set the server to not
167 respond to such queries.
168
169 nsid: <string>
170 Add the specified nsid to the EDNS section of the answer when
171 queried with an NSID EDNS enabled packet. As a sequence of hex
172 characters or with ascii_ prefix and then an ascii string. Same
173 as commandline option -I.
174
175 logfile: <filename>
176 Log messages to the logfile. The default is to log to stderr and
177 syslog (with facility LOG_DAEMON). Same as commandline option
178 -l.
179
180 server-count: <number>
181 Start this many NSD servers. Default is 1. Same as commandline
182 option -N.
183
184 tcp-count: <number>
185 The maximum number of concurrent, active TCP connections by each
186 server. Default is 100. Same as commandline option -n.
187
188 tcp-reject-overflow: <yes or no>
189 If set to yes, TCP connections made beyond the maximum set by
190 tcp-count will be dropped immediately (accepted and closed).
191 Default is no.
192
193 tcp-query-count: <number>
194 The maximum number of queries served on a single TCP connection.
195 Default is 0, meaning there is no maximum.
196
197 tcp-timeout: <number>
198 Overrides the default TCP timeout. This also affects zone trans‐
199 fers over TCP.
200
201 tcp-mss: <number>
202 Maximum segment size (MSS) of TCP socket on which the server
203 responds to queries. Value lower than common MSS on Ethernet
204 (1220 for example) will address path MTU problem. Note that not
205 all platform supports socket option to set MSS (TCP_MAXSEG).
206 Default is system default MSS determined by interface MTU and
207 negotiation between server and client.
208
209 outgoing-tcp-mss: <number>
210 Maximum segment size (MSS) of TCP socket for outgoing XFR
211 request to other namesevers. Value lower than common MSS on Eth‐
212 ernet (1220 for example) will address path MTU problem. Note
213 that not all platform supports socket option to set MSS
214 (TCP_MAXSEG). Default is system default MSS determined by
215 interface MTU and negotiation between NSD and other servers.
216
217 ipv4-edns-size: <number>
218 Preferred EDNS buffer size for IPv4. Default 4096.
219
220 ipv6-edns-size: <number>
221 Preferred EDNS buffer size for IPv6. Default 4096.
222
223 pidfile: <filename>
224 Use the pid file instead of the platform specific default, usu‐
225 ally /run/nsd/nsd.pid. Same as commandline option -P. With ""
226 there is no pidfile, for some startup management setups, where a
227 pidfile is not useful to have.
228
229 port: <number>
230 Answer queries on the specified port. Default is 53. Same as
231 commandline option -p.
232
233 statistics: <number>
234 If not present no statistics are dumped. Statistics are produced
235 every number seconds. Same as commandline option -s.
236
237 chroot: <directory>
238 NSD will chroot on startup to the specified directory. Note that
239 if elsewhere in the configuration you specify an absolute path‐
240 name to a file inside the chroot, you have to prepend the chroot
241 path. That way, you can switch the chroot option on and off
242 without having to modify anything else in the configuration. Set
243 the value to "" (the empty string) to disable the chroot. By
244 default "" is used. Same as commandline option -t.
245
246 username: <username>
247 After binding the socket, drop user privileges and assume the
248 username. Can be username, id or id.gid. Same as commandline
249 option -u.
250
251 zonesdir: <directory>
252 Change the working directory to the specified directory before
253 accessing zone files. Also, NSD will access database, zonelist‐
254 file, logfile, pidfile, xfrdfile, xfrdir, server-key-file,
255 server-cert-file, control-key-file and control-cert-file rela‐
256 tive to this directory. Set the value to "" (the empty string)
257 to disable the change of working directory. By default
258 "/etc/nsd" is used.
259
260 difffile: <filename>
261 Ignored, for compatibility with NSD3 config files.
262
263 xfrdfile: <filename>
264 The soa timeout and zone transfer daemon in NSD will save its
265 state to this file. State is read back after a restart. The
266 state file can be deleted without too much harm, but timestamps
267 of zones will be gone. If it is configured as "", the state
268 file is not used, all slave zones are checked for updates upon
269 startup. For more details see the section on zone expiry behav‐
270 ior of NSD. Default is /var/lib/nsd/ixfr.state.
271
272 xfrdir: <directory>
273 The zone transfers are stored here before they are processed. A
274 directory is created here that is removed when NSD exits.
275 Default is /tmp.
276
277 xfrd-reload-timeout: <number>
278 If this value is -1, xfrd will not trigger a reload after a zone
279 transfer. If positive xfrd will trigger a reload after a zone
280 transfer, then it will wait for the number of seconds before it
281 will trigger a new reload. Setting this value throttles the
282 reloads to once per the number of seconds. The default is 1 sec‐
283 ond.
284
285 verbosity: <level>
286 This value specifies the verbosity level for (non-debug) log‐
287 ging. Default is 0. 1 gives more information about incoming
288 notifies and zone transfers. 2 lists soft warnings that are
289 encountered. 3 prints more information.
290
291 Verbosity 0 will print warnings and errors, and other events
292 that are important to keep NSD running.
293
294 Verbosity 1 prints additionally messages of interest. Success‐
295 ful notifies, successful incoming zone transfer (the zone is
296 updated), failed incoming zone transfers or the inability to
297 process zone updates.
298
299 Verbosity 2 prints additionally soft errors, like connection
300 resets over TCP. And notify refusal, and axfr request refusals.
301
302 hide-version: <yes or no>
303 Prevent NSD from replying with the version string on CHAOS class
304 queries. Default is no.
305
306 hide-identity: <yes or no>
307 Prevent NSD from replying with the identity string on CHAOS
308 class queries. Default is no.
309
310 log-time-ascii: <yes or no>
311 Log time in ascii, if "no" then in seconds epoch. Default is
312 yes. This chooses the format when logging to file. The print‐
313 out via syslog has a timestamp formatted by syslog.
314
315 round-robin: <yes or no>
316 Enable round robin rotation of records in the answer. This
317 changes the order of records in the answer and this may balance
318 load across them. The default is no.
319
320 minimal-responses: <yes or no>
321 Enable minimal responses for smaller answers. This makes pack‐
322 ets smaller. Extra data is only added for referrals, when it is
323 really necessary. This is different from the --enable-minimal-
324 responses configure time option, that reduces packets, but
325 exactly to the fragmentation length, the nsd.conf option reduces
326 packets as small as possible. The default is no.
327
328 confine-to-zone: <yes or no>
329 If set to yes, additional information will not be added to the
330 response if the apex zone of the additional information does not
331 match the apex zone of the initial query (E.G. CNAME resolu‐
332 tion). Default is no.
333
334 refuse-any: <yes or no>
335 Refuse queries of type ANY. This is useful to stop query floods
336 trying to get large responses. Note that rrl ratelimiting also
337 has type ANY as a ratelimiting type. It sends truncation in
338 response to UDP type ANY queries, and it allows TCP type ANY
339 queries like normal. The default is no.
340
341 zonefiles-check: <yes or no>
342 Make NSD check the mtime of zone files on start and sighup. If
343 you disable it it starts faster (less disk activity in case of a
344 lot of zones). The default is yes. The nsd-control reload com‐
345 mand reloads zone files regardless of this option.
346
347 zonefiles-write: <seconds>
348 Write changed secondary zones to their zonefile every N seconds.
349 If the zone (pattern) configuration has "" zonefile, it is not
350 written. Zones that have received zone transfer updates are
351 written to their zonefile. Default is 0 (disabled) when there
352 is a database, and 3600 (1 hour) when database is "". The data‐
353 base also commits zone transfer contents. You can configure it
354 away from the default by putting the config statement for zone‐
355 files-write: after the database: statement in the config file.
356
357 rrl-size: <numbuckets>
358 This option gives the size of the hashtable. Default 1000000.
359 More buckets use more memory, and reduce the chance of hash col‐
360 lisions.
361
362 rrl-ratelimit: <qps>
363 The max qps allowed (from one query source). Default is on (with
364 a suggested 200 qps). If set to 0 then it is disabled (unlimited
365 rate), also set the whitelist-ratelimit to 0 to disable rate‐
366 limit processing. If you set verbosity to 2 the blocked and
367 unblocked subnets are logged. Blocked queries are blocked and
368 some receive TCP fallback replies. Once the rate limit is
369 reached, NSD begins dropping responses. However, one in every
370 "rrl-slip" number of responses is allowed, with the TC bit set.
371 If slip is set to 2, the outgoing response rate will be halved.
372 If it's set to 3, the outgoing response rate will be one-third,
373 and so on. If you set rrl-slip to 10, traffic is reduced to
374 1/10th. Ratelimit options rrl-ratelimit, rrl-size and
375 rrl-whitelist-ratelimit are updated when nsd-control reconfig is
376 done (also the zone-specific ratelimit options are updated).
377
378 rrl-slip: <numpackets>
379 This option controls the number of packets discarded before we
380 send back a SLIP response (a response with "truncated" bit set
381 to one). 0 disables the sending of SLIP packets, 1 means every
382 query will get a SLIP response. Default is 2, cuts traffic in
383 half and legit users have a fair chance to get a +TC response.
384
385 rrl-ipv4-prefix-length: <subnet>
386 IPv4 prefix length. Addresses are grouped by netblock. Default
387 24.
388
389 rrl-ipv6-prefix-length: <subnet>
390 IPv6 prefix length. Addresses are grouped by netblock. Default
391 64.
392
393 rrl-whitelist-ratelimit: <qps>
394 The max qps for query sorts for a source, which have been
395 whitelisted. Default on (with a suggested 2000 qps). With the
396 rrl-whitelist option you can set specific queries to receive
397 this qps limit instead of the normal limit. With the value 0
398 the rate is unlimited.
399
400 tls-service-key: <filename>
401 If enabled, the server provides TLS service on TCP sockets with
402 the TLS service port number. The port number (853) is config‐
403 ured with tls-port. To turn it on, create an interface: option
404 line in config with @port appended to the IP-address. This cre‐
405 ates the extra socket on which the DNS over TLS service is pro‐
406 vided.
407
408 The file is the private key for the TLS session. The public cer‐
409 tificate is in the tls-service-pem file. Default is "", turned
410 off. Requires a restart (a reload is not enough) if changed,
411 because the private key is read while root permissions are held
412 and before chroot (if any).
413
414 tls-service-pem: <filename>
415 The public key certificate pem file for the tls service. Default
416 is "", turned off.
417
418 tls-service-ocsp: <filename>
419 The ocsp pem file for the tls service, for OCSP stapling.
420 Default is "", turned off. An external process prepares and
421 updates the OCSP stapling data. Like this,
422 openssl ocsp -no_nonce \
423 -respout /path/to/ocsp.pem \
424 -CAfile /path/to/ca_and_any_intermediate.pem \
425 -issuer /path/to/direct_issuer.pem \
426 -cert /path/to/cert.pem \
427 -url "$( openssl x509 -noout -text -in /path/to/cert.pem |
428 grep 'OCSP - URI:' | cut -d: -f2,3 )"
429
430 tls-port: <number>
431 The port number on which to provide TCP TLS service, default is
432 853, only interfaces configured with that port number as @number
433 get DNS over TLS service.
434
435 Remote Control
436 The remote-control: clause is used to set options for using the
437 nsd-control(8) tool to give commands to the running NSD server. It is
438 disabled by default, and listens for localhost by default. It uses TLS
439 over TCP where the server and client authenticate to each other with
440 self-signed certificates. The self-signed certificates can be gener‐
441 ated with the nsd-control-setup tool. The key files are read by NSD
442 before the chroot and before dropping user permissions, so they can be
443 outside the chroot and readable by the superuser only.
444
445 control-enable: <yes or no>
446 Enable remote control, default is no.
447
448 control-interface: <ip4 or ip6>
449 NSD will bind to the listed addresses to service control
450 requests (on TCP). Can be given multiple times to bind multiple
451 ip-addresses. Use 0.0.0.0 and ::0 to service the wildcard
452 interface. If none are given NSD listens to the localhost
453 127.0.0.1 and ::1 interfaces for control, if control is enabled
454 with control-enable.
455
456 With an absolute path, a unix local named pipe is used for con‐
457 trol. The file is created with user and group that is config‐
458 ured and access bits are set to allow members of the group
459 access. Further access can be controlled by setting permissions
460 on the directory containing the control socket file. The key
461 and cert files are not used when control is via the named pipe,
462 because access control is via file and directory permission.
463
464 control-port: <number>
465 The port number for remote control service. 8952 by default.
466
467 server-key-file: <filename>
468 Path to the server private key, by default
469 /etc/nsd/nsd_server.key. This file is generated by the nsd-con‐
470 trol-setup utility. This file is used by the nsd server, but
471 not by nsd-control.
472
473 server-cert-file: <filename>
474 Path to the server self signed certificate, by default
475 /etc/nsd/nsd_server.pem. This file is generated by the nsd-con‐
476 trol-setup utility. This file is used by the nsd server, and
477 also by nsd-control.
478
479 control-key-file: <filename>
480 Path to the control client private key, by default
481 /etc/nsd/nsd_control.key. This file is generated by the
482 nsd-control-setup utility. This file is used by nsd-control.
483
484 control-cert-file: <filename>
485 Path to the control client certificate, by default
486 /etc/nsd/nsd_control.pem. This certificate has to be signed
487 with the server certificate. This file is generated by the
488 nsd-control-setup utility. This file is used by nsd-control.
489
490 Pattern Options
491 The pattern: clause is used to denote a set of options to apply to some
492 zones. The same zone options as for a zone are allowed.
493
494 name: <string>
495 The name of the pattern. This is a (case sensitive) string.
496 The pattern names that start with "_implicit_" are used inter‐
497 nally for zones that have no pattern (they are defined in
498 nsd.conf directly).
499
500 include-pattern: <pattern-name>
501 The options from the given pattern are included at this point in
502 this pattern. The referenced pattern must be defined above this
503 one.
504
505 <zone option>: <value>
506 The zone options such as zonefile, allow-notify, request-xfr,
507 allow-axfr-fallback, notify, notify-retry, provide-xfr, zones‐
508 tats, and outgoing-interface can be given. They are applied to
509 the patterns and zones that include this pattern.
510
511 Zone Options
512 For every zone the options need to be specified in one zone: clause.
513 The access control list elements can be given multiple times to add
514 multiple servers. These elements need to be added explicitly.
515
516 For zones that are configured in the nsd.conf config file their set‐
517 tings are hardcoded (in an implicit pattern for themselves only) and
518 they cannot be deleted via delzone, but remove them from the config
519 file and repattern.
520
521 name: <string>
522 The name of the zone. This is the domain name of the apex of the
523 zone. May end with a '.' (in FQDN notation). For example "exam‐
524 ple.com", "sub.example.net.". This attribute must be present in
525 each zone.
526
527 zonefile: <filename>
528 The file containing the zone information. If this attribute is
529 present it is used to read and write the zone contents. If the
530 attribute is absent it prevents writing out of the zone.
531
532 The string is processed so that one string can be used (in a
533 pattern) for a lot of different zones. If the label or charac‐
534 ter does not exist the percent-character is replaced with a
535 period for output (i.e. for the third character in a two letter
536 domain name).
537
538 %s is replaced with the zone name.
539
540 %1 is replaced with the first character of the zone name.
541
542 %2 is replaced with the second character of the zone name.
543
544 %3 is replaced with the third character of the zone name.
545
546 %z is replaced with the toplevel domain name of the zone.
547
548 %y is replaced with the next label under the toplevel domain.
549
550 %x is replaced with the next-next label under the toplevel
551 domain.
552
553 allow-notify: <ip-spec> <key-name | NOKEY | BLOCKED>
554 Access control list. The listed (primary) address is allowed to
555 send notifies to this (secondary) server. Notifies from unlisted
556 or specifically BLOCKED addresses are discarded. If NOKEY is
557 given no TSIG signature is required. BLOCKED supersedes other
558 entries, other entries are scanned for a match in the order of
559 the statements.
560
561 The ip-spec is either a plain IP address (IPv4 or IPv6), or can
562 be a subnet of the form 1.2.3.4/24, or masked like
563 1.2.3.4&255.255.255.0 or a range of the form 1.2.3.4-1.2.3.25.
564 A port number can be added using a suffix of @number, for exam‐
565 ple 1.2.3.4@5300 or 1.2.3.4/24@5300 for port 5300. Note the
566 ip-spec ranges do not use spaces around the /, &, @ and - sym‐
567 bols.
568
569 request-xfr: [AXFR|UDP] <ip-address> <key-name | NOKEY>
570 Access control list. The listed address (the master) is queried
571 for AXFR/IXFR on update. A port number can be added using a suf‐
572 fix of @number, for example 1.2.3.4@5300. The specified key is
573 used during AXFR/IXFR.
574
575 If the AXFR option is given, the server will not be contacted
576 with IXFR queries but only AXFR requests will be made to the
577 server. This allows an NSD secondary to have a master server
578 that runs NSD. If the AXFR option is left out then both IXFR and
579 AXFR requests are made to the master server.
580
581 If the UDP option is given, the secondary will use UDP to trans‐
582 mit the IXFR requests. You should deploy TSIG when allowing UDP
583 transport, to authenticate notifies and zone transfers. Other‐
584 wise, NSD is more vulnerable for Kaminsky-style attacks. If the
585 UDP option is left out then IXFR will be transmitted using TCP.
586
587 allow-axfr-fallback: <yes or no>
588 This option should be accompanied by request-xfr. It (dis)allows
589 NSD (as secondary) to fallback to AXFR if the primary name
590 server does not support IXFR. Default is yes.
591
592 size-limit-xfr: <number>
593 This option should be accompanied by request-xfr. It specifies
594 XFR temporary file size limit. It can be used to stop very
595 large zone retrieval, that could otherwise use up a lot of mem‐
596 ory and disk space. If this option is 0, unlimited. Default
597 value is 0.
598
599 notify: <ip-address> <key-name | NOKEY>
600 Access control list. The listed address (a secondary) is noti‐
601 fied of updates to this zone. A port number can be added using a
602 suffix of @number, for example 1.2.3.4@5300. The specified key
603 is used to sign the notify. Only on secondary configurations
604 will NSD be able to detect zone updates (as it gets notified
605 itself, or refreshes after a time).
606
607 notify-retry: <number>
608 This option should be accompanied by notify. It sets the number
609 of retries when sending notifies.
610
611 provide-xfr: <ip-spec> <key-name | NOKEY | BLOCKED>
612 Access control list. The listed address (a secondary) is allowed
613 to request AXFR from this server. Zone data will be provided to
614 the address. The specified key is used during AXFR. For unlisted
615 or BLOCKED addresses no data is provided, requests are dis‐
616 carded. BLOCKED supersedes other entries, other entries are
617 scanned for a match in the order of the statements. NSD pro‐
618 vides AXFR for its secondaries, but IXFR is not implemented
619 (IXFR is implemented for request-xfr, but not for provide-xfr).
620
621 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
629 outgoing-interface: <ip-address>
630 Access control list. The listed address is used to request
631 AXFR|IXFR (in case of a secondary) or used to send notifies (in
632 case of a primary).
633
634 The ip-address is a plain IP address (IPv4 or IPv6). A port
635 number can be added using a suffix of @number, for example
636 1.2.3.4@5300.
637
638 max-refresh-time: <seconds>
639 Limit refresh time for secondary zones. This is the timer which
640 checks to see if the zone has to be refetched when it expires.
641 Normally the value from the SOA record is used, but this option
642 restricts that value.
643
644 min-refresh-time: <seconds>
645 Limit refresh time for secondary zones.
646
647 max-retry-time: <seconds>
648 Limit retry time for secondary zones. This is the timeout after
649 a failed fetch attempt for the zone. Normally the value from
650 the SOA record is used, but this option restricts that value.
651
652 min-retry-time: <seconds>
653 Limit retry time for secondary zones.
654
655 zonestats: <name>
656 When compiled with --enable-zone-stats NSD can collect statis‐
657 tics per zone. This name gives the group where statistics are
658 added to. The groups are output from nsd-control stats and
659 stats_noreset. Default is "". You can use "%s" to use the name
660 of the zone to track its statistics. If not compiled in, the
661 option can be given but is ignored.
662
663 include-pattern: <pattern-name>
664 The options from the given pattern are included at this point.
665 The referenced pattern must be defined above this zone.
666
667 rrl-whitelist: <rrltype>
668 This option causes queries of this rrltype to be whitelisted,
669 for this zone. They receive the whitelist-ratelimit. You can
670 give multiple lines, each enables a new rrltype to be
671 whitelisted for the zone. Default has none whitelisted. The rrl‐
672 type is the query classification that the NSD RRL employs to
673 make different types not interfere with one another. The types
674 are logged in the loglines when a subnet is blocked (in ver‐
675 bosity 2). The RRL classification types are: nxdomain, error,
676 referral, any, rrsig, wildcard, nodata, dnskey, positive, all.
677
678 multi-master-check: <yes or no>
679 Default no. If enabled, checks all masters for the last ver‐
680 sion. It uses the higher version of all the configured masters.
681 Useful if you have multiple masters that have different version
682 numbers served.
683
684 Key Declarations
685 The key: clause establishes a key for use in access control lists. It
686 has the following attributes.
687
688 name: <string>
689 The key name. Used to refer to this key in the access control
690 list. The key name has to be correct for tsig to work. This is
691 because the key name is output on the wire.
692
693 algorithm: <string>
694 Authentication algorithm for this key. Such as hmac-md5,
695 hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384 and
696 hmac-sha512. Can also be abbreviated as 'sha1', 'sha256'.
697 Default is sha256. Algorithms are only available when they were
698 compiled in (available in the crypto library).
699
700 secret: <base64 blob>
701 The base64 encoded shared secret. It is possible to put the
702 secret: declaration (and base64 blob) into a different file, and
703 then to include: that file. In this way the key secret and the
704 rest of the configuration file, which may have different secu‐
705 rity policies, can be split apart. The content of the secret is
706 the agreed base64 secret content. To make it up, enter a pass‐
707 word (its length must be a multiple of 4 characters, A-Za-z0-9),
708 or use dev-random output through a base64 encode filter.
709
711 BIND9 is a name server implementation with its own configuration file
712 format, named.conf(5). BIND9 types zones as 'Master' or 'Slave'.
713
714 Slave zones
715 For a slave zone, the master servers are listed. The master servers are
716 queried for zone data, and are listened to for update notifications.
717 In NSD these two properties need to be configured separately, by list‐
718 ing the master address in allow-notify and request-xfr statements.
719
720 In BIND9 you only need to provide allow-notify elements for any extra
721 sources of notifications (i.e. the operators), NSD needs to have
722 allow-notify for both masters and operators. BIND9 allows additional
723 transfer sources, in NSD you list those as request-xfr.
724
725 Here is an example of a slave zone in BIND9 syntax.
726
727 # Config file for example.org options {
728 dnssec-enable yes;
729 };
730
731 key tsig.example.org. {
732 algorithm hmac-md5;
733 secret "aaaaaabbbbbbccccccdddddd";
734 };
735
736 server 162.0.4.49 {
737 keys { tsig.example.org. ; };
738 };
739
740 zone "example.org" {
741 type slave;
742 file "secondary/example.org.signed";
743 masters { 162.0.4.49; };
744 };
745
746 For NSD, DNSSEC is enabled automatically for zones that are signed. The
747 dnssec-enable statement in the options clause is not needed. In NSD
748 keys are associated with an IP address in the access control list
749 statement, therefore the server{} statement is not needed. Below is the
750 same example in an NSD config file.
751
752 # Config file for example.org
753 key:
754 name: tsig.example.org.
755 algorithm: hmac-md5
756 secret: "aaaaaabbbbbbccccccdddddd"
757
758 zone:
759 name: "example.org"
760 zonefile: "secondary/example.org.signed"
761 # the master is allowed to notify and will provide zone data.
762 allow-notify: 162.0.4.49 NOKEY
763 request-xfr: 162.0.4.49 tsig.example.org.
764
765 Notice that the master is listed twice, once to allow it to send noti‐
766 fies to this slave server and once to tell the slave server where to
767 look for updates zone data. More allow-notify and request-xfr lines can
768 be added to specify more masters.
769
770 It is possible to specify extra allow-notify lines for addresses that
771 are also allowed to send notifications to this slave server.
772
773 Master zones
774 For a master zone in BIND9, the slave servers are listed. These slave
775 servers are sent notifications of updated and are allowed to request
776 transfer of the zone data. In NSD these two properties need to be con‐
777 figured separately.
778
779 Here is an example of a master zone in BIND9 syntax.
780
781 zone "example.nl" {
782 type master;
783 file "example.nl";
784 };
785
786 In NSD syntax this becomes:
787
788 zone:
789 name: "example.nl"
790 zonefile: "example.nl"
791 # allow anybody to request xfr.
792 provide-xfr: 0.0.0.0/0 NOKEY
793 provide-xfr: ::0/0 NOKEY
794
795 # to list a slave server you would in general give
796 # provide-xfr: 1.2.3.4 tsig-key.name.
797 # notify: 1.2.3.4 NOKEY
798
799 Other
800 NSD is an authoritative only DNS server. This means that it is meant as
801 a primary or secondary server for zones, providing DNS data to DNS
802 resolvers and caches. BIND9 can function as an authoritative DNS
803 server, the configuration options for that are compared with those for
804 NSD in this section. However, BIND9 can also function as a resolver or
805 cache. The configuration options that BIND9 has for the resolver or
806 caching thus have no equivalents for NSD.
807
809 "" default NSD database
810
811 /etc/nsd/nsd.conf
812 default NSD configuration file
813
815 nsd(8), nsd-checkconf(8), nsd-control(8)
816
818 NSD was written by NLnet Labs and RIPE NCC joint team. Please see CRED‐
819 ITS file in the distribution for further details.
820
822 nsd.conf is parsed by a primitive parser, error messages may not be to
823 the point.
824
825
826
827NLnet Labs Dec 10, 2019 nsd.conf(5)