345 lines
13 KiB
Groff
345 lines
13 KiB
Groff
.TH "nsd\-control" "8" "Apr 4, 2024" "NLnet Labs" "nsd 4.9.1"
|
|
.\" Copyright (c) 2011, NLnet Labs. All rights reserved.
|
|
.\" See LICENSE for the license.
|
|
.SH "NAME"
|
|
.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. Commands that require a reload are queued
|
|
and the result indicates the command was accepted.
|
|
.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 not searched for in the \fBPATH\fR set in the environment. Instead the
|
|
default location relative to the installation prefix specified at
|
|
compile-time. The executable location can be overridden by setting
|
|
\fINSD_PATH\fR 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,
|
|
also per-zone statistics are not applied.
|
|
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 secondary 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 changezone <zone name> <pattern name>
|
|
Change a zone to use the pattern for options. The zone is deleted and added
|
|
in one operation, changing it to use the new pattern for the zone options.
|
|
Zones configured in nsd.conf cannot be changed like this, instead edit
|
|
the nsd.conf (or the included file in nsd.conf) and reconfig.
|
|
.TP
|
|
.B addzones
|
|
Add zones read from stdin of nsd\-control. Input is read per line,
|
|
with name space patternname on a line. For bulk additions.
|
|
.TP
|
|
.B delzones
|
|
Remove zones read from stdin of nsd\-control. Input is one name per line.
|
|
For bulk removals.
|
|
.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. With argument that zone is written if it
|
|
was modified, without argument, all modified zones are written.
|
|
.TP
|
|
.B notify [<zone>]
|
|
Send NOTIFY messages to secondary servers. Sends to the IP addresses
|
|
configured in the 'notify:' lists for the primary zones hosted on this
|
|
server. Usually NSD sends NOTIFY messages right away when a primary zone
|
|
serial is updated. If a zone is given, notifies are sent for that zone.
|
|
These secondary servers are supposed to initiate a zone transfer request
|
|
later (to this server or another primary), this can be allowed via
|
|
the 'provide\-xfr:' acl list configuration. With argument that zone is
|
|
processed, without argument, all zones are processed.
|
|
.TP
|
|
.B transfer [<zone>]
|
|
Attempt to update secondary zones that are hosted on this server by contacting
|
|
the primaries. The primaries are configured via 'request\-xfr:' lists.
|
|
If a zone is given, that zone is updated. Usually NSD receives a NOTIFY
|
|
from the primaries (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 primaries did not respond, but this command
|
|
will reset the backoff to its initial timeout, for frequent retries. With
|
|
argument that zone is transferred, without argument, all zones are transferred.
|
|
.TP
|
|
.B force_transfer [<zone>]
|
|
Force update secondary zones that are hosted on this server. Even if the
|
|
primary 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. With argument that zone is
|
|
transferred, without argument, all zones are transferred.
|
|
.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 primary) if there is activity right now.
|
|
The state of the zone is printed as: 'primary' (primary zones), 'ok' (secondary
|
|
zone is up\-to\-date), 'expired' (secondary zone has expired), 'refreshing' (secondary
|
|
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. With argument
|
|
that zone is printed, without argument, all zones are printed.
|
|
.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.
|
|
.TP
|
|
.B print_tsig [<key_name>]
|
|
print the secret and algorithm for the TSIG key with that name.
|
|
Or list all the tsig keys with their name, secret and algorithm.
|
|
.TP
|
|
.B update_tsig <name> <secret>
|
|
Change existing TSIG key with name to the new secret. The secret is
|
|
a base64 encoded string. The changes are only in-memory and are gone next
|
|
restart, for lasting changes edit the nsd.conf file or a file included from it.
|
|
.TP
|
|
.B add_tsig <name> <secret> [algo]
|
|
Add a new TSIG key with the given name, secret and algorithm. Without
|
|
algorithm a default (hmac-sha256) algorithm is used. The secret is a
|
|
base64 encoded string. The changes are only in-memory and are gone next
|
|
restart, for lasting changes edit the nsd.conf file or a file included from it.
|
|
.TP
|
|
.B assoc_tsig <zone> <key_name>
|
|
Associate the zone with the given tsig. The access control lists for
|
|
notify, allow-notify, provide-xfr and request-xfr are adjusted to use the
|
|
given key.
|
|
.TP
|
|
.B del_tsig <key_name>
|
|
Delete the TSIG key with the given name. Prints error if the key is still
|
|
in use by some zone. The changes are only in-memory and are gone next
|
|
restart, for lasting changes edit the nsd.conf file or a file included from it.
|
|
.TP
|
|
.B add_cookie_secret <secret>
|
|
Add or replace a cookie secret persistently. <secret> needs to be an 128 bit
|
|
hex string.
|
|
|
|
Cookie secrets can be either \fIactive\fR or \fIstaging\fR. \fIActive\fR cookie
|
|
secrets are used to create DNS Cookies, but verification of a DNS Cookie
|
|
succeeds with any of the \fIactive\fR or \fIstaging\fR cookie secrets. The
|
|
state of the current cookie secrets can be printed with the
|
|
\fBprint_cookie_secrets\fR command.
|
|
|
|
When there are no cookie secrets configured yet, the <secret> is added as
|
|
\fIactive\fR. If there is already an \fIactive\fR cookie secret, the <secret>
|
|
is added as \fIstaging\fR or replacing an existing \fIstaging\fR secret.
|
|
|
|
To "roll" a cookie secret used in an anycast set. The new secret has to be
|
|
added as staging secret to \fBall\fR nodes in the anycast set. When \fBall\fR
|
|
nodes can verify DNS Cookies with the new secret, the new secret can be
|
|
activated with the \fBactivate_cookie_secret\fR command. After \fBall\fR nodes
|
|
have the new secret \fIactive\fR for at least one hour, the previous secret can
|
|
be dropped with the \fBdrop_cookie_secret\fR command.
|
|
|
|
Persistence is accomplished by writing to a file which if configured with the
|
|
\fBcookie\-secret\-file\fR option in the server section of the config file.
|
|
The default value for that is: @configdir@/nsd_cookiesecrets.txt .
|
|
.TP
|
|
.B drop_cookie_secret
|
|
Drop the \fIstaging\fR cookie secret.
|
|
.TP
|
|
.B activate_cookie_secret
|
|
Make the current \fIstaging\fR cookie secret \fIactive\fR, and the current
|
|
\fIactive\fR cookie secret \fIstaging\fR.
|
|
.TP
|
|
.B print_cookie_secrets
|
|
Show the current configured cookie secrets with their status.
|
|
.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 tls, 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.tls
|
|
number of connections over TLS ip4. TLS queries are not part of num.tcp.
|
|
.TP
|
|
.I num.tls6
|
|
number of connections over TLS ip6. TLS queries are not part of num.tcp6.
|
|
.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.rixfr
|
|
number of IXFR 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.primary
|
|
number of primary zones served. These are zones with no 'request\-xfr:'
|
|
entries. Also output as 'zone.master' for backwards compatibility.
|
|
.TP
|
|
.I zone.secondary
|
|
number of secondary zones served. These are zones with 'request\-xfr'
|
|
entries. Also output as 'zone.slave' for backwards compatibility.
|
|
.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)
|