nsd.conf(5)                                                         nsd 3.2.12                                                         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.

       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:
            database: "/var/lib/nsd3/nsd.db"
            username: nsd
            logfile: "/var/log/nsd.log"
            pidfile: "/var/run/nsd3/nsd.pid"
            difffile: "/var/lib/nsd3/ixfr.db"
            xfrdfile: "/var/lib/nsd3/xfrd.state"

       zone:
            name: example.com
            # note that quotes are optional on the value
            zonefile: /etc/nsd3/example.com.zone

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: or zone: or key: are allowed. These are followed by their attributes or the start of a new server: or zone:
       or key: clause. 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.

       Files  can be included using the include: directive. It can appear anywhere, and takes a single filename as an argument. Processing contin-
       ues as if the text from the included file was copied into the config file at that point.

   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]
              NSD will bind to the listed ip-address. Can be give 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.

       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.

       ip4-only: <yes or no>
              If yes, NSD only listens to IPv4 connections. Same as commandline option -4.

       ip6-only: <yes or no>
              If yes, NSD only listens to IPv6 connections. Same as commandline option -6.

       database: <filename>
              By  default  /var/lib/nsd3/nsd.db  is  used.  The specified file is used to store the compiled zone information. Same as commandline
              option -f.

       identity: <string>
              Returns the specified identity when asked for CH TXT ID.SERVER.  Default is the name as returned by gethostname(3). Same as command-
              line option -i.

       nsid: <string>
              Add  the  specified nsid to the EDNS section of the answer when queried with an NSID EDNS enabled packet. 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.

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

       tcp-count: <number>
              The maximum number of concurrent, active TCP connections by each server.  Default is 10. This option should have a value below 1000.
              Same as commandline option -n.

       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 transfers over TCP.

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

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

       pidfile: <filename>
              Use the pid file instead of the platform specific default, usually /var/run/nsd3/nsd.pid.  Same as commandline option -P.

       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.

       zone-stats-file: <filename>
              If per zone statistics is enabled, file to dump the statistics.

       chroot: <directory>
              NSD will chroot on startup to the specified directory. 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. Same as commandline  option  -d  for  zonec(8).
              Also nsd(8) will access files (pid file, database file, log file) relative to this directory. Set the value to "" (the empty string)
              to disable the change of working directory.

       difffile: <filename>
              When NSD receives IXFR updates it will store them in this file.  This file contains the differences between the  database  file  and
              the latest zone version. Default is /var/lib/nsd3/ixfr.db.

       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. For more details see the section on zone expiry behavior
              of NSD. Default is /var/lib/nsd3/xfrd.state.

       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 10 seconds.

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

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

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

       rrl-ratelimit: <qps>
              The  max  qps  allowed  (from  one  query  source).  Default 200 qps. If set to 0 then it is disabled (unlimited rate), also set the
              whilelist-ratelimit to 0 to disable ratelimit processing.  If you set verbosity to 2 the blocked and unblocked subnets  are  logged.
              Blocked queries are blocked and some receive TCP fallback replies.

       rrl-whitelist-ratelimit: <qps>
              The  max  qps for query sorts for a source, which have been whitelisted. Default 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.

   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.

       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. This file is used by zonec(8). This attribute must be present in each zone.

       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.

              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  example
              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 - symbols.

       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 suffix
              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 transmit the IXFR requests. You  should  deploy  TSIG  when  allowing  UDP
              transport,  to  authenticate  notifies  and zone transfers. Otherwise, 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.

       notify: <ip-address> <key-name | NOKEY>
              Access control list. The listed address (a secondary) is notified 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 discarded.

              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 example
              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 - symbols.

       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.

       rrl-whitelist: <rrltype>
              This option causes queries of this rrltype to be whitelisted, for this zone. They receive the whitelist-ratelimit. You can give mul-
              tiple lines, each enables a new rrltype to be whitelisted for the zone. Default has none whitelisted. The rrltype is the query clas-
              sification 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  verbosity 2).  The RRL classification types are: nxdomain, error, referral, any, rrsig, wildcard,
              nodata, dnskey, positive, all.

   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.

       algorithm: <string>
              Authentication algorithm for this key.

       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 security policies,
              can be split apart.

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  notifica-
       tions.   In NSD these two properties need to be configured separately, by listing the master address in allow-notify and request-xfr state-
       ments.

       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 notifies 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 configured 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/lib/nsd3/nsd.db
              default NSD database

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

SEE ALSO

       nsd(8), nsdc(8), nsd-checkconf(8), nsd-notify(8), nsd-patch(8), nsd-xfer(8), zonec(8)

AUTHORS

       NSD was written by NLnet Labs and RIPE NCC joint team. Please see CREDITS 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                                                         jul 19, 2012                                                        nsd.conf(5)