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 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.8 2007/01/29 23:57:20 marka 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> named
  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
 145             the
 146             command line, the host named by the default-server clause
 147             in the option statement of the configuration file will be
 148             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">keyid</replaceable></term>
 176         <listitem>
 177           <para>
 178             Use the key <replaceable class="parameter">keyid</replaceable>
 179             from the configuration file.
 180             <replaceable class="parameter">keyid</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">keyid</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
 199     <para>
 200       For the complete set of commands supported by <command>rndc</command>,
 201       see the BIND 9 Administrator Reference Manual or run
 202       <command>rndc</command> without arguments to see its help
 203       message.
 204     </para>
 205
 206   </refsect1>
 207
 208   <refsect1>
 209     <title>LIMITATIONS</title>
 210     <para><command>rndc</command>
 211       does not yet support all the commands of
 212       the BIND 8 <command>ndc</command> utility.
 213     </para>
 214     <para>
 215       There is currently no way to provide the shared secret for a
 216       <option>key_id</option> without using the configuration file.
 217     </para>
 218     <para>
 219       Several error messages could be clearer.
 220     </para>
 221   </refsect1>
 222
 223   <refsect1>
 224     <title>SEE ALSO</title>
 225     <para><citerefentry>
 226         <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
 227       </citerefentry>,
 228       <citerefentry>
 229         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 230       </citerefentry>,
 231       <citerefentry>
 232         <refentrytitle>named.conf</refentrytitle><manvolnum>5</manvolnum>
 233       </citerefentry>
 234       <citerefentry>
 235         <refentrytitle>ndc</refentrytitle><manvolnum>8</manvolnum>
 236       </citerefentry>,
 237       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
 238     </para>
 239   </refsect1>
 240
 241   <refsect1>
 242     <title>AUTHOR</title>
 243     <para><corpauthor>Internet Systems Consortium</corpauthor>
 244     </para>
 245   </refsect1>
 246
 247 </refentry><!--
 248  - Local variables:
 249  - mode: sgml
 250  - End:
 251 -->