path: root/usr.sbin/nsd/nsd.conf.5.in

.TH "nsd.conf" "5" "Nov  1, 2012" "NLnet Labs" "nsd 3.2.14"
.\" Copyright (c) 2001\-2011, NLnet Labs. All rights reserved.
.\" See LICENSE for the license.
.SH "NAME"
.LP
.B nsd.conf
\- NSD configuration file
.SH "SYNOPSIS"
.LP
.B nsd.conf
.SH "DESCRIPTION"
.B 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. 
.PP
Comments start with # and last to the end of line. Empty lines are
ignored as is whitespace at the beginning of a line.
.PP
.B Nsd.conf
specifies options for the nsd server, zone files, primaries and 
secondaries.
.SH "EXAMPLE"
.LP
An example of a short nsd.conf file is below.
.LP
# Example.com nsd.conf file
.RS 0
# This is a comment.
.RE
.TP
server:
.RS 5
database: "@dbfile@"
.RE
.RS 5
username: @user@
.RE
.RS 5
logfile: "@logfile@"
.RE
.RS 5
pidfile: "@pidfile@"
.RE
.RS 5
difffile: "@difffile@"
.RE
.RS 5
xfrdfile: "@xfrdfile@"
.RE
.TP
zone:
.RS 5
name: example.com
.RE
.RS 5
# note that quotes are optional on the value
.RE
.RS 5
zonefile: @configdir@/example.com.zone 
.RE
.SH "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. 
.P
At the top level only 
.B server:
or
.B zone: 
or 
.B key: 
are allowed. These are followed by their attributes or the start of 
a new 
.B server:
or
.B zone: 
or 
.B key: 
clause. The 
.B zone:
attribute is followed by zone options. The 
.B server: 
attribute is followed by global options for the 
.B NSD 
server. A 
.B key: 
attribute is used to define keys for authentication.
.P
Files can be included using the 
.B 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.
.SS "Server Options"
.LP
The global options (if not overridden from the NSD commandline) are 
taken from the 
.B server: 
clause. There may only be one 
.B server: 
clause.
.TP
.B ip\-address:\fR <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 
.BR \-a.
.TP
.B debug\-mode:\fR <yes or no>
Turns on debugging mode for nsd, does not fork a daemon process. 
Default is no. Same as commandline option 
.BR \-d.
.TP
.B ip4\-only:\fR <yes or no>
If yes, NSD only listens to IPv4 connections. Same as commandline 
option 
.BR \-4.
.TP
.B ip6\-only:\fR <yes or no>
If yes, NSD only listens to IPv6 connections. Same as commandline 
option 
.BR \-6.
.TP
.B database:\fR <filename>
By default 
.I @dbfile@
is used. The specified file is used to store the compiled 
zone information. Same as commandline option 
.BR \-f.
.TP
.B identity:\fR <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 
.BR \-i .
.TP
.B nsid:\fR <string>
Add the specified nsid to the EDNS section of the answer when queried
with an NSID EDNS enabled packet. Same as commandline option
.BR \-I .
.TP
.B logfile:\fR <filename>
Log messages to the logfile. The default is to log to stderr and 
syslog (with facility LOG_DAEMON). Same as commandline option 
.BR \-l .
.TP
.B server\-count:\fR <number>
Start this many NSD servers. Default is 1. Same as commandline 
option 
.BR \-N .
.TP
.B tcp\-count:\fR <number>
The maximum number of concurrent, active TCP connections by each server. 
Default is 10. This option should have a value below 1000.
Same as commandline option 
.BR \-n .
.TP
.B tcp\-query\-count:\fR <number>
The maximum number of queries served on a single TCP connection.
Default is 0, meaning there is no maximum.
.TP
.B tcp\-timeout:\fR <number>
Overrides the default TCP timeout. This also affects zone transfers over TCP.
.TP
.B ipv4\-edns\-size:\fR <number>
Preferred EDNS buffer size for IPv4. 
.TP
.B ipv6\-edns\-size:\fR <number>
Preferred EDNS buffer size for IPv6. 
.TP
.B pidfile:\fR <filename>
Use the pid file instead of the platform specific default, usually 
.IR @pidfile@. 
Same as commandline option 
.BR \-P .
.TP
.B port:\fR <number>
Answer queries on the specified port. Default is 53. Same as 
commandline option 
.BR \-p .
.TP
.B statistics:\fR <number>
If not present no statistics are dumped. Statistics are produced 
every number seconds. Same as commandline option 
.BR \-s .
.TP
.B zone-stats-file:\fR <filename>
If per zone statistics is enabled, file to dump the statistics.
.TP
.B chroot:\fR <directory>
NSD will chroot on startup to the specified directory. Same as 
commandline option 
.BR \-t .
.TP
.B username:\fR <username>
After binding the socket, drop user privileges and assume the 
username. Can be username, id or id.gid. Same as commandline option 
.BR \-u .
.TP
.B zonesdir:\fR <directory>
Change the working directory to the specified directory before 
accessing zone files. Same as commandline option 
.B \-d 
for nsd\-zonec(8). Also nsd(8) will access files (pid file, database 
file, log file) relative to this directory. Set the value to "" 
(the empty string) to disable the change of working directory.
.TP
.B difffile:\fR <filename>
When NSD receives IXFR updates it will store them in this file. 
This file contains the differences between the database file and the 
latest zone version. Default is 
.IR @difffile@ .
.TP
.B xfrdfile:\fR <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
.IR @xfrdfile@ .
.TP
.B xfrd\-reload\-timeout:\fR <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 10 seconds.
.TP
.B verbosity:\fR <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.
.TP
.B hide\-version:\fR <yes or no>
Prevent NSD from replying with the version string on CHAOS class 
queries.
.SS "Zone Options"
.LP 
For every zone the options need to be specified in one 
.B zone: 
clause. The access control list elements can be given multiple 
times to add multiple servers. These elements need to be added
explicitly.
.TP
.B name:\fR <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.
.TP
.B zonefile:\fR <filename>
The file containing the zone information. This file is used by 
nsd\-zonec(8). This attribute must be present in each zone.
.TP
.B allow\-notify:\fR <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.
.P
.RS
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.
.RE
.TP
.B request\-xfr:\fR [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.
.P
.RS
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.
.P
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.
.RE
.TP
.B allow\-axfr\-fallback:\fR <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.
.TP
.B notify:\fR <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).
.TP
.B notify\-retry:\fR <number>
This option should be accompanied by notify. It sets the number of retries
when sending notifies.
.TP
.B provide\-xfr:\fR <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.
.P
.RS
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.
.RE
.TP
.B outgoing\-interface:\fR <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). 
.P
.RS
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.
.RE
.SS "Key Declarations"
The 
.B key: 
clause establishes a key for use in access control lists. It has 
the following attributes.
.TP
.B name:\fR <string>
The key name. Used to refer to this key in the access control list.
.TP
.B algorithm:\fR <string>
Authentication algorithm for this key.
.TP
.B secret:\fR <base64 blob>
The base64 encoded shared secret. It is possible to put the 
.B secret:
declaration (and base64 blob) into a different file, and then to
.B 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.
.SH "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'. 
.SS "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. 
.P
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.
.P
Here is an example of a slave zone in BIND9 syntax.
.P
# Config file for example.org
options {
.RS 5
dnssec\-enable yes;
.RE
.RS 0
};
.RE
.LP
key tsig.example.org. {
.RS 5
algorithm hmac\-md5;
.RE
.RS 5
secret "aaaaaabbbbbbccccccdddddd";
.RE
};
.LP
server 162.0.4.49 {
.RS 5
keys { tsig.example.org. ; };
.RE
};
.LP
zone "example.org" {
.RS 5
type slave;
.RE
.RS 5
file "secondary/example.org.signed";
.RE
.RS 5
masters { 162.0.4.49; };
.RE
};
.P
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.
.LP
# Config file for example.org
.RS 0
key:
.RE
.RS 5
name: tsig.example.org.
.RE
.RS 5
algorithm: hmac\-md5
.RE
.RS 5
secret: "aaaaaabbbbbbccccccdddddd"
.RE
.LP
zone:
.RS 5
name: "example.org"
.RE
.RS 5
zonefile: "secondary/example.org.signed"
.RE
.RS 5
# the master is allowed to notify and will provide zone data.
.RE
.RS 5
allow\-notify: 162.0.4.49 NOKEY 
.RE
.RS 5
request\-xfr: 162.0.4.49 tsig.example.org.
.RE
.P
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.
.P
It is possible to specify extra allow\-notify lines for addresses 
that are also allowed to send notifications to this slave server.
.SS "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.
.P
Here is an example of a master zone in BIND9 syntax.
.LP
zone "example.nl" {
.RS 5
type master;
.RE
.RS 5
file "example.nl";
.RE
};
.LP
In NSD syntax this becomes:
.LP
zone:
.RS 5
name: "example.nl"
.RE
.RS 5
zonefile: "example.nl"
.RE
.RS 5
# allow anybody to request xfr.
.RE
.RS 5
provide\-xfr: 0.0.0.0/0 NOKEY
.RE
.RS 5
provide\-xfr: ::0/0 NOKEY
.RE
.P
.RS 5
# to list a slave server you would in general give
.RE
.RS 5
# provide\-xfr: 1.2.3.4 tsig\-key.name.
.RE
.RS 5
# notify: 1.2.3.4 NOKEY
.RE
.SS "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.
.SH "FILES"
.TP
@dbfile@
default
.B NSD
database
.TP
@nsdconfigfile@
default
.B NSD
configuration file
.SH "SEE ALSO" 
.LP
nsd(8), nsdc(8), nsd\-checkconf(8), nsd-notify(8), 
nsd-patch(8), nsd-xfer(8), nsd\-zonec(8)
.SH "AUTHORS"
.LP
.B NSD
was written by NLnet Labs and RIPE NCC joint team. Please see 
CREDITS file in the distribution for further details.
.SH "BUGS"
.LP
.B nsd.conf
is parsed by a primitive parser, error messages may not be to the 
point.