RNDC(8) BIND 9 RNDC(8)
NAME
rndc - name server control utility
SYNOPSIS
rndc [-b source-address] [-c config-file] [-k key-file] [-s server] [-p
port] [-q] [-r] [-V] [-y key_id] [[-4] | [-6]] {command}
DESCRIPTION
rndc controls the operation of a name server. It supersedes the ndc
utility that was provided in old BIND releases. If rndc is invoked with
no command line options or arguments, it prints a short summary of the
supported commands and the available options and their arguments.
rndc communicates with the name server over a TCP connection, sending
commands authenticated with digital signatures. In the current versions
of rndc and named, the only supported authentication algorithms are
HMAC-MD5 (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (de-
fault), HMAC-SHA384 and HMAC-SHA512. They use a shared secret on each
end of the connection. This provides TSIG-style authentication for the
command request and the name server's response. All commands sent over
the channel must be signed by a key_id known to the server.
rndc reads a configuration file to determine how to contact the name
server and decide what algorithm and key it should use.
OPTIONS
-4 Use IPv4 only.
-6 Use IPv6 only.
-b source-address
Use source-address as the source address for the connection to
the server. Multiple instances are permitted to allow setting of
both the IPv4 and IPv6 source addresses.
-c config-file
Use config-file as the configuration file instead of the de-
fault, /etc/rndc.conf.
-k key-file
Use key-file as the key file instead of the default,
/etc/rndc.key. The key in /etc/rndc.key will be used to authen-
ticate commands sent to the server if the config-file does not
exist.
-s server
server is the name or address of the server which matches a
server statement in the configuration file for rndc. If no
server is supplied on the command line, the host named by the
default-server clause in the options statement of the rndc con-
figuration file will be used.
-p port
Send commands to TCP port port instead of BIND 9's default con-
trol channel port, 953.
-q Quiet mode: Message text returned by the server will not be
printed except when there is an error.
-r Instructs rndc to print the result code returned by named after
executing the requested command (e.g., ISC_R_SUCCESS,
ISC_R_FAILURE, etc).
-V Enable verbose logging.
-y key_id
Use the key key_id from the configuration file. key_id must be
known by named with the same algorithm and secret string in or-
der for control message validation to succeed. If no key_id is
specified, rndc will first look for a key clause in the server
statement of the server being used, or if no server statement is
present for that host, then the default-key clause of the op-
tions statement. Note that the configuration file contains
shared secrets which are used to send authenticated control com-
mands to name servers. It should therefore not have general read
or write access.
COMMANDS
A list of commands supported by rndc can be seen by running rndc with-
out arguments.
Currently supported commands are:
addzone zone [class [view]] configuration
Add a zone while the server is running. This command requires
the allow-new-zones option to be set to yes. The configuration
string specified on the command line is the zone configuration
text that would ordinarily be placed in named.conf(5).
The configuration is saved in a file called viewname.nzf (or, if
named(8) is compiled with liblmdb, an LMDB database file called
viewname.nzd). viewname is the name of the view, unless the view
name contains characters that are incompatible with use as a
file name, in which case a cryptographic hash of the view name
is used instead. When named(8) is restarted, the file will be
loaded into the view configuration, so that zones that were
added can persist after a restart.
This sample addzone command would add the zone example.com to
the default view:
$rndc addzone example.com '{ type master; file "example.com.db";
};'
(Note the brackets and semi-colon around the zone configuration
text.)
See also rndc delzone and rndc modzone.
delzone [-clean] zone [class [view]]
Delete a zone while the server is running.
If the -clean argument is specified, the zone's master file (and
journal file, if any) will be deleted along with the zone. With-
out the -clean option, zone files must be cleaned up by hand.
(If the zone is of type "slave" or "stub", the files needing to
be cleaned up will be reported in the output of the rndc delzone
command.)
If the zone was originally added via rndc addzone, then it will
be removed permanently. However, if it was originally configured
in named.conf, then that original configuration is still in
place; when the server is restarted or reconfigured, the zone
will come back. To remove it permanently, it must also be re-
moved from named.conf
See also rndc addzone and rndc modzone.
dnssec ( -status | -rollover -key id [-alg algorithm] [-when time] |
-checkds [-key id [-alg algorithm]] [-when time] ( published | with-
drawn )) zone [class [view]]
This command allows you to interact with the "dnssec-policy" of
a given zone.
rndc dnssec -status show the DNSSEC signing state for the speci-
fied zone.
rndc dnssec -rollover allows you to schedule key rollover for a
specific key (overriding the original key lifetime).
rndc dnssec -checkds will let named know that the DS for the
given key has been seen published into or withdrawn from the
parent. This is required in order to complete a KSK rollover.
If the -key id argument is specified, look for the key with the
given identifier, otherwise if there is only one key acting as a
KSK in the zone, assume the DS of that key (if there are multi-
ple keys with the same tag, use -alg algorithm to select the
correct algorithm). The time that the DS has been published or
withdrawn is set to now, unless otherwise specified with the ar-
gument -when time.
dnstap ( -reopen | -roll [number] )
Close and re-open DNSTAP output files. rndc dnstap -reopen al-
lows the output file to be renamed externally, so that named(8)
can truncate and re-open it. rndc dnstap -roll causes the output
file to be rolled automatically, similar to log files; the most
recent output file has ".0" appended to its name; the previous
most recent output file is moved to ".1", and so on. If number
is specified, then the number of backup log files is limited to
that number.
dumpdb [-all | -cache | -zones | -adb | -bad | -expired | -fail] [view
...]
Dump the server's caches (default) and/or zones to the dump file
for the specified views. If no view is specified, all views are
dumped. (See the dump-file option in the BIND 9 Administrator
Reference Manual.)
flush Flushes the server's cache.
flushname name [view]
Flushes the given name from the view's DNS cache and, if appli-
cable, from the view's nameserver address database, bad server
cache and SERVFAIL cache.
flushtree name [view]
Flushes the given name, and all of its subdomains, from the
view's DNS cache, address database, bad server cache, and SERV-
FAIL cache.
freeze [zone [class [view]]]
Suspend updates to a dynamic zone. If no zone is specified, then
all zones are suspended. This allows manual edits to be made to
a zone normally updated by dynamic update. It also causes
changes in the journal file to be synced into the master file.
All dynamic update attempts will be refused while the zone is
frozen.
See also rndc thaw.
halt [-p]
Stop the server immediately. Recent changes made through dynamic
update or IXFR are not saved to the master files, but will be
rolled forward from the journal files when the server is
restarted. If -p is specified named(8)'s process id is returned.
This allows an external process to determine when named(8) had
completed halting.
See also rndc stop.
loadkeys [zone [class [view]]]
Fetch all DNSSEC keys for the given zone from the key directory.
If they are within their publication period, merge them into the
zone's DNSKEY RRset. Unlike rndc sign, however, the zone is not
immediately re-signed by the new keys, but is allowed to incre-
mentally re-sign over time.
This command requires that zone is configured with a dnssec-pol-
icy, or the auto-dnssec zone option be set to maintain, and also
requires the zone to be configured to allow dynamic DNS. (See
"Dynamic Update Policies" in the Administrator Reference Manual
for more details.)
managed-keys (status | refresh | sync | destroy) [class [view]]
Inspect and control the "managed-keys" database which handles
RFC 5011 DNSSEC trust anchor maintenance. If a view is speci-
fied, these commands are applied to that view; otherwise they
are applied to all views.
o When run with the status keyword, prints the current status of
the managed-keys database.
o When run with the refresh keyword, forces an immediate refresh
query to be sent for all the managed keys, updating the man-
aged-keys database if any new keys are found, without waiting
the normal refresh interval.
o When run with the sync keyword, forces an immediate dump of
the managed-keys database to disk (in the file man-
aged-keys.bind or (viewname.mkeys). This synchronizes the
database with its journal file, so that the database's current
contents can be inspected visually.
o When run with the destroy keyword, the managed-keys database
is shut down and deleted, and all key maintenance is termi-
nated. This command should be used only with extreme caution.
Existing keys that are already trusted are not deleted from
memory; DNSSEC validation can continue after this command is
used. However, key maintenance operations will cease until
named(8) is restarted or reconfigured, and all existing key
maintenance state will be deleted.
Running rndc reconfig or restarting named(8) immediately after
this command will cause key maintenance to be reinitialized
from scratch, just as if the server were being started for the
first time. This is primarily intended for testing, but it may
also be used, for example, to jumpstart the acquisition of new
keys in the event of a trust anchor rollover, or as a
brute-force repair for key maintenance problems.
modzone zone [class [view]] configuration
Modify the configuration of a zone while the server is running.
This command requires the allow-new-zones option to be set to
yes. As with addzone, the configuration string specified on the
command line is the zone configuration text that would ordinar-
ily be placed in named.conf.
If the zone was originally added via rndc addzone, the configu-
ration changes will be recorded permanently and will still be in
effect after the server is restarted or reconfigured. However,
if it was originally configured in named.conf, then that origi-
nal configuration is still in place; when the server is
restarted or reconfigured, the zone will revert to its original
configuration. To make the changes permanent, it must also be
modified in named.conf
See also rndc addzone and rndc delzone.
notify zone [class [view]]
Resend NOTIFY messages for the zone.
notrace
Sets the server's debugging level to 0.
See also rndc trace.
nta [( -class class | -dump | -force | -remove | -lifetime duration)]
domain [view]
Sets a DNSSEC negative trust anchor (NTA) for domain, with a
lifetime of duration. The default lifetime is configured in
named.conf via the nta-lifetime option, and defaults to one
hour. The lifetime cannot exceed one week.
A negative trust anchor selectively disables DNSSEC validation
for zones that are known to be failing because of misconfigura-
tion rather than an attack. When data to be validated is at or
below an active NTA (and above any other configured trust an-
chors), named(8) will abort the DNSSEC validation process and
treat the data as insecure rather than bogus. This continues un-
til the NTA's lifetime is elapsed.
NTAs persist across restarts of the named(8) server. The NTAs
for a view are saved in a file called name.nta, where name is
the name of the view, or if it contains characters that are in-
compatible with use as a file name, a cryptographic hash gener-
ated from the name of the view.
An existing NTA can be removed by using the -remove option.
An NTA's lifetime can be specified with the -lifetime option.
TTL-style suffixes can be used to specify the lifetime in sec-
onds, minutes, or hours. If the specified NTA already exists,
its lifetime will be updated to the new value. Setting lifetime
to zero is equivalent to -remove.
If the -dump is used, any other arguments are ignored, and a
list of existing NTAs is printed (note that this may include
NTAs that are expired but have not yet been cleaned up).
Normally, named(8) will periodically test to see whether data
below an NTA can now be validated (see the nta-recheck option in
the Administrator Reference Manual for details). If data can be
validated, then the NTA is regarded as no longer necessary, and
will be allowed to expire early. The -force overrides this be-
havior and forces an NTA to persist for its entire lifetime, re-
gardless of whether data could be validated if the NTA were not
present.
The view class can be specified with -class. The default is
class IN, which is the only class for which DNSSEC is currently
supported.
All of these options can be shortened, i.e., to -l, -r, -d, -f,
and -c.
Unrecognized options are treated as errors. To reference a do-
main or view name that begins with a hyphen, use a double-hyphen
on the command line to indicate the end of options.
querylog [(on | off)]
Enable or disable query logging. (For backward compatibility,
this command can also be used without an argument to toggle
query logging on and off.)
Query logging can also be enabled by explicitly directing the
queries category to a channel in the logging section of
named.conf or by specifying querylog yes; in the options section
of named.conf.
reconfig
Reload the configuration file and load new zones, but do not
reload existing zone files even if they have changed. This is
faster than a full reload when there is a large number of zones
because it avoids the need to examine the modification times of
the zones files.
recursing
Dump the list of queries named(8) is currently recursing on, and
the list of domains to which iterative queries are currently be-
ing sent. (The second list includes the number of fetches cur-
rently active for the given domain, and how many have been
passed or dropped because of the fetches-per-zone option.)
refresh zone [class [view]]
Schedule zone maintenance for the given zone.
reload Reload configuration file and zones.
reload zone [class [view]]
Reload the given zone.
retransfer zone [class [view]]
Retransfer the given slave zone from the master server.
If the zone is configured to use inline-signing, the signed ver-
sion of the zone is discarded; after the retransfer of the un-
signed version is complete, the signed version will be regener-
ated with all new signatures.
scan Scan the list of available network interfaces for changes, with-
out performing a full reconfig or waiting for the interface-in-
terval timer.
secroots [-] [view ...]
Dump the security roots (i.e., trust anchors configured via
trust-anchors, or the managed-keys or trusted-keys statements
(both deprecated), or dnssec-validation auto) and negative trust
anchors for the specified views. If no view is specified, all
views are dumped. Security roots will indicate whether they are
configured as trusted keys, managed keys, or initializing man-
aged keys (managed keys that have not yet been updated by a suc-
cessful key refresh query).
If the first argument is "-", then the output is returned via
the rndc response channel and printed to the standard output.
Otherwise, it is written to the secroots dump file, which de-
faults to named.secroots, but can be overridden via the sec-
roots-file option in named.conf.
See also rndc managed-keys.
serve-stale (on | off | reset | status) [class [view]]
Enable, disable, reset, or report the current status of the
serving of stale answers as configured in named.conf.
If serving of stale answers is disabled by rndc-serve-stale off,
then it will remain disabled even if named(8) is reloaded or re-
configured. rndc serve-stale reset restores the setting as con-
figured in named.conf.
rndc serve-stale status will report whether serving of stale an-
swers is currently enabled, disabled by the configuration, or
disabled by rndc. It will also report the values of stale-an-
swer-ttl and max-stale-ttl.
showzone zone [class [view]]
Print the configuration of a running zone.
See also rndc zonestatus.
sign zone [class [view]]
Fetch all DNSSEC keys for the given zone from the key directory
(see the key-directory option in the BIND 9 Administrator Refer-
ence Manual). If they are within their publication period, merge
them into the zone's DNSKEY RRset. If the DNSKEY RRset is
changed, then the zone is automatically re-signed with the new
key set.
This command requires that the zone is configure with a
dnssec-policy, or that the auto-dnssec zone option be set to al-
low or maintain, and also requires the zone to be configured to
allow dynamic DNS. (See "Dynamic Update Policies" in the Admin-
istrator Reference Manual for more details.)
See also rndc loadkeys.
signing [(-list | -clear keyid/algorithm | -clear all | -nsec3param (
parameters | none ) | -serial value ) zone [class [view]]
List, edit, or remove the DNSSEC signing state records for the
specified zone. The status of ongoing DNSSEC operations (such as
signing or generating NSEC3 chains) is stored in the zone in the
form of DNS resource records of type sig-signing-type. rndc
signing -list converts these records into a human-readable form,
indicating which keys are currently signing or have finished
signing the zone, and which NSEC3 chains are being created or
removed.
rndc signing -clear can remove a single key (specified in the
same format that rndc signing -list uses to display it), or all
keys. In either case, only completed keys are removed; any
record indicating that a key has not yet finished signing the
zone will be retained.
rndc signing -nsec3param sets the NSEC3 parameters for a zone.
This is the only supported mechanism for using NSEC3 with in-
line-signing zones. Parameters are specified in the same format
as an NSEC3PARAM resource record: hash algorithm, flags, itera-
tions, and salt, in that order.
Currently, the only defined value for hash algorithm is 1, rep-
resenting SHA-1. The flags may be set to 0 or 1, depending on
whether you wish to set the opt-out bit in the NSEC3 chain. it-
erations defines the number of additional times to apply the al-
gorithm when generating an NSEC3 hash. The salt is a string of
data expressed in hexadecimal, a hyphen (-') if no salt is to be
used, or the keyword ``auto`, which causes named(8) to generate
a random 64-bit salt.
So, for example, to create an NSEC3 chain using the SHA-1 hash
algorithm, no opt-out flag, 10 iterations, and a salt value of
"FFFF", use: rndc signing -nsec3param 1 0 10 FFFF zone. To set
the opt-out flag, 15 iterations, and no salt, use: rndc signing
-nsec3param 1 1 15 - zone.
rndc signing -nsec3param none removes an existing NSEC3 chain
and replaces it with NSEC.
rndc signing -serial value sets the serial number of the zone to
value. If the value would cause the serial number to go back-
wards it will be rejected. The primary use is to set the serial
on inline signed zones.
stats Write server statistics to the statistics file. (See the statis-
tics-file option in the BIND 9 Administrator Reference Manual.)
status Display status of the server. Note that the number of zones in-
cludes the internal bind/CH zone and the default ./IN hint zone
if there is not an explicit root zone configured.
stop -p
Stop the server, making sure any recent changes made through dy-
namic update or IXFR are first saved to the master files of the
updated zones. If -p is specified named(8)'s process id is re-
turned. This allows an external process to determine when
named(8) had completed stopping.
See also rndc halt.
sync -clean [zone [class [view]]]
Sync changes in the journal file for a dynamic zone to the mas-
ter file. If the "-clean" option is specified, the journal file
is also removed. If no zone is specified, then all zones are
synced.
tcp-timeouts [initial idle keepalive advertised]
When called without arguments, display the current values of the
tcp-initial-timeout, tcp-idle-timeout, tcp-keepalive-timeout and
tcp-advertised-timeout options. When called with arguments, up-
date these values. This allows an administrator to make rapid
adjustments when under a denial of service attack. See the de-
scriptions of these options in the BIND 9 Administrator Refer-
ence Manual for details of their use.
thaw [zone [class [view]]]
Enable updates to a frozen dynamic zone. If no zone is speci-
fied, then all frozen zones are enabled. This causes the server
to reload the zone from disk, and re-enables dynamic updates af-
ter the load has completed. After a zone is thawed, dynamic up-
dates will no longer be refused. If the zone has changed and the
ixfr-from-differences option is in use, then the journal file
will be updated to reflect changes in the zone. Otherwise, if
the zone has changed, any existing journal file will be removed.
See also rndc freeze.
trace Increment the servers debugging level by one.
trace level
Sets the server's debugging level to an explicit value.
See also rndc notrace.
tsig-delete keyname [view]
Delete a given TKEY-negotiated key from the server. (This does
not apply to statically configured TSIG keys.)
tsig-list
List the names of all TSIG keys currently configured for use by
named(8) in each view. The list both statically configured keys
and dynamic TKEY-negotiated keys.
validation (on | off | status) [view ...]``
Enable, disable, or check the current status of DNSSEC valida-
tion. By default, validation is enabled.
The cache is flushed when validation is turned on or off to
avoid using data that might differ between states.
zonestatus zone [class [view]]
Displays the current status of the given zone, including the
master file name and any include files from which it was loaded,
when it was most recently loaded, the current serial number, the
number of nodes, whether the zone supports dynamic updates,
whether the zone is DNSSEC signed, whether it uses automatic
DNSSEC key management or inline signing, and the scheduled re-
fresh or expiry times for the zone.
See also rndc showzone.
rndc commands that specify zone names, such as reload, retransfer or
zonestatus, can be ambiguous when applied to zones of type redirect.
Redirect zones are always called ".", and can be confused with zones of
type hint or with slaved copies of the root zone. To specify a redirect
zone, use the special zone name -redirect, without a trailing period.
(With a trailing period, this would specify a zone called "-redirect".)
LIMITATIONS
There is currently no way to provide the shared secret for a key_id
without using the configuration file.
Several error messages could be clearer.
SEE ALSO
rndc.conf(5), rndc-confgen(8), named(8), named.conf(5), ndc(8), BIND 9
Administrator Reference Manual.
AUTHOR
Internet Systems Consortium
COPYRIGHT
2020, Internet Systems Consortium
9.16.8-Debian 2020-10-13 RNDC(8)