1nsd.conf(5)                        nsd 4.3.5                       nsd.conf(5)
2
3
4

NAME

6       nsd.conf - NSD configuration file
7

SYNOPSIS

9       nsd.conf
10

DESCRIPTION

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

EXAMPLE

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

FILE FORMAT

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] [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
90              interface. Same as commandline option -a.
91
92              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
97              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
101              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
103              address 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
110       interface: <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
111              Same   as   ip-address   (for   ease   of   compatibility   with
112              unbound.conf).
113
114       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
120       ip-freebind: <yes or no>
121              Set  the  IP_FREEBIND  option  to bind to nonlocal addresses and
122              interfaces that are down.  Similar to  ip-transparent.   Default
123              is no.
124
125       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
133       send-buffer-size: <number>
134              Set the send buffer size for query-servicing sockets.  Set to  0
135              to use the default settings.
136
137       receive-buffer-size: <number>
138              Set the receive buffer size for query-servicing sockets.  Set to
139              0 to use the default settings.
140
141       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
148       do-ip4: <yes or no>
149              If yes, NSD listens to IPv4 connections.  Default yes.
150
151       do-ip6: <yes or no>
152              If yes, NSD listens to IPv6 connections.  Default yes.
153
154       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
160       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
167       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
173       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
177              respond to such queries.
178
179       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
185       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
190       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.
193              Before syslog has been opened, the server uses  stderr.   Stderr
194              is also used if syslog is not available.  Default is no.
195
196       server-count: <number>
197              Start  this  many NSD servers. Default is 1. Same as commandline
198              option -N.
199
200       cpu-affinity: <number> <number> ...
201              Overall CPU affinity for NSD server(s). Default is no  affinity.
202              -n.
203
204       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
209       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
214       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
218       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
223       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
227       tcp-timeout: <number>
228              Overrides the default TCP timeout. This also affects zone trans‐
229              fers over TCP.  The default is 120 seconds.
230
231       tcp-mss: <number>
232              Maximum segment size (MSS) of TCP socket  on  which  the  server
233              responds  to  queries.  Value  lower than common MSS on Ethernet
234              (1220 for example) will address path MTU problem.  Note that not
235              all  platform  supports  socket  option to set MSS (TCP_MAXSEG).
236              Default is system default MSS determined by  interface  MTU  and
237              negotiation between server and client.
238
239       outgoing-tcp-mss: <number>
240              Maximum  segment  size  (MSS)  of  TCP  socket  for outgoing XFR
241              request to other namesevers. Value lower than common MSS on Eth‐
242              ernet  (1220  for  example) will address path MTU problem.  Note
243              that  not  all  platform  supports  socket  option  to  set  MSS
244              (TCP_MAXSEG).   Default  is  system  default  MSS  determined by
245              interface MTU and negotiation between NSD and other servers.
246
247       ipv4-edns-size: <number>
248              Preferred EDNS buffer size for IPv4.  Default 1232.
249
250       ipv6-edns-size: <number>
251              Preferred EDNS buffer size for IPv6.  Default 1232.
252
253       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
259       port: <number>
260              Answer  queries  on  the  specified port. Default is 53. Same as
261              commandline option -p.
262
263       statistics: <number>
264              If not present no statistics are dumped. Statistics are produced
265              every number seconds. Same as commandline option -s.
266
267       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
274              default "" is used. Same as commandline option -t.
275
276       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
279              option -u.
280
281       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
290       difffile: <filename>
291              Ignored, for compatibility with NSD3 config files.
292
293       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
302       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.
305              Default is /tmp.
306
307       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
315       verbosity: <level>
316              This value specifies the verbosity level  for  (non-debug)  log‐
317              ging.   Default  is  0.  1 gives more information about incoming
318              notifies and zone transfers. 2  lists  soft  warnings  that  are
319              encountered. 3 prints more information.
320
321              Verbosity  0  will  print  warnings and errors, and other events
322              that are important to keep NSD running.
323
324              Verbosity 1 prints additionally messages of interest.   Success‐
325              ful  notifies,  successful  incoming  zone transfer (the zone is
326              updated), failed incoming zone transfers  or  the  inability  to
327              process zone updates.
328
329              Verbosity  2  prints  additionally  soft errors, like connection
330              resets over TCP.  And notify refusal, and axfr request refusals.
331
332       hide-version: <yes or no>
333              Prevent NSD from replying with the version string on CHAOS class
334              queries.  Default is no.
335
336       hide-identity: <yes or no>
337              Prevent  NSD  from  replying  with  the identity string on CHAOS
338              class queries.  Default is no.
339
340       drop-updates: <yes or no>
341              If set to yes, drop received packets  with  the  UPDATE  opcode.
342              Default is no.
343
344       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
349       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
354       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
359       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
364              exactly to the fragmentation length, the nsd.conf option reduces
365              packets as small as possible.  The default is no.
366
367       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
373       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
377              response to UDP type ANY queries, and it  allows  TCP  type  ANY
378              queries like normal.  The default is no.
379
380       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
386       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
396       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
401       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
406              unblocked  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
417       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
424       rrl-ipv4-prefix-length: <subnet>
425              IPv4 prefix length. Addresses are grouped by netblock.   Default
426              24.
427
428       rrl-ipv6-prefix-length: <subnet>
429              IPv6  prefix length. Addresses are grouped by netblock.  Default
430              64.
431
432       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
439       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
447              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,
450              because the private key is read while root permissions are  held
451              and before chroot (if any).
452
453       tls-service-pem: <filename>
454              The public key certificate pem file for the tls service. Default
455              is "", turned off.
456
457       tls-service-ocsp: <filename>
458              The ocsp pem file  for  the  tls  service,  for  OCSP  stapling.
459              Default  is  "",  turned  off.  An external process prepares and
460              updates 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
469       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
474   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
484       control-enable: <yes or no>
485              Enable remote control, default is no.
486
487       control-interface: <ip4 or ip6>
488              NSD will  bind  to  the  listed  addresses  to  service  control
489              requests (on TCP).  Can be given multiple times to bind multiple
490              ip-addresses.  Use 0.0.0.0  and  ::0  to  service  the  wildcard
491              interface.   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
495              With  an absolute path, a unix local named pipe is used for con‐
496              trol.  The file is created with user and group that  is  config‐
497              ured  and  access  bits  are  set  to allow members of the group
498              access.  Further access can be controlled by setting permissions
499              on  the  directory  containing the control socket file.  The key
500              and cert files are not used when control is via the named  pipe,
501              because access control is via file and directory permission.
502
503       control-port: <number>
504              The port number for remote control service. 8952 by default.
505
506       server-key-file: <filename>
507              Path     to    the    server    private    key,    by    default
508              /etc/nsd/nsd_server.key.  This file is generated by the nsd-con‐
509              trol-setup  utility.   This  file is used by the nsd server, but
510              not by nsd-control.
511
512       server-cert-file: <filename>
513              Path  to  the  server  self  signed  certificate,   by   default
514              /etc/nsd/nsd_server.pem.  This file is generated by the nsd-con‐
515              trol-setup utility.  This file is used by the  nsd  server,  and
516              also by nsd-control.
517
518       control-key-file: <filename>
519              Path   to   the   control   client   private   key,  by  default
520              /etc/nsd/nsd_control.key.   This  file  is  generated   by   the
521              nsd-control-setup utility.  This file is used by nsd-control.
522
523       control-cert-file: <filename>
524              Path   to   the   control   client   certificate,   by   default
525              /etc/nsd/nsd_control.pem.  This certificate  has  to  be  signed
526              with  the  server  certificate.   This  file is generated by the
527              nsd-control-setup utility.  This file is used by nsd-control.
528
529   Pattern Options
530       The pattern: clause is used to denote a set of options to apply to some
531       zones.  The same zone options as for a zone are allowed.
532
533       name: <string>
534              The  name  of  the  pattern.  This is a (case sensitive) string.
535              The pattern names that start with "_implicit_" are  used  inter‐
536              nally  for  zones  that  have  no  pattern  (they are defined in
537              nsd.conf directly).
538
539       include-pattern: <pattern-name>
540              The options from the given pattern are included at this point in
541              this pattern.  The referenced pattern must be defined above this
542              one.
543
544       <zone option>: <value>
545              The zone options such as  zonefile,  allow-notify,  request-xfr,
546              allow-axfr-fallback,  notify,  notify-retry, provide-xfr, zones‐
547              tats, and outgoing-interface can be given.  They are applied  to
548              the patterns and zones that include this pattern.
549
550   Zone Options
551       For  every  zone  the options need to be specified in one zone: clause.
552       The access control list elements can be given  multiple  times  to  add
553       multiple servers. These elements need to be added explicitly.
554
555       For  zones  that  are configured in the nsd.conf config file their set‐
556       tings are hardcoded (in an implicit pattern for  themselves  only)  and
557       they  cannot  be  deleted  via delzone, but remove them from the config
558       file and repattern.
559
560       name: <string>
561              The name of the zone. This is the domain name of the apex of the
562              zone.  May end with a '.' (in FQDN notation). For example "exam‐
563              ple.com", "sub.example.net.". This attribute must be present  in
564              each zone.
565
566       zonefile: <filename>
567              The  file  containing the zone information. If this attribute is
568              present it is used to read and write the zone contents.  If  the
569              attribute is absent it prevents writing out of the zone.
570
571              The  string  is  processed  so that one string can be used (in a
572              pattern) for a lot of different zones.  If the label or  charac‐
573              ter  does  not  exist  the  percent-character is replaced with a
574              period for output (i.e. for the third character in a two  letter
575              domain name).
576
577              %s is replaced with the zone name.
578
579              %1 is replaced with the first character of the zone name.
580
581              %2 is replaced with the second character of the zone name.
582
583              %3 is replaced with the third character of the zone name.
584
585              %z is replaced with the toplevel domain name of the zone.
586
587              %y is replaced with the next label under the toplevel domain.
588
589              %x  is  replaced  with  the  next-next  label under the toplevel
590              domain.
591
592       allow-notify: <ip-spec> <key-name | NOKEY | BLOCKED>
593              Access control list. The listed (primary) address is allowed  to
594              send notifies to this (secondary) server. Notifies from unlisted
595              or specifically BLOCKED addresses are  discarded.  If  NOKEY  is
596              given  no  TSIG signature is required.  BLOCKED supersedes other
597              entries, other entries are scanned for a match in the  order  of
598              the statements.
599
600              The  ip-spec is either a plain IP address (IPv4 or IPv6), or can
601              be  a  subnet  of  the   form   1.2.3.4/24,   or   masked   like
602              1.2.3.4&255.255.255.0  or  a range of the form 1.2.3.4-1.2.3.25.
603              A port number can be added using a suffix of @number, for  exam‐
604              ple  1.2.3.4@5300  or  1.2.3.4/24@5300  for port 5300.  Note the
605              ip-spec ranges do not use spaces around the /, &, @ and  -  sym‐
606              bols.
607
608       request-xfr: [AXFR|UDP] <ip-address> <key-name | NOKEY>
609              Access  control list. The listed address (the master) is queried
610              for AXFR/IXFR on update. A port number can be added using a suf‐
611              fix  of  @number, for example 1.2.3.4@5300. The specified key is
612              used during AXFR/IXFR.
613
614              If the AXFR option is given, the server will  not  be  contacted
615              with  IXFR  queries  but  only AXFR requests will be made to the
616              server. This allows an NSD secondary to  have  a  master  server
617              that runs NSD. If the AXFR option is left out then both IXFR and
618              AXFR requests are made to the master server.
619
620              If the UDP option is given, the secondary will use UDP to trans‐
621              mit  the IXFR requests. You should deploy TSIG when allowing UDP
622              transport, to authenticate notifies and zone  transfers.  Other‐
623              wise,  NSD is more vulnerable for Kaminsky-style attacks. If the
624              UDP option is left out then IXFR will be transmitted using TCP.
625
626       allow-axfr-fallback: <yes or no>
627              This option should be accompanied by request-xfr. It (dis)allows
628              NSD  (as  secondary)  to  fallback  to  AXFR if the primary name
629              server does not support IXFR. Default is yes.
630
631       size-limit-xfr: <number>
632              This option should be accompanied by request-xfr.  It  specifies
633              XFR  temporary  file  size  limit.   It can be used to stop very
634              large zone retrieval, that could otherwise use up a lot of  mem‐
635              ory  and  disk  space.   If this option is 0, unlimited. Default
636              value is 0.
637
638       notify: <ip-address> <key-name | NOKEY>
639              Access control list. The listed address (a secondary)  is  noti‐
640              fied of updates to this zone. A port number can be added using a
641              suffix of @number, for example 1.2.3.4@5300. The  specified  key
642              is  used  to  sign  the notify. Only on secondary configurations
643              will NSD be able to detect zone updates  (as  it  gets  notified
644              itself, or refreshes after a time).
645
646       notify-retry: <number>
647              This  option should be accompanied by notify. It sets the number
648              of retries when sending notifies.
649
650       provide-xfr: <ip-spec> <key-name | NOKEY | BLOCKED>
651              Access control list. The listed address (a secondary) is allowed
652              to  request AXFR from this server. Zone data will be provided to
653              the address. The specified key is used during AXFR. For unlisted
654              or  BLOCKED  addresses  no  data  is provided, requests are dis‐
655              carded.  BLOCKED supersedes other  entries,  other  entries  are
656              scanned  for  a  match in the order of the statements.  NSD pro‐
657              vides AXFR for its secondaries,  but  IXFR  is  not  implemented
658              (IXFR is implemented for request-xfr, but not for provide-xfr).
659
660              The  ip-spec is either a plain IP address (IPv4 or IPv6), or can
661              be  a  subnet  of  the   form   1.2.3.4/24,   or   masked   like
662              1.2.3.4&255.255.255.0  or  a range of the form 1.2.3.4-1.2.3.25.
663              A port number can be added using a suffix of @number, for  exam‐
664              ple  1.2.3.4@5300  or  1.2.3.4/24@5300  for  port 5300. Note the
665              ip-spec ranges do not use spaces around the /, &, @ and  -  sym‐
666              bols.
667
668       outgoing-interface: <ip-address>
669              Access  control  list.  The  listed  address  is used to request
670              AXFR|IXFR (in case of a secondary) or used to send notifies  (in
671              case of a primary).
672
673              The  ip-address  is  a  plain IP address (IPv4 or IPv6).  A port
674              number can be added using  a  suffix  of  @number,  for  example
675              1.2.3.4@5300.
676
677       max-refresh-time: <seconds>
678              Limit refresh time for secondary zones.  This is the timer which
679              checks to see if the zone has to be refetched when  it  expires.
680              Normally  the value from the SOA record is used, but this option
681              restricts that value.
682
683       min-refresh-time: <seconds>
684              Limit refresh time for secondary zones.
685
686       max-retry-time: <seconds>
687              Limit retry time for secondary zones.  This is the  timer  which
688              retries after a failed fetch attempt for the zone.  Normally the
689              value from the SOA record is used, followed  by  an  exponential
690              backoff, but this option restricts that value.
691
692       min-retry-time: <seconds>
693              Limit retry time for secondary zones.
694
695       min-expire-time: <seconds or refresh+retry+1>
696              Limit  expire  time  for  secondary  zones.   The  value  can be
697              expressed  either  by  a  number  of  seconds,  or  the   string
698              "refresh+retry+1".   With  the  latter  the  expire time will be
699              lower bound to the refresh plus the retry  value  from  the  SOA
700              record, plus 1.  The refresh and retry values will be subject to
701              the bounds configured with  max-refresh-time,  min-refresh-time,
702              max-retry-time and min-retry-time if given.
703
704       zonestats: <name>
705              When  compiled  with --enable-zone-stats NSD can collect statis‐
706              tics per zone.  This name gives the group where  statistics  are
707              added  to.   The  groups  are  output from nsd-control stats and
708              stats_noreset.  Default is "".  You can use "%s" to use the name
709              of  the  zone  to track its statistics.  If not compiled in, the
710              option can be given but is ignored.
711
712       include-pattern: <pattern-name>
713              The options from the given pattern are included at  this  point.
714              The referenced pattern must be defined above this zone.
715
716       rrl-whitelist: <rrltype>
717              This  option  causes  queries of this rrltype to be whitelisted,
718              for this zone. They receive  the  whitelist-ratelimit.  You  can
719              give   multiple   lines,  each  enables  a  new  rrltype  to  be
720              whitelisted for the zone. Default has none whitelisted. The rrl‐
721              type  is  the  query  classification that the NSD RRL employs to
722              make different types not interfere with one another.  The  types
723              are  logged  in  the  loglines when a subnet is blocked (in ver‐
724              bosity 2).  The RRL classification types are:  nxdomain,  error,
725              referral, any, rrsig, wildcard, nodata, dnskey, positive, all.
726
727       multi-master-check: <yes or no>
728              Default  no.   If  enabled, checks all masters for the last ver‐
729              sion.  It uses the higher version of all the configured masters.
730              Useful  if you have multiple masters that have different version
731              numbers served.
732
733   Key Declarations
734       The key: clause establishes a key for use in access control  lists.  It
735       has the following attributes.
736
737       name: <string>
738              The  key  name.  Used to refer to this key in the access control
739              list.  The key name has to be correct for tsig to work.  This is
740              because the key name is output on the wire.
741
742       algorithm: <string>
743              Authentication  algorithm  for  this  key.   Such  as  hmac-md5,
744              hmac-sha1,    hmac-sha224,    hmac-sha256,    hmac-sha384    and
745              hmac-sha512.   Can  also  be  abbreviated  as  'sha1', 'sha256'.
746              Default is sha256.  Algorithms are only available when they were
747              compiled in (available in the crypto library).
748
749       secret: <base64 blob>
750              The  base64  encoded  shared  secret.  It is possible to put the
751              secret: declaration (and base64 blob) into a different file, and
752              then  to  include: that file. In this way the key secret and the
753              rest of the configuration file, which may have  different  secu‐
754              rity policies, can be split apart.  The content of the secret is
755              the agreed base64 secret content.  To make it up, enter a  pass‐
756              word (its length must be a multiple of 4 characters, A-Za-z0-9),
757              or use dev-random output through a base64 encode filter.
758

NSD CONFIGURATION FOR BIND9 HACKERS

760       BIND9 is a name server implementation with its own  configuration  file
761       format, named.conf(5). BIND9 types zones as 'Master' or 'Slave'.
762
763   Slave zones
764       For a slave zone, the master servers are listed. The master servers are
765       queried for zone data, and are listened to  for  update  notifications.
766       In  NSD these two properties need to be configured separately, by list‐
767       ing the master address in allow-notify and request-xfr statements.
768
769       In BIND9 you only need to provide allow-notify elements for  any  extra
770       sources  of  notifications  (i.e.  the  operators),  NSD  needs to have
771       allow-notify for both masters and operators.  BIND9  allows  additional
772       transfer sources, in NSD you list those as request-xfr.
773
774       Here is an example of a slave zone in BIND9 syntax.
775
776       # Config file for example.org options {
777            dnssec-enable yes;
778       };
779
780       key tsig.example.org. {
781            algorithm hmac-md5;
782            secret "aaaaaabbbbbbccccccdddddd";
783       };
784
785       server 162.0.4.49 {
786            keys { tsig.example.org. ; };
787       };
788
789       zone "example.org" {
790            type slave;
791            file "secondary/example.org.signed";
792            masters { 162.0.4.49; };
793       };
794
795       For NSD, DNSSEC is enabled automatically for zones that are signed. The
796       dnssec-enable statement in the options clause is  not  needed.  In  NSD
797       keys  are  associated  with  an  IP  address in the access control list
798       statement, therefore the server{} statement is not needed. Below is the
799       same example in an NSD config file.
800
801       # Config file for example.org
802       key:
803            name: tsig.example.org.
804            algorithm: hmac-md5
805            secret: "aaaaaabbbbbbccccccdddddd"
806
807       zone:
808            name: "example.org"
809            zonefile: "secondary/example.org.signed"
810            # the master is allowed to notify and will provide zone data.
811            allow-notify: 162.0.4.49 NOKEY
812            request-xfr: 162.0.4.49 tsig.example.org.
813
814       Notice  that the master is listed twice, once to allow it to send noti‐
815       fies to this slave server and once to tell the slave  server  where  to
816       look for updates zone data. More allow-notify and request-xfr lines can
817       be added to specify more masters.
818
819       It is possible to specify extra allow-notify lines for  addresses  that
820       are also allowed to send notifications to this slave server.
821
822   Master zones
823       For  a  master zone in BIND9, the slave servers are listed. These slave
824       servers are sent notifications of updated and are  allowed  to  request
825       transfer  of the zone data. In NSD these two properties need to be con‐
826       figured separately.
827
828       Here is an example of a master zone in BIND9 syntax.
829
830       zone "example.nl" {
831            type master;
832            file "example.nl";
833       };
834
835       In NSD syntax this becomes:
836
837       zone:
838            name: "example.nl"
839            zonefile: "example.nl"
840            # allow anybody to request xfr.
841            provide-xfr: 0.0.0.0/0 NOKEY
842            provide-xfr: ::0/0 NOKEY
843
844            # to list a slave server you would in general give
845            # provide-xfr: 1.2.3.4 tsig-key.name.
846            # notify: 1.2.3.4 NOKEY
847
848   Other
849       NSD is an authoritative only DNS server. This means that it is meant as
850       a  primary  or  secondary  server  for zones, providing DNS data to DNS
851       resolvers and caches.  BIND9  can  function  as  an  authoritative  DNS
852       server,  the configuration options for that are compared with those for
853       NSD in this section. However, BIND9 can also function as a resolver  or
854       cache.  The  configuration  options  that BIND9 has for the resolver or
855       caching thus have no equivalents for NSD.
856

FILES

858       ""     default NSD database
859
860       /etc/nsd/nsd.conf
861              default NSD configuration file
862

SEE ALSO

864       nsd(8), nsd-checkconf(8), nsd-control(8)
865

AUTHORS

867       NSD was written by NLnet Labs and RIPE NCC joint team. Please see CRED‐
868       ITS file in the distribution for further details.
869

BUGS

871       nsd.conf  is parsed by a primitive parser, error messages may not be to
872       the point.
873
874
875
876NLnet Labs                       Jan 26, 2021                      nsd.conf(5)
Impressum