nsd.conf(5) nsd 4.8.0 nsd.conf(5) #
nsd.conf(5) nsd 4.8.0 nsd.conf(5)
NNAAMMEE #
nnssdd..ccoonnff - NSD configuration file
SSYYNNOOPPSSIISS #
nnssdd..ccoonnff
DDEESSCCRRIIPPTTIIOONN #
NNssdd..ccoonnff 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".
NNssdd..ccoonnff specifies options for the nsd server, zone files, primaries and
secondaries.
EEXXAAMMPPLLEE #
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 "@dbfile@"
zonelistfile: "/var/nsd/db/zone.list"
username: _nsd
logfile: "/var/log/nsd.log"
pidfile: ""
xfrdfile: "/var/nsd/run/xfrd.state"
zone:
name: example.com
zonefile: /var/nsd/etc/example.com.zone
zone:
# this server is master, 192.0.2.1 is the secondary.
name: masterzone.com
zonefile: /var/nsd/etc/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: /var/nsd/etc/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.
FFIILLEE FFOORRMMAATT #
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 sseerrvveerr::, vveerriiffyy::, kkeeyy::, ppaatttteerrnn::, zzoonnee::,
ttllss--aauutthh::, and rreemmoottee--ccoonnttrrooll:: are allowed. These are followed by their
attributes or a new top-level keyword. The zzoonnee:: attribute is followed by
zone options. The sseerrvveerr:: attribute is followed by global options for the
NNSSDD server. The vveerriiffyy:: attribute is used to control zone verification. A
kkeeyy:: attribute is used to define keys for authentication. The ppaatttteerrnn::
attribute is followed by the zone options for zones that use the pattern.
A ttllss--aauutthh:: attribute is used to define credentials for authenticating an
outgoing TLS connection used for XFR-over-TLS.
Files can be included using the iinncclluuddee:: directive. It can appear
anywhere, and takes a single filename as an argument. Processing
continues as if the text from the included file were 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 gglloobb(7).
If no files match the pattern, this is not an error.
SSeerrvveerr OOppttiioonnss The global options (if not overridden from the NSD commandline) are taken from the sseerrvveerr:: clause. There may only be one sseerrvveerr:: clause.
iipp--aaddddrreessss:: <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
NSD will bind to the listed ip-address. Can be given 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 --aa..
To limit which NSD server(s) listen on the given interface,
specify one or more servers separated by whitespace after
<ip>[@port]. Ranges can be used as a shorthand to specify multiple
consecutive servers. By default every server will listen.
If an interface name is used instead of ip4 or ip6, the list of IP
addresses associated with that interface is picked up and used at
server start.
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).
iinntteerrffaaccee:: <ip4 or ip6>[@port] [servers] [bindtodevice] [setfib]
Same as ip-address (for ease of compatibility with unbound.conf).
iipp--ttrraannssppaarreenntt:: <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.
iipp--ffrreeeebbiinndd:: <yes or no>
Set the IP_FREEBIND option to bind to nonlocal addresses and
interfaces that are down. Similar to ip-transparent. Default is
no.
rreeuusseeppoorrtt:: <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.
sseenndd--bbuuffffeerr--ssiizzee:: <number>
Set the send buffer size for query-servicing sockets. Set to 0 to
use the default settings.
rreecceeiivvee--bbuuffffeerr--ssiizzee:: <number>
Set the receive buffer size for query-servicing sockets. Set to 0
to use the default settings.
ddeebbuugg--mmooddee:: <yes or no>
Turns on debugging mode for nsd, does not fork a daemon process.
Default is no. Same as commandline option --dd.. 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.
ddoo--iipp44:: <yes or no>
If yes, NSD listens to IPv4 connections. Default yes.
ddoo--iipp66:: <yes or no>
If yes, NSD listens to IPv6 connections. Default yes.
zzoonneelliissttffiillee:: <filename>
By default _/_v_a_r_/_n_s_d_/_d_b_/_z_o_n_e_._l_i_s_t 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.
iiddeennttiittyy:: <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 --ii. See hide-identity to set the server to not
respond to such queries.
vveerrssiioonn:: <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.
nnssiidd:: <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 --II.
llooggffiillee:: <filename>
Log messages to the logfile. The default is to log to stderr and
syslog (with facility LOG_DAEMON). Same as commandline option --ll.
lloogg--oonnllyy--ssyysslloogg:: <yes or no>
Log messages only to syslog. Useful with systemd so that print to
stderr does not cause duplicate log strings in journald. Before
syslog has been opened, the server uses stderr. Stderr is also
used if syslog is not available. Default is no.
sseerrvveerr--ccoouunntt:: <number>
Start this many NSD servers. Default is 1. Same as commandline
option --NN.
ccppuu--aaffffiinniittyy:: <number> <number> ...
Overall CPU affinity for NSD server(s). Default is no affinity.
--nn.
sseerrvveerr--NN--ccppuu--aaffffiinniittyy:: <number>
Bind NSD server specified by N to a specific core. Default is to
have affinity set to every core specified in cpu-affinity. This
setting only takes effect if cpu-affinity is enabled. --nn
xxffrrdd--ccppuu--aaffffiinniittyy:: <number>
Bind xfrd to a specific core. Default is to have affinity set to
every core specified in cpu-affinity. This setting only takes
effect if cpu-affinity is enabled. --nn
ttccpp--ccoouunntt:: <number>
The maximum number of concurrent, active TCP connections by each
server. Default is 100. Same as commandline option --nn.
ttccpp--rreejjeecctt--oovveerrffllooww:: <yes or no>
If set to yes, TCP connections made beyond the maximum set by tcp-
count will be dropped immediately (accepted and closed). Default
is no.
ttccpp--qquueerryy--ccoouunntt:: <number>
The maximum number of queries served on a single TCP connection.
Default is 0, meaning there is no maximum.
ttccpp--ttiimmeeoouutt:: <number>
Overrides the default TCP timeout. This also affects zone
transfers over TCP. The default is 120 seconds.
ttccpp--mmssss:: <number>
Maximum segment size (MSS) of TCP socket on which the server
responds to queries. Value lower than common MSS on Ethernet (1220
for example) will address path MTU problem. Note that not all
platform supports socket option to set MSS (TCP_MAXSEG). Default
is system default MSS determined by interface MTU and negotiation
between server and client.
oouuttggooiinngg--ttccpp--mmssss:: <number>
Maximum segment size (MSS) of TCP socket for outgoing XFR request
to other nameservers. Value lower than common MSS on Ethernet
(1220 for example) will address path MTU problem. Note that not
all platform supports socket option to set MSS (TCP_MAXSEG).
Default is system default MSS determined by interface MTU and
negotiation between NSD and other servers.
xxffrrdd--ttccpp--mmaaxx:: <number>
Number of sockets for xfrd to use for outgoing zone transfers.
Default 128. Increase it to allow more zone transfer sockets,
like to 256. To save memory, this can be lowered, set it lower
together with some other settings to have reduced memory footprint
for NSD. xfrd-tcp-max: 32 and xfrd-tcp-pipeline: 128 and rrl-size:
1000
This reduces memory footprint, other memory usage is caused mainly
by the server-count setting, the number of server processes, and
the tcp-count setting, which keeps buffers per server process, and
by the size of the zone data.
xxffrrdd--ttccpp--ppiippeelliinnee:: <number>
Number of simultaneous outgoing zone transfers that are possible
on the tcp sockets of xfrd. Max is 65536, default is 128.
iippvv44--eeddnnss--ssiizzee:: <number>
Preferred EDNS buffer size for IPv4. Default 1232.
iippvv66--eeddnnss--ssiizzee:: <number>
Preferred EDNS buffer size for IPv6. Default 1232.
ppiiddffiillee:: <filename>
Use the pid file instead of the platform specific default, usually
_. Same as commandline option --PP. With "" there is no pidfile,
for some startup management setups, where a pidfile is not useful
to have.
ppoorrtt:: <number>
Answer queries on the specified port. Default is 53. Same as
commandline option --pp.
ssttaattiissttiiccss:: <number>
If not present no statistics are dumped. Statistics are produced
every number seconds. Same as commandline option --ss.
cchhrroooott:: <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 cchhrroooott 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
"_/_v_a_r_/_n_s_d" is used. Same as commandline option --tt.
uusseerrnnaammee:: <username>
After binding the socket, drop user privileges and assume the
username. Can be username, id or id.gid. Same as commandline
option --uu.
zzoonneessddiirr:: <directory>
Change the working directory to the specified directory before
accessing zone files. Also, NSD will access ddaattaabbaassee,
zzoonneelliissttffiillee, llooggffiillee, ppiiddffiillee, xxffrrddffiillee, xxffrrddiirr, sseerrvveerr--kkeeyy--ffiillee,
sseerrvveerr--cceerrtt--ffiillee, ccoonnttrrooll--kkeeyy--ffiillee and ccoonnttrrooll--cceerrtt--ffiillee relative
to this directory. Set the value to "" (the empty string) to
disable the change of working directory. By default
"_/_v_a_r_/_n_s_d_/_z_o_n_e_s" is used.
ddiiffffffiillee:: <filename>
Ignored, for compatibility with NSD3 config files.
xxffrrddffiillee:: <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 _/_v_a_r_/_n_s_d_/_r_u_n_/_x_f_r_d_._s_t_a_t_e.
xxffrrddiirr:: <directory>
The zone transfers are stored here before they are processed. A
directory is created here that is removed when NSD exits. Default
is _/_v_a_r_/_n_s_d_/_r_u_n_/_x_f_r.
xxffrrdd--rreellooaadd--ttiimmeeoouutt:: <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.
vveerrbboossiittyy:: <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.
hhiiddee--vveerrssiioonn:: <yes or no>
Prevent NSD from replying with the version string on CHAOS class
queries. Default is no.
hhiiddee--iiddeennttiittyy:: <yes or no>
Prevent NSD from replying with the identity string on CHAOS class
queries. Default is no.
ddrroopp--uuppddaatteess:: <yes or no>
If set to yes, drop received packets with the UPDATE opcode.
Default is no.
uussee--ssyysstteemmdd:: <yes or no>
This option is deprecated and ignored. If compiled with
libsystemd, NSD signals readiness to systemd and use of the option
is not necessary.
lloogg--ttiimmee--aasscciiii:: <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.
rroouunndd--rroobbiinn:: <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.
mmiinniimmaall--rreessppoonnsseess:: <yes or no>
Enable minimal responses for smaller answers. This makes packets
smaller. Extra data is only added for referrals, when it is
really necessary. This is different from the --enable-minimal-
responses configure time option, that reduces packets, but exactly
to the fragmentation length, the nsd.conf option reduces packets
as small as possible. The default is yes.
ccoonnffiinnee--ttoo--zzoonnee:: <yes or no>
If set to yes, additional information will not be added to the
response if the apex zone of the additional information does not
match the apex zone of the initial query (E.G. CNAME resolution).
Default is no.
rreeffuussee--aannyy:: <yes or no>
Refuse queries of type ANY. This is useful to stop query floods
trying to get large responses. Note that rrl ratelimiting also
has type ANY as a ratelimiting type. It sends truncation in
response to UDP type ANY queries, and it allows TCP type ANY
queries like normal. The default is yes.
zzoonneeffiilleess--cchheecckk:: <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.
zzoonneeffiilleess--wwrriittee:: <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.
rrrrll--ssiizzee:: <numbuckets>
This option gives the size of the hashtable. Default 1000000. More
buckets use more memory, and reduce the chance of hash collisions.
rrrrll--rraatteelliimmiitt:: <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).
rrrrll--sslliipp:: <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.
rrrrll--iippvv44--pprreeffiixx--lleennggtthh:: <subnet>
IPv4 prefix length. Addresses are grouped by netblock. Default
24.
rrrrll--iippvv66--pprreeffiixx--lleennggtthh:: <subnet>
IPv6 prefix length. Addresses are grouped by netblock. Default
64.
rrrrll--wwhhiitteelliisstt--rraatteelliimmiitt:: <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.
aannsswweerr--ccooookkiiee:: <yes or no>
Enable to answer to requests containing DNS Cookies as specified
in RFC7873. Default is yes.
ccooookkiiee--sseeccrreett:: <128 bit hex string>
Servers in an anycast deployment need to be able to verify each
other's DNS Server Cookies. For this they need to share the
secret used to construct and verify the DNS Cookies. Default is a
128 bits random secret generated at startup time. This option is
ignored if a ccooookkiiee--sseeccrreett--ffiillee is present. In that case the
secrets from that file are used in DNS Cookie calculations.
ccooookkiiee--sseeccrreett--ffiillee:: <filename>
File from which the secrets are read used in DNS Cookie
calculations. When this file exists, the secrets in this file are
used and the secret specified by the ccooookkiiee--sseeccrreett option is
ignored. Default is /var/nsd/etc/nsd_cookiesecrets.txt
The content of this file must be manipulated with the
aadddd__ccooookkiiee__sseeccrreett, ddrroopp__ccooookkiiee__sseeccrreett and aaccttiivvaattee__ccooookkiiee__sseeccrreett
commands to the _n_s_d_-_c_o_n_t_r_o_l(8) tool. Please see that manpage how
to perform a safe cookie secret rollover.
ttllss--sseerrvviiccee--kkeeyy:: <filename>
If enabled, the server provides TLS service on TCP sockets with
the TLS service port number. The port number (853) is configured
with tls-port. To turn it on, create an interface: option line in
config with @port appended to the IP-address. This creates the
extra socket on which the DNS over TLS service is provided.
The file is the private key for the TLS session. The public
certificate is in the tls-service-pem file. Default is "", turned
off. Requires a restart (a reload is not enough) if changed,
because the private key is read while root permissions are held
and before chroot (if any).
ttllss--sseerrvviiccee--ppeemm:: <filename>
The public key certificate pem file for the tls service. Default
is "", turned off.
ttllss--sseerrvviiccee--ooccsspp:: <filename>
The ocsp pem file for the tls service, for OCSP stapling. Default
is "", turned off. An external process prepares and updates the
OCSP stapling data. Like this,
openssl ocsp -no_nonce \
-respout /path/to/ocsp.pem \
-CAfile /path/to/ca_and_any_intermediate.pem \
-issuer /path/to/direct_issuer.pem \
-cert /path/to/cert.pem \
-url "$( openssl x509 -noout -text -in /path/to/cert.pem |
grep 'OCSP - URI:' | cut -d: -f2,3 )"
ttllss--ppoorrtt:: <number>
The port number on which to provide TCP TLS service, default is
853, only interfaces configured with that port number as @number
get DNS over TLS service.
ttllss--cceerrtt--bbuunnddllee:: <filename>
If null or "", the default verify locations are used. Set it to
the certificate bundle file, for example "/etc/pki/tls/certs/ca-
bundle.crt". These certificates are used for authenticating
Transfer over TLS (XoT) connections.
pprrooxxyy--pprroottooccooll--ppoorrtt:: <number>
The port number for proxy protocol service. If the statement is
given multiple times, additional port numbers can be used for
proxy protocol service. The interface definitions that use this
port number expect PROXYv2 proxy protocol traffic, for UDP, TCP
and for TLS service.
RReemmoottee CCoonnttrrooll The rreemmoottee--ccoonnttrrooll:: clause is used to set options for using the _n_s_d_-_c_o_n_t_r_o_l(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 _n_s_d_-_c_o_n_t_r_o_l_-_s_e_t_u_p 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.
ccoonnttrrooll--eennaabbllee:: <yes or no>
Enable remote control, default is no.
ccoonnttrrooll--iinntteerrffaaccee:: <ip4 or ip6 | interface name | absolute path>
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.
If an interface name is used instead of ip4 or ip6, the list of IP
addresses associated with that interface is picked up and used at
server start.
With an absolute path, a unix local named pipe is used for
control. The file is created with user and group that is
configured and access bits are set to allow members of the group
access. Further access can be controlled by setting permissions
on the directory containing the control socket file. The key and
cert files are not used when control is via the named pipe,
because access control is via file and directory permission.
ccoonnttrrooll--ppoorrtt:: <number>
The port number for remote control service. 8952 by default.
sseerrvveerr--kkeeyy--ffiillee:: <filename>
Path to the server private key, by default
_/_v_a_r_/_n_s_d_/_e_t_c_/_n_s_d___s_e_r_v_e_r_._k_e_y. This file is generated by the
_n_s_d_-_c_o_n_t_r_o_l_-_s_e_t_u_p utility. This file is used by the nsd server,
but not by _n_s_d_-_c_o_n_t_r_o_l.
sseerrvveerr--cceerrtt--ffiillee:: <filename>
Path to the server self signed certificate, by default
_/_v_a_r_/_n_s_d_/_e_t_c_/_n_s_d___s_e_r_v_e_r_._p_e_m. This file is generated by the
_n_s_d_-_c_o_n_t_r_o_l_-_s_e_t_u_p utility. This file is used by the nsd server,
and also by _n_s_d_-_c_o_n_t_r_o_l.
ccoonnttrrooll--kkeeyy--ffiillee:: <filename>
Path to the control client private key, by default
_/_v_a_r_/_n_s_d_/_e_t_c_/_n_s_d___c_o_n_t_r_o_l_._k_e_y. This file is generated by the
_n_s_d_-_c_o_n_t_r_o_l_-_s_e_t_u_p utility. This file is used by _n_s_d_-_c_o_n_t_r_o_l.
ccoonnttrrooll--cceerrtt--ffiillee:: <filename>
Path to the control client certificate, by default
_/_v_a_r_/_n_s_d_/_e_t_c_/_n_s_d___c_o_n_t_r_o_l_._p_e_m. This certificate has to be signed
with the server certificate. This file is generated by the
_n_s_d_-_c_o_n_t_r_o_l_-_s_e_t_u_p utility. This file is used by _n_s_d_-_c_o_n_t_r_o_l.
VVeerriiffiieerr ooppttiioonnss The vveerriiffyy:: clause is used to enable or disable zone verification, configure listen interfaces and control the global defaults.
eennaabbllee:: <yes or no>
Enable zone verification. Default is no.
ppoorrtt:: <number>
The port to answer verifier queries on. Default is 5347.
iipp--aaddddrreessss::
Interfaces to bind for zone verification (default are the
localhost interfaces, usually 127.0.0.1 and ::1). To bind to
multiple IP addresses, list them one by one. Optionally, Socket
options cannot be specified for verify ip-address
vveerriiffyy--zzoonneess:: <yes or no>
Verify zones by default.
vveerriiffiieerr:: <command>
When an update is received for the zone (by IXFR or AXFR) this
program will be run to assess the zone with the update. If the
program exits with a status code of 0, the zone is considered good
and will be served. Any other status code will designate the zone
bad and the received update will be discarded. The zone will
continue to be served but without the update.
The following environment variables are available to verifiers:
VVEERRIIFFYY__ZZOONNEE #
The domain name of the zone to be verified.
VVEERRIIZZFFYY__ZZOONNEE__OONN__SSTTDDIINN #
When the zone can be read from standard input
(stdin), this variable is set to "yes", otherwise it
is set to "no".
VVEERRIIFFYY__IIPP__AADDDDRREESSSSEESS #
The first address on which the zones to be assessed
will be served. If IPv6 is available an IPv6
address will be preferred over IPv4.
VVEERRIIFFYY__PPOORRTT #
The port number for VVEERRIIFFYY__IIPP__AADDDDRREESSSS.
VVEERRIIFFYY__IIPPVV66__AADDDDRREESSSS #
The first IPv6 address on which the zones to be
assessed will be served.
VVEERRIIFFYY__IIPPVV66__PPOORRTT #
The port number for VVEERRIIFFYY__IIPPVV66__AADDDDRREESSSS.
VVEERRIIFFYY__IIPPVV44__AADDDDRREESSSS #
The first IPv4 address on which the zones to be
assessed will be served.
VVEERRIIFFYY__IIPPVV44__PPOORRTT #
The port number for VVEERRIIFFYY__IIPPVV44__AADDDDRREESSSS.
vveerriiffiieerr--ccoouunntt:: <number>
Maximum number of verifiers to run concurrently. Default is 1.
vveerriiffiieerr--ffeeeedd--zzoonnee:: <yes or no>
Feed the updated zone to the verifier over standard input (stdin).
vveerriiffiieerr--ttiimmeeoouutt:: <seconds>
The maximum number of seconds a verifier is allowed to run for
assessing one zone. If the verifier takes longer, it will be
terminated and the zone update will be discarded. The default is 0
seconds which means the verifier may take as long as it needs.
PPaatttteerrnn OOppttiioonnss The ppaatttteerrnn:: clause is used to denote a set of options to apply to some zones. The same zone options as for a zone are allowed.
nnaammee:: <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).
iinncclluuddee--ppaatttteerrnn:: <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.
<<zzoonnee ooppttiioonn>>:: <value>
The zone options such as zzoonneeffiillee, aallllooww--qquueerryy, aallllooww--nnoottiiffyy,
rreeqquueesstt--xxffrr, aallllooww--aaxxffrr--ffaallllbbaacckk, nnoottiiffyy, nnoottiiffyy--rreettrryy,
pprroovviiddee--xxffrr, ssttoorree--iixxffrr, iixxffrr--nnuummbbeerr, iixxffrr--ssiizzee, ccrreeaattee--iixxffrr,
zzoonneessttaattss, oouuttggooiinngg--iinntteerrffaaccee, vveerriiffyy--zzoonnee, vveerriiffiieerr,
vveerriiffiieerr--ffeeeedd--zzoonnee, and vveerriiffiieerr--ttiimmeeoouutt can be given. They are
applied to the patterns and zones that include this pattern.
ZZoonnee OOppttiioonnss For every zone the options need to be specified in one zzoonnee:: 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 _n_s_d_._c_o_n_f 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.
nnaammee:: <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.
zzoonneeffiillee:: <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).
%%ss is replaced with the zone name.
%%11 is replaced with the first character of the zone name.
%%22 is replaced with the second character of the zone name.
%%33 is replaced with the third character of the zone name.
%%zz is replaced with the toplevel domain name of the zone.
%%yy is replaced with the next label under the toplevel domain.
%%xx is replaced with the next-next label under the toplevel domain.
aallllooww--qquueerryy:: <ip-spec> <key-name | NOKEY | BLOCKED>
Access control list. When at least one aallllooww--qquueerryy option is
specified, then the in the aallllooww--qquueerryy options specified addresses
are are allowed to query the server for the zone. Queries 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. Without aallllooww--qquueerryy options, queries are allowed from
any IP address without TSIG key (which is the default).
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.
Note the ip-spec ranges do not use spaces around the /, &, @ and -
symbols.
aallllooww--nnoottiiffyy:: <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.
rreeqquueesstt--xxffrr:: [AXFR|UDP] <ip-address> <key-name | NOKEY> [tls-auth-name]
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 tls-auth-name is included, the specified tls-
auth clause will be used to perform authenticated XFR-over-TLS.
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.
If a tls-auth-name is given then TLS (by default on port 853) will
be used for all zone transfers for the zone. If authentication of
the master based on the specified tls-auth authentication
information fails, the XFR request will not be sent. Support for
TLS 1.3 is required for XFR-over-TLS.
aallllooww--aaxxffrr--ffaallllbbaacckk:: <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.
ssiizzee--lliimmiitt--xxffrr:: <number>
This option should be accompanied by request-xfr. It specifies XFR
temporary file size limit. It can be used to stop very large zone
retrieval, that could otherwise use up a lot of memory and disk
space. If this option is 0, unlimited. Default value is 0.
nnoottiiffyy:: <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).
nnoottiiffyy--rreettrryy:: <number>
This option should be accompanied by notify. It sets the number of
retries when sending notifies.
pprroovviiddee--xxffrr:: <ip-spec> <key-name | NOKEY | BLOCKED>
Access control list. The listed address (a secondary) is allowed
to request XFR from this server. Zone data will be provided to the
address. The specified key is used during XFR. For unlisted or
BLOCKED addresses no data is provided and requests are discarded.
BLOCKED supersedes other entries and 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.
oouuttggooiinngg--iinntteerrffaaccee:: <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.
ssttoorree--iixxffrr:: <yes or no>
If enabled, IXFR contents are stored and provided to the set of
clients specified in the provide-xfr statement. Default is no.
IXFR content is a smaller set of changes that differ between zone
versions, whereas an AXFR contains the full contents of the zone.
iixxffrr--nnuummbbeerr:: <number>
The number of IXFR versions to store for this zone, at most.
Default is 5.
iixxffrr--ssiizzee:: <number>
The max storage to use for IXFR versions for this zone, in bytes.
Default is 1048576. A value of 0 means unlimited. If you want to
turn off IXFR storage, set the store-ixfr option to no. NSD does
not elide IXFR contents from versions that add and remove the same
data. It stores and transmits IXFRs as they were transmitted by
the upstream server.
ccrreeaattee--iixxffrr:: <yes or no>
If enabled, IXFR data is created when a zonefile is read by the
server. This requires store-ixfr to be set to yes, so that the
IXFR contents are saved to disk. Default is off. If the server is
not running, the nsd-checkzone -i option can be used to create an
IXFR file. When an IXFR is created, the server spools a version of
the zone to a temporary file, at the location where the ixfr files
are stored. This creates IXFR data when the zone is read from
file, but not when a zone is read by AXFR transfer from a server,
because then the topmost server that originates the data is the
one place where IXFR differences are computed and those
differences are then transmitted verbatim to all the other
servers.
mmaaxx--rreeffrreesshh--ttiimmee:: <seconds>
Limit refresh time for secondary zones. This is the timer which
checks to see if the zone has to be refetched when it expires.
Normally the value from the SOA record is used, but this option
restricts that value.
mmiinn--rreeffrreesshh--ttiimmee:: <seconds>
Limit refresh time for secondary zones.
mmaaxx--rreettrryy--ttiimmee:: <seconds>
Limit retry time for secondary zones. This is the timer which
retries after a failed fetch attempt for the zone. Normally the
value from the SOA record is used, followed by an exponential
backoff, but this option restricts that value.
mmiinn--rreettrryy--ttiimmee:: <seconds>
Limit retry time for secondary zones.
mmiinn--eexxppiirree--ttiimmee:: <seconds or refresh+retry+1>
Limit expire time for secondary zones. The value can be expressed
either by a number of seconds, or the string "refresh+retry+1".
With the latter the expire time will be lower bound to the refresh
plus the retry value from the SOA record, plus 1. The refresh and
retry values will be subject to the bounds configured with
max-refresh-time, min-refresh-time, max-retry-time and
min-retry-time if given.
zzoonneessttaattss:: <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.
iinncclluuddee--ppaatttteerrnn:: <pattern-name>
The options from the given pattern are included at this point.
The referenced pattern must be defined above this zone.
rrrrll--wwhhiitteelliisstt:: <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.
mmuullttii--mmaasstteerr--cchheecckk:: <yes or no>
Default no. If enabled, checks all masters for the last version.
It uses the higher version of all the configured masters. Useful
if you have multiple masters that have different version numbers
served.
vveerriiffyy--zzoonnee:: <yes or no>
Enable or disable verification for this zone. Default is
value-zones configured in vveerriiffyy::.
vveerriiffiieerr:: <command>
Command to execute to assess this zone. Default is verifier
configured in vveerriiffyy::.
vveerriiffiieerr--ffeeeedd--zzoonnee:: <yes or no>
Feed updated zone to verifier over standard input. Default is
verifier-feed-zone configured in vveerriiffyy::.
vveerriiffiieerr--ttiimmeeoouutt:: <<sseeccoonnddss>>
Number of seconds before verifier is forcefully terminated.
Specify 0 (zero) to not use a specific timeout. Default is
verifier-timeout from vveerriiffyy::.
KKeeyy DDeeccllaarraattiioonnss The kkeeyy:: clause establishes a key for use in access control lists. It has the following attributes.
nnaammee:: <string>
The key name. Used to refer to this key in the access control
list. The key name has to be correct for tsig to work. This is
because the key name is output on the wire.
aallggoorriitthhmm:: <string>
Authentication algorithm for this key. Such as hmac-md5,
hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384 and hmac-sha512.
Can also be abbreviated as 'sha1', 'sha256'. Default is sha256.
Algorithms are only available when they were compiled in
(available in the crypto library).
sseeccrreett:: <base64 blob>
The base64 encoded shared secret. It is possible to put the
sseeccrreett:: declaration (and base64 blob) into a different file, and
then to iinncclluuddee:: 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. The content of the secret is the
agreed base64 secret content. To make it up, enter a password
(its length must be a multiple of 4 characters, A-Za-z0-9), or use
dev-random output through a base64 encode filter.
TTLLSS AAuutthh DDeeccllaarraattiioonnss The ttllss--aauutthh:: clause establishes authentication attributes to use when authenticating the far end of an outgoing TLS connection used in access control lists for XFR-over-TLS. It has the following attributes.
nnaammee:: <string>
The tls-auth name. Used to refer to this TLS authentication
information in the access control list.
aauutthh--ddoommaaiinn--nnaammee:: <string>
The authentication domain name as defined in RFC8310.
cclliieenntt--cceerrtt:: <<ffiillee nnaammee ooff cclliieennttcceerrtt..ppeemm>>
If you want to use mutual TLS authentication, this is where the
client certificates can be configured that NSD uses to connect to
the upstream server to download the zone. The client public key
pem cert file can be configured here. Also configure a private key
with client-key.
cclliieenntt--kkeeyy:: <<ffiillee nnaammee ooff cclliieennttkkeeyy..kkeeyy>>
If you want to use mutual TLS authentication, the private key file
can be configured here for the client authentication.
cclliieenntt--kkeeyy--ppww:: <<ssttrriinngg>>
If the client-key file uses a password to decrypt the key before
it can be used, then the password can be specified here as a
string. It is possible to include other config files with the
include: option, and this can be used to move that sensitive data
to another file, if you wish.
DDNNSSTTAAPP LLooggggiinngg OOppttiioonnss DNSTAP support, when compiled in, is enabled in the ddnnssttaapp:: section. This starts a collector process that writes the log information to the destination.
ddnnssttaapp--eennaabbllee:: <yes or no>
If dnstap is enabled. Default no. If yes, it connects to the
dnstap server and if any of the dnstap-log-..-messages options is
enabled it sends logs for those messages to the server.
ddnnssttaapp--ssoocckkeett--ppaatthh:: <file name>
Sets the unix socket file name for connecting to the server that
is listening on that socket. Default is "/var/run/nsd-
dnstap.sock".
ddnnssttaapp--iipp:: <"" or addr[@port]>
If disabled with "", the socket path is used. With a value, like
address or address@port, like "127.0.0.1@3333" TCP or TLS is used.
Default is "".
ddnnssttaapp--ttllss:: <yes or no>
If enabled, TLS is used to the address specified in ddnnssttaapp--iipp.
Otherwise, TCP is used. Default is yes.
ddnnssttaapp--ttllss--sseerrvveerr--nnaammee:: <string>
The name for authenticating the upstream server. With "" disabled.
ddnnssttaapp--ttllss--cclliieenntt--kkeeyy--ffiillee:: <file name>
The key file for client authentication, or "" disabled.
ddnnssttaapp--ttllss--cclliieenntt--cceerrtt--ffiillee:: <file name>
The cert file for client authentication, or "" disabled.
ddnnssttaapp--sseenndd--iiddeennttiittyy:: <yes or no>
If enabled, the server identity is included in the log messages.
Default is no.
ddnnssttaapp--sseenndd--vveerrssiioonn:: <yes or no>
If enabled, the server version if included in the log messages.
Default is no.
ddnnssttaapp--iiddeennttiittyy:: <string>
The identity to send with messages, if "" the hostname is used.
Default is "".
ddnnssttaapp--vveerrssiioonn:: <string>
The version to send with messages, if "" the package version is
used. Default is "".
ddnnssttaapp--lloogg--aauutthh--qquueerryy--mmeessssaaggeess:: <yes or no>
Enable to log auth query messages. Default is no. These are
client queries to NSD.
ddnnssttaapp--lloogg--aauutthh--rreessppoonnssee--mmeessssaaggeess:: <yes or no>
Enable to log auth response messages. Default is no. These are
responses from NSD to clients.
NNSSDD CCOONNFFIIGGUURRAATTIIOONN FFOORR BBIINNDD99 HHAACCKKEERRSS #
BIND9 is a name server implementation with its own configuration file
format, named.conf(5). BIND9 types zones as 'Master' or 'Slave'.
SSllaavvee zzoonneess 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.
MMaasstteerr zzoonneess 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
OOtthheerr 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.
FFIILLEESS #
"@dbfile@"
default NNSSDD database
/var/nsd/etc/nsd.conf
default NNSSDD configuration file
SSEEEE AALLSSOO #
_n_s_d(8), _n_s_d_-_c_h_e_c_k_c_o_n_f(8), _n_s_d_-_c_o_n_t_r_o_l(8)
AAUUTTHHOORRSS #
NNSSDD was written by NLnet Labs and RIPE NCC joint team. Please see CREDITS
file in the distribution for further details.
BBUUGGSS #
nnssdd..ccoonnff is parsed by a primitive parser, error messages may not be to
the point.
NLnet Labs December 6, 2023 nsd.conf(5)