| nsd.conf(5) | nsd 4.13.0 | nsd.conf(5) |
nsd.conf - NSD configuration file
nsd.conf
This file is used to configure nsd(8). It specifies options for the nsd server, zone files, primaries and secondaries.
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 must be used for values with spaces in them, eg. "file name.zone".
An example of a short nsd.conf file is below.
# Example nsd.conf file for example.com. # This is a comment. server: server-count: 1 # use this number of cpu cores username: _nsd zonelistfile: /var/nsd/db/zone.list logfile: /var/log/nsd.log xfrdfile: /var/nsd/run/xfrd.state zone: name: example.com zonefile: /var/nsd/etc/example.com.zone zone: # this server is the primary and 192.0.2.1 is the secondary. name: primaryzone.com zonefile: /var/nsd/etc/primaryzone.com.zone notify: 192.0.2.1 NOKEY provide-xfr: 192.0.2.1 NOKEY zone: # this server is the secondary and 192.0.2.2 is the primary. name: secondaryzone.com zonefile: /var/nsd/etc/secondaryzone.com.zone allow-notify: 192.0.2.2 NOKEY request-xfr: 192.0.2.2 NOKEY
Then, use kill -HUP to reload changes from primary zone files. And use kill -TERM to stop the server.
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:, verify:, key:, pattern:, zone:, tls-auth:, and remote-control: are allowed. These are followed by their attributes or a new top-level keyword. The zone: attribute is followed by zone options. The server: attribute is followed by global options for the NSD server. The verify: attribute is used to control zone verification. 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. A tls-auth: attribute is used to define authentication attributes for TLS connections used for XFR-over-TLS.
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 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 glob(7). If no files match the pattern, this is not an error.
The global options (if not overridden from the NSD command-line) are taken from the server: clause. There may only be one server: clause.
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).
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.
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.
DNS Cookies increase transaction security and provide limited protection against denial-off-service amplification attacks. Server cookies will be created and included in responses. Server cookies are created based on the client cookie in the request, the current time, the client's IP address and a secret. When a client includes a valid server cookie in successive requests, the client will not be subjected to Request Rate Limiting (see rrl-ratelimit).
Servers in an anycast deployment need to be able to verify each other's server cookies. For this they need to share the secret used to construct and verify the cookies. These cookie secrets can be specified in the configuration files with the cookie-secret and cookie-staging-secret options.
If no cookie secrets are provided via configuration file, server cookie secrets can be added, dropped and activated with the nsd-control(8) tool. These secrets will be stored persistently in the cookie secret file for which the location can be specified with the cookie-secret-file option.
If no cookie secrets are provided via configuration file, and there is no or an empty cookie secret file, a random cookie secret is generated.
A cookie-staging-secret can only be configured when there is also a cookie-secret configured.
In NSD version 4.10.1 and earlier, the default location of the cookie secret file was "/var/nsd/etc/nsd_cookiesecrets.txt". For migration purposes, cookie secrets will be read from that location if no value is given for the cookie-secret-file option and when the current default location ("/var/db/nsd/cookiesecrets.txt") does not exist.
The content of the cookie secret file must be manipulated with the add_cookie_secret, drop_cookie_secret and activate_cookie_secret commands to the nsd-control(8) tool. Please see that manpage how to perform a safe cookie secret rollover.
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).
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 -ocsp_uri -in /path/to/cert.pem )"
Client (secondary) must enable tls-auth, configure client-cert and client-key and enable tls-auth in zone configuration in order to authenticate to a remote (primary) server.
Considerations:
• If cpu-affinity is configured, please be aware of the cpu
affinity of network device queues.
• The number of spawned servers depends on the number of combined
rx/tx channels/queues of the selected interface. As many processes as
there are combined channels on the specified interface will receive
traffic via XDP. server-count will be increased if necessary. If
server-count is higher, the excess processes will not use XDP.
• The PROXYv2 protocol, DNSTAP, and ratelimiting are currently not
supported via XDP.
This option needs to be set, even when NSD is configured not to load the specified XDP program (see xdp-program-load), to be able to determine the XSKMAP structure. In this case your XDP program needs to pin the above mentioned map in a bpffs (see xdp-bpffs-path).
Default is "/usr/share/nsd/xdp-dns-redirect_kern.o".
If NSD is configured to load an XDP program that pins its map, NSD needs to have read/write/execute access to the specified bpffs to be able to create and later delete the map pin. If you load the XDP program yourself, NSD only needs read and write access to the pin file itself (but at least execute access to the parent directories). The default bpffs (/sys/fs/bpf) usually doesn't have the necessary permissions set for non-root users. You can either set the necessary permissions or mount your own bpffs.
Default is "/sys/fs/bpf".
To generate per zone metrics, specify the zonestats option on the desired zones.
Beware, that when using nsd-control(8) stats (instead of stats_noreset), the statistics will be reset for the HTTP metrics endpoint as well.
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.
Default is 127.0.0.1 and ::1.
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.
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.
The verify: clause is used to enable or disable zone verification, configure listen interfaces and control the global defaults.
The following environment variables are available to verifiers:
VERIFY_ZONE
The domain name of the zone to be verified.
VERIFY_ZONE_ON_STDIN
When the zone can be read from standard input (stdin), this variable is
set to "yes", otherwise it is set to "no".
VERIFY_IP_ADDRESSES
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.
VERIFY_PORT
The port number for VERIFY_IP_ADDRESS.
VERIFY_IPV6_ADDRESS
The first IPv6 address on which the zones to be assessed will be
served.
VERIFY_IPV6_PORT
The port number for VERIFY_IPV6_ADDRESS.
VERIFY_IPV4_ADDRESS
The first IPv4 address of which the zones to be assessed will be
served.
VERIFY_IPV4_PORT
The port number for VERIFY_IPV4_ADDRESS.
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.
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.
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.
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.
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.
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 primary server that runs NSD. If the AXFR option is left out then both IXFR and AXFR requests are made to the primary 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 primary, 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.
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.
If a tls-auth-name is given then TLS authentication of the secondary will be performed for zone transfer requests for the zone. The remote end must connect to the tls-auth-port and must present a certificate with a SAN (Subject Alternative Name) DNS entry or CN (Common Name) entry equal to auth-domain-name of the defined tls-auth. The certificate validify is also verified with tls-cert-bundle. If authentication of the secondary, based on the specified tls-auth authentication information, fails the XFR zone transfer will be refused. If the connection is performed on the tls-port then no authentication will be performed and the transfer will not be refused. To enforce only authenticated zone transfers, tls-auth-xfr-only should also be enabled. Support for TLS 1.3 is required for XFR-over-TLS.
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.
A zone with the option set to producer, can be used to produce a catalog zone. Member zones for catalog producer zones can be added with "nsd-control addzone <zone> <pattern>", where <pattern> has a catalog-producer-zone option pointing to a catalog producer zone. Members will get a group property with the pattern name as value. Catalog producer zones must be primary zones and may not have a request-xfr option. Catalog producer zones will not read content from zone files, but will reconstruct the zone on startup from the member zone entries in /var/nsd/db/zone.list, specified with the zonelistfile option.
The status of both catalog consumer and producer zones can be verified with nsd-control zonestatus. It will show the number of member zones and, if the catalog zone is invalid, the reason for it to be invalid is shown. nsd-control zonestatus will also show the entry of a catalog member zone in the catalog (consumer or producer) zone as catalog-member-id:.
A catalog zone can either be catalog consumer zone or a catalog producer zone but not both. Likewise, catalog member zones can be either a member of catalog consumer zone or a catalog producer zone but not both.
Catalog zones contain a list of zones that are served. Use allow-query: 0.0.0.0/0 BLOCKED and allow-query: ::0/0 BLOCKED in a catalog zone zone or pattern clause to prevent revealing the catalog. Also consider using transfers over TLS to further protect the catalog against eavesdroppers.
The key: clause establishes a key for use in access control lists. It has the following attributes.
The tls-auth: clause establishes attributes to use when authenticating the far end of a TLS connection as well as to define credentials to authenticate to a remote server. It is used in access control lists for XFR-over-TLS. It has the following attributes.
DNSTAP support, when compiled in, is enabled in the dnstap: section. This starts a collector process that writes the log information to the destination.
BIND9 is a name server implementation with its own configuration file format, named.conf(5). BIND9 types zones as 'Primary' or 'Secondary'.
For a secondary zone, the primary servers are listed. The primary 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 primary 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 primaries and operators. BIND9 allows additional transfer sources, in NSD you list those as request-xfr.
Here is an example of a secondary 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 secondary;
file "secondary/example.org.signed";
primaries { 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 primary 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 primary is listed twice, once to allow it to send notifies to this secondary server and once to tell the secondary server where to look for updates zone data. More allow-notify and request-xfr lines can be added to specify more primaries.
It is possible to specify extra allow-notify lines for addresses that are also allowed to send notifications to this secondary server.
For a primary zone in BIND9, the secondary servers are listed. These secondary 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 primary zone in BIND9 syntax.
zone "example.nl" {
type primary;
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 secondary server you would in general give # provide-xfr: 1.2.3.4 tsig-key.name. # notify: 1.2.3.4 NOKEY
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.
nsd(8), nsd-checkconf(8), nsd-checkzone(8), nsd-control(8)
NSD was written by a combined team from NLnet Labs and RIPE NCC. Please see the CREDITS file in the distribution for further details.
nsd.conf is parsed by a primitive parser. Error messages may not be to the point.
| September 3, 2025 | NLnet Labs |