1.0 Introduction
1.1 ... Basic theory of operation
1.2 ... Quick build & install
2.0 Building nsd
2.1 ... Unpacking the source
2.2 ... Configuring NSD
2.3 ... Building
2.4 ... Installing
3.0 Running NSD
3.1 ... Logging
3.2 ... AXFR access
3.3 ... Using TSIG
3.4 ... Zone expiry of secondary zones
3.5 ... Diagnosing NSD log entries
3.6 ... Interfaces
4.0 Support and Feedback


1.0 Introduction

This is NSD Name Server Daemon (NSD) version 3.2.2.

The NLnet Labs Name Server Daemon (NSD) is an authoritative RFC compliant 
DNS nameserver. It was first conceived to allow for more genetic 
diversity for DNS server implementations used by the root-server system 
and it has been developed for operations in environments where speed, 
reliability, stability, and security are of high importance. NSD is 
currently used on root servers such as k.root-servers.net and is also in 
use by several top-level domain registries.

NSD is a complete implementation of an authoritative DNS name server.
For further information about what NSD is and what NSD is not please
consult the REQUIREMENTS document which is a part of this distribution.

If you are a BIND user (the named daemon) consult NSD_FOR_BIND_USERS.

The source code is available for download from:

         http://www.nlnetlabs.nl/downloads


1.1 Basic Theory of Operation

NSD consists of two programs: the zone compiler 'zonec' and the name
server 'nsd' itself. The name server works with an intermediate
database prepared by the zone compiler from standard zone files.

For NSD operation this means that zones have to be compiled by zonec
before NSD can use them.

All this can be controlled by a simple control script called 'nsdc'
and uses a simple configuration file 'nsd.conf'.


1.2 Quick build and install

Step 1: Unpack the source with gtar -xzvf nsd-3.2.2.tar.gz

Step 2: Create user nsd or any other unprivileged user of your
        choice. In case of later make sure to use
        --with-user=<username> while running configure.
	You can also set "username: <name>" in the nsd.conf file later.

Step 3: ./configure

Step 4: make all	(or simply 'make').

Step 5: make install

Step 6: Create and edit /etc/nsd/nsd.conf file possibly from
        nsd.conf.sample template that comes with the distribution.
	(installed by default at /etc/nsd/nsd.conf.sample)
	Here you need to configure the zones you want to serve.
	TSIG keys used for secure zone transfers must be included.
	Also server parameters can be set, see nsd.conf(5) man page.

	If you have a NSD 2 nsd.zones config file take a look at the
	python script contrib/nsd.zones2nsd.conf, it will convert 
	zone and TSIG key settings for you.

Step 7: Copy necessary master zone files into appropriate directories
        under /etc/nsd/primary & /etc/nsd/secondary. 

Step 8: Run nsdc rebuild

Step 9: Run nsdc start

Step 10: Test the NSD with dig, drill or host.

Step 11: If you're happy add nsdc start into your OS boot up sequence.
	 nsdc stop can be used in the shutdown sequence.

Step 12: If desired add nsdc patch to your superuser crontab to
         update the zone files with the content transferred from master
	 servers periodically, such as once per day.

         Got any problems or questions with the steps above? Read the
         rest of this file.



2.0 Building NSD


2.1 Unpacking the source

Use your favorite combination of tar and gnu zip to unpack the source,
for example

$ gtar -xzvf nsd-3.2.2.tar.gz

will unpack the source into the ./nsd-3.2.2 directory...


2.2 Configuring NSD

NSD can be configured using GNU autoconf's configure script. In
addition to standard configure options, one may use the following:

  CC=compiler
 
        Specify the C compiler.  The default is gcc or cc.  The
        compiler must support ANSI C89.

  CPPFLAGS=flags

        Specify the C preprocessor flags.  Such as -I<includedir>.

  CFLAGS=flags

        Specify the C compiler flags.  These include code generation,
        optimization, warning, and debugging flags.  These flags are
        also passed to the linker.

        The default for gcc is "-g -O2".

  LD=linker

        Specify the linker (defaults to the C compiler).

  LDFLAGS=flags

        Specify linker flags.

  LIBS=libs
 
        Specify additional libraries to link with.

  --enable-root-server

        Configure NSD as a root server. Unless this option is
        specified, NSD will refuse to serve the ``.'' zone as a
        misconfiguration safeguard.

  --disable-ipv6

        Disables IPv6 support in NSD.

  --enable-checking

        Enable some internal development checks.  Useful if you want
        to modify NSD.  This option enables the standard C "assert" macro
	and compiler warnings.

	This will instruct NSD to be stricter when validating its input. 
	This could lead to a reduced service level.

  --disable-dnssec

        Disable support for DNSSEC (RFC 4033, 4034, and 4035).

  --disable-tsig

        Disable TSIG support in NSD and the support tools.

  --enable-bind8-stats

        Enables BIND8-like statistics.

  --with-configdir=dir

        Specified, NSD configuration directory, default /etc/nsd

  --with-nsd_conf_file=path

	Pathname to the NSD configuration file, default /ect/nsd/nsd.conf

  --with-pidfile=path

        Pathname to the NSD pidfile, default is platform specific,
        mostly /var/run/nsd.pid

  --with-dbfile=path

        Pathname to the NSD database, default is /etc/nsd/nsd.db

  --with-zonesdir=dir

        NSD default location for master zone files, default /etc/nsd/

  --with-user=username

        User name or ID to answer the queries with, default is nsd

  --with-facility=facility

        Specify the syslog facility to use.  The default is
        LOG_DAEMON.  See the syslog(3) manual page for the available
        facilities.

  --with-ssl=path

        Specify the location of the OpenSSL libraries.  OpenSSL 0.9.7
        or higher is required for TSIG support.  Use --disable-tsig if
        you do not have OpenSSL installed.

  --with-start_priority=number

	Startup priority for NSD. 

  --with-kill_priority=number

	Shutdown priority for NSD. 

  --disable-nsec3

  	Disable NSEC3 support. With NSEC3 support enabled, very large zones,
	also non-nsec3 zones, use about 20% more memory.

  --enable-nsid

  	Enable (experimental) NSID support. 

  --disable-largefile

	Disable large file support (64 bit file lengths). Makes off_t
	a 32bit length during compilation.


2.3 Building

Use ``make'' to create NSD and support tools.  If you get errors, try to
use ``gmake'' (gnu version of make), especially on old systems. If so,
do a `gmake realclean` first, to remove stuff that the make call messed up.


2.4 Installing

Become a superuser (if necessary) and type ``make install''

This step should install seven binaries

nsd             - the daemon itself
nsdc            - a shell script to control the daemon
zonec           - zone compiler
nsd-notify      - a simple C program to send outbound notifies
nsd-xfer        - a program to receive zones from a master server
                  using AXFR from the command line.
nsd-checkconf	- simple C program to check nsd.conf before use.
nsd-patch	- simple program that cleans IXFR changes back to zone files.

Plus the manual pages and a sample configuration file.


3.0 Running NSD

Before running NSD you need to create a configuration file for it.
The config file contains server settings, secret keys and zone settings.

The server settings start with a line with the keyword 'server:'.
In the server settings set 'database: <file>' with the filename of the name 
database that NSD will use. Set 'chroot: <dir>' to run nsd in a chroot-jail.
Make sure the zone files, database file, xfrdfile, difffile and pidfile
can be accessed from the chroot-jail.  Set 'username: <user>' to an 
unprivileged user, for security.  

For example:
	# This is a sample configuration
	server:
		database: "/etc/nsd/nsd.db"
		pidfile: "/etc/nsd/nsd.pid"
		chroot: "/etc/nsd/"
		username: nsd

After the global server settings to need to make entries for the
zones that you wish to serve. For each zone you need to list the zone
name, the file name with the zone contents, and access control lists.

	zone:
		name:	"example.com"
		zonefile: "example.com.zone"

The zonefile needs to be filled with the correct zone information
for master zones. For secondary zones an empty file will suffice,
a zone transfer will be initiated to obtain the slave zone contents.

Access control lists are needed for zone transfer and notifications.

For a slave zone list the masters, by IP address. Below is an example
of a slave zone with two master servers. If a master only supports AXFR
transfers and not IXFR transfers (like NSD), specify the master as
"request-xfr: AXFR <ip_address> <key>". By default, all zone transfer requests 
are made over TCP. If you want the IXFR request be transmitted over UDP, use
"request-xfr: UDP <ip address> <key>".

	zone:
		name: "example.com"
		zonefile: "example.com.zone"
		allow-notify: 168.192.185.33 NOKEY
		request-xfr: 168.192.185.33 NOKEY
		allow-notify: 168.192.199.2 NOKEY
		request-xfr: 168.192.199.2 NOKEY

By default, a slave will fallback to AXFR requests if the master told us it does 
not support IXFR. You can configure the slave not to do AXFR fallback with:

		allow-axfr-fallback: "no"

For a master zone, list the slave servers, by IP address or subnet.
Below is an example of a master zone with two slave servers.

	zone:
		name: "example.com"
		zonefile: "example.com.zone"
		notify: 168.192.133.75 NOKEY
		provide-xfr: 168.192.133.75 NOKEY
		notify: 168.192.5.44 NOKEY
		provide-xfr: 168.192.5.44 NOKEY

You also can set the outgoing interface for notifies and zone transfer requests 
to satisfy access control lists at the other end:

		outgoing-interface: 168.192.5.69

Zone transfers can be secured with TSIG keys, replace NOKEY with
the name of the tsig key to use. See section 3.3.

Since NSD is written to be run on the root name servers, the config file 
can to contain something like:

	zone:
		name: "."
		zonefile: "root.zone"
		provide-xfr: 0.0.0.0/0 NOKEY # allow axfr for everyone.
		provide-xfr: ::0/0 NOKEY

You should only do that if you're intending to run a root server, NSD
is not suited for running a . cache. Therefore if you choose to serve
the .  zone you have to make sure that the complete root zone is
timely and fully updated.

To prevent misconfiguration, NSD configure has the --enable-root-server
switch, that is by default disabled.

When you are done with the configuration file, check the syntax using
	nsd-checkconf <name of configfile>

To build the name database, use nsdc. Use -c configfile if your config
file is not in the default location.

	nsdc rebuild

This starts zonec on your zone files. If zonec reports no errors, your
database is now ready for the daemon which can be started with

	nsdc start

To check if the daemon is running use

	nsdc running

To reload a new database after you recompiled it with 'nsdc rebuild'
without stopping the daemon issue

	nsdc reload

To restart the daemon (should never be necessary, unless you do some
development work)

	nsdc restart

To shut it down (for example on the system shutdown) do

	nsdc stop

NSD will automatically keep track of secondary zones and update them
when needed. When primary zones are updated and reloaded notifications
are sent to slave servers.

NSD keeps a journal file with the contents of the zone transfers
(difffile: "ixfr.db" setting in the configuration file). This file
will slowly grow as zone transfers are done. To clean up the journal
file issue a patch command

	nsdc patch

This will see if a transfer journal exists, and if so, move it away,
proceed with writing new contents to the zone files (listed as zonefile:
for the zones). If any zone have been changed the nsd database is rebuild
with the updates zone contents and NSD is issued a reload command.

The patch process will break a zone transfer in progress, which will be
reattempted later.  The patch process does this to avoid certain race
conditions, which could otherwise happen.

NSD will send notifications to slave zones if a master zone is updated.
NSD will check for updates at master servers periodically and transfer
the updated zone by AXFR/IXFR and reload the new zone contents. If you
wish exert manual control use the nsdc update and nsdc notify commands.
The update command will check for new versions of all secondary zones
hosted by this NSD. The notify command will send notifications to all
slave servers in 'notify:' statements.

the follow cron(8) command will take care of synchronizing the
database with zone updates received:

# nsd to patch every day
5       5       *       *       *       /usr/local/sbin/nsdc patch


3.1 Logging

NSD doesn't do any logging. We believe that logging is a separate task
and has to be done independently from the core operation.

This consciously is not part of nsd itself in order to keep nsd
focused and minimize its complexity. It is better to leave logging and
tracing to separate dedicated tools. dnsstat can also easily be
configured and/or modified to suit local statistics requirements
without any danger of affecting the name server itself. We have run
dnsstat on the same machine as nsd, we would recommend using a
multiprocessor if performance is an issue. Of course it can also run
on a separate machine that has MAC layer access to the network of the
server.

The CAIDA dnsstat tool referenced is recommended to nsd operators as a 
means of keeping statistics and check on abnormal query loads.

    http://www.caida.org/tools/utilities/dnsstat/dnsstat-3.5.1a.tar.gz

Another tool is the dnstop, that displays DNS statistics on your network.

    http://dns.measurement-factory.com/tools/dnstop/src/dnstop-20060517.tar.gz

A sample invocation of dnsstat:

/usr/local/Coral/bin/crl_dnsstat -D -Ci=60 -Cd=240 -C'filter dst 10.1.1.3'  -h -u if:fxp1

A sample output of a slightly modified version:

# dnsstat output version: 0.2 "dfk"

# begin trace interval at 1025267664.859043, duration 15.000000
# DNS messages: 74973 (4998.200000/s); DNS queries: 151983 (10132.200000/s)
# print threshold: 30 messages/sec

#src              op type  class queries    msgs      rd notes
 208.18.162.10     - -     -         533     533       0
 "                 0 MX    IN          6
 "                 0 A     IN        264
 "                 0 ANY   IN        263
 209.11.18.248     - -     -         661     661       0
 "                 0 A     IN        655
 "                 0 MX    IN          6
 210.117.65.137    - -     -         745     745       0
 "                 0 A     IN        745
 216.54.221.131    - -     -         477     477       0
 "                 0 A     IN        477
 193.97.205.80     - -     -         681     681       0
 "                 0 A     IN          3
 "                 0 ANY   IN        678
 168.30.240.11     - -     -         685     685       0
 "                 0 A     IN        405
 "                 0 MX    IN        280
 210.94.6.67       - -     -         742     742       0
 "                 0 A     IN        742
 63.66.68.237      - -     -        1375    1375       0
 "                 0 A     IN       1375
 168.30.240.12     - -     -         493     493       0
 "                 0 A     IN        493
 139.142.205.225   - -     -        5579    5579       0
 "                 0 A     IN       3006
 "                 0 MX    IN       2573
 210.117.65.2      - -     -         700     700       0
 "                 0 A     IN        700
# end trace interval 


3.2 AXFR access

The access list for AXFR should be set with provide-xfr:
in the nsd config file. This is per zone. See nsd.conf(5).
For example to grant zone 'example.com' AXFR right to localhost for
IPv4 and IPv6, use the below config options.

zone:
	name: "example.com"
	provide-xfr: 127.0.0.1 NOKEY
	provide-xfr: ::1 NOKEY

You can use dig @localhost example.com axfr to test this.


3.3 Using TSIG

NSD supports TSIG for any query to the server, for zone transfer
and for notify sending and receiving.

TSIG keys are based on shared secrets. These must be configured
in the config file. To keep the secret in a separate file use 
include: "filename" to include that file.

An example tsig key named sec1_key.

	key:
		name: "sec1_key"
		algorithm: hmac-md5
		secret: "6KM6qiKfwfEpamEq72HQdA=="

This key can then be used for any query to the NSD server. NSD
will check if the signature is valid, and if so, return a signed
answer. Unsigned queries will be given unsigned replies.

The key can be used to restrict the access control lists, for
example to only allow zone transfer with the key, by listing
the key name on the access control line.

	# provides AXFR to the subnet when TSIG is used.
	provide-xfr: 10.11.12.0/24 sec1_key
	# allow only notifications that are signed
	allow-notify: 192.168.0.0/16 sec1_key

If the TSIG key name is used in notify or request-xfr lines,
the key is used to sign the request/notification messages.

nsd-notify uses the -y keyname:secret format that dig uses too. For example
  nsd-notify -y sec1_key:6KM6qiKfwfEpamEq72HQdA== -z example.com 127.0.0.1

If you want to perform manual zone transfers you can use nsd-xfer.
nsd-xfer(8) uses the same cryptic file format as named-xfer(8) (to
be backward compatible).  This is a so called tsig-info file. 

Lets say we have following:

zone: nlnetlabs.nl
server: 213.53.69.1
key-name: nlnetlabs-axfr
algorithm: hmac-md5
secret: Y87923jksdXlsdv+LeXpUA==

Then we need to create file nlnetlabs.nl.tsiginfo containing:
213.53.69.1
nlnetlabs-axfr
157
Y87923jksdXlsdv+LeXpUA==

Cryptic? Yes. The first line tells this key is to be used for
213.53.69.1 Second one is the name of the key. 157 stands for hmac-md5
algorithm and the last line is the secret.

Here's a list of algorithms with their corresponding algorithm numbers.
hmac-md5:		157
hmac-sha1:		158
hmac-sha256:	159

3.4 Zone expiry of secondary zones

NSD will keep track of the status of secondary zones, according to the 
timing values in the SOA record for the zone.  When the refresh time of a
zone is reached, the serial number is checked and a zone transfer is
started if the zone has changed.  Each master server is tried in turn.

Master zones cannot expire.  They are always served.  Zones are master
zones if they have no 'request-xfr:' statements in the config file.

After the expire timeout (from the SOA record at the zone apex) is reached,
the zone becomes expired. NSD will return SERVFAIL for expired zones,
and will attempt to perform a zone transfer from any of the masters.
After a zone transfer succeeds, or if the master indicates that the SOA 
serial number is still the same, the zone will be OK again.

In contrast with e.g. BIND, the inception time for a slave zone is stored
on disk (in the xfrdfile: "xfrd.state"), together with timeouts.  If a
slave zone acquisition time is recent enough, this means that NSD can start
serving a zone immediately on loading, without querying the master server.

If your slave zone has expired, and no masters can be reached, but you 
still want NSD to serve the zone.  (i.e. ''My network is in shambles, but
serve the zone dangit!'').  You can delete the file 'xfrd.state',
but leave the zonefile for the zone intact.  Make sure to stop nsd before
you delete the file, as NSD writes it on exit.  Upon loading NSD will treat
the zonefile that you as operator have provided as recent and will serve
the zone.  Even though NSD will start to serve the zone immediately,
the zone will expire after the timeout is reached again.  NSD will also
attempt to confirm that you have provided the correct data by polling 
the masters.  So when the master servers come back up, it will transfer
the updated zone within <retry timeout from SOA> seconds.

In general it is possible to provide zone files for both master and slave
zones manually (say from email or rsync). Use nsdc rebuild to put the new
zonefile contents into the name database. Upon the next reload or start,
your zone will be served. For master zones, NSD will issue notifications
to all configured 'notify:' targets.  For slave zones the above happens;
NSD attempts to validate the zone from the master.

3.5 Diagnosing NSD log entries

NSD will print log messages to the system log (or 'logfile:' configuration
entry). Some of these messages are discussed below. These messages can
get extra support if errors happen.

- "Reload process <pid> failed with status <s>, continuing with old database"

This log message indicates the reload process of NSD has failed for
some reason.  The reason can be anything from a missing database file
to internal errors.  If this happens often, please let us know, this
error message can be caught in the code, and appropriate action could
be taken.  We are as of yet not sure what action is appropriate, if any.

- "snipping off trailing partial part of <ixfr.db>"

Please let us know if, and how often, this happens.

What happens is the file ixfr.db contains only part of expected data.
The corruption is removed by snipping off the trailing part.

- "memory recyclebin holds <num> bytes"

This is printed for every reload. NSD allocates and deallocates memory
to service IXFR updates. The recyclebin holds deallocated memory ready
for future use. If the number grows too large, nsdc patch will reset it.

- "xfrd: max number of tcp connections (10) reached."

This line is printed when more than 10 zones need a zone transfer at
the same time.  The value is a compile constant (xfrd-tcp.h), but if
this happens often for you, we could make this a config option.

If this happens, more zones have to wait until a zone transfer completes
(or is aborted) before they can have a zone transfer too.

- "error: <zone> NSEC3PARAM entry <num> has unknown hash algo <number>"

This error means that the zone has NSEC3 chain(s) with hash algorithms
that are not supported by this version of NSD, and thus cannot be served
by NSD.  If there are also no NSECs or NSEC3 chain(s) with known hash
algorithms, NSD will not be able to serve DNSSEC authenticated denials
for the zone.


3.6 Interfaces

NSD will by default bind itself to the system default interface and
service ip4 and if available also ip6. It is possible to service only ip4
or ip6 using the -4, -6 commandline options, or the ip4-only and ip6-only
config file options.

The commandline option -a and config file option ip-address can be given
to bind to specific interfaces.  Multiple interfaces can be specified.
This is useful for two reasons:
	o The specific interface bound will result in the OS bypassing
	  routing tables for the interface selection.  This results in
	  a small performance gain.  It is not the performance gain that
	  is the problem, sometimes the routing tables can give the
	  wrong answer, see the next point.
	o The answer will be routed via the interface the query came from.
	  This makes sure that the return address on the DNS replies is the
	  same as the query was sent to.  Many resolvers require the source
	  address of the replies to be correct.  The ip-address: option is
	  easier than configuring the OS routing table to return the DNS
	  replies via the correct interface.
The above means that even for systems with multiple interfaces where you
intend to provide DNS service to all interfaces, it is prudent to specify
all the interfaces as ip-address config file options.


4.0 Support and Feedback

NLnet Labs is committed to support NSD and its other software products on 
a best effort basis, free of charge. This form of community support is 
offered through a mailing lists and the 'bugzilla' web interface. 

	http://www.nlnetlabs.nl/bugs/

If for any reason NLnet Labs would stop community support of NSD such 
would be announced on our web pages at least two years in advance.

The community mailing list nsd-users@nlnetlabs.nl can be used to discuss 
issues with other users of NSD. Subscribe here

	http://open.nlnetlabs.nl/mailman/listinfo/nsd-users	

NLnet Labs recognizes that in some corporate environments this commitment to
community support is not sufficient and that support needs to be codified. 
We therefore offer paid support contracts that come in 3 varieties. 

More information about these support varieties can be found at 
	<url on support varieties on www.nlnetlabs.nl>

Alternatively you can contact mailto:nsd-support@nlnetlabs.nl .

Support goes two ways.  By acquiring one of the support contracts you
also support NLnet Labs to continue to participate in the development
of the Internet architecture. We do this through our participation in
the (IETF) standards process and by developing and maintaining
reference implementations of standards and tools to support operation
and deployment of new and existing Internet technology. 

We are interested in our users and in the environment you use NSD. Please 
drop us a mail when you use NSD. Indicate in what kind of operation you 
deploy NSD and let us know what your positive and negative experiences are.
http://www.nlnetlabs.nl/nsd  and  mailto:nsd-info@nlnetlabs.nl

$Id: README 2871 2009-05-11 10:48:15Z matje $