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

NSD CONFIGURATION FOR BIND9 HACKERS

889       BIND9  is  a name server implementation with its own configuration file
890       format, named.conf(5). BIND9 types zones as 'Master' or 'Slave'.
891
892   Slave zones
893       For a slave zone, the master servers are listed. The master servers are
894       queried  for  zone  data, and are listened to for update notifications.
895       In NSD these two properties need to be configured separately, by  list‐
896       ing the master address in allow-notify and request-xfr statements.
897
898       In  BIND9  you only need to provide allow-notify elements for any extra
899       sources of notifications (i.e. the operators), NSD needs  to  have  al‐
900       low-notify  for  both  masters  and  operators. BIND9 allows additional
901       transfer sources, in NSD you list those as request-xfr.
902
903       Here is an example of a slave zone in BIND9 syntax.
904
905       # Config file for example.org options {
906            dnssec-enable yes;
907       };
908
909       key tsig.example.org. {
910            algorithm hmac-md5;
911            secret "aaaaaabbbbbbccccccdddddd";
912       };
913
914       server 162.0.4.49 {
915            keys { tsig.example.org. ; };
916       };
917
918       zone "example.org" {
919            type slave;
920            file "secondary/example.org.signed";
921            masters { 162.0.4.49; };
922       };
923
924       For NSD, DNSSEC is enabled automatically for zones that are signed. The
925       dnssec-enable  statement  in  the  options clause is not needed. In NSD
926       keys are associated with an IP  address  in  the  access  control  list
927       statement, therefore the server{} statement is not needed. Below is the
928       same example in an NSD config file.
929
930       # Config file for example.org
931       key:
932            name: tsig.example.org.
933            algorithm: hmac-md5
934            secret: "aaaaaabbbbbbccccccdddddd"
935
936       zone:
937            name: "example.org"
938            zonefile: "secondary/example.org.signed"
939            # the master is allowed to notify and will provide zone data.
940            allow-notify: 162.0.4.49 NOKEY
941            request-xfr: 162.0.4.49 tsig.example.org.
942
943       Notice that the master is listed twice, once to allow it to send  noti‐
944       fies  to  this  slave server and once to tell the slave server where to
945       look for updates zone data. More allow-notify and request-xfr lines can
946       be added to specify more masters.
947
948       It  is  possible to specify extra allow-notify lines for addresses that
949       are also allowed to send notifications to this slave server.
950
951   Master zones
952       For a master zone in BIND9, the slave servers are listed.  These  slave
953       servers  are  sent  notifications of updated and are allowed to request
954       transfer of the zone data. In NSD these two properties need to be  con‐
955       figured separately.
956
957       Here is an example of a master zone in BIND9 syntax.
958
959       zone "example.nl" {
960            type master;
961            file "example.nl";
962       };
963
964       In NSD syntax this becomes:
965
966       zone:
967            name: "example.nl"
968            zonefile: "example.nl"
969            # allow anybody to request xfr.
970            provide-xfr: 0.0.0.0/0 NOKEY
971            provide-xfr: ::0/0 NOKEY
972
973            # to list a slave server you would in general give
974            # provide-xfr: 1.2.3.4 tsig-key.name.
975            # notify: 1.2.3.4 NOKEY
976
977   Other
978       NSD is an authoritative only DNS server. This means that it is meant as
979       a primary or secondary server for zones, providing DNS data to DNS  re‐
980       solvers  and caches. BIND9 can function as an authoritative DNS server,
981       the configuration options for that are compared with those for  NSD  in
982       this  section. However, BIND9 can also function as a resolver or cache.
983       The configuration options that BIND9 has for the  resolver  or  caching
984       thus have no equivalents for NSD.
985

FILES

987       ""     default NSD database
988
989       /etc/nsd/nsd.conf
990              default NSD configuration file
991

SEE ALSO

993       nsd(8), nsd-checkconf(8), nsd-control(8)
994

AUTHORS

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

BUGS

1000       nsd.conf is parsed by a primitive parser, error messages may not be  to
1001       the point.
1002
1003
1004
1005NLnet Labs                       Dec  9, 2021                      nsd.conf(5)
Impressum