rndc.docbook revision 17cb8353e999e3294e6619613f401af3f7b1540c
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
499b34cea04a46823d003d4c0520c8b03e8513cbBrian Wellington<!--
816e576f77e2c46df3e3d97d65822aa8aded7c4bDavid Lawrence - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
9bff67898d55cddfcec9ce30cc2b1bb6211ec691David Lawrence - Copyright (C) 2001 Internet Software Consortium.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews -
9c3531d72aeaad6c5f01efe6a1c82023e1379e4dDavid Lawrence - Permission to use, copy, modify, and distribute this software for any
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence - purpose with or without fee is hereby granted, provided that the above
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence - copyright notice and this permission notice appear in all copies.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence -
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence - PERFORMANCE OF THIS SOFTWARE.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence-->
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence<!-- $Id: rndc.docbook,v 1.9 2004/06/03 02:22:33 marka Exp $ -->
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence<refentry>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refentryinfo>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <date>June 30, 2000</date>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </refentryinfo>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refmeta>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refentrytitle><application>rndc</application></refentrytitle>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <manvolnum>8</manvolnum>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refmiscinfo>BIND9</refmiscinfo>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </refmeta>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refnamediv>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refname><application>rndc</application></refname>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refpurpose>name server control utility</refpurpose>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </refnamediv>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refsynopsisdiv>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <cmdsynopsis>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <command>rndc</command>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence <arg><option>-k <replaceable class="parameter">key-file</replaceable></option></arg>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <arg><option>-s <replaceable class="parameter">server</replaceable></option></arg>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <arg><option>-p <replaceable class="parameter">port</replaceable></option></arg>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <arg><option>-V</option></arg>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <arg><option>-y <replaceable class="parameter">key_id</replaceable></option></arg>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <arg choice="req">command</arg>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </cmdsynopsis>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </refsynopsisdiv>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refsect1>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <title>DESCRIPTION</title>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <command>rndc</command> controls the operation of a name
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence server. It supersedes the <command>ndc</command> utility
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence that was provided in old BIND releases. If
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <command>rndc</command> is invoked with no command line
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence options or arguments, it prints a short summary of the
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence supported commands and the available options and their
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence arguments.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <command>rndc</command> communicates with the name server
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence over a TCP connection, sending commands authenticated with
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence digital signatures. In the current versions of
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <command>rndc</command> and <command>named</command> named
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence the only supported authentication algorithm is HMAC-MD5,
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence which uses a shared secret on each end of the connection.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence This provides TSIG-style authentication for the command
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence request and the name server's response. All commands sent
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence over the channel must be signed by a key_id known to the
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence server.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <command>rndc</command> reads a configuration file to
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence determine how to contact the name server and decide what
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence algorithm and key it should use.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </refsect1>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <refsect1>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <title>OPTIONS</title>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <variablelist>
f8a95eb9127a97e81ad4f1295a9d1abce993ef63David Lawrence <varlistentry>
f8a95eb9127a97e81ad4f1295a9d1abce993ef63David Lawrence <term>-c <replaceable class="parameter">config-file</replaceable></term>
f8a95eb9127a97e81ad4f1295a9d1abce993ef63David Lawrence <listitem>
f8a95eb9127a97e81ad4f1295a9d1abce993ef63David Lawrence <para>
f8a95eb9127a97e81ad4f1295a9d1abce993ef63David Lawrence Use <replaceable class="parameter">config-file</replaceable>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence as the configuration file instead of the default,
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <filename>/etc/rndc.conf</filename>.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </listitem>
f8a95eb9127a97e81ad4f1295a9d1abce993ef63David Lawrence </varlistentry>
f8a95eb9127a97e81ad4f1295a9d1abce993ef63David Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <varlistentry>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <term>-k <replaceable class="parameter">key-file</replaceable></term>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <listitem>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence Use <replaceable class="parameter">key-file</replaceable>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence as the key file instead of the default,
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <filename>/etc/rndc.key</filename>. The key in
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <filename>/etc/rndc.key</filename> will be used to authenticate
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence commands sent to the server if the <replaceable class="parameter">config-file</replaceable>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence does not exist.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </listitem>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </varlistentry>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <varlistentry>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <term>-s <replaceable class="parameter">server</replaceable></term>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <listitem>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <replaceable class="parameter">server</replaceable> is
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence the name or address of the server which matches a
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence server statement in the configuration file for
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <command>rndc</command>. If no server is supplied on the
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence command line, the host named by the default-server clause
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence in the option statement of the configuration file will be
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence used.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </listitem>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </varlistentry>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <varlistentry>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <term>-p <replaceable class="parameter">port</replaceable></term>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <listitem>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence Send commands to TCP port
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <replaceable class="parameter">port</replaceable> instead
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence of BIND 9's default control channel port, 953.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </listitem>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </varlistentry>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <varlistentry>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <term>-V</term>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <listitem>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence <para>
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence Enable verbose logging.
487e6abc16c1b2958d371b0d4e808953646b520aDavid Lawrence </para>
</listitem>
</varlistentry>
<varlistentry>
<term>-y <replaceable class="parameter">keyid</replaceable></term>
<listitem>
<para>
Use the key <replaceable class="parameter">keyid</replaceable>
from the configuration file.
<replaceable class="parameter">keyid</replaceable> must be
known by named with the same algorithm and secret string
in order for control message validation to succeed.
If no <replaceable class="parameter">keyid</replaceable>
is specified, <command>rndc</command> will first look
for a key clause in the server statement of the server
being used, or if no server statement is present for that
host, then the default-key clause of the options statement.
Note that the configuration file contains shared secrets
which are used to send authenticated control commands
to name servers. It should therefore not have general read
or write access.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
For the complete set of commands supported by <command>rndc</command>,
see the BIND 9 Administrator Reference Manual or run
<command>rndc</command> without arguments to see its help message.
</para>
</refsect1>
<refsect1>
<title>LIMITATIONS</title>
<para>
<command>rndc</command> does not yet support all the commands of
the BIND 8 <command>ndc</command> utility.
</para>
<para>
There is currently no way to provide the shared secret for a
<option>key_id</option> without using the configuration file.
</para>
<para>
Several error messages could be clearer.
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>rndc.conf</refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>named</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>named.conf</refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>
<citerefentry>
<refentrytitle>ndc</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:
-->