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