nsd.conf(5)                        nsd 4.3.5                       nsd.conf(5)



NAME
       nsd.conf - NSD configuration file

SYNOPSIS
       nsd.conf

DESCRIPTION
       Nsd.conf  is  used  to configure nsd(8). The file format has attributes
       and values. Some attributes have attributes inside them.  The  notation
       is: attribute: value.

       Comments  start  with  #  and  last to the end of line. Empty lines are
       ignored as is whitespace at the beginning of  a  line.  Quotes  can  be
       used, for names with spaces, eg. "file name.zone".

       Nsd.conf  specifies  options  for the nsd server, zone files, primaries
       and secondaries.

EXAMPLE
       An example of a short nsd.conf file is below.

       # Example.com nsd.conf file
       # This is a comment.

       server:
            server-count: 1 # use this number of cpu cores
            database: ""  # or use "/var/db/nsd/nsd.db"
            zonelistfile: "/var/db/nsd/zone.list"
            username: nsd
            logfile: "/var/log/nsd.log"
            pidfile: "/var/run/nsd.pid"
            xfrdfile: "/var/db/nsd/xfrd.state"

       zone:
            name: example.com
            zonefile: /etc/nsd/example.com.zone

       zone:
            # this server is master, 192.0.2.1 is the secondary.
            name: masterzone.com
            zonefile: /etc/nsd/masterzone.com.zone
            notify: 192.0.2.1 NOKEY
            provide-xfr: 192.0.2.1 NOKEY

       zone:
            # this server is secondary, 192.0.2.2 is master.
            name: secondzone.com
            zonefile: /etc/nsd/secondzone.com.zone
            allow-notify: 192.0.2.2 NOKEY
            request-xfr: 192.0.2.2 NOKEY

       Then, use kill -HUP to reload changes from master zone files.  And  use
       kill -TERM to stop the server.

FILE FORMAT
       There  must be whitespace between keywords. Attribute keywords end with
       a colon ':'. An attribute is followed by its containing attributes,  or
       a value.

       At  the  top level only server:, key:, pattern:, zone:, and remote-con-
       trol: are allowed. These are followed by their attributes or a new top-
       level  keyword.  The  zone:  attribute is followed by zone options. The
       server: attribute is followed by global options for the NSD  server.  A
       key:  attribute is used to define keys for authentication. The pattern:
       attribute is followed by the zone options for zones that use  the  pat-
       tern.

       Files  can be included using the include: directive. It can appear any-
       where, and takes a single filename as an argument. Processing continues
       as  if  the text from the included file was copied into the config file
       at that point.  If a chroot is used  an  absolute  filename  is  needed
       (with  the  chroot prepended), so that the include can be parsed before
       and after application of the chroot (and the  knowledge  of  what  that
       chroot  is).  You can use '*' to include a wildcard match of files, eg.
       "foo/nsd.d/*.conf".  Also '?', '{}', '[]', and '~' work,  see  glob(7).
       If no files match the pattern, this is not an error.

   Server Options
       The  global  options  (if  not overridden from the NSD commandline) are
       taken from the server: clause. There may only be one server: clause.

       ip-address: <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
              NSD will bind to the listed ip-address. Can  be  given  multiple
              times  to  bind multiple ip-addresses. Optionally, a port number
              can be given.  If none are given NSD  listens  to  the  wildcard
              interface. Same as commandline option -a.

              To  limit  which  NSD  server(s)  listen on the given interface,
              specify one  or  more  servers  separated  by  whitespace  after
              <ip>[@port]. Ranges can be used as a shorthand to specify multi-
              ple consecutive servers. By default every server will listen.

              If an interface name is used instead of ip4 or ip6, the list  of
              IP  addresses  associated  with  that interface is picked up and
              used at server start.

              For servers with multiple IP addresses that can be used to  send
              traffic  to  the  internet,  list them one by one, or the source
              address of replies could be wrong.  This is because if  the  udp
              socket  associates  a  source address of 0.0.0.0 then the kernel
              picks an ip-address with which to send to the internet,  and  it
              picks  the  wrong  one.  Typically needed for anycast instances.
              Use ip-transparent to be able to list  addresses  that  turn  on
              later (typical for certain load-balancing).

       interface: <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
              Same   as   ip-address   (for   ease   of   compatibility   with
              unbound.conf).

       ip-transparent: <yes or no>
              Allows NSD to bind to non local addresses.  This  is  useful  to
              have  NSD listen to IP addresses that are not (yet) added to the
              network interface, so that it can answer  immediately  when  the
              address is added. Default is no.

       ip-freebind: <yes or no>
              Set  the  IP_FREEBIND  option  to bind to nonlocal addresses and
              interfaces that are down.  Similar to  ip-transparent.   Default
              is no.

       reuseport: <yes or no>
              Use  the SO_REUSEPORT socket option, and create file descriptors
              for every server in the server-count.  This improves performance
              of  the network stack.  Only really useful if you also configure
              a server-count higher than 1 (such as, equal to  the  number  of
              cpus).  The default is no.  It works on Linux, but does not work
              on FreeBSD, and likely does not work on other systems.

       send-buffer-size: <number>
              Set the send buffer size for query-servicing sockets.  Set to  0
              to use the default settings.

       receive-buffer-size: <number>
              Set the receive buffer size for query-servicing sockets.  Set to
              0 to use the default settings.

       debug-mode: <yes or no>
              Turns on debugging mode for nsd, does not fork a daemon process.
              Default  is no. Same as commandline option -d.  If set to yes it
              does not fork and stays in the foreground, which can be  helpful
              for  commandline  debugging,  but is also used by certain server
              supervisor processes to ascertain that the server is running.

       do-ip4: <yes or no>
              If yes, NSD listens to IPv4 connections.  Default yes.

       do-ip6: <yes or no>
              If yes, NSD listens to IPv6 connections.  Default yes.

       database: <filename>
              By default '/var/db/nsd/nsd.db' is used. The specified  file  is
              used to store the compiled zone information. Same as commandline
              option -f.  If set to "" then no database is  used.   This  uses
              less  memory  but  zone updates are not (immediately) spooled to
              disk.

       zonelistfile: <filename>
              By default /var/db/nsd/zone.list is used. The specified file  is
              used  to store the dynamically added list of zones.  The list is
              written to by NSD to add and delete zones.  It is  a  text  file
              with  a  zone-name  and pattern-name on each line.  This file is
              used for the nsd-control addzone and delzone commands.

       identity: <string>
              Returns the specified identity when asked for CH TXT  ID.SERVER.
              Default  is the name as returned by gethostname(3). Same as com-
              mandline option -i.  See hide-identity to set the server to  not
              respond to such queries.

       version: <string>
              Returns  the specified version string when asked for CH TXT ver-
              sion.server, and version.bind queries.  Default is the  compiled
              package  version.   See  hide-version  to  set the server to not
              respond to such queries.

       nsid: <string>
              Add the specified nsid to the EDNS section of  the  answer  when
              queried  with an NSID EDNS enabled packet.  As a sequence of hex
              characters or with ascii_ prefix and then an ascii string.  Same
              as commandline option -I.

       logfile: <filename>
              Log messages to the logfile. The default is to log to stderr and
              syslog (with facility LOG_DAEMON). Same  as  commandline  option
              -l.

       log-only-syslog: <yes or no>
              Log  messages only to syslog.  Useful with systemd so that print
              to stderr does not cause  duplicate  log  strings  in  journald.
              Before  syslog  has been opened, the server uses stderr.  Stderr
              is also used if syslog is not available.  Default is no.

       server-count: <number>
              Start this many NSD servers. Default is 1. Same  as  commandline
              option -N.

       cpu-affinity: <number> <number> ...
              Overall  CPU affinity for NSD server(s). Default is no affinity.
              -n.

       server-N-cpu-affinity: <number>
              Bind NSD server specified by N to a specific core. Default is to
              have  affinity set to every core specified in cpu-affinity. This
              setting only takes effect if cpu-affinity is enabled.  -n

       xfrd-cpu-affinity: <number>
              Bind xfrd to a specific core. Default is to have affinity set to
              every  core  specified  in cpu-affinity. This setting only takes
              effect if cpu-affinity is enabled.  -n

       tcp-count: <number>
              The maximum number of concurrent, active TCP connections by each
              server.  Default is 100. Same as commandline option -n.

       tcp-reject-overflow: <yes or no>
              If  set  to  yes, TCP connections made beyond the maximum set by
              tcp-count will be dropped  immediately  (accepted  and  closed).
              Default is no.

       tcp-query-count: <number>
              The maximum number of queries served on a single TCP connection.
              Default is 0, meaning there is no maximum.

       tcp-timeout: <number>
              Overrides the default TCP timeout. This also affects zone trans-
              fers over TCP.  The default is 120 seconds.

       tcp-mss: <number>
              Maximum  segment  size  (MSS)  of TCP socket on which the server
              responds to queries. Value lower than  common  MSS  on  Ethernet
              (1220 for example) will address path MTU problem.  Note that not
              all platform supports socket option  to  set  MSS  (TCP_MAXSEG).
              Default  is  system  default MSS determined by interface MTU and
              negotiation between server and client.

       outgoing-tcp-mss: <number>
              Maximum segment size  (MSS)  of  TCP  socket  for  outgoing  XFR
              request to other namesevers. Value lower than common MSS on Eth-
              ernet (1220 for example) will address path  MTU  problem.   Note
              that  not  all  platform  supports  socket  option  to  set  MSS
              (TCP_MAXSEG).  Default  is  system  default  MSS  determined  by
              interface MTU and negotiation between NSD and other servers.

       ipv4-edns-size: <number>
              Preferred EDNS buffer size for IPv4.  Default 1232.

       ipv6-edns-size: <number>
              Preferred EDNS buffer size for IPv6.  Default 1232.

       pidfile: <filename>
              Use  the pid file instead of the platform specific default, usu-
              ally /var/run/nsd.pid.  Same as commandline option -P.  With  ""
              there is no pidfile, for some startup management setups, where a
              pidfile is not useful to have.

       port: <number>
              Answer queries on the specified port. Default  is  53.  Same  as
              commandline option -p.

       statistics: <number>
              If not present no statistics are dumped. Statistics are produced
              every number seconds. Same as commandline option -s.

       chroot: <directory>
              NSD will chroot on startup to the specified directory. Note that
              if  elsewhere in the configuration you specify an absolute path-
              name to a file inside the chroot, you have to prepend the chroot
              path.  That  way,  you  can  switch the chroot option on and off
              without having to modify anything else in the configuration. Set
              the  value  to  ""  (the empty string) to disable the chroot. By
              default "" is used. Same as commandline option -t.

       username: <username>
              After binding the socket, drop user privileges  and  assume  the
              username.  Can  be  username,  id or id.gid. Same as commandline
              option -u.

       zonesdir: <directory>
              Change the working directory to the specified  directory  before
              accessing  zone files. Also, NSD will access database, zonelist-
              file,  logfile,  pidfile,  xfrdfile,  xfrdir,   server-key-file,
              server-cert-file,  control-key-file  and control-cert-file rela-
              tive to this directory. Set the value to "" (the  empty  string)
              to   disable   the  change  of  working  directory.  By  default
              "/etc/nsd" is used.

       difffile: <filename>
              Ignored, for compatibility with NSD3 config files.

       xfrdfile: <filename>
              The soa timeout and zone transfer daemon in NSD  will  save  its
              state  to  this  file.  State  is read back after a restart. The
              state file can be deleted without too much harm, but  timestamps
              of  zones  will  be  gone.  If it is configured as "", the state
              file is not used, all slave zones are checked for  updates  upon
              startup.  For more details see the section on zone expiry behav-
              ior of NSD. Default is /var/db/nsd/xfrd.state.

       xfrdir: <directory>
              The zone transfers are stored here before they are processed.  A
              directory  is  created  here  that  is  removed  when NSD exits.
              Default is /tmp.

       xfrd-reload-timeout: <number>
              If this value is -1, xfrd will not trigger a reload after a zone
              transfer.  If  positive  xfrd will trigger a reload after a zone
              transfer, then it will wait for the number of seconds before  it
              will  trigger  a  new  reload.  Setting this value throttles the
              reloads to once per the number of seconds. The default is 1 sec-
              ond.

       verbosity: <level>
              This  value  specifies  the verbosity level for (non-debug) log-
              ging.  Default is 0. 1 gives  more  information  about  incoming
              notifies  and  zone  transfers.  2  lists soft warnings that are
              encountered. 3 prints more information.

              Verbosity 0 will print warnings and  errors,  and  other  events
              that are important to keep NSD running.

              Verbosity  1 prints additionally messages of interest.  Success-
              ful notifies, successful incoming zone  transfer  (the  zone  is
              updated),  failed  incoming  zone  transfers or the inability to
              process zone updates.

              Verbosity 2 prints additionally  soft  errors,  like  connection
              resets over TCP.  And notify refusal, and axfr request refusals.

       hide-version: <yes or no>
              Prevent NSD from replying with the version string on CHAOS class
              queries.  Default is no.

       hide-identity: <yes or no>
              Prevent NSD from replying with  the  identity  string  on  CHAOS
              class queries.  Default is no.

       drop-updates: <yes or no>
              If  set  to  yes,  drop received packets with the UPDATE opcode.
              Default is no.

       use-systemd: <yes or no>
              This option is deprecated and ignored.  If compiled with libsys-
              temd,  NSD signals readiness to systemd and use of the option is
              not necessary.

       log-time-ascii: <yes or no>
              Log time in ascii, if "no" then in seconds  epoch.   Default  is
              yes.   This chooses the format when logging to file.  The print-
              out via syslog has a timestamp formatted by syslog.

       round-robin: <yes or no>
              Enable round robin rotation of  records  in  the  answer.   This
              changes  the order of records in the answer and this may balance
              load across them.  The default is no.

       minimal-responses: <yes or no>
              Enable minimal responses for smaller answers.  This makes  pack-
              ets smaller.  Extra data is only added for referrals, when it is
              really necessary.  This is different from the  --enable-minimal-
              responses  configure  time  option,  that  reduces  packets, but
              exactly to the fragmentation length, the nsd.conf option reduces
              packets as small as possible.  The default is no.

       confine-to-zone: <yes or no>
              If  set  to yes, additional information will not be added to the
              response if the apex zone of the additional information does not
              match  the  apex  zone  of the initial query (E.G. CNAME resolu-
              tion). Default is no.

       refuse-any: <yes or no>
              Refuse queries of type ANY.  This is useful to stop query floods
              trying  to get large responses.  Note that rrl ratelimiting also
              has type ANY as a ratelimiting type.   It  sends  truncation  in
              response  to  UDP  type  ANY queries, and it allows TCP type ANY
              queries like normal.  The default is no.

       zonefiles-check: <yes or no>
              Make NSD check the mtime of zone files on start and sighup.   If
              you disable it it starts faster (less disk activity in case of a
              lot of zones).  The default is yes.  The nsd-control reload com-
              mand reloads zone files regardless of this option.

       zonefiles-write: <seconds>
              Write changed secondary zones to their zonefile every N seconds.
              If the zone (pattern) configuration has "" zonefile, it  is  not
              written.   Zones  that  have  received zone transfer updates are
              written to their zonefile.  Default is 0 (disabled)  when  there
              is a database, and 3600 (1 hour) when database is "".  The data-
              base also commits zone transfer contents.  You can configure  it
              away  from the default by putting the config statement for zone-
              files-write: after the database: statement in the config file.

       rrl-size: <numbuckets>
              This option gives the size of the  hashtable.  Default  1000000.
              More buckets use more memory, and reduce the chance of hash col-
              lisions.

       rrl-ratelimit: <qps>
              The max qps allowed (from one query source). Default is on (with
              a suggested 200 qps). If set to 0 then it is disabled (unlimited
              rate), also set the whitelist-ratelimit to 0  to  disable  rate-
              limit  processing.   If  you  set verbosity to 2 the blocked and
              unblocked subnets are logged.  Blocked queries are  blocked  and
              some  receive  TCP  fallback  replies.   Once  the rate limit is
              reached, NSD begins dropping responses. However,  one  in  every
              "rrl-slip"  number of responses is allowed, with the TC bit set.
              If slip is set to 2, the outgoing response rate will be  halved.
              If  it's set to 3, the outgoing response rate will be one-third,
              and so on.  If you set rrl-slip to 10,  traffic  is  reduced  to
              1/10th.    Ratelimit   options   rrl-ratelimit,   rrl-size   and
              rrl-whitelist-ratelimit are updated when nsd-control reconfig is
              done (also the zone-specific ratelimit options are updated).

       rrl-slip: <numpackets>
              This  option  controls the number of packets discarded before we
              send back a SLIP response (a response with "truncated"  bit  set
              to  one).  0 disables the sending of SLIP packets, 1 means every
              query will get a SLIP response.  Default is 2, cuts  traffic  in
              half and legit users have a fair chance to get a +TC response.

       rrl-ipv4-prefix-length: <subnet>
              IPv4  prefix length. Addresses are grouped by netblock.  Default
              24.

       rrl-ipv6-prefix-length: <subnet>
              IPv6 prefix length. Addresses are grouped by netblock.   Default
              64.

       rrl-whitelist-ratelimit: <qps>
              The  max  qps  for  query  sorts  for  a source, which have been
              whitelisted. Default on (with a suggested 2000  qps).  With  the
              rrl-whitelist  option  you  can  set specific queries to receive
              this qps limit instead of the normal limit.  With  the  value  0
              the rate is unlimited.

       tls-service-key: <filename>
              If  enabled, the server provides TLS service on TCP sockets with
              the TLS service port number.  The port number (853)  is  config-
              ured  with tls-port.  To turn it on, create an interface: option
              line in config with @port appended to the IP-address.  This cre-
              ates  the extra socket on which the DNS over TLS service is pro-
              vided.

              The file is the private key for the TLS session. The public cer-
              tificate  is  in the tls-service-pem file. Default is "", turned
              off. Requires a restart (a reload is  not  enough)  if  changed,
              because  the private key is read while root permissions are held
              and before chroot (if any).

       tls-service-pem: <filename>
              The public key certificate pem file for the tls service. Default
              is "", turned off.

       tls-service-ocsp: <filename>
              The  ocsp  pem  file  for  the  tls  service, for OCSP stapling.
              Default is "", turned off.  An  external  process  prepares  and
              updates the OCSP stapling data.  Like this,
                openssl ocsp -no_nonce \
                   -respout /path/to/ocsp.pem \
                   -CAfile /path/to/ca_and_any_intermediate.pem \
                   -issuer /path/to/direct_issuer.pem \
                   -cert /path/to/cert.pem \
                   -url  "$( openssl x509 -noout -text -in /path/to/cert.pem |
                grep 'OCSP - URI:' | cut -d: -f2,3 )"

       tls-port: <number>
              The port number on which to provide TCP TLS service, default  is
              853, only interfaces configured with that port number as @number
              get DNS over TLS service.

   Remote Control
       The remote-control: clause  is  used  to  set  options  for  using  the
       nsd-control(8)  tool to give commands to the running NSD server.  It is
       disabled by default, and listens for localhost by default.  It uses TLS
       over  TCP  where  the server and client authenticate to each other with
       self-signed certificates.  The self-signed certificates can  be  gener-
       ated  with  the  nsd-control-setup tool.  The key files are read by NSD
       before the chroot and before dropping user permissions, so they can  be
       outside the chroot and readable by the superuser only.

       control-enable: <yes or no>
              Enable remote control, default is no.

       control-interface: <ip4 or ip6>
              NSD  will  bind  to  the  listed  addresses  to  service control
              requests (on TCP).  Can be given multiple times to bind multiple
              ip-addresses.   Use  0.0.0.0  and  ::0  to  service the wildcard
              interface.  If none are  given  NSD  listens  to  the  localhost
              127.0.0.1  and ::1 interfaces for control, if control is enabled
              with control-enable.

              With an absolute path, a unix local named pipe is used for  con-
              trol.   The  file is created with user and group that is config-
              ured and access bits are set  to  allow  members  of  the  group
              access.  Further access can be controlled by setting permissions
              on the directory containing the control socket  file.   The  key
              and  cert files are not used when control is via the named pipe,
              because access control is via file and directory permission.

       control-port: <number>
              The port number for remote control service. 8952 by default.

       server-key-file: <filename>
              Path    to    the    server    private    key,    by     default
              /etc/nsd/nsd_server.key.  This file is generated by the nsd-con-
              trol-setup utility.  This file is used by the  nsd  server,  but
              not by nsd-control.

       server-cert-file: <filename>
              Path   to   the  server  self  signed  certificate,  by  default
              /etc/nsd/nsd_server.pem.  This file is generated by the nsd-con-
              trol-setup  utility.   This  file is used by the nsd server, and
              also by nsd-control.

       control-key-file: <filename>
              Path  to  the   control   client   private   key,   by   default
              /etc/nsd/nsd_control.key.    This   file  is  generated  by  the
              nsd-control-setup utility.  This file is used by nsd-control.

       control-cert-file: <filename>
              Path   to   the   control   client   certificate,   by   default
              /etc/nsd/nsd_control.pem.   This  certificate  has  to be signed
              with the server certificate.  This  file  is  generated  by  the
              nsd-control-setup utility.  This file is used by nsd-control.

   Pattern Options
       The pattern: clause is used to denote a set of options to apply to some
       zones.  The same zone options as for a zone are allowed.

       name: <string>
              The name of the pattern.  This is  a  (case  sensitive)  string.
              The  pattern  names that start with "_implicit_" are used inter-
              nally for zones that  have  no  pattern  (they  are  defined  in
              nsd.conf directly).

       include-pattern: <pattern-name>
              The options from the given pattern are included at this point in
              this pattern.  The referenced pattern must be defined above this
              one.

       <zone option>: <value>
              The  zone  options  such as zonefile, allow-notify, request-xfr,
              allow-axfr-fallback, notify, notify-retry,  provide-xfr,  zones-
              tats,  and outgoing-interface can be given.  They are applied to
              the patterns and zones that include this pattern.

   Zone Options
       For every zone the options need to be specified in  one  zone:  clause.
       The  access  control  list  elements can be given multiple times to add
       multiple servers. These elements need to be added explicitly.

       For zones that are configured in the nsd.conf config  file  their  set-
       tings  are  hardcoded  (in an implicit pattern for themselves only) and
       they cannot be deleted via delzone, but remove  them  from  the  config
       file and repattern.

       name: <string>
              The name of the zone. This is the domain name of the apex of the
              zone. May end with a '.' (in FQDN notation). For example  "exam-
              ple.com",  "sub.example.net.". This attribute must be present in
              each zone.

       zonefile: <filename>
              The file containing the zone information. If this  attribute  is
              present  it  is used to read and write the zone contents. If the
              attribute is absent it prevents writing out of the zone.

              The string is processed so that one string can  be  used  (in  a
              pattern)  for a lot of different zones.  If the label or charac-
              ter does not exist the  percent-character  is  replaced  with  a
              period  for output (i.e. for the third character in a two letter
              domain name).

              %s is replaced with the zone name.

              %1 is replaced with the first character of the zone name.

              %2 is replaced with the second character of the zone name.

              %3 is replaced with the third character of the zone name.

              %z is replaced with the toplevel domain name of the zone.

              %y is replaced with the next label under the toplevel domain.

              %x is replaced with  the  next-next  label  under  the  toplevel
              domain.

       allow-notify: <ip-spec> <key-name | NOKEY | BLOCKED>
              Access  control list. The listed (primary) address is allowed to
              send notifies to this (secondary) server. Notifies from unlisted
              or  specifically  BLOCKED  addresses  are discarded. If NOKEY is
              given no TSIG signature is required.  BLOCKED  supersedes  other
              entries,  other  entries are scanned for a match in the order of
              the statements.

              The ip-spec is either a plain IP address (IPv4 or IPv6), or  can
              be   a   subnet   of   the   form  1.2.3.4/24,  or  masked  like
              1.2.3.4&255.255.255.0 or a range of the  form  1.2.3.4-1.2.3.25.
              A  port number can be added using a suffix of @number, for exam-
              ple 1.2.3.4@5300 or 1.2.3.4/24@5300 for  port  5300.   Note  the
              ip-spec  ranges  do not use spaces around the /, &, @ and - sym-
              bols.

       request-xfr: [AXFR|UDP] <ip-address> <key-name | NOKEY>
              Access control list. The listed address (the master) is  queried
              for AXFR/IXFR on update. A port number can be added using a suf-
              fix of @number, for example 1.2.3.4@5300. The specified  key  is
              used during AXFR/IXFR.

              If  the  AXFR  option is given, the server will not be contacted
              with IXFR queries but only AXFR requests will  be  made  to  the
              server.  This  allows  an  NSD secondary to have a master server
              that runs NSD. If the AXFR option is left out then both IXFR and
              AXFR requests are made to the master server.

              If the UDP option is given, the secondary will use UDP to trans-
              mit the IXFR requests. You should deploy TSIG when allowing  UDP
              transport,  to  authenticate notifies and zone transfers. Other-
              wise, NSD is more vulnerable for Kaminsky-style attacks. If  the
              UDP option is left out then IXFR will be transmitted using TCP.

       allow-axfr-fallback: <yes or no>
              This option should be accompanied by request-xfr. It (dis)allows
              NSD (as secondary) to fallback  to  AXFR  if  the  primary  name
              server does not support IXFR. Default is yes.

       size-limit-xfr: <number>
              This  option  should be accompanied by request-xfr. It specifies
              XFR temporary file size limit.  It can  be  used  to  stop  very
              large  zone retrieval, that could otherwise use up a lot of mem-
              ory and disk space.  If this option  is  0,  unlimited.  Default
              value is 0.

       notify: <ip-address> <key-name | NOKEY>
              Access  control  list. The listed address (a secondary) is noti-
              fied of updates to this zone. A port number can be added using a
              suffix  of  @number, for example 1.2.3.4@5300. The specified key
              is used to sign the notify.  Only  on  secondary  configurations
              will  NSD  be  able  to detect zone updates (as it gets notified
              itself, or refreshes after a time).

       notify-retry: <number>
              This option should be accompanied by notify. It sets the  number
              of retries when sending notifies.

       provide-xfr: <ip-spec> <key-name | NOKEY | BLOCKED>
              Access control list. The listed address (a secondary) is allowed
              to request AXFR from this server. Zone data will be provided  to
              the address. The specified key is used during AXFR. For unlisted
              or BLOCKED addresses no data  is  provided,  requests  are  dis-
              carded.   BLOCKED  supersedes  other  entries, other entries are
              scanned for a match in the order of the  statements.   NSD  pro-
              vides  AXFR  for  its  secondaries,  but IXFR is not implemented
              (IXFR is implemented for request-xfr, but not for provide-xfr).

              The ip-spec is either a plain IP address (IPv4 or IPv6), or  can
              be   a   subnet   of   the   form  1.2.3.4/24,  or  masked  like
              1.2.3.4&255.255.255.0 or a range of the  form  1.2.3.4-1.2.3.25.
              A  port number can be added using a suffix of @number, for exam-
              ple 1.2.3.4@5300 or 1.2.3.4/24@5300  for  port  5300.  Note  the
              ip-spec  ranges  do not use spaces around the /, &, @ and - sym-
              bols.

       outgoing-interface: <ip-address>
              Access control list. The  listed  address  is  used  to  request
              AXFR|IXFR  (in case of a secondary) or used to send notifies (in
              case of a primary).

              The ip-address is a plain IP address (IPv4  or  IPv6).   A  port
              number  can  be  added  using  a  suffix of @number, for example
              1.2.3.4@5300.

       max-refresh-time: <seconds>
              Limit refresh time for secondary zones.  This is the timer which
              checks  to  see if the zone has to be refetched when it expires.
              Normally the value from the SOA record is used, but this  option
              restricts that value.

       min-refresh-time: <seconds>
              Limit refresh time for secondary zones.

       max-retry-time: <seconds>
              Limit  retry  time for secondary zones.  This is the timer which
              retries after a failed fetch attempt for the zone.  Normally the
              value  from  the  SOA record is used, followed by an exponential
              backoff, but this option restricts that value.

       min-retry-time: <seconds>
              Limit retry time for secondary zones.

       min-expire-time: <seconds or refresh+retry+1>
              Limit expire  time  for  secondary  zones.   The  value  can  be
              expressed   either  by  a  number  of  seconds,  or  the  string
              "refresh+retry+1".  With the latter  the  expire  time  will  be
              lower  bound  to  the  refresh plus the retry value from the SOA
              record, plus 1.  The refresh and retry values will be subject to
              the  bounds  configured with max-refresh-time, min-refresh-time,
              max-retry-time and min-retry-time if given.

       zonestats: <name>
              When compiled with --enable-zone-stats NSD can  collect  statis-
              tics  per  zone.  This name gives the group where statistics are
              added to.  The groups are  output  from  nsd-control  stats  and
              stats_noreset.  Default is "".  You can use "%s" to use the name
              of the zone to track its statistics.  If not  compiled  in,  the
              option can be given but is ignored.

       include-pattern: <pattern-name>
              The  options  from the given pattern are included at this point.
              The referenced pattern must be defined above this zone.

       rrl-whitelist: <rrltype>
              This option causes queries of this rrltype  to  be  whitelisted,
              for  this  zone.  They  receive the whitelist-ratelimit. You can
              give  multiple  lines,  each  enables  a  new  rrltype   to   be
              whitelisted for the zone. Default has none whitelisted. The rrl-
              type is the query classification that the  NSD  RRL  employs  to
              make  different types not interfere with one another.  The types
              are logged in the loglines when a subnet  is  blocked  (in  ver-
              bosity  2).   The RRL classification types are: nxdomain, error,
              referral, any, rrsig, wildcard, nodata, dnskey, positive, all.

       multi-master-check: <yes or no>
              Default no.  If enabled, checks all masters for  the  last  ver-
              sion.  It uses the higher version of all the configured masters.
              Useful if you have multiple masters that have different  version
              numbers served.

   Key Declarations
       The  key:  clause establishes a key for use in access control lists. It
       has the following attributes.

       name: <string>
              The key name. Used to refer to this key in  the  access  control
              list.  The key name has to be correct for tsig to work.  This is
              because the key name is output on the wire.

       algorithm: <string>
              Authentication  algorithm  for  this  key.   Such  as  hmac-md5,
              hmac-sha1,    hmac-sha224,    hmac-sha256,    hmac-sha384    and
              hmac-sha512.  Can  also  be  abbreviated  as  'sha1',  'sha256'.
              Default is sha256.  Algorithms are only available when they were
              compiled in (available in the crypto library).

       secret: <base64 blob>
              The base64 encoded shared secret. It  is  possible  to  put  the
              secret: declaration (and base64 blob) into a different file, and
              then to include: that file. In this way the key secret  and  the
              rest  of  the configuration file, which may have different secu-
              rity policies, can be split apart.  The content of the secret is
              the  agreed base64 secret content.  To make it up, enter a pass-
              word (its length must be a multiple of 4 characters, A-Za-z0-9),
              or use dev-random output through a base64 encode filter.

NSD CONFIGURATION FOR BIND9 HACKERS
       BIND9  is  a name server implementation with its own configuration file
       format, named.conf(5). BIND9 types zones as 'Master' or 'Slave'.

   Slave zones
       For a slave zone, the master servers are listed. The master servers are
       queried  for  zone  data, and are listened to for update notifications.
       In NSD these two properties need to be configured separately, by  list-
       ing the master address in allow-notify and request-xfr statements.

       In  BIND9  you only need to provide allow-notify elements for any extra
       sources of notifications  (i.e.  the  operators),  NSD  needs  to  have
       allow-notify  for  both  masters and operators. BIND9 allows additional
       transfer sources, in NSD you list those as request-xfr.

       Here is an example of a slave zone in BIND9 syntax.

       # Config file for example.org options {
            dnssec-enable yes;
       };

       key tsig.example.org. {
            algorithm hmac-md5;
            secret "aaaaaabbbbbbccccccdddddd";
       };

       server 162.0.4.49 {
            keys { tsig.example.org. ; };
       };

       zone "example.org" {
            type slave;
            file "secondary/example.org.signed";
            masters { 162.0.4.49; };
       };

       For NSD, DNSSEC is enabled automatically for zones that are signed. The
       dnssec-enable  statement  in  the  options clause is not needed. In NSD
       keys are associated with an IP  address  in  the  access  control  list
       statement, therefore the server{} statement is not needed. Below is the
       same example in an NSD config file.

       # Config file for example.org
       key:
            name: tsig.example.org.
            algorithm: hmac-md5
            secret: "aaaaaabbbbbbccccccdddddd"

       zone:
            name: "example.org"
            zonefile: "secondary/example.org.signed"
            # the master is allowed to notify and will provide zone data.
            allow-notify: 162.0.4.49 NOKEY
            request-xfr: 162.0.4.49 tsig.example.org.

       Notice that the master is listed twice, once to allow it to send  noti-
       fies  to  this  slave server and once to tell the slave server where to
       look for updates zone data. More allow-notify and request-xfr lines can
       be added to specify more masters.

       It  is  possible to specify extra allow-notify lines for addresses that
       are also allowed to send notifications to this slave server.

   Master zones
       For a master zone in BIND9, the slave servers are listed.  These  slave
       servers  are  sent  notifications of updated and are allowed to request
       transfer of the zone data. In NSD these two properties need to be  con-
       figured separately.

       Here is an example of a master zone in BIND9 syntax.

       zone "example.nl" {
            type master;
            file "example.nl";
       };

       In NSD syntax this becomes:

       zone:
            name: "example.nl"
            zonefile: "example.nl"
            # allow anybody to request xfr.
            provide-xfr: 0.0.0.0/0 NOKEY
            provide-xfr: ::0/0 NOKEY

            # to list a slave server you would in general give
            # provide-xfr: 1.2.3.4 tsig-key.name.
            # notify: 1.2.3.4 NOKEY

   Other
       NSD is an authoritative only DNS server. This means that it is meant as
       a primary or secondary server for zones,  providing  DNS  data  to  DNS
       resolvers  and  caches.  BIND9  can  function  as  an authoritative DNS
       server, the configuration options for that are compared with those  for
       NSD  in this section. However, BIND9 can also function as a resolver or
       cache. The configuration options that BIND9 has  for  the  resolver  or
       caching thus have no equivalents for NSD.

FILES
       "/var/db/nsd/nsd.db"
              default NSD database

       /etc/nsd/nsd.conf
              default NSD configuration file

SEE ALSO
       nsd(8), nsd-checkconf(8), nsd-control(8)

AUTHORS
       NSD was written by NLnet Labs and RIPE NCC joint team. Please see CRED-
       ITS file in the distribution for further details.

BUGS
       nsd.conf is parsed by a primitive parser, error messages may not be  to
       the point.



NLnet Labs                       Jan 26, 2021                      nsd.conf(5)