Skip to content

GitLab

Switch branch/tag
Find file Normal viewHistoryPermalink
Bv9ARM.ch06.html 672 KB
Newer Older
Mark Andrews's avatar
4456. [doc] Add DOCTYPE and lang attribute to <html> tags.    
Mark Andrews committed
1 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
Rob Austein's avatar
regen    
Rob Austein committed
2 
<!--
Tinderbox User's avatar
regen master    
Tinderbox User committed
3 
 - Copyright (C) 2000-2016 Internet Systems Consortium, Inc. ("ISC")
Rob Austein's avatar
regen    
Rob Austein committed
4 
 -
Tinderbox User's avatar
regen master    
Tinderbox User committed
5
6
7 
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
Rob Austein's avatar
regen    
Rob Austein committed
8 
-->
Mark Andrews's avatar
4456. [doc] Add DOCTYPE and lang attribute to <html> tags.    
Mark Andrews committed
9 
<html lang="en">
Rob Austein's avatar
regen    
Rob Austein committed
10
11
12 
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter 6. BIND 9 Configuration Reference</title>
Tinderbox User's avatar
regen master    
Tinderbox User committed
13 
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
14 
<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
Rob Austein's avatar
regen    
Rob Austein committed
15
16
17
18
19
20
21 
<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
<link rel="prev" href="Bv9ARM.ch05.html" title="Chapter 5. The BIND 9 Lightweight Resolver">
<link rel="next" href="Bv9ARM.ch07.html" title="Chapter 7. BIND 9 Security Considerations">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
Mark Andrews's avatar
regen    
Mark Andrews committed
22 
<tr><th colspan="3" align="center">Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</th></tr>
Rob Austein's avatar
regen    
Rob Austein committed
23
24
25
26
27
28
29
30
31
32 
<tr>
<td width="20%" align="left">
<a accesskey="p" href="Bv9ARM.ch05.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch07.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
33
34
35 
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="Bv9ARM.ch06"></a>Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</h1></div></div></div>
Rob Austein's avatar
regen    
Rob Austein committed
36
37 
<div class="toc">
<p><b>Table of Contents</b></p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
38 
<dl class="toc">
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
39 
<dt><span class="section"><a href="Bv9ARM.ch06.html#configuration_file_elements">Configuration File Elements</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
40 
<dd><dl>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
41 
<dt><span class="section"><a href="Bv9ARM.ch06.html#address_match_lists">Address Match Lists</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
42 
<dt><span class="section"><a href="Bv9ARM.ch06.html#comment_syntax">Comment Syntax</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
43 
</dl></dd>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
44 
<dt><span class="section"><a href="Bv9ARM.ch06.html#Configuration_File_Grammar">Configuration File Grammar</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
45 
<dd><dl>
Tinderbox User's avatar
regen master    
Tinderbox User committed
46 
<dt><span class="section"><a href="Bv9ARM.ch06.html#acl_grammar"><span class="command"><strong>acl</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
47 
<dt><span class="section"><a href="Bv9ARM.ch06.html#acl"><span class="command"><strong>acl</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
48 
          Usage</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
49 
<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_grammar"><span class="command"><strong>controls</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
50 
<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage"><span class="command"><strong>controls</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
51 
          Usage</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
52
53
54
55
56
57
58
59
60
61 
<dt><span class="section"><a href="Bv9ARM.ch06.html#include_grammar"><span class="command"><strong>include</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#include_statement"><span class="command"><strong>include</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#key_grammar"><span class="command"><strong>key</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#key_statement"><span class="command"><strong>key</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_grammar"><span class="command"><strong>logging</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#logging_statement"><span class="command"><strong>logging</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_grammar"><span class="command"><strong>lwres</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#lwres_statement"><span class="command"><strong>lwres</strong></span> Statement Definition and Usage</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_grammar"><span class="command"><strong>masters</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#masters_statement"><span class="command"><strong>masters</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
62 
          Usage</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
63 
<dt><span class="section"><a href="Bv9ARM.ch06.html#options_grammar"><span class="command"><strong>options</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
64 
<dt><span class="section"><a href="Bv9ARM.ch06.html#options"><span class="command"><strong>options</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
65 
          Usage</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
66
67 
<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_grammar"><span class="command"><strong>server</strong></span> Statement Grammar</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#server_statement_definition_and_usage"><span class="command"><strong>server</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
68 
            Usage</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
69 
<dt><span class="section"><a href="Bv9ARM.ch06.html#statschannels"><span class="command"><strong>statistics-channels</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
70 
<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_channels"><span class="command"><strong>statistics-channels</strong></span> Statement Definition and
Automatic Updater's avatar
regen    
Automatic Updater committed
71 
            Usage</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
72 
<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted-keys"><span class="command"><strong>trusted-keys</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
73 
<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted_keys"><span class="command"><strong>trusted-keys</strong></span> Statement Definition
Automatic Updater's avatar
regen    
Automatic Updater committed
74 
            and Usage</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
75 
<dt><span class="section"><a href="Bv9ARM.ch06.html#managed_keys"><span class="command"><strong>managed-keys</strong></span> Statement Grammar</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
76 
<dt><span class="section"><a href="Bv9ARM.ch06.html#managed-keys"><span class="command"><strong>managed-keys</strong></span> Statement Definition
Rob Austein's avatar
regen    
Rob Austein committed
77 
            and Usage</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
78 
<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement_grammar"><span class="command"><strong>view</strong></span> Statement Grammar</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
79 
<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement"><span class="command"><strong>view</strong></span> Statement Definition and Usage</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
80 
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement_grammar"><span class="command"><strong>zone</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
81 
            Statement Grammar</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
82 
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement"><span class="command"><strong>zone</strong></span> Statement Definition and Usage</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
83 
</dl></dd>
Tinderbox User's avatar
regen master    
Tinderbox User committed
84 
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_file">Zone File</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
85 
<dd><dl>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
86 
<dt><span class="section"><a href="Bv9ARM.ch06.html#types_of_resource_records_and_when_to_use_them">Types of Resource Records and When to Use Them</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
87 
<dt><span class="section"><a href="Bv9ARM.ch06.html#mx_records">Discussion of MX Records</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
88 
<dt><span class="section"><a href="Bv9ARM.ch06.html#Setting_TTLs">Setting TTLs</a></span></dt>
Tinderbox User's avatar
regen master    
Tinderbox User committed
89
90
91 
<dt><span class="section"><a href="Bv9ARM.ch06.html#ipv4_reverse">Inverse Mapping in IPv4</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_directives">Other Zone File Directives</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#generate_directive"><acronym class="acronym">BIND</acronym> Master File Extension: the  <span class="command"><strong>$GENERATE</strong></span> Directive</a></span></dt>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
92
93
94
95
96
97 
<dt><span class="section"><a href="Bv9ARM.ch06.html#zonefile_format">Additional File Formats</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics">BIND9 Statistics</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="Bv9ARM.ch06.html#statsfile">The Statistics File</a></span></dt>
<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_counters">Statistics Counters</a></span></dt>
Rob Austein's avatar
regen    
Rob Austein committed
98
99
100 
</dl></dd>
</dl>
</div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
101 
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
102
103 
      <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
104 
      areas
Mark Andrews's avatar
regen    
Mark Andrews committed
105
106 
      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
107
108 
      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
109 
      found in <acronym class="acronym">BIND</acronym> 9.
Rob Austein's avatar
regen    
Rob Austein committed
110 
    </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
111 
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
112 
      <acronym class="acronym">BIND</acronym> 4 configuration files can be
Rob Austein's avatar
regen    
Rob Austein committed
113
114
115
116 
      converted to the new format
      using the shell script
      <code class="filename">contrib/named-bootconf/named-bootconf.sh</code>.
    </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
117 
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
118
119 
<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
regen master    
Tinderbox User committed
120 
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
121 
        Following is a list of elements used throughout the <acronym class="acronym">BIND</acronym> configuration
Rob Austein's avatar
regen    
Rob Austein committed
122
123 
        file documentation:
      </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
124 
<div class="informaltable"><table border="1">
Rob Austein's avatar
regen    
Rob Austein committed
125 
<colgroup>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
126
127 
<col width="1.855in" class="1">
<col width="3.770in" class="2">
Rob Austein's avatar
regen    
Rob Austein committed
128
129
130
131
132
133
134
135
136
137
138 
</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
[master] upgrade doc toolchain    
Evan Hunt committed
139 
                  defined by the <span class="command"><strong>acl</strong></span> statement.
Rob Austein's avatar
regen    
Rob Austein committed
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154 
                </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
[master] upgrade doc toolchain    
Evan Hunt committed
155 
                  <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
156
157
158
159 
                </p>
              </td>
</tr>
<tr>
Mark Andrews's avatar
gregen    
Mark Andrews committed
160
161
162
163
164
165
166
167 
<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
168 
                  with optional <code class="varname">key_id</code> and/or
Mark Andrews's avatar
gregen    
Mark Andrews committed
169
170
171
172
173
174
175 
                  <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
176
177
178
179
180
181
182
183
184
185
186
187
188 
<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
189
190
191
192
193
194
195
196
197
198
199
200
201 
<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
202
203
204
205
206
207
208
209 
<td>
                <p>
                  <code class="varname">dotted_decimal</code>
                </p>
              </td>
<td>
                <p>
                  One to four integers valued 0 through
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
210
211 
                  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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235 
                </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
[master] upgrade doc toolchain    
Evan Hunt committed
236 
                  An IPv6 address, such as <span class="command"><strong>2001:db8::1234</strong></span>.
Mark Andrews's avatar
regen    
Mark Andrews committed
237
238
239
240
241
242
243
244
245 
                  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
246 
                  are supported, assuming one-to-one mapping between
Mark Andrews's avatar
regen    
Mark Andrews committed
247 
                  interfaces and links.  For example, a link-local
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
248
249
250 
                  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
251
252
253 
                  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
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269 
                </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
regen master    
Tinderbox User committed
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284 
<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
285
286
287
288
289
290
291
292 
<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
293 
                  The <code class="varname">number</code> is limited to 0
Rob Austein's avatar
regen    
Rob Austein committed
294
295
296 
                  through 65535, with values
                  below 1024 typically restricted to use by processes running
                  as root.
Mark Andrews's avatar
regen    
Mark Andrews committed
297 
                  In some cases, an asterisk (`*') character can be used as a
Rob Austein's avatar
regen    
Rob Austein committed
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315 
                  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
[master] upgrade doc toolchain    
Evan Hunt committed
316
317
318
319 
                  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
320 
                </p>
Mark Andrews's avatar
regen    
Mark Andrews committed
321
322
323
324
325 
                <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
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363 
              </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
364 
                  A non-negative 32-bit integer
Rob Austein's avatar
regen    
Rob Austein committed
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384 
                  (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
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411 
<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
412
413
414
415
416
417
418 
<td>
                <p>
                  <code class="varname">size_spec</code>
                </p>
              </td>
<td>
                <p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
419
420
421 
                  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
422 
                </p>
Mark Andrews's avatar
gregen    
Mark Andrews committed
423 
                <p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
424
425 
                  Integers may take values
                  0 &lt;= value &lt;= 18446744073709551615, though
Tinderbox User's avatar
regen master    
Tinderbox User committed
426 
                  certain parameters
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
427 
                  (such as <span class="command"><strong>max-journal-size</strong></span>) may
Tinderbox User's avatar
regen master    
Tinderbox User committed
428
429
430
431 
                  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
regen master    
Tinderbox User committed
432 
                  See the explanations of particular parameters
Tinderbox User's avatar
regen master    
Tinderbox User committed
433 
                  that use <code class="varname">size_spec</code>
Tinderbox User's avatar
regen master    
Tinderbox User committed
434 
                  for details on how they interpret its use.
Rob Austein's avatar
regen    
Rob Austein committed
435
436 
                </p>
                <p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
437
438 
                  Numeric values can optionally be followed by a
                  scaling factor:
Mark Andrews's avatar
gregen    
Mark Andrews committed
439
440
441
442 
                  <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
regen master    
Tinderbox User committed
443
444
445 
                  <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
446
447 
                </p>
                <p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
448 
                  <code class="varname">unlimited</code> generally means
Tinderbox User's avatar
regen master    
Tinderbox User committed
449
450 
                  "as big as possible", and is usually the best
                  way to safely set a very large number.
Tinderbox User's avatar
regen master    
Tinderbox User committed
451
452 
                </p>
                <p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
453 
                  <code class="varname">default</code>
Tinderbox User's avatar
regen master    
Tinderbox User committed
454 
                  uses the limit that was in force when the server was started.
Rob Austein's avatar
regen    
Rob Austein committed
455
456
457
458 
                </p>
              </td>
</tr>
<tr>
Tinderbox User's avatar
regen master    
Tinderbox User committed
459
460
461
462
463
464
465
466
467
468
469 
<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
regen master    
Tinderbox User committed
470 
                  The behavior is exactly the same as
Tinderbox User's avatar
regen master    
Tinderbox User committed
471
472
473
474
475
476
477
478 
                  <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
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
506
507
508
509
510
511 
<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
regen master    
Tinderbox User committed
512
513 
</table></div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
514
515 
<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
regen master    
Tinderbox User committed
516 
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
517 
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
518 
<a name="id-1.7.4.4.2"></a>Syntax</h4></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
519
520
521
522 
<pre class="programlisting"><em class="replaceable"><code>address_match_list</code></em> = <em class="replaceable"><code>address_match_list_element</code></em> <span class="command"><strong>;</strong></span> ...

<em class="replaceable"><code>address_match_list_element</code></em> = [ <span class="command"><strong>!</strong></span> ] ( <em class="replaceable"><code>ip_address</code></em> | <em class="replaceable"><code>ip_prefix</code></em> |
     <span class="command"><strong>key</strong></span> <em class="replaceable"><code>key_id</code></em> | <em class="replaceable"><code>acl_name</code></em> | <span class="command"><strong>{</strong></span> <em class="replaceable"><code>address_match_list</code></em> <span class="command"><strong>}</strong></span> )
Rob Austein's avatar
regen    
Rob Austein committed
523 
</pre>
Tinderbox User's avatar
regen master    
Tinderbox User committed
524
525 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
526 
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
527
528 
<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
529
530 
            Address match lists are primarily used to determine access
            control for various server operations. They are also used in
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
531 
            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
532
533 
            statements. The elements which constitute an address match
            list can be any of the following:
Rob Austein's avatar
regen    
Rob Austein committed
534 
          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
535
536
537 
<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
[master] upgrade doc toolchain    
Evan Hunt committed
538
539 
<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
540 
                statement
Tinderbox User's avatar
regen master    
Tinderbox User committed
541
542 
              </li>
<li class="listitem">the name of an address match list defined with
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
543 
                the <span class="command"><strong>acl</strong></span> statement
Tinderbox User's avatar
regen master    
Tinderbox User committed
544
545 
              </li>
<li class="listitem">a nested address match list enclosed in braces</li>
Rob Austein's avatar
regen    
Rob Austein committed
546 
</ul></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
547 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
548
549 
            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
550
551 
            "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
552 
          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
553 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
554
555
556 
            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
557
558 
            Nonetheless, the term "address match list" is still used
            throughout the documentation.
Rob Austein's avatar
regen    
Rob Austein committed
559 
          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
560 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
561 
            When a given IP address or prefix is compared to an address
Mark Andrews's avatar
regen    
Mark Andrews committed
562
563
564
565
566 
            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
regen master    
Tinderbox User committed
567 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
568 
            The interpretation of a match depends on whether the list is being
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
569
570 
            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
571 
          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
572 
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
573
574
575 
            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
[master] upgrade doc toolchain    
Evan Hunt committed
576
577
578
579
580
581
582
583
584
585
586
587
588 
            <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
589 
            server to refuse queries on any of the machine's
Mark Andrews's avatar
regen    
Mark Andrews committed
590 
            addresses which do not match the list.
Rob Austein's avatar
regen    
Rob Austein committed
591 
          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
592 
<p>
Automatic Updater's avatar
regen    
Automatic Updater committed
593 
            Order of insertion is significant.  If more than one element
Mark Andrews's avatar
regen    
Mark Andrews committed
594
595
596
597
598
599
600 
            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
[master] upgrade doc toolchain    
Evan Hunt committed
601 
            <span class="command"><strong>1.2.3/24; ! 1.2.3.13;</strong></span>
Mark Andrews's avatar
regen    
Mark Andrews committed
602
603 
            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
[master] upgrade doc toolchain    
Evan Hunt committed
604 
            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
605
606 
            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
607 
          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
608
609
610 
</div>
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
611 
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
612 
<a name="comment_syntax"></a>Comment Syntax</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
613 
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
614 
          The <acronym class="acronym">BIND</acronym> 9 comment syntax allows for
Rob Austein's avatar
regen    
Rob Austein committed
615 
          comments to appear
Mark Andrews's avatar
regen    
Mark Andrews committed
616 
          anywhere that whitespace may appear in a <acronym class="acronym">BIND</acronym> configuration
Rob Austein's avatar
regen    
Rob Austein committed
617
618
619 
          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
regen master    
Tinderbox User committed
620 
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
621 
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
622
623 
<a name="id-1.7.4.5.3"></a>Syntax</h4></div></div></div>
<p>
Rob Austein's avatar
regen    
Rob Austein committed
624 
            </p>
Mark Andrews's avatar
regen    
Mark Andrews committed
625 
<pre class="programlisting">/* This is a <acronym class="acronym">BIND</acronym> comment as in C */</pre>
Rob Austein's avatar
regen    
Rob Austein committed
626
627 
<p>
            </p>
Mark Andrews's avatar
regen    
Mark Andrews committed
628 
<pre class="programlisting">// This is a <acronym class="acronym">BIND</acronym> comment as in C++</pre>
Rob Austein's avatar
regen    
Rob Austein committed
629
630 
<p>
            </p>
Automatic Updater's avatar
regen    
Automatic Updater committed
631
632 
<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
633
634 
<p>
          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
635
636 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
637 
<div class="titlepage"><div><div><h4 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
638
639 
<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
640 
            Comments may appear anywhere that whitespace may appear in
Mark Andrews's avatar
regen    
Mark Andrews committed
641 
            a <acronym class="acronym">BIND</acronym> configuration file.
Rob Austein's avatar
regen    
Rob Austein committed
642 
          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
643 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
644
645
646
647
648 
            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
regen master    
Tinderbox User committed
649 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
650
651
652 
            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
regen master    
Tinderbox User committed
653 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
654
655
656 

</p>
<pre class="programlisting">/* This is the start of a comment.
Eric Luce's avatar
Add some flags to the nominum dsssl modification that hvae the HTML  
Eric Luce committed
657
658
659 
   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
660
661
662
663 
</pre>
<p>

          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
664 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
665
666
667
668
669
670 
            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
regen master    
Tinderbox User committed
671 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
672
673
674 

</p>
<pre class="programlisting">// This is the start of a comment.  The next line
Eric Luce's avatar
Add some flags to the nominum dsssl modification that hvae the HTML  
Eric Luce committed
675
676 
// is a new comment, even though it is logically
// part of the previous comment.
Rob Austein's avatar
regen    
Rob Austein committed
677
678
679
680 
</pre>
<p>

          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
681 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
682
683
684
685
686
687 
            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
regen master    
Tinderbox User committed
688 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
689
690
691 

</p>
<pre class="programlisting"># This is the start of a comment.  The next line
Eric Luce's avatar
Add some flags to the nominum dsssl modification that hvae the HTML  
Eric Luce committed
692
693 
# is a new comment, even though it is logically
# part of the previous comment.
Rob Austein's avatar
regen    
Rob Austein committed
694
695
696
697 
</pre>
<p>

          </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
698 
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
Rob Austein's avatar
regen    
Rob Austein committed
699 
<h3 class="title">Warning</h3>
Tinderbox User's avatar
regen master    
Tinderbox User committed
700 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
701
702
703
704
705 
              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
regen master    
Tinderbox User committed
706
707
708
709
710 
</div>
</div>
</div>
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
711
712 
<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
regen master    
Tinderbox User committed
713 
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
714 
        A <acronym class="acronym">BIND</acronym> 9 configuration consists of
Rob Austein's avatar
regen    
Rob Austein committed
715
716
717
718
719
720 
        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
regen master    
Tinderbox User committed
721 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
722
723 
        The following statements are supported:
      </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
724 
<div class="informaltable"><table border="1">
Rob Austein's avatar
regen    
Rob Austein committed
725 
<colgroup>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
726
727 
<col width="1.336in" class="1">
<col width="3.778in" class="2">
Rob Austein's avatar
regen    
Rob Austein committed
728
729
730
731 
</colgroup>
<tbody>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
732 
                <p><span class="command"><strong>acl</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
733
734
735
736
737
738
739
740
741
742 
              </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
[master] upgrade doc toolchain    
Evan Hunt committed
743 
                <p><span class="command"><strong>controls</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
744
745
746
747 
              </td>
<td>
                <p>
                  declares control channels to be used
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
748 
                  by the <span class="command"><strong>rndc</strong></span> utility.
Rob Austein's avatar
regen    
Rob Austein committed
749
750
751
752
753 
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
754 
                <p><span class="command"><strong>include</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
755
756
757
758
759
760
761
762
763 
              </td>
<td>
                <p>
                  includes a file.
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
764 
                <p><span class="command"><strong>key</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
765
766
767
768
769
770
771
772
773
774 
              </td>
<td>
                <p>
                  specifies key information for use in
                  authentication and authorization using TSIG.
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
775 
                <p><span class="command"><strong>logging</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
776
777
778
779
780
781
782
783
784
785 
              </td>
<td>
                <p>
                  specifies what the server logs, and where
                  the log messages are sent.
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
786 
                <p><span class="command"><strong>lwres</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
787
788
789 
              </td>
<td>
                <p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
790
791 
                  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
792
793
794
795
796 
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
797 
                <p><span class="command"><strong>masters</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
798
799
800
801 
              </td>
<td>
                <p>
                  defines a named masters list for
Automatic Updater's avatar
regen HEAD    
Automatic Updater committed
802 
                  inclusion in stub and slave zones'
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
803
804 
                  <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
805
806
807
808
809 
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
810 
                <p><span class="command"><strong>options</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
811
812
813
814
815
816
817
818
819 
              </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
820 
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
821 
                <p><span class="command"><strong>server</strong></span></p>
Mark Andrews's avatar
regen    
Mark Andrews committed
822
823
824 
              </td>
<td>
                <p>
Automatic Updater's avatar
regen    
Automatic Updater committed
825
826 
                  sets certain configuration options on
                  a per-server basis.
Mark Andrews's avatar
regen    
Mark Andrews committed
827
828
829
830 
                </p>
              </td>
</tr>
<tr>
Rob Austein's avatar
regen    
Rob Austein committed
831 
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
832 
                <p><span class="command"><strong>statistics-channels</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
833
834
835 
              </td>
<td>
                <p>
Automatic Updater's avatar
regen    
Automatic Updater committed
836 
                  declares communication channels to get access to
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
837 
                  <span class="command"><strong>named</strong></span> statistics.
Rob Austein's avatar
regen    
Rob Austein committed
838
839
840
841
842 
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
843 
                <p><span class="command"><strong>trusted-keys</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
844
845
846
847
848
849
850
851 
              </td>
<td>
                <p>
                  defines trusted DNSSEC keys.
                </p>
              </td>
</tr>
<tr>
Automatic Updater's avatar
regen    
Automatic Updater committed
852 
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
853 
                <p><span class="command"><strong>managed-keys</strong></span></p>
Automatic Updater's avatar
regen    
Automatic Updater committed
854
855
856
857
858
859
860
861
862 
              </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
863 
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
864 
                <p><span class="command"><strong>view</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
865
866
867
868
869
870
871
872
873 
              </td>
<td>
                <p>
                  defines a view.
                </p>
              </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
874 
                <p><span class="command"><strong>zone</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
875
876
877
878
879
880
881
882 
              </td>
<td>
                <p>
                  defines a zone.
                </p>
              </td>
</tr>
</tbody>
Tinderbox User's avatar
regen master    
Tinderbox User committed
883
884 
</table></div>
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
885
886 
        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
887
888
889 
        per
        configuration.
      </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
890 
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
891 
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
892 
<a name="acl_grammar"></a><span class="command"><strong>acl</strong></span> Statement Grammar</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
893
894
895 
<pre class="programlisting"><span class="command"><strong>acl</strong></span> <em class="replaceable"><code>acl-name</code></em> <span class="command"><strong>{</strong></span>
    <em class="replaceable"><code>address_match_list</code></em>
<span class="command"><strong>};</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
896 
</pre>
Tinderbox User's avatar
regen master    
Tinderbox User committed
897
898 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
899 
<div class="titlepage"><div><div><h3 class="title">
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
900 
<a name="acl"></a><span class="command"><strong>acl</strong></span> Statement Definition and
Rob Austein's avatar
regen    
Rob Austein committed
901 
          Usage</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
902 
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
903 
          The <span class="command"><strong>acl</strong></span> statement assigns a symbolic
Rob Austein's avatar
regen    
Rob Austein committed
904
905
906 
          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
regen master    
Tinderbox User committed
907 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
908
909 
          The following ACLs are built-in:
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
910 
<div class="informaltable"><table border="1">
Rob Austein's avatar
regen    
Rob Austein committed
911 
<colgroup>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
912
913 
<col width="1.130in" class="1">
<col width="4.000in" class="2">
Rob Austein's avatar
regen    
Rob Austein committed
914
915
916
917 
</colgroup>
<tbody>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
918 
                  <p><span class="command"><strong>any</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
919
920
921
922
923
924
925
926
927 
                </td>
<td>
                  <p>
                    Matches all hosts.
                  </p>
                </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
928 
                  <p><span class="command"><strong>none</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
929
930
931
932
933
934
935
936
937 
                </td>
<td>
                  <p>
                    Matches no hosts.
                  </p>
                </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
938 
                  <p><span class="command"><strong>localhost</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
939
940
941
942 
                </td>
<td>
                  <p>
                    Matches the IPv4 and IPv6 addresses of all network
Tinderbox User's avatar
regen master    
Tinderbox User committed
943 
                    interfaces on the system.  When addresses are
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
944 
                    added or removed, the <span class="command"><strong>localhost</strong></span>
Tinderbox User's avatar
regen master    
Tinderbox User committed
945 
                    ACL element is updated to reflect the changes.
Rob Austein's avatar
regen    
Rob Austein committed
946
947
948
949
950 
                  </p>
                </td>
</tr>
<tr>
<td>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
951 
                  <p><span class="command"><strong>localnets</strong></span></p>
Rob Austein's avatar
regen    
Rob Austein committed
952
953
954
955
956 
                </td>
<td>
                  <p>
                    Matches any host on an IPv4 or IPv6 network
                    for which the system has an interface.
Tinderbox User's avatar
regen master    
Tinderbox User committed
957 
                    When addresses are added or removed,
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
958 
                    the <span class="command"><strong>localnets</strong></span>
Tinderbox User's avatar
regen master    
Tinderbox User committed
959 
                    ACL element is updated to reflect the changes.
Rob Austein's avatar
regen    
Rob Austein committed
960
961
962 
                    Some systems do not provide a way to determine the prefix
                    lengths of
                    local IPv6 addresses.
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
963 
                    In such a case, <span class="command"><strong>localnets</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
964 
                    only matches the local
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
965 
                    IPv6 addresses, just like <span class="command"><strong>localhost</strong></span>.
Rob Austein's avatar
regen    
Rob Austein committed
966
967
968
969 
                  </p>
                </td>
</tr>
</tbody>
Tinderbox User's avatar
regen master    
Tinderbox User committed
970
971
972 
</table></div>
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
973 
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
974 
<a name="controls_grammar"></a><span class="command"><strong>controls</strong></span> Statement Grammar</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
975
976
977
978
979
980
981
982
983 
<pre class="programlisting"><span class="command"><strong>controls {</strong></span>
  [ <span class="command"><strong>inet</strong></span> ( <em class="replaceable"><code>ip_addr</code></em> | <span class="command"><strong>*</strong></span> ) [ <span class="command"><strong>port</strong></span> <em class="replaceable"><code>ip_port</code></em> ] <span class="command"><strong>allow {</strong></span> <em class="replaceable"><code>address_match_list</code></em> <span class="command"><strong>}</strong></span>
      [ <span class="command"><strong>keys {</strong></span> <em class="replaceable"><code>key_list</code></em> <span class="command"><strong>}</strong></span> ]
      [ <span class="command"><strong>read-only</strong></span> <em class="replaceable"><code>yes_or_no</code></em> ] <span class="command"><strong>;</strong></span> ]
  [ <span class="command"><strong>unix</strong></span> <em class="replaceable"><code>path</code></em> <span class="command"><strong>perm</strong></span> <em class="replaceable"><code>number</code></em> <span class="command"><strong>owner</strong></span> <em class="replaceable"><code>number</code></em> <span class="command"><strong>group</strong></span> <em class="replaceable"><code>number</code></em>
      [ <span class="command"><strong>keys {</strong></span> <em class="replaceable"><code>key_list</code></em> <span class="command"><strong>}</strong></span> ]
      [ <span class="command"><strong>read-only</strong></span> <em class="replaceable"><code>yes_or_no</code></em> ] <span class="command"><strong>;</strong></span> ]
   [ ...; ]
<span class="command"><strong>};</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
984 
</pre>
Tinderbox User's avatar
regen master    
Tinderbox User committed
985
986 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
987 
<div class="titlepage"><div><div><h3 class="title">
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
988 
<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
989 
          Usage</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
990 
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
991 
          The <span class="command"><strong>controls</strong></span> statement declares control
Rob Austein's avatar
regen    
Rob Austein committed
992
993 
          channels to be used by system administrators to control the
          operation of the name server. These control channels are
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
994 
          used by the <span class="command"><strong>rndc</strong></span> utility to send
Mark Andrews's avatar
gregen    
Mark Andrews committed
995 
          commands to and retrieve non-DNS results from a name server.
Rob Austein's avatar
regen    
Rob Austein committed
996 
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
997 
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
998
999
1000
1001 
          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
1002
1003
1004 
          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
[master] upgrade doc toolchain    
Evan Hunt committed
1005
1006 
          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
1007 
          using the loopback address (<code class="literal">127.0.0.1</code>
Mark Andrews's avatar
gregen    
Mark Andrews committed
1008 
          or <code class="literal">::1</code>) is recommended for maximum security.
Rob Austein's avatar
regen    
Rob Austein committed
1009 
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1010 
<p>
Mark Andrews's avatar
regen    
Mark Andrews committed
1011 
          If no port is specified, port 953 is used. The asterisk
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1012 
          "<code class="literal">*</code>" cannot be used for <span class="command"><strong>ip_port</strong></span>.
Rob Austein's avatar
regen    
Rob Austein committed
1013 
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1014 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
1015 
          The ability to issue commands over the control channel is
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1016
1017 
          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
1018 
          Connections to the control channel are permitted based on the
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1019
1020
1021 
          <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
1022
1023 
          are ignored.
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1024 
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1025 
          A <span class="command"><strong>unix</strong></span> control channel is a UNIX domain
Mark Andrews's avatar
gregen    
Mark Andrews committed
1026 
          socket listening at the specified path in the file system.
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1027
1028 
          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
1029 
          Note on some platforms (SunOS and Solaris) the permissions
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1030 
          (<span class="command"><strong>perm</strong></span>) are applied to the parent directory
Mark Andrews's avatar
gregen    
Mark Andrews committed
1031 
          as the permissions on the socket itself are ignored.
Rob Austein's avatar
regen    
Rob Austein committed
1032 
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1033 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
1034 
          The primary authorization mechanism of the command
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1035
1036
1037 
          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
1038 
          is authorized to execute commands over the control channel.
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1039
1040 
          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
1041 
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051 
<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
regen master    
Tinderbox User committed
1052 
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1053
1054 
          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
1055
1056 
          control channel listening on the loopback address 127.0.0.1
          and its IPv6 counterpart ::1.
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1057
1058
1059 
          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
1060
1061 
          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
1062 
          was specified as when <acronym class="acronym">BIND</acronym> was built).
Rob Austein's avatar
regen    
Rob Austein committed
1063
1064
1065 
          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
regen master    
Tinderbox User committed
1066 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
1067 
          The <code class="filename">rndc.key</code> feature was created to
Mark Andrews's avatar
regen    
Mark Andrews committed
1068 
          ease the transition of systems from <acronym class="acronym">BIND</acronym> 8,
Rob Austein's avatar
regen    
Rob Austein committed
1069 
          which did not have digital signatures on its command channel
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1070 
          messages and thus did not have a <span class="command"><strong>keys</strong></span> clause.
Andreas Gustafsson's avatar
regenerated docs    
Andreas Gustafsson committed
1071
Mark Andrews's avatar
regen    
Mark Andrews committed
1072
1073 
          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
[master] upgrade doc toolchain    
Evan Hunt committed
1074
1075 
          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
1076
1077
1078 
          command <strong class="userinput"><code>rndc-confgen -a</code></strong> after BIND 9 is
          installed.
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1079 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
1080
1081 
          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
1082 
          <acronym class="acronym">BIND</acronym> 8 configuration files, this
Rob Austein's avatar
regen    
Rob Austein committed
1083
1084
1085
1086
1087
1088
1089
1090 
          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
[master] upgrade doc toolchain    
Evan Hunt committed
1091 
          <span class="command"><strong>named</strong></span> is running as) can access it.
Rob Austein's avatar
regen    
Rob Austein committed
1092
1093 
          If you
          desire greater flexibility in allowing other users to access
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1094 
          <span class="command"><strong>rndc</strong></span> commands, then you need to create
Mark Andrews's avatar
regen    
Mark Andrews committed
1095
1096 
          a
          <code class="filename">rndc.conf</code> file and make it group
Rob Austein's avatar
regen    
Rob Austein committed
1097
1098
1099 
          readable by a group
          that contains the users who should have access.
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1100 
<p>
Mark Andrews's avatar
gregen    
Mark Andrews committed
1101 
          To disable the command channel, use an empty
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1102
1103 
          <span class="command"><strong>controls</strong></span> statement:
          <span class="command"><strong>controls { };</strong></span>.
Rob Austein's avatar
regen    
Rob Austein committed
1104 
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1105
1106 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1107 
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
1108 
<a name="include_grammar"></a><span class="command"><strong>include</strong></span> Statement Grammar</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1109 
<pre class="programlisting"><span class="command"><strong>include</strong></span> <em class="replaceable"><code>filename</code></em><span class="command"><strong>;</strong></span></pre>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1110
1111 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1112 
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
1113 
<a name="include_statement"></a><span class="command"><strong>include</strong></span> Statement Definition and Usage</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1114 
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1115
1116
1117 
          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
1118
1119
1120
1121
1122
1123 
                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
regen master    
Tinderbox User committed
1124
1125 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1126 
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
1127 
<a name="key_grammar"></a><span class="command"><strong>key</strong></span> Statement Grammar</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1128
1129
1130
1131 
<pre class="programlisting"><span class="command"><strong>key</strong></span> <em class="replaceable"><code>key_id</code></em> <span class="command"><strong>{</strong></span>
    <span class="command"><strong>algorithm</strong></span> <em class="replaceable"><code>algorithm_id</code></em><span class="command"><strong>;</strong></span>
    <span class="command"><strong>secret</strong></span> <em class="replaceable"><code>secret_string</code></em><span class="command"><strong>;</strong></span>
<span class="command"><strong>};</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
1132 
</pre>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1133
1134 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1135 
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
1136 
<a name="key_statement"></a><span class="command"><strong>key</strong></span> Statement Definition and Usage</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1137 
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1138
1139 
          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
1140 
          or the command channel
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1141 
          (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
1142
1143 
          Usage&#8221;</a>).
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1144 
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1145 
          The <span class="command"><strong>key</strong></span> statement can occur at the
Rob Austein's avatar
regen    
Rob Austein committed
1146 
          top level
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1147
1148 
          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
1149 
          statements can be used in all views.  Keys intended for use in
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1150
1151 
          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
1152
1153
1154 
          Usage&#8221;</a>)
          must be defined at the top level.
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1155 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
1156
1157 
          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
[master] upgrade doc toolchain    
Evan Hunt committed
1158 
          be used in a <span class="command"><strong>server</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
1159
1160
1161
1162
1163 
          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
regen master    
Tinderbox User committed
1164 
<p>
Rob Austein's avatar
regen    
Rob Austein committed
1165 
          The <em class="replaceable"><code>algorithm_id</code></em> is a string
Tinderbox User's avatar
regen master    
Tinderbox User committed
1166 
          that specifies a security/authentication algorithm.  The
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1167 
          <span class="command"><strong>named</strong></span> server supports <code class="literal">hmac-md5</code>,
Mark Andrews's avatar
regen    
Mark Andrews committed
1168
1169
1170
1171 
          <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
1172 
          number of required bits preceded by a dash, e.g.
Mark Andrews's avatar
regen    
Mark Andrews committed
1173 
          <code class="literal">hmac-sha1-80</code>.  The
Rob Austein's avatar
regen    
Rob Austein committed
1174 
          <em class="replaceable"><code>secret_string</code></em> is the secret
Mark Andrews's avatar
regen    
Mark Andrews committed
1175
1176 
          to be used by the algorithm, and is treated as a base-64
          encoded string.
Rob Austein's avatar
regen    
Rob Austein committed
1177 
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1178
1179 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1180 
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
1181 
<a name="logging_grammar"></a><span class="command"><strong>logging</strong></span> Statement Grammar</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201 
<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>{</strong></span>
    ( ( <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> | <code class="option">unlimited</code> ) ]
          [ <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>;</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> |
                   <code class="option">info</code> | <code class="option">debug</code> [ <em class="replaceable"><code>level</code></em> ] | <code class="option">dynamic</code> ) <span class="command"><strong>;</strong></span> ]
      [ <span class="command"><strong>print-category</strong></span> <em class="replaceable"><code>yes_or_no</code></em> <span class="command"><strong>;</strong></span> ]
      [ <span class="command"><strong>print-severity</strong></span> <em class="replaceable"><code>yes_or_no</code></em> <span class="command"><strong>;</strong></span> ]
      [ <span class="command"><strong>print-time</strong></span> ( <code class="option">yes</code> | <code class="option">no</code> | <code class="option">local</code> | <code class="option">iso8601</code> | <code class="option">iso8601-utc</code> ) ;
      [ <span class="command"><strong>buffered</strong></span> <em class="replaceable"><code>yes_or_no</code></em> <span class="command"><strong>;</strong></span> ]
    <span class="command"><strong>};</strong></span> ]
  [ <span class="command"><strong>category</strong></span> <em class="replaceable"><code>category_name</code></em> <span class="command"><strong>{</strong></span>
     <em class="replaceable"><code>channel_name</code></em> <span class="command"><strong>;</strong></span> ...
    <span class="command"><strong>};</strong></span> ]
    ...
<span class="command"><strong>};</strong></span>
Rob Austein's avatar
regen    
Rob Austein committed
1202 
</pre>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1203
1204 
</div>
<div class="section">
Rob Austein's avatar
regen    
Rob Austein committed
1205 
<div class="titlepage"><div><div><h3 class="title">
Tinderbox User's avatar
regen master    
Tinderbox User committed
1206 
<a name="logging_statement"></a><span class="command"><strong>logging</strong></span> Statement Definition and Usage</h3></div></div></div>
Tinderbox User's avatar
regen master    
Tinderbox User committed
1207 
<p>
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1208 
          The <span class="command"><strong>logging</strong></span> statement configures a
Rob Austein's avatar
regen    
Rob Austein committed
1209 
          wide
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1210 
          variety of logging options for the name server. Its <span class="command"><strong>channel</strong></span> phrase
Rob Austein's avatar
regen    
Rob Austein committed
1211 
          associates output methods, format options and severity levels with
Evan Hunt's avatar
[master] upgrade doc toolchain    
Evan Hunt committed
1212 
          a name that can then be used with the <span class="command"><strong>category</strong></span> phrase
Rob Austein's avatar
regen    
Rob Austein committed
1213
1214 
          to select how various classes of messages are logged.
        </p>
Tinderbox User's avatar
regen master    
Tinderbox User committed