Bv9ARM.ch06.html 631 KB
Newer Older
Rob Austein's avatar
regen  
Rob Austein committed
1
<!--
Tinderbox User's avatar
Tinderbox User committed
2
 - Copyright (C) 2004-2015 Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
regen  
Mark Andrews committed
3
 - Copyright (C) 2000-2003 Internet Software Consortium.
Rob Austein's avatar
regen  
Rob Austein committed
4
 - 
Automatic Updater's avatar
regen  
Automatic Updater committed
5
 - Permission to use, copy, modify, and/or distribute this software for any
Rob Austein's avatar
regen  
Rob Austein committed
6 7 8 9 10 11 12 13 14 15 16
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 - 
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->
Tinderbox User's avatar
Tinderbox User committed
17
<!-- $Id$ -->
Rob Austein's avatar
regen  
Rob Austein committed
18 19 20 21
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 6. BIND 9 Configuration Reference</title>
Mark Andrews's avatar
regen  
Mark Andrews committed
22
<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
Rob Austein's avatar
regen  
Rob Austein committed
23 24 25 26 27 28 29 30
<link rel="start" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
<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
31
<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
32 33 34 35 36 37 38 39 40 41 42 43
<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>
<div class="chapter" lang="en">
<div class="titlepage"><div><div><h2 class="title">
Mark Andrews's avatar
regen  
Mark Andrews committed
44
<a name="Bv9ARM.ch06"></a>Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</h2></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
45 46 47 48 49 50
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="Bv9ARM.ch06.html#configuration_file_elements">Configuration File Elements</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#address_match_lists">Address Match Lists</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
51
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2564126">Comment Syntax</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
52 53 54
</dl></dd>
<dt><span class="sect1"><a href="Bv9ARM.ch06.html#Configuration_File_Grammar">Configuration File Grammar</a></span></dt>
<dd><dl>
Tinderbox User's avatar
Tinderbox User committed
55
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574276"><span><strong class="command">acl</strong></span> Statement Grammar</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
56 57
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#acl"><span><strong class="command">acl</strong></span> Statement Definition and
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
58
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574466"><span><strong class="command">controls</strong></span> Statement Grammar</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
59 60
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage"><span><strong class="command">controls</strong></span> Statement Definition and
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
61 62
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574893"><span><strong class="command">include</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574910"><span><strong class="command">include</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
63
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
64 65 66 67
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574934"><span><strong class="command">key</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574957"><span><strong class="command">key</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575051"><span><strong class="command">logging</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575187"><span><strong class="command">logging</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
68
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
69 70 71 72
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2576512"><span><strong class="command">lwres</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2576677"><span><strong class="command">lwres</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2576773"><span><strong class="command">masters</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2576822"><span><strong class="command">masters</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
73
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
74
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2576843"><span><strong class="command">options</strong></span> Statement Grammar</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
75 76 77 78 79
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#options"><span><strong class="command">options</strong></span> Statement Definition and
          Usage</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#server_statement_grammar"><span><strong class="command">server</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#server_statement_definition_and_usage"><span><strong class="command">server</strong></span> Statement Definition and
            Usage</a></span></dt>
Automatic Updater's avatar
regen  
Automatic Updater committed
80
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#statschannels"><span><strong class="command">statistics-channels</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
81
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2592897"><span><strong class="command">statistics-channels</strong></span> Statement Definition and
Automatic Updater's avatar
regen  
Automatic Updater committed
82
            Usage</a></span></dt>
Automatic Updater's avatar
regen  
Automatic Updater committed
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>
Tinderbox User's avatar
Tinderbox User committed
84
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2593262"><span><strong class="command">trusted-keys</strong></span> Statement Definition
Automatic Updater's avatar
regen  
Automatic Updater committed
85
            and Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
86
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2593316"><span><strong class="command">managed-keys</strong></span> Statement Grammar</a></span></dt>
Automatic Updater's avatar
regen  
Automatic Updater committed
87
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#managed-keys"><span><strong class="command">managed-keys</strong></span> Statement Definition
Rob Austein's avatar
regen  
Rob Austein committed
88 89
            and Usage</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#view_statement_grammar"><span><strong class="command">view</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
90
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2593751"><span><strong class="command">view</strong></span> Statement Definition and Usage</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
91 92
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#zone_statement_grammar"><span><strong class="command">zone</strong></span>
            Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
93
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2595712"><span><strong class="command">zone</strong></span> Statement Definition and Usage</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
94
</dl></dd>
Tinderbox User's avatar
Tinderbox User committed
95
<dt><span class="sect1"><a href="Bv9ARM.ch06.html#id2599349">Zone File</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
96 97
<dd><dl>
<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>
Tinderbox User's avatar
Tinderbox User committed
98
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2602476">Discussion of MX Records</a></span></dt>
Rob Austein's avatar
regen  
Rob Austein committed
99
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#Setting_TTLs">Setting TTLs</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
100 101 102
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2603228">Inverse Mapping in IPv4</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2603355">Other Zone File Directives</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2603560"><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>
Rob Austein's avatar
regen  
Rob Austein committed
104
</dl></dd>
Automatic Updater's avatar
regen  
Automatic Updater committed
105 106
<dt><span class="sect1"><a href="Bv9ARM.ch06.html#statistics">BIND9 Statistics</a></span></dt>
<dd><dl><dt><span class="sect2"><a href="Bv9ARM.ch06.html#statistics_counters">Statistics Counters</a></span></dt></dl></dd>
Rob Austein's avatar
regen  
Rob Austein committed
107 108 109
</dl>
</div>
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
110 111
      <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
112
      areas
Mark Andrews's avatar
regen  
Mark Andrews committed
113 114
      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
115 116
      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
117
      found in <acronym class="acronym">BIND</acronym> 9.
Rob Austein's avatar
regen  
Rob Austein committed
118 119
    </p>
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
120
      <acronym class="acronym">BIND</acronym> 4 configuration files can be
Rob Austein's avatar
regen  
Rob Austein committed
121 122 123 124 125 126 127 128
      converted to the new format
      using the shell script
      <code class="filename">contrib/named-bootconf/named-bootconf.sh</code>.
    </p>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="configuration_file_elements"></a>Configuration File Elements</h2></div></div></div>
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
129
        Following is a list of elements used throughout the <acronym class="acronym">BIND</acronym> configuration
Rob Austein's avatar
regen  
Rob Austein committed
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
        file documentation:
      </p>
<div class="informaltable"><table border="1">
<colgroup>
<col>
<col>
</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
                  defined by the <span><strong class="command">acl</strong></span> statement.
                </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
                  <a href="Bv9ARM.ch06.html#address_match_lists" title="Address Match Lists">the section called &#8220;Address Match Lists&#8221;</a>.
                </p>
              </td>
</tr>
<tr>
Mark Andrews's avatar
gregen  
Mark Andrews committed
168 169 170 171 172 173 174 175
<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
176
                  with optional <code class="varname">key_id</code> and/or
Mark Andrews's avatar
gregen  
Mark Andrews committed
177 178 179 180 181 182 183
                  <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
184 185 186 187 188 189 190 191 192 193 194 195 196
<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
197 198 199 200 201 202 203 204 205 206 207 208 209
<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
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
<td>
                <p>
                  <code class="varname">dotted_decimal</code>
                </p>
              </td>
<td>
                <p>
                  One to four integers valued 0 through
                  255 separated by dots (`.'), such as <span><strong class="command">123</strong></span>,
                  <span><strong class="command">45.67</strong></span> or <span><strong class="command">89.123.45.67</strong></span>.
                </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>
                  An IPv6 address, such as <span><strong class="command">2001:db8::1234</strong></span>.
Mark Andrews's avatar
regen  
Mark Andrews committed
245 246 247 248 249 250 251 252 253
                  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
254
                  are supported, assuming one-to-one mapping between
Mark Andrews's avatar
regen  
Mark Andrews committed
255 256 257
                  interfaces and links.  For example, a link-local
                  address <span><strong class="command">fe80::1</strong></span> on the link
                  attached to the interface <span><strong class="command">ne0</strong></span>
Rob Austein's avatar
regen  
Rob Austein committed
258
                  can be specified as <span><strong class="command">fe80::1%ne0</strong></span>.
Mark Andrews's avatar
regen  
Mark Andrews committed
259 260 261
                  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
262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277
                </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
278 279 280 281 282 283 284 285 286 287 288 289 290 291 292
<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
293 294 295 296 297 298 299 300
<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
301
                  The <code class="varname">number</code> is limited to 0
Rob Austein's avatar
regen  
Rob Austein committed
302 303 304
                  through 65535, with values
                  below 1024 typically restricted to use by processes running
                  as root.
Mark Andrews's avatar
regen  
Mark Andrews committed
305
                  In some cases, an asterisk (`*') character can be used as a
Rob Austein's avatar
regen  
Rob Austein committed
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328
                  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.
                  For example, <span><strong class="command">127/8</strong></span> is the
                  network <span><strong class="command">127.0.0.0</strong></span> with
                  netmask <span><strong class="command">255.0.0.0</strong></span> and <span><strong class="command">1.2.3.0/28</strong></span> is
                  network <span><strong class="command">1.2.3.0</strong></span> with netmask <span><strong class="command">255.255.255.240</strong></span>.
                </p>
Mark Andrews's avatar
regen  
Mark Andrews committed
329 330 331 332 333
                <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
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 368 369 370 371
              </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
372
                  A non-negative 32-bit integer
Rob Austein's avatar
regen  
Rob Austein committed
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392
                  (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
393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419
<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
420 421 422 423 424 425 426
<td>
                <p>
                  <code class="varname">size_spec</code>
                </p>
              </td>
<td>
                <p>
Tinderbox User's avatar
Tinderbox User committed
427 428 429
                  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
430
                </p>
Mark Andrews's avatar
gregen  
Mark Andrews committed
431
                <p>
Tinderbox User's avatar
Tinderbox User committed
432 433
                  Integers may take values
                  0 &lt;= value &lt;= 18446744073709551615, though
Tinderbox User's avatar
Tinderbox User committed
434 435 436 437 438 439
                  certain parameters
                  (such as <span><strong class="command">max-journal-size</strong></span>) may
                  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
440
                  See the explanations of particular parameters
Tinderbox User's avatar
Tinderbox User committed
441
                  that use <code class="varname">size_spec</code>
Tinderbox User's avatar
Tinderbox User committed
442
                  for details on how they interpret its use.
Rob Austein's avatar
regen  
Rob Austein committed
443 444
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
445 446
                  Numeric values can optionally be followed by a
                  scaling factor:
Mark Andrews's avatar
gregen  
Mark Andrews committed
447 448 449 450
                  <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
451 452 453
                  <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
454 455
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
456
                  <code class="varname">unlimited</code> generally means
Tinderbox User's avatar
Tinderbox User committed
457 458
                  "as big as possible", and is usually the best
                  way to safely set a very large number.
Tinderbox User's avatar
Tinderbox User committed
459 460
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
461
                  <code class="varname">default</code>
Tinderbox User's avatar
Tinderbox User committed
462
                  uses the limit that was in force when the server was started.
Rob Austein's avatar
regen  
Rob Austein committed
463 464 465 466
                </p>
              </td>
</tr>
<tr>
Tinderbox User's avatar
Tinderbox User committed
467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486
<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>
                  The behaviour is exactly the same as
                  <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
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 516 517 518 519 520 521 522 523 524 525
<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>
</table></div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="address_match_lists"></a>Address Match Lists</h3></div></div></div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
526
<a name="id2573174"></a>Syntax</h4></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
527 528 529
<pre class="programlisting"><code class="varname">address_match_list</code> = address_match_list_element ;
  [<span class="optional"> address_match_list_element; ... </span>]
<code class="varname">address_match_list_element</code> = [<span class="optional"> ! </span>] (ip_address [<span class="optional">/length</span>] |
530
   key key_id | acl_name | { address_match_list } )
Rob Austein's avatar
regen  
Rob Austein committed
531 532 533 534
</pre>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
535
<a name="id2573202"></a>Definition and Usage</h4></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
536 537 538 539
<p>
            Address match lists are primarily used to determine access
            control for various server operations. They are also used in
            the <span><strong class="command">listen-on</strong></span> and <span><strong class="command">sortlist</strong></span>
Mark Andrews's avatar
regen  
Mark Andrews committed
540 541
            statements. The elements which constitute an address match
            list can be any of the following:
Rob Austein's avatar
regen  
Rob Austein committed
542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557
          </p>
<div class="itemizedlist"><ul type="disc">
<li>an IP address (IPv4 or IPv6)</li>
<li>an IP prefix (in `/' notation)</li>
<li>
                a key ID, as defined by the <span><strong class="command">key</strong></span>
                statement
              </li>
<li>the name of an address match list defined with
                the <span><strong class="command">acl</strong></span> statement
              </li>
<li>a nested address match list enclosed in braces</li>
</ul></div>
<p>
            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
558 559
            "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
560 561 562 563 564
          </p>
<p>
            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
565 566
            Nonetheless, the term "address match list" is still used
            throughout the documentation.
Rob Austein's avatar
regen  
Rob Austein committed
567 568 569
          </p>
<p>
            When a given IP address or prefix is compared to an address
Mark Andrews's avatar
regen  
Mark Andrews committed
570 571 572 573 574 575
            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>
<p>
Rob Austein's avatar
regen  
Rob Austein committed
576
            The interpretation of a match depends on whether the list is being
Automatic Updater's avatar
regen  
Automatic Updater committed
577 578
            used for access control, defining <span><strong class="command">listen-on</strong></span> ports, or in a
            <span><strong class="command">sortlist</strong></span>, and whether the element was negated.
Rob Austein's avatar
regen  
Rob Austein committed
579 580
          </p>
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
581 582 583 584
            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
            <span><strong class="command">allow-notify</strong></span>,
Mark Andrews's avatar
regen  
Mark Andrews committed
585 586
            <span><strong class="command">allow-recursion</strong></span>,
            <span><strong class="command">allow-recursion-on</strong></span>,
Mark Andrews's avatar
regen  
Mark Andrews committed
587
            <span><strong class="command">allow-query</strong></span>,
Mark Andrews's avatar
regen  
Mark Andrews committed
588
            <span><strong class="command">allow-query-on</strong></span>,
Mark Andrews's avatar
regen  
Mark Andrews committed
589
            <span><strong class="command">allow-query-cache</strong></span>,
Mark Andrews's avatar
regen  
Mark Andrews committed
590
            <span><strong class="command">allow-query-cache-on</strong></span>,
Rob Austein's avatar
regen  
Rob Austein committed
591
            <span><strong class="command">allow-transfer</strong></span>,
Mark Andrews's avatar
regen  
Mark Andrews committed
592
            <span><strong class="command">allow-update</strong></span>,
Tinderbox User's avatar
Tinderbox User committed
593 594 595
            <span><strong class="command">allow-update-forwarding</strong></span>,
            <span><strong class="command">blackhole</strong></span>, and
            <span><strong class="command">keep-response-order</strong></span> all use address match
Automatic Updater's avatar
regen  
Automatic Updater committed
596
            lists.  Similarly, the <span><strong class="command">listen-on</strong></span> option will cause the
Mark Andrews's avatar
regen  
Mark Andrews committed
597
            server to refuse queries on any of the machine's
Mark Andrews's avatar
regen  
Mark Andrews committed
598
            addresses which do not match the list.
Rob Austein's avatar
regen  
Rob Austein committed
599 600
          </p>
<p>
Automatic Updater's avatar
regen  
Automatic Updater committed
601
            Order of insertion is significant.  If more than one element
Mark Andrews's avatar
regen  
Mark Andrews committed
602 603 604 605 606 607 608 609 610 611 612 613 614
            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
            <span><strong class="command">1.2.3/24; ! 1.2.3.13;</strong></span>
            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
            element.  Using <span><strong class="command">! 1.2.3.13; 1.2.3/24</strong></span> fixes
            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
615 616 617 618 619
          </p>
</div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
620
<a name="id2564126"></a>Comment Syntax</h3></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
621
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
622
          The <acronym class="acronym">BIND</acronym> 9 comment syntax allows for
Rob Austein's avatar
regen  
Rob Austein committed
623
          comments to appear
Mark Andrews's avatar
regen  
Mark Andrews committed
624
          anywhere that whitespace may appear in a <acronym class="acronym">BIND</acronym> configuration
Rob Austein's avatar
regen  
Rob Austein committed
625 626 627 628 629
          file. To appeal to programmers of all kinds, they can be written
          in the C, C++, or shell/perl style.
        </p>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
630
<a name="id2564141"></a>Syntax</h4></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
631 632
<p>
            </p>
Mark Andrews's avatar
regen  
Mark Andrews committed
633
<pre class="programlisting">/* This is a <acronym class="acronym">BIND</acronym> comment as in C */</pre>
Rob Austein's avatar
regen  
Rob Austein committed
634 635
<p>
            </p>
Mark Andrews's avatar
regen  
Mark Andrews committed
636
<pre class="programlisting">// This is a <acronym class="acronym">BIND</acronym> comment as in C++</pre>
Rob Austein's avatar
regen  
Rob Austein committed
637 638
<p>
            </p>
Automatic Updater's avatar
regen  
Automatic Updater committed
639 640
<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
641 642 643 644 645
<p>
          </p>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
646
<a name="id2564171"></a>Definition and Usage</h4></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
647
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
648
            Comments may appear anywhere that whitespace may appear in
Mark Andrews's avatar
regen  
Mark Andrews committed
649
            a <acronym class="acronym">BIND</acronym> configuration file.
Rob Austein's avatar
regen  
Rob Austein committed
650 651 652 653 654 655 656 657 658 659 660 661 662 663 664
          </p>
<p>
            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>
<p>
            C-style comments cannot be nested. For example, the following
            is not valid because the entire comment ends with the first */:
          </p>
<p>

</p>
<pre class="programlisting">/* This is the start of a comment.
665 666 667
   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
668 669 670 671 672 673 674 675 676 677 678 679 680 681 682
</pre>
<p>

          </p>
<p>
            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>
<p>

</p>
<pre class="programlisting">// This is the start of a comment.  The next line
683 684
// is a new comment, even though it is logically
// part of the previous comment.
Rob Austein's avatar
regen  
Rob Austein committed
685 686 687 688 689 690 691 692 693 694 695 696 697 698 699
</pre>
<p>

          </p>
<p>
            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>
<p>

</p>
<pre class="programlisting"># This is the start of a comment.  The next line
700 701
# is a new comment, even though it is logically
# part of the previous comment.
Rob Austein's avatar
regen  
Rob Austein committed
702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721
</pre>
<p>

          </p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p>
              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>
</div>
</div>
</div>
</div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="Configuration_File_Grammar"></a>Configuration File Grammar</h2></div></div></div>
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
722
        A <acronym class="acronym">BIND</acronym> 9 configuration consists of
Rob Austein's avatar
regen  
Rob Austein committed
723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798
        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>
<p>
        The following statements are supported:
      </p>
<div class="informaltable"><table border="1">
<colgroup>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td>
                <p><span><strong class="command">acl</strong></span></p>
              </td>
<td>
                <p>
                  defines a named IP address
                  matching list, for access control and other uses.
                </p>
              </td>
</tr>
<tr>
<td>
                <p><span><strong class="command">controls</strong></span></p>
              </td>
<td>
                <p>
                  declares control channels to be used
                  by the <span><strong class="command">rndc</strong></span> utility.
                </p>
              </td>
</tr>
<tr>
<td>
                <p><span><strong class="command">include</strong></span></p>
              </td>
<td>
                <p>
                  includes a file.
                </p>
              </td>
</tr>
<tr>
<td>
                <p><span><strong class="command">key</strong></span></p>
              </td>
<td>
                <p>
                  specifies key information for use in
                  authentication and authorization using TSIG.
                </p>
              </td>
</tr>
<tr>
<td>
                <p><span><strong class="command">logging</strong></span></p>
              </td>
<td>
                <p>
                  specifies what the server logs, and where
                  the log messages are sent.
                </p>
              </td>
</tr>
<tr>
<td>
                <p><span><strong class="command">lwres</strong></span></p>
              </td>
<td>
                <p>
                  configures <span><strong class="command">named</strong></span> to
Mark Andrews's avatar
regen  
Mark Andrews committed
799
                  also act as a light-weight resolver daemon (<span><strong class="command">lwresd</strong></span>).
Rob Austein's avatar
regen  
Rob Austein committed
800 801 802 803 804 805 806 807 808 809
                </p>
              </td>
</tr>
<tr>
<td>
                <p><span><strong class="command">masters</strong></span></p>
              </td>
<td>
                <p>
                  defines a named masters list for
Automatic Updater's avatar
Automatic Updater committed
810
                  inclusion in stub and slave zones'
Tinderbox User's avatar
Tinderbox User committed
811
                  <span><strong class="command">masters</strong></span> or
Automatic Updater's avatar
Automatic Updater committed
812
                  <span><strong class="command">also-notify</strong></span> lists.
Rob Austein's avatar
regen  
Rob Austein committed
813 814 815 816 817 818 819 820 821 822 823 824 825 826 827
                </p>
              </td>
</tr>
<tr>
<td>
                <p><span><strong class="command">options</strong></span></p>
              </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
828
<td>
Automatic Updater's avatar
regen  
Automatic Updater committed
829
                <p><span><strong class="command">server</strong></span></p>
Mark Andrews's avatar
regen  
Mark Andrews committed
830 831 832
              </td>
<td>
                <p>
Automatic Updater's avatar
regen  
Automatic Updater committed
833 834
                  sets certain configuration options on
                  a per-server basis.
Mark Andrews's avatar
regen  
Mark Andrews committed
835 836 837 838
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen  
Rob Austein committed
839
<td>
Automatic Updater's avatar
regen  
Automatic Updater committed
840
                <p><span><strong class="command">statistics-channels</strong></span></p>
Rob Austein's avatar
regen  
Rob Austein committed
841 842 843
              </td>
<td>
                <p>
Automatic Updater's avatar
regen  
Automatic Updater committed
844 845
                  declares communication channels to get access to
                  <span><strong class="command">named</strong></span> statistics.
Rob Austein's avatar
regen  
Rob Austein committed
846 847 848 849 850 851 852 853 854 855 856 857 858 859
                </p>
              </td>
</tr>
<tr>
<td>
                <p><span><strong class="command">trusted-keys</strong></span></p>
              </td>
<td>
                <p>
                  defines trusted DNSSEC keys.
                </p>
              </td>
</tr>
<tr>
Automatic Updater's avatar
regen  
Automatic Updater committed
860 861 862 863 864 865 866 867 868 869 870
<td>
                <p><span><strong class="command">managed-keys</strong></span></p>
              </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
871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899
<td>
                <p><span><strong class="command">view</strong></span></p>
              </td>
<td>
                <p>
                  defines a view.
                </p>
              </td>
</tr>
<tr>
<td>
                <p><span><strong class="command">zone</strong></span></p>
              </td>
<td>
                <p>
                  defines a zone.
                </p>
              </td>
</tr>
</tbody>
</table></div>
<p>
        The <span><strong class="command">logging</strong></span> and
        <span><strong class="command">options</strong></span> statements may only occur once
        per
        configuration.
      </p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
900
<a name="id2574276"></a><span><strong class="command">acl</strong></span> Statement Grammar</h3></div></div></div>
Mark Andrews's avatar
gregen  
Mark Andrews committed
901 902
<pre class="programlisting"><span><strong class="command">acl</strong></span> acl-name {
    address_match_list
903
};
Rob Austein's avatar
regen  
Rob Austein committed
904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950
</pre>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="acl"></a><span><strong class="command">acl</strong></span> Statement Definition and
          Usage</h3></div></div></div>
<p>
          The <span><strong class="command">acl</strong></span> statement assigns a symbolic
          name to an address match list. It gets its name from a primary
          use of address match lists: Access Control Lists (ACLs).
        </p>
<p>
          The following ACLs are built-in:
        </p>
<div class="informaltable"><table border="1">
<colgroup>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td>
                  <p><span><strong class="command">any</strong></span></p>
                </td>
<td>
                  <p>
                    Matches all hosts.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p><span><strong class="command">none</strong></span></p>
                </td>
<td>
                  <p>
                    Matches no hosts.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p><span><strong class="command">localhost</strong></span></p>
                </td>
<td>
                  <p>
                    Matches the IPv4 and IPv6 addresses of all network
Tinderbox User's avatar
Tinderbox User committed
951 952 953
                    interfaces on the system.  When addresses are
                    added or removed, the <span><strong class="command">localhost</strong></span>
                    ACL element is updated to reflect the changes.
Rob Austein's avatar
regen  
Rob Austein committed
954 955 956 957 958 959 960 961 962 963 964
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p><span><strong class="command">localnets</strong></span></p>
                </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
965 966 967
                    When addresses are added or removed,
                    the <span><strong class="command">localnets</strong></span>
                    ACL element is updated to reflect the changes.
Rob Austein's avatar
regen  
Rob Austein committed
968 969 970 971 972 973 974 975 976 977 978 979 980 981
                    Some systems do not provide a way to determine the prefix
                    lengths of
                    local IPv6 addresses.
                    In such a case, <span><strong class="command">localnets</strong></span>
                    only matches the local
                    IPv6 addresses, just like <span><strong class="command">localhost</strong></span>.
                  </p>
                </td>
</tr>
</tbody>
</table></div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
982
<a name="id2574466"></a><span><strong class="command">controls</strong></span> Statement Grammar</h3></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
983
<pre class="programlisting"><span><strong class="command">controls</strong></span> {
Automatic Updater's avatar
regen  
Automatic Updater committed
984 985
   [ inet ( ip_addr | * ) [ port ip_port ]
                allow { <em class="replaceable"><code> address_match_list </code></em> }
Mark Andrews's avatar
gregen  
Mark Andrews committed
986 987
                keys { <em class="replaceable"><code>key_list</code></em> }; ]
   [ inet ...; ]
Automatic Updater's avatar
regen  
Automatic Updater committed
988 989
   [ 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>
     keys { <em class="replaceable"><code>key_list</code></em> }; ]
Mark Andrews's avatar
gregen  
Mark Andrews committed
990
   [ unix ...; ]
991
};
Rob Austein's avatar
regen  
Rob Austein committed
992 993 994 995 996 997 998
</pre>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="controls_statement_definition_and_usage"></a><span><strong class="command">controls</strong></span> Statement Definition and
          Usage</h3></div></div></div>
<p>
Mark Andrews's avatar
gregen  
Mark Andrews committed
999
          The <span><strong class="command">controls</strong></span> statement declares control
Rob Austein's avatar
regen  
Rob Austein committed
1000 1001 1002
          channels to be used by system administrators to control the
          operation of the name server. These control channels are
          used by the <span><strong class="command">rndc</strong></span> utility to send
Mark Andrews's avatar
gregen  
Mark Andrews committed
1003
          commands to and retrieve non-DNS results from a name server.
Rob Austein's avatar
regen  
Rob Austein committed
1004 1005
        </p>
<p>
Mark Andrews's avatar
gregen  
Mark Andrews committed
1006 1007 1008
          An <span><strong class="command">inet</strong></span> control channel is a TCP socket
          listening at the specified <span><strong class="command">ip_port</strong></span> on the
          specified <span><strong class="command">ip_addr</strong></span>, which can be an IPv4 or IPv6
Mark Andrews's avatar
regen  
Mark Andrews committed
1009
          address.  An <span><strong class="command">ip_addr</strong></span> of <code class="literal">*</code> (asterisk) is
Mark Andrews's avatar
gregen  
Mark Andrews committed
1010 1011 1012
          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,
Rob Austein's avatar
regen  
Rob Austein committed
1013
          use an <span><strong class="command">ip_addr</strong></span> of <code class="literal">::</code>.
Mark Andrews's avatar
gregen  
Mark Andrews committed
1014
          If you will only use <span><strong class="command">rndc</strong></span> on the local host,
Rob Austein's avatar
regen  
Rob Austein committed
1015
          using the loopback address (<code class="literal">127.0.0.1</code>
Mark Andrews's avatar
gregen  
Mark Andrews committed
1016
          or <code class="literal">::1</code>) is recommended for maximum security.
Rob Austein's avatar
regen  
Rob Austein committed
1017 1018
        </p>
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
1019
          If no port is specified, port 953 is used. The asterisk
Mark Andrews's avatar
gregen  
Mark Andrews committed
1020
          "<code class="literal">*</code>" cannot be used for <span><strong class="command">ip_port</strong></span>.
Rob Austein's avatar
regen  
Rob Austein committed
1021 1022 1023 1024
        </p>
<p>
          The ability to issue commands over the control channel is
          restricted by the <span><strong class="command">allow</strong></span> and
Mark Andrews's avatar
gregen  
Mark Andrews committed
1025 1026 1027
          <span><strong class="command">keys</strong></span> clauses.
          Connections to the control channel are permitted based on the
          <span><strong class="command">address_match_list</strong></span>.  This is for simple
Rob Austein's avatar
regen  
Rob Austein committed
1028 1029
          IP address based filtering only; any <span><strong class="command">key_id</strong></span>
          elements of the <span><strong class="command">address_match_list</strong></span>
Mark Andrews's avatar
gregen  
Mark Andrews committed
1030 1031 1032
          are ignored.
        </p>
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
1033
          A <span><strong class="command">unix</strong></span> control channel is a UNIX domain
Mark Andrews's avatar
gregen  
Mark Andrews committed
1034 1035 1036 1037 1038 1039
          socket listening at the specified path in the file system.
          Access to the socket is specified by the <span><strong class="command">perm</strong></span>,
          <span><strong class="command">owner</strong></span> and <span><strong class="command">group</strong></span> clauses.
          Note on some platforms (SunOS and Solaris) the permissions
          (<span><strong class="command">perm</strong></span>) are applied to the parent directory
          as the permissions on the socket itself are ignored.
Rob Austein's avatar
regen  
Rob Austein committed
1040 1041 1042 1043
        </p>
<p>
          The primary authorization mechanism of the command
          channel is the <span><strong class="command">key_list</strong></span>, which
Mark Andrews's avatar
gregen  
Mark Andrews committed
1044 1045 1046 1047 1048
          contains a list of <span><strong class="command">key_id</strong></span>s.
          Each <span><strong class="command">key_id</strong></span> in the <span><strong class="command">key_list</strong></span>
          is authorized to execute commands over the control channel.
          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 &#8220;Administrative Tools&#8221;</a>)
          for information about configuring keys in <span><strong class="command">rndc</strong></span>.
Rob Austein's avatar
regen  
Rob Austein committed
1049 1050 1051 1052 1053 1054 1055
        </p>
<p>
          If no <span><strong class="command">controls</strong></span> statement is present,
          <span><strong class="command">named</strong></span> will set up a default
          control channel listening on the loopback address 127.0.0.1
          and its IPv6 counterpart ::1.
          In this case, and also when the <span><strong class="command">controls</strong></span> statement
Mark Andrews's avatar
gregen  
Mark Andrews committed
1056 1057
          is present but does not have a <span><strong class="command">keys</strong></span> clause,
          <span><strong class="command">named</strong></span> will attempt to load the command channel key
Rob Austein's avatar
regen  
Rob Austein committed
1058 1059
          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
1060
          was specified as when <acronym class="acronym">BIND</acronym> was built).
Rob Austein's avatar
regen  
Rob Austein committed
1061 1062 1063 1064 1065
          To create a <code class="filename">rndc.key</code> file, run
          <strong class="userinput"><code>rndc-confgen -a</code></strong>.
        </p>
<p>
          The <code class="filename">rndc.key</code> feature was created to
Mark Andrews's avatar
regen  
Mark Andrews committed
1066
          ease the transition of systems from <acronym class="acronym">BIND</acronym> 8,
Rob Austein's avatar
regen  
Rob Austein committed
1067
          which did not have digital signatures on its command channel
Mark Andrews's avatar
gregen  
Mark Andrews committed
1068
          messages and thus did not have a <span><strong class="command">keys</strong></span> clause.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1069

Mark Andrews's avatar
regen  
Mark Andrews committed
1070 1071
          It makes it possible to use an existing <acronym class="acronym">BIND</acronym> 8
          configuration file in <acronym class="acronym">BIND</acronym> 9 unchanged,
Rob Austein's avatar
regen  
Rob Austein committed
1072
          and still have <span><strong class="command">rndc</strong></span> work the same way
Mark Andrews's avatar
gregen  
Mark Andrews committed
1073
          <span><strong class="command">ndc</strong></span> worked in BIND 8, simply by executing the
Rob Austein's avatar
regen  
Rob Austein committed
1074 1075 1076 1077 1078 1079
          command <strong class="userinput"><code>rndc-confgen -a</code></strong> after BIND 9 is
          installed.
        </p>
<p>
          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
1080
          <acronym class="acronym">BIND</acronym> 8 configuration files, this
Rob Austein's avatar
regen  
Rob Austein committed
1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091
          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
          <span><strong class="command">named</strong></span> is running as) can access it.
          If you
          desire greater flexibility in allowing other users to access
Mark Andrews's avatar
regen  
Mark Andrews committed
1092 1093 1094
          <span><strong class="command">rndc</strong></span> commands, then you need to create
          a
          <code class="filename">rndc.conf</code> file and make it group
Rob Austein's avatar
regen  
Rob Austein committed
1095 1096 1097 1098
          readable by a group
          that contains the users who should have access.
        </p>
<p>
Mark Andrews's avatar
gregen  
Mark Andrews committed
1099 1100 1101
          To disable the command channel, use an empty
          <span><strong class="command">controls</strong></span> statement:
          <span><strong class="command">controls { };</strong></span>.
Rob Austein's avatar
regen  
Rob Austein committed
1102 1103 1104 1105
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1106
<a name="id2574893"></a><span><strong class="command">include</strong></span> Statement Grammar</h3></div></div></div>
Mark Andrews's avatar
regen  
Mark Andrews committed
1107
<pre class="programlisting"><span><strong class="command">include</strong></span> <em class="replaceable"><code>filename</code></em>;</pre>
Rob Austein's avatar
regen  
Rob Austein committed
1108 1109 1110
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1111
<a name="id2574910"></a><span><strong class="command">include</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125
          Usage</h3></div></div></div>
<p>
          The <span><strong class="command">include</strong></span> statement inserts the
          specified file at the point where the <span><strong class="command">include</strong></span>
          statement is encountered. The <span><strong class="command">include</strong></span>
                statement facilitates the administration of configuration
          files
          by permitting the reading or writing of some things but not
          others. For example, the statement could include private keys
          that are readable only by the name server.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1126
<a name="id2574934"></a><span><strong class="command">key</strong></span> Statement Grammar</h3></div></div></div>
Mark Andrews's avatar
regen  
Mark Andrews committed
1127
<pre class="programlisting"><span><strong class="command">key</strong></span> <em class="replaceable"><code>key_id</code></em> {
Tinderbox User's avatar
Tinderbox User committed
1128 1129
    algorithm <em class="replaceable"><code>algorithm_id</code></em>;
    secret <em class="replaceable"><code>secret_string</code></em>;
1130
};
Rob Austein's avatar
regen  
Rob Austein committed
1131 1132 1133 1134
</pre>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1135
<a name="id2574957"></a><span><strong class="command">key</strong></span> Statement Definition and Usage</h3></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166
<p>
          The <span><strong class="command">key</strong></span> statement defines a shared
          secret key for use with TSIG (see <a href="Bv9ARM.ch04.html#tsig" title="TSIG">the section called &#8220;TSIG&#8221;</a>)
          or the command channel
          (see <a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and
          Usage">the section called &#8220;<span><strong class="command">controls</strong></span> Statement Definition and
          Usage&#8221;</a>).
        </p>
<p>
          The <span><strong class="command">key</strong></span> statement can occur at the
          top level
          of the configuration file or inside a <span><strong class="command">view</strong></span>
          statement.  Keys defined in top-level <span><strong class="command">key</strong></span>
          statements can be used in all views.  Keys intended for use in
          a <span><strong class="command">controls</strong></span> statement
          (see <a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and
          Usage">the section called &#8220;<span><strong class="command">controls</strong></span> Statement Definition and
          Usage&#8221;</a>)
          must be defined at the top level.
        </p>
<p>
          The <em class="replaceable"><code>key_id</code></em>, also known as the
          key name, is a domain name uniquely identifying the key. It can
          be used in a <span><strong class="command">server</strong></span>
          statement to cause requests sent to that
          server to be signed with this key, or in address match lists to
          verify that incoming requests have been signed with a key
          matching this name, algorithm, and secret.
        </p>
<p>
          The <em class="replaceable"><code>algorithm_id</code></em> is a string
Tinderbox User's avatar
Tinderbox User committed
1167 1168
          that specifies a security/authentication algorithm.  The
          <span><strong class="command">named</strong></span> server supports <code class="literal">hmac-md5</code>,
Mark Andrews's avatar
regen  
Mark Andrews committed
1169 1170 1171 1172
          <code class="literal">hmac-sha1</code>, <code class="literal">hmac-sha224</code>,
          <code class="literal">hmac-sha256</code>, <code class="literal">hmac-sha384</code>
          and <code class="literal">hmac-sha512</code> TSIG authentication.
          Truncated hashes are supported by appending the minimum
Mark Andrews's avatar
regen  
Mark Andrews committed
1173
          number of required bits preceded by a dash, e.g.
Mark Andrews's avatar
regen  
Mark Andrews committed
1174
          <code class="literal">hmac-sha1-80</code>.  The
Rob Austein's avatar
regen  
Rob Austein committed
1175
          <em class="replaceable"><code>secret_string</code></em> is the secret
Mark Andrews's avatar
regen  
Mark Andrews committed
1176 1177
          to be used by the algorithm, and is treated as a base-64
          encoded string.
Rob Austein's avatar
regen  
Rob Austein committed
1178 1179 1180 1181
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1182
<a name="id2575051"></a><span><strong class="command">logging</strong></span> Statement Grammar</h3></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
1183 1184
<pre class="programlisting"><span><strong class="command">logging</strong></span> {
   [ <span><strong class="command">channel</strong></span> <em class="replaceable"><code>channel_name</code></em> {
Automatic Updater's avatar
regen  
Automatic Updater committed
1185
     ( <span><strong class="command">file</strong></span> <em class="replaceable"><code>path_name</code></em>
Rob Austein's avatar
regen  
Rob Austein committed
1186
         [ <span><strong class="command">versions</strong></span> ( <em class="replaceable"><code>number</code></em> | <span><strong class="command">unlimited</strong></span> ) ]
Tinderbox User's avatar
Tinderbox User committed
1187
         [ <span><strong class="command">size</strong></span> <em class="replaceable"><code>size_spec</code></em> ]
Rob Austein's avatar
regen  
Rob Austein committed
1188 1189 1190 1191 1192 1193 1194 1195
       | <span><strong class="command">syslog</strong></span> <em class="replaceable"><code>syslog_facility</code></em>
       | <span><strong class="command">stderr</strong></span>
       | <span><strong class="command">null</strong></span> );
     [ <span><strong class="command">severity</strong></span> (<code class="option">critical</code> | <code class="option">error</code> | <code class="option">warning</code> | <code class="option">notice</code> |
                 <code class="option">info</code> | <code class="option">debug</code> [ <em class="replaceable"><code>level</code></em> ] | <code class="option">dynamic</code> ); ]
     [ <span><strong class="command">print-category</strong></span> <code class="option">yes</code> or <code class="option">no</code>; ]
     [ <span><strong class="command">print-severity</strong></span> <code class="option">yes</code> or <code class="option">no</code>; ]
     [ <span><strong class="command">print-time</strong></span> <code class="option">yes</code> or <code class="option">no</code>; ]
Tinderbox User's avatar
Tinderbox User committed
1196
     [ <span><strong class="command">buffered</strong></span> <code class="option">yes</code> or <code class="option">no</code>; ]
1197
   }; ]
Rob Austein's avatar
regen  
Rob Austein committed
1198 1199
   [ <span><strong class="command">category</strong></span> <em class="replaceable"><code>category_name</code></em> {
     <em class="replaceable"><code>channel_name</code></em> ; [ <em class="replaceable"><code>channel_name</code></em> ; ... ]
1200 1201 1202
   }; ]
   ...
};
Rob Austein's avatar
regen  
Rob Austein committed
1203 1204 1205 1206
</pre>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1207
<a name="id2575187"></a><span><strong class="command">logging</strong></span> Statement Definition and
Rob Austein's avatar
regen  
Rob Austein committed
1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223
          Usage</h3></div></div></div>
<p>
          The <span><strong class="command">logging</strong></span> statement configures a
          wide
          variety of logging options for the name server. Its <span><strong class="command">channel</strong></span> phrase
          associates output methods, format options and severity levels with
          a name that can then be used with the <span><strong class="command">category</strong></span> phrase
          to select how various classes of messages are logged.
        </p>
<p>
          Only one <span><strong class="command">logging</strong></span> statement is used to
          define
          as many channels and categories as are wanted. If there is no <span><strong class="command">logging</strong></span> statement,
          the logging configuration will be:
        </p>
<pre class="programlisting">logging {
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1224 1225
     category default { default_syslog; default_debug; };
     category unmatched { null; };
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1226
};
Rob Austein's avatar
regen  
Rob Austein committed
1227
</pre>
Tinderbox User's avatar
Tinderbox User committed
1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238
<p>
          If <span><strong class="command">named</strong></span> is started with the
          <code class="option">-L</code> option, it logs to the specified file
          at startup, instead of using syslog. In this case the logging
          configuration will be:
        </p>
<pre class="programlisting">logging {
     category default { default_logfile; default_debug; };
     category unmatched { null; };
};
</pre>
Rob Austein's avatar
regen  
Rob Austein committed
1239
<p>
Mark Andrews's avatar
regen  
Mark Andrews committed
1240
          In <acronym class="acronym">BIND</acronym> 9, the logging configuration
Rob Austein's avatar
regen  
Rob Austein committed
1241
          is only established when
Mark Andrews's avatar
regen  
Mark Andrews committed
1242
          the entire configuration file has been parsed.  In <acronym class="acronym">BIND</acronym> 8, it was
Rob Austein's avatar
regen  
Rob Austein committed
1243 1244 1245 1246
          established as soon as the <span><strong class="command">logging</strong></span>
          statement
          was parsed. When the server is starting up, all logging messages
          regarding syntax errors in the configuration file go to the default
Tinderbox User's avatar
Tinderbox User committed
1247
          channels, or to standard error if the <code class="option">-g</code> option
Rob Austein's avatar
regen  
Rob Austein committed
1248 1249 1250 1251
          was specified.
        </p>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
1252
<a name="id2575252"></a>The <span><strong class="command">channel</strong></span> Phrase</h4></div></div></div>
Rob Austein's avatar
regen  
Rob Austein committed
1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285
<p>
            All log output goes to one or more <span class="emphasis"><em>channels</em></span>;
            you can make as many of them as you want.
          </p>
<p>
            Every channel definition must include a destination clause that
            says whether messages selected for the channel go to a file, to a
            particular syslog facility, to the standard error stream, or are
            discarded. It can optionally also limit the message severity level
            that will be accepted by the channel (the default is
            <span><strong class="command">info</strong></span>), and whether to include a
            <span><strong class="command">named</strong></span>-generated time stamp, the
            category name
            and/or severity level (the default is not to include any).
          </p>
<p>
            The <span><strong class="command">null</strong></span> destination clause
            causes all messages sent to the channel to be discarded;
            in that case, other options for the channel are meaningless.
          </p>
<p>
            The <span><strong class="command">file</strong></span> destination clause directs
            the channel
            to a disk file.  It can include limitations
            both on how large the file is allowed to become, and how many
            versions
            of the file will be saved each time the file is opened.
          </p>
<p>
            If you use the <span><strong class="command">versions</strong></span> log file
            option, then
            <span><strong class="command">named</strong></span> will retain that many backup
            versions of the file by
Mark Andrews's avatar
regen  
Mark Andrews committed
1286 1287 1288
            renaming them when opening.  For example, if you choose to keep
            three old versions
            of the file <code class="filename">lamers.log</code>, then just
Rob Austein's avatar
regen  
Rob Austein committed
1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324
            before it is opened
            <code class="filename">lamers.log.1</code> is renamed to
            <code class="filename">lamers.log.2</code>, <code class="filename">lamers.log.0</code> is renamed
            to <code class="filename">lamers.log.1</code>, and <code class="filename">lamers.log</code> is
            renamed to <code class="filename">lamers.log.0</code>.
            You can say <span><strong class="command">versions unlimited</strong></span> to
            not limit
            the number of versions.
            If a <span><strong class="command">size</strong></span> option is associated with
            the log file,
            then renaming is only done when the file being opened exceeds the
            indicated size.  No backup versions are kept by default; any
            existing
            log file is simply appended.
          </p>
<p>
            The <span><strong class="command">size</strong></span> option for files is used
            to limit log
            growth. If the file ever exceeds the size, then <span><strong class="command">named</strong></span> will
            stop writing to the file unless it has a <span><strong class="command">versions</strong></span> option
            associated with it.  If backup versions are kept, the files are
            rolled as
            described above and a new one begun.  If there is no
            <span><strong class="command">versions</strong></span> option, no more data will
            be written to the log
            until some out-of-band mechanism removes or truncates the log to
            less than the
            maximum size.  The default behavior is not to limit the size of
            the
            file.
          </p>
<p>
            Example usage of the <span><strong class="command">size</strong></span> and
            <span><strong class="command">versions</strong></span> options:
          </p>
<pre class="programlisting">channel an_example_channel {
1325 1326 1327 1328
    file "example.log" versions 3 size 20m;
    print-time yes;
    print-category yes;
};
Rob Austein's avatar
regen  
Rob Austein committed
1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351
</pre>
<p>
            The <span><strong class="command">syslog</strong></span> destination clause
            directs the
            channel to the system log.  Its argument is a
            syslog facility as described in the <span><strong class="command">syslog</strong></span> man
            page. Known facilities are <span><strong class="command">kern</strong></span>, <span><strong class="command">user</strong></span>,
            <span><strong class="command">mail</strong></span>, <span><strong class="command">daemon</strong></span>, <span><strong class="command">auth</strong></span>,
            <span><strong class="command">syslog</strong></span>, <span><strong class="command">lpr</strong></span>, <span><strong class="command">news</strong></span>,
            <span><strong class="command">uucp</strong></span>, <span><strong class="command">cron</strong></span>, <span><strong class="command">authpriv</strong></span>,
            <span><strong class="command">ftp</strong></span>, <span><strong class="command">local0</strong></span>, <span><strong class="command">local1</strong></span>,
            <span><strong class="command">local2</strong></span>, <span><strong class="command">local3</strong></span>, <span><strong class="command">local4</strong></span>,
            <span><strong class="command">local5</strong></span>, <span><strong class="command">local6</strong></span> and
            <span><strong class="command">local7</strong></span>, however not all facilities
            are supported on
            all operating systems.
            How <span><strong class="command">syslog</strong></span> will handle messages
            sent to
            this facility is described in the <span><strong class="command">syslog.conf</strong></span> man
            page. If you have a system which uses a very old version of <span><strong class="command">syslog</strong></span> that
            only uses two arguments to the <span><strong class="command">openlog()</strong></span> function,
            then this clause is silently ignored.
          </p>
Tinderbox User's avatar
Tinderbox User committed
1352 1353 1354
<p>
            On Windows machines syslog messages are directed to the EventViewer.
          </p>
Rob Austein's avatar
regen  
Rob Austein committed
1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393
<p>
            The <span><strong class="command">severity</strong></span> clause works like <span><strong class="command">syslog</strong></span>'s
            "priorities", except that they can also be used if you are writing
            straight to a file rather than using <span><strong class="command">syslog</strong></span>.
            Messages which are not at least of the severity level given will
            not be selected for the channel; messages of higher severity
            levels
            will be accepted.
          </p>
<p>
            If you are using <span><strong class="command">syslog</strong></span>, then the <span><strong class="command">syslog.conf</strong></span> priorities
            will also determine what eventually passes through. For example,
            defining a channel facility and severity as <span><strong class="command">daemon</strong></span> and <span><strong class="command">debug</strong></span> but
            only logging <span><strong class="command">daemon.warning</strong></span> via <span><strong class="command">syslog.conf</strong></span> will
            cause messages of severity <span><strong class="command">info</strong></span> and
            <span><strong class="command">notice</strong></span> to
            be dropped. If the situation were reversed, with <span><strong class="command">named</strong></span> writing
            messages of only <span><strong class="command">warning</strong></span> or higher,
            then <span><strong class="command">syslogd</strong></span> would
            print all messages it received from the channel.
          </p>
<p>
            The <span><strong class="command">stderr</strong></span> destination clause
            directs the
            channel to the server's standard error stream.  This is intended
            for
            use when the server is running as a foreground process, for
            example
            when debugging a configuration.
          </p>
<p>
            The server can supply extensive debugging information when
            it is in debugging mode. If the server's global debug level is
            greater
            than zero, then debugging mode will be active. The global debug
            level is set either by starting the <span><strong class="command">named</strong></span> server
            with the <code class="option">-d</code> flag followed by a positive integer,
            or by running <span><strong class="command">rndc trace</strong></span>.
            The global debug level
Mark Andrews's avatar
regen  
Mark Andrews committed
1394
            can be set to zero, and debugging mode turned off, by running <span><strong class="command">rndc
Rob Austein's avatar
regen  
Rob Austein committed
1395 1396 1397 1398 1399
notrace</strong></span>. All debugging messages in the server have a debug
            level, and higher debug levels give more detailed output. Channels
            that specify a specific debug severity, for example:
          </p>
<pre class="programlisting">channel specific_debug_level {
1400 1401 1402
    file "foo";
    severity debug 3;
};
Rob Austein's avatar
regen  
Rob Austein committed
1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416
</pre>
<p>
            will get debugging output of level 3 or less any time the
            server is in debugging mode, regardless of the global debugging
            level. Channels with <span><strong class="command">dynamic</strong></span>
            severity use the
            server's global debug level to determine what messages to print.
          </p>
<p>
            If <span><strong class="command">print-time</strong></span> has been turned on,
            then
            the date and time will be logged. <span><strong class="command">print-time</strong></span> may
            be specified for a <span><strong class="command">syslog</strong></span> channel,
            but is usually
Automatic Updater's avatar
regen  
Automatic Updater committed
1417
            pointless since <span><strong class="command">syslog</strong></span> also logs
Rob Austein's avatar
regen  
Rob Austein committed
1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431
            the date and
            time. If <span><strong class="command">print-category</strong></span> is
            requested, then the
            category of the message will be logged as well. Finally, if <span><strong class="command">print-severity</strong></span> is
            on, then the severity level of the message will be logged. The <span><strong class="command">print-</strong></span> options may
            be used in any combination, and will always be printed in the
            following
            order: time, category, severity. Here is an example where all
            three <span><strong class="command">print-</strong></span> options
            are on:
          </p>
<p>
            <code class="computeroutput">28-Feb-2000 15:05:32.863 general: notice: running</code>
          </p>
Tinderbox User's avatar
Tinderbox User committed
1432 1433 1434 1435 1436
<p>
            If <span><strong class="command">buffered</strong></span> has been turned on the output
            to files will not be flushed after each log entry.  By default
            all log messages are flushed.
          </p>
Rob Austein's avatar
regen  
Rob Austein committed