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

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
               "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
 - Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
 - Copyright (C) 2001, 2003  Internet Software Consortium.
 -
 - Permission to use, copy, modify, and 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.3.2.1.4.5 2005/05/13 01:22:34 marka Exp $ -->

<refentry>
  <refentryinfo>
    <date>Aug 27, 2001</date>
  </refentryinfo>

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

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

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

  <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:
-->