man.rndc.conf.html revision 71cef386fae61275b03e203825680b39fedaa8c6
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - Copyright (C) 2000-2018 Internet Systems Consortium, Inc. ("ISC")
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - This Source Code Form is subject to the terms of the Mozilla Public
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - License, v. 2.0. If a copy of the MPL was not distributed with this
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - file, You can obtain one at http://mozilla.org/MPL/2.0/.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maeder<link rel="up" href="Bv9ARM.ch13.html" title="Manual pages">
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maeder<link rel="prev" href="man.rndc.html" title="rndc">
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder<link rel="next" href="man.rndc-confgen.html" title="rndc-confgen">
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
760ae19a92dde8249679a674f93f58d26a7c5f6bChristian Maeder<table width="100%" summary="Navigation header">
88c800932dd7053322501ea2039d9f234be6866cKlaus Luettich<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder<th width="60%" align="center">Manual pages</th>
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder<td width="20%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich<a name="man.rndc.conf"></a><div class="titlepage"></div>
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder — rndc configuration file
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder<a name="id-1.14.28.7"></a><h2>DESCRIPTION</h2>
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder <p><code class="filename">rndc.conf</code> is the configuration file
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder utility. This file has a similar structure and syntax to
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder <code class="filename">named.conf</code>. Statements are enclosed
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder in braces and terminated with a semi-colon. Clauses in
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder the statements are also semi-colon terminated. The usual
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder comment styles are supported:
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder C style: /* */
f4505a64a089693012a3f5c3b1f12a82cd7a2a5aKlaus Luettich C++ style: // to end of line
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder Unix style: # to end of line
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <p><code class="filename">rndc.conf</code> is much simpler than
77a65251ee036c6aaf09c2775315a4ee24259fbdJorina Freya Gerken <code class="filename">named.conf</code>. The file uses three
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder statements: an options statement, a server statement
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder and a key statement.
97812b7ce9860bf514a8822a63503451795dbc65Klaus Luettich The <code class="option">options</code> statement contains five clauses.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder The <code class="option">default-server</code> clause is followed by the
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder name or address of a name server. This host will be used when
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder no name server is given as an argument to
61fa0ac06ede811c7aad54ec4c4202346727368eChristian 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
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder a <code class="option">key</code> statement. If no
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <code class="option">keyid</code> is provided on the rndc command line,
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder and no <code class="option">key</code> clause is found in a matching
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <code class="option">server</code> statement, this default key will be
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder used to authenticate the server's commands and responses. The
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maeder <code class="option">default-port</code> clause is followed by the port
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder to connect to on the remote name server. If no
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <code class="option">port</code> option is provided on the rndc command
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder line, and no <code class="option">port</code> clause is found in a
9df11f85fd7f8c4745d64464876e84ec4e263692Christian Maeder matching <code class="option">server</code> statement, this default port
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers will be used to connect.
9df11f85fd7f8c4745d64464876e84ec4e263692Christian Maeder The <code class="option">default-source-address</code> and
5b818f10e11fc79def1fdd5c8a080d64a6438d87Christian Maeder <code class="option">default-source-address-v6</code> clauses which
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers can be used to set the IPv4 and IPv6 source addresses
5d4038657f6a63e131f5804af2f7957b69e15a43Klaus Luettich respectively.
c432483b64662e8db604a58758cd18ea7fa65659Christian Maeder After the <code class="option">server</code> keyword, the server
857992065be4ed40a72c6296b6c0aec62ab4c5b9Christian Maeder statement includes a string which is the hostname or address
857992065be4ed40a72c6296b6c0aec62ab4c5b9Christian Maeder for a name server. The statement has three possible clauses:
8659594bb40eb5f3da5439692f0908300947191eSonja Gröning <code class="option">key</code>, <code class="option">port</code> and
8c692d0cc44e7df93f58a3eed0d9774ba5908339Jorina Freya Gerken <code class="option">addresses</code>. The key name must match the
eeb419aa20c97b4af973e97ee6ae77a8eed29e15Till Mossakowski name of a key statement in the file. The port number
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers specifies the port to connect to. If an <code class="option">addresses</code>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder clause is supplied these addresses will be used instead of
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder the server name. Each address can take an optional port.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder If an <code class="option">source-address</code> or <code class="option">source-address-v6</code>
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder of supplied then these will be used to specify the IPv4 and IPv6
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder source addresses respectively.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder The <code class="option">key</code> statement begins with an identifying
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder string, the name of the key. The statement has two clauses.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <code class="option">algorithm</code> identifies the authentication algorithm
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder (default), HMAC-SHA384 and HMAC-SHA512 are
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder supported. This is followed by a secret clause which contains
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder the base-64 encoding of the algorithm's authentication key. The
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder base-64 string is enclosed in double quotes.
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckers There are two common ways to generate the base-64 string for the
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder secret. The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span>
51e836611726885f6d2719d959ed1b51f8fd06f4Klaus Luettich be used to generate a random key, or the
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till Mossakowski <span class="command"><strong>mmencode</strong></span> program, also known as
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till Mossakowski <span class="command"><strong>mimencode</strong></span>, can be used to generate a
b49276c9f50038e0bd499ad49f7bd6444566a834Christian Maeder string from known input. <span class="command"><strong>mmencode</strong></span> does
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder ship with BIND 9 but is available on many systems. See the
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder EXAMPLE section for sample command lines for each.
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder default-server localhost;
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder default-key samplekey;
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder server localhost {
dbe752ee940baae7f9f231f29c62284bb0f90a25Christian Maeder key samplekey;
53818ced114da21321063fff307aa41c1ab31dd3Achim Mahnke server testserver {
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder addresses { localhost port 5353; };
857992065be4ed40a72c6296b6c0aec62ab4c5b9Christian Maeder key samplekey {
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till Mossakowski algorithm hmac-sha256;
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder secret "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
b49276c9f50038e0bd499ad49f7bd6444566a834Christian Maeder key testkey {
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder algorithm hmac-sha256;
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder secret "R3HI8P6BKw9ZwXwN3VZKuQ==";
ed9207cf24e96b0d6f59985822054ae28cb69b2eChristian Maeder In the above example, <span class="command"><strong>rndc</strong></span> will by
b49276c9f50038e0bd499ad49f7bd6444566a834Christian Maeder the server at localhost (127.0.0.1) and the key called samplekey.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder Commands to the localhost server will use the samplekey key, which
b49276c9f50038e0bd499ad49f7bd6444566a834Christian Maeder must also be defined in the server's configuration file with the
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder same name and secret. The key statement indicates that samplekey
b905126bab9454b89041f92b3c50bb9efc85e427Klaus Luettich uses the HMAC-SHA256 algorithm and its secret clause contains the
d784803f9c752667b4fcf7393d698002bedf3f89Klaus Luettich base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
08e5741dd8b6bf9b7419e89298e384e18bc57f64Christian Maeder If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will
53818ced114da21321063fff307aa41c1ab31dd3Achim Mahnke connect to server on localhost port 5353 using the key testkey.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <p><strong class="userinput"><code>rndc-confgen</code></strong>
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder A complete <code class="filename">rndc.conf</code> file, including
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder randomly generated key, will be written to the standard
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder output. Commented-out <code class="option">key</code> and
b905126bab9454b89041f92b3c50bb9efc85e427Klaus Luettich <code class="option">controls</code> statements for
b905126bab9454b89041f92b3c50bb9efc85e427Klaus Luettich <code class="filename">named.conf</code> are also printed.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>:
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
ef67402074be14deb95e4ff564737d5593144130Klaus Luettich<a name="id-1.14.28.9"></a><h2>NAME SERVER CONFIGURATION</h2>
ef67402074be14deb95e4ff564737d5593144130Klaus Luettich The name server must be configured to accept rndc connections and
5958fabb264ec3f5b2125ac5602121bd34814a79Klaus Luettich to recognize the key specified in the <code class="filename">rndc.conf</code>
5958fabb264ec3f5b2125ac5602121bd34814a79Klaus Luettich file, using the controls statement in <code class="filename">named.conf</code>.
e7e1ab2ac3f1fded8611bb92ae00e8f3b8c693fbKlaus Luettich See the sections on the <code class="option">controls</code> statement in the
ef67402074be14deb95e4ff564737d5593144130Klaus Luettich BIND 9 Administrator Reference Manual for details.
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder <span class="refentrytitle">rndc-confgen</span>(8)
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich <span class="refentrytitle">mmencode</span>(1)
4e7050bcbcf0f372a5bad32ecd0282bccabf0983Klaus Luettich <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
340706b6c0c6e3dbacdd7003e20e9cab7f9aa765Christian Maeder<table width="100%" summary="Navigation footer">
340706b6c0c6e3dbacdd7003e20e9cab7f9aa765Christian Maeder<a accesskey="p" href="man.rndc.html">Prev</a>�</td>
fdb2d618144159395f7bf8ce3327b3c112a17dd3Till Mossakowski<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch13.html">Up</a></td>
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder<td width="40%" align="right">�<a accesskey="n" href="man.rndc-confgen.html">Next</a>
94d3aa05411444596b44ede4531f05dd7ac20fdfChristian Maeder<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
dc929508a3bd3c666e9b0182d56898fcafb5d66fChristian Maeder<td width="40%" align="right" valign="top">�<span class="application">rndc-confgen</span>
ddc9315cc0b1f5dd3d8f99a77f1c75064db33b48Christian Maeder<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.2 (Extended Support Version)</p>