d29201dd5328b88140ce050100693c501852657dChristian Maeder<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

211c5fb252e0a776baad9a4857ab198659289a4aKristina Sojakova "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

211c5fb252e0a776baad9a4857ab198659289a4aKristina Sojakova [<!ENTITY mdash "&#8212;">]>

8b054cade993ef373d564b2d74c9c5a2da48f8b7Kristina Sojakova

9f8b6c20948cc102562f8ad0c39a4b5e3855b02fKristina Sojakova<refentry id="man.rndc.conf">

8b054cade993ef373d564b2d74c9c5a2da48f8b7Kristina Sojakova <refentryinfo>

2ddc9d39235393dca2e40203dde20284db4c3deeKristina Sojakova <date>June 30, 2000</date>

2ddc9d39235393dca2e40203dde20284db4c3deeKristina Sojakova </refentryinfo>

45caf47cd6ed07be0637f6c51e4735512ce9d83aKristina Sojakova

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <refmeta>

345d3dcc9f809776009851c446916fc770aa428dKristina Sojakova <refentrytitle><filename>rndc.conf</filename></refentrytitle>

63dbf3642c023a8bebbc8ca0d56f698114551c8cKristina Sojakova <manvolnum>5</manvolnum>

63dbf3642c023a8bebbc8ca0d56f698114551c8cKristina Sojakova <refmiscinfo>BIND9</refmiscinfo>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova </refmeta>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <refnamediv>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <refname><filename>rndc.conf</filename></refname>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <refpurpose>rndc configuration file</refpurpose>

dd6f22b9dcff2695181b86372e4df03d5b96e92dKristina Sojakova </refnamediv>

dd6f22b9dcff2695181b86372e4df03d5b96e92dKristina Sojakova

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <docinfo>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <copyright>

8b054cade993ef373d564b2d74c9c5a2da48f8b7Kristina Sojakova <year>2004</year>

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder <year>2005</year>

51bbd37b3957f301b2628422e161aac2cbd46f1cKristina Sojakova <year>2007</year>

51bbd37b3957f301b2628422e161aac2cbd46f1cKristina Sojakova <year>2013</year>

14650c9e129d8dc51ed55b2edc6ec27d9f0f6d00Kristina Sojakova <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder </copyright>

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder <copyright>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <year>2000</year>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <year>2001</year>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <holder>Internet Software Consortium.</holder>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova </copyright>

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder </docinfo>

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <refsynopsisdiv>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <cmdsynopsis>

345d3dcc9f809776009851c446916fc770aa428dKristina Sojakova <command>rndc.conf</command>

a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder </cmdsynopsis>

a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder </refsynopsisdiv>

63dbf3642c023a8bebbc8ca0d56f698114551c8cKristina Sojakova

cb5d588c4c3b286cc1e7210335d6ef7f584d79bcKristina Sojakova <refsect1>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <title>DESCRIPTION</title>

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <para><filename>rndc.conf</filename> is the configuration file

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder for <command>rndc</command>, the BIND 9 name server control

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder utility. This file has a similar structure and syntax to

2fa2a7c86b9416f0e1607787e9416e274feb1143Christian Maeder <filename>named.conf</filename>. Statements are enclosed

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder in braces and terminated with a semi-colon. Clauses in

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder the statements are also semi-colon terminated. The usual

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder comment styles are supported:

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder </para>

2fa2a7c86b9416f0e1607787e9416e274feb1143Christian Maeder <para>

2ddc9d39235393dca2e40203dde20284db4c3deeKristina Sojakova C style: /* */

8b054cade993ef373d564b2d74c9c5a2da48f8b7Kristina Sojakova </para>

2ddc9d39235393dca2e40203dde20284db4c3deeKristina Sojakova <para>

a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder C++ style: // to end of line

80d2ec8f37d5ddec13c14b17b1bab01e9c94630aChristian Maeder </para>

c82e21a85ef57135a0c582ca0f418b1541151645Kristina Sojakova <para>

63dbf3642c023a8bebbc8ca0d56f698114551c8cKristina Sojakova Unix style: # to end of line

c82e21a85ef57135a0c582ca0f418b1541151645Kristina Sojakova </para>

8b054cade993ef373d564b2d74c9c5a2da48f8b7Kristina Sojakova <para><filename>rndc.conf</filename> is much simpler than

a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder <filename>named.conf</filename>. The file uses three

9d770d1ea15092156d65e2a89b081eeeb8c6b153Kristina Sojakova statements: an options statement, a server statement

9d770d1ea15092156d65e2a89b081eeeb8c6b153Kristina Sojakova and a key statement.

a669e4685b32ff5ca1bca785eacc5e30a545b010Christian Maeder </para>

9d770d1ea15092156d65e2a89b081eeeb8c6b153Kristina Sojakova <para>

63dbf3642c023a8bebbc8ca0d56f698114551c8cKristina Sojakova The <option>options</option> statement contains five clauses.

63dbf3642c023a8bebbc8ca0d56f698114551c8cKristina Sojakova The <option>default-server</option> clause is followed by the

45caf47cd6ed07be0637f6c51e4735512ce9d83aKristina Sojakova name or address of a name server. This host will be used when

df31d6f25f90e5112184f4eb60c8d3c7b116ca2dKristina Sojakova no name server is given as an argument to

df31d6f25f90e5112184f4eb60c8d3c7b116ca2dKristina Sojakova <command>rndc</command>. The <option>default-key</option>

345a7bff808e621f05d2ce86fdbab2a28c9e0d3dKristina Sojakova clause is followed by the name of a key which is identified by

cb5d588c4c3b286cc1e7210335d6ef7f584d79bcKristina Sojakova a <option>key</option> statement. If no

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova <option>keyid</option> is provided on the rndc command line,

150dbefbeef7403ab31ecbf9c3bb56515be67cdfKristina Sojakova and no <option>key</option> clause is found in a matching

4b61e23f57d9d13d036aedb1b10178d3e013ab38Kristina Sojakova <option>server</option> statement, this default key will be

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder used to authenticate the server's commands and responses. The

2fa2a7c86b9416f0e1607787e9416e274feb1143Christian Maeder <option>default-port</option> clause is followed by the port

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder to connect to on the remote name server. If no

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder <option>port</option> option is provided on the rndc command

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder line, and no <option>port</option> clause is found in a

9be5b6267dea82f0eb283bd4ae9d4f83e05a6944Christian Maeder matching <option>server</option> statement, this default port

2fa2a7c86b9416f0e1607787e9416e274feb1143Christian Maeder will be used to connect.

2ddc9d39235393dca2e40203dde20284db4c3deeKristina Sojakova The <option>default-source-address</option> and

4b61e23f57d9d13d036aedb1b10178d3e013ab38Kristina Sojakova <option>default-source-address-v6</option> clauses which

345d3dcc9f809776009851c446916fc770aa428dKristina Sojakova can be used to set the IPv4 and IPv6 source addresses

345d3dcc9f809776009851c446916fc770aa428dKristina Sojakova respectively.

345d3dcc9f809776009851c446916fc770aa428dKristina Sojakova </para>

345d3dcc9f809776009851c446916fc770aa428dKristina Sojakova <para>

After the <option>server</option> keyword, the server

statement includes a string which is the hostname or address

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

<option>key</option>, <option>port</option> and

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

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

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

clause is supplied these addresses will be used instead of

the server name. Each address can take an optional port.

If an <option>source-address</option> or <option>source-address-v6</option>

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

source addresses respectively.

</para>

<para>

The <option>key</option> statement begins with an identifying

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

<option>algorithm</option> identifies the authentication algorithm

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

(for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256

(default), HMAC-SHA384 and HMAC-SHA512 are

supported. This is followed by a secret clause which contains

the base-64 encoding of the algorithm's authentication key. The

base-64 string is enclosed in double quotes.

</para>

<para>

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

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

can

be used to generate a random key, or the

<command>mmencode</command> program, also known as

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

base-64

string from known input. <command>mmencode</command> does

not

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

EXAMPLE section for sample command lines for each.

</para>

</refsect1>

<refsect1>

<title>EXAMPLE</title>

<para><programlisting>

options {

default-server localhost;

default-key samplekey;

};

</programlisting>

</para>

<para><programlisting>

server localhost {

key samplekey;

};

</programlisting>

</para>

<para><programlisting>

server testserver {

key testkey;

addresses { localhost port 5353; };

};

</programlisting>

</para>

<para><programlisting>

key samplekey {

algorithm hmac-sha256;

secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";

};

</programlisting>

</para>

<para><programlisting>

key testkey {

algorithm hmac-sha256;

secret "R3HI8P6BKw9ZwXwN3VZKuQ==";

};

</programlisting>

</para>

<para>

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

default use

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

Commands to the localhost server will use the samplekey key, which

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

same name and secret. The key statement indicates that samplekey

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

base-64 encoding of the HMAC-SHA256 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><!--