2 - Copyright (C) 2004, 2005, 2007, 2013 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.
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="man.rndc"></a><div class="titlepage"></div>
26 <div class="refnamediv">
28 <p><span class="application">rndc</span> — name server control utility</p>
30 <div class="refsynopsisdiv">
32 <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>
34 <div class="refsect1" lang="en">
35 <a name="id2543418"></a><h2>DESCRIPTION</h2>
36 <p><span><strong class="command">rndc</strong></span>
37 controls the operation of a name
38 server. It supersedes the <span><strong class="command">ndc</strong></span> utility
39 that was provided in old BIND releases. If
40 <span><strong class="command">rndc</strong></span> is invoked with no command line
41 options or arguments, it prints a short summary of the
42 supported commands and the available options and their
45 <p><span><strong class="command">rndc</strong></span>
46 communicates with the name server
47 over a TCP connection, sending commands authenticated with
48 digital signatures. In the current versions of
49 <span><strong class="command">rndc</strong></span> and <span><strong class="command">named</strong></span>,
50 the only supported authentication algorithm is HMAC-MD5,
51 which uses a shared secret on each end of the connection.
52 This provides TSIG-style authentication for the command
53 request and the name server's response. All commands sent
54 over the channel must be signed by a key_id known to the
57 <p><span><strong class="command">rndc</strong></span>
58 reads a configuration file to
59 determine how to contact the name server and decide what
60 algorithm and key it should use.
63 <div class="refsect1" lang="en">
64 <a name="id2543453"></a><h2>OPTIONS</h2>
65 <div class="variablelist"><dl>
66 <dt><span class="term">-b <em class="replaceable"><code>source-address</code></em></span></dt>
68 Use <em class="replaceable"><code>source-address</code></em>
69 as the source address for the connection to the server.
70 Multiple instances are permitted to allow setting of both
71 the IPv4 and IPv6 source addresses.
73 <dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt>
75 Use <em class="replaceable"><code>config-file</code></em>
76 as the configuration file instead of the default,
77 <code class="filename">/etc/rndc.conf</code>.
79 <dt><span class="term">-k <em class="replaceable"><code>key-file</code></em></span></dt>
81 Use <em class="replaceable"><code>key-file</code></em>
82 as the key file instead of the default,
83 <code class="filename">/etc/rndc.key</code>. The key in
84 <code class="filename">/etc/rndc.key</code> will be used to
86 commands sent to the server if the <em class="replaceable"><code>config-file</code></em>
89 <dt><span class="term">-s <em class="replaceable"><code>server</code></em></span></dt>
90 <dd><p><em class="replaceable"><code>server</code></em> is
91 the name or address of the server which matches a
92 server statement in the configuration file for
93 <span><strong class="command">rndc</strong></span>. If no server is supplied on the
94 command line, the host named by the default-server clause
95 in the options statement of the <span><strong class="command">rndc</strong></span>
96 configuration file will be used.
98 <dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt>
100 Send commands to TCP port
101 <em class="replaceable"><code>port</code></em>
103 of BIND 9's default control channel port, 953.
105 <dt><span class="term">-V</span></dt>
107 Enable verbose logging.
109 <dt><span class="term">-y <em class="replaceable"><code>key_id</code></em></span></dt>
111 Use the key <em class="replaceable"><code>key_id</code></em>
112 from the configuration file.
113 <em class="replaceable"><code>key_id</code></em>
115 known by named with the same algorithm and secret string
116 in order for control message validation to succeed.
117 If no <em class="replaceable"><code>key_id</code></em>
118 is specified, <span><strong class="command">rndc</strong></span> will first look
119 for a key clause in the server statement of the server
120 being used, or if no server statement is present for that
121 host, then the default-key clause of the options statement.
122 Note that the configuration file contains shared secrets
123 which are used to send authenticated control commands
124 to name servers. It should therefore not have general read
129 <div class="refsect1" lang="en">
130 <a name="id2543650"></a><h2>COMMANDS</h2>
132 A list of commands supported by <span><strong class="command">rndc</strong></span> can
133 be seen by running <span><strong class="command">rndc</strong></span> without arguments.
136 Currently supported commands are:
138 <div class="variablelist"><dl>
139 <dt><span class="term"><strong class="userinput"><code>reload</code></strong></span></dt>
141 Reload configuration file and zones.
143 <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>
145 Reload the given zone.
147 <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>
149 Schedule zone maintenance for the given zone.
151 <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>
154 Retransfer the given slave zone from the master server.
157 If the zone is configured to use
158 <span><strong class="command">inline-signing</strong></span>, the signed
159 version of the zone is discarded; after the
160 retransfer of the unsigned version is complete, the
161 signed version will be regenerated with all new
165 <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>
168 Fetch all DNSSEC keys for the given zone
169 from the key directory (see the
170 <span><strong class="command">key-directory</strong></span> option in
171 the BIND 9 Administrator Reference Manual). If they are within
172 their publication period, merge them into the
173 zone's DNSKEY RRset. If the DNSKEY RRset
174 is changed, then the zone is automatically
175 re-signed with the new key set.
178 This command requires that the
179 <span><strong class="command">auto-dnssec</strong></span> zone option be set
180 to <code class="literal">allow</code> or
181 <code class="literal">maintain</code>,
182 and also requires the zone to be configured to
184 (See "Dynamic Update Policies" in the Administrator
185 Reference Manual for more details.)
188 <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>
191 Fetch all DNSSEC keys for the given zone
192 from the key directory. If they are within
193 their publication period, merge them into the
194 zone's DNSKEY RRset. Unlike <span><strong class="command">rndc
195 sign</strong></span>, however, the zone is not
196 immediately re-signed by the new keys, but is
197 allowed to incrementally re-sign over time.
200 This command requires that the
201 <span><strong class="command">auto-dnssec</strong></span> zone option
202 be set to <code class="literal">maintain</code>,
203 and also requires the zone to be configured to
205 (See "Dynamic Update Policies" in the Administrator
206 Reference Manual for more details.)
209 <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>
211 Suspend updates to a dynamic zone. If no zone is
212 specified, then all zones are suspended. This allows
213 manual edits to be made to a zone normally updated by
214 dynamic update. It also causes changes in the
215 journal file to be synced into the master file.
216 All dynamic update attempts will be refused while
219 <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>
221 Enable updates to a frozen dynamic zone. If no
222 zone is specified, then all frozen zones are
223 enabled. This causes the server to reload the zone
224 from disk, and re-enables dynamic updates after the
225 load has completed. After a zone is thawed,
226 dynamic updates will no longer be refused. If
227 the zone has changed and the
228 <span><strong class="command">ixfr-from-differences</strong></span> option is
229 in use, then the journal file will be updated to
230 reflect changes in the zone. Otherwise, if the
231 zone has changed, any existing journal file will be
234 <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>
236 Sync changes in the journal file for a dynamic zone
237 to the master file. If the "-clean" option is
238 specified, the journal file is also removed. If
239 no zone is specified, then all zones are synced.
241 <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>
243 Resend NOTIFY messages for the zone.
245 <dt><span class="term"><strong class="userinput"><code>reconfig</code></strong></span></dt>
247 Reload the configuration file and load new zones,
248 but do not reload existing zone files even if they
250 This is faster than a full <span><strong class="command">reload</strong></span> when there
251 is a large number of zones because it avoids the need
253 modification times of the zones files.
255 <dt><span class="term"><strong class="userinput"><code>stats</code></strong></span></dt>
257 Write server statistics to the statistics file.
259 <dt><span class="term"><strong class="userinput"><code>querylog</code></strong> [<span class="optional">on|off</span>] </span></dt>
262 Enable or disable query logging. (For backward
263 compatibility, this command can also be used without
264 an argument to toggle query logging on and off.)
267 Query logging can also be enabled
268 by explicitly directing the <span><strong class="command">queries</strong></span>
269 <span><strong class="command">category</strong></span> to a
270 <span><strong class="command">channel</strong></span> in the
271 <span><strong class="command">logging</strong></span> section of
272 <code class="filename">named.conf</code> or by specifying
273 <span><strong class="command">querylog yes;</strong></span> in the
274 <span><strong class="command">options</strong></span> section of
275 <code class="filename">named.conf</code>.
278 <dt><span class="term"><strong class="userinput"><code>dumpdb [<span class="optional">-all|-cache|-zone</span>] [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt>
280 Dump the server's caches (default) and/or zones to
282 dump file for the specified views. If no view is
286 <dt><span class="term"><strong class="userinput"><code>secroots [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt>
288 Dump the server's security roots to the secroots
289 file for the specified views. If no view is
290 specified, security roots for all
293 <dt><span class="term"><strong class="userinput"><code>stop [<span class="optional">-p</span>]</code></strong></span></dt>
295 Stop the server, making sure any recent changes
296 made through dynamic update or IXFR are first saved to
297 the master files of the updated zones.
298 If <code class="option">-p</code> is specified <span><strong class="command">named</strong></span>'s process id is returned.
299 This allows an external process to determine when <span><strong class="command">named</strong></span>
300 had completed stopping.
302 <dt><span class="term"><strong class="userinput"><code>halt [<span class="optional">-p</span>]</code></strong></span></dt>
304 Stop the server immediately. Recent changes
305 made through dynamic update or IXFR are not saved to
306 the master files, but will be rolled forward from the
307 journal files when the server is restarted.
308 If <code class="option">-p</code> is specified <span><strong class="command">named</strong></span>'s process id is returned.
309 This allows an external process to determine when <span><strong class="command">named</strong></span>
310 had completed halting.
312 <dt><span class="term"><strong class="userinput"><code>trace</code></strong></span></dt>
314 Increment the servers debugging level by one.
316 <dt><span class="term"><strong class="userinput"><code>trace <em class="replaceable"><code>level</code></em></code></strong></span></dt>
318 Sets the server's debugging level to an explicit
321 <dt><span class="term"><strong class="userinput"><code>notrace</code></strong></span></dt>
323 Sets the server's debugging level to 0.
325 <dt><span class="term"><strong class="userinput"><code>flush</code></strong></span></dt>
327 Flushes the server's cache.
329 <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>
331 Flushes the given name from the server's DNS cache
332 and, if applicable, from the server's nameserver address
333 database or bad-server cache.
335 <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>
337 Flushes the given name, and all of its subdomains,
338 from the server's DNS cache. Note that this does
339 <span class="emphasis"><em>not</em></span> affect he server's address
340 database or bad-server cache.
342 <dt><span class="term"><strong class="userinput"><code>status</code></strong></span></dt>
344 Display status of the server.
345 Note that the number of zones includes the internal <span><strong class="command">bind/CH</strong></span> zone
346 and the default <span><strong class="command">./IN</strong></span>
347 hint zone if there is not an
348 explicit root zone configured.
350 <dt><span class="term"><strong class="userinput"><code>recursing</code></strong></span></dt>
352 Dump the list of queries <span><strong class="command">named</strong></span> is currently recursing
355 <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>
357 Enable, disable, or check the current status of
359 Note <span><strong class="command">dnssec-enable</strong></span> also needs to be
360 set to <strong class="userinput"><code>yes</code></strong> or
361 <strong class="userinput"><code>auto</code></strong> to be effective.
362 It defaults to enabled.
364 <dt><span class="term"><strong class="userinput"><code>tsig-list</code></strong></span></dt>
366 List the names of all TSIG keys currently configured
367 for use by <span><strong class="command">named</strong></span> in each view. The
368 list both statically configured keys and dynamic
369 TKEY-negotiated keys.
371 <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>
373 Delete a given TKEY-negotiated key from the server.
374 (This does not apply to statically configured TSIG
377 <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>
380 Add a zone while the server is running. This
382 <span><strong class="command">allow-new-zones</strong></span> option to be set
383 to <strong class="userinput"><code>yes</code></strong>. The
384 <em class="replaceable"><code>configuration</code></em> string
385 specified on the command line is the zone
386 configuration text that would ordinarily be
387 placed in <code class="filename">named.conf</code>.
390 The configuration is saved in a file called
391 <code class="filename"><em class="replaceable"><code>hash</code></em>.nzf</code>,
392 where <em class="replaceable"><code>hash</code></em> is a
393 cryptographic hash generated from the name of
394 the view. When <span><strong class="command">named</strong></span> is
395 restarted, the file will be loaded into the view
396 configuration, so that zones that were added
397 can persist after a restart.
400 This sample <span><strong class="command">addzone</strong></span> command
401 would add the zone <code class="literal">example.com</code>
405 <code class="prompt">$ </code><strong class="userinput"><code>rndc addzone example.com '{ type master; file "example.com.db"; };'</code></strong>
408 (Note the brackets and semi-colon around the zone
412 <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>
414 Delete a zone while the server is running.
415 Only zones that were originally added via
416 <span><strong class="command">rndc addzone</strong></span> can be deleted
419 <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>
422 List, edit, or remove the DNSSEC signing state for
423 the specified zone. The status of ongoing DNSSEC
424 operations (such as signing or generating
425 NSEC3 chains) is stored in the zone in the form
426 of DNS resource records of type
427 <span><strong class="command">sig-signing-type</strong></span>.
428 <span><strong class="command">rndc signing -list</strong></span> converts
429 these records into a human-readable form,
430 indicating which keys are currently signing
431 or have finished signing the zone, and which NSEC3
432 chains are being created or removed.
435 <span><strong class="command">rndc signing -clear</strong></span> can remove
436 a single key (specified in the same format that
437 <span><strong class="command">rndc signing -list</strong></span> uses to
438 display it), or all keys. In either case, only
439 completed keys are removed; any record indicating
440 that a key has not yet finished signing the zone
444 <span><strong class="command">rndc signing -nsec3param</strong></span> sets
445 the NSEC3 parameters for a zone. This is the
446 only supported mechanism for using NSEC3 with
447 <span><strong class="command">inline-signing</strong></span> zones.
448 Parameters are specified in the same format as
449 an NSEC3PARAM resource record: hash algorithm,
450 flags, iterations, and salt, in that order.
453 Currently, the only defined value for hash algorithm
454 is <code class="literal">1</code>, representing SHA-1.
455 The <code class="option">flags</code> may be set to
456 <code class="literal">0</code> or <code class="literal">1</code>,
457 depending on whether you wish to set the opt-out
458 bit in the NSEC3 chain. <code class="option">iterations</code>
459 defines the number of additional times to apply
460 the algorithm when generating an NSEC3 hash. The
461 <code class="option">salt</code> is a string of data expressed
462 in hexadecimal, or a hyphen (`-') if no salt is
466 So, for example, to create an NSEC3 chain using
467 the SHA-1 hash algorithm, no opt-out flag,
468 10 iterations, and a salt value of "FFFF", use:
469 <span><strong class="command">rndc signing -nsec3param 1 0 10 FFFF <em class="replaceable"><code>zone</code></em></strong></span>.
470 To set the opt-out flag, 15 iterations, and no
472 <span><strong class="command">rndc signing -nsec3param 1 1 15 - <em class="replaceable"><code>zone</code></em></strong></span>.
475 <span><strong class="command">rndc signing -nsec3param none</strong></span>
476 removes an existing NSEC3 chain and replaces it
482 <div class="refsect1" lang="en">
483 <a name="id2544843"></a><h2>LIMITATIONS</h2>
485 There is currently no way to provide the shared secret for a
486 <code class="option">key_id</code> without using the configuration file.
489 Several error messages could be clearer.
492 <div class="refsect1" lang="en">
493 <a name="id2542131"></a><h2>SEE ALSO</h2>
494 <p><span class="citerefentry"><span class="refentrytitle">rndc.conf</span>(5)</span>,
495 <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
496 <span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
497 <span class="citerefentry"><span class="refentrytitle">named.conf</span>(5)</span>,
498 <span class="citerefentry"><span class="refentrytitle">ndc</span>(8)</span>,
499 <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
502 <div class="refsect1" lang="en">
503 <a name="id2545190"></a><h2>AUTHOR</h2>
504 <p><span class="corpauthor">Internet Systems Consortium</span>