path: root/bin/rndc/rndc-confgen.docbook

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
 - Copyright (C) 2004, 2005, 2007  Internet Systems Consortium, Inc. ("ISC")
 - Copyright (C) 2001, 2003  Internet Software Consortium.
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

<!-- $Id: rndc-confgen.docbook,v 1.13 2007/06/18 23:47:25 tbox Exp $ -->
<refentry id="man.rndc-confgen">
  <refentryinfo>
    <date>Aug 27, 2001</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle><application>rndc-confgen</application></refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND9</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname><application>rndc-confgen</application></refname>
    <refpurpose>rndc key generation tool</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
      <year>2004</year>
      <year>2005</year>
      <year>2007</year>
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
    <copyright>
      <year>2001</year>
      <year>2003</year>
      <holder>Internet Software Consortium.</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>rndc-confgen</command>
      <arg><option>-a</option></arg>
      <arg><option>-b <replaceable class="parameter">keysize</replaceable></option></arg>
      <arg><option>-c <replaceable class="parameter">keyfile</replaceable></option></arg>
      <arg><option>-h</option></arg>
      <arg><option>-k <replaceable class="parameter">keyname</replaceable></option></arg>
      <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
      <arg><option>-r <replaceable class="parameter">randomfile</replaceable></option></arg>
      <arg><option>-s <replaceable class="parameter">address</replaceable></option></arg>
      <arg><option>-t <replaceable class="parameter">chrootdir</replaceable></option></arg>
      <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para><command>rndc-confgen</command>
      generates configuration files
      for <command>rndc</command>.  It can be used as a
      convenient alternative to writing the
      <filename>rndc.conf</filename> file
      and the corresponding <command>controls</command>
      and <command>key</command>
      statements in <filename>named.conf</filename> by hand.
      Alternatively, it can be run with the <command>-a</command>
      option to set up a <filename>rndc.key</filename> file and
      avoid the need for a <filename>rndc.conf</filename> file
      and a <command>controls</command> statement altogether.
    </para>

  </refsect1>

  <refsect1>
    <title>OPTIONS</title>

    <variablelist>
      <varlistentry>
        <term>-a</term>
        <listitem>
          <para>
            Do automatic <command>rndc</command> configuration.
            This creates a file <filename>rndc.key</filename>
            in <filename>/etc</filename> (or whatever
            <varname>sysconfdir</varname>
            was specified as when <acronym>BIND</acronym> was
            built)
            that is read by both <command>rndc</command>
            and <command>named</command> on startup.  The
            <filename>rndc.key</filename> file defines a default
            command channel and authentication key allowing
            <command>rndc</command> to communicate with
            <command>named</command> on the local host
            with no further configuration.
          </para>
          <para>
            Running <command>rndc-confgen -a</command> allows
            BIND 9 and <command>rndc</command> to be used as
            drop-in
            replacements for BIND 8 and <command>ndc</command>,
            with no changes to the existing BIND 8
            <filename>named.conf</filename> file.
          </para>
          <para>
            If a more elaborate configuration than that
            generated by <command>rndc-confgen -a</command>
            is required, for example if rndc is to be used remotely,
            you should run <command>rndc-confgen</command> without
            the
            <command>-a</command> option and set up a
            <filename>rndc.conf</filename> and
            <filename>named.conf</filename>
            as directed.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-b <replaceable class="parameter">keysize</replaceable></term>
        <listitem>
          <para>
            Specifies the size of the authentication key in bits.
            Must be between 1 and 512 bits; the default is 128.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-c <replaceable class="parameter">keyfile</replaceable></term>
        <listitem>
          <para>
            Used with the <command>-a</command> option to specify
            an alternate location for <filename>rndc.key</filename>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-h</term>
        <listitem>
          <para>
            Prints a short summary of the options and arguments to
            <command>rndc-confgen</command>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-k <replaceable class="parameter">keyname</replaceable></term>
        <listitem>
          <para>
            Specifies the key name of the rndc authentication key.
            This must be a valid domain name.
            The default is <constant>rndc-key</constant>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-p <replaceable class="parameter">port</replaceable></term>
        <listitem>
          <para>
            Specifies the command channel port where <command>named</command>
            listens for connections from <command>rndc</command>.
            The default is 953.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-r <replaceable class="parameter">randomfile</replaceable></term>
        <listitem>
          <para>
            Specifies a source of random data for generating the
            authorization.  If the operating
            system does not provide a <filename>/dev/random</filename>
            or equivalent device, the default source of randomness
            is keyboard input.  <filename>randomdev</filename>
            specifies
            the name of a character device or file containing random
            data to be used instead of the default.  The special value
            <filename>keyboard</filename> indicates that keyboard
            input should be used.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-s <replaceable class="parameter">address</replaceable></term>
        <listitem>
          <para>
            Specifies the IP address where <command>named</command>
            listens for command channel connections from
            <command>rndc</command>.  The default is the loopback
            address 127.0.0.1.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-t <replaceable class="parameter">chrootdir</replaceable></term>
        <listitem>
          <para>
            Used with the <command>-a</command> option to specify
            a directory where <command>named</command> will run
            chrooted.  An additional copy of the <filename>rndc.key</filename>
            will be written relative to this directory so that
            it will be found by the chrooted <command>named</command>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-u <replaceable class="parameter">user</replaceable></term>
        <listitem>
          <para>
            Used with the <command>-a</command> option to set the
            owner
            of the <filename>rndc.key</filename> file generated.
            If
            <command>-t</command> is also specified only the file
            in
            the chroot area has its owner changed.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>EXAMPLES</title>
    <para>
      To allow <command>rndc</command> to be used with
      no manual configuration, run
    </para>
    <para><userinput>rndc-confgen -a</userinput>
    </para>
    <para>
      To print a sample <filename>rndc.conf</filename> file and
      corresponding <command>controls</command> and <command>key</command>
      statements to be manually inserted into <filename>named.conf</filename>,
      run
    </para>
    <para><userinput>rndc-confgen</userinput>
    </para>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para><citerefentry>
        <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>rndc.conf</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
    </para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
    <para><corpauthor>Internet Systems Consortium</corpauthor>
    </para>
  </refsect1>

</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->