Provided by: nsd_4.1.7-1_amd64 
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/lib/nsd/nsd.db"
zonelistfile: "/var/lib/nsd/zone.list"
username: nsd
logfile: "/var/log/nsd.log"
pidfile: "/run/nsd/nsd.pid"
xfrdfile: "/var/lib/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: and key: and pattern: and zone: are allowed. These are followed by their
attributes or the start of a new server: or key: or pattern: or zone: 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. The pattern: attribute is followed by the zone
options for zones that use the pattern.
Files can be included using the include: directive. It can appear anywhere, 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]
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. 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]
Same as ip-address (for easy 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.
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.
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/lib/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/lib/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 commandline option -i.
version: <string>
Returns the specified version string when asked for CH TXT version.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.
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 100. 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. Default 4096.
ipv6-edns-size: <number>
Preferred EDNS buffer size for IPv6. Default 4096.
pidfile: <filename>
Use the pid file instead of the platform specific default, usually /run/nsd/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.
chroot: <directory>
NSD will chroot on startup to the specified directory. Note that if elsewhere in the configuration
you specify an absolute pathname 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, zonelistfile, logfile, pidfile, xfrdfile, xfrdir, server-key-file, server-
cert-file, control-key-file and control-cert-file relative 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 behavior of NSD.
Default is /var/lib/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 second.
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. 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. Successful 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.
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 printout 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.
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
command 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 database also commits zone transfer contents. You can configure
it away from the default by putting the config statement for zonefiles-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 collisions.
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 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. 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.
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 generated 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.
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-control-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-control-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 internally 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, zonestats, 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 settings 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 "example.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 character 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 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. BLOCKED supersedes other entries,
other entries are scanned for a match in the order of the statements. NSD provides 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 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.
zonestats: <name>
When compiled with --enable-zone-stats NSD can collect statistics 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 rrltype 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 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 notifications. In NSD these two properties need to be configured separately, by
listing 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 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/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 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.