/contrib/bind9/doc/arm/Bv9ARM.ch06.html
HTML | 10075 lines | 10019 code | 39 blank | 17 comment | 0 complexity | 23bebf82675bbeb8b00207a8416d590f MD5 | raw file
Large files files are truncated, but you can click here to view the full file
1<!-- 2 - Copyright (C) 2004-2012 Internet Systems Consortium, Inc. ("ISC") 3 - Copyright (C) 2000-2003 Internet Software Consortium. 4 - 5 - Permission to use, copy, modify, and/or distribute this software for any 6 - purpose with or without fee is hereby granted, provided that the above 7 - copyright notice and this permission notice appear in all copies. 8 - 9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 - PERFORMANCE OF THIS SOFTWARE. 16--> 17<!-- $Id$ --> 18<html> 19<head> 20<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 21<title>Chapter 6. BIND 9 Configuration Reference</title> 22<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> 23<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> 24<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> 25<link rel="prev" href="Bv9ARM.ch05.html" title="Chapter 5. The BIND 9 Lightweight Resolver"> 26<link rel="next" href="Bv9ARM.ch07.html" title="Chapter 7. BIND 9 Security Considerations"> 27</head> 28<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 29<div class="navheader"> 30<table width="100%" summary="Navigation header"> 31<tr><th colspan="3" align="center">Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</th></tr> 32<tr> 33<td width="20%" align="left"> 34<a accesskey="p" href="Bv9ARM.ch05.html">Prev</a> </td> 35<th width="60%" align="center"> </th> 36<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch07.html">Next</a> 37</td> 38</tr> 39</table> 40<hr> 41</div> 42<div class="chapter" lang="en"> 43<div class="titlepage"><div><div><h2 class="title"> 44<a name="Bv9ARM.ch06"></a>Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</h2></div></div></div> 45<div class="toc"> 46<p><b>Table of Contents</b></p> 47<dl> 48<dt><span class="sect1"><a href="Bv9ARM.ch06.html#configuration_file_elements">Configuration File Elements</a></span></dt> 49<dd><dl> 50<dt><span class="sect2"><a href="Bv9ARM.ch06.html#address_match_lists">Address Match Lists</a></span></dt> 51<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574332">Comment Syntax</a></span></dt> 52</dl></dd> 53<dt><span class="sect1"><a href="Bv9ARM.ch06.html#Configuration_File_Grammar">Configuration File Grammar</a></span></dt> 54<dd><dl> 55<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574986"><span><strong class="command">acl</strong></span> Statement Grammar</a></span></dt> 56<dt><span class="sect2"><a href="Bv9ARM.ch06.html#acl"><span><strong class="command">acl</strong></span> Statement Definition and 57 Usage</a></span></dt> 58<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575176"><span><strong class="command">controls</strong></span> Statement Grammar</a></span></dt> 59<dt><span class="sect2"><a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage"><span><strong class="command">controls</strong></span> Statement Definition and 60 Usage</a></span></dt> 61<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575467"><span><strong class="command">include</strong></span> Statement Grammar</a></span></dt> 62<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575484"><span><strong class="command">include</strong></span> Statement Definition and 63 Usage</a></span></dt> 64<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575576"><span><strong class="command">key</strong></span> Statement Grammar</a></span></dt> 65<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575600"><span><strong class="command">key</strong></span> Statement Definition and Usage</a></span></dt> 66<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575758"><span><strong class="command">logging</strong></span> Statement Grammar</a></span></dt> 67<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575884"><span><strong class="command">logging</strong></span> Statement Definition and 68 Usage</a></span></dt> 69<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2577910"><span><strong class="command">lwres</strong></span> Statement Grammar</a></span></dt> 70<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2577984"><span><strong class="command">lwres</strong></span> Statement Definition and Usage</a></span></dt> 71<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2578116"><span><strong class="command">masters</strong></span> Statement Grammar</a></span></dt> 72<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2578160"><span><strong class="command">masters</strong></span> Statement Definition and 73 Usage</a></span></dt> 74<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2578174"><span><strong class="command">options</strong></span> Statement Grammar</a></span></dt> 75<dt><span class="sect2"><a href="Bv9ARM.ch06.html#options"><span><strong class="command">options</strong></span> Statement Definition and 76 Usage</a></span></dt> 77<dt><span class="sect2"><a href="Bv9ARM.ch06.html#server_statement_grammar"><span><strong class="command">server</strong></span> Statement Grammar</a></span></dt> 78<dt><span class="sect2"><a href="Bv9ARM.ch06.html#server_statement_definition_and_usage"><span><strong class="command">server</strong></span> Statement Definition and 79 Usage</a></span></dt> 80<dt><span class="sect2"><a href="Bv9ARM.ch06.html#statschannels"><span><strong class="command">statistics-channels</strong></span> Statement Grammar</a></span></dt> 81<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2589481"><span><strong class="command">statistics-channels</strong></span> Statement Definition and 82 Usage</a></span></dt> 83<dt><span class="sect2"><a href="Bv9ARM.ch06.html#trusted-keys"><span><strong class="command">trusted-keys</strong></span> Statement Grammar</a></span></dt> 84<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2589689"><span><strong class="command">trusted-keys</strong></span> Statement Definition 85 and Usage</a></span></dt> 86<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2589736"><span><strong class="command">managed-keys</strong></span> Statement Grammar</a></span></dt> 87<dt><span class="sect2"><a href="Bv9ARM.ch06.html#managed-keys"><span><strong class="command">managed-keys</strong></span> Statement Definition 88 and Usage</a></span></dt> 89<dt><span class="sect2"><a href="Bv9ARM.ch06.html#view_statement_grammar"><span><strong class="command">view</strong></span> Statement Grammar</a></span></dt> 90<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2590162"><span><strong class="command">view</strong></span> Statement Definition and Usage</a></span></dt> 91<dt><span class="sect2"><a href="Bv9ARM.ch06.html#zone_statement_grammar"><span><strong class="command">zone</strong></span> 92 Statement Grammar</a></span></dt> 93<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2591713"><span><strong class="command">zone</strong></span> Statement Definition and Usage</a></span></dt> 94</dl></dd> 95<dt><span class="sect1"><a href="Bv9ARM.ch06.html#id2595116">Zone File</a></span></dt> 96<dd><dl> 97<dt><span class="sect2"><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> 98<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2597415">Discussion of MX Records</a></span></dt> 99<dt><span class="sect2"><a href="Bv9ARM.ch06.html#Setting_TTLs">Setting TTLs</a></span></dt> 100<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2597962">Inverse Mapping in IPv4</a></span></dt> 101<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2598157">Other Zone File Directives</a></span></dt> 102<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2598430"><acronym class="acronym">BIND</acronym> Master File Extension: the <span><strong class="command">$GENERATE</strong></span> Directive</a></span></dt> 103<dt><span class="sect2"><a href="Bv9ARM.ch06.html#zonefile_format">Additional File Formats</a></span></dt> 104</dl></dd> 105<dt><span class="sect1"><a href="Bv9ARM.ch06.html#statistics">BIND9 Statistics</a></span></dt> 106<dd><dl><dt><span class="sect2"><a href="Bv9ARM.ch06.html#statistics_counters">Statistics Counters</a></span></dt></dl></dd> 107</dl> 108</div> 109<p> 110 <acronym class="acronym">BIND</acronym> 9 configuration is broadly similar 111 to <acronym class="acronym">BIND</acronym> 8; however, there are a few new 112 areas 113 of configuration, such as views. <acronym class="acronym">BIND</acronym> 114 8 configuration files should work with few alterations in <acronym class="acronym">BIND</acronym> 115 9, although more complex configurations should be reviewed to check 116 if they can be more efficiently implemented using the new features 117 found in <acronym class="acronym">BIND</acronym> 9. 118 </p> 119<p> 120 <acronym class="acronym">BIND</acronym> 4 configuration files can be 121 converted to the new format 122 using the shell script 123 <code class="filename">contrib/named-bootconf/named-bootconf.sh</code>. 124 </p> 125<div class="sect1" lang="en"> 126<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 127<a name="configuration_file_elements"></a>Configuration File Elements</h2></div></div></div> 128<p> 129 Following is a list of elements used throughout the <acronym class="acronym">BIND</acronym> configuration 130 file documentation: 131 </p> 132<div class="informaltable"><table border="1"> 133<colgroup> 134<col> 135<col> 136</colgroup> 137<tbody> 138<tr> 139<td> 140 <p> 141 <code class="varname">acl_name</code> 142 </p> 143 </td> 144<td> 145 <p> 146 The name of an <code class="varname">address_match_list</code> as 147 defined by the <span><strong class="command">acl</strong></span> statement. 148 </p> 149 </td> 150</tr> 151<tr> 152<td> 153 <p> 154 <code class="varname">address_match_list</code> 155 </p> 156 </td> 157<td> 158 <p> 159 A list of one or more 160 <code class="varname">ip_addr</code>, 161 <code class="varname">ip_prefix</code>, <code class="varname">key_id</code>, 162 or <code class="varname">acl_name</code> elements, see 163 <a href="Bv9ARM.ch06.html#address_match_lists" title="Address Match Lists">the section called “Address Match Lists”</a>. 164 </p> 165 </td> 166</tr> 167<tr> 168<td> 169 <p> 170 <code class="varname">masters_list</code> 171 </p> 172 </td> 173<td> 174 <p> 175 A named list of one or more <code class="varname">ip_addr</code> 176 with optional <code class="varname">key_id</code> and/or 177 <code class="varname">ip_port</code>. 178 A <code class="varname">masters_list</code> may include other 179 <code class="varname">masters_lists</code>. 180 </p> 181 </td> 182</tr> 183<tr> 184<td> 185 <p> 186 <code class="varname">domain_name</code> 187 </p> 188 </td> 189<td> 190 <p> 191 A quoted string which will be used as 192 a DNS name, for example "<code class="literal">my.test.domain</code>". 193 </p> 194 </td> 195</tr> 196<tr> 197<td> 198 <p> 199 <code class="varname">namelist</code> 200 </p> 201 </td> 202<td> 203 <p> 204 A list of one or more <code class="varname">domain_name</code> 205 elements. 206 </p> 207 </td> 208</tr> 209<tr> 210<td> 211 <p> 212 <code class="varname">dotted_decimal</code> 213 </p> 214 </td> 215<td> 216 <p> 217 One to four integers valued 0 through 218 255 separated by dots (`.'), such as <span><strong class="command">123</strong></span>, 219 <span><strong class="command">45.67</strong></span> or <span><strong class="command">89.123.45.67</strong></span>. 220 </p> 221 </td> 222</tr> 223<tr> 224<td> 225 <p> 226 <code class="varname">ip4_addr</code> 227 </p> 228 </td> 229<td> 230 <p> 231 An IPv4 address with exactly four elements 232 in <code class="varname">dotted_decimal</code> notation. 233 </p> 234 </td> 235</tr> 236<tr> 237<td> 238 <p> 239 <code class="varname">ip6_addr</code> 240 </p> 241 </td> 242<td> 243 <p> 244 An IPv6 address, such as <span><strong class="command">2001:db8::1234</strong></span>. 245 IPv6 scoped addresses that have ambiguity on their 246 scope zones must be disambiguated by an appropriate 247 zone ID with the percent character (`%') as 248 delimiter. It is strongly recommended to use 249 string zone names rather than numeric identifiers, 250 in order to be robust against system configuration 251 changes. However, since there is no standard 252 mapping for such names and identifier values, 253 currently only interface names as link identifiers 254 are supported, assuming one-to-one mapping between 255 interfaces and links. For example, a link-local 256 address <span><strong class="command">fe80::1</strong></span> on the link 257 attached to the interface <span><strong class="command">ne0</strong></span> 258 can be specified as <span><strong class="command">fe80::1%ne0</strong></span>. 259 Note that on most systems link-local addresses 260 always have the ambiguity, and need to be 261 disambiguated. 262 </p> 263 </td> 264</tr> 265<tr> 266<td> 267 <p> 268 <code class="varname">ip_addr</code> 269 </p> 270 </td> 271<td> 272 <p> 273 An <code class="varname">ip4_addr</code> or <code class="varname">ip6_addr</code>. 274 </p> 275 </td> 276</tr> 277<tr> 278<td> 279 <p> 280 <code class="varname">ip_port</code> 281 </p> 282 </td> 283<td> 284 <p> 285 An IP port <code class="varname">number</code>. 286 The <code class="varname">number</code> is limited to 0 287 through 65535, with values 288 below 1024 typically restricted to use by processes running 289 as root. 290 In some cases, an asterisk (`*') character can be used as a 291 placeholder to 292 select a random high-numbered port. 293 </p> 294 </td> 295</tr> 296<tr> 297<td> 298 <p> 299 <code class="varname">ip_prefix</code> 300 </p> 301 </td> 302<td> 303 <p> 304 An IP network specified as an <code class="varname">ip_addr</code>, 305 followed by a slash (`/') and then the number of bits in the 306 netmask. 307 Trailing zeros in a <code class="varname">ip_addr</code> 308 may omitted. 309 For example, <span><strong class="command">127/8</strong></span> is the 310 network <span><strong class="command">127.0.0.0</strong></span> with 311 netmask <span><strong class="command">255.0.0.0</strong></span> and <span><strong class="command">1.2.3.0/28</strong></span> is 312 network <span><strong class="command">1.2.3.0</strong></span> with netmask <span><strong class="command">255.255.255.240</strong></span>. 313 </p> 314 <p> 315 When specifying a prefix involving a IPv6 scoped address 316 the scope may be omitted. In that case the prefix will 317 match packets from any scope. 318 </p> 319 </td> 320</tr> 321<tr> 322<td> 323 <p> 324 <code class="varname">key_id</code> 325 </p> 326 </td> 327<td> 328 <p> 329 A <code class="varname">domain_name</code> representing 330 the name of a shared key, to be used for transaction 331 security. 332 </p> 333 </td> 334</tr> 335<tr> 336<td> 337 <p> 338 <code class="varname">key_list</code> 339 </p> 340 </td> 341<td> 342 <p> 343 A list of one or more 344 <code class="varname">key_id</code>s, 345 separated by semicolons and ending with a semicolon. 346 </p> 347 </td> 348</tr> 349<tr> 350<td> 351 <p> 352 <code class="varname">number</code> 353 </p> 354 </td> 355<td> 356 <p> 357 A non-negative 32-bit integer 358 (i.e., a number between 0 and 4294967295, inclusive). 359 Its acceptable value might further 360 be limited by the context in which it is used. 361 </p> 362 </td> 363</tr> 364<tr> 365<td> 366 <p> 367 <code class="varname">path_name</code> 368 </p> 369 </td> 370<td> 371 <p> 372 A quoted string which will be used as 373 a pathname, such as <code class="filename">zones/master/my.test.domain</code>. 374 </p> 375 </td> 376</tr> 377<tr> 378<td> 379 <p> 380 <code class="varname">port_list</code> 381 </p> 382 </td> 383<td> 384 <p> 385 A list of an <code class="varname">ip_port</code> or a port 386 range. 387 A port range is specified in the form of 388 <strong class="userinput"><code>range</code></strong> followed by 389 two <code class="varname">ip_port</code>s, 390 <code class="varname">port_low</code> and 391 <code class="varname">port_high</code>, which represents 392 port numbers from <code class="varname">port_low</code> through 393 <code class="varname">port_high</code>, inclusive. 394 <code class="varname">port_low</code> must not be larger than 395 <code class="varname">port_high</code>. 396 For example, 397 <strong class="userinput"><code>range 1024 65535</code></strong> represents 398 ports from 1024 through 65535. 399 In either case an asterisk (`*') character is not 400 allowed as a valid <code class="varname">ip_port</code>. 401 </p> 402 </td> 403</tr> 404<tr> 405<td> 406 <p> 407 <code class="varname">size_spec</code> 408 </p> 409 </td> 410<td> 411 <p> 412 A number, the word <strong class="userinput"><code>unlimited</code></strong>, 413 or the word <strong class="userinput"><code>default</code></strong>. 414 </p> 415 <p> 416 An <code class="varname">unlimited</code> <code class="varname">size_spec</code> requests unlimited 417 use, or the maximum available amount. A <code class="varname">default size_spec</code> uses 418 the limit that was in force when the server was started. 419 </p> 420 <p> 421 A <code class="varname">number</code> can optionally be 422 followed by a scaling factor: 423 <strong class="userinput"><code>K</code></strong> or <strong class="userinput"><code>k</code></strong> 424 for kilobytes, 425 <strong class="userinput"><code>M</code></strong> or <strong class="userinput"><code>m</code></strong> 426 for megabytes, and 427 <strong class="userinput"><code>G</code></strong> or <strong class="userinput"><code>g</code></strong> for gigabytes, 428 which scale by 1024, 1024*1024, and 1024*1024*1024 429 respectively. 430 </p> 431 <p> 432 The value must be representable as a 64-bit unsigned integer 433 (0 to 18446744073709551615, inclusive). 434 Using <code class="varname">unlimited</code> is the best 435 way 436 to safely set a really large number. 437 </p> 438 </td> 439</tr> 440<tr> 441<td> 442 <p> 443 <code class="varname">yes_or_no</code> 444 </p> 445 </td> 446<td> 447 <p> 448 Either <strong class="userinput"><code>yes</code></strong> or <strong class="userinput"><code>no</code></strong>. 449 The words <strong class="userinput"><code>true</code></strong> and <strong class="userinput"><code>false</code></strong> are 450 also accepted, as are the numbers <strong class="userinput"><code>1</code></strong> 451 and <strong class="userinput"><code>0</code></strong>. 452 </p> 453 </td> 454</tr> 455<tr> 456<td> 457 <p> 458 <code class="varname">dialup_option</code> 459 </p> 460 </td> 461<td> 462 <p> 463 One of <strong class="userinput"><code>yes</code></strong>, 464 <strong class="userinput"><code>no</code></strong>, <strong class="userinput"><code>notify</code></strong>, 465 <strong class="userinput"><code>notify-passive</code></strong>, <strong class="userinput"><code>refresh</code></strong> or 466 <strong class="userinput"><code>passive</code></strong>. 467 When used in a zone, <strong class="userinput"><code>notify-passive</code></strong>, 468 <strong class="userinput"><code>refresh</code></strong>, and <strong class="userinput"><code>passive</code></strong> 469 are restricted to slave and stub zones. 470 </p> 471 </td> 472</tr> 473</tbody> 474</table></div> 475<div class="sect2" lang="en"> 476<div class="titlepage"><div><div><h3 class="title"> 477<a name="address_match_lists"></a>Address Match Lists</h3></div></div></div> 478<div class="sect3" lang="en"> 479<div class="titlepage"><div><div><h4 class="title"> 480<a name="id2574099"></a>Syntax</h4></div></div></div> 481<pre class="programlisting"><code class="varname">address_match_list</code> = address_match_list_element ; 482 [<span class="optional"> address_match_list_element; ... </span>] 483<code class="varname">address_match_list_element</code> = [<span class="optional"> ! </span>] (ip_address [<span class="optional">/length</span>] | 484 key key_id | acl_name | { address_match_list } ) 485</pre> 486</div> 487<div class="sect3" lang="en"> 488<div class="titlepage"><div><div><h4 class="title"> 489<a name="id2574126"></a>Definition and Usage</h4></div></div></div> 490<p> 491 Address match lists are primarily used to determine access 492 control for various server operations. They are also used in 493 the <span><strong class="command">listen-on</strong></span> and <span><strong class="command">sortlist</strong></span> 494 statements. The elements which constitute an address match 495 list can be any of the following: 496 </p> 497<div class="itemizedlist"><ul type="disc"> 498<li>an IP address (IPv4 or IPv6)</li> 499<li>an IP prefix (in `/' notation)</li> 500<li> 501 a key ID, as defined by the <span><strong class="command">key</strong></span> 502 statement 503 </li> 504<li>the name of an address match list defined with 505 the <span><strong class="command">acl</strong></span> statement 506 </li> 507<li>a nested address match list enclosed in braces</li> 508</ul></div> 509<p> 510 Elements can be negated with a leading exclamation mark (`!'), 511 and the match list names "any", "none", "localhost", and 512 "localnets" are predefined. More information on those names 513 can be found in the description of the acl statement. 514 </p> 515<p> 516 The addition of the key clause made the name of this syntactic 517 element something of a misnomer, since security keys can be used 518 to validate access without regard to a host or network address. 519 Nonetheless, the term "address match list" is still used 520 throughout the documentation. 521 </p> 522<p> 523 When a given IP address or prefix is compared to an address 524 match list, the comparison takes place in approximately O(1) 525 time. However, key comparisons require that the list of keys 526 be traversed until a matching key is found, and therefore may 527 be somewhat slower. 528 </p> 529<p> 530 The interpretation of a match depends on whether the list is being 531 used for access control, defining <span><strong class="command">listen-on</strong></span> ports, or in a 532 <span><strong class="command">sortlist</strong></span>, and whether the element was negated. 533 </p> 534<p> 535 When used as an access control list, a non-negated match 536 allows access and a negated match denies access. If 537 there is no match, access is denied. The clauses 538 <span><strong class="command">allow-notify</strong></span>, 539 <span><strong class="command">allow-recursion</strong></span>, 540 <span><strong class="command">allow-recursion-on</strong></span>, 541 <span><strong class="command">allow-query</strong></span>, 542 <span><strong class="command">allow-query-on</strong></span>, 543 <span><strong class="command">allow-query-cache</strong></span>, 544 <span><strong class="command">allow-query-cache-on</strong></span>, 545 <span><strong class="command">allow-transfer</strong></span>, 546 <span><strong class="command">allow-update</strong></span>, 547 <span><strong class="command">allow-update-forwarding</strong></span>, and 548 <span><strong class="command">blackhole</strong></span> all use address match 549 lists. Similarly, the <span><strong class="command">listen-on</strong></span> option will cause the 550 server to refuse queries on any of the machine's 551 addresses which do not match the list. 552 </p> 553<p> 554 Order of insertion is significant. If more than one element 555 in an ACL is found to match a given IP address or prefix, 556 preference will be given to the one that came 557 <span class="emphasis"><em>first</em></span> in the ACL definition. 558 Because of this first-match behavior, an element that 559 defines a subset of another element in the list should 560 come before the broader element, regardless of whether 561 either is negated. For example, in 562 <span><strong class="command">1.2.3/24; ! 1.2.3.13;</strong></span> 563 the 1.2.3.13 element is completely useless because the 564 algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24 565 element. Using <span><strong class="command">! 1.2.3.13; 1.2.3/24</strong></span> fixes 566 that problem by having 1.2.3.13 blocked by the negation, but 567 all other 1.2.3.* hosts fall through. 568 </p> 569</div> 570</div> 571<div class="sect2" lang="en"> 572<div class="titlepage"><div><div><h3 class="title"> 573<a name="id2574332"></a>Comment Syntax</h3></div></div></div> 574<p> 575 The <acronym class="acronym">BIND</acronym> 9 comment syntax allows for 576 comments to appear 577 anywhere that whitespace may appear in a <acronym class="acronym">BIND</acronym> configuration 578 file. To appeal to programmers of all kinds, they can be written 579 in the C, C++, or shell/perl style. 580 </p> 581<div class="sect3" lang="en"> 582<div class="titlepage"><div><div><h4 class="title"> 583<a name="id2574347"></a>Syntax</h4></div></div></div> 584<p> 585 </p> 586<pre class="programlisting">/* This is a <acronym class="acronym">BIND</acronym> comment as in C */</pre> 587<p> 588 </p> 589<pre class="programlisting">// This is a <acronym class="acronym">BIND</acronym> comment as in C++</pre> 590<p> 591 </p> 592<pre class="programlisting"># This is a <acronym class="acronym">BIND</acronym> comment as in common UNIX shells 593# and perl</pre> 594<p> 595 </p> 596</div> 597<div class="sect3" lang="en"> 598<div class="titlepage"><div><div><h4 class="title"> 599<a name="id2574377"></a>Definition and Usage</h4></div></div></div> 600<p> 601 Comments may appear anywhere that whitespace may appear in 602 a <acronym class="acronym">BIND</acronym> configuration file. 603 </p> 604<p> 605 C-style comments start with the two characters /* (slash, 606 star) and end with */ (star, slash). Because they are completely 607 delimited with these characters, they can be used to comment only 608 a portion of a line or to span multiple lines. 609 </p> 610<p> 611 C-style comments cannot be nested. For example, the following 612 is not valid because the entire comment ends with the first */: 613 </p> 614<p> 615 616</p> 617<pre class="programlisting">/* This is the start of a comment. 618 This is still part of the comment. 619/* This is an incorrect attempt at nesting a comment. */ 620 This is no longer in any comment. */ 621</pre> 622<p> 623 624 </p> 625<p> 626 C++-style comments start with the two characters // (slash, 627 slash) and continue to the end of the physical line. They cannot 628 be continued across multiple physical lines; to have one logical 629 comment span multiple lines, each line must use the // pair. 630 For example: 631 </p> 632<p> 633 634</p> 635<pre class="programlisting">// This is the start of a comment. The next line 636// is a new comment, even though it is logically 637// part of the previous comment. 638</pre> 639<p> 640 641 </p> 642<p> 643 Shell-style (or perl-style, if you prefer) comments start 644 with the character <code class="literal">#</code> (number sign) 645 and continue to the end of the 646 physical line, as in C++ comments. 647 For example: 648 </p> 649<p> 650 651</p> 652<pre class="programlisting"># This is the start of a comment. The next line 653# is a new comment, even though it is logically 654# part of the previous comment. 655</pre> 656<p> 657 658 </p> 659<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> 660<h3 class="title">Warning</h3> 661<p> 662 You cannot use the semicolon (`;') character 663 to start a comment such as you would in a zone file. The 664 semicolon indicates the end of a configuration 665 statement. 666 </p> 667</div> 668</div> 669</div> 670</div> 671<div class="sect1" lang="en"> 672<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 673<a name="Configuration_File_Grammar"></a>Configuration File Grammar</h2></div></div></div> 674<p> 675 A <acronym class="acronym">BIND</acronym> 9 configuration consists of 676 statements and comments. 677 Statements end with a semicolon. Statements and comments are the 678 only elements that can appear without enclosing braces. Many 679 statements contain a block of sub-statements, which are also 680 terminated with a semicolon. 681 </p> 682<p> 683 The following statements are supported: 684 </p> 685<div class="informaltable"><table border="1"> 686<colgroup> 687<col> 688<col> 689</colgroup> 690<tbody> 691<tr> 692<td> 693 <p><span><strong class="command">acl</strong></span></p> 694 </td> 695<td> 696 <p> 697 defines a named IP address 698 matching list, for access control and other uses. 699 </p> 700 </td> 701</tr> 702<tr> 703<td> 704 <p><span><strong class="command">controls</strong></span></p> 705 </td> 706<td> 707 <p> 708 declares control channels to be used 709 by the <span><strong class="command">rndc</strong></span> utility. 710 </p> 711 </td> 712</tr> 713<tr> 714<td> 715 <p><span><strong class="command">include</strong></span></p> 716 </td> 717<td> 718 <p> 719 includes a file. 720 </p> 721 </td> 722</tr> 723<tr> 724<td> 725 <p><span><strong class="command">key</strong></span></p> 726 </td> 727<td> 728 <p> 729 specifies key information for use in 730 authentication and authorization using TSIG. 731 </p> 732 </td> 733</tr> 734<tr> 735<td> 736 <p><span><strong class="command">logging</strong></span></p> 737 </td> 738<td> 739 <p> 740 specifies what the server logs, and where 741 the log messages are sent. 742 </p> 743 </td> 744</tr> 745<tr> 746<td> 747 <p><span><strong class="command">lwres</strong></span></p> 748 </td> 749<td> 750 <p> 751 configures <span><strong class="command">named</strong></span> to 752 also act as a light-weight resolver daemon (<span><strong class="command">lwresd</strong></span>). 753 </p> 754 </td> 755</tr> 756<tr> 757<td> 758 <p><span><strong class="command">masters</strong></span></p> 759 </td> 760<td> 761 <p> 762 defines a named masters list for 763 inclusion in stub and slave zone masters clauses. 764 </p> 765 </td> 766</tr> 767<tr> 768<td> 769 <p><span><strong class="command">options</strong></span></p> 770 </td> 771<td> 772 <p> 773 controls global server configuration 774 options and sets defaults for other statements. 775 </p> 776 </td> 777</tr> 778<tr> 779<td> 780 <p><span><strong class="command">server</strong></span></p> 781 </td> 782<td> 783 <p> 784 sets certain configuration options on 785 a per-server basis. 786 </p> 787 </td> 788</tr> 789<tr> 790<td> 791 <p><span><strong class="command">statistics-channels</strong></span></p> 792 </td> 793<td> 794 <p> 795 declares communication channels to get access to 796 <span><strong class="command">named</strong></span> statistics. 797 </p> 798 </td> 799</tr> 800<tr> 801<td> 802 <p><span><strong class="command">trusted-keys</strong></span></p> 803 </td> 804<td> 805 <p> 806 defines trusted DNSSEC keys. 807 </p> 808 </td> 809</tr> 810<tr> 811<td> 812 <p><span><strong class="command">managed-keys</strong></span></p> 813 </td> 814<td> 815 <p> 816 lists DNSSEC keys to be kept up to date 817 using RFC 5011 trust anchor maintenance. 818 </p> 819 </td> 820</tr> 821<tr> 822<td> 823 <p><span><strong class="command">view</strong></span></p> 824 </td> 825<td> 826 <p> 827 defines a view. 828 </p> 829 </td> 830</tr> 831<tr> 832<td> 833 <p><span><strong class="command">zone</strong></span></p> 834 </td> 835<td> 836 <p> 837 defines a zone. 838 </p> 839 </td> 840</tr> 841</tbody> 842</table></div> 843<p> 844 The <span><strong class="command">logging</strong></span> and 845 <span><strong class="command">options</strong></span> statements may only occur once 846 per 847 configuration. 848 </p> 849<div class="sect2" lang="en"> 850<div class="titlepage"><div><div><h3 class="title"> 851<a name="id2574986"></a><span><strong class="command">acl</strong></span> Statement Grammar</h3></div></div></div> 852<pre class="programlisting"><span><strong class="command">acl</strong></span> acl-name { 853 address_match_list 854}; 855</pre> 856</div> 857<div class="sect2" lang="en"> 858<div class="titlepage"><div><div><h3 class="title"> 859<a name="acl"></a><span><strong class="command">acl</strong></span> Statement Definition and 860 Usage</h3></div></div></div> 861<p> 862 The <span><strong class="command">acl</strong></span> statement assigns a symbolic 863 name to an address match list. It gets its name from a primary 864 use of address match lists: Access Control Lists (ACLs). 865 </p> 866<p> 867 Note that an address match list's name must be defined 868 with <span><strong class="command">acl</strong></span> before it can be used 869 elsewhere; no forward references are allowed. 870 </p> 871<p> 872 The following ACLs are built-in: 873 </p> 874<div class="informaltable"><table border="1"> 875<colgroup> 876<col> 877<col> 878</colgroup> 879<tbody> 880<tr> 881<td> 882 <p><span><strong class="command">any</strong></span></p> 883 </td> 884<td> 885 <p> 886 Matches all hosts. 887 </p> 888 </td> 889</tr> 890<tr> 891<td> 892 <p><span><strong class="command">none</strong></span></p> 893 </td> 894<td> 895 <p> 896 Matches no hosts. 897 </p> 898 </td> 899</tr> 900<tr> 901<td> 902 <p><span><strong class="command">localhost</strong></span></p> 903 </td> 904<td> 905 <p> 906 Matches the IPv4 and IPv6 addresses of all network 907 interfaces on the system. 908 </p> 909 </td> 910</tr> 911<tr> 912<td> 913 <p><span><strong class="command">localnets</strong></span></p> 914 </td> 915<td> 916 <p> 917 Matches any host on an IPv4 or IPv6 network 918 for which the system has an interface. 919 Some systems do not provide a way to determine the prefix 920 lengths of 921 local IPv6 addresses. 922 In such a case, <span><strong class="command">localnets</strong></span> 923 only matches the local 924 IPv6 addresses, just like <span><strong class="command">localhost</strong></span>. 925 </p> 926 </td> 927</tr> 928</tbody> 929</table></div> 930</div> 931<div class="sect2" lang="en"> 932<div class="titlepage"><div><div><h3 class="title"> 933<a name="id2575176"></a><span><strong class="command">controls</strong></span> Statement Grammar</h3></div></div></div> 934<pre class="programlisting"><span><strong class="command">controls</strong></span> { 935 [ inet ( ip_addr | * ) [ port ip_port ] 936 allow { <em class="replaceable"><code> address_match_list </code></em> } 937 keys { <em class="replaceable"><code>key_list</code></em> }; ] 938 [ inet ...; ] 939 [ unix <em class="replaceable"><code>path</code></em> perm <em class="replaceable"><code>number</code></em> owner <em class="replaceable"><code>number</code></em> group <em class="replaceable"><code>number</code></em> 940 keys { <em class="replaceable"><code>key_list</code></em> }; ] 941 [ unix ...; ] 942}; 943</pre> 944</div> 945<div class="sect2" lang="en"> 946<div class="titlepage"><div><div><h3 class="title"> 947<a name="controls_statement_definition_and_usage"></a><span><strong class="command">controls</strong></span> Statement Definition and 948 Usage</h3></div></div></div> 949<p> 950 The <span><strong class="command">controls</strong></span> statement declares control 951 channels to be used by system administrators to control the 952 operation of the name server. These control channels are 953 used by the <span><strong class="command">rndc</strong></span> utility to send 954 commands to and retrieve non-DNS results from a name server. 955 </p> 956<p> 957 An <span><strong class="command">inet</strong></span> control channel is a TCP socket 958 listening at the specified <span><strong class="command">ip_port</strong></span> on the 959 specified <span><strong class="command">ip_addr</strong></span>, which can be an IPv4 or IPv6 960 address. An <span><strong class="command">ip_addr</strong></span> of <code class="literal">*</code> (asterisk) is 961 interpreted as the IPv4 wildcard address; connections will be 962 accepted on any of the system's IPv4 addresses. 963 To listen on the IPv6 wildcard address, 964 use an <span><strong class="command">ip_addr</strong></span> of <code class="literal">::</code>. 965 If you will only use <span><strong class="command">rndc</strong></span> on the local host, 966 using the loopback address (<code class="literal">127.0.0.1</code> 967 or <code class="literal">::1</code>) is recommended for maximum security. 968 </p> 969<p> 970 If no port is specified, port 953 is used. The asterisk 971 "<code class="literal">*</code>" cannot be used for <span><strong class="command">ip_port</strong></span>. 972 </p> 973<p> 974 The ability to issue commands over the control channel is 975 restricted by the <span><strong class="command">allow</strong></span> and 976 <span><strong class="command">keys</strong></span> clauses. 977 Connections to the control channel are permitted based on the 978 <span><strong class="command">address_match_list</strong></span>. This is for simple 979 IP address based filtering only; any <span><strong class="command">key_id</strong></span> 980 elements of the <span><strong class="command">address_match_list</strong></span> 981 are ignored. 982 </p> 983<p> 984 A <span><strong class="command">unix</strong></span> control channel is a UNIX domain 985 socket listening at the specified path in the file system. 986 Access to the socket is specified by the <span><strong class="command">perm</strong></span>, 987 <span><strong class="command">owner</strong></span> and <span><strong class="command">group</strong></span> clauses. 988 Note on some platforms (SunOS and Solaris) the permissions 989 (<span><strong class="command">perm</strong></span>) are applied to the parent directory 990 as the permissions on the socket itself are ignored. 991 </p> 992<p> 993 The primary authorization mechanism of the command 994 channel is the <span><strong class="command">key_list</strong></span>, which 995 contains a list of <span><strong class="command">key_id</strong></span>s. 996 Each <span><strong class="command">key_id</strong></span> in the <span><strong class="command">key_list</strong></span> 997 is authorized to execute commands over the control channel. 998 See <a href="Bv9ARM.ch03.html#rndc">Remote Name Daemon Control application</a> in <a href="Bv9ARM.ch03.html#admin_tools" title="Administrative Tools">the section called “Administrative Tools”</a>) 999 for information about configuring keys in <span><strong class="command">rndc</strong></span>. 1000 </p> 1001<p> 1002 If no <span><strong class="command">controls</strong></span> statement is present, 1003 <span><strong class="command">named</strong></span> will set up a default 1004 control channel listening on the loopback address 127.0.0.1 1005 and its IPv6 counterpart ::1. 1006 In this case, and also when the <span><strong class="command">controls</strong></span> statement 1007 is present but does not have a <span><strong class="command">keys</strong></span> clause, 1008 <span><strong class="command">named</strong></span> will attempt to load the command channel key 1009 from the file <code class="filename">rndc.key</code> in 1010 <code class="filename">/etc</code> (or whatever <code class="varname">sysconfdir</code> 1011 was specified as when <acronym class="acronym">BIND</acronym> was built). 1012 To create a <code class="filename">rndc.key</code> file, run 1013 <strong class="userinput"><code>rndc-confgen -a</code></strong>. 1014 </p> 1015<p> 1016 The <code class="filename">rndc.key</code> feature was created to 1017 ease the transition of systems from <acronym class="acronym">BIND</acronym> 8, 1018 which did not have digital signatures on its command channel 1019 messages and thus did not have a <span><strong class="command">keys</strong></span> clause. 1020 1021 It makes it possible to use an existing <acronym class="acronym">BIND</acronym> 8 1022 configuration file in <acronym class="acronym">BIND</acronym> 9 unchanged, 1023 and still have <span><strong class="command">rndc</strong></span> work the same way 1024 <span><strong class="command">ndc</strong></span> worked in BIND 8, simply by executing the 1025 command <strong class="userinput"><code>rndc-confgen -a</code></strong> after BIND 9 is 1026 installed. 1027 </p> 1028<p> 1029 Since the <code class="filename">rndc.key</code> feature 1030 is only intended to allow the backward-compatible usage of 1031 <acronym class="acronym">BIND</acronym> 8 configuration files, this 1032 feature does not 1033 have a high degree of configurability. You cannot easily change 1034 the key name or the size of the secret, so you should make a 1035 <code class="filename">rndc.conf</code> with your own key if you 1036 wish to change 1037 those things. The <code class="filename">rndc.key</code> file 1038 also has its 1039 permissions set such that only the owner of the file (the user that 1040 <span><strong class="command">named</strong></span> is running as) can access it. 1041 If you 1042 desire greater flexibility in allowing other users to access 1043 <span><strong class="command">rndc</strong></span> commands, then you need to create 1044 a 1045 <code class="filename">rndc.conf</code> file and make it group 1046 readable by a group 1047 that contains the users who should have access. 1048 </p> 1049<p> 1050 To disable the command channel, use an empty 1051 <span><strong class="command">controls</strong></span> statement: 1052 <span><strong class="command">controls { };</strong></span>. 1053 </p> 1054</div> 1055<div class="sect2" lang="en"> 1056<div class="titlepage"><div><div><h3 class="title"> 1057<a name="id2575467"></a><span><strong class="command">include</strong></span> Statement Grammar</h3></div></div></div> 1058<pre class="programlisting"><span><strong class="command">include</strong></span> <em class="replaceable"><code>filename</code></em>;</pre> 1059</div> 1060<div class="sect2" lang="en"> 1061<div class="titlepage"><div><div><h3 class="title"> 1062<a name="id2575484"></a><span><strong class="command">include</strong></span> Statement Definition and 1063 Usage</h3></div></div></div> 1064<p> 1065 The <span><strong class="command">include</strong></span> statement inserts the 1066 specified file at the point where the <span><strong class="command">include</strong></span> 1067 statement is encountered. The <span><strong class="command">include</strong></span> 1068 statement facilitates the administration of configuration 1069 files 1070 by permitting the reading or writing of some things but not 1071 others. For example, the statement could include private keys 1072 that are readable only by the name server. 1073 </p> 1074</div> 1075<div class="sect2" lang="en"> 1076<div class="titlepage"><div><div><h3 class="title"> 1077<a name="id2575576"></a><span><strong class="command">key</strong></span> Statement Grammar</h3></div></div></div> 1078<pre class="programlisting"><span><strong class="command">key</strong></span> <em class="replaceable"><code>key_id</code></em> { 1079 algorithm <em class="replaceable"><code>string</code></em>; 1080 secret <em class="replaceable"><code>string</code></em>; 1081}; 1082</pre> 1083</div> 1084<div class="sect2" lang="en"> 1085<div class="titlepage"><div><div><h3 class="title"> 1086<a name="id2575600"></a><span><strong class="command">key</strong></span> Statement Definition and Usage</h3></div></div></div> 1087<p> 1088 The <span><strong class="command">key</strong></span> statement defines a shared 1089 secret key for use with TSIG (see <a href="Bv9ARM.ch04.html#tsig" title="TSIG">the section called “TSIG”</a>) 1090 or the command channel 1091 (see <a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and 1092 Usage">the section called “<span><strong class="command">controls</strong></span> Statement Definition and 1093 Usage”</a>). 1094 </p> 1095<p> 1096 The <span><strong class="command">key</strong></span> statement can occur at the 1097 top level 1098 of the configuration file or inside a <span><strong class="command">view</strong></span> 1099 statement. Keys defined in top-level <span><strong class="command">key</strong></span> 1100 statements can be used in all views. Keys intended for use in 1101 a <span><strong class="command">controls</strong></span> statement 1102 (see <a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and 1103 Usage">the section called “<span><strong class="command">controls</strong></span> Statement Definition…
Large files files are truncated, but you can click here to view the full file