DragonFly On-Line Manual Pages
nsd-control(8) nsd 4.1.7 nsd-control(8)
NAME
nsd-control, nsd-control-setup - NSD remote server control utility.
SYNOPSIS
nsd-control [-c cfgfile] [-s server] command
DESCRIPTION
nsd-control performs remote administration on the nsd(8) DNS server.
It reads the configuration file, contacts the nsd server over SSL,
sends the command and displays the result.
The available options are:
-h Show the version and commandline option help.
-c cfgfile
The config file to read with settings. If not given the default
config file /usr/local/etc/nsd/nsd.conf is used.
-s server[@port]
IPv4 or IPv6 address of the server to contact. If not given,
the address is read from the config file.
COMMANDS
There are several commands that the server understands.
start Start the server. Simply execs nsd(8). The nsd executable is
searched for in the PATH set in the environment. It is started
with the config file specified using -c or the default config
file.
stop Stop the server. The server daemon exits.
reload [<zone>]
Reload zonefiles and reopen logfile. Without argument reads
changed zonefiles. With argument reads the zonefile for the
given zone and loads it.
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.
repattern
Same as the reconfig option.
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).
status Display server status. Exit code 3 if not running (the
connection to the port is refused), 1 on error, 0 if running.
stats Output a sequence of name=value lines with statistics
information, requires NSD to be compiled with this option
enabled.
stats_noreset
Same as stats, but does not zero the counters.
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.
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.
addzones
Add zones read from stdin of nsd-control. Input is read per
line, with name space patternname on a line. For bulk
additions.
delzones
Remove zones read from stdin of nsd-control. Input is one name
per line. For bulk removals.
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.
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.
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. For zones with no content, NSD may have backed off
from asking often because the masters did not respond, but this
command will reset the backoff to its initial timeout, for
frequent retries.
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.
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. The state of the zone is printed as:
'master' (master zones), 'ok' (slave zone is up-to-date),
'expired' (slave zone has expired), 'refreshing' (slave zone has
transfers active). The serial numbers printed are the
'served-serial' (currently active), the 'commit-serial' (is in
reload), the 'notified-serial' (got notify, busy fetching the
data). The serial numbers are only printed if such a serial
number is available.
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.
verbosity <number>
Change logging verbosity.
EXIT CODE
The nsd-control program exits with status code 1 on error, 0 on
success.
SET UP
The setup requires a self-signed certificate and private keys for both
the server and client. The script nsd-control-setup 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 control-enable in nsd.conf.
STATISTIC COUNTERS
The stats command shows a number of statistic counters.
num.queries
number of queries received (the tcp and udp queries added up).
serverX.queries
number of queries handled by the server process. The number of
server processes is set with the config statement server-count.
time.boot
uptime in seconds since the server was started. With fractional
seconds.
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.
size.db.disk
size of nsd.db on disk, in bytes.
size.db.mem
size of the DNS database in memory, in bytes.
size.xfrd.mem
size of memory for zone transfers and notifies in xfrd process,
excludes TSIG data, in bytes.
size.config.disk
size of zonelist file on disk, excludes the nsd.conf size, in
bytes.
size.config.mem
size of config data in memory, kept twice in server and xfrd
process, in bytes.
num.type.X
number of queries with this query type.
num.opcode.X
number of queries with this opcode.
num.class.X
number of queries with this query class.
num.rcode.X
number of answers that carried this return code.
num.edns
number of queries with EDNS OPT.
num.ednserr
number of queries which failed EDNS parse.
num.udp
number of queries over UDP ip4.
num.udp6
number of queries over UDP ip6.
num.tcp
number of connections over TCP ip4.
num.tcp6
number of connections over TCP ip6.
num.answer_wo_aa
number of answers with NOERROR rcode and without AA flag, this
includes the referrals.
num.rxerr
number of queries for which the receive failed.
num.txerr
number of answers for which the transmit failed.
num.raxfr
number of AXFR requests from clients (that got served with
reply).
num.truncated
number of answers with TC flag set.
num.dropped
number of queries that were dropped because they failed sanity
check.
zone.master
number of master zones served. These are zones with no
'request-xfr:' entries.
zone.slave
number of slave zones served. These are zones with
'request-xfr' entries.
FILES
/usr/local/etc/nsd/nsd.conf
nsd configuration file.
/usr/local/etc/nsd
directory with private keys (nsd_server.key and nsd_control.key)
and self-signed certificates (nsd_server.pem and
nsd_control.pem).
SEE ALSO
nsd.conf(5), nsd(8), nsd-checkconf(8)
NLnet Labs December 10, 2015 nsd-control(8)