xref: /netbsd-src/external/bsd/nsd/dist/doc/README (revision 7330f729ccf0bd976a06f95fad452fe774fc7fd1)

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
4.1 ... Your Support


1.0 Introduction

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

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 via rc.d (SIGTERM, SIGHUP) or nsd-control,
and uses a simple configuration file 'nsd.conf'.


1.2 Quick build and install

Step 1: Unpack the source with gtar -xzvf nsd-4.1.27.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.
	Install openssl and libevent.

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 nsd-control start

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

Step 10: If you're happy add a rc.d script to start into your OS boot up
	 sequence. The format of the rc.d startup script depends on
	 the platform.  Also stop it in the shutdown sequence.
	 You can use SIGTERM to stop, or nsd-control stop.

Step 11: If desired add 'nsd-control write' 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-4.1.27.tar.gz

will unpack the source into the ./nsd-4.1.27 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.

  --enable-bind8-stats

        Enables BIND8-like statistics.

  --enable-ratelimit

	Enables ratelimiting, based on query name, type and source.

   --enable-draft-rrtypes

	Enables draft RRtypes.

  --with-configdir=dir

        Specified, NSD configuration directory, default /etc/nsd

  --with-nsd_conf_file=path

	Pathname to the NSD configuration file, default /etc/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-libevent=path

  	Specity the location of the libevent library (or libev).
	--with-libevent=no uses a builtin portable implementation (select()).

  --with-ssl=path

        Specify the location of the OpenSSL libraries.  OpenSSL 0.9.7
        or higher is required for TSIG support.

  --with-start_priority=number

	Startup priority for NSD.

  --with-kill_priority=number

	Shutdown priority for NSD.

  --with-tcp-timeout=number

	Set the default TCP timeout (in seconds). Default 120 seconds.

  --disable-nsec3

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

  --disable-minimal-responses

  	Disable minimal responses. If disabled, responses are more likely
	to get truncated, resulting in TCP fallback.  When enabled (by default)
	NSD will leave out RRsets to make responses fit inside one datagram,
	but for shorter responses the full normal response is carried.

  --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 four binaries

nsd               - the daemon itself
nsd-control-setup - a shell script that creates keys for nsd-control.
nsd-control	      - program that connects over SSL to nsd and gives commands.
nsd-checkconf	  - simple C program to check nsd.conf before use.

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

By default, NSD will retry a notify up to 5 times. You can override that
value with:

		notify-retry: 5

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.

In the config file, you can use patterns.  A pattern can have the
same configuration statements that a zone can have.  And then you can
include-pattern: <name-of-pattern> in a zone (or in another pattern)
to apply those settings.  This can be used to organise the settings.

The nsd-control tool is also controlled from the nsd.conf config file.
It uses SSL encrypted transport to 127.0.0.1, and if you want to use it
you have to setup the keys and also edit the config file.  You can leave
the remote-control disabled (the secure default), or opt to turn it on:

	# generate keys
	nsd-control-setup

	# edit nsd.conf to add this
	remote-control:
		control-enable: yes

By default nsd-control is limited to localhost, as well as encrypted, but
some people may want to remotely administer their nameserver.  What you
then do is setup nsd-control to listen to the public IP address, with
control-interface: <IP> after the control-enable statement.  Furthermore,
you copy the key files /etc/nsd/nsd_server.pem /etc/nsd/nsd_control.*
to a remote host on the internet; on that host you can run nsd-control
with -c <special config file> which references same IP address
control-interface and references the copies of the key files with
server-cert-file, control-key-file and control-cert-file config lines
after the control-enable statement.  The nsd-server authenticates the
nsd-control client, and also the nsd-control client authenticates the
nsd-server.

When you are done with the configuration file, check the syntax using

	nsd-checkconf <name of configfile>

The zone files are read by the daemon, which builds 'nsd.db' with their
contents.  You can start the daemon with

	nsd
	or with "nsd-control start" (which execs nsd again).
	or with nsd -c <name of configfile>

To check if the daemon is running look with ps, top, or if you enabled
nsd-control,

	nsd-control status

To reload changed zone files after you edited them, without stopping
the daemon, use this to check if files are modified:

	kill -HUP `cat <name of nsd pidfile>`

If you enabled nsd-control, you can reread with

	nsd-control reload

With nsd-control you can also reread the config file (new zones, ..)

	nsd-control reconfig

To restart the daemon

	/etc/rc.d/nsd restart  # or your system(d) equivalent

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

	kill -TERM <pid of nsd>
	or nsd-control 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.

The zone transfers are applied to nsd.db by the daemon.  To write changed
contents of the zone files for slave zones to disk in the text-based zone
file format, issue nsd-control write.

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 nsd-control notify, transfer and
force_transfer commands.  The transfer command will check for new versions
of the secondary zones hosted by this NSD. The notify command will send
notifications to the slave servers configured in 'notify:' statements.


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 nsd-control tool can output some statistics, with nsd-control stats
and nsd-control stats_noreset.  In contrib/nsd_munin_ there is a munin
grapher plugin that uses it.  The output of nsd-control stats is easy
to read (text only) with scripts.  The output values are documented on
the nsd-control man page.

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.


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). Reload with SIGHUP
or nsd-control reload to read the new zonefile contents into the name
database.  When this is done the new 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 (checking its SOA serial number).


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, a restart resets it.

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

This line is printed when more than 32 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.  NSD will reuse
existing TCP connections to the same master (determined by IP address)
to transfer up to 64k zones from that master.  Thus this error should
only happen with more than 32 masters or more than 64*32=2M zones that
need to be updated at the same time.

If this happens, more zones have to wait until a zone transfer completes
(or is aborted) before they can have a zone transfer too. This waiting
list has no size limit.

- "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.

With the config file option ip-transparent you can allow NSD to bind to
non local addresses.

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


4.1 Your Support

NLnet Labs offers all of its software products as open source, most are
published under a BSD license. You can download them, not only from the
NLnet Labs website but also through the various OS distributions for
which NSD, ldns, and Unbound are packaged. We therefore have little idea
who uses our software in production environments and have no direct ties
with 'our customers'.

Therefore, we ask you to contact us at users@NLnetLabs.nl and tell us
whether you use one of our products in your production environment,
what that environment looks like, and maybe even share some praise.
We would like to refer to the fact that your organization is using our
products. We will only do that if you explicitly allow us. In all other
cases we will keep the information you share with us to ourselves.

In addition to the moral support you can also support us
financially. NLnet Labs is a recognized not-for-profit charity foundation
that is chartered to develop open-source software and open-standards
for the Internet. If you use our software to satisfaction please express
that by giving us a donation. For small donations PayPal can be used. For
larger and regular donations please contact us at users@NLnetLabs.nl. Also
see http://www.nlnetlabs.nl/labs/contributors/.


$Id: README,v 1.1.1.5 2019/05/25 19:44:44 christos Exp $