rndc.conf.html revision f6da30bb5447c23d880b09f601441e70c5313557
cd348e325366620fe047edcc849e3c9424828599Peter Bray - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
0ca9a2c194523c517c3aafe5758e217ac88d6baaLubos Kosco - Copyright (C) 2000, 2001 Internet Software Consortium.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - Permission to use, copy, modify, and distribute this software for any
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal - purpose with or without fee is hereby granted, provided that the above
983523cf73bc85cce6282cb5aa78b60f6bcd959fLubos Kosco - copyright notice and this permission notice appear in all copies.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
c577d2f6c082eaff9af5bc997d12f3d3bcef537cPeter Bray - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
983523cf73bc85cce6282cb5aa78b60f6bcd959fLubos Kosco - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
c577d2f6c082eaff9af5bc997d12f3d3bcef537cPeter Bray - PERFORMANCE OF THIS SOFTWARE.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<!-- $Id: rndc.conf.html,v 1.29 2007/05/09 13:35:57 marka Exp $ -->
c577d2f6c082eaff9af5bc997d12f3d3bcef537cPeter Bray<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
d961aa46ea0d50fed47802497e45226b1965b12dVladimir Kotal<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
d961aa46ea0d50fed47802497e45226b1965b12dVladimir Kotal<a name="man.rndc.conf"></a><div class="titlepage"></div>
983523cf73bc85cce6282cb5aa78b60f6bcd959fLubos Kosco<p><code class="filename">rndc.conf</code> — rndc configuration file</p>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<div class="cmdsynopsis"><p><code class="command">rndc.conf</code> </p></div>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<p><code class="filename">rndc.conf</code> is the configuration file
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal for <span><strong class="command">rndc</strong></span>, the BIND 9 name server control
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal utility. This file has a similar structure and syntax to
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="filename">named.conf</code>. Statements are enclosed
c577d2f6c082eaff9af5bc997d12f3d3bcef537cPeter Bray in braces and terminated with a semi-colon. Clauses in
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal the statements are also semi-colon terminated. The usual
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal comment styles are supported:
65df1e87266301e243dcead8082ca6255abea666Vladimir Kotal C style: /* */
425278cfacbc73f1e955ab6016f206fc5ed93ccbVladimir Kotal C++ style: // to end of line
65df1e87266301e243dcead8082ca6255abea666Vladimir Kotal Unix style: # to end of line
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal<p><code class="filename">rndc.conf</code> is much simpler than
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal <code class="filename">named.conf</code>. The file uses three
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal statements: an options statement, a server statement
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal and a key statement.
6ce0623fa4ef95af9d77700a1c9c19ec1a919326Guillaume Smet The <code class="option">options</code> statement contains five clauses.
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal The <code class="option">default-server</code> clause is followed by the
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal name or address of a name server. This host will be used when
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal no name server is given as an argument to
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal <span><strong class="command">rndc</strong></span>. The <code class="option">default-key</code>
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal clause is followed by the name of a key which is identified by
83439b4ed8fe40097dc3f2c05168d26bd7926159Vladimir Kotal a <code class="option">key</code> statement. If no
83439b4ed8fe40097dc3f2c05168d26bd7926159Vladimir Kotal <code class="option">keyid</code> is provided on the rndc command line,
83439b4ed8fe40097dc3f2c05168d26bd7926159Vladimir Kotal and no <code class="option">key</code> clause is found in a matching
3ba66fbb56ef22f183da783a1b2718280c357a4eStanislav Kozina <code class="option">server</code> statement, this default key will be
3ba66fbb56ef22f183da783a1b2718280c357a4eStanislav Kozina used to authenticate the server's commands and responses. The
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal <code class="option">default-port</code> clause is followed by the port
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal to connect to on the remote name server. If no
983523cf73bc85cce6282cb5aa78b60f6bcd959fLubos Kosco <code class="option">port</code> option is provided on the rndc command
983523cf73bc85cce6282cb5aa78b60f6bcd959fLubos Kosco line, and no <code class="option">port</code> clause is found in a
983523cf73bc85cce6282cb5aa78b60f6bcd959fLubos Kosco matching <code class="option">server</code> statement, this default port
983523cf73bc85cce6282cb5aa78b60f6bcd959fLubos Kosco will be used to connect.
983523cf73bc85cce6282cb5aa78b60f6bcd959fLubos Kosco The <code class="option">default-source-address</code> and
c577d2f6c082eaff9af5bc997d12f3d3bcef537cPeter Bray <code class="option">default-source-address-v6</code> clauses which
c577d2f6c082eaff9af5bc997d12f3d3bcef537cPeter Bray can be used to set the IPv4 and IPv6 source addresses
c577d2f6c082eaff9af5bc997d12f3d3bcef537cPeter Bray respectively.
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal After the <code class="option">server</code> keyword, the server
425278cfacbc73f1e955ab6016f206fc5ed93ccbVladimir Kotal statement includes a string which is the hostname or address
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal for a name server. The statement has three possible clauses:
cd348e325366620fe047edcc849e3c9424828599Peter Bray <code class="option">key</code>, <code class="option">port</code> and
3b0448fdd830b8d04c6a71511e5d26a4fc3b5b80Lubos Kosco <code class="option">addresses</code>. The key name must match the
cd348e325366620fe047edcc849e3c9424828599Peter Bray name of a key statement in the file. The port number
cd348e325366620fe047edcc849e3c9424828599Peter Bray specifies the port to connect to. If an <code class="option">addresses</code>
cd348e325366620fe047edcc849e3c9424828599Peter Bray clause is supplied these addresses will be used instead of
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal the server name. Each address can take an optional port.
6c8465e3b4611cb632cba9b0572e3e3737c8c341Vladimir Kotal If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
43dac746513591adbd09bc4f417feb385f4fd87eVladimir Kotal of supplied then these will be used to specify the IPv4 and IPv6
fbf97ea1786d1e25add88bbfb91810170473bc9fLubos Kosco source addresses respectively.
3a4816d2417e1abe89a913616de36f200793bea3Vladimir Kotal The <code class="option">key</code> statement begins with an identifying
fbf97ea1786d1e25add88bbfb91810170473bc9fLubos Kosco string, the name of the key. The statement has two clauses.
fbf97ea1786d1e25add88bbfb91810170473bc9fLubos Kosco <code class="option">algorithm</code> identifies the encryption algorithm
fbf97ea1786d1e25add88bbfb91810170473bc9fLubos Kosco for <span><strong class="command">rndc</strong></span> to use; currently only HMAC-MD5
fbf97ea1786d1e25add88bbfb91810170473bc9fLubos Kosco supported. This is followed by a secret clause which contains
f21b682cd9b414738a4f5a38b56f6682e537e1d2Trond Norbye the base-64 encoding of the algorithm's encryption key. The
3b0448fdd830b8d04c6a71511e5d26a4fc3b5b80Lubos Kosco base-64 string is enclosed in double quotes.
cd348e325366620fe047edcc849e3c9424828599Peter Bray There are two common ways to generate the base-64 string for the
cd348e325366620fe047edcc849e3c9424828599Peter Bray secret. The BIND 9 program <span><strong class="command">rndc-confgen</strong></span>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray be used to generate a random key, or the
cd348e325366620fe047edcc849e3c9424828599Peter Bray <span><strong class="command">mmencode</strong></span> program, also known as
c276b1ec9722ee95a86a4a381b39c5f405fc1cc4Vladimir Kotal <span><strong class="command">mimencode</strong></span>, can be used to generate a
c276b1ec9722ee95a86a4a381b39c5f405fc1cc4Vladimir Kotal string from known input. <span><strong class="command">mmencode</strong></span> does
c276b1ec9722ee95a86a4a381b39c5f405fc1cc4Vladimir Kotal ship with BIND 9 but is available on many systems. See the
c276b1ec9722ee95a86a4a381b39c5f405fc1cc4Vladimir Kotal EXAMPLE section for sample command lines for each.
d280c5e286f5b98be13237f52281ae5afdcf51b9Peter Bray default-server localhost;
d280c5e286f5b98be13237f52281ae5afdcf51b9Peter Bray default-key samplekey;
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray server localhost {
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray key samplekey;
cd348e325366620fe047edcc849e3c9424828599Peter Bray server testserver {
cd348e325366620fe047edcc849e3c9424828599Peter Bray key testkey;
cd348e325366620fe047edcc849e3c9424828599Peter Bray addresses { localhost port 5353; };
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray key samplekey {
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray algorithm hmac-md5;
0ca9a2c194523c517c3aafe5758e217ac88d6baaLubos Kosco secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray key testkey {
d280c5e286f5b98be13237f52281ae5afdcf51b9Peter Bray algorithm hmac-md5;
d280c5e286f5b98be13237f52281ae5afdcf51b9Peter Bray secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
b34561d2c3d92fac37dbced05ba6a8738e3d20e9Lubos Kosco In the above example, <span><strong class="command">rndc</strong></span> will by
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray the server at localhost (127.0.0.1) and the key called samplekey.
5e6c91d7e77062129cd0b6ac8aaa546dff216419Lubos Kosco Commands to the localhost server will use the samplekey key, which
c83dfde6b364917fa8ed28142d509a7c29a4da68Vladimir Kotal must also be defined in the server's configuration file with the
c83dfde6b364917fa8ed28142d509a7c29a4da68Vladimir Kotal same name and secret. The key statement indicates that samplekey
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray uses the HMAC-MD5 algorithm and its secret clause contains the
cd348e325366620fe047edcc849e3c9424828599Peter Bray base-64 encoding of the HMAC-MD5 secret enclosed in double quotes.
cd348e325366620fe047edcc849e3c9424828599Peter Bray If <span><strong class="command">rndc -s testserver</strong></span> is used then <span><strong class="command">rndc</strong></span> will
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray connect to server on localhost port 5353 using the key testkey.
cd348e325366620fe047edcc849e3c9424828599Peter Bray To generate a random secret with <span><strong class="command">rndc-confgen</strong></span>:
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<p><strong class="userinput"><code>rndc-confgen</code></strong>
0b2998be561e7bf5e3479d686a5af36f712b0d9aVladimir Kotal A complete <code class="filename">rndc.conf</code> file, including
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray randomly generated key, will be written to the standard
cd348e325366620fe047edcc849e3c9424828599Peter Bray output. Commented-out <code class="option">key</code> and
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="option">controls</code> statements for
cd348e325366620fe047edcc849e3c9424828599Peter Bray <code class="filename">named.conf</code> are also printed.
c842732324ee4c74ede17887ad1f0dcdc4364a2cLubos Kosco To generate a base-64 secret with <span><strong class="command">mmencode</strong></span>:
c842732324ee4c74ede17887ad1f0dcdc4364a2cLubos Kosco<p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
c842732324ee4c74ede17887ad1f0dcdc4364a2cLubos Kosco<a name="id2543592"></a><h2>NAME SERVER CONFIGURATION</h2>
d280c5e286f5b98be13237f52281ae5afdcf51b9Peter Bray The name server must be configured to accept rndc connections and
d280c5e286f5b98be13237f52281ae5afdcf51b9Peter Bray to recognize the key specified in the <code class="filename">rndc.conf</code>
d280c5e286f5b98be13237f52281ae5afdcf51b9Peter Bray file, using the controls statement in <code class="filename">named.conf</code>.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray See the sections on the <code class="option">controls</code> statement in the
3aa0947feb67d3e8292d84776638be98dd97fdc3Lubos Kosco BIND 9 Administrator Reference Manual for details.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<p><span class="citerefentry"><span class="refentrytitle">rndc</span>(8)</span>,
cd348e325366620fe047edcc849e3c9424828599Peter Bray <span class="citerefentry"><span class="refentrytitle">rndc-confgen</span>(8)</span>,
cd348e325366620fe047edcc849e3c9424828599Peter Bray <span class="citerefentry"><span class="refentrytitle">mmencode</span>(1)</span>,
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
d961aa46ea0d50fed47802497e45226b1965b12dVladimir Kotal<p><span class="corpauthor">Internet Systems Consortium</span>