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