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