1RNDC(8) BIND 9 RNDC(8)
2
6 rndc - name server control utility
7
9 rndc [-b source-address] [-c config-file] [-k key-file] [-s server] [-p
10 port] [-q] [-r] [-V] [-y server_key] [[-4] | [-6]] {command}
11
13 rndc controls the operation of a name server. If rndc is invoked with
14 no command line options or arguments, it prints a short summary of the
15 supported commands and the available options and their arguments.
16 rndc communicates with the name server over a TCP connection, sending
18 commands authenticated with digital signatures. In the current versions
19 of rndc and named, the only supported authentication algorithms are
20 HMAC-MD5 (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256 (de‐
21 fault), HMAC-SHA384, and HMAC-SHA512. They use a shared secret on each
22 end of the connection, which provides TSIG-style authentication for the
23 command request and the name server's response. All commands sent over
24 the channel must be signed by a server_key known to the server.
25 rndc reads a configuration file to determine how to contact the name
27 server and decide what algorithm and key it should use.
28
30 -4 This option indicates use of IPv4 only.
31 -6 This option indicates use of IPv6 only.
33 -b source-address
35 This option indicates source-address as the source address for
36 the connection to the server. Multiple instances are permitted,
37 to allow setting of both the IPv4 and IPv6 source addresses.
38 -c config-file
40 This option indicates config-file as the configuration file in‐
41 stead of the default, /etc/rndc.conf.
42 -k key-file
44 This option indicates key-file as the key file instead of the
45 default, /etc/rndc.key. The key in /etc/rndc.key is used to au‐
46 thenticate commands sent to the server if the config-file does
47 not exist.
48 -s server
50 server is the name or address of the server which matches a
51 server statement in the configuration file for rndc. If no
52 server is supplied on the command line, the host named by the
53 default-server clause in the options statement of the rndc con‐
54 figuration file is used.
55 -p port
57 This option instructs BIND 9 to send commands to TCP port port
58 instead of its default control channel port, 953.
59 -q This option sets quiet mode, where message text returned by the
61 server is not printed unless there is an error.
62 -r This option instructs rndc to print the result code returned by
64 named after executing the requested command (e.g., ISC_R_SUC‐
65 CESS, ISC_R_FAILURE, etc.).
66 -V This option enables verbose logging.
68 -y server_key
70 This option indicates use of the key server_key from the config‐
71 uration file. For control message validation to succeed,
72 server_key must be known by named with the same algorithm and
73 secret string. If no server_key is specified, rndc first looks
74 for a key clause in the server statement of the server being
75 used, or if no server statement is present for that host, then
76 in the default-key clause of the options statement. Note that
77 the configuration file contains shared secrets which are used to
78 send authenticated control commands to name servers, and should
79 therefore not have general read or write access.
80
82 A list of commands supported by rndc can be seen by running rndc with‐
83 out arguments.
84 Currently supported commands are:
86 addzone zone [class [view]] configuration
88 This command adds a zone while the server is running. This com‐
89 mand requires the allow-new-zones option to be set to yes. The
90 configuration string specified on the command line is the zone
91 configuration text that would ordinarily be placed in
92 named.conf.
93 The configuration is saved in a file called viewname.nzf (or, if
95 named is compiled with liblmdb, an LMDB database file called
96 viewname.nzd). viewname is the name of the view, unless the view
97 name contains characters that are incompatible with use as a
98 file name, in which case a cryptographic hash of the view name
99 is used instead. When named is restarted, the file is loaded
100 into the view configuration so that zones that were added can
101 persist after a restart.
102 This sample addzone command adds the zone example.com to the de‐
104 fault view:
105 rndc addzone example.com '{ type primary; file "example.com.db";
107 };'
108 (Note the brackets around and semi-colon after the zone configu‐
110 ration text.)
111 See also rndc delzone and rndc modzone.
113 delzone [-clean] zone [class [view]]
115 This command deletes a zone while the server is running.
116 If the -clean argument is specified, the zone's master file (and
118 journal file, if any) are deleted along with the zone. Without
119 the -clean option, zone files must be deleted manually. (If the
120 zone is of type secondary or stub, the files needing to be re‐
121 moved are reported in the output of the rndc delzone command.)
122 If the zone was originally added via rndc addzone, then it is
124 removed permanently. However, if it was originally configured in
125 named.conf, then that original configuration remains in place;
126 when the server is restarted or reconfigured, the zone is recre‐
127 ated. To remove it permanently, it must also be removed from
128 named.conf.
129 See also rndc addzone and rndc modzone.
131 dnssec (-status | -rollover -key id [-alg algorithm] [-when time] |
133 -checkds [-key id [-alg algorithm]] [-when time] published | with‐
134 drawn)) zone [class [view]]
135 This command allows you to interact with the "dnssec-policy" of
136 a given zone.
137 rndc dnssec -status show the DNSSEC signing state for the speci‐
139 fied zone.
140 rndc dnssec -rollover allows you to schedule key rollover for a
142 specific key (overriding the original key lifetime).
143 rndc dnssec -checkds informs named that the DS for a specified
145 zone's key-signing key has been confirmed to be published in, or
146 withdrawn from, the parent zone. This is required in order to
147 complete a KSK rollover. The -key id and -alg algorithm argu‐
148 ments can be used to specify a particular KSK, if necessary; if
149 there is only one key acting as a KSK for the zone, these argu‐
150 ments can be omitted. The time of publication or withdrawal for
151 the DS is set to the current time by default, but can be over‐
152 ridden to a specific time with the argument -when time, where
153 time is expressed in YYYYMMDDHHMMSS notation.
154 dnstap (-reopen | -roll [number])
156 This command closes and re-opens DNSTAP output files. rndc
157 dnstap -reopen allows the output file to be renamed externally,
158 so that named can truncate and re-open it. rndc dnstap -roll
159 causes the output file to be rolled automatically, similar to
160 log files. The most recent output file has ".0" appended to its
161 name; the previous most recent output file is moved to ".1", and
162 so on. If number is specified, then the number of backup log
163 files is limited to that number.
164 dumpdb [-all | -cache | -zones | -adb | -bad | -expired | -fail] [view
166 ...]
167 This command dumps the server's caches (default) and/or zones to
168 the dump file for the specified views. If no view is specified,
169 all views are dumped. (See the dump-file option in the BIND 9
170 Administrator Reference Manual.)
171 flush This command flushes the server's cache.
173 flushname name [view]
175 This command flushes the given name from the view's DNS cache
176 and, if applicable, from the view's nameserver address database,
177 bad server cache, and SERVFAIL cache.
178 flushtree name [view]
180 This command flushes the given name, and all of its subdomains,
181 from the view's DNS cache, address database, bad server cache,
182 and SERVFAIL cache.
183 freeze [zone [class [view]]]
185 This command suspends updates to a dynamic zone. If no zone is
186 specified, then all zones are suspended. This allows manual ed‐
187 its to be made to a zone normally updated by dynamic update, and
188 causes changes in the journal file to be synced into the master
189 file. All dynamic update attempts are refused while the zone is
190 frozen.
191 See also rndc thaw.
193 halt [-p]
195 This command stops the server immediately. Recent changes made
196 through dynamic update or IXFR are not saved to the master
197 files, but are rolled forward from the journal files when the
198 server is restarted. If -p is specified, named's process ID is
199 returned. This allows an external process to determine when
200 named has completed halting.
201 See also rndc stop.
203 loadkeys [zone [class [view]]]
205 This command fetches all DNSSEC keys for the given zone from the
206 key directory. If they are within their publication period, they
207 are merged into the zone's DNSKEY RRset. Unlike rndc sign, how‐
208 ever, the zone is not immediately re-signed by the new keys, but
209 is allowed to incrementally re-sign over time.
210 This command requires that the zone be configured with a
212 dnssec-policy, or that the auto-dnssec zone option be set to
213 maintain, and also requires the zone to be configured to allow
214 dynamic DNS. (See "Dynamic Update Policies" in the Administrator
215 Reference Manual for more details.)
216 managed-keys (status | refresh | sync | destroy) [class [view]]
218 This command inspects and controls the "managed-keys" database
219 which handles RFC 5011 DNSSEC trust anchor maintenance. If a
220 view is specified, these commands are applied to that view; oth‐
221 erwise, they are applied to all views.
222 • When run with the status keyword, this prints the current sta‐
224 tus of the managed-keys database.
225 • When run with the refresh keyword, this forces an immediate
227 refresh query to be sent for all the managed keys, updating
228 the managed-keys database if any new keys are found, without
229 waiting the normal refresh interval.
230 • When run with the sync keyword, this forces an immediate dump
232 of the managed-keys database to disk (in the file man‐
233 aged-keys.bind or (viewname.mkeys). This synchronizes the
234 database with its journal file, so that the database's current
235 contents can be inspected visually.
236 • When run with the destroy keyword, the managed-keys database
238 is shut down and deleted, and all key maintenance is termi‐
239 nated. This command should be used only with extreme caution.
240 Existing keys that are already trusted are not deleted from
242 memory; DNSSEC validation can continue after this command is
243 used. However, key maintenance operations cease until named
244 is restarted or reconfigured, and all existing key maintenance
245 states are deleted.
246 Running rndc reconfig or restarting named immediately after
248 this command causes key maintenance to be reinitialized from
249 scratch, just as if the server were being started for the
250 first time. This is primarily intended for testing, but it may
251 also be used, for example, to jumpstart the acquisition of new
252 keys in the event of a trust anchor rollover, or as a
253 brute-force repair for key maintenance problems.
254 modzone zone [class [view]] configuration
256 This command modifies the configuration of a zone while the
257 server is running. This command requires the allow-new-zones op‐
258 tion to be set to yes. As with addzone, the configuration
259 string specified on the command line is the zone configuration
260 text that would ordinarily be placed in named.conf.
261 If the zone was originally added via rndc addzone, the configu‐
263 ration changes are recorded permanently and are still in effect
264 after the server is restarted or reconfigured. However, if it
265 was originally configured in named.conf, then that original con‐
266 figuration remains in place; when the server is restarted or re‐
267 configured, the zone reverts to its original configuration. To
268 make the changes permanent, it must also be modified in
269 named.conf.
270 See also rndc addzone and rndc delzone.
272 notify zone [class [view]]
274 This command resends NOTIFY messages for the zone.
275 notrace
277 This command sets the server's debugging level to 0.
278 See also rndc trace.
280 nta [(-class class | -dump | -force | -remove | -lifetime duration)]
282 domain [view]
283 This command sets a DNSSEC negative trust anchor (NTA) for do‐
284 main, with a lifetime of duration. The default lifetime is con‐
285 figured in named.conf via the nta-lifetime option, and defaults
286 to one hour. The lifetime cannot exceed one week.
287 A negative trust anchor selectively disables DNSSEC validation
289 for zones that are known to be failing because of misconfigura‐
290 tion rather than an attack. When data to be validated is at or
291 below an active NTA (and above any other configured trust an‐
292 chors), named aborts the DNSSEC validation process and treats
293 the data as insecure rather than bogus. This continues until the
294 NTA's lifetime has elapsed.
295 NTAs persist across restarts of the named server. The NTAs for a
297 view are saved in a file called name.nta, where name is the name
298 of the view; if it contains characters that are incompatible
299 with use as a file name, a cryptographic hash is generated from
300 the name of the view.
301 An existing NTA can be removed by using the -remove option.
303 An NTA's lifetime can be specified with the -lifetime option.
305 TTL-style suffixes can be used to specify the lifetime in sec‐
306 onds, minutes, or hours. If the specified NTA already exists,
307 its lifetime is updated to the new value. Setting lifetime to
308 zero is equivalent to -remove.
309 If -dump is used, any other arguments are ignored and a list of
311 existing NTAs is printed. Note that this may include NTAs that
312 are expired but have not yet been cleaned up.
313 Normally, named periodically tests to see whether data below an
315 NTA can now be validated (see the nta-recheck option in the Ad‐
316 ministrator Reference Manual for details). If data can be vali‐
317 dated, then the NTA is regarded as no longer necessary and is
318 allowed to expire early. The -force parameter overrides this be‐
319 havior and forces an NTA to persist for its entire lifetime, re‐
320 gardless of whether data could be validated if the NTA were not
321 present.
322 The view class can be specified with -class. The default is
324 class IN, which is the only class for which DNSSEC is currently
325 supported.
326 All of these options can be shortened, i.e., to -l, -r, -d, -f,
328 and -c.
329 Unrecognized options are treated as errors. To refer to a domain
331 or view name that begins with a hyphen, use a double-hyphen (--)
332 on the command line to indicate the end of options.
333 querylog [(on | off)]
335 This command enables or disables query logging. For backward
336 compatibility, this command can also be used without an argument
337 to toggle query logging on and off.
338 Query logging can also be enabled by explicitly directing the
340 queries category to a channel in the logging section of
341 named.conf, or by specifying querylog yes; in the options sec‐
342 tion of named.conf.
343 reconfig
345 This command reloads the configuration file and loads new zones,
346 but does not reload existing zone files even if they have
347 changed. This is faster than a full rndc reload when there is a
348 large number of zones, because it avoids the need to examine the
349 modification times of the zone files.
350 recursing
352 This command dumps the list of queries named is currently re‐
353 cursing on, and the list of domains to which iterative queries
354 are currently being sent.
355 The first list includes all unique clients that are waiting for
357 recursion to complete, including the query that is awaiting a
358 response and the timestamp (seconds since the Unix epoch) of
359 when named started processing this client query.
360 The second list comprises of domains for which there are active
362 (or recently active) fetches in progress. It reports the number
363 of active fetches for each domain and the number of queries that
364 have been passed (allowed) or dropped (spilled) as a result of
365 the fetches-per-zone limit. (Note: these counters are not cumu‐
366 lative over time; whenever the number of active fetches for a
367 domain drops to zero, the counter for that domain is deleted,
368 and the next time a fetch is sent to that domain, it is recre‐
369 ated with the counters set to zero).
370 refresh zone [class [view]]
372 This command schedules zone maintenance for the given zone.
373 reload This command reloads the configuration file and zones.
375 zone [class [view]]
377 If a zone is specified, this command reloads only the given
379 zone.
380 retransfer zone [class [view]]
382 This command retransfers the given secondary zone from the pri‐
383 mary server.
384 If the zone is configured to use inline-signing, the signed ver‐
386 sion of the zone is discarded; after the retransfer of the un‐
387 signed version is complete, the signed version is regenerated
388 with new signatures.
389 scan This command scans the list of available network interfaces for
391 changes, without performing a full rndc reconfig or waiting for
392 the interface-interval timer.
393 secroots [-] [view ...]
395 This command dumps the security roots (i.e., trust anchors con‐
396 figured via trust-anchors, or the managed-keys or trusted-keys
397 statements [both deprecated], or dnssec-validation auto) and
398 negative trust anchors for the specified views. If no view is
399 specified, all views are dumped. Security roots indicate whether
400 they are configured as trusted keys, managed keys, or initializ‐
401 ing managed keys (managed keys that have not yet been updated by
402 a successful key refresh query).
403 If the first argument is -, then the output is returned via the
405 rndc response channel and printed to the standard output. Oth‐
406 erwise, it is written to the secroots dump file, which defaults
407 to named.secroots, but can be overridden via the secroots-file
408 option in named.conf.
409 See also rndc managed-keys.
411 serve-stale (on | off | reset | status) [class [view]]
413 This command enables, disables, resets, or reports the current
414 status of the serving of stale answers as configured in
415 named.conf.
416 If serving of stale answers is disabled by rndc-serve-stale off,
418 then it remains disabled even if named is reloaded or reconfig‐
419 ured. rndc serve-stale reset restores the setting as configured
420 in named.conf.
421 rndc serve-stale status reports whether caching and serving of
423 stale answers is currently enabled or disabled. It also reports
424 the values of stale-answer-ttl and max-stale-ttl.
425 showzone zone [class [view]]
427 This command prints the configuration of a running zone.
428 See also rndc zonestatus.
430 sign zone [class [view]]
432 This command fetches all DNSSEC keys for the given zone from the
433 key directory (see the key-directory option in the BIND 9 Admin‐
434 istrator Reference Manual). If they are within their publication
435 period, they are merged into the zone's DNSKEY RRset. If the
436 DNSKEY RRset is changed, then the zone is automatically
437 re-signed with the new key set.
438 This command requires that the zone be configured with a
440 dnssec-policy, or that the auto-dnssec zone option be set to al‐
441 low or maintain, and also requires the zone to be configured to
442 allow dynamic DNS. (See "Dynamic Update Policies" in the BIND 9
443 Administrator Reference Manual for more details.)
444 See also rndc loadkeys.
446 signing [(-list | -clear keyid/algorithm | -clear all | -nsec3param
448 (parameters | none) | -serial value) zone [class [view]]
449 This command lists, edits, or removes the DNSSEC signing-state
450 records for the specified zone. The status of ongoing DNSSEC op‐
451 erations, such as signing or generating NSEC3 chains, is stored
452 in the zone in the form of DNS resource records of type
453 sig-signing-type. rndc signing -list converts these records
454 into a human-readable form, indicating which keys are currently
455 signing or have finished signing the zone, and which NSEC3
456 chains are being created or removed.
457 rndc signing -clear can remove a single key (specified in the
459 same format that rndc signing -list uses to display it), or all
460 keys. In either case, only completed keys are removed; any
461 record indicating that a key has not yet finished signing the
462 zone is retained.
463 rndc signing -nsec3param sets the NSEC3 parameters for a zone.
465 This is the only supported mechanism for using NSEC3 with in‐
466 line-signing zones. Parameters are specified in the same format
467 as an NSEC3PARAM resource record: hash algorithm, flags, itera‐
468 tions, and salt, in that order.
469 Currently, the only defined value for hash algorithm is 1, rep‐
471 resenting SHA-1. The flags may be set to 0 or 1, depending on
472 whether the opt-out bit in the NSEC3 chain should be set. itera‐
473 tions defines the number of additional times to apply the algo‐
474 rithm when generating an NSEC3 hash. The salt is a string of
475 data expressed in hexadecimal, a hyphen (-) if no salt is to be
476 used, or the keyword auto, which causes named to generate a ran‐
477 dom 64-bit salt.
478 The only recommended configuration is rndc signing -nsec3param 1
480 0 0 - zone, i.e. no salt, no additional iterations, no opt-out.
481 WARNING:
483 Do not use extra iterations, salt, or opt-out unless all
484 their implications are fully understood. A higher number of
485 iterations causes interoperability problems and opens servers
486 to CPU-exhausting DoS attacks.
487 rndc signing -nsec3param none removes an existing NSEC3 chain
489 and replaces it with NSEC.
490 rndc signing -serial value sets the serial number of the zone to
492 value. If the value would cause the serial number to go back‐
493 wards, it is rejected. The primary use of this parameter is to
494 set the serial number on inline signed zones.
495 stats This command writes server statistics to the statistics file.
497 (See the statistics-file option in the BIND 9 Administrator Ref‐
498 erence Manual.)
499 status This command displays the status of the server. Note that the
501 number of zones includes the internal bind/CH zone and the de‐
502 fault ./IN hint zone, if there is no explicit root zone config‐
503 ured.
504 stop -p
506 This command stops the server, making sure any recent changes
507 made through dynamic update or IXFR are first saved to the mas‐
508 ter files of the updated zones. If -p is specified, named's
509 process ID is returned. This allows an external process to de‐
510 termine when named has completed stopping.
511 See also rndc halt.
513 sync -clean [zone [class [view]]]
515 This command syncs changes in the journal file for a dynamic
516 zone to the master file. If the "-clean" option is specified,
517 the journal file is also removed. If no zone is specified, then
518 all zones are synced.
519 tcp-timeouts [initial idle keepalive advertised]
521 When called without arguments, this command displays the current
522 values of the tcp-initial-timeout, tcp-idle-timeout,
523 tcp-keepalive-timeout, and tcp-advertised-timeout options. When
524 called with arguments, these values are updated. This allows an
525 administrator to make rapid adjustments when under a de‐
526 nial-of-service (DoS) attack. See the descriptions of these op‐
527 tions in the BIND 9 Administrator Reference Manual for details
528 of their use.
529 thaw [zone [class [view]]]
531 This command enables updates to a frozen dynamic zone. If no
532 zone is specified, then all frozen zones are enabled. This
533 causes the server to reload the zone from disk, and re-enables
534 dynamic updates after the load has completed. After a zone is
535 thawed, dynamic updates are no longer refused. If the zone has
536 changed and the ixfr-from-differences option is in use, the
537 journal file is updated to reflect changes in the zone. Other‐
538 wise, if the zone has changed, any existing journal file is re‐
539 moved.
540 See also rndc freeze.
542 trace [level]
544 If no level is specified, this command increments the server's
545 debugging level by one.
546 level If specified, this command sets the server's debugging
548 level to the provided value.
549 See also rndc notrace.
551 tsig-delete keyname [view]
553 This command deletes a given TKEY-negotiated key from the
554 server. This does not apply to statically configured TSIG keys.
555 tsig-list
557 This command lists the names of all TSIG keys currently config‐
558 ured for use by named in each view. The list includes both stat‐
559 ically configured keys and dynamic TKEY-negotiated keys.
560 validation (on | off | status) [view ...]
562 This command enables, disables, or checks the current status of
563 DNSSEC validation. By default, validation is enabled.
564 The cache is flushed when validation is turned on or off to
566 avoid using data that might differ between states.
567 zonestatus zone [class [view]]
569 This command displays the current status of the given zone, in‐
570 cluding the master file name and any include files from which it
571 was loaded, when it was most recently loaded, the current serial
572 number, the number of nodes, whether the zone supports dynamic
573 updates, whether the zone is DNSSEC signed, whether it uses au‐
574 tomatic DNSSEC key management or inline signing, and the sched‐
575 uled refresh or expiry times for the zone.
576 See also rndc showzone.
578 rndc commands that specify zone names, such as reload retransfer, or
580 zonestatus, can be ambiguous when applied to zones of type redirect.
581 Redirect zones are always called ., and can be confused with zones of
582 type hint or with secondary copies of the root zone. To specify a redi‐
583 rect zone, use the special zone name -redirect, without a trailing pe‐
584 riod. (With a trailing period, this would specify a zone called "-redi‐
585 rect".)
586
588 There is currently no way to provide the shared secret for a server_key
589 without using the configuration file.
590 Several error messages could be clearer.
592
594 rndc.conf(5), rndc-confgen(8), named(8), named.conf(5), BIND 9 Adminis‐
595 trator Reference Manual.
596
598 Internet Systems Consortium
599
601 2023, Internet Systems Consortium
6029.18.11 RNDC(8)