nsd.conf(5) nsd 4.0.3 nsd.conf(5)NAMEnsd.conf - NSD configuration file
SYNOPSISnsd.confDESCRIPTION
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/db/nsd/nsd.db"
zonelistfile: "/var/db/nsd/zone.list"
username: nsd
logfile: "/var/log/nsd.log"
pidfile: "/var/run/nsd/nsd.pid"
xfrdfile: "/var/db/nsd/xfrd.state"
zone:
name: example.com
# note that quotes are optional on the value
zonefile: /etc/nsd/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: 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 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).
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.
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. Default is no.
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.
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.
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.
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 trans‐
fers 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, usu‐
ally /var/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 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. For more details see the section on zone
expiry behavior 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 /var/db/nsd.
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.
hide-version: <yes or no>
Prevent NSD from replying with the version string on CHAOS class
queries.
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 enabled. The nsd-control reload
command reloads zone files regardless of this option.
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.
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, and out‐
going-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.
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.
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.
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.
include-pattern: <pattern-name>
The options from the given pattern are included at this point.
The referenced pattern must be defined above this zone.
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 secu‐
rity 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 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 ALSOnsd(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.
BUGSnsd.conf is parsed by a primitive parser, error messages may not be to
the point.
NLnet Labs Mar 14, 2014 nsd.conf(5)
