Bv9ARM.ch06.html 694 KB
Newer Older
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
Rob Austein's avatar
regen  
Rob Austein committed
2
<!--
Tinderbox User's avatar
Tinderbox User committed
3
 - Copyright (C) 2000-2017 Internet Systems Consortium, Inc. ("ISC")
Rob Austein's avatar
regen  
Rob Austein committed
4
 - 
Tinderbox User's avatar
Tinderbox User committed
5 6 7
 - 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/.
Rob Austein's avatar
regen  
Rob Austein committed
8
-->
9
<html lang="en">
Rob Austein's avatar
regen  
Rob Austein committed
10 11 12
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 6. BIND 9 Configuration Reference</title>
Tinderbox User's avatar
Tinderbox User committed
13
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
Evan Hunt's avatar
Evan Hunt committed
14
<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
Rob Austein's avatar
regen  
Rob Austein committed
15 16 17 18 19 20 21
<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
<link rel="prev" href="Bv9ARM.ch05.html" title="Chapter 5. The BIND 9 Lightweight Resolver">
<link rel="next" href="Bv9ARM.ch07.html" title="Chapter 7. BIND 9 Security Considerations">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
Mark Andrews's avatar
regen  
Mark Andrews committed
22
<tr><th colspan="3" align="center">Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</th></tr>
Rob Austein's avatar
regen  
Rob Austein committed
23 24 25 26 27 28 29 30 31 32
<tr>
<td width="20%" align="left">
<a accesskey="p" href="Bv9ARM.ch05.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch07.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
Tinderbox User's avatar
Tinderbox User committed
33 34 35
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="Bv9ARM.ch06"></a>Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</h1></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
36 37
<div class="toc">
<p><b>Table of Contents</b></p>
Tinderbox User's avatar
Tinderbox User committed
38
<dl class="toc">
Evan Hunt's avatar
Evan Hunt committed
39
<dt><span class="section"><a href="Bv9ARM.ch06.html#configuration_file_elements">Configuration File Elements</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
40
<dd><dl>
Evan Hunt's avatar
Evan Hunt committed
41
<dt><span class="section"><a href="Bv9ARM.ch06.html#address_match_lists">Address Match Lists</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
42
<dt><span class="section"><a href="Bv9ARM.ch06.html#comment_syntax">Comment Syntax</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
43
</dl></dd>
Evan Hunt's avatar
Evan Hunt committed
44
<dt><span class="section"><a href="Bv9ARM.ch06.html#Configuration_File_Grammar">Configuration File Grammar</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
45
<dd><dl>
Tinderbox User's avatar
Tinderbox User committed
46
<dt><span class="section"><a href="Bv9ARM.ch06.html#acl_grammar"><span class="command"><strong>acl</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
47
<dt><span class="section"><a href="Bv9ARM.ch06.html#acl"><span class="command"><strong>acl</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
48
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
49
<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_grammar"><span class="command"><strong>controls</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
50
<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage"><span class="command"><strong>controls</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
51
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
52 53 54 55 56 57 58 59 60 61
<dt><span class="section"><a href="Bv9ARM.ch06.html#include_grammar"><span class="command"><strong>include</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#include_statement"><span class="command"><strong>include</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#key_grammar"><span class="command"><strong>key</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#key_statement"><span class="command"><strong>key</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_grammar"><span class="command"><strong>logging</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_statement"><span class="command"><strong>logging</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_grammar"><span class="command"><strong>lwres</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_statement"><span class="command"><strong>lwres</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_grammar"><span class="command"><strong>masters</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_statement"><span class="command"><strong>masters</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
62
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
63
<dt><span class="section"><a href="Bv9ARM.ch06.html#options_grammar"><span class="command"><strong>options</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
64
<dt><span class="section"><a href="Bv9ARM.ch06.html#options"><span class="command"><strong>options</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
65
          Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
66 67
<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_grammar"><span class="command"><strong>server</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_definition_and_usage"><span class="command"><strong>server</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
68
            Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
69
<dt><span class="section"><a href="Bv9ARM.ch06.html#statschannels"><span class="command"><strong>statistics-channels</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
70
<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_channels"><span class="command"><strong>statistics-channels</strong></span> Statement Definition and
Automatic Updater's avatar
regen  
Automatic Updater committed
71
            Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
72
<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted-keys"><span class="command"><strong>trusted-keys</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
73
<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted_keys"><span class="command"><strong>trusted-keys</strong></span> Statement Definition
Automatic Updater's avatar
regen  
Automatic Updater committed
74
            and Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
75
<dt><span class="section"><a href="Bv9ARM.ch06.html#managed_keys"><span class="command"><strong>managed-keys</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
76
<dt><span class="section"><a href="Bv9ARM.ch06.html#managed-keys"><span class="command"><strong>managed-keys</strong></span> Statement Definition
Rob Austein's avatar
regen  
Rob Austein committed
77
            and Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
78
<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement_grammar"><span class="command"><strong>view</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
79
<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement"><span class="command"><strong>view</strong></span> Statement Definition and Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
80
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement_grammar"><span class="command"><strong>zone</strong></span>
Rob Austein's avatar
regen  
Rob Austein committed
81
            Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
82
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement"><span class="command"><strong>zone</strong></span> Statement Definition and Usage</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
83
</dl></dd>
Tinderbox User's avatar
Tinderbox User committed
84
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_file">Zone File</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
85
<dd><dl>
Evan Hunt's avatar
Evan Hunt committed
86
<dt><span class="section"><a href="Bv9ARM.ch06.html#types_of_resource_records_and_when_to_use_them">Types of Resource Records and When to Use Them</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
87
<dt><span class="section"><a href="Bv9ARM.ch06.html#mx_records">Discussion of MX Records</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
88
<dt><span class="section"><a href="Bv9ARM.ch06.html#Setting_TTLs">Setting TTLs</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
89 90 91
<dt><span class="section"><a href="Bv9ARM.ch06.html#ipv4_reverse">Inverse Mapping in IPv4</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_directives">Other Zone File Directives</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#generate_directive"><acronym class="acronym">BIND</acronym> Master File Extension: the  <span class="command"><strong>$GENERATE</strong></span> Directive</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
92 93 94 95 96 97
<dt><span class="section"><a href="Bv9ARM.ch06.html#zonefile_format">Additional File Formats</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics">BIND9 Statistics</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="Bv9ARM.ch06.html#statsfile">The Statistics File</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_counters">Statistics Counters</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
98 99 100
</dl></dd>
</dl>
</div>
Tinderbox User's avatar
Tinderbox User committed
101 102

    <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
103 104
      <acronym class="acronym">BIND</acronym> 9 configuration is broadly similar
      to <acronym class="acronym">BIND</acronym> 8; however, there are a few new
Rob Austein's avatar
regen  
Rob Austein committed
105
      areas
Mark Andrews's avatar
regen  
Mark Andrews committed
106 107
      of configuration, such as views. <acronym class="acronym">BIND</acronym>
      8 configuration files should work with few alterations in <acronym class="acronym">BIND</acronym>
Rob Austein's avatar
regen  
Rob Austein committed
108 109
      9, although more complex configurations should be reviewed to check
      if they can be more efficiently implemented using the new features
Mark Andrews's avatar
regen  
Mark Andrews committed
110
      found in <acronym class="acronym">BIND</acronym> 9.
Rob Austein's avatar
regen  
Rob Austein committed
111
    </p>
Tinderbox User's avatar
Tinderbox User committed
112 113

    <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
114
      <acronym class="acronym">BIND</acronym> 4 configuration files can be
Rob Austein's avatar
regen  
Rob Austein committed
115 116 117 118
      converted to the new format
      using the shell script
      <code class="filename">contrib/named-bootconf/named-bootconf.sh</code>.
    </p>
Tinderbox User's avatar
Tinderbox User committed
119
    <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
120 121
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="configuration_file_elements"></a>Configuration File Elements</h2></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
122 123

      <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
124
        Following is a list of elements used throughout the <acronym class="acronym">BIND</acronym> configuration
Rob Austein's avatar
regen  
Rob Austein committed
125 126
        file documentation:
      </p>
Tinderbox User's avatar
Tinderbox User committed
127 128
      <div class="informaltable">
        <table border="1">
Rob Austein's avatar
regen  
Rob Austein committed
129
<colgroup>
Evan Hunt's avatar
Evan Hunt committed
130 131
<col width="1.855in" class="1">
<col width="3.770in" class="2">
Rob Austein's avatar
regen  
Rob Austein committed
132 133 134 135 136 137 138 139 140 141 142
</colgroup>
<tbody>
<tr>
<td>
                <p>
                  <code class="varname">acl_name</code>
                </p>
              </td>
<td>
                <p>
                  The name of an <code class="varname">address_match_list</code> as
Evan Hunt's avatar
Evan Hunt committed
143
                  defined by the <span class="command"><strong>acl</strong></span> statement.
Rob Austein's avatar
regen  
Rob Austein committed
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">address_match_list</code>
                </p>
              </td>
<td>
                <p>
                  A list of one or more
                  <code class="varname">ip_addr</code>,
                  <code class="varname">ip_prefix</code>, <code class="varname">key_id</code>,
                  or <code class="varname">acl_name</code> elements, see
Evan Hunt's avatar
Evan Hunt committed
159
                  <a class="xref" href="Bv9ARM.ch06.html#address_match_lists" title="Address Match Lists">the section called &#8220;Address Match Lists&#8221;</a>.
Rob Austein's avatar
regen  
Rob Austein committed
160 161 162 163
                </p>
              </td>
</tr>
<tr>
Mark Andrews's avatar
gregen  
Mark Andrews committed
164 165 166 167 168 169 170 171
<td>
                <p>
                  <code class="varname">masters_list</code>
                </p>
              </td>
<td>
                <p>
                  A named list of one or more <code class="varname">ip_addr</code>
Mark Andrews's avatar
regen  
Mark Andrews committed
172
                  with optional <code class="varname">key_id</code> and/or
Mark Andrews's avatar
gregen  
Mark Andrews committed
173 174 175 176 177 178 179
                  <code class="varname">ip_port</code>.
                  A <code class="varname">masters_list</code> may include other
                  <code class="varname">masters_lists</code>.
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen  
Rob Austein committed
180 181 182 183 184 185 186 187 188 189 190 191 192
<td>
                <p>
                  <code class="varname">domain_name</code>
                </p>
              </td>
<td>
                <p>
                  A quoted string which will be used as
                  a DNS name, for example "<code class="literal">my.test.domain</code>".
                </p>
              </td>
</tr>
<tr>
Automatic Updater's avatar
regen  
Automatic Updater committed
193 194 195 196 197 198 199 200 201 202 203 204 205
<td>
                <p>
                  <code class="varname">namelist</code>
                </p>
              </td>
<td>
                <p>
                  A list of one or more <code class="varname">domain_name</code>
                  elements.
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen  
Rob Austein committed
206 207 208 209 210 211 212 213
<td>
                <p>
                  <code class="varname">dotted_decimal</code>
                </p>
              </td>
<td>
                <p>
                  One to four integers valued 0 through
Evan Hunt's avatar
Evan Hunt committed
214 215
                  255 separated by dots (`.'), such as <span class="command"><strong>123</strong></span>,
                  <span class="command"><strong>45.67</strong></span> or <span class="command"><strong>89.123.45.67</strong></span>.
Rob Austein's avatar
regen  
Rob Austein committed
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">ip4_addr</code>
                </p>
              </td>
<td>
                <p>
                  An IPv4 address with exactly four elements
                  in <code class="varname">dotted_decimal</code> notation.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">ip6_addr</code>
                </p>
              </td>
<td>
                <p>
Evan Hunt's avatar
Evan Hunt committed
240
                  An IPv6 address, such as <span class="command"><strong>2001:db8::1234</strong></span>.
Mark Andrews's avatar
regen  
Mark Andrews committed
241 242 243 244 245 246 247 248 249
                  IPv6 scoped addresses that have ambiguity on their
                  scope zones must be disambiguated by an appropriate
                  zone ID with the percent character (`%') as
                  delimiter.  It is strongly recommended to use
                  string zone names rather than numeric identifiers,
                  in order to be robust against system configuration
                  changes.  However, since there is no standard
                  mapping for such names and identifier values,
                  currently only interface names as link identifiers
Rob Austein's avatar
regen  
Rob Austein committed
250
                  are supported, assuming one-to-one mapping between
Mark Andrews's avatar
regen  
Mark Andrews committed
251
                  interfaces and links.  For example, a link-local
Evan Hunt's avatar
Evan Hunt committed
252 253 254
                  address <span class="command"><strong>fe80::1</strong></span> on the link
                  attached to the interface <span class="command"><strong>ne0</strong></span>
                  can be specified as <span class="command"><strong>fe80::1%ne0</strong></span>.
Mark Andrews's avatar
regen  
Mark Andrews committed
255 256 257
                  Note that on most systems link-local addresses
                  always have the ambiguity, and need to be
                  disambiguated.
Rob Austein's avatar
regen  
Rob Austein committed
258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">ip_addr</code>
                </p>
              </td>
<td>
                <p>
                  An <code class="varname">ip4_addr</code> or <code class="varname">ip6_addr</code>.
                </p>
              </td>
</tr>
<tr>
Tinderbox User's avatar
Tinderbox User committed
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
<td>
                <p>
                  <code class="varname">ip_dscp</code>
                </p>
              </td>
<td>
                <p>
                  A <code class="varname">number</code> between 0 and 63, used
                  to select a differentiated services code point (DSCP)
                  value for use with outgoing traffic on operating systems
                  that support DSCP.
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen  
Rob Austein committed
289 290 291 292 293 294 295 296
<td>
                <p>
                  <code class="varname">ip_port</code>
                </p>
              </td>
<td>
                <p>
                  An IP port <code class="varname">number</code>.
Mark Andrews's avatar
regen  
Mark Andrews committed
297
                  The <code class="varname">number</code> is limited to 0
Rob Austein's avatar
regen  
Rob Austein committed
298 299 300
                  through 65535, with values
                  below 1024 typically restricted to use by processes running
                  as root.
Mark Andrews's avatar
regen  
Mark Andrews committed
301
                  In some cases, an asterisk (`*') character can be used as a
Rob Austein's avatar
regen  
Rob Austein committed
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
                  placeholder to
                  select a random high-numbered port.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">ip_prefix</code>
                </p>
              </td>
<td>
                <p>
                  An IP network specified as an <code class="varname">ip_addr</code>,
                  followed by a slash (`/') and then the number of bits in the
                  netmask.
                  Trailing zeros in a <code class="varname">ip_addr</code>
                  may omitted.
Evan Hunt's avatar
Evan Hunt committed
320 321 322 323
                  For example, <span class="command"><strong>127/8</strong></span> is the
                  network <span class="command"><strong>127.0.0.0</strong></span> with
                  netmask <span class="command"><strong>255.0.0.0</strong></span> and <span class="command"><strong>1.2.3.0/28</strong></span> is
                  network <span class="command"><strong>1.2.3.0</strong></span> with netmask <span class="command"><strong>255.255.255.240</strong></span>.
Rob Austein's avatar
regen  
Rob Austein committed
324
                </p>
Mark Andrews's avatar
regen  
Mark Andrews committed
325 326 327 328 329
                <p>
                  When specifying a prefix involving a IPv6 scoped address
                  the scope may be omitted.  In that case the prefix will
                  match packets from any scope.
                </p>
Rob Austein's avatar
regen  
Rob Austein committed
330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">key_id</code>
                </p>
              </td>
<td>
                <p>
                  A <code class="varname">domain_name</code> representing
                  the name of a shared key, to be used for transaction
                  security.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">key_list</code>
                </p>
              </td>
<td>
                <p>
                  A list of one or more
                  <code class="varname">key_id</code>s,
                  separated by semicolons and ending with a semicolon.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">number</code>
                </p>
              </td>
<td>
                <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
368
                  A non-negative 32-bit integer
Rob Austein's avatar
regen  
Rob Austein committed
369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388
                  (i.e., a number between 0 and 4294967295, inclusive).
                  Its acceptable value might further
                  be limited by the context in which it is used.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">path_name</code>
                </p>
              </td>
<td>
                <p>
                  A quoted string which will be used as
                  a pathname, such as <code class="filename">zones/master/my.test.domain</code>.
                </p>
              </td>
</tr>
<tr>
Automatic Updater's avatar
regen  
Automatic Updater committed
389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415
<td>
                <p>
                  <code class="varname">port_list</code>
                </p>
              </td>
<td>
                <p>
                  A list of an <code class="varname">ip_port</code> or a port
                  range.
                  A port range is specified in the form of
                  <strong class="userinput"><code>range</code></strong> followed by
                  two <code class="varname">ip_port</code>s,
                  <code class="varname">port_low</code> and
                  <code class="varname">port_high</code>, which represents
                  port numbers from <code class="varname">port_low</code> through
                  <code class="varname">port_high</code>, inclusive.
                  <code class="varname">port_low</code> must not be larger than
                  <code class="varname">port_high</code>.
                  For example,
                  <strong class="userinput"><code>range 1024 65535</code></strong> represents
                  ports from 1024 through 65535.
                  In either case an asterisk (`*') character is not
                  allowed as a valid <code class="varname">ip_port</code>.
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen  
Rob Austein committed
416 417 418 419 420 421 422
<td>
                <p>
                  <code class="varname">size_spec</code>
                </p>
              </td>
<td>
                <p>
Tinderbox User's avatar
Tinderbox User committed
423 424 425
                  A 64-bit unsigned integer, or the keywords
                  <strong class="userinput"><code>unlimited</code></strong> or
                  <strong class="userinput"><code>default</code></strong>.
Rob Austein's avatar
regen  
Rob Austein committed
426
                </p>
Mark Andrews's avatar
gregen  
Mark Andrews committed
427
                <p>
Tinderbox User's avatar
Tinderbox User committed
428 429
                  Integers may take values
                  0 &lt;= value &lt;= 18446744073709551615, though
Tinderbox User's avatar
Tinderbox User committed
430
                  certain parameters
Evan Hunt's avatar
Evan Hunt committed
431
                  (such as <span class="command"><strong>max-journal-size</strong></span>) may
Tinderbox User's avatar
Tinderbox User committed
432 433 434 435
                  use a more limited range within these extremes.
                  In most cases, setting a value to 0 does not
                  literally mean zero; it means "undefined" or
                  "as big as possible", depending on the context.
Tinderbox User's avatar
Tinderbox User committed
436
                  See the explanations of particular parameters
Tinderbox User's avatar
Tinderbox User committed
437
                  that use <code class="varname">size_spec</code>
Tinderbox User's avatar
Tinderbox User committed
438
                  for details on how they interpret its use.
Rob Austein's avatar
regen  
Rob Austein committed
439 440
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
441 442
                  Numeric values can optionally be followed by a
                  scaling factor:
Mark Andrews's avatar
gregen  
Mark Andrews committed
443 444 445 446
                  <strong class="userinput"><code>K</code></strong> or <strong class="userinput"><code>k</code></strong>
                  for kilobytes,
                  <strong class="userinput"><code>M</code></strong> or <strong class="userinput"><code>m</code></strong>
                  for megabytes, and
Tinderbox User's avatar
Tinderbox User committed
447 448 449
                  <strong class="userinput"><code>G</code></strong> or <strong class="userinput"><code>g</code></strong>
                  for gigabytes, which scale by 1024, 1024*1024, and
                  1024*1024*1024 respectively.
Rob Austein's avatar
regen  
Rob Austein committed
450 451
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
452
                  <code class="varname">unlimited</code> generally means
Tinderbox User's avatar
Tinderbox User committed
453 454
                  "as big as possible", and is usually the best
                  way to safely set a very large number.
Tinderbox User's avatar
Tinderbox User committed
455 456
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
457
                  <code class="varname">default</code>
Tinderbox User's avatar
Tinderbox User committed
458
                  uses the limit that was in force when the server was started.
Rob Austein's avatar
regen  
Rob Austein committed
459 460 461 462
                </p>
              </td>
</tr>
<tr>
Tinderbox User's avatar
Tinderbox User committed
463 464 465 466 467 468 469 470 471 472 473
<td>
                <p>
                  <code class="varname">size_or_percent</code>
                </p>
              </td>
<td>
                <p>
                  <code class="varname">size_spec</code> or integer value
                  followed by '%' to represent percents.
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
474
                  The behavior is exactly the same as
Tinderbox User's avatar
Tinderbox User committed
475 476 477 478 479 480 481 482
                  <code class="varname">size_spec</code>, but
                  <code class="varname">size_or_percent</code> allows also
                  to specify a positive integer value followed by
                  '%' sign to represent percents.
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen  
Rob Austein committed
483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515
<td>
                <p>
                  <code class="varname">yes_or_no</code>
                </p>
              </td>
<td>
                <p>
                  Either <strong class="userinput"><code>yes</code></strong> or <strong class="userinput"><code>no</code></strong>.
                  The words <strong class="userinput"><code>true</code></strong> and <strong class="userinput"><code>false</code></strong> are
                  also accepted, as are the numbers <strong class="userinput"><code>1</code></strong>
                  and <strong class="userinput"><code>0</code></strong>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">dialup_option</code>
                </p>
              </td>
<td>
                <p>
                  One of <strong class="userinput"><code>yes</code></strong>,
                  <strong class="userinput"><code>no</code></strong>, <strong class="userinput"><code>notify</code></strong>,
                  <strong class="userinput"><code>notify-passive</code></strong>, <strong class="userinput"><code>refresh</code></strong> or
                  <strong class="userinput"><code>passive</code></strong>.
                  When used in a zone, <strong class="userinput"><code>notify-passive</code></strong>,
                  <strong class="userinput"><code>refresh</code></strong>, and <strong class="userinput"><code>passive</code></strong>
                  are restricted to slave and stub zones.
                </p>
              </td>
</tr>
</tbody>
Tinderbox User's avatar
Tinderbox User committed
516 517 518
</table>
      </div>
      <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
519 520
<div class="titlepage"><div><div><h3 class="title">
<a name="address_match_lists"></a>Address Match Lists</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
521 522

        <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
523
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
524
<a name="id-1.7.4.4.2"></a>Syntax</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
525

Tinderbox User's avatar
Tinderbox User committed
526 527 528 529
<pre class="programlisting"><em class="replaceable"><code>address_match_list</code></em> = <em class="replaceable"><code>address_match_list_element</code></em> <span class="command"><strong>;</strong></span> ...

<em class="replaceable"><code>address_match_list_element</code></em> = [ <span class="command"><strong>!</strong></span> ] ( <em class="replaceable"><code>ip_address</code></em> | <em class="replaceable"><code>ip_prefix</code></em> |
     <span class="command"><strong>key</strong></span> <em class="replaceable"><code>key_id</code></em> | <em class="replaceable"><code>acl_name</code></em> | <span class="command"><strong>{</strong></span> <em class="replaceable"><code>address_match_list</code></em> <span class="command"><strong>}</strong></span> )
Rob Austein's avatar
regen  
Rob Austein committed
530
</pre>
Tinderbox User's avatar
Tinderbox User committed
531 532 533

        </div>
        <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
534
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
535
<a name="id-1.7.4.4.3"></a>Definition and Usage</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
536 537

          <p>
Rob Austein's avatar
regen  
Rob Austein committed
538 539
            Address match lists are primarily used to determine access
            control for various server operations. They are also used in
Evan Hunt's avatar
Evan Hunt committed
540
            the <span class="command"><strong>listen-on</strong></span> and <span class="command"><strong>sortlist</strong></span>
Mark Andrews's avatar
regen  
Mark Andrews committed
541 542
            statements. The elements which constitute an address match
            list can be any of the following:
Rob Austein's avatar
regen  
Rob Austein committed
543
          </p>
Tinderbox User's avatar
Tinderbox User committed
544 545 546 547 548 549 550
          <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              an IP address (IPv4 or IPv6)
            </li>
<li class="listitem">
              an IP prefix (in `/' notation)
            </li>
Evan Hunt's avatar
Evan Hunt committed
551
<li class="listitem">
Tinderbox User's avatar
Tinderbox User committed
552
              
Evan Hunt's avatar
Evan Hunt committed
553
                a key ID, as defined by the <span class="command"><strong>key</strong></span>
Rob Austein's avatar
regen  
Rob Austein committed
554
                statement
Tinderbox User's avatar
Tinderbox User committed
555 556 557 558
              
            </li>
<li class="listitem">
              the name of an address match list defined with
Evan Hunt's avatar
Evan Hunt committed
559
                the <span class="command"><strong>acl</strong></span> statement
Tinderbox User's avatar
Tinderbox User committed
560 561 562 563 564
              
            </li>
<li class="listitem">
              a nested address match list enclosed in braces
            </li>
Rob Austein's avatar
regen  
Rob Austein committed
565
</ul></div>
Tinderbox User's avatar
Tinderbox User committed
566 567

          <p>
Rob Austein's avatar
regen  
Rob Austein committed
568 569
            Elements can be negated with a leading exclamation mark (`!'),
            and the match list names "any", "none", "localhost", and
Mark Andrews's avatar
regen  
Mark Andrews committed
570 571
            "localnets" are predefined. More information on those names
            can be found in the description of the acl statement.
Rob Austein's avatar
regen  
Rob Austein committed
572
          </p>
Tinderbox User's avatar
Tinderbox User committed
573 574

          <p>
Rob Austein's avatar
regen  
Rob Austein committed
575 576 577
            The addition of the key clause made the name of this syntactic
            element something of a misnomer, since security keys can be used
            to validate access without regard to a host or network address.
Mark Andrews's avatar
regen  
Mark Andrews committed
578 579
            Nonetheless, the term "address match list" is still used
            throughout the documentation.
Rob Austein's avatar
regen  
Rob Austein committed
580
          </p>
Tinderbox User's avatar
Tinderbox User committed
581 582

          <p>
Rob Austein's avatar
regen  
Rob Austein committed
583
            When a given IP address or prefix is compared to an address
Mark Andrews's avatar
regen  
Mark Andrews committed
584 585 586 587 588
            match list, the comparison takes place in approximately O(1)
            time.  However, key comparisons require that the list of keys
            be traversed until a matching key is found, and therefore may
            be somewhat slower.
          </p>
Tinderbox User's avatar
Tinderbox User committed
589 590

          <p>
Rob Austein's avatar
regen  
Rob Austein committed
591
            The interpretation of a match depends on whether the list is being
Evan Hunt's avatar
Evan Hunt committed
592 593
            used for access control, defining <span class="command"><strong>listen-on</strong></span> ports, or in a
            <span class="command"><strong>sortlist</strong></span>, and whether the element was negated.
Rob Austein's avatar
regen  
Rob Austein committed
594
          </p>
Tinderbox User's avatar
Tinderbox User committed
595 596

          <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
597 598 599
            When used as an access control list, a non-negated match
            allows access and a negated match denies access. If
            there is no match, access is denied. The clauses
Evan Hunt's avatar
Evan Hunt committed
600 601 602 603 604 605 606 607 608 609 610 611 612
            <span class="command"><strong>allow-notify</strong></span>,
            <span class="command"><strong>allow-recursion</strong></span>,
            <span class="command"><strong>allow-recursion-on</strong></span>,
            <span class="command"><strong>allow-query</strong></span>,
            <span class="command"><strong>allow-query-on</strong></span>,
            <span class="command"><strong>allow-query-cache</strong></span>,
            <span class="command"><strong>allow-query-cache-on</strong></span>,
            <span class="command"><strong>allow-transfer</strong></span>,
            <span class="command"><strong>allow-update</strong></span>,
            <span class="command"><strong>allow-update-forwarding</strong></span>,
            <span class="command"><strong>blackhole</strong></span>, and
            <span class="command"><strong>keep-response-order</strong></span> all use address match
            lists.  Similarly, the <span class="command"><strong>listen-on</strong></span> option will cause the
Mark Andrews's avatar
regen  
Mark Andrews committed
613
            server to refuse queries on any of the machine's
Mark Andrews's avatar
regen  
Mark Andrews committed
614
            addresses which do not match the list.
Rob Austein's avatar
regen  
Rob Austein committed
615
          </p>
Tinderbox User's avatar
Tinderbox User committed
616 617

          <p>
Automatic Updater's avatar
regen  
Automatic Updater committed
618
            Order of insertion is significant.  If more than one element
Mark Andrews's avatar
regen  
Mark Andrews committed
619 620 621 622 623 624 625
            in an ACL is found to match a given IP address or prefix,
            preference will be given to the one that came
            <span class="emphasis"><em>first</em></span> in the ACL definition.
            Because of this first-match behavior, an element that
            defines a subset of another element in the list should
            come before the broader element, regardless of whether
            either is negated. For example, in
Evan Hunt's avatar
Evan Hunt committed
626
            <span class="command"><strong>1.2.3/24; ! 1.2.3.13;</strong></span>
Mark Andrews's avatar
regen  
Mark Andrews committed
627 628
            the 1.2.3.13 element is completely useless because the
            algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24
Evan Hunt's avatar
Evan Hunt committed
629
            element.  Using <span class="command"><strong>! 1.2.3.13; 1.2.3/24</strong></span> fixes
Mark Andrews's avatar
regen  
Mark Andrews committed
630 631
            that problem by having 1.2.3.13 blocked by the negation, but
            all other 1.2.3.* hosts fall through.
Rob Austein's avatar
regen  
Rob Austein committed
632
          </p>
Tinderbox User's avatar
Tinderbox User committed
633 634 635 636
        </div>
      </div>

      <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
637
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
638
<a name="comment_syntax"></a>Comment Syntax</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
639 640

        <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
641
          The <acronym class="acronym">BIND</acronym> 9 comment syntax allows for
Rob Austein's avatar
regen  
Rob Austein committed
642
          comments to appear
Mark Andrews's avatar
regen  
Mark Andrews committed
643
          anywhere that whitespace may appear in a <acronym class="acronym">BIND</acronym> configuration
Rob Austein's avatar
regen  
Rob Austein committed
644 645 646
          file. To appeal to programmers of all kinds, they can be written
          in the C, C++, or shell/perl style.
        </p>
Tinderbox User's avatar
Tinderbox User committed
647 648

        <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
649
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
650
<a name="id-1.7.4.5.3"></a>Syntax</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
651 652

          <p>
Rob Austein's avatar
regen  
Rob Austein committed
653
            </p>
Mark Andrews's avatar
regen  
Mark Andrews committed
654
<pre class="programlisting">/* This is a <acronym class="acronym">BIND</acronym> comment as in C */</pre>
Rob Austein's avatar
regen  
Rob Austein committed
655 656
<p>
            </p>
Mark Andrews's avatar
regen  
Mark Andrews committed
657
<pre class="programlisting">// This is a <acronym class="acronym">BIND</acronym> comment as in C++</pre>
Rob Austein's avatar
regen  
Rob Austein committed
658 659
<p>
            </p>
Automatic Updater's avatar
regen  
Automatic Updater committed
660 661
<pre class="programlisting"># This is a <acronym class="acronym">BIND</acronym> comment as in common UNIX shells
# and perl</pre>
Rob Austein's avatar
regen  
Rob Austein committed
662 663
<p>
          </p>
Tinderbox User's avatar
Tinderbox User committed
664 665
        </div>
        <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
666
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
667
<a name="id-1.7.4.5.4"></a>Definition and Usage</h4></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
668 669

          <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
670
            Comments may appear anywhere that whitespace may appear in
Mark Andrews's avatar
regen  
Mark Andrews committed
671
            a <acronym class="acronym">BIND</acronym> configuration file.
Rob Austein's avatar
regen  
Rob Austein committed
672
          </p>
Tinderbox User's avatar
Tinderbox User committed
673
          <p>
Rob Austein's avatar
regen  
Rob Austein committed
674 675 676 677 678
            C-style comments start with the two characters /* (slash,
            star) and end with */ (star, slash). Because they are completely
            delimited with these characters, they can be used to comment only
            a portion of a line or to span multiple lines.
          </p>
Tinderbox User's avatar
Tinderbox User committed
679
          <p>
Rob Austein's avatar
regen  
Rob Austein committed
680 681 682
            C-style comments cannot be nested. For example, the following
            is not valid because the entire comment ends with the first */:
          </p>
Tinderbox User's avatar
Tinderbox User committed
683
          <p>
Rob Austein's avatar
regen  
Rob Austein committed
684 685 686

</p>
<pre class="programlisting">/* This is the start of a comment.
687 688 689
   This is still part of the comment.
/* This is an incorrect attempt at nesting a comment. */
   This is no longer in any comment. */
Rob Austein's avatar
regen  
Rob Austein committed
690 691 692 693
</pre>
<p>

          </p>
Tinderbox User's avatar
Tinderbox User committed
694 695

          <p>
Rob Austein's avatar
regen  
Rob Austein committed
696 697 698 699 700 701
            C++-style comments start with the two characters // (slash,
            slash) and continue to the end of the physical line. They cannot
            be continued across multiple physical lines; to have one logical
            comment span multiple lines, each line must use the // pair.
            For example:
          </p>
Tinderbox User's avatar
Tinderbox User committed
702
          <p>
Rob Austein's avatar
regen  
Rob Austein committed
703 704 705

</p>
<pre class="programlisting">// This is the start of a comment.  The next line
706 707
// is a new comment, even though it is logically
// part of the previous comment.
Rob Austein's avatar
regen  
Rob Austein committed
708 709 710 711
</pre>
<p>

          </p>
Tinderbox User's avatar
Tinderbox User committed
712
          <p>
Rob Austein's avatar
regen  
Rob Austein committed
713 714 715 716 717 718
            Shell-style (or perl-style, if you prefer) comments start
            with the character <code class="literal">#</code> (number sign)
            and continue to the end of the
            physical line, as in C++ comments.
            For example:
          </p>
Tinderbox User's avatar
Tinderbox User committed
719 720

          <p>
Rob Austein's avatar
regen  
Rob Austein committed
721 722 723

</p>
<pre class="programlisting"># This is the start of a comment.  The next line
724 725
# is a new comment, even though it is logically
# part of the previous comment.
Rob Austein's avatar
regen  
Rob Austein committed
726 727 728 729
</pre>
<p>

          </p>
Tinderbox User's avatar
Tinderbox User committed
730 731

          <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
Rob Austein's avatar
regen  
Rob Austein committed
732
<h3 class="title">Warning</h3>
Tinderbox User's avatar
Tinderbox User committed
733
            <p>
Rob Austein's avatar
regen  
Rob Austein committed
734 735 736 737 738
              You cannot use the semicolon (`;') character
              to start a comment such as you would in a zone file. The
              semicolon indicates the end of a configuration
              statement.
            </p>
Tinderbox User's avatar
Tinderbox User committed
739 740 741 742 743 744
          </div>
        </div>
      </div>
    </div>

    <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
745 746
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="Configuration_File_Grammar"></a>Configuration File Grammar</h2></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
747 748

      <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
749
        A <acronym class="acronym">BIND</acronym> 9 configuration consists of
Rob Austein's avatar
regen  
Rob Austein committed
750 751 752 753 754 755
        statements and comments.
        Statements end with a semicolon. Statements and comments are the
        only elements that can appear without enclosing braces. Many
        statements contain a block of sub-statements, which are also
        terminated with a semicolon.
      </p>
Tinderbox User's avatar
Tinderbox User committed
756 757

      <p>
Rob Austein's avatar
regen  
Rob Austein committed
758 759
        The following statements are supported:
      </p>
Tinderbox User's avatar
Tinderbox User committed
760 761 762

      <div class="informaltable">
        <table border="1">
Rob Austein's avatar
regen  
Rob Austein committed
763
<colgroup>
Evan Hunt's avatar
Evan Hunt committed
764 765
<col width="1.336in" class="1">
<col width="3.778in" class="2">
Rob Austein's avatar
regen  
Rob Austein committed
766 767 768 769
</colgroup>
<tbody>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
770
                <p><span class="command"><strong>acl</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
771 772 773 774 775 776 777 778 779 780
              </td>
<td>
                <p>
                  defines a named IP address
                  matching list, for access control and other uses.
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
781
                <p><span class="command"><strong>controls</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
782 783 784 785
              </td>
<td>
                <p>
                  declares control channels to be used
Evan Hunt's avatar
Evan Hunt committed
786
                  by the <span class="command"><strong>rndc</strong></span> utility.
Rob Austein's avatar
regen  
Rob Austein committed
787 788 789 790 791
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
792
                <p><span class="command"><strong>include</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
793 794 795 796 797 798 799 800 801
              </td>
<td>
                <p>
                  includes a file.
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
802
                <p><span class="command"><strong>key</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
803 804 805 806 807 808 809 810 811 812
              </td>
<td>
                <p>
                  specifies key information for use in
                  authentication and authorization using TSIG.
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
813
                <p><span class="command"><strong>logging</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
814 815 816 817 818 819 820 821 822 823
              </td>
<td>
                <p>
                  specifies what the server logs, and where
                  the log messages are sent.
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
824
                <p><span class="command"><strong>lwres</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
825 826 827
              </td>
<td>
                <p>
Evan Hunt's avatar
Evan Hunt committed
828 829
                  configures <span class="command"><strong>named</strong></span> to
                  also act as a light-weight resolver daemon (<span class="command"><strong>lwresd</strong></span>).
Rob Austein's avatar
regen  
Rob Austein committed
830 831 832 833 834
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
835
                <p><span class="command"><strong>masters</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
836 837 838 839
              </td>
<td>
                <p>
                  defines a named masters list for
Automatic Updater's avatar
Automatic Updater committed
840
                  inclusion in stub and slave zones'
Evan Hunt's avatar
Evan Hunt committed
841 842
                  <span class="command"><strong>masters</strong></span> or
                  <span class="command"><strong>also-notify</strong></span> lists.
Rob Austein's avatar
regen  
Rob Austein committed
843 844 845 846 847
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
848
                <p><span class="command"><strong>options</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
849 850 851 852 853 854 855 856 857
              </td>
<td>
                <p>
                  controls global server configuration
                  options and sets defaults for other statements.
                </p>
              </td>
</tr>
<tr>
Mark Andrews's avatar
regen  
Mark Andrews committed
858
<td>
Evan Hunt's avatar
Evan Hunt committed
859
                <p><span class="command"><strong>server</strong></span></p>
Mark Andrews's avatar
regen  
Mark Andrews committed
860 861 862
              </td>
<td>
                <p>
Automatic Updater's avatar
regen  
Automatic Updater committed
863 864
                  sets certain configuration options on
                  a per-server basis.
Mark Andrews's avatar
regen  
Mark Andrews committed
865 866 867 868
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen  
Rob Austein committed
869
<td>
Evan Hunt's avatar
Evan Hunt committed
870
                <p><span class="command"><strong>statistics-channels</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
871 872 873
              </td>
<td>
                <p>
Automatic Updater's avatar
regen  
Automatic Updater committed
874
                  declares communication channels to get access to
Evan Hunt's avatar
Evan Hunt committed
875
                  <span class="command"><strong>named</strong></span> statistics.
Rob Austein's avatar
regen  
Rob Austein committed
876 877 878 879 880
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
881
                <p><span class="command"><strong>trusted-keys</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
882 883 884 885 886 887 888 889
              </td>
<td>
                <p>
                  defines trusted DNSSEC keys.
                </p>
              </td>
</tr>
<tr>
Automatic Updater's avatar
regen  
Automatic Updater committed
890
<td>
Evan Hunt's avatar
Evan Hunt committed
891
                <p><span class="command"><strong>managed-keys</strong></span></p>
Automatic Updater's avatar
regen  
Automatic Updater committed
892 893 894 895 896 897 898 899 900
              </td>
<td>
                <p>
                  lists DNSSEC keys to be kept up to date
                  using RFC 5011 trust anchor maintenance.
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen  
Rob Austein committed
901
<td>
Evan Hunt's avatar
Evan Hunt committed
902
                <p><span class="command"><strong>view</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
903 904 905 906 907 908 909 910 911
              </td>
<td>
                <p>
                  defines a view.
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
912
                <p><span class="command"><strong>zone</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
913 914 915 916 917 918 919 920
              </td>
<td>
                <p>
                  defines a zone.
                </p>
              </td>
</tr>
</tbody>
Tinderbox User's avatar
Tinderbox User committed
921 922 923 924
</table>
      </div>

      <p>
Evan Hunt's avatar
Evan Hunt committed
925 926
        The <span class="command"><strong>logging</strong></span> and
        <span class="command"><strong>options</strong></span> statements may only occur once
Rob Austein's avatar
regen  
Rob Austein committed
927 928 929
        per
        configuration.
      </p>
Tinderbox User's avatar
Tinderbox User committed
930 931

      <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
932
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
933
<a name="acl_grammar"></a><span class="command"><strong>acl</strong></span> Statement Grammar</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
934

Tinderbox User's avatar
Tinderbox User committed
935 936 937
<pre class="programlisting"><span class="command"><strong>acl</strong></span> <em class="replaceable"><code>acl-name</code></em> <span class="command"><strong>{</strong></span>
    <em class="replaceable"><code>address_match_list</code></em>
<span class="command"><strong>};</strong></span>
Rob Austein's avatar
regen  
Rob Austein committed
938
</pre>
Tinderbox User's avatar
Tinderbox User committed
939 940 941

      </div>
      <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
942
<div class="titlepage"><div><div><h3 class="title">
Evan Hunt's avatar
Evan Hunt committed
943
<a name="acl"></a><span class="command"><strong>acl</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
944
          Usage</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
945 946

        <p>
Evan Hunt's avatar
Evan Hunt committed
947
          The <span class="command"><strong>acl</strong></span> statement assigns a symbolic
Rob Austein's avatar
regen  
Rob Austein committed
948 949 950
          name to an address match list. It gets its name from a primary
          use of address match lists: Access Control Lists (ACLs).
        </p>
Tinderbox User's avatar
Tinderbox User committed
951 952

        <p>
Rob Austein's avatar
regen  
Rob Austein committed
953 954
          The following ACLs are built-in:
        </p>
Tinderbox User's avatar
Tinderbox User committed
955 956 957

        <div class="informaltable">
          <table border="1">
Rob Austein's avatar
regen  
Rob Austein committed
958
<colgroup>
Evan Hunt's avatar
Evan Hunt committed
959 960
<col width="1.130in" class="1">
<col width="4.000in" class="2">
Rob Austein's avatar
regen  
Rob Austein committed
961 962 963 964
</colgroup>
<tbody>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
965
                  <p><span class="command"><strong>any</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
966 967 968 969 970 971 972 973 974
                </td>
<td>
                  <p>
                    Matches all hosts.
                  </p>
                </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
975
                  <p><span class="command"><strong>none</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
976 977 978 979 980 981 982 983 984
                </td>
<td>
                  <p>
                    Matches no hosts.
                  </p>
                </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
985
                  <p><span class="command"><strong>localhost</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
986 987 988 989
                </td>
<td>
                  <p>
                    Matches the IPv4 and IPv6 addresses of all network
Tinderbox User's avatar
Tinderbox User committed
990
                    interfaces on the system.  When addresses are
Evan Hunt's avatar
Evan Hunt committed
991
                    added or removed, the <span class="command"><strong>localhost</strong></span>
Tinderbox User's avatar
Tinderbox User committed
992
                    ACL element is updated to reflect the changes.
Rob Austein's avatar
regen  
Rob Austein committed
993 994 995 996 997
                  </p>
                </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
Evan Hunt committed
998
                  <p><span class="command"><strong>localnets</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
999 1000 1001 1002 1003
                </td>
<td>
                  <p>
                    Matches any host on an IPv4 or IPv6 network
                    for which the system has an interface.
Tinderbox User's avatar
Tinderbox User committed
1004
                    When addresses are added or removed,
Evan Hunt's avatar
Evan Hunt committed
1005
                    the <span class="command"><strong>localnets</strong></span>
Tinderbox User's avatar
Tinderbox User committed
1006
                    ACL element is updated to reflect the changes.
Rob Austein's avatar
regen  
Rob Austein committed
1007 1008 1009
                    Some systems do not provide a way to determine the prefix
                    lengths of
                    local IPv6 addresses.
Evan Hunt's avatar
Evan Hunt committed
1010
                    In such a case, <span class="command"><strong>localnets</strong></span>
Rob Austein's avatar
regen  
Rob Austein committed
1011
                    only matches the local
Evan Hunt's avatar
Evan Hunt committed
1012
                    IPv6 addresses, just like <span class="command"><strong>localhost</strong></span>.
Rob Austein's avatar
regen  
Rob Austein committed
1013 1014 1015 1016
                  </p>
                </td>
</tr>
</tbody>
Tinderbox User's avatar
Tinderbox User committed
1017 1018 1019 1020
</table>
        </div>
      </div>
      <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
1021
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1022
<a name="controls_grammar"></a><span class="command"><strong>controls</strong></span> Statement Grammar</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
1023

Tinderbox User's avatar
Tinderbox User committed
1024 1025 1026 1027 1028 1029 1030 1031 1032
<pre class="programlisting"><span class="command"><strong>controls {</strong></span>
  [ <span class="command"><strong>inet</strong></span> ( <em class="replaceable"><code>ip_addr</code></em> | <span class="command"><strong>*</strong></span> ) [ <span class="command"><strong>port</strong></span> <em class="replaceable"><code>ip_port</code></em> ] <span class="command"><strong>allow {</strong></span> <em class="replaceable"><code>address_match_list</code></em> <span class="command"><strong>}</strong></span>
      [ <span class="command"><strong>keys {</strong></span> <em class="replaceable"><code>key_list</code></em> <span class="command"><strong>}</strong></span> ]
      [ <span class="command"><strong>read-only</strong></span> <em class="replaceable"><code>yes_or_no</code></em> ] <span class="command"><strong>;</strong></span> ]
  [ <span class="command"><strong>unix</strong></span> <em class="replaceable"><code>path</code></em> <span class="command"><strong>perm</strong></span> <em class="replaceable"><code>number</code></em> <span class="command"><strong>owner</strong></span> <em class="replaceable"><code>number</code></em> <span class="command"><strong>group</strong></span> <em class="replaceable"><code>number</code></em>
      [ <span class="command"><strong>keys {</strong></span> <em class="replaceable"><code>key_list</code></em> <span class="command"><strong>}</strong></span> ]
      [ <span class="command"><strong>read-only</strong></span> <em class="replaceable"><code>yes_or_no</code></em> ] <span class="command"><strong>;</strong></span> ]
   [ ...; ]
<span class="command"><strong>};</strong></span>
Rob Austein's avatar
regen  
Rob Austein committed
1033
</pre>
Tinderbox User's avatar
Tinderbox User committed
1034 1035 1036 1037

      </div>

      <div class="section">
Rob Austein's avatar
regen  
Rob Austein committed
1038
<div class="titlepage"><div><div><h3 class="title">
Evan Hunt's avatar
Evan Hunt committed
1039
<a name="controls_statement_definition_and_usage"></a><span class="command"><strong>controls</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
1040
          Usage</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
1041 1042

        <p>
Evan Hunt's avatar
Evan Hunt committed
1043
          The <span class="command"><strong>controls</strong></span> statement declares control
Rob Austein's avatar
regen  
Rob Austein committed
1044 1045
          channels to be used by system administrators to control the
          operation of the name server. These control channels are
Evan Hunt's avatar
Evan Hunt committed
1046
          used by the <span class="command"><strong>rndc</strong></span> utility to send
Mark Andrews's avatar
gregen  
Mark Andrews committed
1047
          commands to and retrieve non-DNS results from a name server.
Rob Austein's avatar
regen  
Rob Austein committed
1048
        </p>
Tinderbox User's avatar
Tinderbox User committed
1049 1050

        <p>
Evan Hunt's avatar
Evan Hunt committed
1051 1052 1053 1054
          An <span class="command"><strong>inet</strong></span> control channel is a TCP socket
          listening at the specified <span class="command"><strong>ip_port</strong></span> on the
          specified <span class="command"><strong>ip_addr</strong></span>, which can be an IPv4 or IPv6
          address.  An <span class="command"><strong>ip_addr</strong></span> of <code class="literal">*</code> (asterisk) is
Mark Andrews's avatar
gregen  
Mark Andrews committed
1055 1056 1057
          interpreted as the IPv4 wildcard address; connections will be
          accepted on any of the system's IPv4 addresses.
          To listen on the IPv6 wildcard address,
Evan Hunt's avatar
Evan Hunt committed
1058 1059
          use an <span class="command"><strong>ip_addr</strong></span> of <code class="literal">::</code>.
          If you will only use <span class="command"><strong>rndc</strong></span> on the local host,
Rob Austein's avatar
regen  
Rob Austein committed
1060
          using the loopback address (<code class="literal">127.0.0.1</code>
Mark Andrews's avatar
gregen  
Mark Andrews committed
1061
          or <code class="literal">::1</code>) is recommended for maximum security.
Rob Austein's avatar
regen  
Rob Austein committed
1062
        </p>
Tinderbox User's avatar
Tinderbox User committed
1063 1064

        <p>
Mark Andrews's avatar
regen  
Mark Andrews committed
1065
          If no port is specified, port 953 is used. The asterisk
Evan Hunt's avatar
Evan Hunt committed
1066
          "<code class="literal">*</code>" cannot be used for <span class="command"><strong>ip_port</strong></span>.
Rob Austein's avatar
regen  
Rob Austein committed
1067
        </p>
Tinderbox User's avatar
Tinderbox User committed
1068 1069

        <p>
Rob Austein's avatar
regen  
Rob Austein committed
1070
          The ability to issue commands over the control channel is
Evan Hunt's avatar
Evan Hunt committed
1071 1072
          restricted by the <span class="command"><strong>allow</strong></span> and
          <span class="command"><strong>keys</strong></span> clauses.
Mark Andrews's avatar
gregen  
Mark Andrews committed
1073
          Connections to the control channel are permitted based on the
Evan Hunt's avatar
Evan Hunt committed
1074 1075 1076
          <span class="command"><strong>address_match_list</strong></span>.  This is for simple
          IP address based filtering only; any <span class="command"><strong>key_id</strong></span>
          elements of the <span class="command"><strong>address_match_list</strong></span>
Mark Andrews's avatar
gregen  
Mark Andrews committed
1077 1078
          are ignored.
        </p>
Tinderbox User's avatar
Tinderbox User committed
1079 1080

        <p>
Evan Hunt's avatar
Evan Hunt committed
1081
          A <span class="command"><strong>unix</strong></span> control channel is a UNIX domain
Mark Andrews's avatar
gregen  
Mark Andrews committed
1082
          socket listening at the specified path in the file system.
Evan Hunt's avatar
Evan Hunt committed
1083 1084
          Access to the socket is specified by the <span class="command"><strong>perm</strong></span>,
          <span class="command"><strong>owner</strong></span> and <span class="command"><strong>group</strong></span> clauses.
Mark Andrews's avatar
gregen  
Mark Andrews committed
1085
          Note on some platforms (SunOS and Solaris) the permissions
Evan Hunt's avatar
Evan Hunt committed
1086
          (<span class="command"><strong>perm</strong></span>) are applied to the parent directory
Mark Andrews's avatar
gregen  
Mark Andrews committed
1087
          as the permissions on the socket itself are ignored.
Rob Austein's avatar
regen  
Rob Austein committed
1088
        </p>
Tinderbox User's avatar
Tinderbox User committed
1089 1090

        <p>
Rob Austein's avatar
regen  
Rob Austein committed
1091
          The primary authorization mechanism of the command
Evan Hunt's avatar
Evan Hunt committed
1092 1093 1094
          channel is the <span class="command"><strong>key_list</strong></span>, which
          contains a list of <span class="command"><strong>key_id</strong></span>s.
          Each <span class="command"><strong>key_id</strong></span> in the <span class="command"><strong>key_list</strong></span>
Mark Andrews's avatar
gregen  
Mark Andrews committed
1095
          is authorized to execute commands over the control channel.
Evan Hunt's avatar
Evan Hunt committed
1096 1097
          See <a class="xref" href="Bv9ARM.ch03.html#rndc">Remote Name Daemon Control application</a> in <a class="xref" href="Bv9ARM.ch03.html#admin_tools" title="Administrative Tools">the section called &#8220;Administrative Tools&#8221;</a>)
          for information about configuring keys in <span class="command"><strong>rndc</strong></span>.
Rob Austein's avatar
regen  
Rob Austein committed
1098
        </p>
Tinderbox User's avatar
Tinderbox User committed
1099 1100

        <p>
Tinderbox User's avatar
Tinderbox User committed
1101 1102 1103 1104 1105 1106 1107 1108 1109
          If the <span class="command"><strong>read-only</strong></span> clause is enabled, the
          control channel is limited to the following set of read-only
          commands: <span class="command"><strong>nta -dump</strong></span>,
          <span class="command"><strong>null</strong></span>, <span class="command"><strong>status</strong></span>,
          <span class="command"><strong>showzone</strong></span>, <span class="command"><strong>testgen</strong></span>, and
          <span class="command"><strong>zonestatus</strong></span>. By default,
          <span class="command"><strong>read-only</strong></span> is not enabled and the control
          channel allows read-write access.
        </p>
Tinderbox User's avatar
Tinderbox User committed
1110 1111

        <p>
Evan Hunt's avatar
Evan Hunt committed
1112 1113
          If no <span class="command"><strong>controls</strong></span> statement is present,
          <span class="command"><strong>named</strong></span> will set up a default
Rob Austein's avatar
regen  
Rob Austein committed
1114 1115
          control channel listening on the loopback address 127.0.0.1
          and its IPv6 counterpart ::1.
Evan Hunt's avatar
Evan Hunt committed
1116 1117 1118
          In this case, and also when the <span class="command"><strong>controls</strong></span> statement
          is present but does not have a <span class="command"><strong>keys</strong></span> clause,
          <span class="command"><strong>named</strong></span> will attempt to load the command channel key
Rob Austein's avatar
regen  
Rob Austein committed
1119 1120
          from the file <code class="filename">rndc.key</code> in
          <code class="filename">/etc</code> (or whatever <code class="varname">sysconfdir</code>
Mark Andrews's avatar
regen  
Mark Andrews committed
1121
          was specified as when <acronym class="acronym">BIND</acronym> was built).
Rob Austein's avatar
regen  
Rob Austein committed
1122 1123 1124
          To create a <code class="filename">rndc.key</code> file, run
          <strong class="userinput"><code>rndc-confgen -a</code></strong>.
        </p>
Tinderbox User's avatar
Tinderbox User committed
1125 1126

        <p>
Rob Austein's avatar
regen  
Rob Austein committed
1127
          The <code class="filename">rndc.key</code> feature was created to
Mark Andrews's avatar
regen  
Mark Andrews committed
1128
          ease the transition of systems from <acronym class="acronym">BIND</acronym> 8,
Rob Austein's avatar
regen  
Rob Austein committed
1129
          which did not have digital signatures on its command channel
Evan Hunt's avatar
Evan Hunt committed
1130
          messages and thus did not have a <span class="command"><strong>keys</strong></span> clause.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1131

Mark Andrews's avatar
regen  
Mark Andrews committed
1132 1133
          It makes it possible to use an existing <acronym class="acronym">BIND</acronym> 8
          configuration file in <acronym class="acronym">BIND</acronym> 9 unchanged,
Evan Hunt's avatar
Evan Hunt committed
1134 1135
          and still have <span class="command"><strong>rndc</strong></span> work the same way
          <span class="command"><strong>ndc</strong></span> worked in BIND 8, simply by executing the
Rob Austein's avatar
regen  
Rob Austein committed
1136 1137 1138
          command <strong class="userinput"><code>rndc-confgen -a</code></strong> after BIND 9 is
          installed.
        </p>
Tinderbox User's avatar
Tinderbox User committed
1139 1140

        <p>
Rob Austein's avatar
regen  
Rob Austein committed
1141 1142
          Since the <code class="filename">rndc.key</code> feature
          is only intended to allow the backward-compatible usage of
Mark Andrews's avatar
regen  
Mark Andrews committed
1143
          <acronym class="acronym">BIND</acronym> 8 configuration files, this
Rob Austein's avatar
regen  
Rob Austein committed
1144 1145 1146 1147 1148 1149 1150 1151
          feature does not
          have a high degree of configurability.  You cannot easily change
          the key name or the size of the secret, so you should make a
          <code class="filename">rndc.conf</code> with your own key if you
          wish to change
          those things.  The <code class="filename">rndc.key</code> file
          also has its
          permissions set such that only the owner of the file (the user that
Evan Hunt's avatar
Evan Hunt committed
1152
          <span class="command"><strong>named</strong></span> is running as) can access it.
Rob Austein's avatar
regen  
Rob Austein committed
1153 1154
          If you
          desire greater flexibility in allowing other users to access
Evan Hunt's avatar
Evan Hunt committed
1155
          <span class="command"><strong>rndc</strong></span> commands, then you need to create
Mark Andrews's avatar
regen  
Mark Andrews committed
1156 1157
          a
          <code class="filename">rndc.conf</code> file and make it group
Rob Austein's avatar
regen  
Rob Austein committed
1158 1159 1160
          readable by a group
          that contains the users who should have access.
        </p>
Tinderbox User's avatar
Tinderbox User committed
1161