Provided by: nsd_4.0.1-1ubuntu0.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.
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/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
# 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 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).
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/lib/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/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.
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.
ipv6-edns-size: <number>
Preferred EDNS buffer size for IPv6.
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. 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.
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.
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 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-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.
rrl-ipv4-prefix-length: <subnet>
IPv4 prefix length. Addresses are grouped by netblock.
rrl-ipv6-prefix-length: <subnet>
IPv6 prefix length. Addresses are grouped by netblock.
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.
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, 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.
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.
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.
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.