man.rndc.conf.html revision 60a900e83bab52c3f023be66654f3ab023172778
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - Copyright (C) 2004-2011 Internet Systems Consortium, Inc. ("ISC")
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - Copyright (C) 2000-2003 Internet Software Consortium.
746d35bf3dba3ae5ddbcecb9732f60d5e9de77efTimo Sirainen - Permission to use, copy, modify, and/or distribute this software for any
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - purpose with or without fee is hereby granted, provided that the above
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - copyright notice and this permission notice appear in all copies.
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
43d32cbe60fdaef2699d99f1ca259053e9350411Timo Sirainen - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - PERFORMANCE OF THIS SOFTWARE.
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<!-- $Id: man.rndc.conf.html,v 1.193 2011/03/05 01:14:22 tbox Exp $ -->
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen<link rel="prev" href="man.rndc.html" title="rndc">
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
eb9f7005390bf7d5771d2faedb771ce41103b93aTimo Sirainen<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen<table width="100%" summary="Navigation header">
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
e3689d0f073341e844638f34e1e4d0b7bb053cc8Timo Sirainen<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
eb9f7005390bf7d5771d2faedb771ce41103b93aTimo Sirainen<th width="60%" align="center">Manual pages</th>
eb9f7005390bf7d5771d2faedb771ce41103b93aTimo Sirainen<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
b00eab39755656ee5bac297f5f6ae959da5acef1Timo Sirainen<a name="man.rndc.conf"></a><div class="titlepage"></div>
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen<p><code class="filename">rndc.conf</code> is the configuration file
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen for <span><strong class="command">rndc</strong></span>, the BIND 9 name server control
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen utility. This file has a similar structure and syntax to
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen <code class="filename">named.conf</code>. Statements are enclosed
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen in braces and terminated with a semi-colon. Clauses in
9f57ffa4d421951bbfc7f2de2abcbd8033e6a8c3Timo Sirainen the statements are also semi-colon terminated. The usual
746d35bf3dba3ae5ddbcecb9732f60d5e9de77efTimo Sirainen comment styles are supported:
746d35bf3dba3ae5ddbcecb9732f60d5e9de77efTimo Sirainen C style: /* */
746d35bf3dba3ae5ddbcecb9732f60d5e9de77efTimo Sirainen C++ style: // to end of line
746d35bf3dba3ae5ddbcecb9732f60d5e9de77efTimo Sirainen Unix style: # to end of line
746d35bf3dba3ae5ddbcecb9732f60d5e9de77efTimo Sirainen<p><code class="filename">rndc.conf</code> is much simpler than
746d35bf3dba3ae5ddbcecb9732f60d5e9de77efTimo Sirainen <code class="filename">named.conf</code>. The file uses three
746d35bf3dba3ae5ddbcecb9732f60d5e9de77efTimo Sirainen statements: an options statement, a server statement
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen and a key statement.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen The <code class="option">options</code> statement contains five clauses.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen The <code class="option">default-server</code> clause is followed by the
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen name or address of a name server. This host will be used when
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen no name server is given as an argument to
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <span><strong class="command">rndc</strong></span>. The <code class="option">default-key</code>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen clause is followed by the name of a key which is identified by
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen a <code class="option">key</code> statement. If no
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="option">keyid</code> is provided on the rndc command line,
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen and no <code class="option">key</code> clause is found in a matching
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="option">server</code> statement, this default key will be
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen used to authenticate the server's commands and responses. The
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="option">default-port</code> clause is followed by the port
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen to connect to on the remote name server. If no
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="option">port</code> option is provided on the rndc command
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen line, and no <code class="option">port</code> clause is found in a
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen matching <code class="option">server</code> statement, this default port
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen will be used to connect.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen The <code class="option">default-source-address</code> and
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="option">default-source-address-v6</code> clauses which
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen can be used to set the IPv4 and IPv6 source addresses
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen respectively.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen After the <code class="option">server</code> keyword, the server
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen statement includes a string which is the hostname or address
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen for a name server. The statement has three possible clauses:
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="option">key</code>, <code class="option">port</code> and
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="option">addresses</code>. The key name must match the
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen name of a key statement in the file. The port number
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen specifies the port to connect to. If an <code class="option">addresses</code>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen clause is supplied these addresses will be used instead of
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen the server name. Each address can take an optional port.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen of supplied then these will be used to specify the IPv4 and IPv6
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen source addresses respectively.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen The <code class="option">key</code> statement begins with an identifying
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen string, the name of the key. The statement has two clauses.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="option">algorithm</code> identifies the encryption algorithm
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen for <span><strong class="command">rndc</strong></span> to use; currently only HMAC-MD5
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen supported. This is followed by a secret clause which contains
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen the base-64 encoding of the algorithm's encryption key. The
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen base-64 string is enclosed in double quotes.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen There are two common ways to generate the base-64 string for the
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen be used to generate a random key, or the
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <span><strong class="command">mmencode</strong></span> program, also known as
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <span><strong class="command">mimencode</strong></span>, can be used to generate a
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen string from known input. <span><strong class="command">mmencode</strong></span> does
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen ship with BIND 9 but is available on many systems. See the
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen EXAMPLE section for sample command lines for each.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen default-server localhost;
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen default-key samplekey;
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen server localhost {
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen key samplekey;
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen server testserver {
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen addresses { localhost port 5353; };
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen key samplekey {
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen algorithm hmac-md5;
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen key testkey {
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen algorithm hmac-md5;
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen In the above example, <span><strong class="command">rndc</strong></span> will by
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen the server at localhost (127.0.0.1) and the key called samplekey.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen Commands to the localhost server will use the samplekey key, which
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen must also be defined in the server's configuration file with the
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen same name and secret. The key statement indicates that samplekey
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen uses the HMAC-MD5 algorithm and its secret clause contains the
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen If <span><strong class="command">rndc -s testserver</strong></span> is used then <span><strong class="command">rndc</strong></span> will
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen connect to server on localhost port 5353 using the key testkey.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen To generate a random secret with <span><strong class="command">rndc-confgen</strong></span>:
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<p><strong class="userinput"><code>rndc-confgen</code></strong>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen A complete <code class="filename">rndc.conf</code> file, including
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen randomly generated key, will be written to the standard
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen output. Commented-out <code class="option">key</code> and
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="option">controls</code> statements for
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <code class="filename">named.conf</code> are also printed.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen To generate a base-64 secret with <span><strong class="command">mmencode</strong></span>:
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<a name="id2641372"></a><h2>NAME SERVER CONFIGURATION</h2>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen The name server must be configured to accept rndc connections and
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen to recognize the key specified in the <code class="filename">rndc.conf</code>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen file, using the controls statement in <code class="filename">named.conf</code>.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen See the sections on the <code class="option">controls</code> statement in the
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen BIND 9 Administrator Reference Manual for details.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<p><span class="corpauthor">Internet Systems Consortium</span>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<table width="100%" summary="Navigation footer">
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
8ababf3e7b15f793370d1dedf85825d38b42633fTimo Sirainen<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
746d35bf3dba3ae5ddbcecb9732f60d5e9de77efTimo Sirainen<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>