contrib/bind9/bin/confgen/rndc-confgen.docbook

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007, 2009, 2014, 2015  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001, 2003  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and/or distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17
  18 <!-- Converted by db4-upgrade version 1.0 -->
  19 <refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="man.rndc-confgen">
  20   <info>
  21     <date>2009-06-15</date>
  22   </info>
  23   <refentryinfo>
  24     <corpname>ISC</corpname>
  25     <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle><application>rndc-confgen</application></refentrytitle>
  30     <manvolnum>8</manvolnum>
  31     <refmiscinfo>BIND9</refmiscinfo>
  32   </refmeta>
  33
  34   <refnamediv>
  35     <refname><application>rndc-confgen</application></refname>
  36     <refpurpose>rndc key generation tool</refpurpose>
  37   </refnamediv>
  38
  39   <docinfo>
  40     <copyright>
  41       <year>2004</year>
  42       <year>2005</year>
  43       <year>2007</year>
  44       <year>2009</year>
  45       <year>2014</year>
  46       <year>2015</year>
  47       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  48     </copyright>
  49     <copyright>
  50       <year>2001</year>
  51       <year>2003</year>
  52       <holder>Internet Software Consortium.</holder>
  53     </copyright>
  54   </docinfo>
  55
  56   <refsynopsisdiv>
  57     <cmdsynopsis sepchar=" ">
  58       <command>rndc-confgen</command>
  59       <arg choice="opt" rep="norepeat"><option>-a</option></arg>
  60       <arg choice="opt" rep="norepeat"><option>-b <replaceable class="parameter">keysize</replaceable></option></arg>
  61       <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">keyfile</replaceable></option></arg>
  62       <arg choice="opt" rep="norepeat"><option>-h</option></arg>
  63       <arg choice="opt" rep="norepeat"><option>-k <replaceable class="parameter">keyname</replaceable></option></arg>
  64       <arg choice="opt" rep="norepeat"><option>-p <replaceable class="parameter">port</replaceable></option></arg>
  65       <arg choice="opt" rep="norepeat"><option>-r <replaceable class="parameter">randomfile</replaceable></option></arg>
  66       <arg choice="opt" rep="norepeat"><option>-s <replaceable class="parameter">address</replaceable></option></arg>
  67       <arg choice="opt" rep="norepeat"><option>-t <replaceable class="parameter">chrootdir</replaceable></option></arg>
  68       <arg choice="opt" rep="norepeat"><option>-u <replaceable class="parameter">user</replaceable></option></arg>
  69     </cmdsynopsis>
  70   </refsynopsisdiv>
  71
  72   <refsection><info><title>DESCRIPTION</title></info>
  73
  74     <para><command>rndc-confgen</command>
  75       generates configuration files
  76       for <command>rndc</command>.  It can be used as a
  77       convenient alternative to writing the
  78       <filename>rndc.conf</filename> file
  79       and the corresponding <command>controls</command>
  80       and <command>key</command>
  81       statements in <filename>named.conf</filename> by hand.
  82       Alternatively, it can be run with the <command>-a</command>
  83       option to set up a <filename>rndc.key</filename> file and
  84       avoid the need for a <filename>rndc.conf</filename> file
  85       and a <command>controls</command> statement altogether.
  86     </para>
  87
  88   </refsection>
  89
  90   <refsection><info><title>OPTIONS</title></info>
  91
  92
  93     <variablelist>
  94       <varlistentry>
  95         <term>-a</term>
  96         <listitem>
  97           <para>
  98             Do automatic <command>rndc</command> configuration.
  99             This creates a file <filename>rndc.key</filename>
 100             in <filename>/etc</filename> (or whatever
 101             <varname>sysconfdir</varname>
 102             was specified as when <acronym>BIND</acronym> was
 103             built)
 104             that is read by both <command>rndc</command>
 105             and <command>named</command> on startup.  The
 106             <filename>rndc.key</filename> file defines a default
 107             command channel and authentication key allowing
 108             <command>rndc</command> to communicate with
 109             <command>named</command> on the local host
 110             with no further configuration.
 111           </para>
 112           <para>
 113             Running <command>rndc-confgen -a</command> allows
 114             BIND 9 and <command>rndc</command> to be used as
 115             drop-in
 116             replacements for BIND 8 and <command>ndc</command>,
 117             with no changes to the existing BIND 8
 118             <filename>named.conf</filename> file.
 119           </para>
 120           <para>
 121             If a more elaborate configuration than that
 122             generated by <command>rndc-confgen -a</command>
 123             is required, for example if rndc is to be used remotely,
 124             you should run <command>rndc-confgen</command> without
 125             the
 126             <command>-a</command> option and set up a
 127             <filename>rndc.conf</filename> and
 128             <filename>named.conf</filename>
 129             as directed.
 130           </para>
 131         </listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term>-b <replaceable class="parameter">keysize</replaceable></term>
 136         <listitem>
 137           <para>
 138             Specifies the size of the authentication key in bits.
 139             Must be between 1 and 512 bits; the default is 128.
 140           </para>
 141         </listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term>-c <replaceable class="parameter">keyfile</replaceable></term>
 146         <listitem>
 147           <para>
 148             Used with the <command>-a</command> option to specify
 149             an alternate location for <filename>rndc.key</filename>.
 150           </para>
 151         </listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term>-h</term>
 156         <listitem>
 157           <para>
 158             Prints a short summary of the options and arguments to
 159             <command>rndc-confgen</command>.
 160           </para>
 161         </listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term>-k <replaceable class="parameter">keyname</replaceable></term>
 166         <listitem>
 167           <para>
 168             Specifies the key name of the rndc authentication key.
 169             This must be a valid domain name.
 170             The default is <constant>rndc-key</constant>.
 171           </para>
 172         </listitem>
 173       </varlistentry>
 174
 175       <varlistentry>
 176         <term>-p <replaceable class="parameter">port</replaceable></term>
 177         <listitem>
 178           <para>
 179             Specifies the command channel port where <command>named</command>
 180             listens for connections from <command>rndc</command>.
 181             The default is 953.
 182           </para>
 183         </listitem>
 184       </varlistentry>
 185
 186       <varlistentry>
 187         <term>-r <replaceable class="parameter">randomfile</replaceable></term>
 188         <listitem>
 189           <para>
 190             Specifies a source of random data for generating the
 191             authorization.  If the operating
 192             system does not provide a <filename>/dev/random</filename>
 193             or equivalent device, the default source of randomness
 194             is keyboard input.  <filename>randomdev</filename>
 195             specifies
 196             the name of a character device or file containing random
 197             data to be used instead of the default.  The special value
 198             <filename>keyboard</filename> indicates that keyboard
 199             input should be used.
 200           </para>
 201         </listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term>-s <replaceable class="parameter">address</replaceable></term>
 206         <listitem>
 207           <para>
 208             Specifies the IP address where <command>named</command>
 209             listens for command channel connections from
 210             <command>rndc</command>.  The default is the loopback
 211             address 127.0.0.1.
 212           </para>
 213         </listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term>-t <replaceable class="parameter">chrootdir</replaceable></term>
 218         <listitem>
 219           <para>
 220             Used with the <command>-a</command> option to specify
 221             a directory where <command>named</command> will run
 222             chrooted.  An additional copy of the <filename>rndc.key</filename>
 223             will be written relative to this directory so that
 224             it will be found by the chrooted <command>named</command>.
 225           </para>
 226         </listitem>
 227       </varlistentry>
 228
 229       <varlistentry>
 230         <term>-u <replaceable class="parameter">user</replaceable></term>
 231         <listitem>
 232           <para>
 233             Used with the <command>-a</command> option to set the
 234             owner
 235             of the <filename>rndc.key</filename> file generated.
 236             If
 237             <command>-t</command> is also specified only the file
 238             in
 239             the chroot area has its owner changed.
 240           </para>
 241         </listitem>
 242       </varlistentry>
 243
 244     </variablelist>
 245   </refsection>
 246
 247   <refsection><info><title>EXAMPLES</title></info>
 248
 249     <para>
 250       To allow <command>rndc</command> to be used with
 251       no manual configuration, run
 252     </para>
 253     <para><userinput>rndc-confgen -a</userinput>
 254     </para>
 255     <para>
 256       To print a sample <filename>rndc.conf</filename> file and
 257       corresponding <command>controls</command> and <command>key</command>
 258       statements to be manually inserted into <filename>named.conf</filename>,
 259       run
 260     </para>
 261     <para><userinput>rndc-confgen</userinput>
 262     </para>
 263   </refsection>
 264
 265   <refsection><info><title>SEE ALSO</title></info>
 266
 267     <para><citerefentry>
 268         <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
 269       </citerefentry>,
 270       <citerefentry>
 271         <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
 272       </citerefentry>,
 273       <citerefentry>
 274         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 275       </citerefentry>,
 276       <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
 277     </para>
 278   </refsection>
 279
 280 </refentry>