rndc.conf.docbook revision d4ef65050feac78554addf6e16a06c6e2e0bd331
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - Copyright (C) 2001 Internet Software Consortium.
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - Permission to use, copy, modify, and distribute this software for any
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - purpose with or without fee is hereby granted, provided that the above
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - copyright notice and this permission notice appear in all copies.
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync<!-- $Id: rndc.conf.docbook,v 1.3 2001/06/10 13:57:52 tale Exp $ -->
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync <refentryinfo>
5f2b03bf7695dabd71222dba123532a3f76828c1vboxsync </refentryinfo>
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync <refentrytitle><filename>rndc.conf</filename></refentrytitle>
d4a9d525e6f2111d462d2d96462dced6b9ec00efvboxsync <refnamediv>
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync </refnamediv>
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <refsynopsisdiv>
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <cmdsynopsis>
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync </cmdsynopsis>
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync </refsynopsisdiv>
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <filename>rndc.conf</filename> is the configuration file
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync for <command>rndc</command>, the BIND 9 name server control
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync utility. This file has a similar structure and syntax to
6b9d50a0f466bd5a61458ed53925480ab28a3c17vboxsync <filename>named.conf</filename>. Statements are enclosed
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync in braces and terminated with a semi-colon. Clauses in
6b9d50a0f466bd5a61458ed53925480ab28a3c17vboxsync the statements are also semi-colon terminated. The usual
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync comment styles are supported:
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync C style: /* */
6b9d50a0f466bd5a61458ed53925480ab28a3c17vboxsync C++ style: // to end of line
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync Unix style: # to end of line
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <filename>rndc.conf</filename> is much simpler than
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <filename>named.conf</filename>. The file uses three
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync statements: an options statement, a server statement
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync and a key statement.
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync The <option>options</option> statement contains three clauses.
6b9d50a0f466bd5a61458ed53925480ab28a3c17vboxsync The <option>default-server</option> clause is followed by the
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync name or address of a name server. This host will be used when
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync no name server is given as an argument to
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync <command>rndc</command>. The <option>default-key</option>
c740281e4f5e61397e892447aeef2a7bdbbaaf8dvboxsync clause is followed by the name of a key which is identified by
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync <option>keyid</option> is provided on the rndc command line,
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync and no <option>key</option> clause is found in a matching
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <option>server</option> statement, this default key will be
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync used to authenticate the server's commands and responses. The
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <option>default-port</option> clause is followed by the port
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync to connect to on the remote name server. If no
6b9d50a0f466bd5a61458ed53925480ab28a3c17vboxsync <option>port</option> option is provided on the rndc command
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync line, and no <option>port</option> clause is found in a
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync matching <option>server</option> statement, this default port
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync will be used to connect.
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync After the <option>server</option> keyword, the server statement
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync includes a string which is the hostname or address for a name
3d33b6a3faf40871bae75119c2569cdc4acb2d46vboxsync server. The statement has two possible clauses:
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <option>key</option> and <option>port</option>. The key name must
6b9d50a0f466bd5a61458ed53925480ab28a3c17vboxsync match the name of a key statement in the file. The port number
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync specifies the port to connect to.
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync The <option>key</option> statement begins with an identifying
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync string, the name of the key. The statement has two clauses.
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <option>algorithm</option> identifies the encryption algorithm
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync for <command>rndc</command> to use; currently only HMAC-MD5 is
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync supported. This is followed by a secret clause which contains
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync the base-64 encoding of the algorithm's encryption key. The
6b9d50a0f466bd5a61458ed53925480ab28a3c17vboxsync base-64 string is enclosed in double quotes.
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync There are two common ways to generate the base-64 string for the
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync secret. The BIND 9 program <command>dnssec-keygen</command> can
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync be used to generate a random key, or the
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <command>mimencode</command>, can be used to generate a base-64
6b9d50a0f466bd5a61458ed53925480ab28a3c17vboxsync string from known input. <command>mmencode</command> does not
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync ship with BIND 9 but is available on many systems. See the
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync EXAMPLE section for sample command lines for each.
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync </refsect1>
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <programlisting>
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync default-server localhost;
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync default-key samplekey;
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync server localhost {
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync key samplekey;
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync key samplekey {
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync algorithm hmac-md5;
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync </programlisting>
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync In the above example, <command>rndc</command> will by default use
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync the server at localhost (127.0.0.1) and the key called samplekey.
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync Commands to the localhost server will use the samplekey key, which
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync must also be defined in the server's configuration file with the
c4b821bf03ae7641a0791e3fd161247e66433b68vboxsync same name and secret. The key statement indicates that samplekey
c4b821bf03ae7641a0791e3fd161247e66433b68vboxsync uses the HMAC-MD5 algorithm and its secret clause contains the
c4b821bf03ae7641a0791e3fd161247e66433b68vboxsync base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync To generate a random secret with <command>dnssec-keygen</command>:
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync <userinput>$ dnssec-keygen -a hmac-md5 -b 128 -n user rndc</userinput>
88cc9bf61296bc5526344415167bb2625ae1dd99vboxsync The base-64 string will appear in two files,
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync <filename>Krndc.+157.+{random}.private</filename>. After
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync extracting the key to be placed in the
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync <filename>named.conf</filename> key statements, the
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync .key and .private files can be removed.
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync To generate a random secret with <command>mmencode</command>:
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync <userinput>$ echo "known plaintext for a secret" | mmencode</userinput>
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync </refsect1>
687794577e2e35c3cae67e692a7f2130d1262a82vboxsync The name server must be configured to accept rndc connections and
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync to recognize the key specified in the <filename>rndc.conf</filename>
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync file, using the controls statement in <filename>named.conf</filename>.
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync See the sections on the <option>controls</option> statement in the
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync BIND 9 Administrator Reference Manual for details.
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync </refsect1>
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync <citerefentry>
06ea6bcf23874b662d499b3f130024c98b2dd7a6vboxsync </citerefentry>,
1cd59fdf671ca60c64d77e3f7046aaecf7003824vboxsync <citerefentry>
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync </citerefentry>,
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync <citerefentry>
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync </citerefentry>,
2f3883b126a405f92b19e829472f614c7352b4f9vboxsync <citetitle>BIND 9 Administrator Reference Manual</citetitle>.
0fd108a555ae02f2fb557d5f2c40281999b60d15vboxsync </refsect1>
9523921c89c66f4bececdbd5ac95aed0039eda1bvboxsync <corpauthor>Internet Software Consortium</corpauthor>
06ea6bcf23874b662d499b3f130024c98b2dd7a6vboxsync </refsect1>
9523921c89c66f4bececdbd5ac95aed0039eda1bvboxsync - Local variables:
9523921c89c66f4bececdbd5ac95aed0039eda1bvboxsync - mode: sgml