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