2 - Copyright (C) 2004, 2005, 2007, 2013-2015 Internet Systems Consortium, Inc. ("ISC")
3 - Copyright (C) 2000, 2001 Internet Software Consortium.
5 - Permission to use, copy, modify, and/or distribute this software for any
6 - purpose with or without fee is hereby granted, provided that the above
7 - copyright notice and this permission notice appear in all copies.
9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 - PERFORMANCE OF THIS SOFTWARE.
19 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
23 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
24 <a name="man.rndc"></a><div class="titlepage"></div>
25 <div class="refnamediv">
27 <p><span class="application">rndc</span> — name server control utility</p>
29 <div class="refsynopsisdiv">
31 <div class="cmdsynopsis"><p><code class="command">rndc</code> [<code class="option">-b <em class="replaceable"><code>source-address</code></em></code>] [<code class="option">-c <em class="replaceable"><code>config-file</code></em></code>] [<code class="option">-k <em class="replaceable"><code>key-file</code></em></code>] [<code class="option">-s <em class="replaceable"><code>server</code></em></code>] [<code class="option">-p <em class="replaceable"><code>port</code></em></code>] [<code class="option">-V</code>] [<code class="option">-y <em class="replaceable"><code>key_id</code></em></code>] {command}</p></div>
33 <div class="refsection">
34 <a name="id-1.7"></a><h2>DESCRIPTION</h2>
35 <p><span class="command"><strong>rndc</strong></span>
36 controls the operation of a name
37 server. It supersedes the <span class="command"><strong>ndc</strong></span> utility
38 that was provided in old BIND releases. If
39 <span class="command"><strong>rndc</strong></span> is invoked with no command line
40 options or arguments, it prints a short summary of the
41 supported commands and the available options and their
44 <p><span class="command"><strong>rndc</strong></span>
45 communicates with the name server
46 over a TCP connection, sending commands authenticated with
47 digital signatures. In the current versions of
48 <span class="command"><strong>rndc</strong></span> and <span class="command"><strong>named</strong></span>,
49 the only supported authentication algorithm is HMAC-MD5,
50 which uses a shared secret on each end of the connection.
51 This provides TSIG-style authentication for the command
52 request and the name server's response. All commands sent
53 over the channel must be signed by a key_id known to the
56 <p><span class="command"><strong>rndc</strong></span>
57 reads a configuration file to
58 determine how to contact the name server and decide what
59 algorithm and key it should use.
62 <div class="refsection">
63 <a name="id-1.8"></a><h2>OPTIONS</h2>
64 <div class="variablelist"><dl class="variablelist">
65 <dt><span class="term">-b <em class="replaceable"><code>source-address</code></em></span></dt>
67 Use <em class="replaceable"><code>source-address</code></em>
68 as the source address for the connection to the server.
69 Multiple instances are permitted to allow setting of both
70 the IPv4 and IPv6 source addresses.
72 <dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt>
74 Use <em class="replaceable"><code>config-file</code></em>
75 as the configuration file instead of the default,
76 <code class="filename">/etc/rndc.conf</code>.
78 <dt><span class="term">-k <em class="replaceable"><code>key-file</code></em></span></dt>
80 Use <em class="replaceable"><code>key-file</code></em>
81 as the key file instead of the default,
82 <code class="filename">/etc/rndc.key</code>. The key in
83 <code class="filename">/etc/rndc.key</code> will be used to
85 commands sent to the server if the <em class="replaceable"><code>config-file</code></em>
88 <dt><span class="term">-s <em class="replaceable"><code>server</code></em></span></dt>
89 <dd><p><em class="replaceable"><code>server</code></em> is
90 the name or address of the server which matches a
91 server statement in the configuration file for
92 <span class="command"><strong>rndc</strong></span>. If no server is supplied on the
93 command line, the host named by the default-server clause
94 in the options statement of the <span class="command"><strong>rndc</strong></span>
95 configuration file will be used.
97 <dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt>
99 Send commands to TCP port
100 <em class="replaceable"><code>port</code></em>
102 of BIND 9's default control channel port, 953.
104 <dt><span class="term">-V</span></dt>
106 Enable verbose logging.
108 <dt><span class="term">-y <em class="replaceable"><code>key_id</code></em></span></dt>
110 Use the key <em class="replaceable"><code>key_id</code></em>
111 from the configuration file.
112 <em class="replaceable"><code>key_id</code></em>
114 known by <span class="command"><strong>named</strong></span> with the same algorithm and secret string
115 in order for control message validation to succeed.
116 If no <em class="replaceable"><code>key_id</code></em>
117 is specified, <span class="command"><strong>rndc</strong></span> will first look
118 for a key clause in the server statement of the server
119 being used, or if no server statement is present for that
120 host, then the default-key clause of the options statement.
121 Note that the configuration file contains shared secrets
122 which are used to send authenticated control commands
123 to name servers. It should therefore not have general read
128 <div class="refsection">
129 <a name="id-1.9"></a><h2>COMMANDS</h2>
131 A list of commands supported by <span class="command"><strong>rndc</strong></span> can
132 be seen by running <span class="command"><strong>rndc</strong></span> without arguments.
135 Currently supported commands are:
137 <div class="variablelist"><dl class="variablelist">
138 <dt><span class="term"><strong class="userinput"><code>addzone <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>] <em class="replaceable"><code>configuration</code></em> </code></strong></span></dt>
141 Add a zone while the server is running. This
143 <span class="command"><strong>allow-new-zones</strong></span> option to be set
144 to <strong class="userinput"><code>yes</code></strong>. The
145 <em class="replaceable"><code>configuration</code></em> string
146 specified on the command line is the zone
147 configuration text that would ordinarily be
148 placed in <code class="filename">named.conf</code>.
151 The configuration is saved in a file called
152 <code class="filename"><em class="replaceable"><code>hash</code></em>.nzf</code>,
153 where <em class="replaceable"><code>hash</code></em> is a
154 cryptographic hash generated from the name of
155 the view. When <span class="command"><strong>named</strong></span> is
156 restarted, the file will be loaded into the view
157 configuration, so that zones that were added
158 can persist after a restart.
161 This sample <span class="command"><strong>addzone</strong></span> command
162 would add the zone <code class="literal">example.com</code>
166 <code class="prompt">$ </code><strong class="userinput"><code>rndc addzone example.com '{ type master; file "example.com.db"; };'</code></strong>
169 (Note the brackets and semi-colon around the zone
173 See also <span class="command"><strong>rndc delzone</strong></span>.
176 <dt><span class="term"><strong class="userinput"><code>delzone <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>] </code></strong></span></dt>
179 Delete a zone while the server is running.
180 Only zones that were originally added via
181 <span class="command"><strong>rndc addzone</strong></span> can be deleted
185 See also <span class="command"><strong>rndc addzone</strong></span>
188 <dt><span class="term"><strong class="userinput"><code>dumpdb [<span class="optional">-all|-cache|-zone|-adb|-bad</span>] [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt>
190 Dump the server's caches (default) and/or zones to
192 dump file for the specified views. If no view is
195 (See the <span class="command"><strong>dump-file</strong></span> option in
196 the BIND 9 Administrator Reference Manual.)
198 <dt><span class="term"><strong class="userinput"><code>flush</code></strong></span></dt>
200 Flushes the server's cache.
202 <dt><span class="term"><strong class="userinput"><code>flushname</code></strong> <em class="replaceable"><code>name</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>] </span></dt>
204 Flushes the given name from the view's DNS cache
205 and, if applicable, from the view's nameserver address
206 database or bad-server cache.
208 <dt><span class="term"><strong class="userinput"><code>flushtree</code></strong> <em class="replaceable"><code>name</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>] </span></dt>
210 Flushes the given name, and all of its subdomains,
211 from the view's DNS cache. Note that this does
212 <span class="emphasis"><em>not</em></span> affect he server's address
213 database or bad-server cache.
215 <dt><span class="term"><strong class="userinput"><code>freeze [<span class="optional"><em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt>
218 Suspend updates to a dynamic zone. If no zone is
219 specified, then all zones are suspended. This allows
220 manual edits to be made to a zone normally updated by
221 dynamic update. It also causes changes in the
222 journal file to be synced into the master file.
223 All dynamic update attempts will be refused while
227 See also <span class="command"><strong>rndc thaw</strong></span>.
230 <dt><span class="term"><strong class="userinput"><code>halt [<span class="optional">-p</span>]</code></strong></span></dt>
233 Stop the server immediately. Recent changes
234 made through dynamic update or IXFR are not saved to
235 the master files, but will be rolled forward from the
236 journal files when the server is restarted.
237 If <code class="option">-p</code> is specified <span class="command"><strong>named</strong></span>'s process id is returned.
238 This allows an external process to determine when <span class="command"><strong>named</strong></span>
239 had completed halting.
242 See also <span class="command"><strong>rndc stop</strong></span>.
245 <dt><span class="term"><strong class="userinput"><code>loadkeys <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
248 Fetch all DNSSEC keys for the given zone
249 from the key directory. If they are within
250 their publication period, merge them into the
251 zone's DNSKEY RRset. Unlike <span class="command"><strong>rndc
252 sign</strong></span>, however, the zone is not
253 immediately re-signed by the new keys, but is
254 allowed to incrementally re-sign over time.
257 This command requires that the
258 <span class="command"><strong>auto-dnssec</strong></span> zone option
259 be set to <code class="literal">maintain</code>,
260 and also requires the zone to be configured to
262 (See "Dynamic Update Policies" in the Administrator
263 Reference Manual for more details.)
266 <dt><span class="term"><strong class="userinput"><code>notify <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
268 Resend NOTIFY messages for the zone.
270 <dt><span class="term"><strong class="userinput"><code>notrace</code></strong></span></dt>
273 Sets the server's debugging level to 0.
276 See also <span class="command"><strong>rndc trace</strong></span>.
279 <dt><span class="term"><strong class="userinput"><code>querylog</code></strong> [<span class="optional">on|off</span>] </span></dt>
282 Enable or disable query logging. (For backward
283 compatibility, this command can also be used without
284 an argument to toggle query logging on and off.)
287 Query logging can also be enabled
288 by explicitly directing the <span class="command"><strong>queries</strong></span>
289 <span class="command"><strong>category</strong></span> to a
290 <span class="command"><strong>channel</strong></span> in the
291 <span class="command"><strong>logging</strong></span> section of
292 <code class="filename">named.conf</code> or by specifying
293 <span class="command"><strong>querylog yes;</strong></span> in the
294 <span class="command"><strong>options</strong></span> section of
295 <code class="filename">named.conf</code>.
298 <dt><span class="term"><strong class="userinput"><code>reconfig</code></strong></span></dt>
300 Reload the configuration file and load new zones,
301 but do not reload existing zone files even if they
303 This is faster than a full <span class="command"><strong>reload</strong></span> when there
304 is a large number of zones because it avoids the need
306 modification times of the zones files.
308 <dt><span class="term"><strong class="userinput"><code>recursing</code></strong></span></dt>
310 Dump the list of queries <span class="command"><strong>named</strong></span> is currently
311 recursing on, and the list of domains to which iterative
312 queries are currently being sent. (The second list includes
313 the number of fetches currently active for the given domain,
314 and how many have been passed or dropped because of the
315 <code class="option">fetches-per-zone</code> option.)
317 <dt><span class="term"><strong class="userinput"><code>refresh <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
319 Schedule zone maintenance for the given zone.
321 <dt><span class="term"><strong class="userinput"><code>reload</code></strong></span></dt>
323 Reload configuration file and zones.
325 <dt><span class="term"><strong class="userinput"><code>reload <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
327 Reload the given zone.
329 <dt><span class="term"><strong class="userinput"><code>retransfer <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
332 Retransfer the given slave zone from the master server.
335 If the zone is configured to use
336 <span class="command"><strong>inline-signing</strong></span>, the signed
337 version of the zone is discarded; after the
338 retransfer of the unsigned version is complete, the
339 signed version will be regenerated with all new
343 <dt><span class="term"><strong class="userinput"><code>secroots [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt>
345 Dump the server's security roots to the secroots
346 file for the specified views. If no view is
347 specified, security roots for all
350 <dt><span class="term"><strong class="userinput"><code>sign <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</code></strong></span></dt>
353 Fetch all DNSSEC keys for the given zone
354 from the key directory (see the
355 <span class="command"><strong>key-directory</strong></span> option in
356 the BIND 9 Administrator Reference Manual). If they are within
357 their publication period, merge them into the
358 zone's DNSKEY RRset. If the DNSKEY RRset
359 is changed, then the zone is automatically
360 re-signed with the new key set.
363 This command requires that the
364 <span class="command"><strong>auto-dnssec</strong></span> zone option be set
365 to <code class="literal">allow</code> or
366 <code class="literal">maintain</code>,
367 and also requires the zone to be configured to
369 (See "Dynamic Update Policies" in the Administrator
370 Reference Manual for more details.)
373 See also <span class="command"><strong>rndc loadkeys</strong></span>.
376 <dt><span class="term"><strong class="userinput"><code>signing [<span class="optional">( -list | -clear <em class="replaceable"><code>keyid/algorithm</code></em> | -clear <code class="literal">all</code> | -nsec3param ( <em class="replaceable"><code>parameters</code></em> | <code class="literal">none</code> ) ) </span>] <em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>] </code></strong></span></dt>
379 List, edit, or remove the DNSSEC signing state records
380 for the specified zone. The status of ongoing DNSSEC
381 operations (such as signing or generating
382 NSEC3 chains) is stored in the zone in the form
383 of DNS resource records of type
384 <span class="command"><strong>sig-signing-type</strong></span>.
385 <span class="command"><strong>rndc signing -list</strong></span> converts
386 these records into a human-readable form,
387 indicating which keys are currently signing
388 or have finished signing the zone, and which NSEC3
389 chains are being created or removed.
392 <span class="command"><strong>rndc signing -clear</strong></span> can remove
393 a single key (specified in the same format that
394 <span class="command"><strong>rndc signing -list</strong></span> uses to
395 display it), or all keys. In either case, only
396 completed keys are removed; any record indicating
397 that a key has not yet finished signing the zone
401 <span class="command"><strong>rndc signing -nsec3param</strong></span> sets
402 the NSEC3 parameters for a zone. This is the
403 only supported mechanism for using NSEC3 with
404 <span class="command"><strong>inline-signing</strong></span> zones.
405 Parameters are specified in the same format as
406 an NSEC3PARAM resource record: hash algorithm,
407 flags, iterations, and salt, in that order.
410 Currently, the only defined value for hash algorithm
411 is <code class="literal">1</code>, representing SHA-1.
412 The <code class="option">flags</code> may be set to
413 <code class="literal">0</code> or <code class="literal">1</code>,
414 depending on whether you wish to set the opt-out
415 bit in the NSEC3 chain. <code class="option">iterations</code>
416 defines the number of additional times to apply
417 the algorithm when generating an NSEC3 hash. The
418 <code class="option">salt</code> is a string of data expressed
419 in hexadecimal, or a hyphen (`-') if no salt is
423 So, for example, to create an NSEC3 chain using
424 the SHA-1 hash algorithm, no opt-out flag,
425 10 iterations, and a salt value of "FFFF", use:
426 <span class="command"><strong>rndc signing -nsec3param 1 0 10 FFFF <em class="replaceable"><code>zone</code></em></strong></span>.
427 To set the opt-out flag, 15 iterations, and no
429 <span class="command"><strong>rndc signing -nsec3param 1 1 15 - <em class="replaceable"><code>zone</code></em></strong></span>.
432 <span class="command"><strong>rndc signing -nsec3param none</strong></span>
433 removes an existing NSEC3 chain and replaces it
437 <dt><span class="term"><strong class="userinput"><code>stats</code></strong></span></dt>
439 Write server statistics to the statistics file.
440 (See the <span class="command"><strong>statistics-file</strong></span> option in
441 the BIND 9 Administrator Reference Manual.)
443 <dt><span class="term"><strong class="userinput"><code>status</code></strong></span></dt>
445 Display status of the server.
446 Note that the number of zones includes the internal <span class="command"><strong>bind/CH</strong></span> zone
447 and the default <span class="command"><strong>./IN</strong></span>
448 hint zone if there is not an
449 explicit root zone configured.
451 <dt><span class="term"><strong class="userinput"><code>stop [<span class="optional">-p</span>]</code></strong></span></dt>
454 Stop the server, making sure any recent changes
455 made through dynamic update or IXFR are first saved to
456 the master files of the updated zones.
457 If <code class="option">-p</code> is specified <span class="command"><strong>named</strong></span>'s process id is returned.
458 This allows an external process to determine when <span class="command"><strong>named</strong></span>
459 had completed stopping.
461 <p>See also <span class="command"><strong>rndc halt</strong></span>.</p>
463 <dt><span class="term"><strong class="userinput"><code>sync [<span class="optional">-clean</span>] [<span class="optional"><em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt>
465 Sync changes in the journal file for a dynamic zone
466 to the master file. If the "-clean" option is
467 specified, the journal file is also removed. If
468 no zone is specified, then all zones are synced.
470 <dt><span class="term"><strong class="userinput"><code>thaw [<span class="optional"><em class="replaceable"><code>zone</code></em> [<span class="optional"><em class="replaceable"><code>class</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span>]</span>]</code></strong></span></dt>
473 Enable updates to a frozen dynamic zone. If no
474 zone is specified, then all frozen zones are
475 enabled. This causes the server to reload the zone
476 from disk, and re-enables dynamic updates after the
477 load has completed. After a zone is thawed,
478 dynamic updates will no longer be refused. If
479 the zone has changed and the
480 <span class="command"><strong>ixfr-from-differences</strong></span> option is
481 in use, then the journal file will be updated to
482 reflect changes in the zone. Otherwise, if the
483 zone has changed, any existing journal file will be
486 <p>See also <span class="command"><strong>rndc freeze</strong></span>.</p>
488 <dt><span class="term"><strong class="userinput"><code>trace</code></strong></span></dt>
490 Increment the servers debugging level by one.
492 <dt><span class="term"><strong class="userinput"><code>trace <em class="replaceable"><code>level</code></em></code></strong></span></dt>
495 Sets the server's debugging level to an explicit
499 See also <span class="command"><strong>rndc notrace</strong></span>.
502 <dt><span class="term"><strong class="userinput"><code>tsig-delete</code></strong> <em class="replaceable"><code>keyname</code></em> [<span class="optional"><em class="replaceable"><code>view</code></em></span>]</span></dt>
504 Delete a given TKEY-negotiated key from the server.
505 (This does not apply to statically configured TSIG
508 <dt><span class="term"><strong class="userinput"><code>tsig-list</code></strong></span></dt>
510 List the names of all TSIG keys currently configured
511 for use by <span class="command"><strong>named</strong></span> in each view. The
512 list both statically configured keys and dynamic
513 TKEY-negotiated keys.
515 <dt><span class="term"><strong class="userinput"><code>validation ( on | off | check ) [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>] </code></strong></span></dt>
517 Enable, disable, or check the current status of
519 Note <span class="command"><strong>dnssec-enable</strong></span> also needs to be
520 set to <strong class="userinput"><code>yes</code></strong> or
521 <strong class="userinput"><code>auto</code></strong> to be effective.
522 It defaults to enabled.
526 <div class="refsection">
527 <a name="id-1.10"></a><h2>LIMITATIONS</h2>
529 There is currently no way to provide the shared secret for a
530 <code class="option">key_id</code> without using the configuration file.
533 Several error messages could be clearer.
536 <div class="refsection">
537 <a name="id-1.11"></a><h2>SEE ALSO</h2>
538 <p><span class="citerefentry"><span class="refentrytitle">rndc.conf</span>(5)</span>,
539 <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
540 <span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
541 <span class="citerefentry"><span class="refentrytitle">named.conf</span>(5)</span>,
542 <span class="citerefentry"><span class="refentrytitle">ndc</span>(8)</span>,
543 <em class="citetitle">BIND 9 Administrator Reference Manual</em>.