rndc-confgen.docbook revision 17cb8353e999e3294e6619613f401af3f7b1540c
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest<!--
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - Copyright (C) 2001, 2003 Internet Software Consortium.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest -
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - Permission to use, copy, modify, and distribute this software for any
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - purpose with or without fee is hereby granted, provided that the above
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - copyright notice and this permission notice appear in all copies.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest -
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest - PERFORMANCE OF THIS SOFTWARE.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest-->
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest<!-- $Id: rndc-confgen.docbook,v 1.7 2004/06/03 02:22:34 marka Exp $ -->
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest<refentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refentryinfo>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <date>Aug 27, 2001</date>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </refentryinfo>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refmeta>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refentrytitle><application>rndc-confgen</application></refentrytitle>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <manvolnum>8</manvolnum>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refmiscinfo>BIND9</refmiscinfo>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </refmeta>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refnamediv>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refname><application>rndc-confgen</application></refname>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refpurpose>rndc key generation tool</refpurpose>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </refnamediv>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refsynopsisdiv>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <cmdsynopsis>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <command>rndc-confgen</command>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-a</option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-b <replaceable class="parameter">keysize</replaceable></option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-c <replaceable class="parameter">keyfile</replaceable></option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-h</option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-k <replaceable class="parameter">keyname</replaceable></option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-r <replaceable class="parameter">randomfile</replaceable></option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-s <replaceable class="parameter">address</replaceable></option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-t <replaceable class="parameter">chrootdir</replaceable></option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <arg><option>-u <replaceable class="parameter">user</replaceable></option></arg>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </cmdsynopsis>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </refsynopsisdiv>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refsect1>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <title>DESCRIPTION</title>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <command>rndc-confgen</command> generates configuration files
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest for <command>rndc</command>. It can be used as a
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest convenient alternative to writing the
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <filename>rndc.conf</filename> file
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest and the corresponding <command>controls</command>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest and <command>key</command>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest statements in <filename>named.conf</filename> by hand.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest Alternatively, it can be run with the <command>-a</command>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest option to set up a <filename>rndc.key</filename> file and
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest avoid the need for a <filename>rndc.conf</filename> file
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest and a <command>controls</command> statement altogether.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </refsect1>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <refsect1>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <title>OPTIONS</title>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <variablelist>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <term>-a</term>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest Do automatic <command>rndc</command> configuration.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest This creates a file <filename>rndc.key</filename>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest in <filename>/etc</filename> (or whatever
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <varname>sysconfdir</varname>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest was specified as when <acronym>BIND</acronym> was built)
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest that is read by both <command>rndc</command>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest and <command>named</command> on startup. The
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <filename>rndc.key</filename> file defines a default
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest command channel and authentication key allowing
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <command>rndc</command> to communicate with
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <command>named</command> on the local host
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest with no further configuration.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest Running <command>rndc-confgen -a</command> allows
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest BIND 9 and <command>rndc</command> to be used as drop-in
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest replacements for BIND 8 and <command>ndc</command>,
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest with no changes to the existing BIND 8
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <filename>named.conf</filename> file.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest If a more elaborate configuration than that
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest generated by <command>rndc-confgen -a</command>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest is required, for example if rndc is to be used remotely,
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest you should run <command>rndc-confgen</command> without the
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <command>-a</command> option and set up a
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <filename>rndc.conf</filename> and
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <filename>named.conf</filename>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest as directed.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <term>-b <replaceable class="parameter">keysize</replaceable></term>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest Specifies the size of the authentication key in bits.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest Must be between 1 and 512 bits; the default is 128.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <term>-c <replaceable class="parameter">keyfile</replaceable></term>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest Used with the <command>-a</command> option to specify
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest an alternate location for <filename>rndc.key</filename>.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </varlistentry>
0658c2def78eed17a52f155683b9a77cb200e319Gabor Melkvi
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <term>-h</term>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest Prints a short summary of the options and arguments to
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <command>rndc-confgen</command>.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
0658c2def78eed17a52f155683b9a77cb200e319Gabor Melkvi </listitem>
0658c2def78eed17a52f155683b9a77cb200e319Gabor Melkvi </varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <term>-k <replaceable class="parameter">keyname</replaceable></term>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
0658c2def78eed17a52f155683b9a77cb200e319Gabor Melkvi Specifies the key name of the rndc authentication key.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest This must be a valid domain name.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest The default is <constant>rndc-key</constant>.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <term>-p <replaceable class="parameter">port</replaceable></term>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest Specifies the command channel port where <command>named</command>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest listens for connections from <command>rndc</command>.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest The default is 953.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <term>-r <replaceable class="parameter">randomfile</replaceable></term>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest Specifies a source of random data for generating the
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest authorization. If the operating
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest system does not provide a <filename>/dev/random</filename>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest or equivalent device, the default source of randomness
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest is keyboard input. <filename>randomdev</filename> specifies
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest the name of a character device or file containing random
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest data to be used instead of the default. The special value
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <filename>keyboard</filename> indicates that keyboard
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest input should be used.
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </para>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </listitem>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest </varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <varlistentry>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <term>-s <replaceable class="parameter">address</replaceable></term>
a898afa0c41d5bdca1134dce14666fef3cfed666Andrew Forrest <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:
-->