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  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.8.18.12 2007/08/28 07:20:01 tbox Exp $ -->
  22 <refentry id="man.rndc">
  23   <refentryinfo>
  24     <date>June 30, 2000</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       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  44     </copyright>
  45     <copyright>
  46       <year>2000</year>
  47       <year>2001</year>
  48       <holder>Internet Software Consortium.</holder>
  49     </copyright>
  50   </docinfo>
  51
  52   <refsynopsisdiv>
  53     <cmdsynopsis>
  54       <command>rndc</command>
  55       <arg><option>-b <replaceable class="parameter">source-address</replaceable></option></arg>
  56       <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
  57       <arg><option>-k <replaceable class="parameter">key-file</replaceable></option></arg>
  58       <arg><option>-s <replaceable class="parameter">server</replaceable></option></arg>
  59       <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
  60       <arg><option>-V</option></arg>
  61       <arg><option>-y <replaceable class="parameter">key_id</replaceable></option></arg>
  62       <arg choice="req">command</arg>
  63     </cmdsynopsis>
  64   </refsynopsisdiv>
  65
  66   <refsect1>
  67     <title>DESCRIPTION</title>
  68     <para><command>rndc</command>
  69       controls the operation of a name
  70       server.  It supersedes the <command>ndc</command> utility
  71       that was provided in old BIND releases.  If
  72       <command>rndc</command> is invoked with no command line
  73       options or arguments, it prints a short summary of the
  74       supported commands and the available options and their
  75       arguments.
  76     </para>
  77     <para><command>rndc</command>
  78       communicates with the name server
  79       over a TCP connection, sending commands authenticated with
  80       digital signatures.  In the current versions of
  81       <command>rndc</command> and <command>named</command>,
  82       the only supported authentication algorithm is HMAC-MD5,
  83       which uses a shared secret on each end of the connection.
  84       This provides TSIG-style authentication for the command
  85       request and the name server's response.  All commands sent
  86       over the channel must be signed by a key_id known to the
  87       server.
  88     </para>
  89     <para><command>rndc</command>
  90       reads a configuration file to
  91       determine how to contact the name server and decide what
  92       algorithm and key it should use.
  93     </para>
  94   </refsect1>
  95
  96   <refsect1>
  97     <title>OPTIONS</title>
  98
  99     <variablelist>
 100       <varlistentry>
 101         <term>-b <replaceable class="parameter">source-address</replaceable></term>
 102         <listitem>
 103           <para>
 104             Use <replaceable class="parameter">source-address</replaceable>
 105             as the source address for the connection to the server.
 106             Multiple instances are permitted to allow setting of both
 107             the IPv4 and IPv6 source addresses.
 108           </para>
 109         </listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term>-c <replaceable class="parameter">config-file</replaceable></term>
 114         <listitem>
 115           <para>
 116             Use <replaceable class="parameter">config-file</replaceable>
 117             as the configuration file instead of the default,
 118             <filename>/etc/rndc.conf</filename>.
 119           </para>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term>-k <replaceable class="parameter">key-file</replaceable></term>
 125         <listitem>
 126           <para>
 127             Use <replaceable class="parameter">key-file</replaceable>
 128             as the key file instead of the default,
 129             <filename>/etc/rndc.key</filename>.  The key in
 130             <filename>/etc/rndc.key</filename> will be used to
 131             authenticate
 132             commands sent to the server if the <replaceable class="parameter">config-file</replaceable>
 133             does not exist.
 134           </para>
 135         </listitem>
 136       </varlistentry>
 137
 138       <varlistentry>
 139         <term>-s <replaceable class="parameter">server</replaceable></term>
 140         <listitem>
 141           <para><replaceable class="parameter">server</replaceable> is
 142             the name or address of the server which matches a
 143             server statement in the configuration file for
 144             <command>rndc</command>.  If no server is supplied on the
 145             command line, the host named by the default-server clause
 146             in the options statement of the <command>rndc</command>
 147             configuration file will be used.
 148           </para>
 149         </listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term>-p <replaceable class="parameter">port</replaceable></term>
 154         <listitem>
 155           <para>
 156             Send commands to TCP port
 157             <replaceable class="parameter">port</replaceable>
 158             instead
 159             of BIND 9's default control channel port, 953.
 160           </para>
 161         </listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term>-V</term>
 166         <listitem>
 167           <para>
 168             Enable verbose logging.
 169           </para>
 170         </listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term>-y <replaceable class="parameter">key_id</replaceable></term>
 175         <listitem>
 176           <para>
 177             Use the key <replaceable class="parameter">key_id</replaceable>
 178             from the configuration file.
 179             <replaceable class="parameter">key_id</replaceable>
 180             must be
 181             known by named with the same algorithm and secret string
 182             in order for control message validation to succeed.
 183             If no <replaceable class="parameter">key_id</replaceable>
 184             is specified, <command>rndc</command> will first look
 185             for a key clause in the server statement of the server
 186             being used, or if no server statement is present for that
 187             host, then the default-key clause of the options statement.
 188             Note that the configuration file contains shared secrets
 189             which are used to send authenticated control commands
 190             to name servers.  It should therefore not have general read
 191             or write access.
 192           </para>
 193         </listitem>
 194       </varlistentry>
 195
 196     </variablelist>
 197
 198     <para>
 199       For the complete set of commands supported by <command>rndc</command>,
 200       see the BIND 9 Administrator Reference Manual or run
 201       <command>rndc</command> without arguments to see its help
 202       message.
 203     </para>
 204
 205   </refsect1>
 206
 207   <refsect1>
 208     <title>LIMITATIONS</title>
 209     <para><command>rndc</command>
 210       does not yet support all the commands of
 211       the BIND 8 <command>ndc</command> utility.
 212     </para>
 213     <para>
 214       There is currently no way to provide the shared secret for a
 215       <option>key_id</option> without using the configuration file.
 216     </para>
 217     <para>
 218       Several error messages could be clearer.
 219     </para>
 220   </refsect1>
 221
 222   <refsect1>
 223     <title>SEE ALSO</title>
 224     <para><citerefentry>
 225         <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
 226       </citerefentry>,
 227       <citerefentry>
 228         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 229       </citerefentry>,
 230       <citerefentry>
 231         <refentrytitle>named.conf</refentrytitle><manvolnum>5</manvolnum>
 232       </citerefentry>,
 233       <citerefentry>
 234         <refentrytitle>ndc</refentrytitle><manvolnum>8</manvolnum>
 235       </citerefentry>,
 236       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
 237     </para>
 238   </refsect1>
 239
 240   <refsect1>
 241     <title>AUTHOR</title>
 242     <para><corpauthor>Internet Systems Consortium</corpauthor>
 243     </para>
 244   </refsect1>
 245
 246 </refentry><!--
 247  - Local variables:
 248  - mode: sgml
 249  - End:
 250 -->