3N/A<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

3N/A "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

3N/A [<!ENTITY mdash "&#8212;">]>

3N/A

3N/A<refentry id="man.rndc.conf">

3N/A <refentryinfo>

3N/A <date>June 30, 2000</date>

3N/A </refentryinfo>

3N/A

3N/A <refmeta>

3N/A <refentrytitle><filename>rndc.conf</filename></refentrytitle>

3N/A <manvolnum>5</manvolnum>

3N/A <refmiscinfo>BIND9</refmiscinfo>

3N/A </refmeta>

3N/A

3N/A <refnamediv>

3N/A <refname><filename>rndc.conf</filename></refname>

3N/A <refpurpose>rndc configuration file</refpurpose>

3N/A </refnamediv>

30N/A

89N/A <docinfo>

3N/A <copyright>

3N/A <year>2004</year>

3N/A <year>2005</year>

3N/A <year>2007</year>

3N/A <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

3N/A </copyright>

3N/A <copyright>

3N/A <year>2000</year>

3N/A <year>2001</year>

193N/A <holder>Internet Software Consortium.</holder>

193N/A </copyright>

193N/A </docinfo>

3N/A

30N/A <refsynopsisdiv>

89N/A <cmdsynopsis>

3N/A <command>rndc.conf</command>

3N/A </cmdsynopsis>

3N/A </refsynopsisdiv>

3N/A

3N/A <refsect1>

3N/A <title>DESCRIPTION</title>

3N/A <para><filename>rndc.conf</filename> is the configuration file

3N/A for <command>rndc</command>, the BIND 9 name server control

3N/A utility. This file has a similar structure and syntax to

3N/A <filename>named.conf</filename>. Statements are enclosed

3N/A in braces and terminated with a semi-colon. Clauses in

89N/A the statements are also semi-colon terminated. The usual

3N/A comment styles are supported:

3N/A </para>

3N/A <para>

3N/A C style: /* */

89N/A </para>

3N/A <para>

3N/A C++ style: // to end of line

3N/A </para>

3N/A <para>

3N/A Unix style: # to end of line

3N/A </para>

3N/A <para><filename>rndc.conf</filename> is much simpler than

3N/A <filename>named.conf</filename>. The file uses three

3N/A statements: an options statement, a server statement

3N/A and a key statement.

3N/A </para>

3N/A <para>

3N/A The <option>options</option> statement contains five clauses.

3N/A The <option>default-server</option> clause is followed by the

3N/A name or address of a name server. This host will be used when

3N/A no name server is given as an argument to

3N/A <command>rndc</command>. The <option>default-key</option>

3N/A clause is followed by the name of a key which is identified by

3N/A a <option>key</option> statement. If no

3N/A <option>keyid</option> is provided on the rndc command line,

3N/A and no <option>key</option> clause is found in a matching

3N/A <option>server</option> statement, this default key will be

3N/A used to authenticate the server's commands and responses. The

3N/A <option>default-port</option> clause is followed by the port

3N/A to connect to on the remote name server. If no

3N/A <option>port</option> option is provided on the rndc command

3N/A line, and no <option>port</option> clause is found in a

3N/A matching <option>server</option> statement, this default port

3N/A will be used to connect.

3N/A The <option>default-source-address</option> and

3N/A <option>default-source-address-v6</option> clauses which

3N/A can be used to set the IPv4 and IPv6 source addresses

193N/A respectively.

3N/A </para>

3N/A <para>

3N/A After the <option>server</option> keyword, the server

3N/A statement includes a string which is the hostname or address

3N/A for a name server. The statement has three possible clauses:

3N/A <option>key</option>, <option>port</option> and

3N/A <option>addresses</option>. The key name must match the

3N/A name of a key statement in the file. The port number

3N/A specifies the port to connect to. If an <option>addresses</option>

3N/A clause is supplied these addresses will be used instead of

193N/A the server name. Each address can take a optional port.

193N/A If an <option>source-address</option> or <option>source-address-v6</option>

193N/A of supplied then these will be used to specify the IPv4 and IPv6

3N/A source addresses respectively.

3N/A </para>

3N/A <para>

3N/A The <option>key</option> statement begins with an identifying

3N/A string, the name of the key. The statement has two clauses.

3N/A <option>algorithm</option> identifies the encryption algorithm

3N/A for <command>rndc</command> to use; currently only HMAC-MD5

3N/A is

3N/A supported. This is followed by a secret clause which contains

3N/A the base-64 encoding of the algorithm's encryption key. The

3N/A base-64 string is enclosed in double quotes.

3N/A </para>

3N/A <para>

3N/A There are two common ways to generate the base-64 string for the

161N/A secret. The BIND 9 program <command>rndc-confgen</command>

161N/A can

161N/A be used to generate a random key, or the

161N/A <command>mmencode</command> program, also known as

161N/A <command>mimencode</command>, can be used to generate a

161N/A base-64

3N/A string from known input. <command>mmencode</command> does

3N/A not

3N/A ship with BIND 9 but is available on many systems. See the

3N/A EXAMPLE section for sample command lines for each.

3N/A </para>

3N/A </refsect1>

3N/A

3N/A <refsect1>

3N/A <title>EXAMPLE</title>

3N/A

3N/A <para><programlisting>

3N/A options {

3N/A default-server localhost;

3N/A default-key samplekey;

3N/A };

3N/A</programlisting>

3N/A </para>

3N/A <para><programlisting>

3N/A server localhost {

3N/A key samplekey;

3N/A };

3N/A</programlisting>

3N/A </para>

3N/A <para><programlisting>

3N/A server testserver {

3N/A key testkey;

3N/A addresses { localhost port 5353; };

3N/A };

3N/A</programlisting>

3N/A </para>

3N/A <para><programlisting>

3N/A key samplekey {

3N/A algorithm hmac-md5;

3N/A secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";

3N/A };

3N/A</programlisting>

3N/A </para>

3N/A <para><programlisting>

3N/A key testkey {

3N/A algorithm hmac-md5;

3N/A secret "R3HI8P6BKw9ZwXwN3VZKuQ==";

3N/A };

3N/A </programlisting>

3N/A </para>

3N/A

3N/A <para>

193N/A In the above example, <command>rndc</command> will by

3N/A default use

3N/A the server at localhost (127.0.0.1) and the key called samplekey.

3N/A Commands to the localhost server will use the samplekey key, which

3N/A must also be defined in the server's configuration file with the

3N/A same name and secret. The key statement indicates that samplekey

3N/A uses the HMAC-MD5 algorithm and its secret clause contains the

3N/A base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.

3N/A </para>

3N/A <para>

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

3N/A connect to server on localhost port 5353 using the key testkey.

3N/A </para>

3N/A <para>

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

3N/A </para>

3N/A <para><userinput>rndc-confgen</userinput>

3N/A </para>

3N/A <para>

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

3N/A the

3N/A randomly generated key, will be written to the standard

3N/A output. Commented-out <option>key</option> and

193N/A <option>controls</option> statements for

193N/A <filename>named.conf</filename> are also printed.

193N/A </para>

193N/A <para>

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

193N/A </para>

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

193N/A </para>

193N/A </refsect1>

193N/A

193N/A <refsect1>

193N/A <title>NAME SERVER CONFIGURATION</title>

193N/A <para>

193N/A The name server must be configured to accept rndc connections and

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

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

89N/A See the sections on the <option>controls</option> statement in the

89N/A BIND 9 Administrator Reference Manual for details.

89N/A </para>

3N/A </refsect1>

3N/A

3N/A <refsect1>

193N/A <title>SEE ALSO</title>

3N/A <para><citerefentry>

3N/A <refentrytitle>rndc</refentrytitle><manvolnum>8</manvolnum>

3N/A </citerefentry>,

89N/A <citerefentry>

3N/A <refentrytitle>rndc-confgen</refentrytitle><manvolnum>8</manvolnum>

3N/A </citerefentry>,

3N/A <citerefentry>

3N/A <refentrytitle>mmencode</refentrytitle><manvolnum>1</manvolnum>

3N/A </citerefentry>,

193N/A <citetitle>BIND 9 Administrator Reference Manual</citetitle>.

3N/A </para>

3N/A </refsect1>

3N/A

3N/A <refsect1>

3N/A <title>AUTHOR</title>

3N/A <para><corpauthor>Internet Systems Consortium</corpauthor>

3N/A </para>

3N/A </refsect1>

3N/A

3N/A</refentry><!--

3N/A