man.rndc.conf.html 10.2 KB
Newer Older
Tinderbox User's avatar
Tinderbox User committed
1 2
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--
Tinderbox User's avatar
Tinderbox User committed
3
 - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC")
Tinderbox User's avatar
Tinderbox User committed
4 5 6 7 8 9 10 11 12
 - 
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>rndc.conf</title>
Tinderbox User's avatar
Tinderbox User committed
13
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
Tinderbox User's avatar
Tinderbox User committed
14
<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
15
<link rel="up" href="Bv9ARM.ch12.html" title="Manual pages">
16 17
<link rel="prev" href="man.rndc-confgen.html" title="rndc-confgen">
<link rel="next" href="man.rndc.html" title="rndc">
Tinderbox User's avatar
Tinderbox User committed
18 19 20 21 22 23 24
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center"><code class="filename">rndc.conf</code></th></tr>
<tr>
<td width="20%" align="left">
25
<a accesskey="p" href="man.rndc-confgen.html">Prev</a> </td>
Tinderbox User's avatar
Tinderbox User committed
26
<th width="60%" align="center">Manual pages</th>
27
<td width="20%" align="right"> <a accesskey="n" href="man.rndc.html">Next</a>
Tinderbox User's avatar
Tinderbox User committed
28 29 30 31 32 33 34
</td>
</tr>
</table>
<hr>
</div>
<div class="refentry">
<a name="man.rndc.conf"></a><div class="titlepage"></div>
Tinderbox User's avatar
Tinderbox User committed
35 36 37 38 39 40
  
  

  

  <div class="refnamediv">
Tinderbox User's avatar
Tinderbox User committed
41
<h2>Name</h2>
Tinderbox User's avatar
Tinderbox User committed
42 43 44 45
<p>
    <code class="filename">rndc.conf</code>
     &#8212; rndc configuration file
  </p>
Tinderbox User's avatar
Tinderbox User committed
46
</div>
Tinderbox User's avatar
Tinderbox User committed
47 48 49 50

  

  <div class="refsynopsisdiv">
Tinderbox User's avatar
Tinderbox User committed
51
<h2>Synopsis</h2>
Tinderbox User's avatar
Tinderbox User committed
52 53 54 55 56 57
    <div class="cmdsynopsis"><p>
      <code class="command">rndc.conf</code> 
    </p></div>
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
58
<a name="id-1.13.37.7"></a><h2>DESCRIPTION</h2>
Tinderbox User's avatar
Tinderbox User committed
59 60

    <p><code class="filename">rndc.conf</code> is the configuration file
Tinderbox User's avatar
Tinderbox User committed
61 62 63 64 65 66 67
      for <span class="command"><strong>rndc</strong></span>, the BIND 9 name server control
      utility.  This file has a similar structure and syntax to
      <code class="filename">named.conf</code>.  Statements are enclosed
      in braces and terminated with a semi-colon.  Clauses in
      the statements are also semi-colon terminated.  The usual
      comment styles are supported:
    </p>
Tinderbox User's avatar
Tinderbox User committed
68
    <p>
Tinderbox User's avatar
Tinderbox User committed
69 70
      C style: /* */
    </p>
Tinderbox User's avatar
Tinderbox User committed
71
    <p>
Tinderbox User's avatar
Tinderbox User committed
72 73
      C++ style: // to end of line
    </p>
Tinderbox User's avatar
Tinderbox User committed
74
    <p>
Tinderbox User's avatar
Tinderbox User committed
75 76
      Unix style: # to end of line
    </p>
Tinderbox User's avatar
Tinderbox User committed
77
    <p><code class="filename">rndc.conf</code> is much simpler than
Tinderbox User's avatar
Tinderbox User committed
78 79 80 81
      <code class="filename">named.conf</code>.  The file uses three
      statements: an options statement, a server statement
      and a key statement.
    </p>
Tinderbox User's avatar
Tinderbox User committed
82
    <p>
Tinderbox User's avatar
Tinderbox User committed
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
      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 class="command"><strong>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>
Tinderbox User's avatar
Tinderbox User committed
105
    <p>
Tinderbox User's avatar
Tinderbox User committed
106 107 108 109 110 111 112 113 114 115 116 117 118
      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 an 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>
Tinderbox User's avatar
Tinderbox User committed
119
    <p>
Tinderbox User's avatar
Tinderbox User committed
120 121 122 123 124 125 126 127 128 129
      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 authentication algorithm
      for <span class="command"><strong>rndc</strong></span> to use; currently only HMAC-MD5
      (for compatibility), HMAC-SHA1, HMAC-SHA224, HMAC-SHA256
      (default), HMAC-SHA384 and HMAC-SHA512 are
      supported.  This is followed by a secret clause which contains
      the base-64 encoding of the algorithm's authentication key.  The
      base-64 string is enclosed in double quotes.
    </p>
Tinderbox User's avatar
Tinderbox User committed
130
    <p>
Tinderbox User's avatar
Tinderbox User committed
131 132 133 134 135 136 137 138 139 140 141 142
      There are two common ways to generate the base-64 string for the
      secret.  The BIND 9 program <span class="command"><strong>rndc-confgen</strong></span>
      can
      be used to generate a random key, or the
      <span class="command"><strong>mmencode</strong></span> program, also known as
      <span class="command"><strong>mimencode</strong></span>, can be used to generate a
      base-64
      string from known input.  <span class="command"><strong>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>
Tinderbox User's avatar
Tinderbox User committed
143 144 145
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
146
<a name="id-1.13.37.8"></a><h2>EXAMPLE</h2>
Tinderbox User's avatar
Tinderbox User committed
147 148 149


    <pre class="programlisting">
Tinderbox User's avatar
Tinderbox User committed
150 151 152 153 154 155 156
      options {
        default-server  localhost;
        default-key     samplekey;
      };
</pre>
<p>
    </p>
Tinderbox User's avatar
Tinderbox User committed
157
    <pre class="programlisting">
Tinderbox User's avatar
Tinderbox User committed
158 159 160 161 162 163
      server localhost {
        key             samplekey;
      };
</pre>
<p>
    </p>
Tinderbox User's avatar
Tinderbox User committed
164
    <pre class="programlisting">
Tinderbox User's avatar
Tinderbox User committed
165 166 167 168 169 170 171
      server testserver {
        key		testkey;
        addresses	{ localhost port 5353; };
      };
</pre>
<p>
    </p>
Tinderbox User's avatar
Tinderbox User committed
172
    <pre class="programlisting">
Tinderbox User's avatar
Tinderbox User committed
173 174 175 176 177 178 179
      key samplekey {
        algorithm       hmac-sha256;
        secret          "6FMfj43Osz4lyb24OIe2iGEz9lf1llJO+lz";
      };
</pre>
<p>
    </p>
Tinderbox User's avatar
Tinderbox User committed
180
    <pre class="programlisting">
Tinderbox User's avatar
Tinderbox User committed
181 182 183 184 185 186 187
      key testkey {
        algorithm	hmac-sha256;
        secret		"R3HI8P6BKw9ZwXwN3VZKuQ==";
      };
    </pre>
<p>
    </p>
Tinderbox User's avatar
Tinderbox User committed
188 189

    <p>
Tinderbox User's avatar
Tinderbox User committed
190 191 192 193 194 195 196 197 198
      In the above example, <span class="command"><strong>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-SHA256 algorithm and its secret clause contains the
      base-64 encoding of the HMAC-SHA256 secret enclosed in double quotes.
    </p>
Tinderbox User's avatar
Tinderbox User committed
199
    <p>
Tinderbox User's avatar
Tinderbox User committed
200 201 202
      If <span class="command"><strong>rndc -s testserver</strong></span> is used then <span class="command"><strong>rndc</strong></span> will
      connect to server on localhost port 5353 using the key testkey.
    </p>
Tinderbox User's avatar
Tinderbox User committed
203
    <p>
Tinderbox User's avatar
Tinderbox User committed
204 205
      To generate a random secret with <span class="command"><strong>rndc-confgen</strong></span>:
    </p>
Tinderbox User's avatar
Tinderbox User committed
206
    <p><strong class="userinput"><code>rndc-confgen</code></strong>
Tinderbox User's avatar
Tinderbox User committed
207
    </p>
Tinderbox User's avatar
Tinderbox User committed
208
    <p>
Tinderbox User's avatar
Tinderbox User committed
209 210 211 212 213 214 215
      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>
Tinderbox User's avatar
Tinderbox User committed
216
    <p>
Tinderbox User's avatar
Tinderbox User committed
217 218
      To generate a base-64 secret with <span class="command"><strong>mmencode</strong></span>:
    </p>
Tinderbox User's avatar
Tinderbox User committed
219
    <p><strong class="userinput"><code>echo "known plaintext for a secret" | mmencode</code></strong>
Tinderbox User's avatar
Tinderbox User committed
220
    </p>
Tinderbox User's avatar
Tinderbox User committed
221 222 223
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
224
<a name="id-1.13.37.9"></a><h2>NAME SERVER CONFIGURATION</h2>
Tinderbox User's avatar
Tinderbox User committed
225 226

    <p>
Tinderbox User's avatar
Tinderbox User committed
227 228 229 230 231 232
      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>
Tinderbox User's avatar
Tinderbox User committed
233 234 235
  </div>

  <div class="refsection">
Tinderbox User's avatar
Tinderbox User committed
236
<a name="id-1.13.37.10"></a><h2>SEE ALSO</h2>
Tinderbox User's avatar
Tinderbox User committed
237 238 239 240 241 242 243 244 245 246

    <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>,
Tinderbox User's avatar
Tinderbox User committed
247 248
      <em class="citetitle">BIND 9 Administrator Reference Manual</em>.
    </p>
Tinderbox User's avatar
Tinderbox User committed
249 250
  </div>

Tinderbox User's avatar
Tinderbox User committed
251 252 253 254 255 256
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
257
<a accesskey="p" href="man.rndc-confgen.html">Prev</a> </td>
258
<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch12.html">Up</a></td>
259
<td width="40%" align="right"> <a accesskey="n" href="man.rndc.html">Next</a>
Tinderbox User's avatar
Tinderbox User committed
260 261 262 263
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
264
<span class="application">rndc-confgen</span> </td>
Tinderbox User's avatar
Tinderbox User committed
265
<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
266
<td width="40%" align="right" valign="top"> <span class="application">rndc</span>
Tinderbox User's avatar
Tinderbox User committed
267 268 269 270
</td>
</tr>
</table>
</div>
Tinderbox User's avatar
Tinderbox User committed
271
<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.14.1 (Stable Release)</p>
Tinderbox User's avatar
Tinderbox User committed
272 273
</body>
</html>