Bv9ARM.ch06.html 651 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
17
18
19
20
 - 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.
-->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 6. BIND 9 Configuration Reference</title>
Tinderbox User's avatar
Tinderbox User committed
21
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
Evan Hunt's avatar
Evan Hunt committed
22
<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
Rob Austein's avatar
regen    
Rob Austein committed
23
24
25
26
27
28
29
<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
30
<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
31
32
33
34
35
36
37
38
39
40
<tr>
<td width="20%" align="left">
<a accesskey="p" href="Bv9ARM.ch05.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch07.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
Tinderbox User's avatar
Tinderbox User committed
41
42
43
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="Bv9ARM.ch06"></a>Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</h1></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
44
45
<div class="toc">
<p><b>Table of Contents</b></p>
Tinderbox User's avatar
Tinderbox User committed
46
<dl class="toc">
Evan Hunt's avatar
Evan Hunt committed
47
<dt><span class="section"><a href="Bv9ARM.ch06.html#configuration_file_elements">Configuration File Elements</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
48
<dd><dl>
Evan Hunt's avatar
Evan Hunt committed
49
<dt><span class="section"><a href="Bv9ARM.ch06.html#address_match_lists">Address Match Lists</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
50
<dt><span class="section"><a href="Bv9ARM.ch06.html#comment_syntax">Comment Syntax</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
51
</dl></dd>
Evan Hunt's avatar
Evan Hunt committed
52
<dt><span class="section"><a href="Bv9ARM.ch06.html#Configuration_File_Grammar">Configuration File Grammar</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
53
<dd><dl>
Tinderbox User's avatar
Tinderbox User committed
54
<dt><span class="section"><a href="Bv9ARM.ch06.html#acl_grammar"><span class="command"><strong>acl</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
55
<dt><span class="section"><a href="Bv9ARM.ch06.html#acl"><span class="command"><strong>acl</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
56
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
57
<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_grammar"><span class="command"><strong>controls</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
58
<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage"><span class="command"><strong>controls</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
59
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
60
61
62
63
64
65
66
67
68
69
<dt><span class="section"><a href="Bv9ARM.ch06.html#include_grammar"><span class="command"><strong>include</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#include_statement"><span class="command"><strong>include</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#key_grammar"><span class="command"><strong>key</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#key_statement"><span class="command"><strong>key</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_grammar"><span class="command"><strong>logging</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_statement"><span class="command"><strong>logging</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_grammar"><span class="command"><strong>lwres</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_statement"><span class="command"><strong>lwres</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_grammar"><span class="command"><strong>masters</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_statement"><span class="command"><strong>masters</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
70
          Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
71
<dt><span class="section"><a href="Bv9ARM.ch06.html#options_grammar"><span class="command"><strong>options</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
72
<dt><span class="section"><a href="Bv9ARM.ch06.html#options"><span class="command"><strong>options</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
73
          Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
74
75
<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_grammar"><span class="command"><strong>server</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_definition_and_usage"><span class="command"><strong>server</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
76
            Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
77
<dt><span class="section"><a href="Bv9ARM.ch06.html#statschannels"><span class="command"><strong>statistics-channels</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
78
<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_channels"><span class="command"><strong>statistics-channels</strong></span> Statement Definition and
Automatic Updater's avatar
regen    
Automatic Updater committed
79
            Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
80
<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted-keys"><span class="command"><strong>trusted-keys</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
81
<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted_keys"><span class="command"><strong>trusted-keys</strong></span> Statement Definition
Automatic Updater's avatar
regen    
Automatic Updater committed
82
            and Usage</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
83
<dt><span class="section"><a href="Bv9ARM.ch06.html#managed_keys"><span class="command"><strong>managed-keys</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
84
<dt><span class="section"><a href="Bv9ARM.ch06.html#managed-keys"><span class="command"><strong>managed-keys</strong></span> Statement Definition
Rob Austein's avatar
regen    
Rob Austein committed
85
            and Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
86
<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement_grammar"><span class="command"><strong>view</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
87
<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement"><span class="command"><strong>view</strong></span> Statement Definition and Usage</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
88
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement_grammar"><span class="command"><strong>zone</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
89
            Statement Grammar</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
90
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement"><span class="command"><strong>zone</strong></span> Statement Definition and Usage</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
91
</dl></dd>
Tinderbox User's avatar
Tinderbox User committed
92
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_file">Zone File</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
93
<dd><dl>
Evan Hunt's avatar
Evan Hunt committed
94
<dt><span class="section"><a href="Bv9ARM.ch06.html#types_of_resource_records_and_when_to_use_them">Types of Resource Records and When to Use Them</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
95
<dt><span class="section"><a href="Bv9ARM.ch06.html#mx_records">Discussion of MX Records</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
96
<dt><span class="section"><a href="Bv9ARM.ch06.html#Setting_TTLs">Setting TTLs</a></span></dt>
Tinderbox User's avatar
Tinderbox User committed
97
98
99
<dt><span class="section"><a href="Bv9ARM.ch06.html#ipv4_reverse">Inverse Mapping in IPv4</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_directives">Other Zone File Directives</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#generate_directive"><acronym class="acronym">BIND</acronym> Master File Extension: the  <span class="command"><strong>$GENERATE</strong></span> Directive</a></span></dt>
Evan Hunt's avatar
Evan Hunt committed
100
101
102
103
104
105
<dt><span class="section"><a href="Bv9ARM.ch06.html#zonefile_format">Additional File Formats</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics">BIND9 Statistics</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="Bv9ARM.ch06.html#statsfile">The Statistics File</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_counters">Statistics Counters</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
106
107
108
</dl></dd>
</dl>
</div>
Tinderbox User's avatar
Tinderbox User committed
109
<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
    </p>
Tinderbox User's avatar
Tinderbox User committed
119
<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
      converted to the new format
      using the shell script
      <code class="filename">contrib/named-bootconf/named-bootconf.sh</code>.
    </p>
Tinderbox User's avatar
Tinderbox User committed
125
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
126
127
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="configuration_file_elements"></a>Configuration File Elements</h2></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
128
<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
        file documentation:
      </p>
Tinderbox User's avatar
Tinderbox User committed
132
<div class="informaltable"><table border="1">
Rob Austein's avatar
regen    
Rob Austein committed
133
<colgroup>
Evan Hunt's avatar
Evan Hunt committed
134
135
<col width="1.855in" class="1">
<col width="3.770in" class="2">
Rob Austein's avatar
regen    
Rob Austein committed
136
137
138
139
140
141
142
143
144
145
146
</colgroup>
<tbody>
<tr>
<td>
                <p>
                  <code class="varname">acl_name</code>
                </p>
              </td>
<td>
                <p>
                  The name of an <code class="varname">address_match_list</code> as
Evan Hunt's avatar
Evan Hunt committed
147
                  defined by the <span class="command"><strong>acl</strong></span> statement.
Rob Austein's avatar
regen    
Rob Austein committed
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">address_match_list</code>
                </p>
              </td>
<td>
                <p>
                  A list of one or more
                  <code class="varname">ip_addr</code>,
                  <code class="varname">ip_prefix</code>, <code class="varname">key_id</code>,
                  or <code class="varname">acl_name</code> elements, see
Evan Hunt's avatar
Evan Hunt committed
163
                  <a class="xref" href="Bv9ARM.ch06.html#address_match_lists" title="Address Match Lists">the section called &#8220;Address Match Lists&#8221;</a>.
Rob Austein's avatar
regen    
Rob Austein committed
164
165
166
167
                </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
<td>
                <p>
                  <code class="varname">dotted_decimal</code>
                </p>
              </td>
<td>
                <p>
                  One to four integers valued 0 through
Evan Hunt's avatar
Evan Hunt committed
218
219
                  255 separated by dots (`.'), such as <span class="command"><strong>123</strong></span>,
                  <span class="command"><strong>45.67</strong></span> or <span class="command"><strong>89.123.45.67</strong></span>.
Rob Austein's avatar
regen    
Rob Austein committed
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">ip4_addr</code>
                </p>
              </td>
<td>
                <p>
                  An IPv4 address with exactly four elements
                  in <code class="varname">dotted_decimal</code> notation.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">ip6_addr</code>
                </p>
              </td>
<td>
                <p>
Evan Hunt's avatar
Evan Hunt committed
244
                  An IPv6 address, such as <span class="command"><strong>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
                  interfaces and links.  For example, a link-local
Evan Hunt's avatar
Evan Hunt committed
256
257
258
                  address <span class="command"><strong>fe80::1</strong></span> on the link
                  attached to the interface <span class="command"><strong>ne0</strong></span>
                  can be specified as <span class="command"><strong>fe80::1%ne0</strong></span>.
Mark Andrews's avatar
regen    
Mark Andrews committed
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
                  placeholder to
                  select a random high-numbered port.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">ip_prefix</code>
                </p>
              </td>
<td>
                <p>
                  An IP network specified as an <code class="varname">ip_addr</code>,
                  followed by a slash (`/') and then the number of bits in the
                  netmask.
                  Trailing zeros in a <code class="varname">ip_addr</code>
                  may omitted.
Evan Hunt's avatar
Evan Hunt committed
324
325
326
327
                  For example, <span class="command"><strong>127/8</strong></span> is the
                  network <span class="command"><strong>127.0.0.0</strong></span> with
                  netmask <span class="command"><strong>255.0.0.0</strong></span> and <span class="command"><strong>1.2.3.0/28</strong></span> is
                  network <span class="command"><strong>1.2.3.0</strong></span> with netmask <span class="command"><strong>255.255.255.240</strong></span>.
Rob Austein's avatar
regen    
Rob Austein committed
328
                </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
                  certain parameters
Evan Hunt's avatar
Evan Hunt committed
435
                  (such as <span class="command"><strong>max-journal-size</strong></span>) may
Tinderbox User's avatar
Tinderbox User committed
436
437
438
439
                  use a more limited range within these extremes.
                  In most cases, setting a value to 0 does not
                  literally mean zero; it means "undefined" or
                  "as big as possible", depending on the context.
Tinderbox User's avatar
Tinderbox User committed
440
                  See the explanations of particular parameters
Tinderbox User's avatar
Tinderbox User committed
441
                  that use <code class="varname">size_spec</code>
Tinderbox User's avatar
Tinderbox User committed
442
                  for details on how they interpret its use.
Rob Austein's avatar
regen    
Rob Austein committed
443
444
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
445
446
                  Numeric values can optionally be followed by a
                  scaling factor:
Mark Andrews's avatar
gregen    
Mark Andrews committed
447
448
449
450
                  <strong class="userinput"><code>K</code></strong> or <strong class="userinput"><code>k</code></strong>
                  for kilobytes,
                  <strong class="userinput"><code>M</code></strong> or <strong class="userinput"><code>m</code></strong>
                  for megabytes, and
Tinderbox User's avatar
Tinderbox User committed
451
452
453
                  <strong class="userinput"><code>G</code></strong> or <strong class="userinput"><code>g</code></strong>
                  for gigabytes, which scale by 1024, 1024*1024, and
                  1024*1024*1024 respectively.
Rob Austein's avatar
regen    
Rob Austein committed
454
455
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
456
                  <code class="varname">unlimited</code> generally means
Tinderbox User's avatar
Tinderbox User committed
457
458
                  "as big as possible", and is usually the best
                  way to safely set a very large number.
Tinderbox User's avatar
Tinderbox User committed
459
460
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
461
                  <code class="varname">default</code>
Tinderbox User's avatar
Tinderbox User committed
462
                  uses the limit that was in force when the server was started.
Rob Austein's avatar
regen    
Rob Austein committed
463
464
465
466
                </p>
              </td>
</tr>
<tr>
Tinderbox User's avatar
Tinderbox User committed
467
468
469
470
471
472
473
474
475
476
477
<td>
                <p>
                  <code class="varname">size_or_percent</code>
                </p>
              </td>
<td>
                <p>
                  <code class="varname">size_spec</code> or integer value
                  followed by '%' to represent percents.
                </p>
                <p>
Tinderbox User's avatar
Tinderbox User committed
478
                  The behavior is exactly the same as
Tinderbox User's avatar
Tinderbox User committed
479
480
481
482
483
484
485
486
                  <code class="varname">size_spec</code>, but
                  <code class="varname">size_or_percent</code> allows also
                  to specify a positive integer value followed by
                  '%' sign to represent percents.
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen    
Rob Austein committed
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
<td>
                <p>
                  <code class="varname">yes_or_no</code>
                </p>
              </td>
<td>
                <p>
                  Either <strong class="userinput"><code>yes</code></strong> or <strong class="userinput"><code>no</code></strong>.
                  The words <strong class="userinput"><code>true</code></strong> and <strong class="userinput"><code>false</code></strong> are
                  also accepted, as are the numbers <strong class="userinput"><code>1</code></strong>
                  and <strong class="userinput"><code>0</code></strong>.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <code class="varname">dialup_option</code>
                </p>
              </td>
<td>
                <p>
                  One of <strong class="userinput"><code>yes</code></strong>,
                  <strong class="userinput"><code>no</code></strong>, <strong class="userinput"><code>notify</code></strong>,
                  <strong class="userinput"><code>notify-passive</code></strong>, <strong class="userinput"><code>refresh</code></strong> or
                  <strong class="userinput"><code>passive</code></strong>.
                  When used in a zone, <strong class="userinput"><code>notify-passive</code></strong>,
                  <strong class="userinput"><code>refresh</code></strong>, and <strong class="userinput"><code>passive</code></strong>
                  are restricted to slave and stub zones.
                </p>
              </td>
</tr>
</tbody>
Tinderbox User's avatar
Tinderbox User committed
520
521
</table></div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
522
523
<div class="titlepage"><div><div><h3 class="title">
<a name="address_match_lists"></a>Address Match Lists</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
524
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
525
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
526
<a name="id-1.7.4.4.2"></a>Syntax</h4></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
527
528
529
<pre class="programlisting"><code class="varname">address_match_list</code> = address_match_list_element ;
  [<span class="optional"> address_match_list_element; ... </span>]
<code class="varname">address_match_list_element</code> = [<span class="optional"> ! </span>] (ip_address [<span class="optional">/length</span>] |
530
   key key_id | acl_name | { address_match_list } )
Rob Austein's avatar
regen    
Rob Austein committed
531
</pre>
Tinderbox User's avatar
Tinderbox User committed
532
533
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
534
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
535
536
<a name="id-1.7.4.4.3"></a>Definition and Usage</h4></div></div></div>
<p>
Rob Austein's avatar
regen    
Rob Austein committed
537
538
            Address match lists are primarily used to determine access
            control for various server operations. They are also used in
Evan Hunt's avatar
Evan Hunt committed
539
            the <span class="command"><strong>listen-on</strong></span> and <span class="command"><strong>sortlist</strong></span>
Mark Andrews's avatar
regen    
Mark Andrews committed
540
541
            statements. The elements which constitute an address match
            list can be any of the following:
Rob Austein's avatar
regen    
Rob Austein committed
542
          </p>
Tinderbox User's avatar
Tinderbox User committed
543
544
545
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">an IP address (IPv4 or IPv6)</li>
<li class="listitem">an IP prefix (in `/' notation)</li>
Evan Hunt's avatar
Evan Hunt committed
546
547
<li class="listitem">
                a key ID, as defined by the <span class="command"><strong>key</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
548
                statement
Tinderbox User's avatar
Tinderbox User committed
549
550
              </li>
<li class="listitem">the name of an address match list defined with
Evan Hunt's avatar
Evan Hunt committed
551
                the <span class="command"><strong>acl</strong></span> statement
Tinderbox User's avatar
Tinderbox User committed
552
553
              </li>
<li class="listitem">a nested address match list enclosed in braces</li>
Rob Austein's avatar
regen    
Rob Austein committed
554
</ul></div>
Tinderbox User's avatar
Tinderbox User committed
555
<p>
Rob Austein's avatar
regen    
Rob Austein committed
556
557
            Elements can be negated with a leading exclamation mark (`!'),
            and the match list names "any", "none", "localhost", and
Mark Andrews's avatar
regen    
Mark Andrews committed
558
559
            "localnets" are predefined. More information on those names
            can be found in the description of the acl statement.
Rob Austein's avatar
regen    
Rob Austein committed
560
          </p>
Tinderbox User's avatar
Tinderbox User committed
561
<p>
Rob Austein's avatar
regen    
Rob Austein committed
562
563
564
            The addition of the key clause made the name of this syntactic
            element something of a misnomer, since security keys can be used
            to validate access without regard to a host or network address.
Mark Andrews's avatar
regen    
Mark Andrews committed
565
566
            Nonetheless, the term "address match list" is still used
            throughout the documentation.
Rob Austein's avatar
regen    
Rob Austein committed
567
          </p>
Tinderbox User's avatar
Tinderbox User committed
568
<p>
Rob Austein's avatar
regen    
Rob Austein committed
569
            When a given IP address or prefix is compared to an address
Mark Andrews's avatar
regen    
Mark Andrews committed
570
571
572
573
574
            match list, the comparison takes place in approximately O(1)
            time.  However, key comparisons require that the list of keys
            be traversed until a matching key is found, and therefore may
            be somewhat slower.
          </p>
Tinderbox User's avatar
Tinderbox User committed
575
<p>
Rob Austein's avatar
regen    
Rob Austein committed
576
            The interpretation of a match depends on whether the list is being
Evan Hunt's avatar
Evan Hunt committed
577
578
            used for access control, defining <span class="command"><strong>listen-on</strong></span> ports, or in a
            <span class="command"><strong>sortlist</strong></span>, and whether the element was negated.
Rob Austein's avatar
regen    
Rob Austein committed
579
          </p>
Tinderbox User's avatar
Tinderbox User committed
580
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
581
582
583
            When used as an access control list, a non-negated match
            allows access and a negated match denies access. If
            there is no match, access is denied. The clauses
Evan Hunt's avatar
Evan Hunt committed
584
585
586
587
588
589
590
591
592
593
594
595
596
            <span class="command"><strong>allow-notify</strong></span>,
            <span class="command"><strong>allow-recursion</strong></span>,
            <span class="command"><strong>allow-recursion-on</strong></span>,
            <span class="command"><strong>allow-query</strong></span>,
            <span class="command"><strong>allow-query-on</strong></span>,
            <span class="command"><strong>allow-query-cache</strong></span>,
            <span class="command"><strong>allow-query-cache-on</strong></span>,
            <span class="command"><strong>allow-transfer</strong></span>,
            <span class="command"><strong>allow-update</strong></span>,
            <span class="command"><strong>allow-update-forwarding</strong></span>,
            <span class="command"><strong>blackhole</strong></span>, and
            <span class="command"><strong>keep-response-order</strong></span> all use address match
            lists.  Similarly, the <span class="command"><strong>listen-on</strong></span> option will cause the
Mark Andrews's avatar
regen    
Mark Andrews committed
597
            server to refuse queries on any of the machine's
Mark Andrews's avatar
regen    
Mark Andrews committed
598
            addresses which do not match the list.
Rob Austein's avatar
regen    
Rob Austein committed
599
          </p>
Tinderbox User's avatar
Tinderbox User committed
600
<p>
Automatic Updater's avatar
regen    
Automatic Updater committed
601
            Order of insertion is significant.  If more than one element
Mark Andrews's avatar
regen    
Mark Andrews committed
602
603
604
605
606
607
608
            in an ACL is found to match a given IP address or prefix,
            preference will be given to the one that came
            <span class="emphasis"><em>first</em></span> in the ACL definition.
            Because of this first-match behavior, an element that
            defines a subset of another element in the list should
            come before the broader element, regardless of whether
            either is negated. For example, in
Evan Hunt's avatar
Evan Hunt committed
609
            <span class="command"><strong>1.2.3/24; ! 1.2.3.13;</strong></span>
Mark Andrews's avatar
regen    
Mark Andrews committed
610
611
            the 1.2.3.13 element is completely useless because the
            algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24
Evan Hunt's avatar
Evan Hunt committed
612
            element.  Using <span class="command"><strong>! 1.2.3.13; 1.2.3/24</strong></span> fixes
Mark Andrews's avatar
regen    
Mark Andrews committed
613
614
            that problem by having 1.2.3.13 blocked by the negation, but
            all other 1.2.3.* hosts fall through.
Rob Austein's avatar
regen    
Rob Austein committed
615
          </p>
Tinderbox User's avatar
Tinderbox User committed
616
617
618
</div>
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
619
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
620
<a name="comment_syntax"></a>Comment Syntax</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
621
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
622
          The <acronym class="acronym">BIND</acronym> 9 comment syntax allows for
Rob Austein's avatar
regen    
Rob Austein committed
623
          comments to appear
Mark Andrews's avatar
regen    
Mark Andrews committed
624
          anywhere that whitespace may appear in a <acronym class="acronym">BIND</acronym> configuration
Rob Austein's avatar
regen    
Rob Austein committed
625
626
627
          file. To appeal to programmers of all kinds, they can be written
          in the C, C++, or shell/perl style.
        </p>
Tinderbox User's avatar
Tinderbox User committed
628
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
629
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
630
631
<a name="id-1.7.4.5.3"></a>Syntax</h4></div></div></div>
<p>
Rob Austein's avatar
regen    
Rob Austein committed
632
            </p>
Mark Andrews's avatar
regen    
Mark Andrews committed
633
<pre class="programlisting">/* This is a <acronym class="acronym">BIND</acronym> comment as in C */</pre>
Rob Austein's avatar
regen    
Rob Austein committed
634
635
<p>
            </p>
Mark Andrews's avatar
regen    
Mark Andrews committed
636
<pre class="programlisting">// This is a <acronym class="acronym">BIND</acronym> comment as in C++</pre>
Rob Austein's avatar
regen    
Rob Austein committed
637
638
<p>
            </p>
Automatic Updater's avatar
regen    
Automatic Updater committed
639
640
<pre class="programlisting"># This is a <acronym class="acronym">BIND</acronym> comment as in common UNIX shells
# and perl</pre>
Rob Austein's avatar
regen    
Rob Austein committed
641
642
<p>
          </p>
Tinderbox User's avatar
Tinderbox User committed
643
644
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
645
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
Tinderbox User committed
646
647
<a name="id-1.7.4.5.4"></a>Definition and Usage</h4></div></div></div>
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
648
            Comments may appear anywhere that whitespace may appear in
Mark Andrews's avatar
regen    
Mark Andrews committed
649
            a <acronym class="acronym">BIND</acronym> configuration file.
Rob Austein's avatar
regen    
Rob Austein committed
650
          </p>
Tinderbox User's avatar
Tinderbox User committed
651
<p>
Rob Austein's avatar
regen    
Rob Austein committed
652
653
654
655
656
            C-style comments start with the two characters /* (slash,
            star) and end with */ (star, slash). Because they are completely
            delimited with these characters, they can be used to comment only
            a portion of a line or to span multiple lines.
          </p>
Tinderbox User's avatar
Tinderbox User committed
657
<p>
Rob Austein's avatar
regen    
Rob Austein committed
658
659
660
            C-style comments cannot be nested. For example, the following
            is not valid because the entire comment ends with the first */:
          </p>
Tinderbox User's avatar
Tinderbox User committed
661
<p>
Rob Austein's avatar
regen    
Rob Austein committed
662
663
664

</p>
<pre class="programlisting">/* This is the start of a comment.
665
666
667
   This is still part of the comment.
/* This is an incorrect attempt at nesting a comment. */
   This is no longer in any comment. */
Rob Austein's avatar
regen    
Rob Austein committed
668
669
670
671
</pre>
<p>

          </p>
Tinderbox User's avatar
Tinderbox User committed
672
<p>
Rob Austein's avatar
regen    
Rob Austein committed
673
674
675
676
677
678
            C++-style comments start with the two characters // (slash,
            slash) and continue to the end of the physical line. They cannot
            be continued across multiple physical lines; to have one logical
            comment span multiple lines, each line must use the // pair.
            For example:
          </p>
Tinderbox User's avatar
Tinderbox User committed
679
<p>
Rob Austein's avatar
regen    
Rob Austein committed
680
681
682

</p>
<pre class="programlisting">// This is the start of a comment.  The next line
683
684
// is a new comment, even though it is logically
// part of the previous comment.
Rob Austein's avatar
regen    
Rob Austein committed
685
686
687
688
</pre>
<p>

          </p>
Tinderbox User's avatar
Tinderbox User committed
689
<p>
Rob Austein's avatar
regen    
Rob Austein committed
690
691
692
693
694
695
            Shell-style (or perl-style, if you prefer) comments start
            with the character <code class="literal">#</code> (number sign)
            and continue to the end of the
            physical line, as in C++ comments.
            For example:
          </p>
Tinderbox User's avatar
Tinderbox User committed
696
<p>
Rob Austein's avatar
regen    
Rob Austein committed
697
698
699

</p>
<pre class="programlisting"># This is the start of a comment.  The next line
700
701
# is a new comment, even though it is logically
# part of the previous comment.
Rob Austein's avatar
regen    
Rob Austein committed
702
703
704
705
</pre>
<p>

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

Mark Andrews's avatar
regen    
Mark Andrews committed
1082
1083
          It makes it possible to use an existing <acronym class="acronym">BIND</acronym> 8
          configuration file in <acronym class="acronym">BIND</acronym> 9 unchanged,
Evan Hunt's avatar
Evan Hunt committed
1084
1085
          and still have <span class="command"><strong>rndc</strong></span> work the same way
          <span class="command"><strong>ndc</strong></span> worked in BIND 8, simply by executing the
Rob Austein's avatar
regen    
Rob Austein committed
1086
1087
1088
          command <strong class="userinput"><code>rndc-confgen -a</code></strong> after BIND 9 is
          installed.
        </p>
Tinderbox User's avatar
Tinderbox User committed
1089
<p>
Rob Austein's avatar
regen    
Rob Austein committed
1090
1091
          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
1092
          <acronym class="acronym">BIND</acronym> 8 configuration files, this
Rob Austein's avatar
regen    
Rob Austein committed
1093
1094
1095
1096
1097
1098
1099
1100
          feature does not
          have a high degree of configurability.  You cannot easily change
          the key name or the size of the secret, so you should make a
          <code class="filename">rndc.conf</code> with your own key if you
          wish to change
          those things.  The <code class="filename">rndc.key</code> file
          also has its
          permissions set such that only the owner of the file (the user that
Evan Hunt's avatar
Evan Hunt committed
1101
          <span class="command"><strong>named</strong></span> is running as) can access it.
Rob Austein's avatar
regen    
Rob Austein committed
1102
1103
          If you
          desire greater flexibility in allowing other users to access
Evan Hunt's avatar
Evan Hunt committed
1104
          <span class="command"><strong>rndc</strong></span> commands, then you need to create
Mark Andrews's avatar
regen    
Mark Andrews committed
1105
1106
          a
          <code class="filename">rndc.conf</code> file and make it group
Rob Austein's avatar
regen    
Rob Austein committed
1107
1108
1109
          readable by a group
          that contains the users who should have access.
        </p>
Tinderbox User's avatar
Tinderbox User committed
1110
<p>
Mark Andrews's avatar
gregen    
Mark Andrews committed
1111
          To disable the command channel, use an empty
Evan Hunt's avatar
Evan Hunt committed
1112
1113
          <span class="command"><strong>controls</strong></span> statement:
          <span class="command"><strong>controls { };</strong></span>.
Rob Austein's avatar
regen    
Rob Austein committed
1114
        </p>
Tinderbox User's avatar
Tinderbox User committed
1115
1116
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1117
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1118
<a name="include_grammar"></a><span class="command"><strong>include</strong></span> Statement Grammar</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
1119
1120
1121
<pre class="programlisting"><span class="command"><strong>include</strong></span> <em class="replaceable"><code>filename</code></em>;</pre>
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1122
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1123
<a name="include_statement"></a><span class="command"><strong>include</strong></span> Statement Definition and Usage</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
1124
<p>
Evan Hunt's avatar
Evan Hunt committed
1125
1126
1127
          The <span class="command"><strong>include</strong></span> statement inserts the
          specified file at the point where the <span class="command"><strong>include</strong></span>
          statement is encountered. The <span class="command"><strong>include</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
1128
1129
1130
1131
1132
1133
                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>
Tinderbox User's avatar
Tinderbox User committed
1134
1135
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1136
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1137
<a name="key_grammar"></a><span class="command"><strong>key</strong></span> Statement Grammar</h3></div></div></div>
Evan Hunt's avatar
Evan Hunt committed
1138
<pre class="programlisting"><span class="command"><strong>key</strong></span> <em class="replaceable"><code>key_id</code></em> {
Tinderbox User's avatar
Tinderbox User committed
1139
1140
    algorithm <em class="replaceable"><code>algorithm_id</code></em>;
    secret <em class="replaceable"><code>secret_string</code></em>;
1141
};
Rob Austein's avatar
regen    
Rob Austein committed
1142
</pre>
Tinderbox User's avatar
Tinderbox User committed
1143
1144
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1145
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1146
<a name="key_statement"></a><span class="command"><strong>key</strong></span> Statement Definition and Usage</h3></div></div></div>
Tinderbox User's avatar
Tinderbox User committed
1147
<p>
Evan Hunt's avatar
Evan Hunt committed
1148
1149
          The <span class="command"><strong>key</strong></span> statement defines a shared
          secret key for use with TSIG (see <a class="xref" href="Bv9ARM.ch04.html#tsig" title="TSIG">the section called &#8220;TSIG&#8221;</a>)
Rob Austein's avatar
regen    
Rob Austein committed
1150
          or the command channel
Evan Hunt's avatar
Evan Hunt committed
1151
          (see <a class="xref" href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and Usage">the section called &#8220;<span class="command"><strong>controls</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
1152
1153
          Usage&#8221;</a>).
        </p>
Tinderbox User's avatar
Tinderbox User committed
1154
<p>
Evan Hunt's avatar
Evan Hunt committed
1155
          The <span class="command"><strong>key</strong></span> statement can occur at the
Rob Austein's avatar
regen    
Rob Austein committed
1156
          top level
Evan Hunt's avatar
Evan Hunt committed
1157
1158
          of the configuration file or inside a <span class="command"><strong>view</strong></span>
          statement.  Keys defined in top-level <span class="command"><strong>key</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
1159
          statements can be used in all views.  Keys intended for use in
Evan Hunt's avatar
Evan Hunt committed
1160
1161
          a <span class="command"><strong>controls</strong></span> statement
          (see <a class="xref" href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and Usage">the section called &#8220;<span class="command"><strong>controls</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
1162
1163
1164
          Usage&#8221;</a>)
          must be defined at the top level.
        </p>
Tinderbox User's avatar
Tinderbox User committed
1165
<p>
Rob Austein's avatar
regen    
Rob Austein committed
1166
1167
          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
Evan Hunt's avatar
Evan Hunt committed
1168
          be used in a <span class="command"><strong>server</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
1169
1170
1171
1172
1173
          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>
Tinderbox User's avatar
Tinderbox User committed
1174
<p>
Rob Austein's avatar
regen    
Rob Austein committed
1175
          The <em class="replaceable"><code>algorithm_id</code></em> is a string
Tinderbox User's avatar
Tinderbox User committed
1176
          that specifies a security/authentication algorithm.  The
Evan Hunt's avatar
Evan Hunt committed
1177
          <span class="command"><strong>named</strong></span> server supports <code class="literal">hmac-md5</code>,
Mark Andrews's avatar
regen    
Mark Andrews committed
1178
1179
1180
1181
          <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
1182
          number of required bits preceded by a dash, e.g.
Mark Andrews's avatar
regen    
Mark Andrews committed
1183
          <code class="literal">hmac-sha1-80</code>.  The
Rob Austein's avatar
regen    
Rob Austein committed
1184
          <em class="replaceable"><code>secret_string</code></em> is the secret
Mark Andrews's avatar
regen    
Mark Andrews committed
1185
1186
          to be used by the algorithm, and is treated as a base-64
          encoded string.
Rob Austein's avatar
regen    
Rob Austein committed
1187
        </p>
Tinderbox User's avatar
Tinderbox User committed
1188
1189
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1190
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
Tinderbox User committed
1191
<a name="logging_grammar"></a><span class="command"><strong>logging</strong></span> Statement Grammar</h3></div></div></div>
Evan Hunt's avatar
Evan Hunt committed
1192
1193
1194
1195
1196
1197
1198
1199
1200
<pre class="programlisting"><span class="command"><strong>logging</strong></span> {
   [ <span class="command"><strong>channel</strong></span> <em class="replaceable"><code>channel_name</code></em> {
     ( <span class="command"><strong>file</strong></span> <em class="replaceable"><code>path_name</code></em>
         [ <span class="command"><strong>versions</strong></span> ( <em class="replaceable"><code>number</code></em> | <span class="command"><strong>unlimited</strong></span> ) ]
         [ <span class="command"><strong>size</strong></span> <em class="replaceable"><code>size_spec</code></em> ]
       | <span class="command"><strong>syslog</strong></span> <em class="replaceable"><code>syslog_facility</code></em>
       | <span class="command"><strong>stderr</strong></span>
       | <span class="command"><strong>null</strong></span> );
     [ <span class="command"><strong>severity</strong></span> (<code class="option">critical</code> | <code class="option">error</code> | <code class="option">warning</code> | <code class="option">notice</code> |
Rob Austein's avatar
regen    
Rob Austein committed
1201
                 <code class="option">info</code> | <code class="option">debug</code> [ <em class="replaceable"><code>level</code></em> ] | <code class="option">dynamic</code> ); ]
Evan Hunt's avatar
Evan Hunt committed
1202
1203
1204
1205
     [ <span class="command"><strong>print-category</strong></span> <code class="option">yes</code> or <code class="option">no</code>; ]
     [ <span class="command"><strong>print-severity</strong></span> <code class="option">yes</code> or <code class="option">no</code>; ]
     [ <span class="command"><strong>print-time</strong></span> <code class="option">yes</code> or <code class="option">no</code>; ]
     [ <span class="command"><strong>buffered</strong></span> <code class="option">yes</code> or <code class="option">no</code>; ]
1206
   }; ]
Evan Hunt's avatar
Evan Hunt committed
1207
   [ <span class="command"><strong>category</strong></span> <em class="replaceable"><code>category_name</code></em> {
Rob Austein's avatar
regen    
Rob Austein committed
1208
     <em class="replaceable"><code>channel_name</code></em> ; [ <em class="replaceable"><code>channel_name</code></em> ; ... ]
1209
1210
1211
   }; ]
   ...
};
Rob Austein's avatar
regen    
Rob Austein committed
1212
</pre>
<