contrib/bind9/bin/rndc/rndc.docbook

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004, 2005, 2007, 2013  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and/or distribute this software for any
   9  - purpose with or without fee is hereby granted, provided that the above
  10  - copyright notice and this permission notice appear in all copies.
  11  -
  12  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  13  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  14  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  15  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  16  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  17  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  18  - PERFORMANCE OF THIS SOFTWARE.
  19 -->
  20
  21 <!-- $Id: rndc.docbook,v 1.21 2007/12/14 20:39:14 marka Exp $ -->
  22 <refentry id="man.rndc">
  23   <refentryinfo>
  24     <date>June 7, 2013</date>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle><application>rndc</application></refentrytitle>
  29     <manvolnum>8</manvolnum>
  30     <refmiscinfo>BIND9</refmiscinfo>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname><application>rndc</application></refname>
  35     <refpurpose>name server control utility</refpurpose>
  36   </refnamediv>
  37
  38   <docinfo>
  39     <copyright>
  40       <year>2004</year>
  41       <year>2005</year>
  42       <year>2007</year>
  43       <year>2013</year>
  44       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  45     </copyright>
  46     <copyright>
  47       <year>2000</year>
  48       <year>2001</year>
  49       <holder>Internet Software Consortium.</holder>
  50     </copyright>
  51   </docinfo>
  52
  53   <refsynopsisdiv>
  54     <cmdsynopsis>
  55       <command>rndc</command>
  56       <arg><option>-b <replaceable class="parameter">source-address</replaceable></option></arg>
  57       <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
  58       <arg><option>-k <replaceable class="parameter">key-file</replaceable></option></arg>
  59       <arg><option>-s <replaceable class="parameter">server</replaceable></option></arg>
  60       <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
  61       <arg><option>-V</option></arg>
  62       <arg><option>-y <replaceable class="parameter">key_id</replaceable></option></arg>
  63       <arg choice="req">command</arg>
  64     </cmdsynopsis>
  65   </refsynopsisdiv>
  66
  67   <refsect1>
  68     <title>DESCRIPTION</title>
  69     <para><command>rndc</command>
  70       controls the operation of a name
  71       server.  It supersedes the <command>ndc</command> utility
  72       that was provided in old BIND releases.  If
  73       <command>rndc</command> is invoked with no command line
  74       options or arguments, it prints a short summary of the
  75       supported commands and the available options and their
  76       arguments.
  77     </para>
  78     <para><command>rndc</command>
  79       communicates with the name server
  80       over a TCP connection, sending commands authenticated with
  81       digital signatures.  In the current versions of
  82       <command>rndc</command> and <command>named</command>,
  83       the only supported authentication algorithm is HMAC-MD5,
  84       which uses a shared secret on each end of the connection.
  85       This provides TSIG-style authentication for the command
  86       request and the name server's response.  All commands sent
  87       over the channel must be signed by a key_id known to the
  88       server.
  89     </para>
  90     <para><command>rndc</command>
  91       reads a configuration file to
  92       determine how to contact the name server and decide what
  93       algorithm and key it should use.
  94     </para>
  95   </refsect1>
  96
  97   <refsect1>
  98     <title>OPTIONS</title>
  99
 100     <variablelist>
 101       <varlistentry>
 102         <term>-b <replaceable class="parameter">source-address</replaceable></term>
 103         <listitem>
 104           <para>
 105             Use <replaceable class="parameter">source-address</replaceable>
 106             as the source address for the connection to the server.
 107             Multiple instances are permitted to allow setting of both
 108             the IPv4 and IPv6 source addresses.
 109           </para>
 110         </listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term>-c <replaceable class="parameter">config-file</replaceable></term>
 115         <listitem>
 116           <para>
 117             Use <replaceable class="parameter">config-file</replaceable>
 118             as the configuration file instead of the default,
 119             <filename>/etc/rndc.conf</filename>.
 120           </para>
 121         </listitem>
 122       </varlistentry>
 123
 124       <varlistentry>
 125         <term>-k <replaceable class="parameter">key-file</replaceable></term>
 126         <listitem>
 127           <para>
 128             Use <replaceable class="parameter">key-file</replaceable>
 129             as the key file instead of the default,
 130             <filename>/etc/rndc.key</filename>.  The key in
 131             <filename>/etc/rndc.key</filename> will be used to
 132             authenticate
 133             commands sent to the server if the <replaceable class="parameter">config-file</replaceable>
 134             does not exist.
 135           </para>
 136         </listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term>-s <replaceable class="parameter">server</replaceable></term>
 141         <listitem>
 142           <para><replaceable class="parameter">server</replaceable> is
 143             the name or address of the server which matches a
 144             server statement in the configuration file for
 145             <command>rndc</command>.  If no server is supplied on the
 146             command line, the host named by the default-server clause
 147             in the options statement of the <command>rndc</command>
 148             configuration file will be used.
 149           </para>
 150         </listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term>-p <replaceable class="parameter">port</replaceable></term>
 155         <listitem>
 156           <para>
 157             Send commands to TCP port
 158             <replaceable class="parameter">port</replaceable>
 159             instead
 160             of BIND 9's default control channel port, 953.
 161           </para>
 162         </listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term>-V</term>
 167         <listitem>
 168           <para>
 169             Enable verbose logging.
 170           </para>
 171         </listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term>-y <replaceable class="parameter">key_id</replaceable></term>
 176         <listitem>
 177           <para>
 178             Use the key <replaceable class="parameter">key_id</replaceable>
 179             from the configuration file.
 180             <replaceable class="parameter">key_id</replaceable>
 181             must be
 182             known by named with the same algorithm and secret string
 183             in order for control message validation to succeed.
 184             If no <replaceable class="parameter">key_id</replaceable>
 185             is specified, <command>rndc</command> will first look
 186             for a key clause in the server statement of the server
 187             being used, or if no server statement is present for that
 188             host, then the default-key clause of the options statement.
 189             Note that the configuration file contains shared secrets
 190             which are used to send authenticated control commands
 191             to name servers.  It should therefore not have general read
 192             or write access.
 193           </para>
 194         </listitem>
 195       </varlistentry>
 196
 197     </variablelist>
 198   </refsect1>
 199
 200   <refsect1>
 201     <title>COMMANDS</title>
 202     <para>
 203       A list of commands supported by <command>rndc</command> can
 204       be seen by running <command>rndc</command> without arguments.
 205     </para>
 206     <para>
 207       Currently supported commands are:
 208     </para>
 209
 210     <variablelist>
 211       <varlistentry>
 212         <term><userinput>reload</userinput></term>
 213         <listitem>
 214           <para>
 215             Reload configuration file and zones.
 216           </para>
 217         </listitem>
 218       </varlistentry>
 219
 220       <varlistentry>
 221         <term><userinput>reload <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 222         <listitem>
 223           <para>
 224             Reload the given zone.
 225           </para>
 226         </listitem>
 227       </varlistentry>
 228
 229       <varlistentry>
 230         <term><userinput>refresh <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 231         <listitem>
 232           <para>
 233             Schedule zone maintenance for the given zone.
 234           </para>
 235         </listitem>
 236       </varlistentry>
 237
 238       <varlistentry>
 239         <term><userinput>retransfer <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 240         <listitem>
 241           <para>
 242             Retransfer the given zone from the master.
 243           </para>
 244         </listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term><userinput>sign <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 249         <listitem>
 250           <para>
 251             Fetch all DNSSEC keys for the given zone
 252             from the key directory (see the
 253             <command>key-directory</command> option in
 254             the BIND 9 Administrator Reference Manual).  If they are within
 255             their publication period, merge them into the
 256             zone's DNSKEY RRset.  If the DNSKEY RRset
 257             is changed, then the zone is automatically
 258             re-signed with the new key set.
 259           </para>
 260           <para>
 261             This command requires that the
 262             <command>auto-dnssec</command> zone option be set
 263             to <literal>allow</literal> or
 264             <literal>maintain</literal>,
 265             and also requires the zone to be configured to
 266             allow dynamic DNS.
 267             (See "Dynamic Update Policies" in the Administrator
 268             Reference Manual for more details.)
 269           </para>
 270         </listitem>
 271       </varlistentry>
 272
 273       <varlistentry>
 274         <term><userinput>loadkeys <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 275         <listitem>
 276           <para>
 277             Fetch all DNSSEC keys for the given zone
 278             from the key directory.  If they are within
 279             their publication period, merge them into the
 280             zone's DNSKEY RRset.  Unlike <command>rndc
 281             sign</command>, however, the zone is not
 282             immediately re-signed by the new keys, but is
 283             allowed to incrementally re-sign over time.
 284           </para>
 285           <para>
 286             This command requires that the
 287             <command>auto-dnssec</command> zone option
 288             be set to <literal>maintain</literal>,
 289             and also requires the zone to be configured to
 290             allow dynamic DNS.
 291             (See "Dynamic Update Policies" in the Administrator
 292             Reference Manual for more details.)
 293           </para>
 294         </listitem>
 295       </varlistentry>
 296
 297       <varlistentry>
 298         <term><userinput>freeze <optional><replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></optional></userinput></term>
 299         <listitem>
 300           <para>
 301             Suspend updates to a dynamic zone.  If no zone is
 302             specified, then all zones are suspended.  This allows
 303             manual edits to be made to a zone normally updated by
 304             dynamic update.  It also causes changes in the
 305             journal file to be synced into the master file,
 306             and the journal file to be removed.
 307             All dynamic update attempts will be refused while
 308             the zone is frozen.
 309           </para>
 310         </listitem>
 311       </varlistentry>
 312
 313       <varlistentry>
 314         <term><userinput>thaw <optional><replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></optional></userinput></term>
 315         <listitem>
 316           <para>
 317             Enable updates to a frozen dynamic zone.  If no
 318             zone is specified, then all frozen zones are
 319             enabled.  This causes the server to reload the zone
 320             from disk, and re-enables dynamic updates after the
 321             load has completed.  After a zone is thawed,
 322             dynamic updates will no longer be refused.
 323           </para>
 324         </listitem>
 325       </varlistentry>
 326
 327       <varlistentry>
 328         <term><userinput>notify <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional></userinput></term>
 329         <listitem>
 330           <para>
 331             Resend NOTIFY messages for the zone.
 332           </para>
 333         </listitem>
 334       </varlistentry>
 335
 336       <varlistentry>
 337         <term><userinput>reconfig</userinput></term>
 338         <listitem>
 339           <para>
 340             Reload the configuration file and load new zones,
 341             but do not reload existing zone files even if they
 342             have changed.
 343             This is faster than a full <command>reload</command> when there
 344             is a large number of zones because it avoids the need
 345             to examine the
 346             modification times of the zones files.
 347           </para>
 348         </listitem>
 349       </varlistentry>
 350
 351       <varlistentry>
 352         <term><userinput>stats</userinput></term>
 353         <listitem>
 354           <para>
 355             Write server statistics to the statistics file.
 356           </para>
 357         </listitem>
 358       </varlistentry>
 359
 360       <varlistentry>
 361         <term><userinput>querylog</userinput> <optional>on|off</optional> </term>
 362         <listitem>
 363           <para>
 364             Toggle query logging.  Query logging can also be enabled
 365             by explicitly directing the <command>queries</command>
 366             <command>category</command> to a
 367             <command>channel</command> in the
 368             <command>logging</command> section of
 369             <filename>named.conf</filename> or by specifying
 370             <command>querylog yes;</command> in the
 371             <command>options</command> section of
 372             <filename>named.conf</filename>.
 373           </para>
 374         </listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><userinput>dumpdb <optional>-all|-cache|-zone</optional> <optional><replaceable>view ...</replaceable></optional></userinput></term>
 379         <listitem>
 380           <para>
 381             Dump the server's caches (default) and/or zones to
 382             the
 383             dump file for the specified views.  If no view is
 384             specified, all
 385             views are dumped.
 386           </para>
 387         </listitem>
 388       </varlistentry>
 389
 390       <varlistentry>
 391         <term><userinput>secroots <optional><replaceable>view ...</replaceable></optional></userinput></term>
 392         <listitem>
 393           <para>
 394             Dump the server's security roots to the secroots
 395             file for the specified views.  If no view is
 396             specified, security roots for all
 397             views are dumped.
 398           </para>
 399         </listitem>
 400       </varlistentry>
 401
 402       <varlistentry>
 403         <term><userinput>stop <optional>-p</optional></userinput></term>
 404         <listitem>
 405           <para>
 406             Stop the server, making sure any recent changes
 407             made through dynamic update or IXFR are first saved to
 408             the master files of the updated zones.
 409             If <option>-p</option> is specified <command>named</command>'s process id is returned.
 410             This allows an external process to determine when <command>named</command>
 411             had completed stopping.
 412           </para>
 413         </listitem>
 414       </varlistentry>
 415
 416       <varlistentry>
 417         <term><userinput>halt <optional>-p</optional></userinput></term>
 418         <listitem>
 419           <para>
 420             Stop the server immediately.  Recent changes
 421             made through dynamic update or IXFR are not saved to
 422             the master files, but will be rolled forward from the
 423             journal files when the server is restarted.
 424             If <option>-p</option> is specified <command>named</command>'s process id is returned.
 425             This allows an external process to determine when <command>named</command>
 426             had completed halting.
 427           </para>
 428         </listitem>
 429       </varlistentry>
 430
 431       <varlistentry>
 432         <term><userinput>trace</userinput></term>
 433         <listitem>
 434           <para>
 435             Increment the servers debugging level by one.
 436           </para>
 437         </listitem>
 438       </varlistentry>
 439
 440       <varlistentry>
 441         <term><userinput>trace <replaceable>level</replaceable></userinput></term>
 442         <listitem>
 443           <para>
 444             Sets the server's debugging level to an explicit
 445             value.
 446           </para>
 447         </listitem>
 448       </varlistentry>
 449
 450       <varlistentry>
 451         <term><userinput>notrace</userinput></term>
 452         <listitem>
 453           <para>
 454             Sets the server's debugging level to 0.
 455           </para>
 456         </listitem>
 457       </varlistentry>
 458
 459       <varlistentry>
 460         <term><userinput>flush</userinput></term>
 461         <listitem>
 462           <para>
 463             Flushes the server's cache.
 464           </para>
 465         </listitem>
 466       </varlistentry>
 467
 468       <varlistentry>
 469         <term><userinput>flushname</userinput> <replaceable>name</replaceable> <optional><replaceable>view</replaceable></optional> </term>
 470         <listitem>
 471           <para>
 472             Flushes the given name from the server's cache.
 473           </para>
 474         </listitem>
 475       </varlistentry>
 476
 477       <varlistentry>
 478         <term><userinput>status</userinput></term>
 479         <listitem>
 480           <para>
 481             Display status of the server.
 482             Note that the number of zones includes the internal <command>bind/CH</command> zone
 483             and the default <command>./IN</command>
 484             hint zone if there is not an
 485             explicit root zone configured.
 486           </para>
 487         </listitem>
 488       </varlistentry>
 489
 490       <varlistentry>
 491         <term><userinput>recursing</userinput></term>
 492         <listitem>
 493           <para>
 494             Dump the list of queries <command>named</command> is currently recursing
 495             on.
 496           </para>
 497         </listitem>
 498       </varlistentry>
 499
 500       <varlistentry>
 501         <term><userinput>validation ( on | off | check ) <optional><replaceable>view ...</replaceable></optional> </userinput></term>
 502         <listitem>
 503           <para>
 504             Enable, disable, or check the current status of
 505             DNSSEC validation.
 506             Note <command>dnssec-enable</command> also needs to be
 507             set to <userinput>yes</userinput> or
 508             <userinput>auto</userinput> to be effective.
 509             It defaults to enabled.
 510           </para>
 511         </listitem>
 512       </varlistentry>
 513
 514       <varlistentry>
 515         <term><userinput>tsig-list</userinput></term>
 516         <listitem>
 517           <para>
 518             List the names of all TSIG keys currently configured
 519             for use by <command>named</command> in each view.  The
 520             list both statically configured keys and dynamic
 521             TKEY-negotiated keys.
 522           </para>
 523         </listitem>
 524       </varlistentry>
 525
 526       <varlistentry>
 527         <term><userinput>tsig-delete</userinput> <replaceable>keyname</replaceable> <optional><replaceable>view</replaceable></optional></term>
 528         <listitem>
 529           <para>
 530             Delete a given TKEY-negotiated key from the server.
 531             (This does not apply to statically configured TSIG
 532             keys.)
 533           </para>
 534         </listitem>
 535       </varlistentry>
 536
 537       <varlistentry>
 538         <term><userinput>addzone <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional> <replaceable>configuration</replaceable> </userinput></term>
 539         <listitem>
 540           <para>
 541             Add a zone while the server is running.  This
 542             command requires the
 543             <command>allow-new-zones</command> option to be set
 544             to <userinput>yes</userinput>.  The
 545             <replaceable>configuration</replaceable> string
 546             specified on the command line is the zone
 547             configuration text that would ordinarily be
 548             placed in <filename>named.conf</filename>.
 549           </para>
 550           <para>
 551             The configuration is saved in a file called
 552            <filename><replaceable>hash</replaceable>.nzf</filename>,
 553             where <replaceable>hash</replaceable> is a
 554             cryptographic hash generated from the name of
 555             the view.  When <command>named</command> is
 556             restarted, the file will be loaded into the view
 557             configuration, so that zones that were added
 558             can persist after a restart.
 559           </para>
 560           <para>
 561             This sample <command>addzone</command> command
 562             would add the zone <literal>example.com</literal>
 563             to the default view:
 564           </para>
 565           <para>
 566 <prompt>$ </prompt><userinput>rndc addzone example.com '{ type master; file "example.com.db"; };'</userinput>
 567           </para>
 568           <para>
 569             (Note the brackets and semi-colon around the zone
 570             configuration text.)
 571           </para>
 572         </listitem>
 573       </varlistentry>
 574
 575       <varlistentry>
 576         <term><userinput>delzone <replaceable>zone</replaceable> <optional><replaceable>class</replaceable> <optional><replaceable>view</replaceable></optional></optional> </userinput></term>
 577         <listitem>
 578           <para>
 579             Delete a zone while the server is running.
 580             Only zones that were originally added via
 581             <command>rndc addzone</command> can be deleted
 582             in this manner.
 583           </para>
 584         </listitem>
 585       </varlistentry>
 586     </variablelist>
 587   </refsect1>
 588
 589   <refsect1>
 590     <title>LIMITATIONS</title>
 591     <para>
 592       There is currently no way to provide the shared secret for a
 593       <option>key_id</option> without using the configuration file.
 594     </para>
 595     <para>
 596       Several error messages could be clearer.
 597     </para>
 598   </refsect1>
 599
 600   <refsect1>
 601     <title>SEE ALSO</title>
 602     <para><citerefentry>
 603         <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
 604       </citerefentry>,
 605       <citerefentry>
 606         <refentrytitle>rndc-confgen</refentrytitle><manvolnum>8</manvolnum>
 607       </citerefentry>,
 608       <citerefentry>
 609         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 610       </citerefentry>,
 611       <citerefentry>
 612         <refentrytitle>named.conf</refentrytitle><manvolnum>5</manvolnum>
 613       </citerefentry>,
 614       <citerefentry>
 615         <refentrytitle>ndc</refentrytitle><manvolnum>8</manvolnum>
 616       </citerefentry>,
 617       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
 618     </para>
 619   </refsect1>
 620
 621   <refsect1>
 622     <title>AUTHOR</title>
 623     <para><corpauthor>Internet Systems Consortium</corpauthor>
 624     </para>
 625   </refsect1>
 626
 627 </refentry><!--
 628  - Local variables:
 629  - mode: sgml
 630  - End:
 631 -->