man.rndc.conf.html revision 14a656f94b1fd0ababd84a772228dfa52276ba15
c63ebf815c8a874525cf18670ad74847f7fc7b26Christian Maeder - Copyright (C) 2004-2015 Internet Systems Consortium, Inc. ("ISC")
7d170078860d52494588609be44be963c416ecf6Christian Maeder - Copyright (C) 2000-2003 Internet Software Consortium.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - Permission to use, copy, modify, and/or distribute this software for any
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - purpose with or without fee is hereby granted, provided that the above
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - copyright notice and this permission notice appear in all copies.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
f4a2a20e49f41b2afa657e5e64d9e349c7faa091Christian Maeder - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder - PERFORMANCE OF THIS SOFTWARE.
a53841f6d6e86ac751c12a33dc8aadf53f59d977Klaus Luettich<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
a53841f6d6e86ac751c12a33dc8aadf53f59d977Klaus Luettich<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
a53841f6d6e86ac751c12a33dc8aadf53f59d977Klaus Luettich<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maeder<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages">
68d10d143f29fcff3c637ba24f90e983995ceae6Christian Maeder<link rel="prev" href="man.rndc.html" title="rndc">
96646aed2ae087b942ae23f15bbe729a8f7c43d3Christian Maeder<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
3b06e23643a9f65390cb8c1caabe83fa7e87a708Till Mossakowski<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
5e5d3e82af3bc2834f8718a52d9f45da80220273Dominik Luecke<table width="100%" summary="Navigation header">
124c859ba4741d5e36d5d98634886b430b7af093Christian Maeder<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
e7757995211bd395dc79d26fe017d99375f7d2a6Christian Maeder<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<th width="60%" align="center">Manual pages</th>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
4cb215739e9ab13447fa21162482ebe485b47455Christian Maeder<a name="man.rndc.conf"></a><div class="titlepage"></div>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder — rndc configuration file
f4a2a20e49f41b2afa657e5e64d9e349c7faa091Christian Maeder<a name="id-1.14.24.7"></a><h2>DESCRIPTION</h2>
dcbd32289a7bdf1e6edd06c6ab0698c6a9dbf37aChristian Maeder <p><code class="filename">rndc.conf</code> is the configuration file
d0279930f87bf39843e0bd2992a4789322662144Christian Maeder for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control
8be81a0578b59f08641da7fad1479e1f9e83c6e9Kristina Sojakova utility. This file has a similar structure and syntax to
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder <code class="filename">named.conf</code>. Statements are enclosed
8b767d09a78927b111f5596fdff9ca7d2c1a439fChristian Maeder in braces and terminated with a semi-colon. Clauses in
8b767d09a78927b111f5596fdff9ca7d2c1a439fChristian Maeder the statements are also semi-colon terminated. The usual
8b767d09a78927b111f5596fdff9ca7d2c1a439fChristian Maeder comment styles are supported:
8b767d09a78927b111f5596fdff9ca7d2c1a439fChristian Maeder C style: /* */
8cacad2a09782249243b80985f28e9387019fe40Christian Maeder C++ style: // to end of line
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder Unix style: # to end of line
f04e8f3ff56405901be968fd4c6e9769239f1a9bKlaus Luettich <p><code class="filename">rndc.conf</code> is much simpler than
797ccd67cb8ae127be097cd43448801b673e3b69Christian Maeder <code class="filename">named.conf</code>. The file uses three
797ccd67cb8ae127be097cd43448801b673e3b69Christian Maeder statements: an options statement, a server statement
431d34c7007a787331c4e5ec997badb0f8190fc7Christian Maeder and a key statement.
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder The <code class="option">options</code> statement contains five clauses.
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder The <code class="option">default-server</code> clause is followed by the
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder name or address of a name server. This host will be used when
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder no name server is given as an argument to
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <span class="command"><strong>rndc</strong></span>. The <code class="option">default-key</code>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder clause is followed by the name of a key which is identified by
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder a <code class="option">key</code> statement. If no
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="option">keyid</code> is provided on the rndc command line,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder and no <code class="option">key</code> clause is found in a matching
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="option">server</code> statement, this default key will be
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder used to authenticate the server's commands and responses. The
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="option">default-port</code> clause is followed by the port
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder to connect to on the remote name server. If no
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <code class="option">port</code> option is provided on the rndc command
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder line, and no <code class="option">port</code> clause is found in a
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder matching <code class="option">server</code> statement, this default port
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder will be used to connect.
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder The <code class="option">default-source-address</code> and
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="option">default-source-address-v6</code> clauses which
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder can be used to set the IPv4 and IPv6 source addresses
a5e5b8c3e5c11177e5034ef2423813a5d28979edChristian Maeder respectively.
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder After the <code class="option">server</code> keyword, the server
51d769d55d88dfa88bdf54bee78d8fa85a2deba8Christian Maeder statement includes a string which is the hostname or address
a5e5b8c3e5c11177e5034ef2423813a5d28979edChristian Maeder for a name server. The statement has three possible clauses:
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder <code class="option">key</code>, <code class="option">port</code> and
bc8cbf12aa172bf5673b92a9e7a0151d4aa4c315Christian Maeder <code class="option">addresses</code>. The key name must match the
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder name of a key statement in the file. The port number
f4a2a20e49f41b2afa657e5e64d9e349c7faa091Christian Maeder specifies the port to connect to. If an <code class="option">addresses</code>
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder clause is supplied these addresses will be used instead of
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder the server name. Each address can take an optional port.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
6ff7a91875597d6e4dfaa68c79187d01473e8341Christian Maeder of supplied then these will be used to specify the IPv4 and IPv6
6ff7a91875597d6e4dfaa68c79187d01473e8341Christian Maeder source addresses respectively.
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder The <code class="option">key</code> statement begins with an identifying
a9b59eb2ce961014974276cdae0e9df4419bd212Christian Maeder string, the name of the key. The statement has two clauses.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <code class="option">algorithm</code> identifies the authentication algorithm
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder (default), HMAC-SHA384 and HMAC-SHA512 are
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder supported. This is followed by a secret clause which contains
a3c6d8e0670bf2aa71bc8e2a3b1f45d56dd65e4cChristian Maeder the base-64 encoding of the algorithm's authentication key. The
dc679edd4ca027663212afdf00926ae2ce19b555Christian Maeder base-64 string is enclosed in double quotes.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder There are two common ways to generate the base-64 string for the
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder secret. The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder be used to generate a random key, or the
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder <span class="command"><strong>mmencode</strong></span> program, also known as
b568982efd0997d877286faa592d81b03c8c67b8Christian Maeder <span class="command"><strong>mimencode</strong></span>, can be used to generate a
0be0db405c49906bd7057255069bf6df53395ac9Klaus Luettich string from known input. <span class="command"><strong>mmencode</strong></span> does
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder ship with BIND 9 but is available on many systems. See the
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder EXAMPLE section for sample command lines for each.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder default-server localhost;
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder default-key samplekey;
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder server localhost {
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder key samplekey;
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder server testserver {
06ba24fa9695b698437546276f37aa5e1924ad1bChristian Maeder addresses { localhost port 5353; };
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder key samplekey {
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder algorithm hmac-sha256;
2def8973f409c9b44fc83b828cf0fe955d360d76Christian Maeder secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder key testkey {
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder algorithm hmac-sha256;
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder In the above example, <span class="command"><strong>rndc</strong></span> will by
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder the server at localhost (127.0.0.1) and the key called samplekey.
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder Commands to the localhost server will use the samplekey key, which
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder must also be defined in the server's configuration file with the
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder same name and secret. The key statement indicates that samplekey
328a85c807f2a95c3f147d10b05927eaf862ebebChristian Maeder uses the HMAC-SHA256 algorithm and its secret clause contains the
a6db617ca58eb6a0587b6366e913107dfecb71b5Heng Jiang base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
5b818f10e11fc79def1fdd5c8a080d64a6438d87Christian Maeder If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers connect to server on localhost port 5353 using the key testkey.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
a14767aeac3e78ed100f5b75e210ba563ee10dbaChristian Maeder <p><strong class="userinput"><code>rndc-confgen</code></strong>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder A complete <code class="filename">rndc.conf</code> file, including
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder randomly generated key, will be written to the standard
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder output. Commented-out <code class="option">key</code> and
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <code class="option">controls</code> statements for
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder <code class="filename">named.conf</code> are also printed.
a14767aeac3e78ed100f5b75e210ba563ee10dbaChristian Maeder To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>:
a14767aeac3e78ed100f5b75e210ba563ee10dbaChristian Maeder <p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder<a name="id-1.14.24.9"></a><h2>NAME SERVER CONFIGURATION</h2>
f9e0b18852b238ddb649d341194e05d7200d1bbeChristian Maeder The name server must be configured to accept rndc connections and
f9e0b18852b238ddb649d341194e05d7200d1bbeChristian Maeder to recognize the key specified in the <code class="filename">rndc.conf</code>
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder file, using the controls statement in <code class="filename">named.conf</code>.
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder See the sections on the <code class="option">controls</code> statement in the
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder BIND 9 Administrator Reference Manual for details.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder<a name="id-1.14.24.10"></a><h2>SEE ALSO</h2>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <span class="refentrytitle">rndc-confgen</span>(8)
ac34194a668399bb8ef238da77c3a09e93fb253bChristian Maeder <span class="refentrytitle">mmencode</span>(1)
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
4561227a776bdf0ab679b19fb92f1eaaed8786f7Christian Maeder<table width="100%" summary="Navigation footer">
5ad5dffe06818a13e1632b1119fbca7881085fc1Dominik Luecke<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
8c812cd83569e973f10cf69a342424ceabc07af9Christian Maeder<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td>
8c812cd83569e973f10cf69a342424ceabc07af9Christian Maeder<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
d54cd08a4cfa26256c38d8ed12c343adbfe1a0e3Christian Maeder<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
d54cd08a4cfa26256c38d8ed12c343adbfe1a0e3Christian Maeder<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>
0b349288edfa50fdf38fda1a14e1562d03f92574Christian Maeder<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.0pre-alpha</p>