50066670817cdf9e86c832066d73715232b29680Tinderbox User<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

11e9368a226272085c337e9e74b79808c16fbdbaTinderbox User "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

50066670817cdf9e86c832066d73715232b29680Tinderbox User [<!ENTITY mdash "&#8212;">]>

50066670817cdf9e86c832066d73715232b29680Tinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User<refentry id="man.rndc.conf">

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refentryinfo>

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User <date>June 30, 2000</date>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </refentryinfo>

50066670817cdf9e86c832066d73715232b29680Tinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refmeta>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refentrytitle><filename>rndc.conf</filename></refentrytitle>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <manvolnum>5</manvolnum>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refmiscinfo>BIND9</refmiscinfo>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </refmeta>

50066670817cdf9e86c832066d73715232b29680Tinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refnamediv>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refname><filename>rndc.conf</filename></refname>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refpurpose>rndc configuration file</refpurpose>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </refnamediv>

50066670817cdf9e86c832066d73715232b29680Tinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User <docinfo>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <copyright>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <year>2004</year>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <year>2005</year>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <year>2007</year>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </copyright>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <copyright>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <year>2000</year>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <year>2001</year>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <holder>Internet Software Consortium.</holder>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </copyright>

6f1205897504b8f50b1785975482c995888dd630Tinderbox User </docinfo>

6f1205897504b8f50b1785975482c995888dd630Tinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refsynopsisdiv>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <cmdsynopsis>

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User <command>rndc.conf</command>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </cmdsynopsis>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </refsynopsisdiv>

50066670817cdf9e86c832066d73715232b29680Tinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refsect1>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <title>DESCRIPTION</title>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para><filename>rndc.conf</filename> is the configuration file

50066670817cdf9e86c832066d73715232b29680Tinderbox User for <command>rndc</command>, the BIND 9 name server control

50066670817cdf9e86c832066d73715232b29680Tinderbox User utility. This file has a similar structure and syntax to

50066670817cdf9e86c832066d73715232b29680Tinderbox User <filename>named.conf</filename>. Statements are enclosed

50066670817cdf9e86c832066d73715232b29680Tinderbox User in braces and terminated with a semi-colon. Clauses in

50066670817cdf9e86c832066d73715232b29680Tinderbox User the statements are also semi-colon terminated. The usual

50066670817cdf9e86c832066d73715232b29680Tinderbox User comment styles are supported:

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User C style: /* */

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User C++ style: // to end of line

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User <para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User Unix style: # to end of line

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para><filename>rndc.conf</filename> is much simpler than

50066670817cdf9e86c832066d73715232b29680Tinderbox User <filename>named.conf</filename>. The file uses three

50066670817cdf9e86c832066d73715232b29680Tinderbox User statements: an options statement, a server statement

50066670817cdf9e86c832066d73715232b29680Tinderbox User and a key statement.

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User The <option>options</option> statement contains five clauses.

50066670817cdf9e86c832066d73715232b29680Tinderbox User The <option>default-server</option> clause is followed by the

50066670817cdf9e86c832066d73715232b29680Tinderbox User name or address of a name server. This host will be used when

50066670817cdf9e86c832066d73715232b29680Tinderbox User no name server is given as an argument to

50066670817cdf9e86c832066d73715232b29680Tinderbox User <command>rndc</command>. The <option>default-key</option>

50066670817cdf9e86c832066d73715232b29680Tinderbox User clause is followed by the name of a key which is identified by

50066670817cdf9e86c832066d73715232b29680Tinderbox User a <option>key</option> statement. If no

50066670817cdf9e86c832066d73715232b29680Tinderbox User <option>keyid</option> is provided on the rndc command line,

50066670817cdf9e86c832066d73715232b29680Tinderbox User and no <option>key</option> clause is found in a matching

50066670817cdf9e86c832066d73715232b29680Tinderbox User <option>server</option> statement, this default key will be

50066670817cdf9e86c832066d73715232b29680Tinderbox User used to authenticate the server's commands and responses. The

50066670817cdf9e86c832066d73715232b29680Tinderbox User <option>default-port</option> clause is followed by the port

50066670817cdf9e86c832066d73715232b29680Tinderbox User to connect to on the remote name server. If no

50066670817cdf9e86c832066d73715232b29680Tinderbox User <option>port</option> option is provided on the rndc command

50066670817cdf9e86c832066d73715232b29680Tinderbox User line, and no <option>port</option> clause is found in a

50066670817cdf9e86c832066d73715232b29680Tinderbox User matching <option>server</option> statement, this default port

50066670817cdf9e86c832066d73715232b29680Tinderbox User will be used to connect.

50066670817cdf9e86c832066d73715232b29680Tinderbox User The <option>default-source-address</option> and

50066670817cdf9e86c832066d73715232b29680Tinderbox User <option>default-source-address-v6</option> clauses which

50066670817cdf9e86c832066d73715232b29680Tinderbox User can be used to set the IPv4 and IPv6 source addresses

50066670817cdf9e86c832066d73715232b29680Tinderbox User respectively.

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User After the <option>server</option> keyword, the server

50066670817cdf9e86c832066d73715232b29680Tinderbox User statement includes a string which is the hostname or address

50066670817cdf9e86c832066d73715232b29680Tinderbox User for a name server. The statement has three possible clauses:

50066670817cdf9e86c832066d73715232b29680Tinderbox User <option>key</option>, <option>port</option> and

6f1205897504b8f50b1785975482c995888dd630Tinderbox User <option>addresses</option>. The key name must match the

6f1205897504b8f50b1785975482c995888dd630Tinderbox User name of a key statement in the file. The port number

6f1205897504b8f50b1785975482c995888dd630Tinderbox User specifies the port to connect to. If an <option>addresses</option>

6f1205897504b8f50b1785975482c995888dd630Tinderbox User clause is supplied these addresses will be used instead of

50066670817cdf9e86c832066d73715232b29680Tinderbox User the server name. Each address can take a optional port.

50066670817cdf9e86c832066d73715232b29680Tinderbox User If an <option>source-address</option> or <option>source-address-v6</option>

50066670817cdf9e86c832066d73715232b29680Tinderbox User of supplied then these will be used to specify the IPv4 and IPv6

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User source addresses respectively.

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User The <option>key</option> statement begins with an identifying

50066670817cdf9e86c832066d73715232b29680Tinderbox User string, the name of the key. The statement has two clauses.

50066670817cdf9e86c832066d73715232b29680Tinderbox User <option>algorithm</option> identifies the encryption algorithm

50066670817cdf9e86c832066d73715232b29680Tinderbox User for <command>rndc</command> to use; currently only HMAC-MD5

50066670817cdf9e86c832066d73715232b29680Tinderbox User is

50066670817cdf9e86c832066d73715232b29680Tinderbox User supported. This is followed by a secret clause which contains

50066670817cdf9e86c832066d73715232b29680Tinderbox User the base-64 encoding of the algorithm's encryption key. The

50066670817cdf9e86c832066d73715232b29680Tinderbox User base-64 string is enclosed in double quotes.

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User There are two common ways to generate the base-64 string for the

50066670817cdf9e86c832066d73715232b29680Tinderbox User secret. The BIND 9 program <command>rndc-confgen</command>

50066670817cdf9e86c832066d73715232b29680Tinderbox User can

50066670817cdf9e86c832066d73715232b29680Tinderbox User be used to generate a random key, or the

50066670817cdf9e86c832066d73715232b29680Tinderbox User <command>mmencode</command> program, also known as

50066670817cdf9e86c832066d73715232b29680Tinderbox User <command>mimencode</command>, can be used to generate a

50066670817cdf9e86c832066d73715232b29680Tinderbox User base-64

50066670817cdf9e86c832066d73715232b29680Tinderbox User string from known input. <command>mmencode</command> does

50066670817cdf9e86c832066d73715232b29680Tinderbox User not

50066670817cdf9e86c832066d73715232b29680Tinderbox User ship with BIND 9 but is available on many systems. See the

50066670817cdf9e86c832066d73715232b29680Tinderbox User EXAMPLE section for sample command lines for each.

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </refsect1>

50066670817cdf9e86c832066d73715232b29680Tinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User <refsect1>

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User <title>EXAMPLE</title>

50066670817cdf9e86c832066d73715232b29680Tinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para><programlisting>

50066670817cdf9e86c832066d73715232b29680Tinderbox User options {

50066670817cdf9e86c832066d73715232b29680Tinderbox User default-server localhost;

50066670817cdf9e86c832066d73715232b29680Tinderbox User default-key samplekey;

50066670817cdf9e86c832066d73715232b29680Tinderbox User };

50066670817cdf9e86c832066d73715232b29680Tinderbox User</programlisting>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User <para><programlisting>

50066670817cdf9e86c832066d73715232b29680Tinderbox User server localhost {

50066670817cdf9e86c832066d73715232b29680Tinderbox User key samplekey;

50066670817cdf9e86c832066d73715232b29680Tinderbox User };

50066670817cdf9e86c832066d73715232b29680Tinderbox User</programlisting>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para><programlisting>

50066670817cdf9e86c832066d73715232b29680Tinderbox User server testserver {

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User key testkey;

50066670817cdf9e86c832066d73715232b29680Tinderbox User addresses { localhost port 5353; };

50066670817cdf9e86c832066d73715232b29680Tinderbox User };

50066670817cdf9e86c832066d73715232b29680Tinderbox User</programlisting>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para><programlisting>

50066670817cdf9e86c832066d73715232b29680Tinderbox User key samplekey {

50066670817cdf9e86c832066d73715232b29680Tinderbox User algorithm hmac-md5;

50066670817cdf9e86c832066d73715232b29680Tinderbox User secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";

50066670817cdf9e86c832066d73715232b29680Tinderbox User };

50066670817cdf9e86c832066d73715232b29680Tinderbox User</programlisting>

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para><programlisting>

50066670817cdf9e86c832066d73715232b29680Tinderbox User key testkey {

50066670817cdf9e86c832066d73715232b29680Tinderbox User algorithm hmac-md5;

50066670817cdf9e86c832066d73715232b29680Tinderbox User secret "R3HI8P6BKw9ZwXwN3VZKuQ==";

50066670817cdf9e86c832066d73715232b29680Tinderbox User };

50066670817cdf9e86c832066d73715232b29680Tinderbox User </programlisting>

50066670817cdf9e86c832066d73715232b29680Tinderbox User </para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User

50066670817cdf9e86c832066d73715232b29680Tinderbox User <para>

50066670817cdf9e86c832066d73715232b29680Tinderbox User In the above example, <command>rndc</command> will by

50066670817cdf9e86c832066d73715232b29680Tinderbox User default use

50066670817cdf9e86c832066d73715232b29680Tinderbox User the server at localhost (127.0.0.1) and the key called samplekey.

30c0c7470d5bfabd8f43c563f4eca636d06cc484Tinderbox User Commands to the localhost server will use the samplekey key, which

50066670817cdf9e86c832066d73715232b29680Tinderbox User must also be defined in the server's configuration file with the

50066670817cdf9e86c832066d73715232b29680Tinderbox User same name and secret. The key statement indicates that samplekey

uses the HMAC-MD5 algorithm and its secret clause contains the

base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.

</para>

<para>

If <command>rndc -s testserver</command> is used then <command>rndc</command> will

connect to server on localhost port 5353 using the key testkey.

</para>

<para>

To generate a random secret with <command>rndc-confgen</command>:

</para>

<para><userinput>rndc-confgen</userinput>

</para>

<para>

A complete <filename>rndc.conf</filename> file, including

the

randomly generated key, will be written to the standard

output. Commented-out <option>key</option> and

<option>controls</option> statements for

<filename>named.conf</filename> are also printed.

</para>

<para>

To generate a base-64 secret with <command>mmencode</command>:

</para>

<para><userinput>echo "known plaintext for a secret" | mmencode</userinput>

</para>

</refsect1>

<refsect1>

<title>NAME SERVER CONFIGURATION</title>

<para>

The name server must be configured to accept rndc connections and

to recognize the key specified in the <filename>rndc.conf</filename>

file, using the controls statement in <filename>named.conf</filename>.

See the sections on the <option>controls</option> statement in the

BIND 9 Administrator Reference Manual for details.

</para>

</refsect1>

<refsect1>

<title>SEE ALSO</title>

<para><citerefentry>

<refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>rndc-confgen</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>mmencode</refentrytitle><manvolnum>1</manvolnum>

</citerefentry>,

<citetitle>BIND 9 Administrator Reference Manual</citetitle>.

</para>

</refsect1>

<refsect1>

<title>AUTHOR</title>

<para><corpauthor>Internet Systems Consortium</corpauthor>

</para>

</refsect1>

</refentry><!--