contrib/bind9/bin/rndc/rndc.html

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007, 2013 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000, 2001 Internet Software Consortium.
   4  -
   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.
   8  -
   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.
  16 -->
  17 <!-- $Id$ -->
  18 <html>
  19 <head>
  20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  21 <title>rndc</title>
  22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
  23 </head>
  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">
  27 <h2>Name</h2>
  28 <p><span class="application">rndc</span> &#8212; name server control utility</p>
  29 </div>
  30 <div class="refsynopsisdiv">
  31 <h2>Synopsis</h2>
  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>
  33 </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
  43       arguments.
  44     </p>
  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
  55       server.
  56     </p>
  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.
  61     </p>
  62 </div>
  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>
  67 <dd><p>
  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.
  72           </p></dd>
  73 <dt><span class="term">-c <em class="replaceable"><code>config-file</code></em></span></dt>
  74 <dd><p>
  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>.
  78           </p></dd>
  79 <dt><span class="term">-k <em class="replaceable"><code>key-file</code></em></span></dt>
  80 <dd><p>
  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
  85             authenticate
  86             commands sent to the server if the <em class="replaceable"><code>config-file</code></em>
  87             does not exist.
  88           </p></dd>
  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.
  97           </p></dd>
  98 <dt><span class="term">-p <em class="replaceable"><code>port</code></em></span></dt>
  99 <dd><p>
 100             Send commands to TCP port
 101             <em class="replaceable"><code>port</code></em>
 102             instead
 103             of BIND 9's default control channel port, 953.
 104           </p></dd>
 105 <dt><span class="term">-V</span></dt>
 106 <dd><p>
 107             Enable verbose logging.
 108           </p></dd>
 109 <dt><span class="term">-y <em class="replaceable"><code>key_id</code></em></span></dt>
 110 <dd><p>
 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>
 114             must be
 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
 125             or write access.
 126           </p></dd>
 127 </dl></div>
 128 </div>
 129 <div class="refsect1" lang="en">
 130 <a name="id2543650"></a><h2>COMMANDS</h2>
 131 <p>
 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.
 134     </p>
 135 <p>
 136       Currently supported commands are:
 137     </p>
 138 <div class="variablelist"><dl>
 139 <dt><span class="term"><strong class="userinput"><code>reload</code></strong></span></dt>
 140 <dd><p>
 141             Reload configuration file and zones.
 142           </p></dd>
 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>
 144 <dd><p>
 145             Reload the given zone.
 146           </p></dd>
 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>
 148 <dd><p>
 149             Schedule zone maintenance for the given zone.
 150           </p></dd>
 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>
 152 <dd><p>
 153             Retransfer the given zone from the master.
 154           </p></dd>
 155 <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>
 156 <dd>
 157 <p>
 158             Fetch all DNSSEC keys for the given zone
 159             from the key directory (see the
 160             <span><strong class="command">key-directory</strong></span> option in
 161             the BIND 9 Administrator Reference Manual).  If they are within
 162             their publication period, merge them into the
 163             zone's DNSKEY RRset.  If the DNSKEY RRset
 164             is changed, then the zone is automatically
 165             re-signed with the new key set.
 166           </p>
 167 <p>
 168             This command requires that the
 169             <span><strong class="command">auto-dnssec</strong></span> zone option be set
 170             to <code class="literal">allow</code> or
 171             <code class="literal">maintain</code>,
 172             and also requires the zone to be configured to
 173             allow dynamic DNS.
 174             (See "Dynamic Update Policies" in the Administrator
 175             Reference Manual for more details.)
 176           </p>
 177 </dd>
 178 <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>
 179 <dd>
 180 <p>
 181             Fetch all DNSSEC keys for the given zone
 182             from the key directory.  If they are within
 183             their publication period, merge them into the
 184             zone's DNSKEY RRset.  Unlike <span><strong class="command">rndc
 185             sign</strong></span>, however, the zone is not
 186             immediately re-signed by the new keys, but is
 187             allowed to incrementally re-sign over time.
 188           </p>
 189 <p>
 190             This command requires that the
 191             <span><strong class="command">auto-dnssec</strong></span> zone option
 192             be set to <code class="literal">maintain</code>,
 193             and also requires the zone to be configured to
 194             allow dynamic DNS.
 195             (See "Dynamic Update Policies" in the Administrator
 196             Reference Manual for more details.)
 197           </p>
 198 </dd>
 199 <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>
 200 <dd><p>
 201             Suspend updates to a dynamic zone.  If no zone is
 202             specified, then all zones are suspended.  This allows
 203             manual edits to be made to a zone normally updated by
 204             dynamic update.  It also causes changes in the
 205             journal file to be synced into the master file,
 206             and the journal file to be removed.
 207             All dynamic update attempts will be refused while
 208             the zone is frozen.
 209           </p></dd>
 210 <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>
 211 <dd><p>
 212             Enable updates to a frozen dynamic zone.  If no
 213             zone is specified, then all frozen zones are
 214             enabled.  This causes the server to reload the zone
 215             from disk, and re-enables dynamic updates after the
 216             load has completed.  After a zone is thawed,
 217             dynamic updates will no longer be refused.
 218           </p></dd>
 219 <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>
 220 <dd><p>
 221             Resend NOTIFY messages for the zone.
 222           </p></dd>
 223 <dt><span class="term"><strong class="userinput"><code>reconfig</code></strong></span></dt>
 224 <dd><p>
 225             Reload the configuration file and load new zones,
 226             but do not reload existing zone files even if they
 227             have changed.
 228             This is faster than a full <span><strong class="command">reload</strong></span> when there
 229             is a large number of zones because it avoids the need
 230             to examine the
 231             modification times of the zones files.
 232           </p></dd>
 233 <dt><span class="term"><strong class="userinput"><code>stats</code></strong></span></dt>
 234 <dd><p>
 235             Write server statistics to the statistics file.
 236           </p></dd>
 237 <dt><span class="term"><strong class="userinput"><code>querylog</code></strong> [<span class="optional">on|off</span>] </span></dt>
 238 <dd><p>
 239             Toggle query logging.  Query logging can also be enabled
 240             by explicitly directing the <span><strong class="command">queries</strong></span>
 241             <span><strong class="command">category</strong></span> to a
 242             <span><strong class="command">channel</strong></span> in the
 243             <span><strong class="command">logging</strong></span> section of
 244             <code class="filename">named.conf</code> or by specifying
 245             <span><strong class="command">querylog yes;</strong></span> in the
 246             <span><strong class="command">options</strong></span> section of
 247             <code class="filename">named.conf</code>.
 248           </p></dd>
 249 <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>
 250 <dd><p>
 251             Dump the server's caches (default) and/or zones to
 252             the
 253             dump file for the specified views.  If no view is
 254             specified, all
 255             views are dumped.
 256           </p></dd>
 257 <dt><span class="term"><strong class="userinput"><code>secroots [<span class="optional"><em class="replaceable"><code>view ...</code></em></span>]</code></strong></span></dt>
 258 <dd><p>
 259             Dump the server's security roots to the secroots
 260             file for the specified views.  If no view is
 261             specified, security roots for all
 262             views are dumped.
 263           </p></dd>
 264 <dt><span class="term"><strong class="userinput"><code>stop [<span class="optional">-p</span>]</code></strong></span></dt>
 265 <dd><p>
 266             Stop the server, making sure any recent changes
 267             made through dynamic update or IXFR are first saved to
 268             the master files of the updated zones.
 269             If <code class="option">-p</code> is specified <span><strong class="command">named</strong></span>'s process id is returned.
 270             This allows an external process to determine when <span><strong class="command">named</strong></span>
 271             had completed stopping.
 272           </p></dd>
 273 <dt><span class="term"><strong class="userinput"><code>halt [<span class="optional">-p</span>]</code></strong></span></dt>
 274 <dd><p>
 275             Stop the server immediately.  Recent changes
 276             made through dynamic update or IXFR are not saved to
 277             the master files, but will be rolled forward from the
 278             journal files when the server is restarted.
 279             If <code class="option">-p</code> is specified <span><strong class="command">named</strong></span>'s process id is returned.
 280             This allows an external process to determine when <span><strong class="command">named</strong></span>
 281             had completed halting.
 282           </p></dd>
 283 <dt><span class="term"><strong class="userinput"><code>trace</code></strong></span></dt>
 284 <dd><p>
 285             Increment the servers debugging level by one.
 286           </p></dd>
 287 <dt><span class="term"><strong class="userinput"><code>trace <em class="replaceable"><code>level</code></em></code></strong></span></dt>
 288 <dd><p>
 289             Sets the server's debugging level to an explicit
 290             value.
 291           </p></dd>
 292 <dt><span class="term"><strong class="userinput"><code>notrace</code></strong></span></dt>
 293 <dd><p>
 294             Sets the server's debugging level to 0.
 295           </p></dd>
 296 <dt><span class="term"><strong class="userinput"><code>flush</code></strong></span></dt>
 297 <dd><p>
 298             Flushes the server's cache.
 299           </p></dd>
 300 <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>
 301 <dd><p>
 302             Flushes the given name from the server's cache.
 303           </p></dd>
 304 <dt><span class="term"><strong class="userinput"><code>status</code></strong></span></dt>
 305 <dd><p>
 306             Display status of the server.
 307             Note that the number of zones includes the internal <span><strong class="command">bind/CH</strong></span> zone
 308             and the default <span><strong class="command">./IN</strong></span>
 309             hint zone if there is not an
 310             explicit root zone configured.
 311           </p></dd>
 312 <dt><span class="term"><strong class="userinput"><code>recursing</code></strong></span></dt>
 313 <dd><p>
 314             Dump the list of queries <span><strong class="command">named</strong></span> is currently recursing
 315             on.
 316           </p></dd>
 317 <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>
 318 <dd><p>
 319             Enable, disable, or check the current status of
 320             DNSSEC validation.
 321             Note <span><strong class="command">dnssec-enable</strong></span> also needs to be
 322             set to <strong class="userinput"><code>yes</code></strong> or
 323             <strong class="userinput"><code>auto</code></strong> to be effective.
 324             It defaults to enabled.
 325           </p></dd>
 326 <dt><span class="term"><strong class="userinput"><code>tsig-list</code></strong></span></dt>
 327 <dd><p>
 328             List the names of all TSIG keys currently configured
 329             for use by <span><strong class="command">named</strong></span> in each view.  The
 330             list both statically configured keys and dynamic
 331             TKEY-negotiated keys.
 332           </p></dd>
 333 <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>
 334 <dd><p>
 335             Delete a given TKEY-negotiated key from the server.
 336             (This does not apply to statically configured TSIG
 337             keys.)
 338           </p></dd>
 339 <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>
 340 <dd>
 341 <p>
 342             Add a zone while the server is running.  This
 343             command requires the
 344             <span><strong class="command">allow-new-zones</strong></span> option to be set
 345             to <strong class="userinput"><code>yes</code></strong>.  The
 346             <em class="replaceable"><code>configuration</code></em> string
 347             specified on the command line is the zone
 348             configuration text that would ordinarily be
 349             placed in <code class="filename">named.conf</code>.
 350           </p>
 351 <p>
 352             The configuration is saved in a file called
 353            <code class="filename"><em class="replaceable"><code>hash</code></em>.nzf</code>,
 354             where <em class="replaceable"><code>hash</code></em> is a
 355             cryptographic hash generated from the name of
 356             the view.  When <span><strong class="command">named</strong></span> is
 357             restarted, the file will be loaded into the view
 358             configuration, so that zones that were added
 359             can persist after a restart.
 360           </p>
 361 <p>
 362             This sample <span><strong class="command">addzone</strong></span> command
 363             would add the zone <code class="literal">example.com</code>
 364             to the default view:
 365           </p>
 366 <p>
 367 <code class="prompt">$ </code><strong class="userinput"><code>rndc addzone example.com '{ type master; file "example.com.db"; };'</code></strong>
 368           </p>
 369 <p>
 370             (Note the brackets and semi-colon around the zone
 371             configuration text.)
 372           </p>
 373 </dd>
 374 <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>
 375 <dd><p>
 376             Delete a zone while the server is running.
 377             Only zones that were originally added via
 378             <span><strong class="command">rndc addzone</strong></span> can be deleted
 379             in this manner.
 380           </p></dd>
 381 </dl></div>
 382 </div>
 383 <div class="refsect1" lang="en">
 384 <a name="id2544662"></a><h2>LIMITATIONS</h2>
 385 <p>
 386       There is currently no way to provide the shared secret for a
 387       <code class="option">key_id</code> without using the configuration file.
 388     </p>
 389 <p>
 390       Several error messages could be clearer.
 391     </p>
 392 </div>
 393 <div class="refsect1" lang="en">
 394 <a name="id2544680"></a><h2>SEE ALSO</h2>
 395 <p><span class="citerefentry"><span class="refentrytitle">rndc.conf</span>(5)</span>,
 396       <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
 397       <span class="citerefentry"><span class="refentrytitle">named</span>(8)</span>,
 398       <span class="citerefentry"><span class="refentrytitle">named.conf</span>(5)</span>,
 399       <span class="citerefentry"><span class="refentrytitle">ndc</span>(8)</span>,
 400       <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
 401     </p>
 402 </div>
 403 <div class="refsect1" lang="en">
 404 <a name="id2544736"></a><h2>AUTHOR</h2>
 405 <p><span class="corpauthor">Internet Systems Consortium</span>
 406     </p>
 407 </div>
 408 </div></body>
 409 </html>