Bv9ARM.ch06.html 632 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#id2573300">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#id2574165"><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#id2574423"><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#id2574782"><span><strong class="command">include</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574800"><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#id2574891"><span><strong class="command">key</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2574915"><span><strong class="command">key</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575009"><span><strong class="command">logging</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2575144"><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
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2577350"><span><strong class="command">lwres</strong></span> Statement Grammar</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2577447"><span><strong class="command">lwres</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2577611"><span><strong class="command">masters</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
72
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2577660"><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#id2577682"><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#id2593291"><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#id2593657"><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#id2593710"><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#id2594146"><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#id2596230"><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#id2599866">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#id2602970">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#id2603586">Inverse Mapping in IPv4</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2603781">Other Zone File Directives</a></span></dt>
<dt><span class="sect2"><a href="Bv9ARM.ch06.html#id2604054"><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
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
                </p>
              </td>
</tr>
<tr>
<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
506
<a name="id2573131"></a>Syntax</h4></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
507
508
509
<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>] |
510
   key key_id | acl_name | { address_match_list } )
Rob Austein's avatar
regen    
Rob Austein committed
511
512
513
514
</pre>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
515
<a name="id2573159"></a>Definition and Usage</h4></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
516
517
518
519
<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
520
521
            statements. The elements which constitute an address match
            list can be any of the following:
Rob Austein's avatar
regen    
Rob Austein committed
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
          </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
538
539
            "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
540
541
542
543
544
          </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
545
546
            Nonetheless, the term "address match list" is still used
            throughout the documentation.
Rob Austein's avatar
regen    
Rob Austein committed
547
548
549
          </p>
<p>
            When a given IP address or prefix is compared to an address
Mark Andrews's avatar
regen    
Mark Andrews committed
550
551
552
553
554
555
            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
556
            The interpretation of a match depends on whether the list is being
Automatic Updater's avatar
regen    
Automatic Updater committed
557
558
            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
559
560
          </p>
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
561
562
563
564
            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
565
566
            <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
567
            <span><strong class="command">allow-query</strong></span>,
Mark Andrews's avatar
regen    
Mark Andrews committed
568
            <span><strong class="command">allow-query-on</strong></span>,
Mark Andrews's avatar
regen    
Mark Andrews committed
569
            <span><strong class="command">allow-query-cache</strong></span>,
Mark Andrews's avatar
regen    
Mark Andrews committed
570
            <span><strong class="command">allow-query-cache-on</strong></span>,
Rob Austein's avatar
regen    
Rob Austein committed
571
            <span><strong class="command">allow-transfer</strong></span>,
Mark Andrews's avatar
regen    
Mark Andrews committed
572
            <span><strong class="command">allow-update</strong></span>,
Tinderbox User's avatar
Tinderbox User committed
573
574
575
            <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
576
            lists.  Similarly, the <span><strong class="command">listen-on</strong></span> option will cause the
Mark Andrews's avatar
regen    
Mark Andrews committed
577
            server to refuse queries on any of the machine's
Mark Andrews's avatar
regen    
Mark Andrews committed
578
            addresses which do not match the list.
Rob Austein's avatar
regen    
Rob Austein committed
579
580
          </p>
<p>
Automatic Updater's avatar
regen    
Automatic Updater committed
581
            Order of insertion is significant.  If more than one element
Mark Andrews's avatar
regen    
Mark Andrews committed
582
583
584
585
586
587
588
589
590
591
592
593
594
            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
595
596
597
598
599
          </p>
</div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
600
<a name="id2573300"></a>Comment Syntax</h3></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
601
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
602
          The <acronym class="acronym">BIND</acronym> 9 comment syntax allows for
Rob Austein's avatar
regen    
Rob Austein committed
603
          comments to appear
Mark Andrews's avatar
regen    
Mark Andrews committed
604
          anywhere that whitespace may appear in a <acronym class="acronym">BIND</acronym> configuration
Rob Austein's avatar
regen    
Rob Austein committed
605
606
607
608
609
          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
610
<a name="id2573383"></a>Syntax</h4></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
611
612
<p>
            </p>
Mark Andrews's avatar
regen    
Mark Andrews committed
613
<pre class="programlisting">/* This is a <acronym class="acronym">BIND</acronym> comment as in C */</pre>
Rob Austein's avatar
regen    
Rob Austein committed
614
615
<p>
            </p>
Mark Andrews's avatar
regen    
Mark Andrews committed
616
<pre class="programlisting">// This is a <acronym class="acronym">BIND</acronym> comment as in C++</pre>
Rob Austein's avatar
regen    
Rob Austein committed
617
618
<p>
            </p>
Automatic Updater's avatar
regen    
Automatic Updater committed
619
620
<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
621
622
623
624
625
<p>
          </p>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
626
<a name="id2573413"></a>Definition and Usage</h4></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
627
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
628
            Comments may appear anywhere that whitespace may appear in
Mark Andrews's avatar
regen    
Mark Andrews committed
629
            a <acronym class="acronym">BIND</acronym> configuration file.
Rob Austein's avatar
regen    
Rob Austein committed
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
          </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.
645
646
647
   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
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
</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
663
664
// is a new comment, even though it is logically
// part of the previous comment.
Rob Austein's avatar
regen    
Rob Austein committed
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
</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
680
681
# is a new comment, even though it is logically
# part of the previous comment.
Rob Austein's avatar
regen    
Rob Austein committed
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
</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
702
        A <acronym class="acronym">BIND</acronym> 9 configuration consists of
Rob Austein's avatar
regen    
Rob Austein committed
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
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
        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
779
                  also act as a light-weight resolver daemon (<span><strong class="command">lwresd</strong></span>).
Rob Austein's avatar
regen    
Rob Austein committed
780
781
782
783
784
785
786
787
788
789
                </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
790
                  inclusion in stub and slave zones'
Tinderbox User's avatar
Tinderbox User committed
791
                  <span><strong class="command">masters</strong></span> or
Automatic Updater's avatar
Automatic Updater committed
792
                  <span><strong class="command">also-notify</strong></span> lists.
Rob Austein's avatar
regen    
Rob Austein committed
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
                </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
808
<td>
Automatic Updater's avatar
regen    
Automatic Updater committed
809
                <p><span><strong class="command">server</strong></span></p>
Mark Andrews's avatar
regen    
Mark Andrews committed
810
811
812
              </td>
<td>
                <p>
Automatic Updater's avatar
regen    
Automatic Updater committed
813
814
                  sets certain configuration options on
                  a per-server basis.
Mark Andrews's avatar
regen    
Mark Andrews committed
815
816
817
818
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen    
Rob Austein committed
819
<td>
Automatic Updater's avatar
regen    
Automatic Updater committed
820
                <p><span><strong class="command">statistics-channels</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
821
822
823
              </td>
<td>
                <p>
Automatic Updater's avatar
regen    
Automatic Updater committed
824
825
                  declares communication channels to get access to
                  <span><strong class="command">named</strong></span> statistics.
Rob Austein's avatar
regen    
Rob Austein committed
826
827
828
829
830
831
832
833
834
835
836
837
838
839
                </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
840
841
842
843
844
845
846
847
848
849
850
<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
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
<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
880
<a name="id2574165"></a><span><strong class="command">acl</strong></span> Statement Grammar</h3></div></div></div>
Mark Andrews's avatar
gregen    
Mark Andrews committed
881
882
<pre class="programlisting"><span><strong class="command">acl</strong></span> acl-name {
    address_match_list
883
};
Rob Austein's avatar
regen    
Rob Austein committed
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
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
</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
931
932
933
                    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
934
935
936
937
938
939
940
941
942
943
944
                  </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
945
946
947
                    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
948
949
950
951
952
953
954
955
956
957
958
959
960
961
                    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
962
<a name="id2574423"></a><span><strong class="command">controls</strong></span> Statement Grammar</h3></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
963
<pre class="programlisting"><span><strong class="command">controls</strong></span> {
Automatic Updater's avatar
regen    
Automatic Updater committed
964
965
   [ inet ( ip_addr | * ) [ port ip_port ]
                allow { <em class="replaceable"><code> address_match_list </code></em> }
Mark Andrews's avatar
gregen    
Mark Andrews committed
966
967
                keys { <em class="replaceable"><code>key_list</code></em> }; ]
   [ inet ...; ]
Automatic Updater's avatar
regen    
Automatic Updater committed
968
969
   [ 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
970
   [ unix ...; ]
971
};
Rob Austein's avatar
regen    
Rob Austein committed
972
973
974
975
976
977
978
</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
979
          The <span><strong class="command">controls</strong></span> statement declares control
Rob Austein's avatar
regen    
Rob Austein committed
980
981
982
          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
983
          commands to and retrieve non-DNS results from a name server.
Rob Austein's avatar
regen    
Rob Austein committed
984
985
        </p>
<p>
Mark Andrews's avatar
gregen    
Mark Andrews committed
986
987
988
          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
989
          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
990
991
992
          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
993
          use an <span><strong class="command">ip_addr</strong></span> of <code class="literal">::</code>.
Mark Andrews's avatar
gregen    
Mark Andrews committed
994
          If you will only use <span><strong class="command">rndc</strong></span> on the local host,
Rob Austein's avatar
regen    
Rob Austein committed
995
          using the loopback address (<code class="literal">127.0.0.1</code>
Mark Andrews's avatar
gregen    
Mark Andrews committed
996
          or <code class="literal">::1</code>) is recommended for maximum security.
Rob Austein's avatar
regen    
Rob Austein committed
997
998
        </p>
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
999
          If no port is specified, port 953 is used. The asterisk
Mark Andrews's avatar
gregen    
Mark Andrews committed
1000
          "<code class="literal">*</code>" cannot be used for <span><strong class="command">ip_port</strong></span>.
Rob Austein's avatar
regen    
Rob Austein committed
1001
1002
1003
1004
        </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
1005
1006
1007
          <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
1008
1009
          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
1010
1011
1012
          are ignored.
        </p>
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
1013
          A <span><strong class="command">unix</strong></span> control channel is a UNIX domain
Mark Andrews's avatar
gregen    
Mark Andrews committed
1014
1015
1016
1017
1018
1019
          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
1020
1021
1022
1023
        </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
1024
1025
1026
1027
1028
          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
1029
1030
1031
1032
1033
1034
1035
        </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
1036
1037
          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
1038
1039
          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
1040
          was specified as when <acronym class="acronym">BIND</acronym> was built).
Rob Austein's avatar
regen    
Rob Austein committed
1041
1042
1043
1044
1045
          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
1046
          ease the transition of systems from <acronym class="acronym">BIND</acronym> 8,
Rob Austein's avatar
regen    
Rob Austein committed
1047
          which did not have digital signatures on its command channel
Mark Andrews's avatar
gregen    
Mark Andrews committed
1048
          messages and thus did not have a <span><strong class="command">keys</strong></span> clause.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1049

Mark Andrews's avatar
regen    
Mark Andrews committed
1050
1051
          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
1052
          and still have <span><strong class="command">rndc</strong></span> work the same way
Mark Andrews's avatar
gregen    
Mark Andrews committed
1053
          <span><strong class="command">ndc</strong></span> worked in BIND 8, simply by executing the
Rob Austein's avatar
regen    
Rob Austein committed
1054
1055
1056
1057
1058
1059
          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
1060
          <acronym class="acronym">BIND</acronym> 8 configuration files, this
Rob Austein's avatar
regen    
Rob Austein committed
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
          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
1072
1073
1074
          <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
1075
1076
1077
1078
          readable by a group
          that contains the users who should have access.
        </p>
<p>
Mark Andrews's avatar
gregen    
Mark Andrews committed
1079
1080
1081
          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
1082
1083
1084
1085
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1086
<a name="id2574782"></a><span><strong class="command">include</strong></span> Statement Grammar</h3></div></div></div>
Mark Andrews's avatar
regen    
Mark Andrews committed
1087
<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
1088
1089
1090
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1091
<a name="id2574800"></a><span><strong class="command">include</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
          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
1106
<a name="id2574891"></a><span><strong class="command">key</strong></span> Statement Grammar</h3></div></div></div>
Mark Andrews's avatar
regen    
Mark Andrews committed
1107
<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
1108
1109
    algorithm <em class="replaceable"><code>algorithm_id</code></em>;
    secret <em class="replaceable"><code>secret_string</code></em>;
1110
};
Rob Austein's avatar
regen    
Rob Austein committed
1111
1112
1113
1114
</pre>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1115
<a name="id2574915"></a><span><strong class="command">key</strong></span> Statement Definition and Usage</h3></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
<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
1147
1148
          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
1149
1150
1151
1152
          <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
1153
          number of required bits preceded by a dash, e.g.
Mark Andrews's avatar
regen    
Mark Andrews committed
1154
          <code class="literal">hmac-sha1-80</code>.  The
Rob Austein's avatar
regen    
Rob Austein committed
1155
          <em class="replaceable"><code>secret_string</code></em> is the secret
Mark Andrews's avatar
regen    
Mark Andrews committed
1156
1157
          to be used by the algorithm, and is treated as a base-64
          encoded string.
Rob Austein's avatar
regen    
Rob Austein committed
1158
1159
1160
1161
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1162
<a name="id2575009"></a><span><strong class="command">logging</strong></span> Statement Grammar</h3></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
1163
1164
<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
1165
     ( <span><strong class="command">file</strong></span> <em class="replaceable"><code>path_name</code></em>
Rob Austein's avatar
regen    
Rob Austein committed
1166
         [ <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
1167
         [ <span><strong class="command">size</strong></span> <em class="replaceable"><code>size_spec</code></em> ]
Rob Austein's avatar
regen    
Rob Austein committed
1168
1169
1170
1171
1172
1173
1174
1175
       | <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
1176
     [ <span><strong class="command">buffered</strong></span> <code class="option">yes</code> or <code class="option">no</code>; ]
1177
   }; ]
Rob Austein's avatar
regen    
Rob Austein committed
1178
1179
   [ <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> ; ... ]
1180
1181
1182
   }; ]
   ...
};
Rob Austein's avatar
regen    
Rob Austein committed
1183
1184
1185
1186
</pre>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1187
<a name="id2575144"></a><span><strong class="command">logging</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
          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
1204
1205
     category default { default_syslog; default_debug; };
     category unmatched { null; };
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1206
};
Rob Austein's avatar
regen    
Rob Austein committed
1207
</pre>
Tinderbox User's avatar
Tinderbox User committed
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
<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
1219
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
1220
          In <acronym class="acronym">BIND</acronym> 9, the logging configuration
Rob Austein's avatar
regen    
Rob Austein committed
1221
          is only established when
Mark Andrews's avatar
regen    
Mark Andrews committed
1222
          the entire configuration file has been parsed.  In <acronym class="acronym">BIND</acronym> 8, it was
Rob Austein's avatar
regen    
Rob Austein committed
1223
1224
1225
1226
          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
1227
          channels, or to standard error if the <code class="option">-g</code> option
Rob Austein's avatar
regen    
Rob Austein committed
1228
1229
1230
1231
          was specified.
        </p>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
1232
<a name="id2575209"></a>The <span><strong class="command">channel</strong></span> Phrase</h4></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
<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
1266
1267
1268
            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
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
            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 {
1305
1306
1307
1308
    file "example.log" versions 3 size 20m;
    print-time yes;
    print-category yes;
};
Rob Austein's avatar
regen    
Rob Austein committed
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
</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
1332
1333
1334
<p>
            On Windows machines syslog messages are directed to the EventViewer.
          </p>
Rob Austein's avatar
regen    
Rob Austein committed
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
<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
1374
            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
1375
1376
1377
1378
1379
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 {
1380
1381
1382
    file "foo";
    severity debug 3;
};
Rob Austein's avatar
regen    
Rob Austein committed
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
</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
1397
            pointless since <span><strong class="command">syslog</strong></span> also logs
Rob Austein's avatar
regen    
Rob Austein committed
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
            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
1412
1413
1414
1415
1416
<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
1417
1418
1419
<p>
            There are four predefined channels that are used for
            <span><strong class="command">named</strong></span>'s default logging as follows.
Tinderbox User's avatar
Tinderbox User committed
1420
1421
1422
            If <span><strong class="command">named</strong></span> is started with the
            <code class="option">-L</code> then a
            fifth channel <span><strong class="command">default_logfile</strong></span> is added.
Rob Austein's avatar
regen    
Rob Austein committed
1423
1424
1425
1426
            How they are
            used is described in <a href="Bv9ARM.ch06.html#the_category_phrase" title="The category Phrase">the section called &#8220;The <span><strong class="command">category</strong></span> Phrase&#8221;</a>.
          </p>
<pre class="programlisting">channel default_syslog {
Automatic Updater's avatar
regen    
Automatic Updater committed
1427
1428
1429
1430
    // send to syslog's daemon facility
    syslog daemon;
    // only send priority info and higher
    severity info;
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1431

Andreas Gustafsson's avatar
Andreas Gustafsson committed
1432
channel default_debug {
Automatic Updater's avatar
regen    
Automatic Updater committed
1433
1434
    // write to named.run in the working directory
    // Note: stderr is used instead of "named.run" if
Tinderbox User's avatar
Tinderbox User committed
1435
    // the server is started with the '-g' option.
Automatic Updater's avatar
regen    
Automatic Updater committed
1436
1437
1438
    file "named.run";
    // log at the server's current debug level
    severity dynamic;
1439
};
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1440

Andreas Gustafsson's avatar
Andreas Gustafsson committed
1441
channel default_stderr {
Automatic Updater's avatar
regen    
Automatic Updater committed
1442
1443
1444
1445
    // writes to stderr
    stderr;
    // only send priority info and higher
    severity info;
1446
};
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1447

Andreas Gustafsson's avatar
Andreas Gustafsson committed
1448
channel null {
Automatic Updater's avatar
regen    
Automatic Updater committed
1449
1450
   // toss anything sent to this channel
   null;
1451
};
Tinderbox User's avatar
Tinderbox User committed
1452
1453
1454
1455
1456
1457
1458
1459
1460

channel default_logfile {
    // this channel is only present if named is
    // started with the -L option, whose argument
    // provides the file name
    file "...";
    // log at the server's current debug level
    severity dynamic;
};
Rob Austein's avatar
regen    
Rob Austein committed
1461
1462
1463
1464
1465
1466
</pre>
<p>
            The <span><strong class="command">default_debug</strong></span> channel has the
            special
            property that it only produces output when the server's debug
            level is
Mark Andrews's avatar
regen    
Mark Andrews committed
1467
            nonzero.  It normally writes to a file called <code class="filename">named.run</code>
Rob Austein's avatar
regen    
Rob Austein committed
1468
1469
1470
            in the server's working directory.
          </p>
<p>
Tinderbox User's avatar
Tinderbox User committed
1471
            For security reasons, when the <code class="option">-u</code>
Rob Austein's avatar
regen    
Rob Austein committed
1472
1473
1474
1475
1476
            command line option is used, the <code class="filename">named.run</code> file
            is created only after <span><strong class="command">named</strong></span> has
            changed to the
            new UID, and any debug output generated while <span><strong class="command">named</strong></span> is
            starting up and still running as root is discarded.  If you need
Tinderbox User's avatar
Tinderbox User committed
1477
1478
1479
            to capture this output, you must run the server with the <code class="option">-L</code>
            option to specify a default logfile, or the <code class="option">-g</code>
            option to log to standard error which you can redirect to a file.
Rob Austein's avatar
regen    
Rob Austein committed
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
          </p>
<p>
            Once a channel is defined, it cannot be redefined. Thus you
            cannot alter the built-in channels directly, but you can modify
            the default logging by pointing categories at channels you have
            defined.
          </p>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="the_category_phrase"></a>The <span><strong class="command">category</strong></span> Phrase</h4></div></div></div>
<p>
            There are many categories, so you can send the logs you want
            to see wherever you want, without seeing logs you don't want. If
            you don't specify a list of channels for a category, then log
            messages
            in that category will be sent to the <span><strong class="command">default</strong></span> category
            instead. If you don't specify a default category, the following
            "default default" is used:
          </p>
<pre class="programlisting">category default { default_syslog; default_debug; };
</pre>
Tinderbox User's avatar
Tinderbox User committed
1502
1503
1504
1505
1506
1507
<p>
            If you start <span><strong class="command">named</strong></span> with the
            <code class="option">-L</code> option then the default category is:
          </p>
<pre class="programlisting">category default { default_logfile; default_debug; };
</pre>
Rob Austein's avatar
regen    
Rob Austein committed
1508
1509
1510
1511
1512
1513
<p>
            As an example, let's say you want to log security events to
            a file, but you also want keep the default logging behavior. You'd
            specify the following:
          </p>
<pre class="programlisting">channel my_security_channel {
1514
1515
1516
    file "my_security_file";
    severity info;
};
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1517
1518
1519
1520
category security {
    my_security_channel;
    default_syslog;
    default_debug;
Rob Austein's avatar
regen    
Rob Austein committed
1521
1522
1523
1524
1525
};</pre>
<p>
            To discard all messages in a category, specify the <span><strong class="command">null</strong></span> channel:
          </p>
<pre class="programlisting">category xfer-out { null; };
Andreas Gustafsson's avatar
Andreas Gustafsson committed
1526
category notify { null; };
Rob Austein's avatar
regen    
Rob Austein committed
1527
1528
1529
1530
</pre>
<p>
            Following are the available categories and brief descriptions
            of the types of log information they contain. More
Mark Andrews's avatar
regen    
Mark Andrews committed
1531
            categories may be added in future <acronym class="acronym">BIND</acronym> releases.
Rob Austein's avatar
regen    
Rob Austein committed
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
          </p>
<div class="informaltable"><table border="1">
<colgroup>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td>
                    <p><span><strong class="command">default</strong></span></p>
                  </td>
<td>
                    <p>
                      The default category defines the logging
                      options for those categories where no specific
                      configuration has been
                      defined.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">general</strong></span></p>
                  </td>
<td>
                    <p>
                      The catch-all. Many things still aren't
                      classified into categories, and they all end up here.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">database</strong></span></p>
                  </td>
<td>
                    <p>
                      Messages relating to the databases used
                      internally by the name server to store zone and cache
                      data.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">security</strong></span></p>
                  </td>
<td>
                    <p>
                      Approval and denial of requests.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">config</strong></span></p>
                  </td>
<td>
                    <p>
                      Configuration file parsing and processing.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">resolver</strong></span></p>
                  </td>
<td>
                    <p>
                      DNS resolution, such as the recursive
                      lookups performed on behalf of clients by a caching name
                      server.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">xfer-in</strong></span></p>
                  </td>
<td>
                    <p>
                      Zone transfers the server is receiving.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">xfer-out</strong></span></p>
                  </td>
<td>
                    <p>
                      Zone transfers the server is sending.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">notify</strong></span></p>
                  </td>
<td>
                    <p>
                      The NOTIFY protocol.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">client</strong></span></p>
                  </td>
<td>
                    <p>
                      Processing of client requests.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">unmatched</strong></span></p>
                  </td>
<td>
                    <p>
Automatic Updater's avatar
regen    
Automatic Updater committed
1653
                      Messages that <span><strong class="command">named</strong></span> was unable to determine the
Rob Austein's avatar
regen    
Rob Austein committed
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
                      class of or for which there was no matching <span><strong class="command">view</strong></span>.
                      A one line summary is also logged to the <span><strong class="command">client</strong></span> category.
                      This category is best sent to a file or stderr, by
                      default it is sent to
                      the <span><strong class="command">null</strong></span> channel.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">network</strong></span></p>
                  </td>
<td>
                    <p>
                      Network operations.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">update</strong></span></p>
                  </td>
<td>
                    <p>
                      Dynamic updates.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">update-security</strong></span></p>
                  </td>
<td>
                    <p>
                      Approval and denial of update requests.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">queries</strong></span></p>
                  </td>
<td>
                    <p>
                      Specify where queries should be logged to.
                    </p>
                    <p>
Mark Andrews's avatar
regen    
Mark Andrews committed
1701
                      At startup, specifying the category <span><strong class="command">queries</strong></span> will also
Rob Austein's avatar
regen    
Rob Austein committed
1702
1703
1704
                      enable query logging unless <span><strong class="command">querylog</strong></span> option has been
                      specified.
                    </p>
Mark Andrews's avatar
regen    
Mark Andrews committed
1705

Rob Austein's avatar
regen    
Rob Austein committed
1706
                    <p>
Mark Andrews's avatar
regen    
Mark Andrews committed
1707
                      The query log entry reports the client's IP
Mark Andrews's avatar
regen    
Mark Andrews committed
1708
                      address and port number, and the query name,
Automatic Updater's avatar
regen    
Automatic Updater committed
1709
                      class and type.  Next it reports whether the
Mark Andrews's avatar
regen    
Mark Andrews committed
1710
1711
                      Recursion Desired flag was set (+ if set, -
                      if not set), if the query was signed (S),
Tinderbox User's avatar
Tinderbox User committed
1712
1713
                      EDNS was in used along with the EDNS version
                      number (E(#)), if TCP was used (T), if DO
Tinderbox User's avatar
Tinderbox User committed
1714
1715
                      (DNSSEC Ok) was set (D), if CD (Checking
                      Disabled) was set (C), if a valid DNS Server
Tinderbox User's avatar
Tinderbox User committed
1716
                      COOKIE was received (V), or if a DNS COOKIE
Tinderbox User's avatar
Tinderbox User committed
1717
1718
1719
                      option without a valid Server COOKIE was
                      present (K).  After this the destination
                      address the query was sent to is reported.
Rob Austein's avatar
regen    
Rob Austein committed
1720
                    </p>
Mark Andrews's avatar
regen    
Mark Andrews committed
1721

Rob Austein's avatar
regen    
Rob Austein committed
1722
                    <p>
Automatic Updater's avatar
Automatic Updater committed
1723
                      <code class="computeroutput">client 127.0.0.1#62536 (www.example.com): query: www.example.com IN AAAA +SE</code>
Rob Austein's avatar
regen    
Rob Austein committed
1724
1725
                    </p>
                    <p>
Automatic Updater's avatar
Automatic Updater committed
1726
1727
1728
1729
1730
1731
1732
                      <code class="computeroutput">client ::1#62537 (www.example.net): query: www.example.net IN AAAA -SE</code>
                    </p>
                    <p>
                      (The first part of this log message, showing the
                      client address/port number and query name, is
                      repeated in all subsequent log messages related
                      to the same query.)
Rob Austein's avatar
regen    
Rob Austein committed
1733
1734
1735
1736
                    </p>
                  </td>
</tr>
<tr>
Automatic Updater's avatar
regen    
Automatic Updater committed
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
<td>
                    <p><span><strong class="command">query-errors</strong></span></p>
                  </td>
<td>
                    <p>
                      Information about queries that resulted in some
                      failure.
                    </p>
                  </td>
</tr>
<tr>
Rob Austein's avatar
regen    
Rob Austein committed
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
<td>
                    <p><span><strong class="command">dispatch</strong></span></p>
                  </td>
<td>
                    <p>
                      Dispatching of incoming packets to the
                      server modules where they are to be processed.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">dnssec</strong></span></p>
                  </td>
<td>
                    <p>
                      DNSSEC and TSIG protocol processing.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">lame-servers</strong></span></p>
                  </td>
<td>
                    <p>
                      Lame servers.  These are misconfigurations
                      in remote servers, discovered by BIND 9 when trying to
Automatic Updater's avatar
regen    
Automatic Updater committed
1776
                      query those servers during resolution.
Rob Austein's avatar
regen    
Rob Austein committed
1777
1778
1779
1780
1781
1782
1783
1784
1785
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p><span><strong class="command">delegation-only</strong></span></p>
                  </td>
<td>
                    <p>
Automatic Updater's avatar
regen    
Automatic Updater committed
1786
1787
1788
                      Delegation only.  Logs queries that have been
                      forced to NXDOMAIN as the result of a
                      delegation-only zone or a
Tinderbox User's avatar
Tinderbox User committed
1789
1790
                      <span><strong class="command">delegation-only</strong></span> in a
                      forward, hint or stub zone declaration.
Rob Austein's avatar
regen    
Rob Austein committed
1791
1792
1793
                    </p>
                  </td>
</tr>
Mark Andrews's avatar
regen    
Mark Andrews committed
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
<tr>
<td>
                    <p><span><strong class="command">edns-disabled</strong></span></p>
                  </td>
<td>
                    <p>
                      Log queries that have been forced to use plain
                      DNS due to timeouts.  This is often due to
                      the remote servers not being RFC 1034 compliant
                      (not always returning FORMERR or similar to
Mark Andrews's avatar
regen    
Mark Andrews committed
1804
1805
                      EDNS queries and other extensions to the DNS
                      when they are not understood).  In other words, this is
Mark Andrews's avatar
regen    
Mark Andrews committed
1806
1807
1808
1809
                      targeted at servers that fail to respond to
                      DNS queries that they don't understand.
                    </p>
                    <p>
Mark Andrews's avatar
regen    
Mark Andrews committed
1810
                      Note: the log message can also be due to
Mark Andrews's avatar
regen    
Mark Andrews committed
1811
                      packet loss.  Before reporting servers for
Mark Andrews's avatar
regen    
Mark Andrews committed
1812
1813
1814
1815
                      non-RFC 1034 compliance they should be re-tested
                      to determine the nature of the non-compliance.
                      This testing should prevent or reduce the
                      number of false-positive reports.
Mark Andrews's avatar
regen    
Mark Andrews committed
1816
1817
                    </p>
                    <p>
Automatic Updater's avatar
regen    
Automatic Updater committed
1818
                      Note: eventually <span><strong class="command">named</strong></span> will have to stop
Mark Andrews's avatar
regen    
Mark Andrews committed
1819
1820
                      treating such timeouts as due to RFC 1034 non
                      compliance and start treating it as plain
Mark Andrews's avatar
regen    
Mark Andrews committed
1821
                      packet loss.  Falsely classifying packet
Mark Andrews's avatar
regen    
Mark Andrews committed
1822
                      loss as due to RFC 1034 non compliance impacts
Mark Andrews's avatar
regen    
Mark Andrews committed
1823
1824
                      on DNSSEC validation which requires EDNS for
                      the DNSSEC records to be returned.
Mark Andrews's avatar
regen    
Mark Andrews committed
1825
1826
1827
                    </p>
                  </td>
</tr>
Automatic Updater's avatar
Automatic Updater committed
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840