man.rndc.conf.html revision cedb0bd0c1e3c461b7e479a16d3adfd5b150f1f4
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale<!--
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale - Copyright (C) 2000-2003 Internet Software Consortium.
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale -
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale - Permission to use, copy, modify, and distribute this software for any
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale - purpose with or without fee is hereby granted, provided that the above
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale - copyright notice and this permission notice appear in all copies.
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale -
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
0075dcb5aeeee4864fe9f64db82c8a8202bbe6d6henning mueller - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
ea54729650a50426c770cb0f2999c478f18d3258Daniel Couto Vale - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
f9c64720306a03102ed06e2e497c8f7d5bd0910aChristian Clausen - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
64533bb0160210256e0a393ea102a4c4f1cc8ecaChristian Clausen - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
45099b8d596ab49a700a8c2c6761cf9ca0d101c4Till Mossakowski - PERFORMANCE OF THIS SOFTWARE.
45099b8d596ab49a700a8c2c6761cf9ca0d101c4Till Mossakowski-->
45099b8d596ab49a700a8c2c6761cf9ca0d101c4Till Mossakowski<!-- $Id: man.rndc.conf.html,v 1.9 2005/10/13 03:14:05 marka Exp $ -->
45099b8d596ab49a700a8c2c6761cf9ca0d101c4Till Mossakowski<html>
d95c0de1fbdb66e2aa8d2dc223ad554413f1dc87Julian Kornberger<head>
e165d93c5dc7e3989fdbde84d77e7ffdd40d73e2Daniel Vale<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen<title>rndc.conf</title>
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale<link rel="up" href="Bv9ARM.ch10.html" title="Manual pages">
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale<link rel="prev" href="man.rndc.html" title="rndc">
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
db07a36c8d27cd066338f3e1f4c3ea9cbbd027fdDaniel Couto Vale</head>
d27bf65fca64c4f86177742c215f0705017aad47Christian Clausen<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
040c1d8fca47a84f09d96ca3c21caa0a2ed91e05henning mueller<div class="navheader">
8ecd6803a4d72196f2e8301c538d7570182fcaadChristian Clausen<table width="100%" summary="Navigation header">
040c1d8fca47a84f09d96ca3c21caa0a2ed91e05henning mueller<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
040c1d8fca47a84f09d96ca3c21caa0a2ed91e05henning mueller<tr>
040c1d8fca47a84f09d96ca3c21caa0a2ed91e05henning mueller<td width="20%" align="left">
040c1d8fca47a84f09d96ca3c21caa0a2ed91e05henning mueller<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
b816481ff5d2fd822a5c616daa03e94d2775594bTill Mossakowski<th width="60%" align="center">Manual pages</th>
b816481ff5d2fd822a5c616daa03e94d2775594bTill Mossakowski<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
8e9749fa7f715b073417d5629d4a14135369d297Daniel Couto Vale</td>
a0bfc54a3228b92b67f0338efd46be08265cd26fDaniel Vale</tr>
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen</table>
0cd37f42517da8081f1e90a0fdfbb82a526c1704henning mueller<hr>
0cd37f42517da8081f1e90a0fdfbb82a526c1704henning mueller</div>
0cd37f42517da8081f1e90a0fdfbb82a526c1704henning mueller<div class="refentry" lang="en">
64533bb0160210256e0a393ea102a4c4f1cc8ecaChristian Clausen<a name="man.rndc.conf"></a><div class="titlepage"></div>
0644459547fa2b5ae4120a5fb8f646d9b55249e7Christian Clausen<div class="refnamediv">
64533bb0160210256e0a393ea102a4c4f1cc8ecaChristian Clausen<h2>Name</h2>
64533bb0160210256e0a393ea102a4c4f1cc8ecaChristian Clausen<p><code class="filename">rndc.conf</code> &#8212; rndc configuration file</p>
7ef46b1adca473f664769a44a378e9f08385d3a0Julian Kornberger</div>
7ef46b1adca473f664769a44a378e9f08385d3a0Julian Kornberger<div class="refsynopsisdiv">
7ef46b1adca473f664769a44a378e9f08385d3a0Julian Kornberger<h2>Synopsis</h2>
5b9d1e25142d3712e05d5df39d5b0d5dc3c0212fChristian Clausen<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
ec4b26551f089e6fac410aba49bfcd8e7fae6536henning mueller</div>
5b9d1e25142d3712e05d5df39d5b0d5dc3c0212fChristian Clausen<div class="refsect1" lang="en">
5b9d1e25142d3712e05d5df39d5b0d5dc3c0212fChristian Clausen<a name="id2585806"></a><h2>DESCRIPTION</h2>
5b9d1e25142d3712e05d5df39d5b0d5dc3c0212fChristian Clausen<p><code class="filename">rndc.conf</code> is the configuration file
5b9d1e25142d3712e05d5df39d5b0d5dc3c0212fChristian Clausen for <span><strong class="command">rndc</strong></span>, the BIND 9 name server control
5b9d1e25142d3712e05d5df39d5b0d5dc3c0212fChristian Clausen utility. This file has a similar structure and syntax to
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen <code class="filename">named.conf</code>. Statements are enclosed
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen in braces and terminated with a semi-colon. Clauses in
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen the statements are also semi-colon terminated. The usual
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen comment styles are supported:
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen </p>
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen<p>
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen C style: /* */
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen </p>
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen<p>
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen C++ style: // to end of line
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen </p>
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen<p>
0ae77dd0f6698fa1948d1c6c973cc64d6df9e8d6Christian Clausen Unix style: # to end of line
0075dcb5aeeee4864fe9f64db82c8a8202bbe6d6henning mueller </p>
<p><code class="filename">rndc.conf</code> is much simpler than
<code class="filename">named.conf</code>. The file uses three
statements: an options statement, a server statement
and a key statement.
</p>
<p>
The <code class="option">options</code> statement contains five clauses.
The <code class="option">default-server</code> clause is followed by the
name or address of a name server. This host will be used when
no name server is given as an argument to
<span><strong class="command">rndc</strong></span>. The <code class="option">default-key</code>
clause is followed by the name of a key which is identified by
a <code class="option">key</code> statement. If no
<code class="option">keyid</code> is provided on the rndc command line,
and no <code class="option">key</code> clause is found in a matching
<code class="option">server</code> statement, this default key will be
used to authenticate the server's commands and responses. The
<code class="option">default-port</code> clause is followed by the port
to connect to on the remote name server. If no
<code class="option">port</code> option is provided on the rndc command
line, and no <code class="option">port</code> clause is found in a
matching <code class="option">server</code> statement, this default port
will be used to connect.
The <code class="option">default-source-address</code> and
<code class="option">default-source-address-v6</code> clauses which
can be used to set the IPv4 and IPv6 source addresses
respectively.
</p>
<p>
After the <code class="option">server</code> keyword, the server
statement includes a string which is the hostname or address
for a name server. The statement has three possible clauses:
<code class="option">key</code>, <code class="option">port</code> and
<code class="option">addresses</code>. 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 <code class="option">addresses</code>
clause is supplied these addresses will be used instead of
the server name. Each address can take a optional port.
If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
of supplied then these will be used to specify the IPv4 and IPv6
source addresses respectively.
</p>
<p>
The <code class="option">key</code> statement begins with an identifying
string, the name of the key. The statement has two clauses.
<code class="option">algorithm</code> identifies the encryption algorithm
for <span><strong class="command">rndc</strong></span> to use; currently only HMAC-MD5
is
supported. This is followed by a secret clause which contains
the base-64 encoding of the algorithm's encryption key. The
base-64 string is enclosed in double quotes.
</p>
<p>
There are two common ways to generate the base-64 string for the
secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
can
be used to generate a random key, or the
<span><strong class="command">mmencode</strong></span> program, also known as
<span><strong class="command">mimencode</strong></span>, can be used to generate a
base-64
string from known input. <span><strong class="command">mmencode</strong></span> does
not
ship with BIND 9 but is available on many systems. See the
EXAMPLE section for sample command lines for each.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2586183"></a><h2>EXAMPLE</h2>
<pre class="programlisting">
options {
default-server localhost;
default-key samplekey;
};
</pre>
<p>
</p>
<pre class="programlisting">
server localhost {
key samplekey;
};
</pre>
<p>
</p>
<pre class="programlisting">
server testserver {
key testkey;
addresses { localhost port 5353; };
};
</pre>
<p>
</p>
<pre class="programlisting">
key samplekey {
algorithm hmac-md5;
secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
};
</pre>
<p>
</p>
<pre class="programlisting">
key testkey {
algorithm hmac-md5;
secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
}
</pre>
<p>
</p>
<p>
In the above example, <span><strong class="command">rndc</strong></span> 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-MD5 algorithm and its secret clause contains the
base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
</p>
<p>
If <span><strong class="command">rndc -s testserver</strong></span> is used then <span><strong class="command">rndc</strong></span> will
connect to server on localhost port 5353 using the key testkey.
</p>
<p>
To generate a random secret with <span><strong class="command">rndc-confgen</strong></span>:
</p>
<p><strong class="userinput"><code>rndc-confgen</code></strong>
</p>
<p>
A complete <code class="filename">rndc.conf</code> file, including
the
randomly generated key, will be written to the standard
output. Commented out <code class="option">key</code> and
<code class="option">controls</code> statements for
<code class="filename">named.conf</code> are also printed.
</p>
<p>
To generate a base-64 secret with <span><strong class="command">mmencode</strong></span>:
</p>
<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2586373"></a><h2>NAME SERVER CONFIGURATION</h2>
<p>
The name server must be configured to accept rndc connections and
to recognize the key specified in the <code class="filename">rndc.conf</code>
file, using the controls statement in <code class="filename">named.conf</code>.
See the sections on the <code class="option">controls</code> statement in the
BIND 9 Administrator Reference Manual for details.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2586398"></a><h2>SEE ALSO</h2>
<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
<span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
<span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
<em class="citetitle">BIND 9 Administrator Reference Manual</em>.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id2586437"></a><h2>AUTHOR</h2>
<p><span class="corpauthor">Internet Systems Consortium</span>
</p>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch10.html">Up</a></td>
<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top"><span class="application">rndc</span>�</td>
<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span></td>
</tr>
</table>
</div>
</body>
</html>