NSD has a vast array of configuration options for advanced use cases. To
configure the application, a
nsd.conf configuration file used. The file
format has attributes and values, and some attributes have attributes inside
The instructions in this page assume that NSD is already installed.
The configuration file¶
The configuration NSD uses is specified in the configuration file, which can be supplied to NSD using the
-c option. In the reference an example
nsd.conf can be found as well as the complete documentation of all the configurable options. The same example and reference can be found on your system using the
man nsd.conf command.
The basic rules are of the config file are:
The used notation is
Comments start with
#and extend to the end of a line
Empty lines are ignored, as is whitespace at the beginning of a line
Quotes can be used, for names containing spaces, e.g.
Below we’ll give an example config file, which specifies options for the NSD server, zone files, primaries and secondaries. This provide basic config whica can be used for as a starting point
The example configuration below specifies options for the NSD server, zone files, primaries and secondaries.
Here is an example config for
server: # use this number of cpu cores server-count: 1 # We recommend leaving this empty, otherwise use "/var/db/nsd/nsd.db" database: "" # the default file used for the nsd-control addzone and delzone commands # zonelistfile: "/var/db/nsd/zone.list" # The unprivileged user that will run NSD, can also be set to "" if # user privilige protection is not needed username: nsd # Default file where all the log messages go logfile: "/var/log/nsd.log" # Use this pid file instead of the platform specific default pidfile: "/var/run/nsd.pid" # Enable if privilege "jail" is needed for unprivileged user. Note # that other file paths may break when using chroot # chroot: "/etc/nsd/" # The default zone transfer file # xfrdfile: "/var/db/nsd/xfrd.state" # The default working directory before accessing zone files # zonesdir: "/etc/nsd" remote-control: # this allows the use of 'nsd-control' to control NSD. The default is "no" control-enable: yes # the interface NSD listens to for nsd-control. The default is 127.0.0.1 control-interface: 127.0.0.1 # the key files that allow the use of 'nsd-control'. The default path is "/etc/nsd/". Create these using the 'nsd-control-setup' utility server-key-file: /etc/nsd/nsd_server.key server-cert-file: /etc/nsd/nsd_server.pem control-key-file: /etc/nsd/nsd_control.key control-cert-file: /etc/nsd/nsd_control.pem zone: name: example.com zonefile: /etc/nsd/example.com.zone
We recommend not using the database (
database: "") as this is will slow down NSD operation. Depending on your needs, we also recommend keeping the
server-count lower or equal to the number of CPU cores your system has.
Optionally, you can control NSD (from the same or even a different device) by configuring remote-control. Using this tool, NSD can be controlled (find the reference of all the options :doc:`here<manpages/nsd-control>) which makes controling NSD much easier. If your install does not come with the keys neede for remote-control use pre-made, you can generate the keys using the nsd-control-setup command, which will create them for you.
You can test the config with nsd-checkconf. This tool will tell you what is wrong with the config and where the error occurs.
If you are happy with the config and any modifications you may have done, you can create the zone to go with the file we mentioned in the config. We show an example zone at the zonefile example.
Setting up a secondary zone¶
If your needs go further than just a few zones that are managed locally, NSD has got you covered. We won’t go into the theoretical details of primaries and secondaries here (we recommend this blog), but we will show how to configure it.
The example for a secondary looks like this:
zone: # this server is the primary, 192.0.2.1 is the secondary. name: primaryzone.com zonefile: /etc/nsd/primaryone.com.zone notify: 192.0.2.1 NOKEY # NOKEY for testing purposes only provide-xfr: 192.0.2.1 NOKEY # NOKEY for testing purposes only zone: # this server is secondary, 192.0.2.2 is primary. name: secondaryzone.com zonefile: /etc/nsd/secondaryzone.com.zone allow-notify: 192.0.2.2 NOKEY # NOKEY for testing purposes only request-xfr: 192.0.2.2 NOKEY # NOKEY for testing purposes only
Note that the
NOKEY keyword above are for testing purposes only, as this can introduce vulnerabilities when used in production environments.
For a secondary zone we list the primaries by IP address. Below is an example
of a secondary zone with two primary servers. If a primary only supports AXFR
transfers and not IXFR transfers (like NSD), specify the primary as
request-xfr: AXFR <ip_address> <key>. By default, all zone transfer requests
are made over TCP. If you want the IXFR request be transmitted over UDP, use
request-xfr: UDP <ip address> <key>.
zone: name: "example.com" zonefile: "example.com.zone" allow-notify: 22.214.171.124 NOKEY request-xfr: 126.96.36.199 NOKEY allow-notify: 188.8.131.52 NOKEY request-xfr: 184.108.40.206 NOKEY
By default, a secondary will fallback to AXFR requests if the primary told us it does not support IXFR. You can configure the secondary not to do AXFR fallback with:
For a primary zone, list the secondary servers, by IP address or subnet. Below is an example of a primary zone with two secondary servers:
zone: name: "example.com" zonefile: "example.com.zone" notify: 220.127.116.11 NOKEY provide-xfr: 18.104.22.168 NOKEY notify: 22.214.171.124 NOKEY provide-xfr: 126.96.36.199 NOKEY
You also can set the outgoing interface for notifies and zone transfer requests to satisfy access control lists at the other end:
By default, NSD will retry a notify up to five times. You can override that value with:
Zone transfers can be secured with TSIG keys, replace NOKEY with the name of the TSIG key to use. See Using TSIG for details.
Since NSD is written to be run on the root name servers, the config file can to contain something like:
zone: name: "." zonefile: "root.zone" provide-xfr: 0.0.0.0/0 NOKEY # allow axfr for everyone. provide-xfr: ::0/0 NOKEY
You should only do that if you’re intending to run a root server, NSD is not
suited for running a
. cache. Therefore if you choose to serve the
zone you have to make sure that the complete root zone is timely and fully
To prevent misconfiguration, NSD configure has the
--enable-root-server option, that is by default disabled.
In the config file, you can use patterns. A pattern can have the same
configuration statements that a zone can have. And then you can
include-pattern: <name-of-pattern> in a zone (or in another pattern) to
apply those settings. This can be used to organise the settings.
Remote controling NSD¶
The nsd-control tool is also controlled from the
file (and it’s manpage is found here). It uses TLS encrypted transport to 127.0.0.1, and if you want to use it
you have to setup the keys and also edit the config file. You can leave the
remote-control disabled (the secure default), or opt to turn it on:
# generate keys nsd-control-setup
# edit nsd.conf to add this remote-control: control-enable: yes
By default nsd-control is limited to localhost, as well as encrypted,
but some people may want to remotely administer their nameserver. What you then
do is setup nsd-control to listen to the public IP address, with
control-interface: <IP> after the control-enable statement.
Furthermore, you copy the key files
/etc/nsd/nsd_control.* to a remote host on the internet; on that host
you can run nsd-control with
<special config file>
which references same IP address
control-interface and references the copies
of the key files with
control-cert-file config lines after the
control-enable statement. The
nsd-server authenticates the nsd-control client, and also the
nsd-control client authenticates the nsd-server.
Starting up the first time¶
When you are done with the configuration file, check the syntax using
nsd-checkconf <name of configfile>
The zone files are read by the daemon, which builds
nsd.db with their
contents. You can start the daemon with:
nsd -c <name of configfile> or with "nsd-control start" (which execs nsd again). or simply with "nsd", which wil use the default configuration file
To check if the daemon is running look with ps, top, or if you enabled nsd-control:
To reload changed zone files after you edited them, without stopping the daemon, use this to check if files are modified:
kill -HUP `cat <name of nsd pidfile>` or "nsd-control reload" if you have remote-control enabled
With nsd-control you can also reread the config file, in case of new zones, etc.
To restart the daemon:
/etc/rc.d/nsd restart # or your system(d) equivalent
To shut it down (for example on the system shutdown) do:
kill -TERM <pid of nsd> or nsd-control stop
NSD will automatically keep track of secondary zones and update them when needed. When primary zones are updated and reloaded notifications are sent to secondary servers.
The zone transfers are applied to
nsd.db by the daemon. To write
changed contents of the zone files for secondary zones to disk in the text-based
zone file format, issue nsd-control write.
NSD will send notifications to secondary zones if a primary zone is updated. NSD will check for updates at primary servers periodically and transfer the updated zone by AXFR/IXFR and reload the new zone contents.
If you wish exert manual control use nsd-control notify,
transfer and force_transfer commands. The transfer
command will check for new versions of the secondary zones hosted by this NSD.
The notify command will send notifications to the secondary servers configured