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