"Fossies" - the Fresh Open Source Software Archive

Member "nsd-4.3.6/doc/README" (6 Apr 2021, 30699 Bytes) of package /linux/misc/dns/nsd-4.3.6.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 4.3.5_vs_4.3.6.

    1 1.0 Introduction
    2 1.1 ... Basic theory of operation
    3 1.2 ... Quick build & install
    4 2.0 Building nsd
    5 2.1 ... Unpacking the source
    6 2.2 ... Configuring NSD
    7 2.3 ... Building
    8 2.4 ... Installing
    9 3.0 Running NSD
   10 3.1 ... Logging
   11 3.2 ... AXFR access
   12 3.3 ... Using TSIG
   13 3.4 ... Zone expiry of secondary zones
   14 3.5 ... Diagnosing NSD log entries
   15 3.6 ... Interfaces
   16 3.7 ... Tuning
   17 4.0 Support and Feedback
   18 4.1 ... Your Support
   19 
   20 
   21 1.0 Introduction
   22 
   23 This is NSD Name Server Daemon (NSD) version 4.3.6.
   24 
   25 The NLnet Labs Name Server Daemon (NSD) is an authoritative RFC compliant 
   26 DNS nameserver. It was first conceived to allow for more genetic 
   27 diversity for DNS server implementations used by the root-server system 
   28 and it has been developed for operations in environments where speed, 
   29 reliability, stability, and security are of high importance. NSD is 
   30 currently used on root servers such as k.root-servers.net and is also in 
   31 use by several top-level domain registries.
   32 
   33 NSD is a complete implementation of an authoritative DNS name server.
   34 For further information about what NSD is and what NSD is not please
   35 consult the REQUIREMENTS document which is a part of this distribution.
   36 
   37 If you are a BIND user (the named daemon) consult NSD_FOR_BIND_USERS.
   38 
   39 The source code is available for download from:
   40 
   41          http://www.nlnetlabs.nl/downloads
   42 
   43 
   44 1.1 Basic Theory of Operation
   45 
   46 NSD consists of two programs: the zone compiler 'zonec' and the name
   47 server 'nsd' itself. The name server works with an intermediate
   48 database prepared by the zone compiler from standard zone files.
   49 
   50 For NSD operation this means that zones have to be compiled by zonec
   51 before NSD can use them.
   52 
   53 All this can be controlled via rc.d (SIGTERM, SIGHUP) or nsd-control,
   54 and uses a simple configuration file 'nsd.conf'.
   55 
   56 
   57 1.2 Quick build and install
   58 
   59 Step 1: Unpack the source with gtar -xzvf nsd-4.3.6.tar.gz
   60 
   61 Step 2: Create user nsd or any other unprivileged user of your
   62         choice. In case of later make sure to use
   63         --with-user=<username> while running configure.
   64 	You can also set "username: <name>" in the nsd.conf file later.
   65 	Install openssl and libevent.
   66 
   67 Step 3: ./configure
   68 
   69 Step 4: make all	(or simply 'make').
   70 
   71 Step 5: make install
   72 
   73 Step 6: Create and edit /etc/nsd/nsd.conf file possibly from
   74         nsd.conf.sample template that comes with the distribution.
   75 	(installed by default at /etc/nsd/nsd.conf.sample)
   76 	Here you need to configure the zones you want to serve.
   77 	TSIG keys used for secure zone transfers must be included.
   78 	Also server parameters can be set, see nsd.conf(5) man page.
   79 
   80 	If you have a NSD 2 nsd.zones config file take a look at the
   81 	python script contrib/nsd.zones2nsd.conf, it will convert 
   82 	zone and TSIG key settings for you.
   83 
   84 Step 7: Copy necessary master zone files into appropriate directories
   85         under /etc/nsd/primary & /etc/nsd/secondary. 
   86 
   87 Step 8: Run nsd-control start
   88 
   89 Step 9: Test the NSD with dig, drill or host.
   90 
   91 Step 10: If you're happy add a rc.d script to start into your OS boot up
   92 	 sequence. The format of the rc.d startup script depends on 
   93 	 the platform.  Also stop it in the shutdown sequence.
   94 	 You can use SIGTERM to stop, or nsd-control stop.
   95 
   96 Step 11: If desired add 'nsd-control write' to your superuser crontab to
   97          update the zone files with the content transferred from master
   98 	 servers periodically, such as once per day.
   99 
  100          Got any problems or questions with the steps above? Read the
  101          rest of this file.
  102 
  103 
  104 
  105 2.0 Building NSD
  106 
  107 
  108 2.1 Unpacking the source
  109 
  110 Use your favorite combination of tar and gnu zip to unpack the source,
  111 for example
  112 
  113 $ gtar -xzvf nsd-4.3.6.tar.gz
  114 
  115 will unpack the source into the ./nsd-4.3.6 directory...
  116 
  117 
  118 2.2 Configuring NSD
  119 
  120 NSD can be configured using GNU autoconf's configure script. In
  121 addition to standard configure options, one may use the following:
  122 
  123   CC=compiler
  124  
  125         Specify the C compiler.  The default is gcc or cc.  The
  126         compiler must support ANSI C89.
  127 
  128   CPPFLAGS=flags
  129 
  130         Specify the C preprocessor flags.  Such as -I<includedir>.
  131 
  132   CFLAGS=flags
  133 
  134         Specify the C compiler flags.  These include code generation,
  135         optimization, warning, and debugging flags.  These flags are
  136         also passed to the linker.
  137 
  138         The default for gcc is "-g -O2".
  139 
  140   LD=linker
  141 
  142         Specify the linker (defaults to the C compiler).
  143 
  144   LDFLAGS=flags
  145 
  146         Specify linker flags.
  147 
  148   LIBS=libs
  149  
  150         Specify additional libraries to link with.
  151 
  152   --enable-root-server
  153 
  154         Configure NSD as a root server. Unless this option is
  155         specified, NSD will refuse to serve the ``.'' zone as a
  156         misconfiguration safeguard.
  157 
  158   --disable-ipv6
  159 
  160         Disables IPv6 support in NSD.
  161 
  162   --enable-checking
  163 
  164         Enable some internal development checks.  Useful if you want
  165         to modify NSD.  This option enables the standard C "assert" macro
  166 	and compiler warnings.
  167 
  168 	This will instruct NSD to be stricter when validating its input. 
  169 	This could lead to a reduced service level.
  170 
  171   --enable-bind8-stats
  172 
  173         Enables BIND8-like statistics.
  174 
  175   --enable-ratelimit
  176 
  177 	Enables ratelimiting, based on query name, type and source.
  178 
  179    --enable-draft-rrtypes
  180 
  181 	Enables draft RRtypes.
  182 
  183   --with-configdir=dir
  184 
  185         Specified, NSD configuration directory, default /etc/nsd
  186 
  187   --with-nsd_conf_file=path
  188 
  189 	Pathname to the NSD configuration file, default /etc/nsd/nsd.conf
  190 
  191   --with-pidfile=path
  192 
  193         Pathname to the NSD pidfile, default is platform specific,
  194         mostly /var/run/nsd.pid
  195 
  196   --with-dbfile=path
  197 
  198         Pathname to the NSD database, default is /etc/nsd/nsd.db
  199 
  200   --with-zonesdir=dir
  201 
  202         NSD default location for master zone files, default /etc/nsd/
  203 
  204   --with-user=username
  205 
  206         User name or ID to answer the queries with, default is nsd
  207 
  208   --with-facility=facility
  209 
  210         Specify the syslog facility to use.  The default is
  211         LOG_DAEMON.  See the syslog(3) manual page for the available
  212         facilities.
  213 
  214   --with-libevent=path
  215 
  216   	Specity the location of the libevent library (or libev).
  217 	--with-libevent=no uses a builtin portable implementation (select()).
  218 
  219   --with-ssl=path
  220 
  221         Specify the location of the OpenSSL libraries.  OpenSSL 0.9.7
  222         or higher is required for TSIG support.
  223 
  224   --with-start_priority=number
  225 
  226 	Startup priority for NSD. 
  227 
  228   --with-kill_priority=number
  229 
  230 	Shutdown priority for NSD. 
  231 
  232   --with-tcp-timeout=number
  233 
  234 	Set the default TCP timeout (in seconds). Default 120 seconds.
  235 
  236   --disable-nsec3
  237 
  238   	Disable NSEC3 support. With NSEC3 support enabled, very large zones,
  239 	also non-nsec3 zones, use about 20% more memory.
  240 
  241   --disable-minimal-responses
  242 
  243   	Disable minimal responses. If disabled, responses are more likely
  244 	to get truncated, resulting in TCP fallback.  When enabled (by default)
  245 	NSD will leave out RRsets to make responses fit inside one datagram,
  246 	but for shorter responses the full normal response is carried.
  247 
  248   --disable-largefile
  249 
  250 	Disable large file support (64 bit file lengths). Makes off_t
  251 	a 32bit length during compilation.
  252 
  253 
  254 2.3 Building
  255 
  256 Use ``make'' to create NSD and support tools.  If you get errors, try to
  257 use ``gmake'' (gnu version of make), especially on old systems. If so,
  258 do a `gmake realclean` first, to remove stuff that the make call messed up.
  259 
  260 
  261 2.4 Installing
  262 
  263 Become a superuser (if necessary) and type ``make install''
  264 
  265 This step should install four binaries
  266 
  267 nsd               - the daemon itself
  268 nsd-control-setup - a shell script that creates keys for nsd-control.
  269 nsd-control	      - program that connects over SSL to nsd and gives commands.
  270 nsd-checkconf	  - simple C program to check nsd.conf before use.
  271 
  272 Plus the manual pages and a sample configuration file.
  273 
  274 
  275 3.0 Running NSD
  276 
  277 Before running NSD you need to create a configuration file for it.
  278 The config file contains server settings, secret keys and zone settings.
  279 
  280 The server settings start with a line with the keyword 'server:'.
  281 In the server settings set 'database: <file>' with the filename of the name 
  282 database that NSD will use. Set 'chroot: <dir>' to run nsd in a chroot-jail.
  283 Make sure the zone files, database file, xfrdfile, difffile and pidfile
  284 can be accessed from the chroot-jail.  Set 'username: <user>' to an 
  285 unprivileged user, for security.  
  286 
  287 For example:
  288 	# This is a sample configuration
  289 	server:
  290 		database: "/etc/nsd/nsd.db"
  291 		pidfile: "/etc/nsd/nsd.pid"
  292 		chroot: "/etc/nsd/"
  293 		username: nsd
  294 
  295 After the global server settings to need to make entries for the
  296 zones that you wish to serve. For each zone you need to list the zone
  297 name, the file name with the zone contents, and access control lists.
  298 
  299 	zone:
  300 		name:	"example.com"
  301 		zonefile: "example.com.zone"
  302 
  303 The zonefile needs to be filled with the correct zone information
  304 for master zones. For secondary zones an empty file will suffice,
  305 a zone transfer will be initiated to obtain the slave zone contents.
  306 
  307 Access control lists are needed for zone transfer and notifications.
  308 
  309 For a slave zone list the masters, by IP address. Below is an example
  310 of a slave zone with two master servers. If a master only supports AXFR
  311 transfers and not IXFR transfers (like NSD), specify the master as
  312 "request-xfr: AXFR <ip_address> <key>". By default, all zone transfer requests 
  313 are made over TCP. If you want the IXFR request be transmitted over UDP, use
  314 "request-xfr: UDP <ip address> <key>".
  315 
  316 	zone:
  317 		name: "example.com"
  318 		zonefile: "example.com.zone"
  319 		allow-notify: 168.192.185.33 NOKEY
  320 		request-xfr: 168.192.185.33 NOKEY
  321 		allow-notify: 168.192.199.2 NOKEY
  322 		request-xfr: 168.192.199.2 NOKEY
  323 
  324 By default, a slave will fallback to AXFR requests if the master told us it does 
  325 not support IXFR. You can configure the slave not to do AXFR fallback with:
  326 
  327 		allow-axfr-fallback: "no"
  328 
  329 For a master zone, list the slave servers, by IP address or subnet.
  330 Below is an example of a master zone with two slave servers.
  331 
  332 	zone:
  333 		name: "example.com"
  334 		zonefile: "example.com.zone"
  335 		notify: 168.192.133.75 NOKEY
  336 		provide-xfr: 168.192.133.75 NOKEY
  337 		notify: 168.192.5.44 NOKEY
  338 		provide-xfr: 168.192.5.44 NOKEY
  339 
  340 You also can set the outgoing interface for notifies and zone transfer requests 
  341 to satisfy access control lists at the other end:
  342 
  343 		outgoing-interface: 168.192.5.69
  344 
  345 By default, NSD will retry a notify up to 5 times. You can override that
  346 value with: 
  347 
  348 		notify-retry: 5
  349 
  350 Zone transfers can be secured with TSIG keys, replace NOKEY with
  351 the name of the tsig key to use. See section 3.3.
  352 
  353 Since NSD is written to be run on the root name servers, the config file 
  354 can to contain something like:
  355 
  356 	zone:
  357 		name: "."
  358 		zonefile: "root.zone"
  359 		provide-xfr: 0.0.0.0/0 NOKEY # allow axfr for everyone.
  360 		provide-xfr: ::0/0 NOKEY
  361 
  362 You should only do that if you're intending to run a root server, NSD
  363 is not suited for running a . cache. Therefore if you choose to serve
  364 the .  zone you have to make sure that the complete root zone is
  365 timely and fully updated.
  366 
  367 To prevent misconfiguration, NSD configure has the --enable-root-server
  368 switch, that is by default disabled.
  369 
  370 In the config file, you can use patterns.  A pattern can have the
  371 same configuration statements that a zone can have.  And then you can
  372 include-pattern: <name-of-pattern> in a zone (or in another pattern)
  373 to apply those settings.  This can be used to organise the settings.
  374 
  375 The nsd-control tool is also controlled from the nsd.conf config file.
  376 It uses SSL encrypted transport to 127.0.0.1, and if you want to use it
  377 you have to setup the keys and also edit the config file.  You can leave
  378 the remote-control disabled (the secure default), or opt to turn it on:
  379 
  380 	# generate keys
  381 	nsd-control-setup
  382 
  383 	# edit nsd.conf to add this
  384 	remote-control:
  385 		control-enable: yes
  386 
  387 By default nsd-control is limited to localhost, as well as encrypted, but
  388 some people may want to remotely administer their nameserver.  What you
  389 then do is setup nsd-control to listen to the public IP address, with
  390 control-interface: <IP> after the control-enable statement.  Furthermore,
  391 you copy the key files /etc/nsd/nsd_server.pem /etc/nsd/nsd_control.*
  392 to a remote host on the internet; on that host you can run nsd-control
  393 with -c <special config file> which references same IP address
  394 control-interface and references the copies of the key files with
  395 server-cert-file, control-key-file and control-cert-file config lines
  396 after the control-enable statement.  The nsd-server authenticates the
  397 nsd-control client, and also the nsd-control client authenticates the
  398 nsd-server.
  399 
  400 When you are done with the configuration file, check the syntax using
  401 
  402 	nsd-checkconf <name of configfile>
  403 
  404 The zone files are read by the daemon, which builds 'nsd.db' with their
  405 contents.  You can start the daemon with
  406 
  407 	nsd
  408 	or with "nsd-control start" (which execs nsd again).
  409 	or with nsd -c <name of configfile>
  410 
  411 To check if the daemon is running look with ps, top, or if you enabled
  412 nsd-control,
  413 
  414 	nsd-control status
  415 
  416 To reload changed zone files after you edited them, without stopping
  417 the daemon, use this to check if files are modified: 
  418 
  419 	kill -HUP `cat <name of nsd pidfile>`
  420 
  421 If you enabled nsd-control, you can reread with
  422 
  423 	nsd-control reload
  424 
  425 With nsd-control you can also reread the config file (new zones, ..)
  426 
  427 	nsd-control reconfig
  428 
  429 To restart the daemon
  430 
  431 	/etc/rc.d/nsd restart  # or your system(d) equivalent
  432 
  433 To shut it down (for example on the system shutdown) do
  434 
  435 	kill -TERM <pid of nsd>
  436 	or nsd-control stop
  437 
  438 NSD will automatically keep track of secondary zones and update them
  439 when needed. When primary zones are updated and reloaded notifications
  440 are sent to slave servers.
  441 
  442 The zone transfers are applied to nsd.db by the daemon.  To write changed
  443 contents of the zone files for slave zones to disk in the text-based zone
  444 file format, issue nsd-control write.
  445 
  446 NSD will send notifications to slave zones if a master zone is updated.
  447 NSD will check for updates at master servers periodically and transfer
  448 the updated zone by AXFR/IXFR and reload the new zone contents. If
  449 you wish exert manual control use nsd-control notify, transfer and
  450 force_transfer commands.  The transfer command will check for new versions
  451 of the secondary zones hosted by this NSD. The notify command will send
  452 notifications to the slave servers configured in 'notify:' statements.
  453 
  454 
  455 3.1 Logging
  456 
  457 NSD doesn't do any logging. We believe that logging is a separate task
  458 and has to be done independently from the core operation.
  459 
  460 This consciously is not part of nsd itself in order to keep nsd
  461 focused and minimize its complexity. It is better to leave logging and
  462 tracing to separate dedicated tools. dnsstat can also easily be
  463 configured and/or modified to suit local statistics requirements
  464 without any danger of affecting the name server itself. We have run
  465 dnsstat on the same machine as nsd, we would recommend using a
  466 multiprocessor if performance is an issue. Of course it can also run
  467 on a separate machine that has MAC layer access to the network of the
  468 server.
  469 
  470 The nsd-control tool can output some statistics, with nsd-control stats
  471 and nsd-control stats_noreset.  In contrib/nsd_munin_ there is a munin
  472 grapher plugin that uses it.  The output of nsd-control stats is easy
  473 to read (text only) with scripts.  The output values are documented on
  474 the nsd-control man page.
  475 
  476 The CAIDA dnsstat tool referenced is recommended to nsd operators as a 
  477 means of keeping statistics and check on abnormal query loads.
  478 
  479     http://www.caida.org/tools/utilities/dnsstat/dnsstat-3.5.1a.tar.gz
  480 
  481 Another tool is the dnstop, that displays DNS statistics on your network.
  482 
  483     http://dns.measurement-factory.com/tools/dnstop/src/dnstop-20060517.tar.gz
  484 
  485 A sample invocation of dnsstat:
  486 
  487 /usr/local/Coral/bin/crl_dnsstat -D -Ci=60 -Cd=240 -C'filter dst 10.1.1.3'  -h -u if:fxp1
  488 
  489 A sample output of a slightly modified version:
  490 
  491 # dnsstat output version: 0.2 "dfk"
  492 
  493 # begin trace interval at 1025267664.859043, duration 15.000000
  494 # DNS messages: 74973 (4998.200000/s); DNS queries: 151983 (10132.200000/s)
  495 # print threshold: 30 messages/sec
  496 
  497 #src              op type  class queries    msgs      rd notes
  498  208.18.162.10     - -     -         533     533       0
  499  "                 0 MX    IN          6
  500  "                 0 A     IN        264
  501  "                 0 ANY   IN        263
  502  209.11.18.248     - -     -         661     661       0
  503  "                 0 A     IN        655
  504  "                 0 MX    IN          6
  505  210.117.65.137    - -     -         745     745       0
  506  "                 0 A     IN        745
  507  216.54.221.131    - -     -         477     477       0
  508  "                 0 A     IN        477
  509  193.97.205.80     - -     -         681     681       0
  510  "                 0 A     IN          3
  511  "                 0 ANY   IN        678
  512  168.30.240.11     - -     -         685     685       0
  513  "                 0 A     IN        405
  514  "                 0 MX    IN        280
  515  210.94.6.67       - -     -         742     742       0
  516  "                 0 A     IN        742
  517  63.66.68.237      - -     -        1375    1375       0
  518  "                 0 A     IN       1375
  519  168.30.240.12     - -     -         493     493       0
  520  "                 0 A     IN        493
  521  139.142.205.225   - -     -        5579    5579       0
  522  "                 0 A     IN       3006
  523  "                 0 MX    IN       2573
  524  210.117.65.2      - -     -         700     700       0
  525  "                 0 A     IN        700
  526 # end trace interval 
  527 
  528 
  529 3.2 AXFR access
  530 
  531 The access list for AXFR should be set with provide-xfr:
  532 in the nsd config file. This is per zone. See nsd.conf(5).
  533 For example to grant zone 'example.com' AXFR right to localhost for
  534 IPv4 and IPv6, use the below config options.
  535 
  536 zone:
  537 	name: "example.com"
  538 	provide-xfr: 127.0.0.1 NOKEY
  539 	provide-xfr: ::1 NOKEY
  540 
  541 You can use dig @localhost example.com axfr to test this.
  542 
  543 
  544 3.3 Using TSIG
  545 
  546 NSD supports TSIG for any query to the server, for zone transfer
  547 and for notify sending and receiving.
  548 
  549 TSIG keys are based on shared secrets. These must be configured
  550 in the config file. To keep the secret in a separate file use 
  551 include: "filename" to include that file.
  552 
  553 An example tsig key named sec1_key.
  554 
  555 	key:
  556 		name: "sec1_key"
  557 		algorithm: hmac-md5
  558 		secret: "6KM6qiKfwfEpamEq72HQdA=="
  559 
  560 This key can then be used for any query to the NSD server. NSD
  561 will check if the signature is valid, and if so, return a signed
  562 answer. Unsigned queries will be given unsigned replies.
  563 
  564 The key can be used to restrict the access control lists, for
  565 example to only allow zone transfer with the key, by listing
  566 the key name on the access control line.
  567 
  568 	# provides AXFR to the subnet when TSIG is used.
  569 	provide-xfr: 10.11.12.0/24 sec1_key
  570 	# allow only notifications that are signed
  571 	allow-notify: 192.168.0.0/16 sec1_key
  572 
  573 If the TSIG key name is used in notify or request-xfr lines,
  574 the key is used to sign the request/notification messages.
  575 
  576 
  577 3.4 Zone expiry of secondary zones
  578 
  579 NSD will keep track of the status of secondary zones, according to the 
  580 timing values in the SOA record for the zone.  When the refresh time of a
  581 zone is reached, the serial number is checked and a zone transfer is
  582 started if the zone has changed.  Each master server is tried in turn.
  583 
  584 Master zones cannot expire.  They are always served.  Zones are master
  585 zones if they have no 'request-xfr:' statements in the config file.
  586 
  587 After the expire timeout (from the SOA record at the zone apex) is reached,
  588 the zone becomes expired. NSD will return SERVFAIL for expired zones,
  589 and will attempt to perform a zone transfer from any of the masters.
  590 After a zone transfer succeeds, or if the master indicates that the SOA 
  591 serial number is still the same, the zone will be OK again.
  592 
  593 In contrast with e.g. BIND, the inception time for a slave zone is stored
  594 on disk (in the xfrdfile: "xfrd.state"), together with timeouts.  If a
  595 slave zone acquisition time is recent enough, this means that NSD can start
  596 serving a zone immediately on loading, without querying the master server.
  597 
  598 If your slave zone has expired, and no masters can be reached, but you 
  599 still want NSD to serve the zone.  (i.e. ''My network is in shambles, but
  600 serve the zone dangit!'').  You can delete the file 'xfrd.state',
  601 but leave the zonefile for the zone intact.  Make sure to stop nsd before
  602 you delete the file, as NSD writes it on exit.  Upon loading NSD will treat
  603 the zonefile that you as operator have provided as recent and will serve
  604 the zone.  Even though NSD will start to serve the zone immediately,
  605 the zone will expire after the timeout is reached again.  NSD will also
  606 attempt to confirm that you have provided the correct data by polling 
  607 the masters.  So when the master servers come back up, it will transfer
  608 the updated zone within <retry timeout from SOA> seconds.
  609 
  610 In general it is possible to provide zone files for both master and
  611 slave zones manually (say from email or rsync). Reload with SIGHUP
  612 or nsd-control reload to read the new zonefile contents into the name
  613 database.  When this is done the new zone will be served. For master
  614 zones, NSD will issue notifications to all configured 'notify:' targets.
  615 For slave zones the above happens; NSD attempts to validate the zone
  616 from the master (checking its SOA serial number).
  617 
  618 
  619 3.5 Diagnosing NSD log entries
  620 
  621 NSD will print log messages to the system log (or 'logfile:' configuration
  622 entry). Some of these messages are discussed below. These messages can
  623 get extra support if errors happen.
  624 
  625 - "Reload process <pid> failed with status <s>, continuing with old database"
  626 
  627 This log message indicates the reload process of NSD has failed for
  628 some reason.  The reason can be anything from a missing database file
  629 to internal errors.  If this happens often, please let us know, this
  630 error message can be caught in the code, and appropriate action could
  631 be taken.  We are as of yet not sure what action is appropriate, if any.
  632 
  633 - "snipping off trailing partial part of <ixfr.db>"
  634 
  635 Please let us know if, and how often, this happens.
  636 
  637 What happens is the file ixfr.db contains only part of expected data.
  638 The corruption is removed by snipping off the trailing part.
  639 
  640 - "memory recyclebin holds <num> bytes"
  641 
  642 This is printed for every reload. NSD allocates and deallocates memory
  643 to service IXFR updates. The recyclebin holds deallocated memory ready
  644 for future use. If the number grows too large, a restart resets it.
  645 
  646 - "xfrd: max number of tcp connections (32) reached."
  647 
  648 This line is printed when more than 32 zones need a zone transfer at the
  649 same time.  The value is a compile constant (xfrd-tcp.h), but if this
  650 happens often for you, we could make this a config option.  NSD will reuse
  651 existing TCP connections to the same master (determined by IP address)
  652 to transfer up to 64k zones from that master.  Thus this error should
  653 only happen with more than 32 masters or more than 64*32=2M zones that
  654 need to be updated at the same time.
  655 
  656 If this happens, more zones have to wait until a zone transfer completes
  657 (or is aborted) before they can have a zone transfer too. This waiting
  658 list has no size limit.
  659 
  660 - "error: <zone> NSEC3PARAM entry <num> has unknown hash algo <number>"
  661 
  662 This error means that the zone has NSEC3 chain(s) with hash algorithms
  663 that are not supported by this version of NSD, and thus cannot be served
  664 by NSD.  If there are also no NSECs or NSEC3 chain(s) with known hash
  665 algorithms, NSD will not be able to serve DNSSEC authenticated denials
  666 for the zone.
  667 
  668 
  669 3.6 Interfaces
  670 
  671 NSD will by default bind itself to the system default interface and
  672 service ip4 and if available also ip6. It is possible to service only ip4
  673 or ip6 using the -4, -6 commandline options, or the ip4-only and ip6-only
  674 config file options.
  675 
  676 The commandline option -a and config file option ip-address can be given
  677 to bind to specific interfaces.  Multiple interfaces can be specified.
  678 This is useful for two reasons:
  679 	o The specific interface bound will result in the OS bypassing
  680 	  routing tables for the interface selection.  This results in
  681 	  a small performance gain.  It is not the performance gain that
  682 	  is the problem, sometimes the routing tables can give the
  683 	  wrong answer, see the next point.
  684 	o The answer will be routed via the interface the query came from.
  685 	  This makes sure that the return address on the DNS replies is the
  686 	  same as the query was sent to.  Many resolvers require the source
  687 	  address of the replies to be correct.  The ip-address: option is
  688 	  easier than configuring the OS routing table to return the DNS
  689 	  replies via the correct interface.
  690 The above means that even for systems with multiple interfaces where you
  691 intend to provide DNS service to all interfaces, it is prudent to specify
  692 all the interfaces as ip-address config file options.
  693 
  694 With the config file option ip-transparent you can allow NSD to bind to
  695 non local addresses.
  696 
  697 
  698 3.7 Tuning
  699 
  700 NSD is performant by design and most users will have little need for tuning
  701 it. For setups that do require every ounce of performance, NSD offers a number
  702 of configuration options.
  703 
  704 
  705 cpu-affinity, server-<N>-cpu-affinity and xfrd-cpu-affinity
  706 
  707 Modern computer systems have many cores available. By default the operating
  708 system's scheduling-algorithm determines which core a given task is allocated
  709 to. Processors build up state, like keeping frequently accessed data in cache
  710 memory, for the task (process/thread) that it is currently running. Whenever,
  711 a task switches cores, performance is degraded because the core it switched
  712 to has yet to build up said state. The cpu-affinity configuration options can
  713 be used to bind NSD to one or more cores.
  714 
  715 cpu-affinity can be used to designate a set of cores onto which NSD processes
  716 are scheduled. server-<N>-cpu-affinity and xfrd-cpu-affinity can be used to
  717 designate a specific core to each individual process. This improves L1/L2
  718 cache hits and reduces pipeline stalls/flushes.
  719 
  720 For example, a name server configured to fork two NSD servers that must run on
  721 dedicated cores 0 and 2, while the transfer daemon (xfrd) must run on core 1,
  722 the configuration becomes.
  723 
  724 	server:
  725 		server-count: 2
  726 		cpu-affinity: 0 1 2
  727 		server-1-cpu-affinity: 0
  728 		server-2-cpu-affinity: 2
  729 		xfrd-cpu-affinity: 1
  730 
  731 
  732 ip-address: x.x.x.x  servers=<N>
  733 
  734 ip-address options can be configured per (set of) server(s). Sockets that are
  735 configured for a specific server are closed by other servers on startup. This
  736 improves select/poll performance and avoids waking up multiple servers when a
  737 packet comes in.
  738 
  739 
  740 ip-address: x.x.x.x  bindtodevice=yes
  741 ip-address: x.x.x.x  setfib=<N>
  742 
  743 The bindtodevice attribute on Linux and the setfib ip-address attribute on
  744 FreeBSD can be used to skip the interface selection process in the kernel. This
  745 improves performance, and ensures responses written to the socket are pushed
  746 out the same interface the corresponding query came in on when multiple
  747 interfaces are configured to listen on the same subnet.
  748 
  749 The aforementioned options all complement eachother and best performance is
  750 achieved by assigning a socket to a single server that runs on a dedicated
  751 core and line that up with a dedicated network interface. Network interface
  752 interrupts are best handled by a core not designated to any NSD servers.
  753 
  754 	server:
  755 		server-count: 3
  756 		cpu-affinity: 0 1 2 4
  757 		server-1-cpu-affinity: 0
  758 		server-2-cpu-affinity: 1
  759 		server-3-cpu-affinity: 2
  760 		xfrd-cpu-affinity: 4
  761 		ip-address: 1.2.3.11  servers=1 setfib=1 bindtodevice=yes
  762 		ip-address: 1.2.3.12  servers=2 setfib=2 bindtodevice=yes
  763 		ip-address: 1.2.3.13  servers=3 setfib=3 bindtodevice=yes
  764 
  765 The number of NSD servers to fork and which cores are best used depends
  766 entirely on the hardware. cpu-affinity options are supported on Linux and
  767 FreeBSD.
  768 
  769 
  770 4.0 Support and Feedback
  771 
  772 NLnet Labs is committed to support NSD and its other software products on 
  773 a best effort basis, free of charge. This form of community support is 
  774 offered through a mailing lists and the 'bugzilla' web interface. 
  775 
  776 	http://www.nlnetlabs.nl/bugs/
  777 
  778 If for any reason NLnet Labs would stop community support of NSD such 
  779 would be announced on our web pages at least two years in advance.
  780 
  781 The community mailing list nsd-users@nlnetlabs.nl can be used to discuss 
  782 issues with other users of NSD. Subscribe here
  783 
  784 	http://lists.nlnetlabs.nl/mailman/listinfo/nsd-users
  785 
  786 NLnet Labs recognizes that in some corporate environments this commitment to
  787 community support is not sufficient and that support needs to be codified. 
  788 We therefore offer paid support contracts that come in 3 varieties. 
  789 
  790 More information about these support varieties can be found at 
  791 	<url on support varieties on www.nlnetlabs.nl>
  792 
  793 Alternatively you can contact mailto:nsd-support@nlnetlabs.nl .
  794 
  795 Support goes two ways.  By acquiring one of the support contracts you
  796 also support NLnet Labs to continue to participate in the development
  797 of the Internet architecture. We do this through our participation in
  798 the (IETF) standards process and by developing and maintaining
  799 reference implementations of standards and tools to support operation
  800 and deployment of new and existing Internet technology. 
  801 
  802 We are interested in our users and in the environment you use NSD. Please 
  803 drop us a mail when you use NSD. Indicate in what kind of operation you 
  804 deploy NSD and let us know what your positive and negative experiences are.
  805 http://www.nlnetlabs.nl/nsd  and  mailto:nsd-info@nlnetlabs.nl
  806 
  807 
  808 4.1 Your Support
  809 
  810 NLnet Labs offers all of its software products as open source, most are
  811 published under a BSD license. You can download them, not only from the
  812 NLnet Labs website but also through the various OS distributions for
  813 which NSD, ldns, and Unbound are packaged. We therefore have little idea
  814 who uses our software in production environments and have no direct ties
  815 with 'our customers'.
  816 
  817 Therefore, we ask you to contact us at users@NLnetLabs.nl and tell us
  818 whether you use one of our products in your production environment,
  819 what that environment looks like, and maybe even share some praise.
  820 We would like to refer to the fact that your organization is using our
  821 products. We will only do that if you explicitly allow us. In all other
  822 cases we will keep the information you share with us to ourselves.
  823 
  824 In addition to the moral support you can also support us
  825 financially. NLnet Labs is a recognized not-for-profit charity foundation
  826 that is chartered to develop open-source software and open-standards
  827 for the Internet. If you use our software to satisfaction please express
  828 that by giving us a donation. For small donations PayPal can be used. For
  829 larger and regular donations please contact us at users@NLnetLabs.nl. Also
  830 see http://www.nlnetlabs.nl/labs/contributors/.
  831 
  832 
  833 $Id$