6/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.7.206.11 2007/12/14 20:56:36 marka Exp $ -->
  22
  23 <refentry>
  24   <refentryinfo>
  25     <date>June 30, 2000</date>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle><application>rndc</application></refentrytitle>
  30     <manvolnum>8</manvolnum>
  31     <refmiscinfo>BIND9</refmiscinfo>
  32   </refmeta>
  33
  34   <docinfo>
  35     <copyright>
  36       <year>2004</year>
  37       <year>2005</year>
  38       <year>2007</year>
  39       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  40     </copyright>
  41     <copyright>
  42       <year>2000</year>
  43       <year>2001</year>
  44       <holder>Internet Software Consortium.</holder>
  45     </copyright>
  46   </docinfo>
  47
  48   <refnamediv>
  49     <refname><application>rndc</application></refname>
  50     <refpurpose>name server control utility</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <cmdsynopsis>
  55       <command>rndc</command>
  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>
  69         <command>rndc</command> 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>
  78         <command>rndc</command> 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>
  90         <command>rndc</command> 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>-c <replaceable class="parameter">config-file</replaceable></term>
 102         <listitem>
 103           <para>
 104               Use <replaceable class="parameter">config-file</replaceable>
 105               as the configuration file instead of the default,
 106               <filename>/etc/rndc.conf</filename>.
 107           </para>
 108         </listitem>
 109       </varlistentry>
 110
 111       <varlistentry>
 112         <term>-k <replaceable class="parameter">key-file</replaceable></term>
 113         <listitem>
 114           <para>
 115               Use <replaceable class="parameter">key-file</replaceable>
 116               as the key file instead of the default,
 117               <filename>/etc/rndc.key</filename>.  The key in
 118               <filename>/etc/rndc.key</filename> will be used to authenticate
 119               commands sent to the server if the <replaceable class="parameter">config-file</replaceable>
 120               does not exist.
 121           </para>
 122         </listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term>-s <replaceable class="parameter">server</replaceable></term>
 127         <listitem>
 128           <para><replaceable class="parameter">server</replaceable> is
 129               the name or address of the server which matches a
 130               server statement in the configuration file for
 131               <command>rndc</command>.  If no server is supplied on the
 132               command line, the host named by the default-server clause
 133               in the options statement of the <command>rndc</command>
 134             configuration file will be used.
 135           </para>
 136         </listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term>-p <replaceable class="parameter">port</replaceable></term>
 141         <listitem>
 142           <para>
 143                Send commands to TCP port
 144                <replaceable class="parameter">port</replaceable> instead
 145                of BIND 9's default control channel port, 953.
 146           </para>
 147         </listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term>-V</term>
 152         <listitem>
 153           <para>
 154                Enable verbose logging.
 155           </para>
 156         </listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term>-y <replaceable class="parameter">key_id</replaceable></term>
 161         <listitem>
 162           <para>
 163                Use the key <replaceable class="parameter">key_id</replaceable>
 164                from the configuration file.
 165                <replaceable class="parameter">key_id</replaceable> must be
 166                known by named with the same algorithm and secret string
 167                in order for control message validation to succeed.
 168                If no <replaceable class="parameter">key_id</replaceable>
 169                is specified, <command>rndc</command> will first look
 170                for a key clause in the server statement of the server
 171                being used, or if no server statement is present for that
 172                host, then the default-key clause of the options statement.
 173                Note that the configuration file contains shared secrets
 174                which are used to send authenticated control commands
 175                to name servers.  It should therefore not have general read
 176                or write access.
 177           </para>
 178         </listitem>
 179       </varlistentry>
 180
 181     </variablelist>
 182
 183     <para>
 184       For the complete set of commands supported by <command>rndc</command>,
 185       see the BIND 9 Administrator Reference Manual or run
 186       <command>rndc</command> without arguments to see its help message.
 187     </para>
 188
 189   </refsect1>
 190
 191   <refsect1>
 192     <title>LIMITATIONS</title>
 193     <para>
 194         <command>rndc</command> does not yet support all the commands of
 195         the BIND 8 <command>ndc</command> utility.
 196     </para>
 197     <para>
 198         There is currently no way to provide the shared secret for a
 199         <option>key_id</option> without using the configuration file.
 200     </para>
 201     <para>
 202         Several error messages could be clearer.
 203     </para>
 204   </refsect1>
 205
 206   <refsect1>
 207     <title>SEE ALSO</title>
 208     <para>
 209       <citerefentry>
 210         <refentrytitle>rndc.conf</refentrytitle>
 211         <manvolnum>5</manvolnum>
 212       </citerefentry>,
 213       <citerefentry>
 214         <refentrytitle>rndc-confgen</refentrytitle>
 215         <manvolnum>8</manvolnum>
 216       </citerefentry>,
 217       <citerefentry>
 218         <refentrytitle>named</refentrytitle>
 219         <manvolnum>8</manvolnum>
 220       </citerefentry>,
 221       <citerefentry>
 222         <refentrytitle>named.conf</refentrytitle>
 223         <manvolnum>5</manvolnum>
 224       </citerefentry>,
 225       <citerefentry>
 226         <refentrytitle>ndc</refentrytitle>
 227         <manvolnum>8</manvolnum>
 228       </citerefentry>,
 229       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
 230     </para>
 231   </refsect1>
 232
 233   <refsect1>
 234     <title>AUTHOR</title>
 235     <para>
 236         <corpauthor>Internet Systems Consortium</corpauthor>
 237     </para>
 238   </refsect1>
 239
 240 </refentry>
 241
 242 <!--
 243  - Local variables:
 244  - mode: sgml
 245  - End:
 246 -->
 247