import NSD 4.0.0, tests from Dorian Büttner, Patrik Lundin, requested by brad@

1 files changed, 245 insertions, 0 deletions

diff --git a/usr.sbin/nsd/nsd-control.8.in b/usr.sbin/nsd/nsd-control.8.in
new file mode 100644
index 00000000000..bf610f1097b
--- /dev/null
+++ b/usr.sbin/nsd/nsd-control.8.in
@@ -0,0 +1,245 @@
+.TH "nsd\-control" "8" "Oct 29, 2013" "NLnet Labs" "nsd 4.0.0"
+.\" Copyright (c) 2011, NLnet Labs. All rights reserved.
+.\" See LICENSE for the license.
+.SH "NAME"
+.LP
+.B nsd\-control,
+.B nsd\-control\-setup
+\- NSD remote server control utility.
+.SH "SYNOPSIS"
+.B nsd\-control
+.RB [ \-c 
+.IR cfgfile ]
+.RB [ \-s 
+.IR server ]
+.IR command
+.SH "DESCRIPTION"
+.B nsd\-control
+performs remote administration on the \fInsd\fR(8) DNS server.  It reads
+the configuration file, contacts the nsd server over SSL, sends the
+command and displays the result.
+.P
+The available options are:
+.TP
+.B \-h
+Show the version and commandline option help.
+.TP
+.B \-c \fIcfgfile
+The config file to read with settings.  If not given the default
+config file @nsdconfigfile@ is used.
+.TP
+.B \-s \fIserver[@port]
+IPv4 or IPv6 address of the server to contact.  If not given, the
+address is read from the config file.
+.SH "COMMANDS"
+There are several commands that the server understands.
+.TP
+.B start
+Start the server. Simply execs \fInsd\fR(8).  The nsd executable 
+is searched for in the \fBPATH\fR set in the environment.  It is started 
+with the config file specified using \fI\-c\fR or the default config file.
+.TP
+.B stop
+Stop the server. The server daemon exits.
+.TP
+.B reload [<zone>]
+Reload zonefiles and reopen logfile.  Without argument reads changed
+zonefiles.  With argument reads the zonefile for the given zone and
+loads it.
+.TP
+.B reconfig
+Reload nsd.conf and apply changes to TSIG keys and configuration patterns,
+and apply the changes to add and remove zones that are mentioned in the config.
+Other changes are not applied, such as listening ip address and port and chroot.
+The pattern updates means that the configuration options for
+zones (request\-xfr, zonefile, notify, ...) are updated.  Also new
+patterns are available for use with the addzone command.
+.TP
+.B repattern
+Same as the reconfig option.
+.TP
+.B log_reopen
+Reopen the logfile, for log rotate that wants to move the logfile away
+and create a new logfile.  The log can also be reopened with kill \-HUP
+(which also reloads all zonefiles).
+.TP
+.B status
+Display server status. Exit code 3 if not running (the connection to the 
+port is refused), 1 on error, 0 if running.
+.TP
+.B stats
+Output a sequence of name=value lines with statistics information, requires
+NSD to be compiled with this option enabled.
+.TP
+.B stats_noreset
+Same as stats, but does not zero the counters.
+.TP
+.B addzone <zone name> <pattern name>
+Add a new zone to the running server.  The zone is added to the zonelist
+file on disk, so it stays after a restart.  The pattern name determines
+the options for the new zone.  For slave zones a zone transfer is
+immediately attempted.  For zones with a zonefile, the zone file is
+attempted to be read in.
+.TP
+.B delzone <zone name>
+Remove the zone from the running server.  The zone is removed from the
+zonelist file on disk, from the nsd.db file and from the memory.  If it
+had a zonefile, this remains (but may be outdated).  Zones configured
+inside nsd.conf itself cannot be removed this way because the daemon
+does not write to the nsd.conf file, you need to add such zones to the
+zonelist file to be able to delete them with the delzone command.
+.TP
+.B write [<zone>]
+Write zonefiles to disk, or the given zonefile to disk.  Zones that have
+changed (via AXFR or IXFR) are written, or if the zonefile has not been
+created yet then it is created.  Directory components of the zonefile
+path are created if necessary.
+.TP
+.B notify [<zone>]
+Send NOTIFY messages to slave servers.  Sends to the IP addresses
+configured in the 'notify:' lists for the master zones hosted on this
+server.  Usually NSD sends NOTIFY messages right away when a master zone
+serial is updated.  If a zone is given, notifies are sent for that zone.
+These slave servers are supposed to initiate a zone transfer request
+later (to this server or another master), this can be allowed via
+the 'provide\-xfr:' acl list configuration.
+.TP
+.B transfer [<zone>]
+Attempt to update slave zones that are hosted on this server by contacting
+the masters.  The masters are configured via 'request\-xfr:' lists.
+If a zone is given, that zone is updated.  Usually NSD receives a NOTIFY
+from the masters (configured via 'allow\-notify:' acl list) that a new zone
+serial has to be transferred.
+.TP
+.B force_transfer [<zone>]
+Force update slave zones that are hosted on this server.  Even if the
+master hosts the same serial number of the zone, a full AXFR is performed
+to fetch it.  If you want to use IXFR and check that the serial number
+increases, use the 'transfer' command.
+.TP
+.B zonestatus [<zone>]
+Print state of the zone, the serial numbers and since when they have
+been acquired.  Also prints the notify action (to which server), and
+zone transfer (and from which master) if there is activity right now.
+.TP
+.B serverpid
+Prints the PID of the server process.  This is used for statistics (and
+only works when NSD is compiled with statistics enabled).  This pid is
+not for sending unix signals, use the pid from nsd.pid for that, that pid
+is also stable.
+.TP
+.B verbosity <number>
+Change logging verbosity.
+.SH "EXIT CODE"
+The nsd\-control program exits with status code 1 on error, 0 on success.
+.SH "SET UP"
+The setup requires a self\-signed certificate and private keys for both 
+the server and client.  The script \fInsd\-control\-setup\fR generates
+these in the default run directory, or with \-d in another directory.
+If you change the access control permissions on the key files you can decide
+who can use nsd\-control, by default owner and group but not all users.
+The script preserves private keys present in the directory.
+After running the script as root, turn on \fBcontrol\-enable\fR in 
+\fInsd.conf\fR.
+.SH "STATISTIC COUNTERS"
+The \fIstats\fR command shows a number of statistic counters.
+.TP
+.I num.queries
+number of queries received (the tcp and udp queries added up).
+.TP
+.I serverX.queries
+number of queries handled by the server process.  The number of
+server processes is set with the config statement \fBserver\-count\fR.
+.TP
+.I time.boot
+uptime in seconds since the server was started.  With fractional seconds.
+.TP
+.I time.elapsed
+time since the last stats report, in seconds.  With fractional seconds.
+Can be zero if polled quickly and the previous stats command resets the
+counters, so that the next gets a fully zero, and zero elapsed time, report.
+.TP
+.I size.db.disk
+size of nsd.db on disk, in bytes.
+.TP
+.I size.db.mem
+size of the DNS database in memory, in bytes.
+.TP
+.I size.xfrd.mem
+size of memory for zone transfers and notifies in xfrd process, excludes
+TSIG data, in bytes.
+.TP
+.I size.config.disk
+size of zonelist file on disk, excludes the nsd.conf size, in bytes.
+.TP
+.I size.config.mem
+size of config data in memory, kept twice in server and xfrd process,
+in bytes.
+.TP
+.I num.type.X
+number of queries with this query type.
+.TP
+.I num.opcode.X
+number of queries with this opcode.
+.TP
+.I num.class.X
+number of queries with this query class.
+.TP
+.I num.rcode.X
+number of answers that carried this return code.
+.TP
+.I num.edns
+number of queries with EDNS OPT.
+.TP
+.I num.ednserr
+number of queries which failed EDNS parse.
+.TP
+.I num.udp
+number of queries over UDP ip4.
+.TP
+.I num.udp6
+number of queries over UDP ip6.
+.TP
+.I num.tcp
+number of connections over TCP ip4.
+.TP
+.I num.tcp6
+number of connections over TCP ip6.
+.TP
+.I num.answer_wo_aa
+number of answers with NOERROR rcode and without AA flag, this includes the referrals.
+.TP
+.I num.rxerr
+number of queries for which the receive failed.
+.TP
+.I num.txerr
+number of answers for which the transmit failed.
+.TP
+.I num.raxfr
+number of AXFR requests from clients (that got served with reply).
+.TP
+.I num.truncated
+number of answers with TC flag set.
+.TP
+.I num.dropped
+number of queries that were dropped because they failed sanity check.
+.TP
+.I zone.master
+number of master zones served.  These are zones with no 'request\-xfr:'
+entries.
+.TP
+.I zone.slave
+number of slave zones served.  These are zones with 'request\-xfr'
+entries.
+.SH "FILES"
+.TP
+.I @nsdconfigfile@
+nsd configuration file.
+.TP
+.I @configdir@
+directory with private keys (nsd_server.key and nsd_control.key) and
+self\-signed certificates (nsd_server.pem and nsd_control.pem).
+.SH "SEE ALSO"
+\fInsd.conf\fR(5), 
+\fInsd\fR(8),
+\fInsd\-checkconf\fR(8)