contrib/bind9/bin/rndc/rndc-confgen.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) 2001, 2003  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-confgen.docbook,v 1.13 2007/06/18 23:47:25 tbox Exp $ -->
  22 <refentry id="man.rndc-confgen">
  23   <refentryinfo>
  24     <date>Aug 27, 2001</date>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle><application>rndc-confgen</application></refentrytitle>
  29     <manvolnum>8</manvolnum>
  30     <refmiscinfo>BIND9</refmiscinfo>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname><application>rndc-confgen</application></refname>
  35     <refpurpose>rndc key generation tool</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>2001</year>
  47       <year>2003</year>
  48       <holder>Internet Software Consortium.</holder>
  49     </copyright>
  50   </docinfo>
  51
  52   <refsynopsisdiv>
  53     <cmdsynopsis>
  54       <command>rndc-confgen</command>
  55       <arg><option>-a</option></arg>
  56       <arg><option>-b <replaceable class="parameter">keysize</replaceable></option></arg>
  57       <arg><option>-c <replaceable class="parameter">keyfile</replaceable></option></arg>
  58       <arg><option>-h</option></arg>
  59       <arg><option>-k <replaceable class="parameter">keyname</replaceable></option></arg>
  60       <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
  61       <arg><option>-r <replaceable class="parameter">randomfile</replaceable></option></arg>
  62       <arg><option>-s <replaceable class="parameter">address</replaceable></option></arg>
  63       <arg><option>-t <replaceable class="parameter">chrootdir</replaceable></option></arg>
  64       <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
  65     </cmdsynopsis>
  66   </refsynopsisdiv>
  67
  68   <refsect1>
  69     <title>DESCRIPTION</title>
  70     <para><command>rndc-confgen</command>
  71       generates configuration files
  72       for <command>rndc</command>.  It can be used as a
  73       convenient alternative to writing the
  74       <filename>rndc.conf</filename> file
  75       and the corresponding <command>controls</command>
  76       and <command>key</command>
  77       statements in <filename>named.conf</filename> by hand.
  78       Alternatively, it can be run with the <command>-a</command>
  79       option to set up a <filename>rndc.key</filename> file and
  80       avoid the need for a <filename>rndc.conf</filename> file
  81       and a <command>controls</command> statement altogether.
  82     </para>
  83
  84   </refsect1>
  85
  86   <refsect1>
  87     <title>OPTIONS</title>
  88
  89     <variablelist>
  90       <varlistentry>
  91         <term>-a</term>
  92         <listitem>
  93           <para>
  94             Do automatic <command>rndc</command> configuration.
  95             This creates a file <filename>rndc.key</filename>
  96             in <filename>/etc</filename> (or whatever
  97             <varname>sysconfdir</varname>
  98             was specified as when <acronym>BIND</acronym> was
  99             built)
 100             that is read by both <command>rndc</command>
 101             and <command>named</command> on startup.  The
 102             <filename>rndc.key</filename> file defines a default
 103             command channel and authentication key allowing
 104             <command>rndc</command> to communicate with
 105             <command>named</command> on the local host
 106             with no further configuration.
 107           </para>
 108           <para>
 109             Running <command>rndc-confgen -a</command> allows
 110             BIND 9 and <command>rndc</command> to be used as
 111             drop-in
 112             replacements for BIND 8 and <command>ndc</command>,
 113             with no changes to the existing BIND 8
 114             <filename>named.conf</filename> file.
 115           </para>
 116           <para>
 117             If a more elaborate configuration than that
 118             generated by <command>rndc-confgen -a</command>
 119             is required, for example if rndc is to be used remotely,
 120             you should run <command>rndc-confgen</command> without
 121             the
 122             <command>-a</command> option and set up a
 123             <filename>rndc.conf</filename> and
 124             <filename>named.conf</filename>
 125             as directed.
 126           </para>
 127         </listitem>
 128       </varlistentry>
 129
 130       <varlistentry>
 131         <term>-b <replaceable class="parameter">keysize</replaceable></term>
 132         <listitem>
 133           <para>
 134             Specifies the size of the authentication key in bits.
 135             Must be between 1 and 512 bits; the default is 128.
 136           </para>
 137         </listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term>-c <replaceable class="parameter">keyfile</replaceable></term>
 142         <listitem>
 143           <para>
 144             Used with the <command>-a</command> option to specify
 145             an alternate location for <filename>rndc.key</filename>.
 146           </para>
 147         </listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term>-h</term>
 152         <listitem>
 153           <para>
 154             Prints a short summary of the options and arguments to
 155             <command>rndc-confgen</command>.
 156           </para>
 157         </listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term>-k <replaceable class="parameter">keyname</replaceable></term>
 162         <listitem>
 163           <para>
 164             Specifies the key name of the rndc authentication key.
 165             This must be a valid domain name.
 166             The default is <constant>rndc-key</constant>.
 167           </para>
 168         </listitem>
 169       </varlistentry>
 170
 171       <varlistentry>
 172         <term>-p <replaceable class="parameter">port</replaceable></term>
 173         <listitem>
 174           <para>
 175             Specifies the command channel port where <command>named</command>
 176             listens for connections from <command>rndc</command>.
 177             The default is 953.
 178           </para>
 179         </listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term>-r <replaceable class="parameter">randomfile</replaceable></term>
 184         <listitem>
 185           <para>
 186             Specifies a source of random data for generating the
 187             authorization.  If the operating
 188             system does not provide a <filename>/dev/random</filename>
 189             or equivalent device, the default source of randomness
 190             is keyboard input.  <filename>randomdev</filename>
 191             specifies
 192             the name of a character device or file containing random
 193             data to be used instead of the default.  The special value
 194             <filename>keyboard</filename> indicates that keyboard
 195             input should be used.
 196           </para>
 197         </listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term>-s <replaceable class="parameter">address</replaceable></term>
 202         <listitem>
 203           <para>
 204             Specifies the IP address where <command>named</command>
 205             listens for command channel connections from
 206             <command>rndc</command>.  The default is the loopback
 207             address 127.0.0.1.
 208           </para>
 209         </listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term>-t <replaceable class="parameter">chrootdir</replaceable></term>
 214         <listitem>
 215           <para>
 216             Used with the <command>-a</command> option to specify
 217             a directory where <command>named</command> will run
 218             chrooted.  An additional copy of the <filename>rndc.key</filename>
 219             will be written relative to this directory so that
 220             it will be found by the chrooted <command>named</command>.
 221           </para>
 222         </listitem>
 223       </varlistentry>
 224
 225       <varlistentry>
 226         <term>-u <replaceable class="parameter">user</replaceable></term>
 227         <listitem>
 228           <para>
 229             Used with the <command>-a</command> option to set the
 230             owner
 231             of the <filename>rndc.key</filename> file generated.
 232             If
 233             <command>-t</command> is also specified only the file
 234             in
 235             the chroot area has its owner changed.
 236           </para>
 237         </listitem>
 238       </varlistentry>
 239
 240     </variablelist>
 241   </refsect1>
 242
 243   <refsect1>
 244     <title>EXAMPLES</title>
 245     <para>
 246       To allow <command>rndc</command> to be used with
 247       no manual configuration, run
 248     </para>
 249     <para><userinput>rndc-confgen -a</userinput>
 250     </para>
 251     <para>
 252       To print a sample <filename>rndc.conf</filename> file and
 253       corresponding <command>controls</command> and <command>key</command>
 254       statements to be manually inserted into <filename>named.conf</filename>,
 255       run
 256     </para>
 257     <para><userinput>rndc-confgen</userinput>
 258     </para>
 259   </refsect1>
 260
 261   <refsect1>
 262     <title>SEE ALSO</title>
 263     <para><citerefentry>
 264         <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
 265       </citerefentry>,
 266       <citerefentry>
 267         <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
 268       </citerefentry>,
 269       <citerefentry>
 270         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 271       </citerefentry>,
 272       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
 273     </para>
 274   </refsect1>
 275
 276   <refsect1>
 277     <title>AUTHOR</title>
 278     <para><corpauthor>Internet Systems Consortium</corpauthor>
 279     </para>
 280   </refsect1>
 281
 282 </refentry><!--
 283  - Local variables:
 284  - mode: sgml
 285  - End:
 286 -->