nsd.conf

NSD configuration file format and options

Synopsis

nsd.conf

Description

This file is used to configure nsd(8). It specifies options for the NSD server, zone files, primaries and secondaries.

File Format

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, e.g., "file name.zone"
There must be whitespace between keywords
Attribute keywords end with a colon :

Example

A short example configuration:

# Example nsd.conf file for example.com
server:
    server-count: 1 # use this number of cpu cores
    username: nsd
    logfile: /var/log/nsd.log
    pidfile: /var/run/nsd.pid

zone:
    name: example.com
    zonefile: /etc/nsd/example.com.zone

zone:
    # this server is the primary and 192.0.2.1 is the secondary
    name: primaryzone.com
    zonefile: /etc/nsd/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: /etc/nsd/secondaryzone.com.zone
    allow-notify: 192.0.2.2 NOKEY
    request-xfr: 192.0.2.2 NOKEY

Top-Level Clauses

At the top level, only these clauses are allowed:

server: - Global server options
verify: - Zone verification options
key: - TSIG key definitions
pattern: - Zone option patterns
zone: - Zone configurations
tls-auth: - TLS authentication for XFR-over-TLS
remote-control: - Remote control options
include: - Include external files

Include Directive

Files can be included using the include: directive:

include: "/etc/nsd/zones.conf"
include: "/etc/nsd/keys/*.conf"

Wildcards are supported: *, ?, {}, [], and ~ (see glob(7)).

Server Options

The server: clause contains global server options. There may only be one server: clause.

ip-address

string

Bind to the specified IP address (IPv4, IPv6, or interface name). Can be given multiple times. Optionally include a port number with @port.

server:
    ip-address: 192.0.2.1
    ip-address: 2001:db8::1@5353
    ip-address: eth0

Additional options: servers, bindtodevice, setfib

interface

string

Same as ip-address (for compatibility with unbound.conf).

ip-transparent

boolean

default:"no"

Allows NSD to bind to non-local addresses. Useful to have NSD listen to IP addresses that are not yet added to the network interface.

ip-freebind

boolean

default:"no"

Set the IP_FREEBIND option to bind to nonlocal addresses and interfaces that are down. Similar to ip-transparent.

reuseport

boolean

default:"no"

Use the SO_REUSEPORT socket option. Improves performance when combined with server-count > 1. Works on Linux.

send-buffer-size

number

default:"4194304"

Set the send buffer size for query-servicing sockets in bytes. Set to 0 to use system defaults. Default is 4m.

receive-buffer-size

number

default:"1048576"

Set the receive buffer size for query-servicing sockets in bytes. Set to 0 to use system defaults. Default is 1m.

debug-mode

boolean

default:"no"

Do not fork a daemon process. Same as command-line option -d.

do-ip4

boolean

default:"yes"

Enable or disable IPv4 connections.

do-ip6

boolean

default:"yes"

Enable or disable IPv6 connections.

database

string

This option is ignored by NSD versions 4.8.0 and newer (database feature removed).

zonelistfile

string

File used to store the dynamically added list of zones. Used by nsd-control addzone and delzone commands.

identity

string

Returns the specified identity when asked for CH TXT ID.SERVER. Default is the name from gethostname(3). Same as -i.

version

string

Returns the specified version string when asked for CH TXT version.server or version.bind queries.

nsid

string

Add the specified NSID to the EDNS section of the answer when queried with NSID EDNS enabled. Hex string or ascii_ prefix. Same as -I.

logfile

string

Log messages to the specified file. Default is to log to stderr and syslog. Same as -l.

log-only-syslog

boolean

default:"no"

Log messages only to syslog. Useful with systemd to avoid duplicate log strings in journald.

server-count

number

default:"1"

Start this many NSD server processes. Same as -N.

cpu-affinity

number

Overall CPU affinity for NSD servers. Specify core numbers.

server:
    cpu-affinity: 0 1 2 3

server-N-cpu-affinity

number

Bind NSD server N to a specific core. Only takes effect if cpu-affinity is enabled.

xfrd-cpu-affinity

number

Bind xfrd process to a specific core. Only takes effect if cpu-affinity is enabled.

tcp-count

number

default:"100"

Maximum number of concurrent, active TCP connections per server. Same as -n.

tcp-reject-overflow

boolean

default:"no"

Drop TCP connections beyond tcp-count immediately (accept and close).

tcp-query-count

number

default:"0"

Maximum number of queries served on a single TCP connection. 0 means unlimited.

tcp-timeout

number

default:"120"

TCP timeout in seconds. Also affects zone transfers over TCP.

tcp-mss

number

Maximum segment size (MSS) of TCP socket. Values lower than common MSS (e.g., 1220) address path MTU problems.

outgoing-tcp-mss

number

Maximum segment size (MSS) of TCP socket for outgoing XFR requests.

tcp-listen-queue

number

default:"-1"

Set the TCP backlog for listening sockets. Default -1 selects the largest allowed value.

xfrd-tcp-max

number

default:"128"

Number of sockets for xfrd to use for outgoing zone transfers.

xfrd-tcp-pipeline

number

default:"128"

Number of simultaneous outgoing zone transfers possible on xfrd TCP sockets. Max 65536.

ipv4-edns-size

number

default:"1232"

Preferred EDNS buffer size for IPv4.

ipv6-edns-size

number

default:"1232"

Preferred EDNS buffer size for IPv6.

pidfile

string

Use the specified PID file. Use "" for no pidfile. Same as -P.

port

number

default:"53"

Answer queries on the specified port. Same as -p.

statistics

number

Produce statistics every N seconds. Same as -s.

chroot

string

Chroot on startup to the specified directory. Use "" to disable. Same as -t.

username

string

Drop privileges to this username after binding. Can be username, id, or id.gid. Same as -u.

zonesdir

string

Change working directory to this location before accessing zone files.

difffile

string

Ignored (for NSD3 compatibility).

xfrdfile

string

File to save zone transfer daemon state. Use "" to disable.

xfrdir

string

Directory where zone transfers are stored before processing.

xfrd-reload-timeout

number

default:"1"

Wait this many seconds before triggering reload after zone transfer. -1 disables automatic reload.

verbosity

number

default:"0"

Verbosity level for logging. Same as -V.

0: Warnings and errors
1: Notifies and zone transfers
2: Soft errors like connection resets

hide-version

boolean

default:"no"

Prevent NSD from replying with version string on CHAOS class queries.

hide-identity

boolean

default:"no"

Prevent NSD from replying with identity string on CHAOS class queries.

drop-updates

boolean

default:"no"

Drop received packets with the UPDATE opcode.

log-time-ascii

boolean

default:"yes"

Log time in ASCII format (not seconds since epoch).

log-time-iso

boolean

default:"no"

Log time in ISO8601 format (requires log-time-ascii: yes).

round-robin

boolean

default:"no"

Enable round-robin rotation of records in answers for load balancing.

minimal-responses

boolean

default:"no"

Enable minimal responses for smaller answer packets.

confine-to-zone

boolean

default:"no"

Don’t add additional information if the apex zone doesn’t match the initial query.

refuse-any

boolean

default:"no"

Refuse queries of type ANY. Useful to stop query floods.

reload-config

boolean

default:"no"

Reload configuration file on SIGHUP and update TSIG keys and zones.

zonefiles-check

boolean

default:"yes"

Check mtime of zone files on start and SIGHUP.

zonefiles-write

number

default:"3600"

Write updated secondary zones to disk every N seconds.

Rate Limiting Options

rrl-size

number

default:"1000000"

Size of the RRL hashtable in buckets. More buckets use more memory and reduce collisions.

rrl-ratelimit

number

default:"200"

Maximum queries per second allowed from one source. 0 disables rate limiting.

rrl-slip

number

default:"2"

Send a truncated response for 1 in N dropped responses. 0 disables SLIP responses.

rrl-ipv4-prefix-length

number

default:"24"

IPv4 prefix length for grouping addresses by netblock.

rrl-ipv6-prefix-length

number

default:"64"

IPv6 prefix length for grouping addresses by netblock.

rrl-whitelist-ratelimit

number

default:"2000"

Maximum QPS for whitelisted query types. 0 means unlimited.

DNS Cookies

Enable DNS Cookies (RFC 7873). Provides limited protection against DoS amplification attacks.

128-bit hex string for creating and verifying server cookies.

128-bit hex string for verifying (not creating) server cookies. For rolling secrets in anycast.

File from which cookie secrets are read. Manipulated with nsd-control commands.

TLS Options

tls-service-key

string

Private key file for TLS service. Enables DNS-over-TLS.

tls-service-pem

string

Public certificate PEM file for TLS service.

tls-service-ocsp

string

OCSP PEM file for TLS service OCSP stapling.

tls-port

number

default:"853"

Port number for DNS-over-TLS service.

tls-auth-port

number

Port number for authenticated TLS (mutual TLS for XFR-over-TLS).

tls-auth-xfr-only

boolean

Allow zone transfers only on tls-auth-port and only to authenticated clients.

tls-cert-bundle

string

Certificate bundle file for authenticating XFR-over-TLS connections.

Proxy Protocol

proxy-protocol-port

number

Port number for PROXYv2 protocol service. Can be specified multiple times.

XDP (Experimental)

xdp-interface

string

Interface to use XDP with. Enables AF_XDP sockets for UDP queries. (EXPERIMENTAL)

xdp-program-path

string

Path to eBPF XDP program.

xdp-program-load

boolean

default:"yes"

Whether NSD should load the XDP program.

xdp-bpffs-path

string

default:"/sys/fs/bpf"

Path to bpffs for storing/reading xsks_map pin.

xdp-force-copy

boolean

default:"no"

Force XDP_COPY mode instead of zero copy for AF_XDP sockets.

Metrics

metrics-enable

boolean

Enable Prometheus metrics HTTP endpoint. Requires libevent2.

metrics-interface

string

default:"127.0.0.1, ::1"

Bind to these addresses for serving metrics. Can be specified multiple times.

metrics-port

number

default:"9100"

Port number for HTTP metrics service.

metrics-path

string

default:"/metrics"

HTTP path to expose metrics.

Remote Control

The remote-control: clause configures nsd-control access.

control-enable

boolean

default:"no"

Enable remote control.

control-interface

string

default:"127.0.0.1, ::1"

Bind to these addresses for control requests. Can be IP address, interface name, or absolute path for Unix socket.

control-port

number

default:"8952"

Port number for remote control service.

server-key-file

string

Path to server private key for control connection.

server-cert-file

string

Path to server certificate for control connection.

control-key-file

string

Path to control client private key.

control-cert-file

string

Path to control client certificate.

Verifier Options

The verify: clause configures zone verification.

enable

boolean

default:"no"

Enable zone verification.

port

number

default:"5347"

Port for verifier queries.

ip-address

string

default:"127.0.0.1, ::1"

Interfaces to bind for zone verification.

verify-zones

boolean

Verify zones by default.

verifier

string

Command to execute for zone verification. The program should exit with status 0 if zone is valid.Environment variables available:

VERIFY_ZONE: Zone domain name
VERIFY_ZONE_ON_STDIN: “yes” or “no”
VERIFY_IP_ADDRESSES: First address for serving zones
VERIFY_PORT: Port number
VERIFY_IPV4_ADDRESS: First IPv4 address
VERIFY_IPV6_ADDRESS: First IPv6 address

verifier-count

number

default:"1"

Maximum number of concurrent verifiers.

verifier-feed-zone

boolean

Feed the updated zone to verifier via stdin.

verifier-timeout

number

default:"0"

Maximum seconds a verifier may run. 0 means unlimited.

Pattern Options

The pattern: clause defines reusable zone option sets.

name

string

required

Pattern name (case-sensitive).

include-pattern

string

Include options from another pattern (must be defined earlier).

Pattern can contain any zone option (see Zone Options below).

Zone Options

The zone: clause configures individual zones.

name

string

required

Zone name (apex domain). May end with . (FQDN notation).

zone:
    name: example.com

zonefile

string

File containing zone data. Can use substitution:

%s: Zone name
%1, %2, %3: First, second, third character of zone name
%z: Top-level domain
%y: Next label under TLD
%x: Next-next label under TLD

zone:
    zonefile: /var/zones/%s.zone
    zonefile: /var/zones/%1/%2/%s.zone

Access Control Lists

allow-query

acl

Allow queries from these addresses. Format: ip-spec key-name|NOKEY|BLOCKEDIP spec can be:

Plain IP: 192.0.2.1
Subnet: 192.0.2.0/24
Masked: 192.0.2.0&255.255.255.0
Range: 192.0.2.1-192.0.2.25

zone:
    allow-query: 192.0.2.0/24 NOKEY
    allow-query: 2001:db8::/32 mykey

allow-notify

acl

Allow NOTIFY from these primary addresses. Format: ip-spec key-name|NOKEY|BLOCKEDPort can be specified: 192.0.2.1@5300

request-xfr

acl

Request zone transfers from this primary. Format: [AXFR|UDP] ip-address key-name|NOKEY [tls-auth-name]

zone:
    request-xfr: 192.0.2.1 NOKEY
    request-xfr: AXFR 192.0.2.1@5300 mykey
    request-xfr: 192.0.2.1 mykey my-tls-auth

AXFR: Only use AXFR (no IXFR)
UDP: Use UDP for IXFR (requires TSIG)
tls-auth-name: Use XFR-over-TLS

allow-axfr-fallback

boolean

default:"yes"

Allow fallback to AXFR if primary doesn’t support IXFR.

size-limit-xfr

number

default:"0"

XFR temporary file size limit in bytes. 0 means unlimited.

notify

acl

Send NOTIFY to these secondary addresses. Format: ip-address key-name|NOKEY

zone:
    notify: 192.0.2.10 NOKEY
    notify: 192.0.2.11@5300 mykey

notify-retry

number

Number of retries when sending notifies.

provide-xfr

acl

Allow zone transfers to these secondaries. Format: ip-spec key-name|NOKEY|BLOCKED [tls-auth-name]

zone:
    provide-xfr: 192.0.2.0/24 NOKEY
    provide-xfr: 2001:db8::1 mykey my-tls-auth

outgoing-interface

string

Use this IP address for outgoing AXFR/IXFR requests and notifies.

zone:
    outgoing-interface: 192.0.2.100
    outgoing-interface: 192.0.2.100@5300

IXFR Options

store-ixfr

boolean

default:"no"

Store and provide IXFR contents to secondaries.

ixfr-number

number

default:"5"

Maximum number of IXFR versions to store.

ixfr-size

number

default:"1048576"

Maximum storage for IXFR versions in bytes. 0 means unlimited.

create-ixfr

boolean

default:"no"

Create IXFR data when zonefile is read. Requires store-ixfr: yes.

Timing Options

max-refresh-time

number

Limit refresh time for secondary zones (seconds).

min-refresh-time

number

Minimum refresh time for secondary zones (seconds).

max-retry-time

number

Maximum retry time for secondary zones (seconds).

min-retry-time

number

Minimum retry time for secondary zones (seconds).

min-expire-time

string

Minimum expire time. Can be seconds or “refresh+retry+1”.

Other Zone Options

zonestats

string

Statistics group name for this zone. Use %s for zone name.

include-pattern

string

Include options from the named pattern (must be defined earlier).

rrl-whitelist

string

Whitelist this RRL type for the zone. Types: nxdomain, error, referral, any, rrsig, wildcard, nodata, dnskey, positive, all.

zone:
    rrl-whitelist: nxdomain
    rrl-whitelist: positive

multi-primary-check

boolean

default:"no"

Check all primaries for the latest version.

verify-zone

boolean

Enable verification for this zone.

verifier

string

Command to execute for verifying this zone.

verifier-feed-zone

boolean

Feed updated zone to verifier via stdin.

verifier-timeout

number

Seconds before verifier is terminated. 0 means no timeout.

catalog

string

Set to consumer or producer for catalog zone processing.

catalog-member-pattern

string

Pattern to use for catalog member zones.

catalog-producer-zone

string

Catalog producer zone for this member zone.

Key Options

The key: clause defines TSIG keys.

name

string

required

Key name.

algorithm

string

HMAC algorithm (e.g., hmac-sha256, hmac-sha512).

secret

string

Base64-encoded secret.

key:
    name: "mykey"
    algorithm: hmac-sha256
    secret: "K2tf3TRjvQkVCmJF3/Z9vA=="

TLS Auth Options

The tls-auth: clause defines TLS authentication for XFR-over-TLS.

name

string

required

TLS auth configuration name.

auth-domain-name

string

Domain name for authentication (SAN or CN in certificate).

client-cert

string

Path to client certificate file.

client-key

string

Path to client private key file.

tls-auth:
    name: "my-tls-auth"
    auth-domain-name: "xfr.example.com"
    client-cert: "/etc/nsd/xfr-client.pem"
    client-key: "/etc/nsd/xfr-client.key"

Manual Pages

Zone Files

Technical Reference

nsd.conf

nsd.conf

Synopsis

Description

File Format

Example

Top-Level Clauses

Include Directive

Server Options

Rate Limiting Options

DNS Cookies

TLS Options

Proxy Protocol

XDP (Experimental)

Metrics

Remote Control

Verifier Options

Pattern Options

Zone Options

Access Control Lists

IXFR Options

Timing Options

Other Zone Options

Key Options

TLS Auth Options

See Also

Build docs developers (and LLMs) love

Manual Pages

Zone Files

Technical Reference

​nsd.conf

​Synopsis

​Description

​File Format

​Example

​Top-Level Clauses

​Include Directive

​Server Options

​Rate Limiting Options

​DNS Cookies

​TLS Options

​Proxy Protocol

​XDP (Experimental)

​Metrics

​Remote Control

​Verifier Options

​Pattern Options

​Zone Options

​Access Control Lists

​IXFR Options

​Timing Options

​Other Zone Options

​Key Options

​TLS Auth Options

​See Also

Build docs developers (and LLMs) love

nsd.conf

Synopsis

Description

File Format

Example

Top-Level Clauses

Include Directive

Server Options

Rate Limiting Options

DNS Cookies

TLS Options

Proxy Protocol

XDP (Experimental)

Metrics

Remote Control

Verifier Options

Pattern Options

Zone Options

Access Control Lists

IXFR Options

Timing Options

Other Zone Options

Key Options

TLS Auth Options

See Also