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.
157 rndc dnstap -reopen allows the output file to be renamed exter‐
159 nally, so that named can truncate and re-open it.
160 rndc dnstap -roll causes the output file to be rolled automati‐
162 cally, similar to log files. The most recent output file has
163 ".0" appended to its name; the previous most recent output file
164 is moved to ".1", and so on. If number is specified, then the
165 number of backup log files is limited to that number.
166 dumpdb [-all | -cache | -zones | -adb | -bad | -expired | -fail] [view
168 ...]
169 This command dumps the server's caches (default) and/or zones to
170 the dump file for the specified views. If no view is specified,
171 all views are dumped. (See the dump-file option in the BIND 9
172 Administrator Reference Manual.)
173 flush This command flushes the server's cache.
175 flushname name [view]
177 This command flushes the given name from the view's DNS cache
178 and, if applicable, from the view's nameserver address database,
179 bad server cache, and SERVFAIL cache.
180 flushtree name [view]
182 This command flushes the given name, and all of its subdomains,
183 from the view's DNS cache, address database, bad server cache,
184 and SERVFAIL cache.
185 freeze [zone [class [view]]]
187 This command suspends updates to a dynamic zone. If no zone is
188 specified, then all zones are suspended. This allows manual ed‐
189 its to be made to a zone normally updated by dynamic update, and
190 causes changes in the journal file to be synced into the master
191 file. All dynamic update attempts are refused while the zone is
192 frozen.
193 See also rndc thaw.
195 halt [-p]
197 This command stops the server immediately. Recent changes made
198 through dynamic update or IXFR are not saved to the master
199 files, but are rolled forward from the journal files when the
200 server is restarted. If -p is specified, named's process ID is
201 returned. This allows an external process to determine when
202 named has completed halting.
203 See also rndc stop.
205 loadkeys [zone [class [view]]]
207 This command fetches all DNSSEC keys for the given zone from the
208 key directory. If they are within their publication period, they
209 are merged into the zone's DNSKEY RRset. Unlike rndc sign, how‐
210 ever, the zone is not immediately re-signed by the new keys, but
211 is allowed to incrementally re-sign over time.
212 This command requires that the zone be configured with a
214 dnssec-policy, or that the auto-dnssec zone option be set to
215 maintain, and also requires the zone to be configured to allow
216 dynamic DNS. (See "Dynamic Update Policies" in the Administrator
217 Reference Manual for more details.)
218 managed-keys (status | refresh | sync | destroy) [class [view]]
220 This command inspects and controls the "managed-keys" database
221 which handles RFC 5011 DNSSEC trust anchor maintenance. If a
222 view is specified, these commands are applied to that view; oth‐
223 erwise, they are applied to all views.
224 • When run with the status keyword, this prints the current sta‐
226 tus of the managed-keys database.
227 • When run with the refresh keyword, this forces an immediate
229 refresh query to be sent for all the managed keys, updating
230 the managed-keys database if any new keys are found, without
231 waiting the normal refresh interval.
232 • When run with the sync keyword, this forces an immediate dump
234 of the managed-keys database to disk (in the file man‐
235 aged-keys.bind or (viewname.mkeys). This synchronizes the
236 database with its journal file, so that the database's current
237 contents can be inspected visually.
238 • When run with the destroy keyword, the managed-keys database
240 is shut down and deleted, and all key maintenance is termi‐
241 nated. This command should be used only with extreme caution.
242 Existing keys that are already trusted are not deleted from
244 memory; DNSSEC validation can continue after this command is
245 used. However, key maintenance operations cease until named
246 is restarted or reconfigured, and all existing key maintenance
247 states are deleted.
248 Running rndc reconfig or restarting named immediately after
250 this command causes key maintenance to be reinitialized from
251 scratch, just as if the server were being started for the
252 first time. This is primarily intended for testing, but it may
253 also be used, for example, to jumpstart the acquisition of new
254 keys in the event of a trust anchor rollover, or as a
255 brute-force repair for key maintenance problems.
256 modzone zone [class [view]] configuration
258 This command modifies the configuration of a zone while the
259 server is running. This command requires the allow-new-zones op‐
260 tion to be set to yes. As with addzone, the configuration
261 string specified on the command line is the zone configuration
262 text that would ordinarily be placed in named.conf.
263 If the zone was originally added via rndc addzone, the configu‐
265 ration changes are recorded permanently and are still in effect
266 after the server is restarted or reconfigured. However, if it
267 was originally configured in named.conf, then that original con‐
268 figuration remains in place; when the server is restarted or re‐
269 configured, the zone reverts to its original configuration. To
270 make the changes permanent, it must also be modified in
271 named.conf.
272 See also rndc addzone and rndc delzone.
274 notify zone [class [view]]
276 This command resends NOTIFY messages for the zone.
277 notrace
279 This command sets the server's debugging level to 0.
280 See also rndc trace.
282 nta [(-class class | -dump | -force | -remove | -lifetime duration)]
284 domain [view]
285 This command sets a DNSSEC negative trust anchor (NTA) for do‐
286 main, with a lifetime of duration. The default lifetime is con‐
287 figured in named.conf via the nta-lifetime option, and defaults
288 to one hour. The lifetime cannot exceed one week.
289 A negative trust anchor selectively disables DNSSEC validation
291 for zones that are known to be failing because of misconfigura‐
292 tion rather than an attack. When data to be validated is at or
293 below an active NTA (and above any other configured trust an‐
294 chors), named aborts the DNSSEC validation process and treats
295 the data as insecure rather than bogus. This continues until the
296 NTA's lifetime has elapsed.
297 NTAs persist across restarts of the named server. The NTAs for a
299 view are saved in a file called name.nta, where name is the name
300 of the view; if it contains characters that are incompatible
301 with use as a file name, a cryptographic hash is generated from
302 the name of the view.
303 An existing NTA can be removed by using the -remove option.
305 An NTA's lifetime can be specified with the -lifetime option.
307 TTL-style suffixes can be used to specify the lifetime in sec‐
308 onds, minutes, or hours. If the specified NTA already exists,
309 its lifetime is updated to the new value. Setting lifetime to
310 zero is equivalent to -remove.
311 If -dump is used, any other arguments are ignored and a list of
313 existing NTAs is printed. Note that this may include NTAs that
314 are expired but have not yet been cleaned up.
315 Normally, named periodically tests to see whether data below an
317 NTA can now be validated (see the nta-recheck option in the Ad‐
318 ministrator Reference Manual for details). If data can be vali‐
319 dated, then the NTA is regarded as no longer necessary and is
320 allowed to expire early. The -force parameter overrides this be‐
321 havior and forces an NTA to persist for its entire lifetime, re‐
322 gardless of whether data could be validated if the NTA were not
323 present.
324 The view class can be specified with -class. The default is
326 class IN, which is the only class for which DNSSEC is currently
327 supported.
328 All of these options can be shortened, i.e., to -l, -r, -d, -f,
330 and -c.
331 Unrecognized options are treated as errors. To refer to a domain
333 or view name that begins with a hyphen, use a double-hyphen (--)
334 on the command line to indicate the end of options.
335 querylog [(on | off)]
337 This command enables or disables query logging. For backward
338 compatibility, this command can also be used without an argument
339 to toggle query logging on and off.
340 Query logging can also be enabled by explicitly directing the
342 queries category to a channel in the logging section of
343 named.conf, or by specifying querylog yes; in the options sec‐
344 tion of named.conf.
345 reconfig
347 This command reloads the configuration file and loads new zones,
348 but does not reload existing zone files even if they have
349 changed. This is faster than a full rndc reload when there is a
350 large number of zones, because it avoids the need to examine the
351 modification times of the zone files.
352 recursing
354 This command dumps the list of queries named is currently re‐
355 cursing on, and the list of domains to which iterative queries
356 are currently being sent.
357 The first list includes all unique clients that are waiting for
359 recursion to complete, including the query that is awaiting a
360 response and the timestamp (seconds since the Unix epoch) of
361 when named started processing this client query.
362 The second list comprises of domains for which there are active
364 (or recently active) fetches in progress. It reports the number
365 of active fetches for each domain and the number of queries that
366 have been passed (allowed) or dropped (spilled) as a result of
367 the fetches-per-zone limit. (Note: these counters are not cumu‐
368 lative over time; whenever the number of active fetches for a
369 domain drops to zero, the counter for that domain is deleted,
370 and the next time a fetch is sent to that domain, it is recre‐
371 ated with the counters set to zero).
372 refresh zone [class [view]]
374 This command schedules zone maintenance for the given zone.
375 reload This command reloads the configuration file and zones.
377 zone [class [view]]
379 If a zone is specified, this command reloads only the given
381 zone. If no zone is specified, the reloading happens asyn‐
382 chronously.
383 retransfer zone [class [view]]
385 This command retransfers the given secondary zone from the pri‐
386 mary server.
387 If the zone is configured to use inline-signing, the signed ver‐
389 sion of the zone is discarded; after the retransfer of the un‐
390 signed version is complete, the signed version is regenerated
391 with new signatures.
392 scan This command scans the list of available network interfaces for
394 changes, without performing a full rndc reconfig or waiting for
395 the interface-interval timer.
396 secroots [-] [view ...]
398 This command dumps the security roots (i.e., trust anchors con‐
399 figured via trust-anchors, or the managed-keys or trusted-keys
400 statements [both deprecated], or dnssec-validation auto) and
401 negative trust anchors for the specified views. If no view is
402 specified, all views are dumped. Security roots indicate whether
403 they are configured as trusted keys, managed keys, or initializ‐
404 ing managed keys (managed keys that have not yet been updated by
405 a successful key refresh query).
406 If the first argument is -, then the output is returned via the
408 rndc response channel and printed to the standard output. Oth‐
409 erwise, it is written to the secroots dump file, which defaults
410 to named.secroots, but can be overridden via the secroots-file
411 option in named.conf.
412 See also rndc managed-keys.
414 serve-stale (on | off | reset | status) [class [view]]
416 This command enables, disables, resets, or reports the current
417 status of the serving of stale answers as configured in
418 named.conf.
419 If serving of stale answers is disabled by rndc-serve-stale off,
421 then it remains disabled even if named is reloaded or reconfig‐
422 ured. rndc serve-stale reset restores the setting as configured
423 in named.conf.
424 rndc serve-stale status reports whether caching and serving of
426 stale answers is currently enabled or disabled. It also reports
427 the values of stale-answer-ttl and max-stale-ttl.
428 showzone zone [class [view]]
430 This command prints the configuration of a running zone.
431 See also rndc zonestatus.
433 sign zone [class [view]]
435 This command fetches all DNSSEC keys for the given zone from the
436 key directory (see the key-directory option in the BIND 9 Admin‐
437 istrator Reference Manual). If they are within their publication
438 period, they are merged into the zone's DNSKEY RRset. If the
439 DNSKEY RRset is changed, then the zone is automatically
440 re-signed with the new key set.
441 This command requires that the zone be configured with a
443 dnssec-policy, or that the auto-dnssec zone option be set to al‐
444 low or maintain, and also requires the zone to be configured to
445 allow dynamic DNS. (See "Dynamic Update Policies" in the BIND 9
446 Administrator Reference Manual for more details.)
447 See also rndc loadkeys.
449 signing [(-list | -clear keyid/algorithm | -clear all | -nsec3param
451 (parameters | none) | -serial value) zone [class [view]]
452 This command lists, edits, or removes the DNSSEC signing-state
453 records for the specified zone. The status of ongoing DNSSEC op‐
454 erations, such as signing or generating NSEC3 chains, is stored
455 in the zone in the form of DNS resource records of type
456 sig-signing-type. rndc signing -list converts these records
457 into a human-readable form, indicating which keys are currently
458 signing or have finished signing the zone, and which NSEC3
459 chains are being created or removed.
460 rndc signing -clear can remove a single key (specified in the
462 same format that rndc signing -list uses to display it), or all
463 keys. In either case, only completed keys are removed; any
464 record indicating that a key has not yet finished signing the
465 zone is retained.
466 rndc signing -nsec3param sets the NSEC3 parameters for a zone.
468 This is the only supported mechanism for using NSEC3 with in‐
469 line-signing zones. Parameters are specified in the same format
470 as an NSEC3PARAM resource record: hash algorithm, flags, itera‐
471 tions, and salt, in that order.
472 Currently, the only defined value for hash algorithm is 1, rep‐
474 resenting SHA-1. The flags may be set to 0 or 1, depending on
475 whether the opt-out bit in the NSEC3 chain should be set. itera‐
476 tions defines the number of additional times to apply the algo‐
477 rithm when generating an NSEC3 hash. The salt is a string of
478 data expressed in hexadecimal, a hyphen (-) if no salt is to be
479 used, or the keyword auto, which causes named to generate a ran‐
480 dom 64-bit salt.
481 The only recommended configuration is rndc signing -nsec3param 1
483 0 0 - zone, i.e. no salt, no additional iterations, no opt-out.
484 WARNING:
486 Do not use extra iterations, salt, or opt-out unless all
487 their implications are fully understood. A higher number of
488 iterations causes interoperability problems and opens servers
489 to CPU-exhausting DoS attacks.
490 rndc signing -nsec3param none removes an existing NSEC3 chain
492 and replaces it with NSEC.
493 rndc signing -serial value sets the serial number of the zone to
495 value. If the value would cause the serial number to go back‐
496 wards, it is rejected. The primary use of this parameter is to
497 set the serial number on inline signed zones.
498 stats This command writes server statistics to the statistics file.
500 (See the statistics-file option in the BIND 9 Administrator Ref‐
501 erence Manual.)
502 status This command displays the status of the server. Note that the
504 number of zones includes the internal bind/CH zone and the de‐
505 fault ./IN hint zone, if there is no explicit root zone config‐
506 ured.
507 stop -p
509 This command stops the server, making sure any recent changes
510 made through dynamic update or IXFR are first saved to the mas‐
511 ter files of the updated zones. If -p is specified, named's
512 process ID is returned. This allows an external process to de‐
513 termine when named has completed stopping.
514 See also rndc halt.
516 sync -clean [zone [class [view]]]
518 This command syncs changes in the journal file for a dynamic
519 zone to the master file. If the "-clean" option is specified,
520 the journal file is also removed. If no zone is specified, then
521 all zones are synced.
522 tcp-timeouts [initial idle keepalive advertised]
524 When called without arguments, this command displays the current
525 values of the tcp-initial-timeout, tcp-idle-timeout,
526 tcp-keepalive-timeout, and tcp-advertised-timeout options. When
527 called with arguments, these values are updated. This allows an
528 administrator to make rapid adjustments when under a de‐
529 nial-of-service (DoS) attack. See the descriptions of these op‐
530 tions in the BIND 9 Administrator Reference Manual for details
531 of their use.
532 thaw [zone [class [view]]]
534 This command enables updates to a frozen dynamic zone. If no
535 zone is specified, then all frozen zones are enabled. This
536 causes the server to reload the zone from disk, and re-enables
537 dynamic updates after the load has completed. After a zone is
538 thawed, dynamic updates are no longer refused. If the zone has
539 changed and the ixfr-from-differences option is in use, the
540 journal file is updated to reflect changes in the zone. Other‐
541 wise, if the zone has changed, any existing journal file is re‐
542 moved. If no zone is specified, the reloading happens asyn‐
543 chronously.
544 See also rndc freeze.
546 trace [level]
548 If no level is specified, this command increments the server's
549 debugging level by one.
550 level If specified, this command sets the server's debugging
552 level to the provided value.
553 See also rndc notrace.
555 tsig-delete keyname [view]
557 This command deletes a given TKEY-negotiated key from the
558 server. This does not apply to statically configured TSIG keys.
559 tsig-list
561 This command lists the names of all TSIG keys currently config‐
562 ured for use by named in each view. The list includes both stat‐
563 ically configured keys and dynamic TKEY-negotiated keys.
564 validation (on | off | status) [view ...]
566 This command enables, disables, or checks the current status of
567 DNSSEC validation. By default, validation is enabled.
568 The cache is flushed when validation is turned on or off to
570 avoid using data that might differ between states.
571 zonestatus zone [class [view]]
573 This command displays the current status of the given zone, in‐
574 cluding the master file name and any include files from which it
575 was loaded, when it was most recently loaded, the current serial
576 number, the number of nodes, whether the zone supports dynamic
577 updates, whether the zone is DNSSEC signed, whether it uses au‐
578 tomatic DNSSEC key management or inline signing, and the sched‐
579 uled refresh or expiry times for the zone.
580 See also rndc showzone.
582 rndc commands that specify zone names, such as reload retransfer, or
584 zonestatus, can be ambiguous when applied to zones of type redirect.
585 Redirect zones are always called ., and can be confused with zones of
586 type hint or with secondary copies of the root zone. To specify a redi‐
587 rect zone, use the special zone name -redirect, without a trailing pe‐
588 riod. (With a trailing period, this would specify a zone called "-redi‐
589 rect".)
590
592 There is currently no way to provide the shared secret for a server_key
593 without using the configuration file.
594 Several error messages could be clearer.
596
598 rndc.conf(5), rndc-confgen(8), named(8), named.conf(5), BIND 9 Adminis‐
599 trator Reference Manual.
600
602 Internet Systems Consortium
603
605 2023, Internet Systems Consortium
6069.18.20 RNDC(8)