diff options
Diffstat (limited to 'doc/arm/Bv9ARM.ch06.html')
| -rw-r--r-- | doc/arm/Bv9ARM.ch06.html | 14665 |
1 files changed, 14665 insertions, 0 deletions
diff --git a/doc/arm/Bv9ARM.ch06.html b/doc/arm/Bv9ARM.ch06.html new file mode 100644 index 0000000..8b35d8a --- /dev/null +++ b/doc/arm/Bv9ARM.ch06.html @@ -0,0 +1,14665 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<!-- + - Copyright (C) 2000-2019 Internet Systems Consortium, Inc. ("ISC") + - + - 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/. +--> +<html lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 6. BIND 9 Configuration Reference</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="up" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual"> +<link rel="prev" href="Bv9ARM.ch05.html" title="Chapter 5. The BIND 9 Lightweight Resolver"> +<link rel="next" href="Bv9ARM.ch07.html" title="Chapter 7. BIND 9 Security Considerations"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="navheader"> +<table width="100%" summary="Navigation header"> +<tr><th colspan="3" align="center">Chapter 6. <acronym class="acronym">BIND</acronym> 9 Configuration Reference</th></tr> +<tr> +<td width="20%" align="left"> +<a accesskey="p" href="Bv9ARM.ch05.html">Prev</a> </td> +<th width="60%" align="center"> </th> +<td width="20%" align="right"> <a accesskey="n" href="Bv9ARM.ch07.html">Next</a> +</td> +</tr> +</table> +<hr> +</div> +<div class="chapter"> +<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> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl class="toc"> +<dt><span class="section"><a href="Bv9ARM.ch06.html#configuration_file_elements">Configuration File Elements</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#address_match_lists">Address Match Lists</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#comment_syntax">Comment Syntax</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch06.html#Configuration_File_Grammar">Configuration File Grammar</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="Bv9ARM.ch06.html#acl_grammar"><span class="command"><strong>acl</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#acl"><span class="command"><strong>acl</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_grammar"><span class="command"><strong>controls</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#controls_statement_definition_and_usage"><span class="command"><strong>controls</strong></span> Statement Definition and + Usage</a></span></dt> +<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 + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#options_grammar"><span class="command"><strong>options</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#options"><span class="command"><strong>options</strong></span> Statement Definition and + Usage</a></span></dt> +<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 + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statschannels"><span class="command"><strong>statistics-channels</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#statistics_channels"><span class="command"><strong>statistics-channels</strong></span> Statement Definition and + Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted-keys"><span class="command"><strong>trusted-keys</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#trusted_keys"><span class="command"><strong>trusted-keys</strong></span> Statement Definition + and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#managed_keys"><span class="command"><strong>managed-keys</strong></span> Statement Grammar</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#managed-keys"><span class="command"><strong>managed-keys</strong></span> Statement Definition + and Usage</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#view_statement_grammar"><span class="command"><strong>view</strong></span> Statement Grammar</a></span></dt> +<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> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_statement_grammar"><span class="command"><strong>zone</strong></span> + Statement Grammar</a></span></dt> +<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> +</dl></dd> +<dt><span class="section"><a href="Bv9ARM.ch06.html#zone_file">Zone File</a></span></dt> +<dd><dl> +<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> +<dt><span class="section"><a href="Bv9ARM.ch06.html#mx_records">Discussion of MX Records</a></span></dt> +<dt><span class="section"><a href="Bv9ARM.ch06.html#Setting_TTLs">Setting TTLs</a></span></dt> +<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> +<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> +</dl></dd> +</dl> +</div> + + <p> + <acronym class="acronym">BIND</acronym> 9 configuration is broadly similar + to <acronym class="acronym">BIND</acronym> 8; however, there are a few new + areas + of configuration, such as views. <acronym class="acronym">BIND</acronym> + 8 configuration files should work with few alterations in <acronym class="acronym">BIND</acronym> + 9, although more complex configurations should be reviewed to check + if they can be more efficiently implemented using the new features + found in <acronym class="acronym">BIND</acronym> 9. + </p> + + <p> + <acronym class="acronym">BIND</acronym> 4 configuration files can be + converted to the new format + using the shell script + <code class="filename">contrib/named-bootconf/named-bootconf.sh</code>. + </p> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="configuration_file_elements"></a>Configuration File Elements</h2></div></div></div> + + <p> + Following is a list of elements used throughout the <acronym class="acronym">BIND</acronym> configuration + file documentation: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.855in" class="1"> +<col width="3.770in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="varname">acl_name</code> + </p> + </td> +<td> + <p> + The name of an <code class="varname">address_match_list</code> as + defined by the <span class="command"><strong>acl</strong></span> statement. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">address_match_list</code> + </p> + </td> +<td> + <p> + A list of one or more + <code class="varname">ip_addr</code>, + <code class="varname">ip_prefix</code>, <code class="varname">key_id</code>, + or <code class="varname">acl_name</code> elements, see + <a class="xref" href="Bv9ARM.ch06.html#address_match_lists" title="Address Match Lists">the section called “Address Match Lists”</a>. + </p> + </td> +</tr> +<tr> +<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> + with optional <code class="varname">key_id</code> and/or + <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> +<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> +<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> +<td> + <p> + <code class="varname">dotted_decimal</code> + </p> + </td> +<td> + <p> + One to four integers valued 0 through + 255 separated by dots (`.'), such as <span 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>. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ip4_addr</code> + </p> + </td> +<td> + <p> + An IPv4 address with exactly four elements + in <code class="varname">dotted_decimal</code> notation. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ip6_addr</code> + </p> + </td> +<td> + <p> + An IPv6 address, such as <span class="command"><strong>2001:db8::1234</strong></span>. + 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 + are supported, assuming one-to-one mapping between + interfaces and links. For example, a link-local + 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>. + Note that on most systems link-local addresses + always have the ambiguity, and need to be + disambiguated. + </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> +<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> +<td> + <p> + <code class="varname">ip_port</code> + </p> + </td> +<td> + <p> + An IP port <code class="varname">number</code>. + The <code class="varname">number</code> is limited to 0 + through 65535, with values + below 1024 typically restricted to use by processes running + as root. + In some cases, an asterisk (`*') character can be used as a + placeholder to + select a random high-numbered port. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ip_prefix</code> + </p> + </td> +<td> + <p> + An IP network specified as an <code class="varname">ip_addr</code>, + followed by a slash (`/') and then the number of bits in the + netmask. + Trailing zeros in a <code class="varname">ip_addr</code> + may omitted. + For example, <span 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>. + </p> + <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> + </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> + A non-negative 32-bit integer + (i.e., a number between 0 and 4294967295, inclusive). + Its acceptable value might be further + limited by the context in which it is used. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">fixedpoint</code> + </p> + </td> +<td> + <p> + A non-negative real number that can be specified to + the nearest one hundredth. Up to five digits can be + specified before a decimal point, and up to two + digits after, so the maximum value is 99999.99. + Acceptable values might be further 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> +<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> +<td> + <p> + <code class="varname">size_spec</code> + </p> + </td> +<td> + <p> + A 64-bit unsigned integer, or the keywords + <strong class="userinput"><code>unlimited</code></strong> or + <strong class="userinput"><code>default</code></strong>. + </p> + <p> + Integers may take values + 0 <= value <= 18446744073709551615, though + certain parameters + (such as <span class="command"><strong>max-journal-size</strong></span>) may + use a more limited range within these extremes. + In most cases, setting a value to 0 does not + literally mean zero; it means "undefined" or + "as big as possible", depending on the context. + See the explanations of particular parameters + that use <code class="varname">size_spec</code> + for details on how they interpret its use. + </p> + <p> + Numeric values can optionally be followed by a + scaling factor: + <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 + <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. + </p> + <p> + <code class="varname">unlimited</code> generally means + "as big as possible", and is usually the best + way to safely set a very large number. + </p> + <p> + <code class="varname">default</code> + uses the limit that was in force when the server was started. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">size_or_percent</code> + </p> + </td> +<td> + <p> + <code class="varname">size_spec</code> or integer value + followed by '%' to represent percents. + </p> + <p> + The behavior is exactly the same as + <code class="varname">size_spec</code>, but + <code class="varname">size_or_percent</code> allows also + to specify a positive integer value followed by + '%' sign to represent percents. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">yes_or_no</code> + </p> + </td> +<td> + <p> + Either <strong class="userinput"><code>yes</code></strong> or <strong class="userinput"><code>no</code></strong>. + The words <strong class="userinput"><code>true</code></strong> and <strong class="userinput"><code>false</code></strong> are + also accepted, as are the numbers <strong class="userinput"><code>1</code></strong> + and <strong class="userinput"><code>0</code></strong>. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">dialup_option</code> + </p> + </td> +<td> + <p> + One of <strong class="userinput"><code>yes</code></strong>, + <strong class="userinput"><code>no</code></strong>, <strong class="userinput"><code>notify</code></strong>, + <strong class="userinput"><code>notify-passive</code></strong>, <strong class="userinput"><code>refresh</code></strong> or + <strong class="userinput"><code>passive</code></strong>. + When used in a zone, <strong class="userinput"><code>notify-passive</code></strong>, + <strong class="userinput"><code>refresh</code></strong>, and <strong class="userinput"><code>passive</code></strong> + are restricted to slave and stub zones. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="address_match_lists"></a>Address Match Lists</h3></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.4.4.2"></a>Syntax</h4></div></div></div> + +<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> ) +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.4.4.3"></a>Definition and Usage</h4></div></div></div> + + <p> + Address match lists are primarily used to determine access + control for various server operations. They are also used in + the <span class="command"><strong>listen-on</strong></span> and <span class="command"><strong>sortlist</strong></span> + statements. The elements which constitute an address match + list can be any of the following: + </p> + <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> +<li class="listitem"> + + a key ID, as defined by the <span class="command"><strong>key</strong></span> + statement + + </li> +<li class="listitem"> + the name of an address match list defined with + the <span class="command"><strong>acl</strong></span> statement + + </li> +<li class="listitem"> + a nested address match list enclosed in braces + </li> +</ul></div> + + <p> + Elements can be negated with a leading exclamation mark (`!'), + and the match list names "any", "none", "localhost", and + "localnets" are predefined. More information on those names + can be found in the description of the acl statement. + </p> + + <p> + The addition of the key clause made the name of this syntactic + element something of a misnomer, since security keys can be used + to validate access without regard to a host or network address. + Nonetheless, the term "address match list" is still used + throughout the documentation. + </p> + + <p> + When a given IP address or prefix is compared to an address + match list, the comparison takes place in approximately O(1) + time. However, key comparisons require that the list of keys + be traversed until a matching key is found, and therefore may + be somewhat slower. + </p> + + <p> + The interpretation of a match depends on whether the list is being + 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. + </p> + + <p> + When used as an access control list, a non-negated match + allows access and a negated match denies access. If + there is no match, access is denied. The clauses + <span 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 + server to refuse queries on any of the machine's + addresses which do not match the list. + </p> + + <p> + Order of insertion is significant. If more than one element + in an ACL is found to match a given IP address or prefix, + preference will be given to the one that came + <span class="emphasis"><em>first</em></span> in the ACL definition. + Because of this first-match behavior, an element that + defines a subset of another element in the list should + come before the broader element, regardless of whether + either is negated. For example, in + <span class="command"><strong>1.2.3/24; ! 1.2.3.13;</strong></span> + the 1.2.3.13 element is completely useless because the + algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24 + element. Using <span class="command"><strong>! 1.2.3.13; 1.2.3/24</strong></span> fixes + that problem by having 1.2.3.13 blocked by the negation, but + all other 1.2.3.* hosts fall through. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="comment_syntax"></a>Comment Syntax</h3></div></div></div> + + <p> + The <acronym class="acronym">BIND</acronym> 9 comment syntax allows for + comments to appear + anywhere that whitespace may appear in a <acronym class="acronym">BIND</acronym> configuration + file. To appeal to programmers of all kinds, they can be written + in the C, C++, or shell/perl style. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.4.5.3"></a>Syntax</h4></div></div></div> + + <p> + </p> +<pre class="programlisting">/* This is a <acronym class="acronym">BIND</acronym> comment as in C */</pre> +<p> + </p> +<pre class="programlisting">// This is a <acronym class="acronym">BIND</acronym> comment as in C++</pre> +<p> + </p> +<pre class="programlisting"># This is a <acronym class="acronym">BIND</acronym> comment as in common UNIX shells +# and perl</pre> +<p> + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.4.5.4"></a>Definition and Usage</h4></div></div></div> + + <p> + Comments may appear anywhere that whitespace may appear in + a <acronym class="acronym">BIND</acronym> configuration file. + </p> + <p> + C-style comments start with the two characters /* (slash, + star) and end with */ (star, slash). Because they are completely + delimited with these characters, they can be used to comment only + a portion of a line or to span multiple lines. + </p> + <p> + C-style comments cannot be nested. For example, the following + is not valid because the entire comment ends with the first */: + </p> + <p> + +</p> +<pre class="programlisting">/* This is the start of a comment. + This is still part of the comment. +/* This is an incorrect attempt at nesting a comment. */ + This is no longer in any comment. */ +</pre> +<p> + + </p> + + <p> + C++-style comments start with the two characters // (slash, + slash) and continue to the end of the physical line. They cannot + be continued across multiple physical lines; to have one logical + comment span multiple lines, each line must use the // pair. + For example: + </p> + <p> + +</p> +<pre class="programlisting">// This is the start of a comment. The next line +// is a new comment, even though it is logically +// part of the previous comment. +</pre> +<p> + + </p> + <p> + Shell-style (or perl-style, if you prefer) comments start + with the character <code class="literal">#</code> (number sign) + and continue to the end of the + physical line, as in C++ comments. + For example: + </p> + + <p> + +</p> +<pre class="programlisting"># This is the start of a comment. The next line +# is a new comment, even though it is logically +# part of the previous comment. +</pre> +<p> + + </p> + + <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Warning</h3> + <p> + You cannot use the semicolon (`;') character + to start a comment such as you would in a zone file. The + semicolon indicates the end of a configuration + statement. + </p> + </div> + </div> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="Configuration_File_Grammar"></a>Configuration File Grammar</h2></div></div></div> + + <p> + A <acronym class="acronym">BIND</acronym> 9 configuration consists of + statements and comments. + Statements end with a semicolon. Statements and comments are the + only elements that can appear without enclosing braces. Many + statements contain a block of sub-statements, which are also + terminated with a semicolon. + </p> + + <p> + The following statements are supported: + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.336in" class="1"> +<col width="3.778in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>acl</strong></span></p> + </td> +<td> + <p> + defines a named IP address + matching list, for access control and other uses. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>controls</strong></span></p> + </td> +<td> + <p> + declares control channels to be used + by the <span class="command"><strong>rndc</strong></span> utility. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>include</strong></span></p> + </td> +<td> + <p> + includes a file. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>key</strong></span></p> + </td> +<td> + <p> + specifies key information for use in + authentication and authorization using TSIG. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>logging</strong></span></p> + </td> +<td> + <p> + specifies what the server logs, and where + the log messages are sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>lwres</strong></span></p> + </td> +<td> + <p> + configures <span class="command"><strong>named</strong></span> to + also act as a light-weight resolver daemon (<span class="command"><strong>lwresd</strong></span>). + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>masters</strong></span></p> + </td> +<td> + <p> + defines a named masters list for + inclusion in stub and slave zones' + <span class="command"><strong>masters</strong></span> or + <span class="command"><strong>also-notify</strong></span> lists. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>options</strong></span></p> + </td> +<td> + <p> + controls global server configuration + options and sets defaults for other statements. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>server</strong></span></p> + </td> +<td> + <p> + sets certain configuration options on + a per-server basis. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>statistics-channels</strong></span></p> + </td> +<td> + <p> + declares communication channels to get access to + <span class="command"><strong>named</strong></span> statistics. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>trusted-keys</strong></span></p> + </td> +<td> + <p> + defines trusted DNSSEC keys. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>managed-keys</strong></span></p> + </td> +<td> + <p> + lists DNSSEC keys to be kept up to date + using RFC 5011 trust anchor maintenance. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>view</strong></span></p> + </td> +<td> + <p> + defines a view. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>zone</strong></span></p> + </td> +<td> + <p> + defines a zone. + </p> + </td> +</tr> +</tbody> +</table> + </div> + + <p> + The <span class="command"><strong>logging</strong></span> and + <span class="command"><strong>options</strong></span> statements may only occur once + per + configuration. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="acl_grammar"></a><span class="command"><strong>acl</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>acl</strong></span> <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>address_match_element</code></em>; ... }; +</pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="acl"></a><span class="command"><strong>acl</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>acl</strong></span> statement assigns a symbolic + name to an address match list. It gets its name from a primary + use of address match lists: Access Control Lists (ACLs). + </p> + + <p> + The following ACLs are built-in: + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.130in" class="1"> +<col width="4.000in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>any</strong></span></p> + </td> +<td> + <p> + Matches all hosts. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>none</strong></span></p> + </td> +<td> + <p> + Matches no hosts. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>localhost</strong></span></p> + </td> +<td> + <p> + Matches the IPv4 and IPv6 addresses of all network + interfaces on the system. When addresses are + added or removed, the <span class="command"><strong>localhost</strong></span> + ACL element is updated to reflect the changes. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>localnets</strong></span></p> + </td> +<td> + <p> + Matches any host on an IPv4 or IPv6 network + for which the system has an interface. + When addresses are added or removed, + the <span class="command"><strong>localnets</strong></span> + ACL element is updated to reflect the changes. + Some systems do not provide a way to determine the prefix + lengths of + local IPv6 addresses. + In such a case, <span class="command"><strong>localnets</strong></span> + only matches the local + IPv6 addresses, just like <span class="command"><strong>localhost</strong></span>. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="controls_grammar"></a><span class="command"><strong>controls</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>controls</strong></span> { + <span class="command"><strong>inet</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> | + * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] allow + { <em class="replaceable"><code>address_match_element</code></em>; ... } [ + <span class="command"><strong>keys</strong></span> { <em class="replaceable"><code>string</code></em>; ... } ] [ read-only + <em class="replaceable"><code>boolean</code></em> ]; + <span class="command"><strong>unix</strong></span> <em class="replaceable"><code>quoted_string</code></em> perm <em class="replaceable"><code>integer</code></em> + <span class="command"><strong>owner</strong></span> <em class="replaceable"><code>integer</code></em> group <em class="replaceable"><code>integer</code></em> [ + <span class="command"><strong>keys</strong></span> { <em class="replaceable"><code>string</code></em>; ... } ] [ read-only + <em class="replaceable"><code>boolean</code></em> ]; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="controls_statement_definition_and_usage"></a><span class="command"><strong>controls</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>controls</strong></span> statement declares control + channels to be used by system administrators to control the + operation of the name server. These control channels are + used by the <span class="command"><strong>rndc</strong></span> utility to send + commands to and retrieve non-DNS results from a name server. + </p> + + <p> + 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 + 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, + 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, + using the loopback address (<code class="literal">127.0.0.1</code> + or <code class="literal">::1</code>) is recommended for maximum security. + </p> + + <p> + If no port is specified, port 953 is used. The asterisk + "<code class="literal">*</code>" cannot be used for <span class="command"><strong>ip_port</strong></span>. + </p> + + <p> + The ability to issue commands over the control channel is + restricted by the <span class="command"><strong>allow</strong></span> and + <span class="command"><strong>keys</strong></span> clauses. + Connections to the control channel are permitted based on the + <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> + are ignored. + </p> + + <p> + A <span class="command"><strong>unix</strong></span> control channel is a UNIX domain + socket listening at the specified path in the file system. + 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. + Note on some platforms (SunOS and Solaris) the permissions + (<span class="command"><strong>perm</strong></span>) are applied to the parent directory + as the permissions on the socket itself are ignored. + </p> + + <p> + The primary authorization mechanism of the command + 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> + is authorized to execute commands over the control channel. + 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 “Administrative Tools”</a>) + for information about configuring keys in <span class="command"><strong>rndc</strong></span>. + </p> + + <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> + + <p> + If no <span class="command"><strong>controls</strong></span> statement is present, + <span class="command"><strong>named</strong></span> will set up a default + control channel listening on the loopback address 127.0.0.1 + and its IPv6 counterpart ::1. + In this case, and also when the <span 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 + from the file <code class="filename">rndc.key</code> in + <code class="filename">/etc</code> (or whatever <code class="varname">sysconfdir</code> + was specified as when <acronym class="acronym">BIND</acronym> was built). + To create a <code class="filename">rndc.key</code> file, run + <strong class="userinput"><code>rndc-confgen -a</code></strong>. + </p> + + <p> + The <code class="filename">rndc.key</code> feature was created to + ease the transition of systems from <acronym class="acronym">BIND</acronym> 8, + which did not have digital signatures on its command channel + messages and thus did not have a <span class="command"><strong>keys</strong></span> clause. + + It makes it possible to use an existing <acronym class="acronym">BIND</acronym> 8 + configuration file in <acronym class="acronym">BIND</acronym> 9 unchanged, + 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 + command <strong class="userinput"><code>rndc-confgen -a</code></strong> after BIND 9 is + installed. + </p> + + <p> + Since the <code class="filename">rndc.key</code> feature + is only intended to allow the backward-compatible usage of + <acronym class="acronym">BIND</acronym> 8 configuration files, this + feature does not + have a high degree of configurability. You cannot easily change + the key name or the size of the secret, so you should make a + <code class="filename">rndc.conf</code> with your own key if you + wish to change + those things. The <code class="filename">rndc.key</code> file + also has its + permissions set such that only the owner of the file (the user that + <span class="command"><strong>named</strong></span> is running as) can access it. + If you + desire greater flexibility in allowing other users to access + <span class="command"><strong>rndc</strong></span> commands, then you need to create + a + <code class="filename">rndc.conf</code> file and make it group + readable by a group + that contains the users who should have access. + </p> + + <p> + To disable the command channel, use an empty + <span class="command"><strong>controls</strong></span> statement: + <span class="command"><strong>controls { };</strong></span>. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="include_grammar"></a><span class="command"><strong>include</strong></span> Statement Grammar</h3></div></div></div> + + <pre class="programlisting"><span class="command"><strong>include</strong></span> <em class="replaceable"><code>filename</code></em><span class="command"><strong>;</strong></span></pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="include_statement"></a><span class="command"><strong>include</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + 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> + statement facilitates the administration of configuration + files + by permitting the reading or writing of some things but not + others. For example, the statement could include private keys + that are readable only by the name server. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="key_grammar"></a><span class="command"><strong>key</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>key</strong></span> <em class="replaceable"><code>string</code></em> { + <span class="command"><strong>algorithm</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>secret</strong></span> <em class="replaceable"><code>string</code></em>; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="key_statement"></a><span class="command"><strong>key</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + 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 “TSIG”</a>) + or the command channel + (see <a class="xref" href="Bv9ARM.ch06.html#controls_statement_definition_and_usage" title="controls Statement Definition and Usage">the section called “<span class="command"><strong>controls</strong></span> Statement Definition and + Usage”</a>). + </p> + + <p> + The <span class="command"><strong>key</strong></span> statement can occur at the + top level + 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> + statements can be used in all views. Keys intended for use in + 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 “<span class="command"><strong>controls</strong></span> Statement Definition and + Usage”</a>) + must be defined at the top level. + </p> + + <p> + The <em class="replaceable"><code>key_id</code></em>, also known as the + key name, is a domain name uniquely identifying the key. It can + be used in a <span class="command"><strong>server</strong></span> + statement to cause requests sent to that + server to be signed with this key, or in address match lists to + verify that incoming requests have been signed with a key + matching this name, algorithm, and secret. + </p> + + <p> + The <em class="replaceable"><code>algorithm_id</code></em> is a string + that specifies a security/authentication algorithm. The + <span class="command"><strong>named</strong></span> server supports <code class="literal">hmac-md5</code>, + <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 + number of required bits preceded by a dash, e.g. + <code class="literal">hmac-sha1-80</code>. The + <em class="replaceable"><code>secret_string</code></em> is the secret + to be used by the algorithm, and is treated as a Base64 + encoded string. + </p> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="logging_grammar"></a><span class="command"><strong>logging</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>logging</strong></span> { + <span class="command"><strong>category</strong></span> <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>; ... }; + <span class="command"><strong>channel</strong></span> <em class="replaceable"><code>string</code></em> { + <span class="command"><strong>buffered</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em> [ versions ( "unlimited" | <em class="replaceable"><code>integer</code></em> ) + ] [ size <em class="replaceable"><code>size</code></em> ]; + <span class="command"><strong>null</strong></span>; + <span class="command"><strong>print-category</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>print-severity</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>print-time</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>severity</strong></span> <em class="replaceable"><code>log_severity</code></em>; + <span class="command"><strong>stderr</strong></span>; + <span class="command"><strong>syslog</strong></span> [ <em class="replaceable"><code>syslog_facility</code></em> ]; + }; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="logging_statement"></a><span class="command"><strong>logging</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>logging</strong></span> statement configures a + wide + variety of logging options for the name server. Its <span class="command"><strong>channel</strong></span> phrase + associates output methods, format options and severity levels with + a name that can then be used with the <span class="command"><strong>category</strong></span> phrase + to select how various classes of messages are logged. + </p> + <p> + Only one <span class="command"><strong>logging</strong></span> statement is used to + define + as many channels and categories as are wanted. If there is no <span class="command"><strong>logging</strong></span> statement, + the logging configuration will be: + </p> + +<pre class="programlisting">logging { + category default { default_syslog; default_debug; }; + category unmatched { null; }; +}; +</pre> + + <p> + If <span class="command"><strong>named</strong></span> is started with the + <code class="option">-L</code> option, it logs to the specified file + at startup, instead of using syslog. In this case the logging + configuration will be: + </p> + +<pre class="programlisting">logging { + category default { default_logfile; default_debug; }; + category unmatched { null; }; +}; +</pre> + + <p> + In <acronym class="acronym">BIND</acronym> 9, the logging configuration + is only established when + the entire configuration file has been parsed. In <acronym class="acronym">BIND</acronym> 8, it was + established as soon as the <span class="command"><strong>logging</strong></span> + statement + was parsed. When the server is starting up, all logging messages + regarding syntax errors in the configuration file go to the default + channels, or to standard error if the <code class="option">-g</code> option + was specified. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="channel"></a>The <span class="command"><strong>channel</strong></span> Phrase</h4></div></div></div> + + <p> + All log output goes to one or more <span class="emphasis"><em>channels</em></span>; + you can make as many of them as you want. + </p> + + <p> + Every channel definition must include a destination clause that + says whether messages selected for the channel go to a file, to a + particular syslog facility, to the standard error stream, or are + discarded. It can optionally also limit the message severity level + that will be accepted by the channel (the default is + <span class="command"><strong>info</strong></span>), and whether to include a + <span class="command"><strong>named</strong></span>-generated time stamp, the + category name + and/or severity level (the default is not to include any). + </p> + + <p> + The <span class="command"><strong>null</strong></span> destination clause + causes all messages sent to the channel to be discarded; + in that case, other options for the channel are meaningless. + </p> + + <p> + The <span class="command"><strong>file</strong></span> destination clause directs + the channel + to a disk file. It can include limitations + both on how large the file is allowed to become, and how many + versions + of the file will be saved each time the file is opened. + </p> + + <p> + If you use the <span class="command"><strong>versions</strong></span> log file + option, then + <span class="command"><strong>named</strong></span> will retain that many backup + versions of the file by + renaming them when opening. For example, if you choose to keep + three old versions + of the file <code class="filename">lamers.log</code>, then just + before it is opened + <code class="filename">lamers.log.1</code> is renamed to + <code class="filename">lamers.log.2</code>, <code class="filename">lamers.log.0</code> is renamed + to <code class="filename">lamers.log.1</code>, and <code class="filename">lamers.log</code> is + renamed to <code class="filename">lamers.log.0</code>. + You can say <span class="command"><strong>versions unlimited</strong></span> to + not limit + the number of versions. + If a <span class="command"><strong>size</strong></span> option is associated with + the log file, + then renaming is only done when the file being opened exceeds the + indicated size. No backup versions are kept by default; any + existing + log file is simply appended. + </p> + + <p> + The <span class="command"><strong>size</strong></span> option for files is used + to limit log + growth. If the file ever exceeds the size, then <span class="command"><strong>named</strong></span> will + stop writing to the file unless it has a <span class="command"><strong>versions</strong></span> option + associated with it. If backup versions are kept, the files are + rolled as + described above and a new one begun. If there is no + <span class="command"><strong>versions</strong></span> option, no more data will + be written to the log + until some out-of-band mechanism removes or truncates the log to + less than the + maximum size. The default behavior is not to limit the size of + the + file. + </p> + + <p> + Example usage of the <span class="command"><strong>size</strong></span> and + <span class="command"><strong>versions</strong></span> options: + </p> + +<pre class="programlisting">channel an_example_channel { + file "example.log" versions 3 size 20m; + print-time yes; + print-category yes; +}; +</pre> + + <p> + The <span class="command"><strong>syslog</strong></span> destination clause + directs the + channel to the system log. Its argument is a + syslog facility as described in the <span class="command"><strong>syslog</strong></span> man + page. Known facilities are <span class="command"><strong>kern</strong></span>, <span class="command"><strong>user</strong></span>, + <span class="command"><strong>mail</strong></span>, <span class="command"><strong>daemon</strong></span>, <span class="command"><strong>auth</strong></span>, + <span class="command"><strong>syslog</strong></span>, <span class="command"><strong>lpr</strong></span>, <span class="command"><strong>news</strong></span>, + <span class="command"><strong>uucp</strong></span>, <span class="command"><strong>cron</strong></span>, <span class="command"><strong>authpriv</strong></span>, + <span class="command"><strong>ftp</strong></span>, <span class="command"><strong>local0</strong></span>, <span class="command"><strong>local1</strong></span>, + <span class="command"><strong>local2</strong></span>, <span class="command"><strong>local3</strong></span>, <span class="command"><strong>local4</strong></span>, + <span class="command"><strong>local5</strong></span>, <span class="command"><strong>local6</strong></span> and + <span class="command"><strong>local7</strong></span>, however not all facilities + are supported on + all operating systems. + How <span class="command"><strong>syslog</strong></span> will handle messages + sent to + this facility is described in the <span class="command"><strong>syslog.conf</strong></span> man + page. If you have a system which uses a very old version of <span class="command"><strong>syslog</strong></span> that + only uses two arguments to the <span class="command"><strong>openlog()</strong></span> function, + then this clause is silently ignored. + </p> + <p> + On Windows machines syslog messages are directed to the EventViewer. + </p> + <p> + The <span class="command"><strong>severity</strong></span> clause works like <span class="command"><strong>syslog</strong></span>'s + "priorities", except that they can also be used if you are writing + straight to a file rather than using <span class="command"><strong>syslog</strong></span>. + Messages which are not at least of the severity level given will + not be selected for the channel; messages of higher severity + levels + will be accepted. + </p> + <p> + If you are using <span class="command"><strong>syslog</strong></span>, then the <span class="command"><strong>syslog.conf</strong></span> priorities + will also determine what eventually passes through. For example, + defining a channel facility and severity as <span class="command"><strong>daemon</strong></span> and <span class="command"><strong>debug</strong></span> but + only logging <span class="command"><strong>daemon.warning</strong></span> via <span class="command"><strong>syslog.conf</strong></span> will + cause messages of severity <span class="command"><strong>info</strong></span> and + <span class="command"><strong>notice</strong></span> to + be dropped. If the situation were reversed, with <span class="command"><strong>named</strong></span> writing + messages of only <span class="command"><strong>warning</strong></span> or higher, + then <span class="command"><strong>syslogd</strong></span> would + print all messages it received from the channel. + </p> + + <p> + The <span class="command"><strong>stderr</strong></span> destination clause + directs the + channel to the server's standard error stream. This is intended + for + use when the server is running as a foreground process, for + example + when debugging a configuration. + </p> + + <p> + The server can supply extensive debugging information when + it is in debugging mode. If the server's global debug level is + greater + than zero, then debugging mode will be active. The global debug + level is set either by starting the <span class="command"><strong>named</strong></span> server + with the <code class="option">-d</code> flag followed by a positive integer, + or by running <span class="command"><strong>rndc trace</strong></span>. + The global debug level + can be set to zero, and debugging mode turned off, by running <span class="command"><strong>rndc +notrace</strong></span>. All debugging messages in the server have a debug + level, and higher debug levels give more detailed output. Channels + that specify a specific debug severity, for example: + </p> + +<pre class="programlisting">channel specific_debug_level { + file "foo"; + severity debug 3; +}; +</pre> + + <p> + will get debugging output of level 3 or less any time the + server is in debugging mode, regardless of the global debugging + level. Channels with <span class="command"><strong>dynamic</strong></span> + severity use the + server's global debug level to determine what messages to print. + </p> + <p> + If <span class="command"><strong>print-time</strong></span> has been turned on, + then + the date and time will be logged. <span class="command"><strong>print-time</strong></span> may + be specified for a <span class="command"><strong>syslog</strong></span> channel, + but is usually + pointless since <span class="command"><strong>syslog</strong></span> also logs + the date and + time. If <span class="command"><strong>print-category</strong></span> is + requested, then the + category of the message will be logged as well. Finally, if <span class="command"><strong>print-severity</strong></span> is + on, then the severity level of the message will be logged. The <span class="command"><strong>print-</strong></span> options may + be used in any combination, and will always be printed in the + following + order: time, category, severity. Here is an example where all + three <span class="command"><strong>print-</strong></span> options + are on: + </p> + + <p> + <code class="computeroutput">28-Feb-2000 15:05:32.863 general: notice: running</code> + </p> + + <p> + If <span class="command"><strong>buffered</strong></span> has been turned on the output + to files will not be flushed after each log entry. By default + all log messages are flushed. + </p> + + <p> + There are four predefined channels that are used for + <span class="command"><strong>named</strong></span>'s default logging as follows. + If <span class="command"><strong>named</strong></span> is started with the + <code class="option">-L</code> then a + fifth channel <span class="command"><strong>default_logfile</strong></span> is added. + How they are + used is described in <a class="xref" href="Bv9ARM.ch06.html#the_category_phrase" title="The category Phrase">the section called “The <span class="command"><strong>category</strong></span> Phrase”</a>. + </p> + +<pre class="programlisting">channel default_syslog { + // send to syslog's daemon facility + syslog daemon; + // only send priority info and higher + severity info; +}; + +channel default_debug { + // write to named.run in the working directory + // Note: stderr is used instead of "named.run" if + // the server is started with the '-g' option. + file "named.run"; + // log at the server's current debug level + severity dynamic; +}; + +channel default_stderr { + // writes to stderr + stderr; + // only send priority info and higher + severity info; +}; + +channel null { + // toss anything sent to this channel + null; +}; + +channel default_logfile { + // this channel is only present if named is + // started with the -L option, whose argument + // provides the file name + file "..."; + // log at the server's current debug level + severity dynamic; +}; +</pre> + + <p> + The <span class="command"><strong>default_debug</strong></span> channel has the + special + property that it only produces output when the server's debug + level is + nonzero. It normally writes to a file called <code class="filename">named.run</code> + in the server's working directory. + </p> + + <p> + For security reasons, when the <code class="option">-u</code> + command line option is used, the <code class="filename">named.run</code> file + is created only after <span class="command"><strong>named</strong></span> has + changed to the + new UID, and any debug output generated while <span class="command"><strong>named</strong></span> is + starting up and still running as root is discarded. If you need + to capture this output, you must run the server with the <code class="option">-L</code> + option to specify a default logfile, or the <code class="option">-g</code> + option to log to standard error which you can redirect to a file. + </p> + + <p> + Once a channel is defined, it cannot be redefined. Thus you + cannot alter the built-in channels directly, but you can modify + the default logging by pointing categories at channels you have + defined. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="the_category_phrase"></a>The <span class="command"><strong>category</strong></span> Phrase</h4></div></div></div> + + <p> + There are many categories, so you can send the logs you want + to see wherever you want, without seeing logs you don't want. If + you don't specify a list of channels for a category, then log + messages + in that category will be sent to the <span class="command"><strong>default</strong></span> category + instead. If you don't specify a default category, the following + "default default" is used: + </p> + +<pre class="programlisting">category default { default_syslog; default_debug; }; +</pre> + + <p> + If you start <span class="command"><strong>named</strong></span> with the + <code class="option">-L</code> option then the default category is: + </p> + +<pre class="programlisting">category default { default_logfile; default_debug; }; +</pre> + + <p> + As an example, let's say you want to log security events to + a file, but you also want keep the default logging behavior. You'd + specify the following: + </p> + +<pre class="programlisting">channel my_security_channel { + file "my_security_file"; + severity info; +}; +category security { + my_security_channel; + default_syslog; + default_debug; +};</pre> + + <p> + To discard all messages in a category, specify the <span class="command"><strong>null</strong></span> channel: + </p> + +<pre class="programlisting">category xfer-out { null; }; +category notify { null; }; +</pre> + + <p> + Following are the available categories and brief descriptions + of the types of log information they contain. More + categories may be added in future <acronym class="acronym">BIND</acronym> releases. + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="3.350in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>client</strong></span></p> + </td> +<td> + <p> + Processing of client requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>cname</strong></span></p> + </td> +<td> + <p> + Logs nameservers that are skipped due to them being + a CNAME rather than A / AAAA records. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>config</strong></span></p> + </td> +<td> + <p> + Configuration file parsing and processing. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>database</strong></span></p> + </td> +<td> + <p> + Messages relating to the databases used + internally by the name server to store zone and cache + data. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>default</strong></span></p> + </td> +<td> + <p> + The default category defines the logging + options for those categories where no specific + configuration has been + defined. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>delegation-only</strong></span></p> + </td> +<td> + <p> + Delegation only. Logs queries that have been + forced to NXDOMAIN as the result of a + delegation-only zone or a + <span class="command"><strong>delegation-only</strong></span> in a + forward, hint or stub zone declaration. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>dispatch</strong></span></p> + </td> +<td> + <p> + Dispatching of incoming packets to the + server modules where they are to be processed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>dnssec</strong></span></p> + </td> +<td> + <p> + DNSSEC and TSIG protocol processing. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>dnstap</strong></span></p> + </td> +<td> + <p> + The "dnstap" DNS traffic capture system. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>edns-disabled</strong></span></p> + </td> +<td> + <p> + Log queries that have been forced to use plain + DNS due to timeouts. This is often due to + the remote servers not being RFC 1034 compliant + (not always returning FORMERR or similar to + EDNS queries and other extensions to the DNS + when they are not understood). In other words, this is + targeted at servers that fail to respond to + DNS queries that they don't understand. + </p> + <p> + Note: the log message can also be due to + packet loss. Before reporting servers for + non-RFC 1034 compliance they should be re-tested + to determine the nature of the non-compliance. + This testing should prevent or reduce the + number of false-positive reports. + </p> + <p> + Note: eventually <span class="command"><strong>named</strong></span> will have to stop + treating such timeouts as due to RFC 1034 non + compliance and start treating it as plain + packet loss. Falsely classifying packet + loss as due to RFC 1034 non compliance impacts + on DNSSEC validation which requires EDNS for + the DNSSEC records to be returned. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>general</strong></span></p> + </td> +<td> + <p> + The catch-all. Many things still aren't + classified into categories, and they all end up here. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>lame-servers</strong></span></p> + </td> +<td> + <p> + Lame servers. These are misconfigurations + in remote servers, discovered by BIND 9 when trying to + query those servers during resolution. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>network</strong></span></p> + </td> +<td> + <p> + Network operations. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>notify</strong></span></p> + </td> +<td> + <p> + The NOTIFY protocol. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>queries</strong></span></p> + </td> +<td> + <p> + Specify where queries should be logged to. + </p> + <p> + At startup, specifying the category <span class="command"><strong>queries</strong></span> will also + enable query logging unless <span class="command"><strong>querylog</strong></span> option has been + specified. + </p> + + <p> + The query log entry first reports a client object + identifier in @0x<hexadecimal-number> + format. Next, it reports the client's IP + address and port number, and the query name, + class and type. Next, it reports whether the + Recursion Desired flag was set (+ if set, - + if not set), if the query was signed (S), + EDNS was in used along with the EDNS version + number (E(#)), if TCP was used (T), if DO + (DNSSEC Ok) was set (D), if CD (Checking + Disabled) was set (C), if a valid DNS Server + COOKIE was received (V), or if a DNS COOKIE + option without a valid Server COOKIE was + present (K). After this the destination + address the query was sent to is reported. + </p> + + <p> + <code class="computeroutput">client 127.0.0.1#62536 (www.example.com): query: www.example.com IN AAAA +SE</code> + </p> + <p> + <code class="computeroutput">client ::1#62537 (www.example.net): query: www.example.net IN AAAA -SE</code> + </p> + <p> + (The first part of this log message, showing the + client address/port number and query name, is + repeated in all subsequent log messages related + to the same query.) + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>query-errors</strong></span></p> + </td> +<td> + <p> + Information about queries that resulted in some + failure. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>rate-limit</strong></span></p> + </td> +<td> + <p> + The start, periodic, and final notices of the + rate limiting of a stream of responses are logged at + <span class="command"><strong>info</strong></span> severity in this category. + These messages include a hash value of the domain name + of the response and the name itself, + except when there is insufficient memory to record + the name for the final notice + The final notice is normally delayed until about one + minute after rate limit stops. + A lack of memory can hurry the final notice, + in which case it starts with an asterisk (*). + Various internal events are logged at debug 1 level + and higher. + </p> + <p> + Rate limiting of individual requests + is logged in the <span class="command"><strong>query-errors</strong></span> category. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>resolver</strong></span></p> + </td> +<td> + <p> + DNS resolution, such as the recursive + lookups performed on behalf of clients by a caching name + server. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>rpz</strong></span></p> + </td> +<td> + <p> + Information about errors in response policy zone files, + rewritten responses, and at the highest + <span class="command"><strong>debug</strong></span> levels, mere rewriting + attempts. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>security</strong></span></p> + </td> +<td> + <p> + Approval and denial of requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>spill</strong></span></p> + </td> +<td> + <p> + Logs queries that have been terminated, either by dropping + or responding with SERVFAIL, as a result of a fetchlimit + quota being exceeded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>trust-anchor-telemetry</strong></span></p> + </td> +<td> + <p> + Logs trust-anchor-telemetry requests received by named. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>unmatched</strong></span></p> + </td> +<td> + <p> + Messages that <span class="command"><strong>named</strong></span> was unable to determine the + class of or for which there was no matching <span class="command"><strong>view</strong></span>. + A one line summary is also logged to the <span class="command"><strong>client</strong></span> category. + This category is best sent to a file or stderr, by + default it is sent to + the <span class="command"><strong>null</strong></span> channel. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>update</strong></span></p> + </td> +<td> + <p> + Dynamic updates. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>update-security</strong></span></p> + </td> +<td> + <p> + Approval and denial of update requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>xfer-in</strong></span></p> + </td> +<td> + <p> + Zone transfers the server is receiving. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>xfer-out</strong></span></p> + </td> +<td> + <p> + Zone transfers the server is sending. + </p> + </td> +</tr> +</tbody> +</table> +</div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="query_errors"></a>The <span class="command"><strong>query-errors</strong></span> Category</h4></div></div></div> + <p> + The <span class="command"><strong>query-errors</strong></span> category is + specifically intended for debugging purposes: To identify + why and how specific queries result in responses which + indicate an error. + Messages of this category are therefore only logged + with <span class="command"><strong>debug</strong></span> levels. + </p> + + <p> + At the debug levels of 1 or higher, each response with the + rcode of SERVFAIL is logged as follows: + </p> + <p> + <code class="computeroutput">client 127.0.0.1#61502: query failed (SERVFAIL) for www.example.com/IN/AAAA at query.c:3880</code> + </p> + <p> + This means an error resulting in SERVFAIL was + detected at line 3880 of source file + <code class="filename">query.c</code>. + Log messages of this level will particularly + help identify the cause of SERVFAIL for an + authoritative server. + </p> + <p> + At the debug levels of 2 or higher, detailed context + information of recursive resolutions that resulted in + SERVFAIL is logged. + The log message will look like as follows: + </p> + <p> + + </p> +<pre class="programlisting"> +fetch completed at resolver.c:2970 for www.example.com/A +in 30.000183: timed out/success [domain:example.com, +referral:2,restart:7,qrysent:8,timeout:5,lame:0,neterr:0, +badresp:1,adberr:0,findfail:0,valfail:0] + </pre> +<p> + </p> + <p> + The first part before the colon shows that a recursive + resolution for AAAA records of www.example.com completed + in 30.000183 seconds and the final result that led to the + SERVFAIL was determined at line 2970 of source file + <code class="filename">resolver.c</code>. + </p> + <p> + The following part shows the detected final result and the + latest result of DNSSEC validation. + The latter is always success when no validation attempt + is made. + In this example, this query resulted in SERVFAIL probably + because all name servers are down or unreachable, leading + to a timeout in 30 seconds. + DNSSEC validation was probably not attempted. + </p> + <p> + The last part enclosed in square brackets shows statistics + information collected for this particular resolution + attempt. + The <code class="varname">domain</code> field shows the deepest zone + that the resolver reached; + it is the zone where the error was finally detected. + The meaning of the other fields is summarized in the + following table. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="3.350in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><code class="varname">referral</code></p> + </td> +<td> + <p> + The number of referrals the resolver received + throughout the resolution process. + In the above example this is 2, which are most + likely com and example.com. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">restart</code></p> + </td> +<td> + <p> + The number of cycles that the resolver tried + remote servers at the <code class="varname">domain</code> + zone. + In each cycle the resolver sends one query + (possibly resending it, depending on the response) + to each known name server of + the <code class="varname">domain</code> zone. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">qrysent</code></p> + </td> +<td> + <p> + The number of queries the resolver sent at the + <code class="varname">domain</code> zone. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">timeout</code></p> + </td> +<td> + <p> + The number of timeouts since the resolver + received the last response. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">lame</code></p> + </td> +<td> + <p> + The number of lame servers the resolver detected + at the <code class="varname">domain</code> zone. + A server is detected to be lame either by an + invalid response or as a result of lookup in + BIND9's address database (ADB), where lame + servers are cached. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">neterr</code></p> + </td> +<td> + <p> + The number of erroneous results that the + resolver encountered in sending queries + at the <code class="varname">domain</code> zone. + One common case is the remote server is + unreachable and the resolver receives an ICMP + unreachable error message. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">badresp</code></p> + </td> +<td> + <p> + The number of unexpected responses (other than + <code class="varname">lame</code>) to queries sent by the + resolver at the <code class="varname">domain</code> zone. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">adberr</code></p> + </td> +<td> + <p> + Failures in finding remote server addresses + of the <code class="varname">domain</code> zone in the ADB. + One common case of this is that the remote + server's name does not have any address records. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">findfail</code></p> + </td> +<td> + <p> + Failures of resolving remote server addresses. + This is a total number of failures throughout + the resolution process. + </p> + </td> +</tr> +<tr> +<td> + <p><code class="varname">valfail</code></p> + </td> +<td> + <p> + Failures of DNSSEC validation. + Validation failures are counted throughout + the resolution process (not limited to + the <code class="varname">domain</code> zone), but should + only happen in <code class="varname">domain</code>. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + At the debug levels of 3 or higher, the same messages + as those at the debug 1 level are logged for other errors + than SERVFAIL. + Note that negative responses such as NXDOMAIN are not + regarded as errors here. + </p> + <p> + At the debug levels of 4 or higher, the same messages + as those at the debug 2 level are logged for other errors + than SERVFAIL. + Unlike the above case of level 3, messages are logged for + negative responses. + This is because any unexpected results can be difficult to + debug in the recursion case. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="lwres_grammar"></a><span class="command"><strong>lwres</strong></span> Statement Grammar</h3></div></div></div> + + <p> + This is the grammar of the <span class="command"><strong>lwres</strong></span> + statement in the <code class="filename">named.conf</code> file: + </p> + +<pre class="programlisting"><span class="command"><strong>lwres {</strong></span> + [ <span class="command"><strong>listen-on {</strong></span> + ( <em class="replaceable"><code>ip_addr</code></em> [ <span class="command"><strong>port</strong></span> <em class="replaceable"><code>ip_port</code></em> ] [ <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>ip_dscp</code></em> ] <span class="command"><strong>;</strong></span> ) + ... + <span class="command"><strong>};</strong></span> ] + [ <span class="command"><strong>view</strong></span> <em class="replaceable"><code>view_name</code></em><span class="command"><strong>;</strong></span> ] + [ <span class="command"><strong>search {</strong></span> <em class="replaceable"><code>domain_name</code></em> <span class="command"><strong>;</strong></span> ... <span class="command"><strong>};</strong></span> ] + [ <span class="command"><strong>ndots</strong></span> <em class="replaceable"><code>number</code></em><span class="command"><strong>;</strong></span> ] + [ <span class="command"><strong>lwres-tasks</strong></span> <em class="replaceable"><code>number</code></em><span class="command"><strong>;</strong></span> ] + [ <span class="command"><strong>lwres-clients</strong></span> <em class="replaceable"><code>number</code></em><span class="command"><strong>;</strong></span> ] +<span class="command"><strong>};</strong></span> +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="lwres_statement"></a><span class="command"><strong>lwres</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>lwres</strong></span> statement configures the + name + server to also act as a lightweight resolver server. (See + <a class="xref" href="Bv9ARM.ch05.html#lwresd" title="Running a Resolver Daemon">the section called “Running a Resolver Daemon”</a>.) There may be multiple + <span class="command"><strong>lwres</strong></span> statements configuring + lightweight resolver servers with different properties. + </p> + + <p> + The <span class="command"><strong>listen-on</strong></span> statement specifies a + list of + IPv4 addresses (and ports) that this instance of a lightweight + resolver daemon + should accept requests on. If no port is specified, port 921 is + used. + If this statement is omitted, requests will be accepted on + 127.0.0.1, + port 921. + </p> + + <p> + The <span class="command"><strong>view</strong></span> statement binds this + instance of a + lightweight resolver daemon to a view in the DNS namespace, so that + the + response will be constructed in the same manner as a normal DNS + query + matching this view. If this statement is omitted, the default view + is + used, and if there is no default view, an error is triggered. + </p> + + <p> + The <span class="command"><strong>search</strong></span> statement is equivalent to + the + <span class="command"><strong>search</strong></span> statement in + <code class="filename">/etc/resolv.conf</code>. It provides a + list of domains + which are appended to relative names in queries. + </p> + + <p> + The <span class="command"><strong>ndots</strong></span> statement is equivalent to + the + <span class="command"><strong>ndots</strong></span> statement in + <code class="filename">/etc/resolv.conf</code>. It indicates the + minimum + number of dots in a relative domain name that should result in an + exact match lookup before search path elements are appended. + </p> + <p> + The <code class="option">lwres-tasks</code> statement specifies the number + of worker threads the lightweight resolver will dedicate to serving + clients. By default the number is the same as the number of CPUs on + the system; this can be overridden using the <code class="option">-n</code> + command line option when starting the server. + </p> + <p> + The <code class="option">lwres-clients</code> specifies + the number of client objects per thread the lightweight + resolver should create to serve client queries. + By default, if the lightweight resolver runs as a part + of <span class="command"><strong>named</strong></span>, 256 client objects are + created for each task; if it runs as <span class="command"><strong>lwresd</strong></span>, + 1024 client objects are created for each thread. The maximum + value is 32768; higher values will be silently ignored and + the maximum will be used instead. + Note that setting too high a value may overconsume + system resources. + </p> + <p> + The maximum number of client queries that the lightweight + resolver can handle at any one time equals + <code class="option">lwres-tasks</code> times <code class="option">lwres-clients</code>. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="masters_grammar"></a><span class="command"><strong>masters</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>masters</strong></span> <em class="replaceable"><code>string</code></em> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp + <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ + <span class="command"><strong>port</strong></span> <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="masters_statement"></a><span class="command"><strong>masters</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p><span class="command"><strong>masters</strong></span> + lists allow for a common set of masters to be easily used by + multiple stub and slave zones in their <span class="command"><strong>masters</strong></span> + or <span class="command"><strong>also-notify</strong></span> lists. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="options_grammar"></a><span class="command"><strong>options</strong></span> Statement Grammar</h3></div></div></div> + + <p> + This is the grammar of the <span class="command"><strong>options</strong></span> + statement in the <code class="filename">named.conf</code> file: + </p> + <pre class="programlisting"> +<span class="command"><strong>options</strong></span> { + <span class="command"><strong>acache-cleaning-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>acache-enable</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>additional-from-auth</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>additional-from-cache</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>allow-new-zones</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>allow-notify</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-cache</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-cache-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-recursion</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-recursion-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-transfer</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-update</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-update-forwarding</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>also-notify</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | + <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>alt-transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) + ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>alt-transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | + * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>answer-cookie</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>attach-cache</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>auth-nxdomain</strong></span> <em class="replaceable"><code>boolean</code></em>; // default changed + <span class="command"><strong>auto-dnssec</strong></span> ( allow | maintain | off ); + <span class="command"><strong>automatic-interface-scan</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>avoid-v4-udp-ports</strong></span> { <em class="replaceable"><code>portrange</code></em>; ... }; + <span class="command"><strong>avoid-v6-udp-ports</strong></span> { <em class="replaceable"><code>portrange</code></em>; ... }; + <span class="command"><strong>bindkeys-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>blackhole</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>cache-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>catalog-zones</strong></span> { zone <em class="replaceable"><code>quoted_string</code></em> [ default-masters [ port + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ + <span class="command"><strong>port</strong></span> <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key + <em class="replaceable"><code>string</code></em> ]; ... } ] [ zone-directory <em class="replaceable"><code>quoted_string</code></em> ] [ + <span class="command"><strong>in-memory</strong></span> <em class="replaceable"><code>boolean</code></em> ] [ min-update-interval <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>check-dup-records</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-integrity</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>check-mx</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-mx-cname</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-names</strong></span> ( master | slave | response + ) ( fail | warn | ignore ); + <span class="command"><strong>check-sibling</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>check-spf</strong></span> ( warn | ignore ); + <span class="command"><strong>check-srv-cname</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-wildcard</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>cleaning-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>clients-per-query</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>cookie-algorithm</strong></span> ( aes | sha1 | sha256 ); + <span class="command"><strong>cookie-secret</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>coresize</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>datasize</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>deny-answer-addresses</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... } [ + <span class="command"><strong>except-from</strong></span> { <em class="replaceable"><code>quoted_string</code></em>; ... } ]; + <span class="command"><strong>deny-answer-aliases</strong></span> { <em class="replaceable"><code>quoted_string</code></em>; ... } [ except-from { + <em class="replaceable"><code>quoted_string</code></em>; ... } ]; + <span class="command"><strong>dialup</strong></span> ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>disable-algorithms</strong></span> <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>; + ... }; + <span class="command"><strong>disable-ds-digests</strong></span> <em class="replaceable"><code>string</code></em> { <em class="replaceable"><code>string</code></em>; + ... }; + <span class="command"><strong>disable-empty-zone</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dns64</strong></span> <em class="replaceable"><code>netprefix</code></em> { + <span class="command"><strong>break-dnssec</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>clients</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>exclude</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>mapped</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>recursive-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>suffix</strong></span> <em class="replaceable"><code>ipv6_address</code></em>; + }; + <span class="command"><strong>dns64-contact</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dns64-server</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dnssec-accept-expired</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-dnskey-kskonly</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-enable</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>dnssec-lookaside</strong></span> ( <em class="replaceable"><code>string</code></em> trust-anchor + <em class="replaceable"><code>string</code></em> | auto | no ); + <span class="command"><strong>dnssec-must-be-secure</strong></span> <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-secure-to-insecure</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-update-mode</strong></span> ( maintain | no-resign ); + <span class="command"><strong>dnssec-validation</strong></span> ( yes | no | auto ); + <span class="command"><strong>dnstap</strong></span> { ( all | auth | client | forwarder | + <span class="command"><strong>resolver</strong></span> ) [ ( query | response ) ]; ... }; + <span class="command"><strong>dnstap-identity</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none | + <span class="command"><strong>hostname</strong></span> ); + <span class="command"><strong>dnstap-output</strong></span> ( file | unix ) <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>dnstap-version</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>dual-stack-servers</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>quoted_string</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv4_address</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port + <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] ); ... }; + <span class="command"><strong>dump-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>edns-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>empty-contact</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>empty-server</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>empty-zones-enable</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>fetch-quota-params</strong></span> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>fixedpoint</code></em> <em class="replaceable"><code>fixedpoint</code></em> <em class="replaceable"><code>fixedpoint</code></em>; + <span class="command"><strong>fetches-per-server</strong></span> <em class="replaceable"><code>integer</code></em> [ ( drop | fail ) ]; + <span class="command"><strong>fetches-per-zone</strong></span> <em class="replaceable"><code>integer</code></em> [ ( drop | fail ) ]; + <span class="command"><strong>files</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>filter-aaaa</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>filter-aaaa-on-v4</strong></span> ( break-dnssec | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>filter-aaaa-on-v6</strong></span> ( break-dnssec | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>flush-zones-on-shutdown</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> + | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>fstrm-set-buffer-hint</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-flush-timeout</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-input-queue-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-output-notify-threshold</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-output-queue-model</strong></span> ( mpsc | spsc ); + <span class="command"><strong>fstrm-set-output-queue-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>fstrm-set-reopen-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>geoip-directory</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>geoip-use-ecs</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>heartbeat-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>hostname</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>inline-signing</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>interface-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>ixfr-from-differences</strong></span> ( master | slave | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>keep-response-order</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>key-directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>lame-ttl</strong></span> <em class="replaceable"><code>ttlval</code></em>; + <span class="command"><strong>listen-on</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp + <em class="replaceable"><code>integer</code></em> ] { + <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>listen-on-v6</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp + <em class="replaceable"><code>integer</code></em> ] { + <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>lmdb-mapsize</strong></span> <em class="replaceable"><code>sizeval</code></em>; + <span class="command"><strong>lock-file</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>managed-keys-directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>match-mapped-addresses</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>max-acache-size</strong></span> ( unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>max-cache-size</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> | <em class="replaceable"><code>percentage</code></em> ); + <span class="command"><strong>max-cache-ttl</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-clients-per-query</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-journal-size</strong></span> ( unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>max-ncache-ttl</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-recursion-depth</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-recursion-queries</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-rsa-exponent-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-zone-ttl</strong></span> ( unlimited | <em class="replaceable"><code>ttlval</code></em> ); + <span class="command"><strong>memstatistics</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>memstatistics-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>message-compression</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>min-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>minimal-any</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>minimal-responses</strong></span> ( no-auth | no-auth-recursive | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>multi-master</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>no-case-compress</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>nocookie-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify</strong></span> ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>notify-delay</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-rate</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] + [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-to-soa</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>nta-lifetime</strong></span> <em class="replaceable"><code>ttlval</code></em>; + <span class="command"><strong>nta-recheck</strong></span> <em class="replaceable"><code>ttlval</code></em>; + <span class="command"><strong>nxdomain-redirect</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>pid-file</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>port</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>preferred-glue</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>prefetch</strong></span> <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>provide-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>query-source</strong></span> ( ( [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) ] + <span class="command"><strong>port</strong></span> ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>query-source-v6</strong></span> ( ( [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) ] + <span class="command"><strong>port</strong></span> ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>querylog</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>random-device</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>rate-limit</strong></span> { + <span class="command"><strong>all-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>errors-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>exempt-clients</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>ipv4-prefix-length</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>ipv6-prefix-length</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>log-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>max-table-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-table-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>nodata-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>nxdomains-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>qps-scale</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>referrals-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>responses-per-second</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>slip</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>window</strong></span> <em class="replaceable"><code>integer</code></em>; + }; + <span class="command"><strong>recursing-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>recursion</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>recursive-clients</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>request-expire</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-nsid</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>require-server-cookie</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>reserved-sockets</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>resolver-query-timeout</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>response-policy</strong></span> { zone <em class="replaceable"><code>quoted_string</code></em> [ log <em class="replaceable"><code>boolean</code></em> ] [ + <span class="command"><strong>max-policy-ttl</strong></span> <em class="replaceable"><code>integer</code></em> ] [ policy ( cname | disabled | drop | + <span class="command"><strong>given</strong></span> | no-op | nodata | nxdomain | passthru | tcp-only + <em class="replaceable"><code>quoted_string</code></em> ) ] [ recursive-only <em class="replaceable"><code>boolean</code></em> ]; ... } [ + <span class="command"><strong>break-dnssec</strong></span> <em class="replaceable"><code>boolean</code></em> ] [ max-policy-ttl <em class="replaceable"><code>integer</code></em> ] [ + <span class="command"><strong>min-ns-dots</strong></span> <em class="replaceable"><code>integer</code></em> ] [ nsip-wait-recurse <em class="replaceable"><code>boolean</code></em> ] [ + <span class="command"><strong>qname-wait-recurse</strong></span> <em class="replaceable"><code>boolean</code></em> ] [ recursive-only <em class="replaceable"><code>boolean</code></em> ]; + <span class="command"><strong>root-delegation-only</strong></span> [ exclude { <em class="replaceable"><code>quoted_string</code></em>; ... } ]; + <span class="command"><strong>root-key-sentinel</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>rrset-order</strong></span> { [ class <em class="replaceable"><code>string</code></em> ] [ type <em class="replaceable"><code>string</code></em> ] [ name + <em class="replaceable"><code>quoted_string</code></em> ] <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>string</code></em>; ... }; + <span class="command"><strong>secroots-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>send-cookie</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>serial-query-rate</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>serial-update-method</strong></span> ( date | increment | unixtime ); + <span class="command"><strong>server-id</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none | hostname ); + <span class="command"><strong>servfail-ttl</strong></span> <em class="replaceable"><code>ttlval</code></em>; + <span class="command"><strong>session-keyalg</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>session-keyfile</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>session-keyname</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>sig-signing-nodes</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-signatures</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-type</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-validity-interval</strong></span> <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>sortlist</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>stacksize</strong></span> ( default | unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>startup-notify-rate</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>statistics-file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>tcp-clients</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>tcp-listen-queue</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>tkey-dhkey</strong></span> <em class="replaceable"><code>quoted_string</code></em> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>tkey-domain</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>tkey-gssapi-credential</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>tkey-gssapi-keytab</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>transfer-format</strong></span> ( many-answers | one-answer ); + <span class="command"><strong>transfer-message-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) + ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfers-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>transfers-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>transfers-per-ns</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>trust-anchor-telemetry</strong></span> <em class="replaceable"><code>boolean</code></em>; // experimental + <span class="command"><strong>try-tcp-refresh</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>update-check-ksk</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>use-alt-transfer-source</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>use-v4-udp-ports</strong></span> { <em class="replaceable"><code>portrange</code></em>; ... }; + <span class="command"><strong>use-v6-udp-ports</strong></span> { <em class="replaceable"><code>portrange</code></em>; ... }; + <span class="command"><strong>v6-bias</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>version</strong></span> ( <em class="replaceable"><code>quoted_string</code></em> | none ); + <span class="command"><strong>zero-no-soa-ttl</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zero-no-soa-ttl-cache</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="options"></a><span class="command"><strong>options</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>options</strong></span> statement sets up global + options + to be used by <acronym class="acronym">BIND</acronym>. This statement + may appear only + once in a configuration file. If there is no <span class="command"><strong>options</strong></span> + statement, an options block with each option set to its default will + be used. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>attach-cache</strong></span></span></dt> +<dd> + <p> + Allows multiple views to share a single cache + database. + Each view has its own cache database by default, but + if multiple views have the same operational policy + for name resolution and caching, those views can + share a single cache to save memory and possibly + improve resolution efficiency by using this option. + </p> + + <p> + The <span class="command"><strong>attach-cache</strong></span> option + may also be specified in <span class="command"><strong>view</strong></span> + statements, in which case it overrides the + global <span class="command"><strong>attach-cache</strong></span> option. + </p> + + <p> + The <em class="replaceable"><code>cache_name</code></em> specifies + the cache to be shared. + When the <span class="command"><strong>named</strong></span> server configures + views which are supposed to share a cache, it + creates a cache with the specified name for the + first view of these sharing views. + The rest of the views will simply refer to the + already created cache. + </p> + + <p> + One common configuration to share a cache would be to + allow all views to share a single cache. + This can be done by specifying + the <span class="command"><strong>attach-cache</strong></span> as a global + option with an arbitrary name. + </p> + + <p> + Another possible operation is to allow a subset of + all views to share a cache while the others to + retain their own caches. + For example, if there are three views A, B, and C, + and only A and B should share a cache, specify the + <span class="command"><strong>attach-cache</strong></span> option as a view A (or + B)'s option, referring to the other view name: + </p> + +<pre class="programlisting"> + view "A" { + // this view has its own cache + ... + }; + view "B" { + // this view refers to A's cache + attach-cache "A"; + }; + view "C" { + // this view has its own cache + ... + }; +</pre> + + <p> + Views that share a cache must have the same policy + on configurable parameters that may affect caching. + The current implementation requires the following + configurable options be consistent among these + views: + <span class="command"><strong>check-names</strong></span>, + <span class="command"><strong>cleaning-interval</strong></span>, + <span class="command"><strong>dnssec-accept-expired</strong></span>, + <span class="command"><strong>dnssec-validation</strong></span>, + <span class="command"><strong>max-cache-ttl</strong></span>, + <span class="command"><strong>max-ncache-ttl</strong></span>, + <span class="command"><strong>max-cache-size</strong></span>, and + <span class="command"><strong>zero-no-soa-ttl</strong></span>. + </p> + + <p> + Note that there may be other parameters that may + cause confusion if they are inconsistent for + different views that share a single cache. + For example, if these views define different sets of + forwarders that can return different answers for the + same question, sharing the answer does not make + sense or could even be harmful. + It is administrator's responsibility to ensure + configuration differences in different views do + not cause disruption with a shared cache. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>directory</strong></span></span></dt> +<dd> + <p> + The working directory of the server. + Any non-absolute pathnames in the configuration file will + be taken as relative to this directory. The default + location for most server output files + (e.g. <code class="filename">named.run</code>) is this directory. + If a directory is not specified, the working directory + defaults to `<code class="filename">.</code>', the directory from + which the server was started. The directory specified + should be an absolute path. It is + <span class="emphasis"><em>strongly recommended</em></span> + that the directory be writable by the effective user + ID of the <span class="command"><strong>named</strong></span> process. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnstap</strong></span></span></dt> +<dd> + <p> + <span class="command"><strong>dnstap</strong></span> is a fast, flexible method + for capturing and logging DNS traffic. Developed by + Robert Edmonds at Farsight Security, Inc., and supported + by multiple DNS implementations, <span class="command"><strong>dnstap</strong></span> + uses + <span class="command"><strong>libfstrm</strong></span> (a lightweight high-speed + framing library, see + <a class="link" href="https://github.com/farsightsec/fstrm" target="_top">https://github.com/farsightsec/fstrm</a>) to send + event payloads which are encoded using Protocol Buffers + (<span class="command"><strong>libprotobuf-c</strong></span>, a mechanism for + serializing structured data developed + by Google, Inc.; see + <a class="link" href="https://developers.google.com/protocol-buffers/" target="_top">https://developers.google.com/protocol-buffers</a>). + </p> + <p> + To enable <span class="command"><strong>dnstap</strong></span> at compile time, + the <span class="command"><strong>fstrm</strong></span> and <span class="command"><strong>protobuf-c</strong></span> + libraries must be available, and BIND must be configured with + <code class="option">--enable-dnstap</code>. + </p> + <p> + The <span class="command"><strong>dnstap</strong></span> option is a bracketed list + of message types to be logged. These may be set differently + for each view. Supported types are <code class="literal">client</code>, + <code class="literal">auth</code>, <code class="literal">resolver</code>, and + <code class="literal">forwarder</code>. Specifying type + <code class="literal">all</code> will cause all <span class="command"><strong>dnstap</strong></span> + messages to be logged, regardless of type. + </p> + <p> + Each type may take an additional argument to indicate whether + to log <code class="literal">query</code> messages or + <code class="literal">response</code> messages; if not specified, + both queries and responses are logged. + </p> + <p> + Example: To log all authoritative queries and responses, + recursive client responses, and upstream queries sent by + the resolver, use: +</p> +<pre class="programlisting">dnstap { + auth; + client response; + resolver query; +}; +</pre> +<p> + </p> + <p> + Logged <span class="command"><strong>dnstap</strong></span> messages can be parsed + using the <span class="command"><strong>dnstap-read</strong></span> utility (see + <a class="xref" href="man.dnstap-read.html" title="dnstap-read"><span class="refentrytitle"><span class="application">dnstap-read</span></span>(1)</a> for details). + </p> + <p> + For more information on <span class="command"><strong>dnstap</strong></span>, see + <a class="link" href="http://dnstap.info" target="_top">http://dnstap.info</a>. + </p> + <p> + The fstrm library has a number of tunables that are exposed + in <code class="filename">named.conf</code>, and can be modified + if necessary to improve performance or prevent loss of data. + These are: + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-buffer-hint</strong></span>: The + threshold number of bytes to accumulate in the output + buffer before forcing a buffer flush. The minimum is + 1024, the maximum is 65536, and the default is 8192. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-flush-timeout</strong></span>: The number + of seconds to allow unflushed data to remain in the + output buffer. The minimum is 1 second, the maximum is + 600 seconds (10 minutes), and the default is 1 second. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-output-notify-threshold</strong></span>: + The number of outstanding queue entries to allow on + an input queue before waking the I/O thread. + The minimum is 1 and the default is 32. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-output-queue-model</strong></span>: + Controls the queuing semantics to use for queue + objects. The default is <code class="literal">mpsc</code> + (multiple producer, single consumer); the other + option is <code class="literal">spsc</code> (single producer, + single consumer). + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-input-queue-size</strong></span>: The + number of queue entries to allocate for each + input queue. This value must be a power of 2. + The minimum is 2, the maximum is 16384, and + the default is 512. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-output-queue-size</strong></span>: + The number of queue entries to allocate for each + output queue. The minimum is 2, the maximum is + system-dependent and based on <code class="option">IOV_MAX</code>, + and the default is 64. + + </li> +<li class="listitem"> + + <span class="command"><strong>fstrm-set-reopen-interval</strong></span>: + The number of seconds to wait between attempts to + reopen a closed output stream. The minimum is 1 second, + the maximum is 600 seconds (10 minutes), and the default + is 5 seconds. + + </li> +</ul></div> + <p> + Note that all of the above minimum, maximum, and default + values are set by the <span class="command"><strong>libfstrm</strong></span> library, + and may be subject to change in future versions of the + library. See the <span class="command"><strong>libfstrm</strong></span> documentation + for more information. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnstap-output</strong></span></span></dt> +<dd> + <p> + Configures the path to which the <span class="command"><strong>dnstap</strong></span> + frame stream will be sent if <span class="command"><strong>dnstap</strong></span> + is enabled at compile time and active. + </p> + <p> + The first argument is either <code class="literal">file</code> or + <code class="literal">unix</code>, indicating whether the destination + is a file or a UNIX domain socket. The second argument + is the path of the file or socket. (Note: when using a + socket, <span class="command"><strong>dnstap</strong></span> messages will + only be sent if another process such as + <span class="command"><strong>fstrm_capture</strong></span> + (provided with <span class="command"><strong>libfstrm</strong></span>) is listening on + the socket.) + </p> + <p> + <span class="command"><strong>dnstap-output</strong></span> can only be set globally + in <span class="command"><strong>options</strong></span>. Currently, it can only be + set once while <span class="command"><strong>named</strong></span> is running; + once set, it cannot be changed by + <span class="command"><strong>rndc reload</strong></span> or + <span class="command"><strong>rndc reconfig</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnstap-identity</strong></span></span></dt> +<dd> + <p> + Specifies an <span class="command"><strong>identity</strong></span> string to send in + <span class="command"><strong>dnstap</strong></span> messages. If set to + <code class="literal">hostname</code>, which is the default, the + server's hostname will be sent. If set to + <code class="literal">none</code>, no identity string will be sent. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnstap-version</strong></span></span></dt> +<dd> + <p> + Specifies a <span class="command"><strong>version</strong></span> string to send in + <span class="command"><strong>dnstap</strong></span> messages. The default is the + version number of the BIND release. If set to + <code class="literal">none</code>, no version string will be sent. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>geoip-directory</strong></span></span></dt> +<dd> + <p> + Specifies the directory containing GeoIP + <code class="filename">.dat</code> database files for GeoIP + initialization. By default, this option is unset + and the GeoIP support will use libGeoIP's + built-in directory. + (For details, see <a class="xref" href="Bv9ARM.ch06.html#acl" title="acl Statement Definition and Usage">the section called “<span class="command"><strong>acl</strong></span> Statement Definition and + Usage”</a> about the + <span class="command"><strong>geoip</strong></span> ACL.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>key-directory</strong></span></span></dt> +<dd> + <p> + When performing dynamic update of secure zones, the + directory where the public and private DNSSEC key files + should be found, if different than the current working + directory. (Note that this option has no effect on the + paths for files containing non-DNSSEC keys such as + <code class="filename">bind.keys</code>, + <code class="filename">rndc.key</code> or + <code class="filename">session.key</code>.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>lmdb-mapsize</strong></span></span></dt> +<dd> + <p> + When <span class="command"><strong>named</strong></span> is built with liblmdb, + this option sets a maximum size for the memory map of + the new-zone database (NZD) in LMDB database format. + This database is used to store configuration information + for zones added using <span class="command"><strong>rndc addzone</strong></span>. + Note that this is not the NZD database file size, but + the largest size that the database may grow to. + </p> + <p> + Because the database file is memory mapped, its size is + limited by the address space of the named process. The + default of 32 megabytes was chosen to be usable with + 32-bit <span class="command"><strong>named</strong></span> builds. The largest + permitted value is 1 terabyte. Given typical zone + configurations without elaborate ACLs, a 32 MB NZD file + ought to be able to hold configurations of about 100,000 + zones. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>managed-keys-directory</strong></span></span></dt> +<dd> + <p> + Specifies the directory in which to store the files that + track managed DNSSEC keys. By default, this is the working + directory. The directory <span class="emphasis"><em>must</em></span> + be writable by the effective user ID of the + <span class="command"><strong>named</strong></span> process. + </p> + <p> + If <span class="command"><strong>named</strong></span> is not configured to use views, + then managed keys for the server will be tracked in a single + file called <code class="filename">managed-keys.bind</code>. + Otherwise, managed keys will be tracked in separate files, + one file per view; each file name will be the view name + (or, if it contains characters that are incompatible with + use as a file name, the SHA256 hash of the view name), + followed by the extension + <code class="filename">.mkeys</code>. + </p> + <p> + (Note: in previous releases, file names for views + always used the SHA256 hash of the view name. To ensure + compatibility after upgrade, if a file using the old + name format is found to exist, it will be used instead + of the new format.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>named-xfer</strong></span></span></dt> +<dd> + <p> + <span class="emphasis"><em>This option is obsolete.</em></span> It + was used in <acronym class="acronym">BIND</acronym> 8 to specify + the pathname to the <span class="command"><strong>named-xfer</strong></span> + program. In <acronym class="acronym">BIND</acronym> 9, no separate + <span class="command"><strong>named-xfer</strong></span> program is needed; + its functionality is built into the name server. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tkey-gssapi-keytab</strong></span></span></dt> +<dd> + <p> + The KRB5 keytab file to use for GSS-TSIG updates. If + this option is set and tkey-gssapi-credential is not + set, then updates will be allowed with any key + matching a principal in the specified keytab. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tkey-gssapi-credential</strong></span></span></dt> +<dd> + <p> + The security credential with which the server should + authenticate keys requested by the GSS-TSIG protocol. + Currently only Kerberos 5 authentication is available + and the credential is a Kerberos principal which the + server can acquire through the default system key + file, normally <code class="filename">/etc/krb5.keytab</code>. + The location keytab file can be overridden using the + tkey-gssapi-keytab option. Normally this principal is + of the form "<strong class="userinput"><code>DNS/</code></strong><code class="varname">server.domain</code>". + To use GSS-TSIG, <span class="command"><strong>tkey-domain</strong></span> must + also be set if a specific keytab is not set with + tkey-gssapi-keytab. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tkey-domain</strong></span></span></dt> +<dd> + <p> + The domain appended to the names of all shared keys + generated with <span class="command"><strong>TKEY</strong></span>. When a + client requests a <span class="command"><strong>TKEY</strong></span> exchange, + it may or may not specify the desired name for the + key. If present, the name of the shared key will + be <code class="varname">client specified part</code> + + <code class="varname">tkey-domain</code>. Otherwise, the + name of the shared key will be <code class="varname">random hex + digits</code> + <code class="varname">tkey-domain</code>. + In most cases, the <span class="command"><strong>domainname</strong></span> + should be the server's domain name, or an otherwise + non-existent subdomain like + "_tkey.<code class="varname">domainname</code>". If you are + using GSS-TSIG, this variable must be defined, unless + you specify a specific keytab using tkey-gssapi-keytab. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tkey-dhkey</strong></span></span></dt> +<dd> + <p> + The Diffie-Hellman key used by the server + to generate shared keys with clients using the Diffie-Hellman + mode + of <span class="command"><strong>TKEY</strong></span>. The server must be + able to load the + public and private keys from files in the working directory. + In + most cases, the <code class="varname">key_name</code> should be the server's host name. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>cache-file</strong></span></span></dt> +<dd> + <p> + This is for testing only. Do not use. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dump-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server dumps + the database to when instructed to do so with + <span class="command"><strong>rndc dumpdb</strong></span>. + If not specified, the default is <code class="filename">named_dump.db</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>memstatistics-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server writes memory + usage statistics to on exit. If not specified, + the default is <code class="filename">named.memstats</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>lock-file</strong></span></span></dt> +<dd> + <p> + The pathname of a file on which <span class="command"><strong>named</strong></span> will + attempt to acquire a file lock when starting up for + the first time; if unsuccessful, the server will + will terminate, under the assumption that another + server is already running. If not specified, the default is + <code class="filename">/var/run/named/named.lock</code>. + </p> + <p> + Specifying <span class="command"><strong>lock-file none</strong></span> disables the + use of a lock file. <span class="command"><strong>lock-file</strong></span> is + ignored if <span class="command"><strong>named</strong></span> was run using the <code class="option">-X</code> + option, which overrides it. Changes to + <span class="command"><strong>lock-file</strong></span> are ignored if + <span class="command"><strong>named</strong></span> is being reloaded or + reconfigured; it is only effective when the server is + first started up. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>pid-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server writes its process ID + in. If not specified, the default is + <code class="filename">/var/run/named/named.pid</code>. + The PID file is used by programs that want to send signals to + the running + name server. Specifying <span class="command"><strong>pid-file none</strong></span> disables the + use of a PID file — no file will be written and any + existing one will be removed. Note that <span class="command"><strong>none</strong></span> + is a keyword, not a filename, and therefore is not enclosed + in + double quotes. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>recursing-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server dumps + the queries that are currently recursing when instructed + to do so with <span class="command"><strong>rndc recursing</strong></span>. + If not specified, the default is <code class="filename">named.recursing</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>statistics-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server appends statistics + to when instructed to do so using <span class="command"><strong>rndc stats</strong></span>. + If not specified, the default is <code class="filename">named.stats</code> in the + server's current directory. The format of the file is + described + in <a class="xref" href="Bv9ARM.ch06.html#statsfile" title="The Statistics File">the section called “The Statistics File”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>bindkeys-file</strong></span></span></dt> +<dd> + <p> + The pathname of a file to override the built-in trusted + keys provided by <span class="command"><strong>named</strong></span>. + See the discussion of <span class="command"><strong>dnssec-validation</strong></span> + for details. If not specified, the default is + <code class="filename">/etc/bind.keys</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>secroots-file</strong></span></span></dt> +<dd> + <p> + The pathname of the file the server dumps + security roots to when instructed to do so with + <span class="command"><strong>rndc secroots</strong></span>. + If not specified, the default is + <code class="filename">named.secroots</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>session-keyfile</strong></span></span></dt> +<dd> + <p> + The pathname of the file into which to write a TSIG + session key generated by <span class="command"><strong>named</strong></span> for use by + <span class="command"><strong>nsupdate -l</strong></span>. If not specified, the + default is <code class="filename">/var/run/named/session.key</code>. + (See <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a>, and in + particular the discussion of the + <span class="command"><strong>update-policy</strong></span> statement's + <strong class="userinput"><code>local</code></strong> option for more + information about this feature.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>session-keyname</strong></span></span></dt> +<dd> + <p> + The key name to use for the TSIG session key. + If not specified, the default is "local-ddns". + </p> + </dd> +<dt><span class="term"><span class="command"><strong>session-keyalg</strong></span></span></dt> +<dd> + <p> + The algorithm to use for the TSIG session key. + Valid values are hmac-sha1, hmac-sha224, hmac-sha256, + hmac-sha384, hmac-sha512 and hmac-md5. If not + specified, the default is hmac-sha256. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>port</strong></span></span></dt> +<dd> + <p> + The UDP/TCP port number the server uses for + receiving and sending DNS protocol traffic. + The default is 53. This option is mainly intended for server + testing; + a server using a port other than 53 will not be able to + communicate with + the global DNS. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dscp</strong></span></span></dt> +<dd> + <p> + The global Differentiated Services Code Point (DSCP) + value to classify outgoing DNS traffic on operating + systems that support DSCP. Valid values are 0 through 63. + It is not configured by default. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>random-device</strong></span></span></dt> +<dd> + <p> + The source of entropy to be used by the server. Entropy is + primarily needed + for DNSSEC operations, such as TKEY transactions and dynamic + update of signed + zones. This options specifies the device (or file) from which + to read + entropy. If this is a file, operations requiring entropy will + fail when the + file has been exhausted. If not specified, the default value + is + <code class="filename">/dev/random</code> + (or equivalent) when present, and none otherwise. The + <span class="command"><strong>random-device</strong></span> option takes + effect during + the initial configuration load at server startup time and + is ignored on subsequent reloads. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>preferred-glue</strong></span></span></dt> +<dd> + <p> + If specified, the listed type (A or AAAA) will be emitted + before other glue + in the additional section of a query response. + The default is to prefer A records when responding + to queries that arrived via IPv4 and AAAA when + responding to queries that arrived via IPv6. + </p> + </dd> +<dt> +<a name="root_delegation_only"></a><span class="term"><span class="command"><strong>root-delegation-only</strong></span></span> +</dt> +<dd> + <p> + Turn on enforcement of delegation-only in TLDs + (top level domains) and root zones with an optional + exclude list. + </p> + <p> + DS queries are expected to be made to and be answered by + delegation only zones. Such queries and responses are + treated as an exception to delegation-only processing + and are not converted to NXDOMAIN responses provided + a CNAME is not discovered at the query name. + </p> + <p> + If a delegation only zone server also serves a child + zone it is not always possible to determine whether + an answer comes from the delegation only zone or the + child zone. SOA NS and DNSKEY records are apex + only records and a matching response that contains + these records or DS is treated as coming from a + child zone. RRSIG records are also examined to see + if they are signed by a child zone or not. The + authority section is also examined to see if there + is evidence that the answer is from the child zone. + Answers that are determined to be from a child zone + are not converted to NXDOMAIN responses. Despite + all these checks there is still a possibility of + false negatives when a child zone is being served. + </p> + <p> + Similarly false positives can arise from empty nodes + (no records at the name) in the delegation only zone + when the query type is not ANY. + </p> + <p> + Note some TLDs are not delegation only (e.g. "DE", "LV", + "US" and "MUSEUM"). This list is not exhaustive. + </p> + +<pre class="programlisting"> +options { + root-delegation-only exclude { "de"; "lv"; "us"; "museum"; }; +}; +</pre> + + </dd> +<dt><span class="term"><span class="command"><strong>disable-algorithms</strong></span></span></dt> +<dd> + <p> + Disable the specified DNSSEC algorithms at and below the + specified name. + Multiple <span class="command"><strong>disable-algorithms</strong></span> + statements are allowed. + Only the best match <span class="command"><strong>disable-algorithms</strong></span> + clause will be used to determine which algorithms are used. + </p> + <p> + If all supported algorithms are disabled, the zones covered + by the <span class="command"><strong>disable-algorithms</strong></span> will be treated + as insecure. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>disable-ds-digests</strong></span></span></dt> +<dd> + <p> + Disable the specified DS/DLV digest types at and below the + specified name. + Multiple <span class="command"><strong>disable-ds-digests</strong></span> + statements are allowed. + Only the best match <span class="command"><strong>disable-ds-digests</strong></span> + clause will be used to determine which digest types are used. + </p> + <p> + If all supported digest types are disabled, the zones covered + by the <span class="command"><strong>disable-ds-digests</strong></span> will be treated + as insecure. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-lookaside</strong></span></span></dt> +<dd> + <p> + When set, <span class="command"><strong>dnssec-lookaside</strong></span> provides the + validator with an alternate method to validate DNSKEY + records at the top of a zone. When a DNSKEY is at or + below a domain specified by the deepest + <span class="command"><strong>dnssec-lookaside</strong></span>, and the normal DNSSEC + validation has left the key untrusted, the trust-anchor + will be appended to the key name and a DLV record will be + looked up to see if it can validate the key. If the DLV + record validates a DNSKEY (similarly to the way a DS + record does) the DNSKEY RRset is deemed to be trusted. + </p> + <p> + If <span class="command"><strong>dnssec-lookaside</strong></span> is set to + <strong class="userinput"><code>no</code></strong>, then dnssec-lookaside + is not used. + </p> + <p> + NOTE: The ISC-provided DLV service at + <code class="literal">dlv.isc.org</code>, has been shut down. + The <span class="command"><strong>dnssec-lookaside auto;</strong></span> + configuration option, which set <span class="command"><strong>named</strong></span> + up to use ISC DLV with minimal configuration, has + accordingly been removed. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-must-be-secure</strong></span></span></dt> +<dd> + <p> + Specify hierarchies which must be or may not be secure + (signed and validated). If <strong class="userinput"><code>yes</code></strong>, + then <span class="command"><strong>named</strong></span> will only accept answers if + they are secure. If <strong class="userinput"><code>no</code></strong>, then normal + DNSSEC validation applies allowing for insecure answers to + be accepted. The specified domain must be under a + <span class="command"><strong>trusted-keys</strong></span> or + <span class="command"><strong>managed-keys</strong></span> statement, or + <span class="command"><strong>dnssec-validation auto</strong></span> must be active. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dns64</strong></span></span></dt> +<dd> + <p> + This directive instructs <span class="command"><strong>named</strong></span> to + return mapped IPv4 addresses to AAAA queries when + there are no AAAA records. It is intended to be + used in conjunction with a NAT64. Each + <span class="command"><strong>dns64</strong></span> defines one DNS64 prefix. + Multiple DNS64 prefixes can be defined. + </p> + <p> + Compatible IPv6 prefixes have lengths of 32, 40, 48, 56, + 64 and 96 as per RFC 6052. + </p> + <p> + Additionally a reverse IP6.ARPA zone will be created for + the prefix to provide a mapping from the IP6.ARPA names + to the corresponding IN-ADDR.ARPA names using synthesized + CNAMEs. <span class="command"><strong>dns64-server</strong></span> and + <span class="command"><strong>dns64-contact</strong></span> can be used to specify + the name of the server and contact for the zones. These + are settable at the view / options level. These are + not settable on a per-prefix basis. + </p> + <p> + Each <span class="command"><strong>dns64</strong></span> supports an optional + <span class="command"><strong>clients</strong></span> ACL that determines which + clients are affected by this directive. If not defined, + it defaults to <strong class="userinput"><code>any;</code></strong>. + </p> + <p> + Each <span class="command"><strong>dns64</strong></span> supports an optional + <span class="command"><strong>mapped</strong></span> ACL that selects which + IPv4 addresses are to be mapped in the corresponding + A RRset. If not defined it defaults to + <strong class="userinput"><code>any;</code></strong>. + </p> + <p> + Normally, DNS64 won't apply to a domain name that + owns one or more AAAA records; these records will + simply be returned. The optional + <span class="command"><strong>exclude</strong></span> ACL allows specification + of a list of IPv6 addresses that will be ignored + if they appear in a domain name's AAAA records, and + DNS64 will be applied to any A records the domain + name owns. If not defined, <span class="command"><strong>exclude</strong></span> + defaults to ::ffff:0.0.0.0/96. + </p> + <p> + A optional <span class="command"><strong>suffix</strong></span> can also + be defined to set the bits trailing the mapped + IPv4 address bits. By default these bits are + set to <strong class="userinput"><code>::</code></strong>. The bits + matching the prefix and mapped IPv4 address + must be zero. + </p> + <p> + If <span class="command"><strong>recursive-only</strong></span> is set to + <span class="command"><strong>yes</strong></span> the DNS64 synthesis will + only happen for recursive queries. The default + is <span class="command"><strong>no</strong></span>. + </p> + <p> + If <span class="command"><strong>break-dnssec</strong></span> is set to + <span class="command"><strong>yes</strong></span> the DNS64 synthesis will + happen even if the result, if validated, would + cause a DNSSEC validation failure. If this option + is set to <span class="command"><strong>no</strong></span> (the default), the DO + is set on the incoming query, and there are RRSIGs on + the applicable records, then synthesis will not happen. + </p> +<pre class="programlisting"> + acl rfc1918 { 10/8; 192.168/16; 172.16/12; }; + + dns64 64:FF9B::/96 { + clients { any; }; + mapped { !rfc1918; any; }; + exclude { 64:FF9B::/96; ::ffff:0000:0000/96; }; + suffix ::; + }; +</pre> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-loadkeys-interval</strong></span></span></dt> +<dd> + <p> + When a zone is configured with <span class="command"><strong>auto-dnssec + maintain;</strong></span> its key repository must be checked + periodically to see if any new keys have been added + or any existing keys' timing metadata has been updated + (see <a class="xref" href="man.dnssec-keygen.html" title="dnssec-keygen"><span class="refentrytitle"><span class="application">dnssec-keygen</span></span>(8)</a> and + <a class="xref" href="man.dnssec-settime.html" title="dnssec-settime"><span class="refentrytitle"><span class="application">dnssec-settime</span></span>(8)</a>). The + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> option + sets the frequency of automatic repository checks, in + minutes. The default is <code class="literal">60</code> (1 hour), + the minimum is <code class="literal">1</code> (1 minute), and the + maximum is <code class="literal">1440</code> (24 hours); any higher + value is silently reduced. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-update-mode</strong></span></span></dt> +<dd> + <p> + If this option is set to its default value of + <code class="literal">maintain</code> in a zone of type + <code class="literal">master</code> which is DNSSEC-signed + and configured to allow dynamic updates (see + <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a>), and + if <span class="command"><strong>named</strong></span> has access to the + private signing key(s) for the zone, then + <span class="command"><strong>named</strong></span> will automatically sign all new + or changed records and maintain signatures for the zone + by regenerating RRSIG records whenever they approach + their expiration date. + </p> + <p> + If the option is changed to <code class="literal">no-resign</code>, + then <span class="command"><strong>named</strong></span> will sign all new or + changed records, but scheduled maintenance of + signatures is disabled. + </p> + <p> + With either of these settings, <span class="command"><strong>named</strong></span> + will reject updates to a DNSSEC-signed zone when the + signing keys are inactive or unavailable to + <span class="command"><strong>named</strong></span>. (A planned third option, + <code class="literal">external</code>, will disable all automatic + signing and allow DNSSEC data to be submitted into a zone + via dynamic update; this is not yet implemented.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>nta-lifetime</strong></span></span></dt> +<dd> + <p> + Species the default lifetime, in seconds, + that will be used for negative trust anchors added + via <span class="command"><strong>rndc nta</strong></span>. + </p> + <p> + A negative trust anchor selectively disables + DNSSEC validation for zones that are known to be + failing because of misconfiguration rather than + an attack. When data to be validated is + at or below an active NTA (and above any other + configured trust anchors), <span class="command"><strong>named</strong></span> will + abort the DNSSEC validation process and treat the data as + insecure rather than bogus. This continues until the + NTA's lifetime is elapsed. NTAs persist + across <span class="command"><strong>named</strong></span> restarts. + </p> + <p> + For convenience, TTL-style time unit suffixes can be + used to specify the NTA lifetime in seconds, minutes + or hours. <code class="option">nta-lifetime</code> defaults to + one hour. It cannot exceed one week. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>nta-recheck</strong></span></span></dt> +<dd> + <p> + Species how often to check whether negative + trust anchors added via <span class="command"><strong>rndc nta</strong></span> + are still necessary. + </p> + <p> + A negative trust anchor is normally used when a + domain has stopped validating due to operator error; + it temporarily disables DNSSEC validation for that + domain. In the interest of ensuring that DNSSEC + validation is turned back on as soon as possible, + <span class="command"><strong>named</strong></span> will periodically send a + query to the domain, ignoring negative trust anchors, + to find out whether it can now be validated. If so, + the negative trust anchor is allowed to expire early. + </p> + <p> + Validity checks can be disabled for an individual + NTA by using <span class="command"><strong>rndc nta -f</strong></span>, or + for all NTAs by setting <code class="option">nta-recheck</code> + to zero. + </p> + <p> + For convenience, TTL-style time unit suffixes can be + used to specify the NTA recheck interval in seconds, + minutes or hours. The default is five minutes. It + cannot be longer than <code class="option">nta-lifetime</code> + (which cannot be longer than a week). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-zone-ttl</strong></span></span></dt> +<dd> + <p> + Specifies a maximum permissible TTL value in seconds. + For convenience, TTL-style time unit suffixes may be + used to specify the maximum value. + When loading a zone file using a + <code class="option">masterfile-format</code> of + <code class="constant">text</code> or <code class="constant">raw</code>, + any record encountered with a TTL higher than + <code class="option">max-zone-ttl</code> will cause the zone to + be rejected. + </p> + <p> + This is useful in DNSSEC-signed zones because when + rolling to a new DNSKEY, the old key needs to remain + available until RRSIG records have expired from + caches. The <code class="option">max-zone-ttl</code> option guarantees + that the largest TTL in the zone will be no higher + than the set value. + </p> + <p> + (NOTE: Because <code class="constant">map</code>-format files + load directly into memory, this option cannot be + used with them.) + </p> + <p> + The default value is <code class="constant">unlimited</code>. + A <code class="option">max-zone-ttl</code> of zero is treated as + <code class="constant">unlimited</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>serial-update-method</strong></span></span></dt> +<dd> + <p> + Zones configured for dynamic DNS may use this + option to set the update method that will be used for + the zone serial number in the SOA record. + </p> + <p> + With the default setting of + <span class="command"><strong>serial-update-method increment;</strong></span>, the + SOA serial number will be incremented by one each time + the zone is updated. + </p> + <p> + When set to + <span class="command"><strong>serial-update-method unixtime;</strong></span>, the + SOA serial number will be set to the number of seconds + since the UNIX epoch, unless the serial number is + already greater than or equal to that value, in which + case it is simply incremented by one. + </p> + <p> + When set to + <span class="command"><strong>serial-update-method date;</strong></span>, the + new SOA serial number will be the current date + in the form "YYYYMMDD", followed by two zeroes, + unless the existing serial number is already greater + than or equal to that value, in which case it is + incremented by one. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zone-statistics</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>full</code></strong>, the server will collect + statistical data on all zones (unless specifically + turned off on a per-zone basis by specifying + <span class="command"><strong>zone-statistics terse</strong></span> or + <span class="command"><strong>zone-statistics none</strong></span> + in the <span class="command"><strong>zone</strong></span> statement). + The default is <strong class="userinput"><code>terse</code></strong>, providing + minimal statistics on zones (including name and + current serial number, but not query type + counters). + </p> + <p> + These statistics may be accessed via the + <span class="command"><strong>statistics-channel</strong></span> or + using <span class="command"><strong>rndc stats</strong></span>, which + will dump them to the file listed + in the <span class="command"><strong>statistics-file</strong></span>. See + also <a class="xref" href="Bv9ARM.ch06.html#statsfile" title="The Statistics File">the section called “The Statistics File”</a>. + </p> + <p> + For backward compatibility with earlier versions + of BIND 9, the <span class="command"><strong>zone-statistics</strong></span> + option can also accept <strong class="userinput"><code>yes</code></strong> + or <strong class="userinput"><code>no</code></strong>; <strong class="userinput"><code>yes</code></strong> + has the same meaning as <strong class="userinput"><code>full</code></strong>. + As of <acronym class="acronym">BIND</acronym> 9.10, + <strong class="userinput"><code>no</code></strong> has the same meaning + as <strong class="userinput"><code>none</code></strong>; previously, it + was the same as <strong class="userinput"><code>terse</code></strong>. + </p> + </dd> +</dl></div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="boolean_options"></a>Boolean Options</h4></div></div></div> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>automatic-interface-scan</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong> and supported by the OS, + automatically rescan network interfaces when the interface + addresses are added or removed. The default is + <strong class="userinput"><code>yes</code></strong>. + </p> + <p> + Currently the OS needs to support routing sockets for + <span class="command"><strong>automatic-interface-scan</strong></span> to be + supported. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-new-zones</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then zones can be + added at runtime via <span class="command"><strong>rndc addzone</strong></span>. + The default is <strong class="userinput"><code>no</code></strong>. + </p> + <p> + Newly added zones' configuration parameters + are stored so that they can persist after the + server is restarted. The configuration information + is saved in a file called + <code class="filename"><em class="replaceable"><code>viewname</code></em>.nzf</code> + (or, if <span class="command"><strong>named</strong></span> is compiled with + liblmdb, in an LMDB database file called + <code class="filename"><em class="replaceable"><code>viewname</code></em>.nzd</code>). + <em class="replaceable"><code>viewname</code></em> is the name of the + view, unless the view name contains characters that are + incompatible with use as a file name, in which case a + cryptographic hash of the view name is used instead. + </p> + <p> + Zones added at runtime will have their configuration + stored either in a new-zone file (NZF) or a new-zone + database (NZD) depending on whether + <span class="command"><strong>named</strong></span> was linked with + liblmdb at compile time. + See <a class="xref" href="man.rndc.html" title="rndc"><span class="refentrytitle"><span class="application">rndc</span></span>(8)</a> for further details + about <span class="command"><strong>rndc addzone</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>auth-nxdomain</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then the <span class="command"><strong>AA</strong></span> bit + is always set on NXDOMAIN responses, even if the server is + not actually + authoritative. The default is <strong class="userinput"><code>no</code></strong>; + this is + a change from <acronym class="acronym">BIND</acronym> 8. If you + are using very old DNS software, you + may need to set it to <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>deallocate-on-exit</strong></span></span></dt> +<dd> + <p> + This option was used in <acronym class="acronym">BIND</acronym> + 8 to enable checking + for memory leaks on exit. <acronym class="acronym">BIND</acronym> 9 ignores the option and always performs + the checks. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>memstatistics</strong></span></span></dt> +<dd> + <p> + Write memory statistics to the file specified by + <span class="command"><strong>memstatistics-file</strong></span> at exit. + The default is <strong class="userinput"><code>no</code></strong> unless + '-m record' is specified on the command line in + which case it is <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dialup</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then the + server treats all zones as if they are doing zone transfers + across + a dial-on-demand dialup link, which can be brought up by + traffic + originating from this server. This has different effects + according + to zone type and concentrates the zone maintenance so that + it all + happens in a short interval, once every <span class="command"><strong>heartbeat-interval</strong></span> and + hopefully during the one call. It also suppresses some of + the normal + zone maintenance traffic. The default is <strong class="userinput"><code>no</code></strong>. + </p> + <p> + The <span class="command"><strong>dialup</strong></span> option + may also be specified in the <span class="command"><strong>view</strong></span> and + <span class="command"><strong>zone</strong></span> statements, + in which case it overrides the global <span class="command"><strong>dialup</strong></span> + option. + </p> + <p> + If the zone is a master zone, then the server will send out a + NOTIFY + request to all the slaves (default). This should trigger the + zone serial + number check in the slave (providing it supports NOTIFY) + allowing the slave + to verify the zone while the connection is active. + The set of servers to which NOTIFY is sent can be controlled + by + <span class="command"><strong>notify</strong></span> and <span class="command"><strong>also-notify</strong></span>. + </p> + <p> + If the + zone is a slave or stub zone, then the server will suppress + the regular + "zone up to date" (refresh) queries and only perform them + when the + <span class="command"><strong>heartbeat-interval</strong></span> expires in + addition to sending + NOTIFY requests. + </p> + <p> + Finer control can be achieved by using + <strong class="userinput"><code>notify</code></strong> which only sends NOTIFY + messages, + <strong class="userinput"><code>notify-passive</code></strong> which sends NOTIFY + messages and + suppresses the normal refresh queries, <strong class="userinput"><code>refresh</code></strong> + which suppresses normal refresh processing and sends refresh + queries + when the <span class="command"><strong>heartbeat-interval</strong></span> + expires, and + <strong class="userinput"><code>passive</code></strong> which just disables normal + refresh + processing. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="1.150in" class="2"> +<col width="1.150in" class="3"> +<col width="1.150in" class="4"> +</colgroup> +<tbody> +<tr> +<td> + <p> + dialup mode + </p> + </td> +<td> + <p> + normal refresh + </p> + </td> +<td> + <p> + heart-beat refresh + </p> + </td> +<td> + <p> + heart-beat notify + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>no</strong></span> (default)</p> + </td> +<td> + <p> + yes + </p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + no + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>yes</strong></span></p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + yes + </p> + </td> +<td> + <p> + yes + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>notify</strong></span></p> + </td> +<td> + <p> + yes + </p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + yes + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>refresh</strong></span></p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + yes + </p> + </td> +<td> + <p> + no + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>passive</strong></span></p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + no + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>notify-passive</strong></span></p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + no + </p> + </td> +<td> + <p> + yes + </p> + </td> +</tr> +</tbody> +</table> + </div> + + <p> + Note that normal NOTIFY processing is not affected by + <span class="command"><strong>dialup</strong></span>. + </p> + + </dd> +<dt><span class="term"><span class="command"><strong>fake-iquery</strong></span></span></dt> +<dd> + <p> + In <acronym class="acronym">BIND</acronym> 8, this option + enabled simulating the obsolete DNS query type + IQUERY. <acronym class="acronym">BIND</acronym> 9 never does + IQUERY simulation. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>fetch-glue</strong></span></span></dt> +<dd> + <p> + This option is obsolete. + In BIND 8, <strong class="userinput"><code>fetch-glue yes</code></strong> + caused the server to attempt to fetch glue resource records + it + didn't have when constructing the additional + data section of a response. This is now considered a bad + idea + and BIND 9 never does it. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>flush-zones-on-shutdown</strong></span></span></dt> +<dd> + <p> + When the nameserver exits due receiving SIGTERM, + flush or do not flush any pending zone writes. The default + is + <span class="command"><strong>flush-zones-on-shutdown</strong></span> <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>geoip-use-ecs</strong></span></span></dt> +<dd> + <p> + When BIND is compiled with GeoIP support and configured + with "geoip" ACL elements, this option indicates whether + the EDNS Client Subnet option, if present in a request, + should be used for matching against the GeoIP database. + The default is + <span class="command"><strong>geoip-use-ecs</strong></span> <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>has-old-clients</strong></span></span></dt> +<dd> + <p> + This option was incorrectly implemented + in <acronym class="acronym">BIND</acronym> 8, and is ignored by <acronym class="acronym">BIND</acronym> 9. + To achieve the intended effect + of + <span class="command"><strong>has-old-clients</strong></span> <strong class="userinput"><code>yes</code></strong>, specify + the two separate options <span class="command"><strong>auth-nxdomain</strong></span> <strong class="userinput"><code>yes</code></strong> + and <span class="command"><strong>rfc2308-type1</strong></span> <strong class="userinput"><code>no</code></strong> instead. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>host-statistics</strong></span></span></dt> +<dd> + <p> + In BIND 8, this enabled keeping of + statistics for every host that the name server interacts + with. + Not implemented in BIND 9. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>root-key-sentinel</strong></span></span></dt> +<dd> + <p> + Respond to root key sentinel probes as described in + draft-ietf-dnsop-kskroll-sentinel-08. The default is + <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>maintain-ixfr-base</strong></span></span></dt> +<dd> + <p> + <span class="emphasis"><em>This option is obsolete</em></span>. + It was used in <acronym class="acronym">BIND</acronym> 8 to + determine whether a transaction log was + kept for Incremental Zone Transfer. <acronym class="acronym">BIND</acronym> 9 maintains a transaction + log whenever possible. If you need to disable outgoing + incremental zone + transfers, use <span class="command"><strong>provide-ixfr</strong></span> <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>message-compression</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, DNS name compression is + used in responses to regular queries (not including + AXFR or IXFR, which always uses compression). Setting + this option to <strong class="userinput"><code>no</code></strong> reduces CPU + usage on servers and may improve throughput. However, + it increases response size, which may cause more queries + to be processed using TCP; a server with compression + disabled is out of compliance with RFC 1123 Section + 6.1.3.2. The default is <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>minimal-responses</strong></span></span></dt> +<dd> + <p> + If set to <strong class="userinput"><code>yes</code></strong>, then when generating + responses the server will only add records to the authority + and additional data sections when they are required (e.g. + delegations, negative responses). This may improve the + performance of the server. + </p> + <p> + When set to <strong class="userinput"><code>no-auth</code></strong>, the + server will omit records from the authority section + unless they are required, but it may still add + records to the additional section. When set to + <strong class="userinput"><code>no-auth-recursive</code></strong>, this + is only done if the query is recursive. These + settings are useful when answering stub clients, + which usually ignore the authority section. + <strong class="userinput"><code>no-auth-recursive</code></strong> is + designed for mixed-mode servers which handle + both authoritative and recursive queries. + </p> + <p> + The default is <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>minimal-any</strong></span></span></dt> +<dd> + <p> + If set to <strong class="userinput"><code>yes</code></strong>, then when + generating a positive response to a query of type + ANY over UDP, the server will reply with only one + of the RRsets for the query name, and its covering + RRSIGs if any, instead of replying with all known + RRsets for the name. Similarly, a query for type + RRSIG will be answered with the RRSIG records covering + only one type. This can reduce the impact of some kinds + of attack traffic, without harming legitimate + clients. (Note, however, that the RRset returned is the + first one found in the database; it is not necessarily + the smallest available RRset.) + Additionally, <code class="option">minimal-responses</code> is + turned on for these queries, so no unnecessary records + will be added to the authority or additional sections. + The default is <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>multiple-cnames</strong></span></span></dt> +<dd> + <p> + This option was used in <acronym class="acronym">BIND</acronym> 8 to allow + a domain name to have multiple CNAME records in violation of + the DNS standards. <acronym class="acronym">BIND</acronym> 9.2 onwards + always strictly enforces the CNAME rules both in master + files and dynamic updates. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong> (the default), + DNS NOTIFY messages are sent when a zone the server is + authoritative for + changes, see <a class="xref" href="Bv9ARM.ch04.html#notify" title="Notify">the section called “Notify”</a>. The messages are + sent to the + servers listed in the zone's NS records (except the master + server identified + in the SOA MNAME field), and to any servers listed in the + <span class="command"><strong>also-notify</strong></span> option. + </p> + <p> + If <strong class="userinput"><code>master-only</code></strong>, notifies are only + sent + for master zones. + If <strong class="userinput"><code>explicit</code></strong>, notifies are sent only + to + servers explicitly listed using <span class="command"><strong>also-notify</strong></span>. + If <strong class="userinput"><code>no</code></strong>, no notifies are sent. + </p> + <p> + The <span class="command"><strong>notify</strong></span> option may also be + specified in the <span class="command"><strong>zone</strong></span> + statement, + in which case it overrides the <span class="command"><strong>options notify</strong></span> statement. + It would only be necessary to turn off this option if it + caused slaves + to crash. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-to-soa</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong> do not check the nameservers + in the NS RRset against the SOA MNAME. Normally a NOTIFY + message is not sent to the SOA MNAME (SOA ORIGIN) as it is + supposed to contain the name of the ultimate master. + Sometimes, however, a slave is listed as the SOA MNAME in + hidden master configurations and in that case you would + want the ultimate master to still send NOTIFY messages to + all the nameservers listed in the NS RRset. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>recursion</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, and a + DNS query requests recursion, then the server will attempt + to do + all the work required to answer the query. If recursion is + off + and the server does not already know the answer, it will + return a + referral response. The default is + <strong class="userinput"><code>yes</code></strong>. + Note that setting <span class="command"><strong>recursion no</strong></span> does not prevent + clients from getting data from the server's cache; it only + prevents new data from being cached as an effect of client + queries. + Caching may still occur as an effect the server's internal + operation, such as NOTIFY address lookups. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>request-nsid</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then an empty EDNS(0) + NSID (Name Server Identifier) option is sent with all + queries to authoritative name servers during iterative + resolution. If the authoritative server returns an NSID + option in its response, then its contents are logged in + the <span class="command"><strong>resolver</strong></span> category at level + <span class="command"><strong>info</strong></span>. + The default is <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>request-sit</strong></span></span></dt> +<dd> + <p> + This experimental option is obsolete. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>require-server-cookie</strong></span></span></dt> +<dd> + <p> + Require a valid server cookie before sending a full + response to a UDP request from a cookie aware client. + BADCOOKIE is sent if there is a bad or no existent + server cookie. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>answer-cookie</strong></span></span></dt> +<dd> + <p> + When set to the default value of <strong class="userinput"><code>yes</code></strong>, + COOKIE EDNS options will be sent when applicable in + replies to client queries. If set to + <strong class="userinput"><code>no</code></strong>, COOKIE EDNS options will not + be sent in replies. This can only be set at the global + options level, not per-view. + </p> + <p> + <span class="command"><strong>answer-cookie no</strong></span> is only intended as a + temporary measure, for use when <span class="command"><strong>named</strong></span> + shares an IP address with other servers that do not yet + support DNS COOKIE. A mismatch between servers on the + same address is not expected to cause operational + problems, but the option to disable COOKIE responses so + that all servers have the same behavior is provided out + of an abundance of caution. DNS COOKIE is an important + security mechanism, and should not be disabled unless + absolutely necessary. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>send-cookie</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then a COOKIE EDNS + option is sent along with the query. If the + resolver has previously talked to the server, the + COOKIE returned in the previous transaction is sent. + This is used by the server to determine whether + the resolver has talked to it before. A resolver + sending the correct COOKIE is assumed not to be an + off-path attacker sending a spoofed-source query; + the query is therefore unlikely to be part of a + reflection/amplification attack, so resolvers + sending a correct COOKIE option are not subject to + response rate limiting (RRL). Resolvers which + do not send a correct COOKIE option may be limited + to receiving smaller responses via the + <span class="command"><strong>nocookie-udp-size</strong></span> option. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>nocookie-udp-size</strong></span></span></dt> +<dd> + <p> + Sets the maximum size of UDP responses that will be + sent to queries without a valid server COOKIE. A value + below 128 will be silently raised to 128. The default + value is 4096, but the <span class="command"><strong>max-udp-size</strong></span> + option may further limit the response size. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sit-secret</strong></span></span></dt> +<dd> + <p> + This experimental option is obsolete. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>cookie-algorithm</strong></span></span></dt> +<dd> + <p> + Set the algorithm to be used when generating the + server cookie. One of "aes", "sha1" or "sha256". + The default is "aes" if supported by the cryptographic + library or otherwise "sha256". + </p> + </dd> +<dt><span class="term"><span class="command"><strong>cookie-secret</strong></span></span></dt> +<dd> + <p> + If set, this is a shared secret used for generating + and verifying EDNS COOKIE options + within an anycast cluster. If not set, the system + will generate a random secret at startup. The + shared secret is encoded as a hex string and needs + to be 128 bits for AES128, 160 bits for SHA1 and + 256 bits for SHA256. + </p> + <p> + If there are multiple secrets specified, the first + one listed in <code class="filename">named.conf</code> is + used to generate new server cookies. The others + will only be used to verify returned cookies. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>rfc2308-type1</strong></span></span></dt> +<dd> + <p> + Setting this to <strong class="userinput"><code>yes</code></strong> will + cause the server to send NS records along with the SOA + record for negative + answers. The default is <strong class="userinput"><code>no</code></strong>. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Not yet implemented in <acronym class="acronym">BIND</acronym> + 9. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>trust-anchor-telemetry</strong></span></span></dt> +<dd> + <p> + Causes <span class="command"><strong>named</strong></span> to send specially-formed + queries once per day to domains for which trust anchors + have been configured via <span class="command"><strong>trusted-keys</strong></span>, + <span class="command"><strong>managed-keys</strong></span>, or + <span class="command"><strong>dnssec-validation auto</strong></span>. + </p> + <p> + The query name used for these queries has the + form "_ta-xxxx(-xxxx)(...)".<domain>, where + each "xxxx" is a group of four hexadecimal digits + representing the key ID of a trusted DNSSEC key. + The key IDs for each domain are sorted smallest + to largest prior to encoding. The query type is NULL. + </p> + <p> + By monitoring these queries, zone operators will + be able to see which resolvers have been updated to + trust a new key; this may help them decide when it + is safe to remove an old one. + </p> + <p> + The default is <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>use-id-pool</strong></span></span></dt> +<dd> + <p> + <span class="emphasis"><em>This option is obsolete</em></span>. + <acronym class="acronym">BIND</acronym> 9 always allocates query + IDs from a pool. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>use-ixfr</strong></span></span></dt> +<dd> + <p> + <span class="emphasis"><em>This option is obsolete</em></span>. + If you need to disable IXFR to a particular server or + servers, see + the information on the <span class="command"><strong>provide-ixfr</strong></span> option + in <a class="xref" href="Bv9ARM.ch06.html#server_statement_definition_and_usage" title="server Statement Definition and Usage">the section called “<span class="command"><strong>server</strong></span> Statement Definition and + Usage”</a>. + See also + <a class="xref" href="Bv9ARM.ch04.html#incremental_zone_transfers" title="Incremental Zone Transfers (IXFR)">the section called “Incremental Zone Transfers (IXFR)”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>provide-ixfr</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>provide-ixfr</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#server_statement_definition_and_usage" title="server Statement Definition and Usage">the section called “<span class="command"><strong>server</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>request-ixfr</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>request-ixfr</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#server_statement_definition_and_usage" title="server Statement Definition and Usage">the section called “<span class="command"><strong>server</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>request-expire</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>request-expire</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#server_statement_definition_and_usage" title="server Statement Definition and Usage">the section called “<span class="command"><strong>server</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>treat-cr-as-space</strong></span></span></dt> +<dd> + <p> + This option was used in <acronym class="acronym">BIND</acronym> + 8 to make + the server treat carriage return ("<span class="command"><strong>\r</strong></span>") characters the same way + as a space or tab character, + to facilitate loading of zone files on a UNIX system that + were generated + on an NT or DOS machine. In <acronym class="acronym">BIND</acronym> 9, both UNIX "<span class="command"><strong>\n</strong></span>" + and NT/DOS "<span class="command"><strong>\r\n</strong></span>" newlines + are always accepted, + and the option is ignored. + </p> + </dd> +<dt> +<span class="term"><span class="command"><strong>additional-from-auth</strong></span>, </span><span class="term"><span class="command"><strong>additional-from-cache</strong></span></span> +</dt> +<dd> + + <p> + These options control the behavior of an authoritative + server when + answering queries which have additional data, or when + following CNAME + and DNAME chains. + </p> + + <p> + When both of these options are set to <strong class="userinput"><code>yes</code></strong> + (the default) and a + query is being answered from authoritative data (a zone + configured into the server), the additional data section of + the + reply will be filled in using data from other authoritative + zones + and from the cache. In some situations this is undesirable, + such + as when there is concern over the correctness of the cache, + or + in servers where slave zones may be added and modified by + untrusted third parties. Also, avoiding + the search for this additional data will speed up server + operations + at the possible expense of additional queries to resolve + what would + otherwise be provided in the additional section. + </p> + + <p> + For example, if a query asks for an MX record for host <code class="literal">foo.example.com</code>, + and the record found is "<code class="literal">MX 10 mail.example.net</code>", normally the address + records (A and AAAA) for <code class="literal">mail.example.net</code> will be provided as well, + if known, even though they are not in the example.com zone. + Setting these options to <span class="command"><strong>no</strong></span> + disables this behavior and makes + the server only search for additional data in the zone it + answers from. + </p> + + <p> + These options are intended for use in authoritative-only + servers, or in authoritative-only views. Attempts to set + them to <span class="command"><strong>no</strong></span> without also + specifying + <span class="command"><strong>recursion no</strong></span> will cause the + server to + ignore the options and log a warning message. + </p> + + <p> + Specifying <span class="command"><strong>additional-from-cache no</strong></span> actually + disables the use of the cache not only for additional data + lookups + but also when looking up the answer. This is usually the + desired + behavior in an authoritative-only server where the + correctness of + the cached data is an issue. + </p> + + <p> + When a name server is non-recursively queried for a name + that is not + below the apex of any served zone, it normally answers with + an + "upwards referral" to the root servers or the servers of + some other + known parent of the query name. Since the data in an + upwards referral + comes from the cache, the server will not be able to provide + upwards + referrals when <span class="command"><strong>additional-from-cache no</strong></span> + has been specified. Instead, it will respond to such + queries + with REFUSED. This should not cause any problems since + upwards referrals are not required for the resolution + process. + </p> + + </dd> +<dt><span class="term"><span class="command"><strong>match-mapped-addresses</strong></span></span></dt> +<dd> + <p> + If <strong class="userinput"><code>yes</code></strong>, then an + IPv4-mapped IPv6 address will match any address match + list entries that match the corresponding IPv4 address. + </p> + <p> + This option was introduced to work around a kernel quirk + in some operating systems that causes IPv4 TCP + connections, such as zone transfers, to be accepted on an + IPv6 socket using mapped addresses. This caused address + match lists designed for IPv4 to fail to match. However, + <span class="command"><strong>named</strong></span> now solves this problem + internally. The use of this option is discouraged. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>filter-aaaa-on-v4</strong></span></span></dt> +<dd> + <p> + This option is only available when + <acronym class="acronym">BIND</acronym> 9 is compiled with the + <strong class="userinput"><code>--enable-filter-aaaa</code></strong> option on the + "configure" command line. It is intended to help the + transition from IPv4 to IPv6 by not giving IPv6 addresses + to DNS clients unless they have connections to the IPv6 + Internet. This is not recommended unless absolutely + necessary. The default is <strong class="userinput"><code>no</code></strong>. + The <span class="command"><strong>filter-aaaa-on-v4</strong></span> option + may also be specified in <span class="command"><strong>view</strong></span> statements + to override the global <span class="command"><strong>filter-aaaa-on-v4</strong></span> + option. + </p> + <p> + If <strong class="userinput"><code>yes</code></strong>, + the DNS client is at an IPv4 address, in <span class="command"><strong>filter-aaaa</strong></span>, + and if the response does not include DNSSEC signatures, + then all AAAA records are deleted from the response. + This filtering applies to all responses and not only + authoritative responses. + </p> + <p> + If <strong class="userinput"><code>break-dnssec</code></strong>, + then AAAA records are deleted even when DNSSEC is enabled. + As suggested by the name, this makes the response not verify, + because the DNSSEC protocol is designed detect deletions. + </p> + <p> + This mechanism can erroneously cause other servers to + not give AAAA records to their clients. + A recursing server with both IPv6 and IPv4 network connections + that queries an authoritative server using this mechanism + via IPv4 will be denied AAAA records even if its client is + using IPv6. + </p> + <p> + This mechanism is applied to authoritative as well as + non-authoritative records. + A client using IPv4 that is not allowed recursion can + erroneously be given AAAA records because the server is not + allowed to check for A records. + </p> + <p> + Some AAAA records are given to IPv4 clients in glue records. + IPv4 clients that are servers can then erroneously + answer requests for AAAA records received via IPv4. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>filter-aaaa-on-v6</strong></span></span></dt> +<dd> + <p> + Identical to <span class="command"><strong>filter-aaaa-on-v4</strong></span>, + except it filters AAAA responses to queries from IPv6 + clients instead of IPv4 clients. To filter all + responses, set both options to <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ixfr-from-differences</strong></span></span></dt> +<dd> + <p> + When <strong class="userinput"><code>yes</code></strong> and the server loads a new + version of a master zone from its zone file or receives a + new version of a slave file via zone transfer, it will + compare the new version to the previous one and calculate + a set of differences. The differences are then logged in + the zone's journal file such that the changes can be + transmitted to downstream slaves as an incremental zone + transfer. + </p> + <p> + By allowing incremental zone transfers to be used for + non-dynamic zones, this option saves bandwidth at the + expense of increased CPU and memory consumption at the + master. + In particular, if the new version of a zone is completely + different from the previous one, the set of differences + will be of a size comparable to the combined size of the + old and new zone version, and the server will need to + temporarily allocate memory to hold this complete + difference set. + </p> + <p><span class="command"><strong>ixfr-from-differences</strong></span> + also accepts <span class="command"><strong>master</strong></span> and + <span class="command"><strong>slave</strong></span> at the view and options + levels which causes + <span class="command"><strong>ixfr-from-differences</strong></span> to be enabled for + all <span class="command"><strong>master</strong></span> or + <span class="command"><strong>slave</strong></span> zones respectively. + It is off by default. + </p> + <p> + Note: if inline signing is enabled for a zone, the + user-provided <span class="command"><strong>ixfr-from-differences</strong></span> + setting is ignored for that zone. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>multi-master</strong></span></span></dt> +<dd> + <p> + This should be set when you have multiple masters for a zone + and the + addresses refer to different machines. If <strong class="userinput"><code>yes</code></strong>, <span class="command"><strong>named</strong></span> will + not log + when the serial number on the master is less than what <span class="command"><strong>named</strong></span> + currently + has. The default is <strong class="userinput"><code>no</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>auto-dnssec</strong></span></span></dt> +<dd> + <p> + Zones configured for dynamic DNS may use this + option to allow varying levels of automatic DNSSEC key + management. There are three possible settings: + </p> + <p> + <span class="command"><strong>auto-dnssec allow;</strong></span> permits + keys to be updated and the zone fully re-signed + whenever the user issues the command <span class="command"><strong>rndc sign + <em class="replaceable"><code>zonename</code></em></strong></span>. + </p> + <p> + <span class="command"><strong>auto-dnssec maintain;</strong></span> includes the + above, but also automatically adjusts the zone's DNSSEC + keys on schedule, according to the keys' timing metadata + (see <a class="xref" href="man.dnssec-keygen.html" title="dnssec-keygen"><span class="refentrytitle"><span class="application">dnssec-keygen</span></span>(8)</a> and + <a class="xref" href="man.dnssec-settime.html" title="dnssec-settime"><span class="refentrytitle"><span class="application">dnssec-settime</span></span>(8)</a>). The command + <span class="command"><strong>rndc sign + <em class="replaceable"><code>zonename</code></em></strong></span> causes + <span class="command"><strong>named</strong></span> to load keys from the key + repository and sign the zone with all keys that are + active. + <span class="command"><strong>rndc loadkeys + <em class="replaceable"><code>zonename</code></em></strong></span> causes + <span class="command"><strong>named</strong></span> to load keys from the key + repository and schedule key maintenance events to occur + in the future, but it does not sign the full zone + immediately. Note: once keys have been loaded for a + zone the first time, the repository will be searched + for changes periodically, regardless of whether + <span class="command"><strong>rndc loadkeys</strong></span> is used. The recheck + interval is defined by + <span class="command"><strong>dnssec-loadkeys-interval</strong></span>.) + </p> + <p> + The default setting is <span class="command"><strong>auto-dnssec off</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-enable</strong></span></span></dt> +<dd> + <p> + This indicates whether DNSSEC-related resource + records are to be returned by <span class="command"><strong>named</strong></span>. + If set to <strong class="userinput"><code>no</code></strong>, + <span class="command"><strong>named</strong></span> will not return DNSSEC-related + resource records unless specifically queried for. + The default is <strong class="userinput"><code>yes</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-validation</strong></span></span></dt> +<dd> + <p> + Enable DNSSEC validation in <span class="command"><strong>named</strong></span>. + Note <span class="command"><strong>dnssec-enable</strong></span> also needs to be + set to <strong class="userinput"><code>yes</code></strong> to be effective. + If set to <strong class="userinput"><code>no</code></strong>, DNSSEC validation + is disabled. + </p> + <p> + If set to <strong class="userinput"><code>auto</code></strong>, DNSSEC validation + is enabled, and a default trust anchor for the DNS root + zone is used. If set to <strong class="userinput"><code>yes</code></strong>, + DNSSEC validation is enabled, but a trust anchor must be + manually configured using a <span class="command"><strong>trusted-keys</strong></span> + or <span class="command"><strong>managed-keys</strong></span> statement. The default + is <strong class="userinput"><code>yes</code></strong>. + </p> + <p> + The default root trust anchor is stored in the file + <code class="filename">bind.keys</code>. + <span class="command"><strong>named</strong></span> will load that key at + startup if <span class="command"><strong>dnssec-validation</strong></span> is + set to <code class="constant">auto</code>. A copy of the file is + installed along with BIND 9, and is current as of the + release date. If the root key expires, a new copy of + <code class="filename">bind.keys</code> can be downloaded + from <a class="link" href="https://www.isc.org/bind-keys" target="_top">https://www.isc.org/bind-keys</a>. + </p> + <p> + To prevent problems if <code class="filename">bind.keys</code> is + not found, the current trust anchor is also compiled in + to <span class="command"><strong>named</strong></span>. Relying on this is not + recommended, however, as it requires <span class="command"><strong>named</strong></span> + to be recompiled with a new key when the root key expires.) + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + <span class="command"><strong>named</strong></span> <span class="emphasis"><em>only</em></span> + loads the root key from <code class="filename">bind.keys</code>. + The file cannot be used to store keys for other zones. + The root key in <code class="filename">bind.keys</code> is ignored + if <span class="command"><strong>dnssec-validation auto</strong></span> is not in + use. + </p> + <p> + Whenever the resolver sends out queries to an + EDNS-compliant server, it always sets the DO bit + indicating it can support DNSSEC responses even if + <span class="command"><strong>dnssec-validation</strong></span> is off. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-accept-expired</strong></span></span></dt> +<dd> + <p> + Accept expired signatures when verifying DNSSEC signatures. + The default is <strong class="userinput"><code>no</code></strong>. + Setting this option to <strong class="userinput"><code>yes</code></strong> + leaves <span class="command"><strong>named</strong></span> vulnerable to + replay attacks. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>querylog</strong></span></span></dt> +<dd> + <p> + Specify whether query logging should be started when <span class="command"><strong>named</strong></span> + starts. + If <span class="command"><strong>querylog</strong></span> is not specified, + then the query logging + is determined by the presence of the logging category <span class="command"><strong>queries</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-names</strong></span></span></dt> +<dd> + <p> + This option is used to restrict the character set and syntax + of + certain domain names in master files and/or DNS responses + received + from the network. The default varies according to usage + area. For + <span class="command"><strong>master</strong></span> zones the default is <span class="command"><strong>fail</strong></span>. + For <span class="command"><strong>slave</strong></span> zones the default + is <span class="command"><strong>warn</strong></span>. + For answers received from the network (<span class="command"><strong>response</strong></span>) + the default is <span class="command"><strong>ignore</strong></span>. + </p> + <p> + The rules for legal hostnames and mail domains are derived + from RFC 952 and RFC 821 as modified by RFC 1123. + </p> + <p><span class="command"><strong>check-names</strong></span> + applies to the owner names of A, AAAA and MX records. + It also applies to the domain names in the RDATA of NS, SOA, + MX, and SRV records. + It also applies to the RDATA of PTR records where the owner + name indicated that it is a reverse lookup of a hostname + (the owner name ends in IN-ADDR.ARPA, IP6.ARPA, or IP6.INT). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-dup-records</strong></span></span></dt> +<dd> + <p> + Check master zones for records that are treated as different + by DNSSEC but are semantically equal in plain DNS. The + default is to <span class="command"><strong>warn</strong></span>. Other possible + values are <span class="command"><strong>fail</strong></span> and + <span class="command"><strong>ignore</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-mx</strong></span></span></dt> +<dd> + <p> + Check whether the MX record appears to refer to a IP address. + The default is to <span class="command"><strong>warn</strong></span>. Other possible + values are <span class="command"><strong>fail</strong></span> and + <span class="command"><strong>ignore</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-wildcard</strong></span></span></dt> +<dd> + <p> + This option is used to check for non-terminal wildcards. + The use of non-terminal wildcards is almost always as a + result of a failure + to understand the wildcard matching algorithm (RFC 1034). + This option + affects master zones. The default (<span class="command"><strong>yes</strong></span>) is to check + for non-terminal wildcards and issue a warning. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-integrity</strong></span></span></dt> +<dd> + <p> + Perform post load zone integrity checks on master + zones. This checks that MX and SRV records refer + to address (A or AAAA) records and that glue + address records exist for delegated zones. For + MX and SRV records only in-zone hostnames are + checked (for out-of-zone hostnames use + <span class="command"><strong>named-checkzone</strong></span>). + For NS records only names below top of zone are + checked (for out-of-zone names and glue consistency + checks use <span class="command"><strong>named-checkzone</strong></span>). + The default is <span class="command"><strong>yes</strong></span>. + </p> + <p> + The use of the SPF record for publishing Sender + Policy Framework is deprecated as the migration + from using TXT records to SPF records was abandoned. + Enabling this option also checks that a TXT Sender + Policy Framework record exists (starts with "v=spf1") + if there is an SPF record. Warnings are emitted if the + TXT record does not exist and can be suppressed with + <span class="command"><strong>check-spf</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-mx-cname</strong></span></span></dt> +<dd> + <p> + If <span class="command"><strong>check-integrity</strong></span> is set then + fail, warn or ignore MX records that refer + to CNAMES. The default is to <span class="command"><strong>warn</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-srv-cname</strong></span></span></dt> +<dd> + <p> + If <span class="command"><strong>check-integrity</strong></span> is set then + fail, warn or ignore SRV records that refer + to CNAMES. The default is to <span class="command"><strong>warn</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-sibling</strong></span></span></dt> +<dd> + <p> + When performing integrity checks, also check that + sibling glue exists. The default is <span class="command"><strong>yes</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-spf</strong></span></span></dt> +<dd> + <p> + If <span class="command"><strong>check-integrity</strong></span> is set then + check that there is a TXT Sender Policy Framework + record present (starts with "v=spf1") if there is an + SPF record present. The default is + <span class="command"><strong>warn</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zero-no-soa-ttl</strong></span></span></dt> +<dd> + <p> + When returning authoritative negative responses to + SOA queries set the TTL of the SOA record returned in + the authority section to zero. + The default is <span class="command"><strong>yes</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zero-no-soa-ttl-cache</strong></span></span></dt> +<dd> + <p> + When caching a negative response to a SOA query + set the TTL to zero. + The default is <span class="command"><strong>no</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>update-check-ksk</strong></span></span></dt> +<dd> + <p> + When set to the default value of <code class="literal">yes</code>, + check the KSK bit in each key to determine how the key + should be used when generating RRSIGs for a secure zone. + </p> + <p> + Ordinarily, zone-signing keys (that is, keys without the + KSK bit set) are used to sign the entire zone, while + key-signing keys (keys with the KSK bit set) are only + used to sign the DNSKEY RRset at the zone apex. + However, if this option is set to <code class="literal">no</code>, + then the KSK bit is ignored; KSKs are treated as if they + were ZSKs and are used to sign the entire zone. This is + similar to the <span class="command"><strong>dnssec-signzone -z</strong></span> + command line option. + </p> + <p> + When this option is set to <code class="literal">yes</code>, there + must be at least two active keys for every algorithm + represented in the DNSKEY RRset: at least one KSK and one + ZSK per algorithm. If there is any algorithm for which + this requirement is not met, this option will be ignored + for that algorithm. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-dnskey-kskonly</strong></span></span></dt> +<dd> + <p> + When this option and <span class="command"><strong>update-check-ksk</strong></span> + are both set to <code class="literal">yes</code>, only key-signing + keys (that is, keys with the KSK bit set) will be used + to sign the DNSKEY RRset at the zone apex. Zone-signing + keys (keys without the KSK bit set) will be used to sign + the remainder of the zone, but not the DNSKEY RRset. + This is similar to the + <span class="command"><strong>dnssec-signzone -x</strong></span> command line option. + </p> + <p> + The default is <span class="command"><strong>no</strong></span>. If + <span class="command"><strong>update-check-ksk</strong></span> is set to + <code class="literal">no</code>, this option is ignored. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>try-tcp-refresh</strong></span></span></dt> +<dd> + <p> + Try to refresh the zone using TCP if UDP queries fail. + For BIND 8 compatibility, the default is + <span class="command"><strong>yes</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-secure-to-insecure</strong></span></span></dt> +<dd> + <p> + Allow a dynamic zone to transition from secure to + insecure (i.e., signed to unsigned) by deleting all + of the DNSKEY records. The default is <span class="command"><strong>no</strong></span>. + If set to <span class="command"><strong>yes</strong></span>, and if the DNSKEY RRset + at the zone apex is deleted, all RRSIG and NSEC records + will be removed from the zone as well. + </p> + <p> + If the zone uses NSEC3, then it is also necessary to + delete the NSEC3PARAM RRset from the zone apex; this will + cause the removal of all corresponding NSEC3 records. + (It is expected that this requirement will be eliminated + in a future release.) + </p> + <p> + Note that if a zone has been configured with + <span class="command"><strong>auto-dnssec maintain</strong></span> and the + private keys remain accessible in the key repository, + then the zone will be automatically signed again the + next time <span class="command"><strong>named</strong></span> is started. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="forwarding"></a>Forwarding</h4></div></div></div> + + <p> + The forwarding facility can be used to create a large site-wide + cache on a few servers, reducing traffic over links to external + name servers. It can also be used to allow queries by servers that + do not have direct access to the Internet, but wish to look up + exterior + names anyway. Forwarding occurs only on those queries for which + the server is not authoritative and does not have the answer in + its cache. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>forward</strong></span></span></dt> +<dd> + <p> + This option is only meaningful if the + forwarders list is not empty. A value of <code class="varname">first</code>, + the default, causes the server to query the forwarders + first — and + if that doesn't answer the question, the server will then + look for + the answer itself. If <code class="varname">only</code> is + specified, the + server will only query the forwarders. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>forwarders</strong></span></span></dt> +<dd> + <p> + Specifies the IP addresses to be used + for forwarding. The default is the empty list (no + forwarding). + </p> + </dd> +</dl></div> + + <p> + Forwarding can also be configured on a per-domain basis, allowing + for the global forwarding options to be overridden in a variety + of ways. You can set particular domains to use different + forwarders, + or have a different <span class="command"><strong>forward only/first</strong></span> behavior, + or not forward at all, see <a class="xref" href="Bv9ARM.ch06.html#zone_statement_grammar" title="zone Statement Grammar">the section called “<span class="command"><strong>zone</strong></span> + Statement Grammar”</a>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="dual_stack"></a>Dual-stack Servers</h4></div></div></div> + + <p> + Dual-stack servers are used as servers of last resort to work + around + problems in reachability due the lack of support for either IPv4 + or IPv6 + on the host machine. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>dual-stack-servers</strong></span></span></dt> +<dd> + <p> + Specifies host names or addresses of machines with access to + both IPv4 and IPv6 transports. If a hostname is used, the + server must be able + to resolve the name using only the transport it has. If the + machine is dual + stacked, then the <span class="command"><strong>dual-stack-servers</strong></span> have no effect unless + access to a transport has been disabled on the command line + (e.g. <span class="command"><strong>named -4</strong></span>). + </p> + </dd> +</dl></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="access_control"></a>Access Control</h4></div></div></div> + + + <p> + Access to the server can be restricted based on the IP address + of the requesting system. See <a class="xref" href="Bv9ARM.ch06.html#address_match_lists" title="Address Match Lists">the section called “Address Match Lists”</a> for + details on how to specify IP address lists. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>allow-notify</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to + notify this server, a slave, of zone changes in addition + to the zone masters. + <span class="command"><strong>allow-notify</strong></span> may also be + specified in the + <span class="command"><strong>zone</strong></span> statement, in which case + it overrides the + <span class="command"><strong>options allow-notify</strong></span> + statement. It is only meaningful + for a slave zone. If not specified, the default is to + process notify messages + only from a zone's master. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to ask ordinary + DNS questions. <span class="command"><strong>allow-query</strong></span> may + also be specified in the <span class="command"><strong>zone</strong></span> + statement, in which case it overrides the + <span class="command"><strong>options allow-query</strong></span> statement. + If not specified, the default is to allow queries + from all hosts. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + <span class="command"><strong>allow-query-cache</strong></span> is now + used to specify access to the cache. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query-on</strong></span></span></dt> +<dd> + <p> + Specifies which local addresses can accept ordinary + DNS questions. This makes it possible, for instance, + to allow queries on internal-facing interfaces but + disallow them on external-facing ones, without + necessarily knowing the internal network's addresses. + </p> + <p> + Note that <span class="command"><strong>allow-query-on</strong></span> is only + checked for queries that are permitted by + <span class="command"><strong>allow-query</strong></span>. A query must be + allowed by both ACLs, or it will be refused. + </p> + <p> + <span class="command"><strong>allow-query-on</strong></span> may + also be specified in the <span class="command"><strong>zone</strong></span> + statement, in which case it overrides the + <span class="command"><strong>options allow-query-on</strong></span> statement. + </p> + <p> + If not specified, the default is to allow queries + on all addresses. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + <span class="command"><strong>allow-query-cache</strong></span> is + used to specify access to the cache. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query-cache</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to get answers + from the cache. If <span class="command"><strong>allow-query-cache</strong></span> + is not set then <span class="command"><strong>allow-recursion</strong></span> + is used if set, otherwise <span class="command"><strong>allow-query</strong></span> + is used if set unless <span class="command"><strong>recursion no;</strong></span> is + set in which case <span class="command"><strong>none;</strong></span> is used, + otherwise the default (<span class="command"><strong>localnets;</strong></span> + <span class="command"><strong>localhost;</strong></span>) is used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query-cache-on</strong></span></span></dt> +<dd> + <p> + Specifies which local addresses can give answers + from the cache. If not specified, the default is + to allow cache queries on any address, + <span class="command"><strong>localnets</strong></span> and + <span class="command"><strong>localhost</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-recursion</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to make recursive + queries through this server. If + <span class="command"><strong>allow-recursion</strong></span> is not set + then <span class="command"><strong>allow-query-cache</strong></span> is + used if set, otherwise <span class="command"><strong>allow-query</strong></span> + is used if set, otherwise the default + (<span class="command"><strong>localnets;</strong></span> + <span class="command"><strong>localhost;</strong></span>) is used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-recursion-on</strong></span></span></dt> +<dd> + <p> + Specifies which local addresses can accept recursive + queries. If not specified, the default is to allow + recursive queries on all addresses. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-update</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to + submit Dynamic DNS updates for master zones. The default is + to deny + updates from all hosts. Note that allowing updates based + on the requestor's IP address is insecure; see + <a class="xref" href="Bv9ARM.ch07.html#dynamic_update_security" title="Dynamic Update Security">the section called “Dynamic Update Security”</a> for details. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-update-forwarding</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to + submit Dynamic DNS updates to slave zones to be forwarded to + the + master. The default is <strong class="userinput"><code>{ none; }</code></strong>, + which + means that no update forwarding will be performed. To + enable + update forwarding, specify + <strong class="userinput"><code>allow-update-forwarding { any; };</code></strong>. + Specifying values other than <strong class="userinput"><code>{ none; }</code></strong> or + <strong class="userinput"><code>{ any; }</code></strong> is usually + counterproductive, since + the responsibility for update access control should rest + with the + master server, not the slaves. + </p> + <p> + Note that enabling the update forwarding feature on a slave + server + may expose master servers relying on insecure IP address + based + access control to attacks; see <a class="xref" href="Bv9ARM.ch07.html#dynamic_update_security" title="Dynamic Update Security">the section called “Dynamic Update Security”</a> + for more details. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-v6-synthesis</strong></span></span></dt> +<dd> + <p> + This option was introduced for the smooth transition from + AAAA + to A6 and from "nibble labels" to binary labels. + However, since both A6 and binary labels were then + deprecated, + this option was also deprecated. + It is now ignored with some warning messages. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-transfer</strong></span></span></dt> +<dd> + <p> + Specifies which hosts are allowed to + receive zone transfers from the server. <span class="command"><strong>allow-transfer</strong></span> may + also be specified in the <span class="command"><strong>zone</strong></span> + statement, in which + case it overrides the <span class="command"><strong>options allow-transfer</strong></span> statement. + If not specified, the default is to allow transfers to all + hosts. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>blackhole</strong></span></span></dt> +<dd> + <p> + Specifies a list of addresses that the + server will not accept queries from or use to resolve a + query. Queries + from these addresses will not be responded to. The default + is <strong class="userinput"><code>none</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>filter-aaaa</strong></span></span></dt> +<dd> + <p> + Specifies a list of addresses to which + <span class="command"><strong>filter-aaaa-on-v4</strong></span> + and <span class="command"><strong>filter-aaaa-on-v6</strong></span> + apply. The default is <strong class="userinput"><code>any</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>keep-response-order</strong></span></span></dt> +<dd> + <p> + Specifies a list of addresses to which the server + will send responses to TCP queries in the same order + in which they were received. This disables the + processing of TCP queries in parallel. The default + is <strong class="userinput"><code>none</code></strong>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>no-case-compress</strong></span></span></dt> +<dd> + <p> + Specifies a list of addresses which require responses + to use case-insensitive compression. This ACL can be + used when <span class="command"><strong>named</strong></span> needs to work with + clients that do not comply with the requirement in RFC + 1034 to use case-insensitive name comparisons when + checking for matching domain names. + </p> + <p> + If left undefined, the ACL defaults to + <span class="command"><strong>none</strong></span>: case-insensitive compression + will be used for all clients. If the ACL is defined and + matches a client, then case will be ignored when + compressing domain names in DNS responses sent to that + client. + </p> + <p> + This can result in slightly smaller responses: if + a response contains the names "example.com" and + "example.COM", case-insensitive compression would treat + the second one as a duplicate. It also ensures + that the case of the query name exactly matches the + case of the owner names of returned records, rather + than matching the case of the records entered in + the zone file. This allows responses to exactly + match the query, which is required by some clients + due to incorrect use of case-sensitive comparisons. + </p> + <p> + Case-insensitive compression is <span class="emphasis"><em>always</em></span> + used in AXFR and IXFR responses, regardless of whether + the client matches this ACL. + </p> + <p> + There are circumstances in which <span class="command"><strong>named</strong></span> + will not preserve the case of owner names of records: + if a zone file defines records of different types with + the same name, but the capitalization of the name is + different (e.g., "www.example.com/A" and + "WWW.EXAMPLE.COM/AAAA"), then all responses for that + name will use the <span class="emphasis"><em>first</em></span> version + of the name that was used in the zone file. This + limitation may be addressed in a future release. However, + domain names specified in the rdata of resource records + (i.e., records of type NS, MX, CNAME, etc) will always + have their case preserved unless the client matches this + ACL. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>resolver-query-timeout</strong></span></span></dt> +<dd> + <p> + The amount of time in seconds that the resolver + will spend attempting to resolve a recursive + query before failing. The default and minimum + is <code class="literal">10</code> and the maximum is + <code class="literal">30</code>. Setting it to + <code class="literal">0</code> will result in the default + being used. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="interfaces"></a>Interfaces</h4></div></div></div> + + <p> + The interfaces and ports that the server will answer queries + from may be specified using the <span class="command"><strong>listen-on</strong></span> option. <span class="command"><strong>listen-on</strong></span> takes + an optional port and an <code class="varname">address_match_list</code> + of IPv4 addresses. (IPv6 addresses are ignored, with a + logged warning.) + The server will listen on all interfaces allowed by the address + match list. If a port is not specified, port 53 will be used. + </p> + <p> + Multiple <span class="command"><strong>listen-on</strong></span> statements are + allowed. + For example, + </p> + +<pre class="programlisting">listen-on { 5.6.7.8; }; +listen-on port 1234 { !1.2.3.4; 1.2/16; }; +</pre> + + <p> + will enable the name server on port 53 for the IP address + 5.6.7.8, and on port 1234 of an address on the machine in net + 1.2 that is not 1.2.3.4. + </p> + + <p> + If no <span class="command"><strong>listen-on</strong></span> is specified, the + server will listen on port 53 on all IPv4 interfaces. + </p> + + <p> + The <span class="command"><strong>listen-on-v6</strong></span> option is used to + specify the interfaces and the ports on which the server will + listen for incoming queries sent using IPv6. If not specified, + the server will listen on port 53 on all IPv6 interfaces. + </p> + + <p> + When </p> +<pre class="programlisting">{ any; }</pre> +<p> is + specified + as the <code class="varname">address_match_list</code> for the + <span class="command"><strong>listen-on-v6</strong></span> option, + the server does not bind a separate socket to each IPv6 interface + address as it does for IPv4 if the operating system has enough API + support for IPv6 (specifically if it conforms to RFC 3493 and RFC + 3542). + Instead, it listens on the IPv6 wildcard address. + If the system only has incomplete API support for IPv6, however, + the behavior is the same as that for IPv4. + </p> + + <p> + A list of particular IPv6 addresses can also be specified, in + which case + the server listens on a separate socket for each specified + address, + regardless of whether the desired API is supported by the system. + IPv4 addresses specified in <span class="command"><strong>listen-on-v6</strong></span> + will be ignored, with a logged warning. + </p> + + <p> + Multiple <span class="command"><strong>listen-on-v6</strong></span> options can + be used. + For example, + </p> + +<pre class="programlisting">listen-on-v6 { any; }; +listen-on-v6 port 1234 { !2001:db8::/32; any; }; +</pre> + + <p> + will enable the name server on port 53 for any IPv6 addresses + (with a single wildcard socket), + and on port 1234 of IPv6 addresses that is not in the prefix + 2001:db8::/32 (with separate sockets for each matched address.) + </p> + + <p> + To make the server not listen on any IPv6 address, use + </p> + +<pre class="programlisting">listen-on-v6 { none; }; +</pre> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="query_address"></a>Query Address</h4></div></div></div> + + <p> + If the server doesn't know the answer to a question, it will + query other name servers. <span class="command"><strong>query-source</strong></span> specifies + the address and port used for such queries. For queries sent over + IPv6, there is a separate <span class="command"><strong>query-source-v6</strong></span> option. + If <span class="command"><strong>address</strong></span> is <span class="command"><strong>*</strong></span> (asterisk) or is omitted, + a wildcard IP address (<span class="command"><strong>INADDR_ANY</strong></span>) + will be used. + </p> + + <p> + If <span class="command"><strong>port</strong></span> is <span class="command"><strong>*</strong></span> or is omitted, + a random port number from a pre-configured + range is picked up and will be used for each query. + The port range(s) is that specified in + the <span class="command"><strong>use-v4-udp-ports</strong></span> (for IPv4) + and <span class="command"><strong>use-v6-udp-ports</strong></span> (for IPv6) + options, excluding the ranges specified in + the <span class="command"><strong>avoid-v4-udp-ports</strong></span> + and <span class="command"><strong>avoid-v6-udp-ports</strong></span> options, respectively. + </p> + + <p> + The defaults of the <span class="command"><strong>query-source</strong></span> and + <span class="command"><strong>query-source-v6</strong></span> options + are: + </p> + +<pre class="programlisting">query-source address * port *; +query-source-v6 address * port *; +</pre> + + <p> + If <span class="command"><strong>use-v4-udp-ports</strong></span> or + <span class="command"><strong>use-v6-udp-ports</strong></span> is unspecified, + <span class="command"><strong>named</strong></span> will check if the operating + system provides a programming interface to retrieve the + system's default range for ephemeral ports. + If such an interface is available, + <span class="command"><strong>named</strong></span> will use the corresponding system + default range; otherwise, it will use its own defaults: + </p> + +<pre class="programlisting">use-v4-udp-ports { range 1024 65535; }; +use-v6-udp-ports { range 1024 65535; }; +</pre> + + <p> + Note: make sure the ranges be sufficiently large for + security. A desirable size depends on various parameters, + but we generally recommend it contain at least 16384 ports + (14 bits of entropy). + Note also that the system's default range when used may be + too small for this purpose, and that the range may even be + changed while <span class="command"><strong>named</strong></span> is running; the new + range will automatically be applied when <span class="command"><strong>named</strong></span> + is reloaded. + It is encouraged to + configure <span class="command"><strong>use-v4-udp-ports</strong></span> and + <span class="command"><strong>use-v6-udp-ports</strong></span> explicitly so that the + ranges are sufficiently large and are reasonably + independent from the ranges used by other applications. + </p> + + <p> + Note: the operational configuration + where <span class="command"><strong>named</strong></span> runs may prohibit the use + of some ports. For example, UNIX systems will not allow + <span class="command"><strong>named</strong></span> running without a root privilege + to use ports less than 1024. + If such ports are included in the specified (or detected) + set of query ports, the corresponding query attempts will + fail, resulting in resolution failures or delay. + It is therefore important to configure the set of ports + that can be safely used in the expected operational environment. + </p> + + <p> + The defaults of the <span class="command"><strong>avoid-v4-udp-ports</strong></span> and + <span class="command"><strong>avoid-v6-udp-ports</strong></span> options + are: + </p> + +<pre class="programlisting">avoid-v4-udp-ports {}; +avoid-v6-udp-ports {}; +</pre> + + <p> + Note: BIND 9.5.0 introduced + the <span class="command"><strong>use-queryport-pool</strong></span> + option to support a pool of such random ports, but this + option is now obsolete because reusing the same ports in + the pool may not be sufficiently secure. + For the same reason, it is generally strongly discouraged to + specify a particular port for the + <span class="command"><strong>query-source</strong></span> or + <span class="command"><strong>query-source-v6</strong></span> options; + it implicitly disables the use of randomized port numbers. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>use-queryport-pool</strong></span></span></dt> +<dd> + <p> + This option is obsolete. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>queryport-pool-ports</strong></span></span></dt> +<dd> + <p> + This option is obsolete. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>queryport-pool-updateinterval</strong></span></span></dt> +<dd> + <p> + This option is obsolete. + </p> + </dd> +</dl></div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + The address specified in the <span class="command"><strong>query-source</strong></span> option + is used for both UDP and TCP queries, but the port applies only + to UDP queries. TCP queries always use a random + unprivileged port. + </p> + </div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Solaris 2.5.1 and earlier does not support setting the source + address for TCP sockets. + </p> + </div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + See also <span class="command"><strong>transfer-source</strong></span> and + <span class="command"><strong>notify-source</strong></span>. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="zone_transfers"></a>Zone Transfers</h4></div></div></div> + + <p> + <acronym class="acronym">BIND</acronym> has mechanisms in place to + facilitate zone transfers + and set limits on the amount of load that transfers place on the + system. The following options apply to zone transfers. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>also-notify</strong></span></span></dt> +<dd> + <p> + Defines a global list of IP addresses of name servers + that are also sent NOTIFY messages whenever a fresh copy of + the + zone is loaded, in addition to the servers listed in the + zone's NS records. + This helps to ensure that copies of the zones will + quickly converge on stealth servers. + Optionally, a port may be specified with each + <span class="command"><strong>also-notify</strong></span> address to send + the notify messages to a port other than the + default of 53. + An optional TSIG key can also be specified with each + address to cause the notify messages to be signed; this + can be useful when sending notifies to multiple views. + In place of explicit addresses, one or more named + <span class="command"><strong>masters</strong></span> lists can be used. + </p> + <p> + If an <span class="command"><strong>also-notify</strong></span> list + is given in a <span class="command"><strong>zone</strong></span> statement, + it will override + the <span class="command"><strong>options also-notify</strong></span> + statement. When a <span class="command"><strong>zone notify</strong></span> + statement + is set to <span class="command"><strong>no</strong></span>, the IP + addresses in the global <span class="command"><strong>also-notify</strong></span> list will + not be sent NOTIFY messages for that zone. The default is + the empty + list (no global notification list). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-time-in</strong></span></span></dt> +<dd> + <p> + Inbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-idle-in</strong></span></span></dt> +<dd> + <p> + Inbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes + (1 hour). The maximum value is 28 days (40320 minutes). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-time-out</strong></span></span></dt> +<dd> + <p> + Outbound zone transfers running longer than + this many minutes will be terminated. The default is 120 + minutes + (2 hours). The maximum value is 28 days (40320 minutes). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-idle-out</strong></span></span></dt> +<dd> + <p> + Outbound zone transfers making no progress + in this many minutes will be terminated. The default is 60 + minutes (1 + hour). The maximum value is 28 days (40320 minutes). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-rate</strong></span></span></dt> +<dd> + <p> + The rate at which NOTIFY requests will be sent + during normal zone maintenance operations. (NOTIFY + requests due to initial zone loading are subject + to a separate rate limit; see below.) The default is + 20 per second. + The lowest possible rate is one per second; when set + to zero, it will be silently raised to one. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>startup-notify-rate</strong></span></span></dt> +<dd> + <p> + The rate at which NOTIFY requests will be sent + when the name server is first starting up, or when + zones have been newly added to the nameserver. + The default is 20 per second. + The lowest possible rate is one per second; when set + to zero, it will be silently raised to one. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>serial-query-rate</strong></span></span></dt> +<dd> + <p> + Slave servers will periodically query master + servers to find out if zone serial numbers have + changed. Each such query uses a minute amount of + the slave server's network bandwidth. To limit + the amount of bandwidth used, BIND 9 limits the + rate at which queries are sent. The value of the + <span class="command"><strong>serial-query-rate</strong></span> option, an + integer, is the maximum number of queries sent + per second. The default is 20 per second. + The lowest possible rate is one per second; when set + to zero, it will be silently raised to one. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>serial-queries</strong></span></span></dt> +<dd> + <p> + In BIND 8, the <span class="command"><strong>serial-queries</strong></span> + option + set the maximum number of concurrent serial number queries + allowed to be outstanding at any given time. + BIND 9 does not limit the number of outstanding + serial queries and ignores the <span class="command"><strong>serial-queries</strong></span> option. + Instead, it limits the rate at which the queries are sent + as defined using the <span class="command"><strong>serial-query-rate</strong></span> option. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-format</strong></span></span></dt> +<dd> + + <p> + Zone transfers can be sent using two different formats, + <span class="command"><strong>one-answer</strong></span> and + <span class="command"><strong>many-answers</strong></span>. + The <span class="command"><strong>transfer-format</strong></span> option is used + on the master server to determine which format it sends. + <span class="command"><strong>one-answer</strong></span> uses one DNS message per + resource record transferred. + <span class="command"><strong>many-answers</strong></span> packs as many resource + records as possible into a message. + <span class="command"><strong>many-answers</strong></span> is more efficient, but is + only supported by relatively new slave servers, + such as <acronym class="acronym">BIND</acronym> 9, <acronym class="acronym">BIND</acronym> + 8.x and <acronym class="acronym">BIND</acronym> 4.9.5 onwards. + The <span class="command"><strong>many-answers</strong></span> format is also supported by + recent Microsoft Windows nameservers. + The default is <span class="command"><strong>many-answers</strong></span>. + <span class="command"><strong>transfer-format</strong></span> may be overridden on a + per-server basis by using the <span class="command"><strong>server</strong></span> + statement. + </p> + + </dd> +<dt><span class="term"><span class="command"><strong>transfer-message-size</strong></span></span></dt> +<dd> + <p> + This is an upper bound on the uncompressed size of DNS + messages used in zone transfers over TCP. If a message + grows larger than this size, additional messages will be + used to complete the zone transfer. (Note, however, + that this is a hint, not a hard limit; if a message + contains a single resource record whose RDATA does not + fit within the size limit, a larger message will be + permitted so the record can be transferred.) + </p> + <p> + Valid values are between 512 and 65535 octets, and any + values outside that range will be adjusted to the nearest + value within it. The default is <code class="literal">20480</code>, + which was selected to improve message compression: + most DNS messages of this size will compress to less + than 16536 bytes. Larger messages cannot be compressed + as effectively, because 16536 is the largest permissible + compression offset pointer in a DNS message. + </p> + <p> + This option is mainly intended for server testing; + there is rarely any benefit in setting a value other + than the default. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfers-in</strong></span></span></dt> +<dd> + <p> + The maximum number of inbound zone transfers + that can be running concurrently. The default value is <code class="literal">10</code>. + Increasing <span class="command"><strong>transfers-in</strong></span> may + speed up the convergence + of slave zones, but it also may increase the load on the + local system. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfers-out</strong></span></span></dt> +<dd> + <p> + The maximum number of outbound zone transfers + that can be running concurrently. Zone transfer requests in + excess + of the limit will be refused. The default value is <code class="literal">10</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfers-per-ns</strong></span></span></dt> +<dd> + <p> + The maximum number of inbound zone transfers + that can be concurrently transferring from a given remote + name server. + The default value is <code class="literal">2</code>. + Increasing <span class="command"><strong>transfers-per-ns</strong></span> + may + speed up the convergence of slave zones, but it also may + increase + the load on the remote name server. <span class="command"><strong>transfers-per-ns</strong></span> may + be overridden on a per-server basis by using the <span class="command"><strong>transfers</strong></span> phrase + of the <span class="command"><strong>server</strong></span> statement. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-source</strong></span></span></dt> +<dd> + <p><span class="command"><strong>transfer-source</strong></span> + determines which local address will be bound to IPv4 + TCP connections used to fetch zones transferred + inbound by the server. It also determines the + source IPv4 address, and optionally the UDP port, + used for the refresh queries and forwarded dynamic + updates. If not set, it defaults to a system + controlled value which will usually be the address + of the interface "closest to" the remote end. This + address must appear in the remote end's + <span class="command"><strong>allow-transfer</strong></span> option for the + zone being transferred, if one is specified. This + statement sets the + <span class="command"><strong>transfer-source</strong></span> for all zones, + but can be overridden on a per-view or per-zone + basis by including a + <span class="command"><strong>transfer-source</strong></span> statement within + the <span class="command"><strong>view</strong></span> or + <span class="command"><strong>zone</strong></span> block in the configuration + file. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Solaris 2.5.1 and earlier does not support setting the + source address for TCP sockets. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-source-v6</strong></span></span></dt> +<dd> + <p> + The same as <span class="command"><strong>transfer-source</strong></span>, + except zone transfers are performed using IPv6. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>alt-transfer-source</strong></span></span></dt> +<dd> + <p> + An alternate transfer source if the one listed in + <span class="command"><strong>transfer-source</strong></span> fails and + <span class="command"><strong>use-alt-transfer-source</strong></span> is + set. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + If you do not wish the alternate transfer source + to be used, you should set + <span class="command"><strong>use-alt-transfer-source</strong></span> + appropriately and you should not depend upon + getting an answer back to the first refresh + query. + </p> +</div> + </dd> +<dt><span class="term"><span class="command"><strong>alt-transfer-source-v6</strong></span></span></dt> +<dd> + <p> + An alternate transfer source if the one listed in + <span class="command"><strong>transfer-source-v6</strong></span> fails and + <span class="command"><strong>use-alt-transfer-source</strong></span> is + set. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>use-alt-transfer-source</strong></span></span></dt> +<dd> + <p> + Use the alternate transfer sources or not. If views are + specified this defaults to <span class="command"><strong>no</strong></span> + otherwise it defaults to + <span class="command"><strong>yes</strong></span> (for BIND 8 + compatibility). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-source</strong></span></span></dt> +<dd> + <p><span class="command"><strong>notify-source</strong></span> + determines which local source address, and + optionally UDP port, will be used to send NOTIFY + messages. This address must appear in the slave + server's <span class="command"><strong>masters</strong></span> zone clause or + in an <span class="command"><strong>allow-notify</strong></span> clause. This + statement sets the <span class="command"><strong>notify-source</strong></span> + for all zones, but can be overridden on a per-zone or + per-view basis by including a + <span class="command"><strong>notify-source</strong></span> statement within + the <span class="command"><strong>zone</strong></span> or + <span class="command"><strong>view</strong></span> block in the configuration + file. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Solaris 2.5.1 and earlier does not support setting the + source address for TCP sockets. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>notify-source-v6</strong></span></span></dt> +<dd> + <p> + Like <span class="command"><strong>notify-source</strong></span>, + but applies to notify messages sent to IPv6 addresses. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="port_lists"></a>UDP Port Lists</h4></div></div></div> + + <p> + <span class="command"><strong>use-v4-udp-ports</strong></span>, + <span class="command"><strong>avoid-v4-udp-ports</strong></span>, + <span class="command"><strong>use-v6-udp-ports</strong></span>, and + <span class="command"><strong>avoid-v6-udp-ports</strong></span> + specify a list of IPv4 and IPv6 UDP ports that will be + used or not used as source ports for UDP messages. + See <a class="xref" href="Bv9ARM.ch06.html#query_address" title="Query Address">the section called “Query Address”</a> about how the + available ports are determined. + For example, with the following configuration + </p> + +<pre class="programlisting"> +use-v6-udp-ports { range 32768 65535; }; +avoid-v6-udp-ports { 40000; range 50000 60000; }; +</pre> + + <p> + UDP ports of IPv6 messages sent + from <span class="command"><strong>named</strong></span> will be in one + of the following ranges: 32768 to 39999, 40001 to 49999, + and 60001 to 65535. + </p> + + <p> + <span class="command"><strong>avoid-v4-udp-ports</strong></span> and + <span class="command"><strong>avoid-v6-udp-ports</strong></span> can be used + to prevent <span class="command"><strong>named</strong></span> from choosing as its random source port a + port that is blocked by your firewall or a port that is + used by other applications; + if a query went out with a source port blocked by a + firewall, the + answer would not get by the firewall and the name server would + have to query again. + Note: the desired range can also be represented only with + <span class="command"><strong>use-v4-udp-ports</strong></span> and + <span class="command"><strong>use-v6-udp-ports</strong></span>, and the + <span class="command"><strong>avoid-</strong></span> options are redundant in that + sense; they are provided for backward compatibility and + to possibly simplify the port specification. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="resource_limits"></a>Operating System Resource Limits</h4></div></div></div> + + <p> + The server's usage of many system resources can be limited. + Scaled values are allowed when specifying resource limits. For + example, <span class="command"><strong>1G</strong></span> can be used instead of + <span class="command"><strong>1073741824</strong></span> to specify a limit of + one + gigabyte. <span class="command"><strong>unlimited</strong></span> requests + unlimited use, or the + maximum available amount. <span class="command"><strong>default</strong></span> + uses the limit + that was in force when the server was started. See the description + of <span class="command"><strong>size_spec</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#configuration_file_elements" title="Configuration File Elements">the section called “Configuration File Elements”</a>. + </p> + + <p> + The following options set operating system resource limits for + the name server process. Some operating systems don't support + some or + any of the limits. On such systems, a warning will be issued if + the + unsupported limit is used. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>coresize</strong></span></span></dt> +<dd> + <p> + The maximum size of a core dump. The default + is <code class="literal">default</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>datasize</strong></span></span></dt> +<dd> + <p> + The maximum amount of data memory the server + may use. The default is <code class="literal">default</code>. + This is a hard limit on server memory usage. + If the server attempts to allocate memory in excess of this + limit, the allocation will fail, which may in turn leave + the server unable to perform DNS service. Therefore, + this option is rarely useful as a way of limiting the + amount of memory used by the server, but it can be used + to raise an operating system data size limit that is + too small by default. If you wish to limit the amount + of memory used by the server, use the + <span class="command"><strong>max-cache-size</strong></span> and + <span class="command"><strong>recursive-clients</strong></span> + options instead. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>files</strong></span></span></dt> +<dd> + <p> + The maximum number of files the server + may have open concurrently. The default is <code class="literal">unlimited</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>stacksize</strong></span></span></dt> +<dd> + <p> + The maximum amount of stack memory the server + may use. The default is <code class="literal">default</code>. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="server_resource_limits"></a>Server Resource Limits</h4></div></div></div> + + <p> + The following options set limits on the server's + resource consumption that are enforced internally by the + server rather than the operating system. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>max-ixfr-log-size</strong></span></span></dt> +<dd> + <p> + This option is obsolete; it is accepted + and ignored for BIND 8 compatibility. The option + <span class="command"><strong>max-journal-size</strong></span> performs a + similar function in BIND 9. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-journal-size</strong></span></span></dt> +<dd> + <p> + Sets a maximum size for each journal file + (see <a class="xref" href="Bv9ARM.ch04.html#journal" title="The journal file">the section called “The journal file”</a>). When the journal file + approaches + the specified size, some of the oldest transactions in the + journal + will be automatically removed. The largest permitted + value is 2 gigabytes. The default is + <code class="literal">unlimited</code>, which also + means 2 gigabytes. + This may also be set on a per-zone basis. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-records</strong></span></span></dt> +<dd> + <p> + The maximum number of records permitted in a zone. + The default is zero which means unlimited. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>host-statistics-max</strong></span></span></dt> +<dd> + <p> + In BIND 8, specifies the maximum number of host statistics + entries to be kept. + Not implemented in BIND 9. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>recursive-clients</strong></span></span></dt> +<dd> + <p> + The maximum number ("hard quota") of simultaneous + recursive lookups the server will perform on behalf + of clients. The default is + <code class="literal">1000</code>. Because each recursing + client uses a fair + bit of memory (on the order of 20 kilobytes), the + value of the + <span class="command"><strong>recursive-clients</strong></span> option may + have to be decreased on hosts with limited memory. + </p> + <p> + <code class="option">recursive-clients</code> defines a "hard + quota" limit for pending recursive clients: when more + clients than this are pending, new incoming requests + will not be accepted, and for each incoming request + a previous pending request will also be dropped. + </p> + <p> + A "soft quota" is also set. When this lower + quota is exceeded, incoming requests are accepted, but + for each one, a pending request will be dropped. + If <code class="option">recursive-clients</code> is greater than + 1000, the soft quota is set to + <code class="option">recursive-clients</code> minus 100; + otherwise it is set to 90% of + <code class="option">recursive-clients</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tcp-clients</strong></span></span></dt> +<dd> + <p> + The maximum number of simultaneous client TCP + connections that the server will accept. + The default is <code class="literal">150</code>. + </p> + </dd> +<dt> +<a name="clients-per-query"></a><span class="term"><a name="cpq_term"></a><span class="command"><strong>clients-per-query</strong></span>, </span><span class="term"><span class="command"><strong>max-clients-per-query</strong></span></span> +</dt> +<dd> + <p>These set the + initial value (minimum) and maximum number of recursive + simultaneous clients for any given query + (<qname,qtype,qclass>) that the server will accept + before dropping additional clients. <span class="command"><strong>named</strong></span> will attempt to + self tune this value and changes will be logged. The + default values are 10 and 100. + </p> + <p> + This value should reflect how many queries come in for + a given name in the time it takes to resolve that name. + If the number of queries exceed this value, <span class="command"><strong>named</strong></span> will + assume that it is dealing with a non-responsive zone + and will drop additional queries. If it gets a response + after dropping queries, it will raise the estimate. The + estimate will then be lowered in 20 minutes if it has + remained unchanged. + </p> + <p> + If <span class="command"><strong>clients-per-query</strong></span> is set to zero, + then there is no limit on the number of clients per query + and no queries will be dropped. + </p> + <p> + If <span class="command"><strong>max-clients-per-query</strong></span> is set to zero, + then there is no upper bound other than imposed by + <span class="command"><strong>recursive-clients</strong></span>. + </p> + </dd> +<dt> +<a name="fetches-per-zone"></a><span class="term"><span class="command"><strong>fetches-per-zone</strong></span></span> +</dt> +<dd> + <p> + The maximum number of simultaneous iterative + queries to any one domain that the server will + permit before blocking new queries for data + in or beneath that zone. + This value should reflect how many fetches would + normally be sent to any one zone in the time it + would take to resolve them. It should be smaller + than <code class="option">recursive-clients</code>. + </p> + <p> + When many clients simultaneously query for the + same name and type, the clients will all be attached + to the same fetch, up to the + <code class="option">max-clients-per-query</code> limit, + and only one iterative query will be sent. + However, when clients are simultaneously + querying for <span class="emphasis"><em>different</em></span> names + or types, multiple queries will be sent and + <code class="option">max-clients-per-query</code> is not + effective as a limit. + </p> + <p> + Optionally, this value may be followed by the keyword + <code class="literal">drop</code> or <code class="literal">fail</code>, + indicating whether queries which exceed the fetch + quota for a zone will be dropped with no response, + or answered with SERVFAIL. The default is + <code class="literal">drop</code>. + </p> + <p> + If <span class="command"><strong>fetches-per-zone</strong></span> is set to zero, + then there is no limit on the number of fetches per query + and no queries will be dropped. The default is zero. + </p> + <p> + The current list of active fetches can be dumped by + running <span class="command"><strong>rndc recursing</strong></span>. The list + includes the number of active fetches for each + domain and the number of queries that have been + passed or dropped as a result of the + <code class="option">fetches-per-zone</code> limit. (Note: + these counters are not cumulative over time; whenever + the number of active fetches for a domain drops to + zero, the counter for that domain is deleted, and the + next time a fetch is sent to that domain, it is + recreated with the counters set to zero.) + </p> + </dd> +<dt> +<a name="fetches-per-server"></a><span class="term"><span class="command"><strong>fetches-per-server</strong></span></span> +</dt> +<dd> + <p> + The maximum number of simultaneous iterative + queries that the server will allow to be sent to + a single upstream name server before blocking + additional queries. + This value should reflect how many fetches would + normally be sent to any one server in the time it + would take to resolve them. It should be smaller + than <code class="option">recursive-clients</code>. + </p> + <p> + Optionally, this value may be followed by the keyword + <code class="literal">drop</code> or <code class="literal">fail</code>, + indicating whether queries will be dropped with no + response, or answered with SERVFAIL, when all of the + servers authoritative for a zone are found to have + exceeded the per-server quota. The default is + <code class="literal">fail</code>. + </p> + <p> + If <span class="command"><strong>fetches-per-server</strong></span> is set to zero, + then there is no limit on the number of fetches per query + and no queries will be dropped. The default is zero. + </p> + <p> + The <span class="command"><strong>fetches-per-server</strong></span> quota is + dynamically adjusted in response to detected + congestion. As queries are sent to a server + and are either answered or time out, an + exponentially weighted moving average is calculated + of the ratio of timeouts to responses. If the + current average timeout ratio rises above a "high" + threshold, then <span class="command"><strong>fetches-per-server</strong></span> + is reduced for that server. If the timeout ratio + drops below a "low" threshold, then + <span class="command"><strong>fetches-per-server</strong></span> is increased. + The <span class="command"><strong>fetch-quota-params</strong></span> options + can be used to adjust the parameters for this + calculation. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>fetch-quota-params</strong></span></span></dt> +<dd> + <p> + Sets the parameters to use for dynamic resizing of + the <code class="option">fetches-per-server</code> quota in + response to detected congestion. + </p> + <p> + The first argument is an integer value indicating + how frequently to recalculate the moving average + of the ratio of timeouts to responses for each + server. The default is 100, meaning we recalculate + the average ratio after every 100 queries have either + been answered or timed out. + </p> + <p> + The remaining three arguments represent the "low" + threshold (defaulting to a timeout ratio of 0.1), + the "high" threshold (defaulting to a timeout + ratio of 0.3), and the discount rate for + the moving average (defaulting to 0.7). + A higher discount rate causes recent events to + weigh more heavily when calculating the moving + average; a lower discount rate causes past + events to weigh more heavily, smoothing out + short-term blips in the timeout ratio. + These arguments are all fixed-point numbers with + precision of 1/100: at most two places after + the decimal point are significant. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>reserved-sockets</strong></span></span></dt> +<dd> + <p> + The number of file descriptors reserved for TCP, stdio, + etc. This needs to be big enough to cover the number of + interfaces <span class="command"><strong>named</strong></span> listens on, <span class="command"><strong>tcp-clients</strong></span> as well as + to provide room for outgoing TCP queries and incoming zone + transfers. The default is <code class="literal">512</code>. + The minimum value is <code class="literal">128</code> and the + maximum value is <code class="literal">128</code> less than + maxsockets (-S). This option may be removed in the future. + </p> + <p> + This option has little effect on Windows. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-cache-size</strong></span></span></dt> +<dd> + <p> + The maximum amount of memory to use for the + server's cache, in bytes or % of total physical memory. + When the amount of data in the cache + reaches this limit, the server will cause records to + expire prematurely based on an LRU based strategy so + that the limit is not exceeded. + The keyword <strong class="userinput"><code>unlimited</code></strong>, + or the value 0, will place no limit on cache size; + records will be purged from the cache only when their + TTLs expire. + Any positive values less than 2MB will be ignored + and reset to 2MB. + In a server with multiple views, the limit applies + separately to the cache of each view. + The default is <strong class="userinput"><code>90%</code></strong>. + On systems where detection of amount of physical + memory is not supported values represented as % + fall back to unlimited. + Note that the detection of physical memory is done only + once at startup, so <span class="command"><strong>named</strong></span> will not + adjust the cache size if the amount of physical memory + is changed during runtime. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>tcp-listen-queue</strong></span></span></dt> +<dd> + <p> + The listen queue depth. The default and minimum is 10. + If the kernel supports the accept filter "dataready" this + also controls how + many TCP connections that will be queued in kernel space + waiting for + some data before being passed to accept. Nonzero values + less than 10 will be silently raised. A value of 0 may also + be used; on most platforms this sets the listen queue + length to a system-defined default value. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="intervals"></a>Periodic Task Intervals</h4></div></div></div> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>cleaning-interval</strong></span></span></dt> +<dd> + <p> + This interval is effectively obsolete. Previously, + the server would remove expired resource records + from the cache every <span class="command"><strong>cleaning-interval</strong></span> minutes. + <acronym class="acronym">BIND</acronym> 9 now manages cache + memory in a more sophisticated manner and does not + rely on the periodic cleaning any more. + Specifying this option therefore has no effect on + the server's behavior. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>heartbeat-interval</strong></span></span></dt> +<dd> + <p> + The server will perform zone maintenance tasks + for all zones marked as <span class="command"><strong>dialup</strong></span> whenever this + interval expires. The default is 60 minutes. Reasonable + values are up + to 1 day (1440 minutes). The maximum value is 28 days + (40320 minutes). + If set to 0, no zone maintenance for these zones will occur. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>interface-interval</strong></span></span></dt> +<dd> + <p> + The server will scan the network interface list + every <span class="command"><strong>interface-interval</strong></span> + minutes. The default + is 60 minutes. The maximum value is 28 days (40320 minutes). + If set to 0, interface scanning will only occur when + the configuration file is loaded. After the scan, the + server will + begin listening for queries on any newly discovered + interfaces (provided they are allowed by the + <span class="command"><strong>listen-on</strong></span> configuration), and + will + stop listening on interfaces that have gone away. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>statistics-interval</strong></span></span></dt> +<dd> + <p> + Name server statistics will be logged + every <span class="command"><strong>statistics-interval</strong></span> + minutes. The default is + 60. The maximum value is 28 days (40320 minutes). + If set to 0, no statistics will be logged. + </p> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Not yet implemented in + <acronym class="acronym">BIND</acronym> 9. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>topology</strong></span></span></dt> +<dd> + <p> + In BIND 8, this option indicated network topology + so that preferential treatment could be given to + the topologicaly closest name servers when sending + queries. It is not implemented in BIND 9. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="the_sortlist_statement"></a>The <span class="command"><strong>sortlist</strong></span> Statement</h4></div></div></div> + + <p> + The response to a DNS query may consist of multiple resource + records (RRs) forming a resource record set (RRset). The name + server will normally return the RRs within the RRset in an + indeterminate order (but see the <span class="command"><strong>rrset-order</strong></span> + statement in <a class="xref" href="Bv9ARM.ch06.html#rrset_ordering" title="RRset Ordering">the section called “RRset Ordering”</a>). The client + resolver code should rearrange the RRs as appropriate, that is, + using any addresses on the local net in preference to other + addresses. However, not all resolvers can do this or are + correctly configured. When a client is using a local server, + the sorting can be performed in the server, based on the + client's address. This only requires configuring the name + servers, not all the clients. + </p> + + <p> + The <span class="command"><strong>sortlist</strong></span> statement (see below) takes an + <span class="command"><strong>address_match_list</strong></span> and interprets it in a + special way. Each top level statement in the + <span class="command"><strong>sortlist</strong></span> must itself be an explicit + <span class="command"><strong>address_match_list</strong></span> with one or two elements. + The first element (which may be an IP address, an IP prefix, an + ACL name or a nested <span class="command"><strong>address_match_list</strong></span>) of + each top level list is checked against the source address of + the query until a match is found. + </p> + <p> + Once the source address of the query has been matched, if the + top level statement contains only one element, the actual + primitive element that matched the source address is used to + select the address in the response to move to the beginning of + the response. If the statement is a list of two elements, then + the second element is interpreted as a topology preference + list. Each top level element is assigned a distance and the + address in the response with the minimum distance is moved to + the beginning of the response. + </p> + <p> + In the following example, any queries received from any of the + addresses of the host itself will get responses preferring + addresses on any of the locally connected networks. Next most + preferred are addresses on the 192.168.1/24 network, and after + that either the 192.168.2/24 or 192.168.3/24 network with no + preference shown between these two networks. Queries received + from a host on the 192.168.1/24 network will prefer other + addresses on that network to the 192.168.2/24 and 192.168.3/24 + networks. Queries received from a host on the 192.168.4/24 or + the 192.168.5/24 network will only prefer other addresses on + their directly connected networks. + </p> + +<pre class="programlisting">sortlist { + // IF the local host + // THEN first fit on the following nets + { localhost; + { localnets; + 192.168.1/24; + { 192.168.2/24; 192.168.3/24; }; }; }; + // IF on class C 192.168.1 THEN use .1, or .2 or .3 + { 192.168.1/24; + { 192.168.1/24; + { 192.168.2/24; 192.168.3/24; }; }; }; + // IF on class C 192.168.2 THEN use .2, or .1 or .3 + { 192.168.2/24; + { 192.168.2/24; + { 192.168.1/24; 192.168.3/24; }; }; }; + // IF on class C 192.168.3 THEN use .3, or .1 or .2 + { 192.168.3/24; + { 192.168.3/24; + { 192.168.1/24; 192.168.2/24; }; }; }; + // IF .4 or .5 THEN prefer that net + { { 192.168.4/24; 192.168.5/24; }; + }; +};</pre> + + <p> + The following example will give reasonable behavior for the + local host and hosts on directly connected networks. It is + similar to the behavior of the address sort in + <acronym class="acronym">BIND</acronym> 4.9.x. Responses sent to queries from + the local host will favor any of the directly connected + networks. Responses sent to queries from any other hosts on a + directly connected network will prefer addresses on that same + network. Responses to other queries will not be sorted. + </p> + +<pre class="programlisting">sortlist { + { localhost; localnets; }; + { localnets; }; +}; +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="rrset_ordering"></a>RRset Ordering</h4></div></div></div> + + <p> + When multiple records are returned in an answer it may be + useful to configure the order of the records placed into the + response. + The <span class="command"><strong>rrset-order</strong></span> statement permits + configuration + of the ordering of the records in a multiple record response. + See also the <span class="command"><strong>sortlist</strong></span> statement, + <a class="xref" href="Bv9ARM.ch06.html#the_sortlist_statement" title="The sortlist Statement">the section called “The <span class="command"><strong>sortlist</strong></span> Statement”</a>. + </p> + + <p> + An <span class="command"><strong>order_spec</strong></span> is defined as + follows: + </p> + <p> + [<span class="optional">class <em class="replaceable"><code>class_name</code></em></span>] + [<span class="optional">type <em class="replaceable"><code>type_name</code></em></span>] + [<span class="optional">name <em class="replaceable"><code>"domain_name"</code></em></span>] + order <em class="replaceable"><code>ordering</code></em> + </p> + <p> + If no class is specified, the default is <span class="command"><strong>ANY</strong></span>. + If no type is specified, the default is <span class="command"><strong>ANY</strong></span>. + If no name is specified, the default is "<span class="command"><strong>*</strong></span>" (asterisk). + </p> + <p> + The legal values for <span class="command"><strong>ordering</strong></span> are: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.750in" class="1"> +<col width="3.750in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>fixed</strong></span></p> + </td> +<td> + <p> + Records are returned in the order they + are defined in the zone file. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>random</strong></span></p> + </td> +<td> + <p> + Records are returned in some random order. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>cyclic</strong></span></p> + </td> +<td> + <p> + Records are returned in a cyclic round-robin order. + </p> + <p> + If <acronym class="acronym">BIND</acronym> is configured with the + "--enable-fixed-rrset" option at compile time, then + the initial ordering of the RRset will match the + one specified in the zone file. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + For example: + </p> + +<pre class="programlisting">rrset-order { + class IN type A name "host.example.com" order random; + order cyclic; +}; +</pre> + + <p> + will cause any responses for type A records in class IN that + have "<code class="literal">host.example.com</code>" as a + suffix, to always be returned + in random order. All other records are returned in cyclic order. + </p> + <p> + If multiple <span class="command"><strong>rrset-order</strong></span> statements + appear, they are not combined — the last one applies. + </p> + <p> + By default, all records are returned in random order. + </p> + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + In this release of <acronym class="acronym">BIND</acronym> 9, the + <span class="command"><strong>rrset-order</strong></span> statement does not support + "fixed" ordering by default. Fixed ordering can be enabled + at compile time by specifying "--enable-fixed-rrset" on + the "configure" command line. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="tuning"></a>Tuning</h4></div></div></div> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>lame-ttl</strong></span></span></dt> +<dd> + <p> + Sets the number of seconds to cache a + lame server indication. 0 disables caching. (This is + <span class="bold"><strong>NOT</strong></span> recommended.) + The default is <code class="literal">600</code> (10 minutes) and the + maximum value is + <code class="literal">1800</code> (30 minutes). + </p> + + </dd> +<dt><span class="term"><span class="command"><strong>servfail-ttl</strong></span></span></dt> +<dd> + <p> + Sets the number of seconds to cache a + SERVFAIL response due to DNSSEC validation failure or + other general server failure. If set to + <code class="literal">0</code>, SERVFAIL caching is disabled. + The SERVFAIL cache is not consulted if a query has + the CD (Checking Disabled) bit set; this allows a + query that failed due to DNSSEC validation to be retried + without waiting for the SERVFAIL TTL to expire. + </p> + <p> + The maximum value is <code class="literal">30</code> + seconds; any higher value will be silently + reduced. The default is <code class="literal">1</code> + second. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-ncache-ttl</strong></span></span></dt> +<dd> + <p> + To reduce network traffic and increase performance, + the server stores negative answers. <span class="command"><strong>max-ncache-ttl</strong></span> is + used to set a maximum retention time for these answers in + the server + in seconds. The default + <span class="command"><strong>max-ncache-ttl</strong></span> is <code class="literal">10800</code> seconds (3 hours). + <span class="command"><strong>max-ncache-ttl</strong></span> cannot exceed + 7 days and will + be silently truncated to 7 days if set to a greater value. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-cache-ttl</strong></span></span></dt> +<dd> + <p> + Sets the maximum time for which the server will + cache ordinary (positive) answers in seconds. + The default is 604800 (one week). + A value of zero may cause all queries to return + SERVFAIL, because of lost caches of intermediate + RRsets (such as NS and glue AAAA/A records) in the + resolution process. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>min-roots</strong></span></span></dt> +<dd> + <p> + The minimum number of root servers that + is required for a request for the root servers to be + accepted. The default + is <strong class="userinput"><code>2</code></strong>. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + Not implemented in <acronym class="acronym">BIND</acronym> 9. + </p> + </div> + </dd> +<dt><span class="term"><span class="command"><strong>sig-validity-interval</strong></span></span></dt> +<dd> + <p> + Specifies the number of days into the future when + DNSSEC signatures automatically generated as a + result of dynamic updates (<a class="xref" href="Bv9ARM.ch04.html#dynamic_update" title="Dynamic Update">the section called “Dynamic Update”</a>) will expire. There + is an optional second field which specifies how + long before expiry that the signatures will be + regenerated. If not specified, the signatures will + be regenerated at 1/4 of base interval. The second + field is specified in days if the base interval is + greater than 7 days otherwise it is specified in hours. + The default base interval is <code class="literal">30</code> days + giving a re-signing interval of 7 1/2 days. The maximum + values are 10 years (3660 days). + </p> + <p> + The signature inception time is unconditionally + set to one hour before the current time to allow + for a limited amount of clock skew. + </p> + <p> + The <span class="command"><strong>sig-validity-interval</strong></span> + should be, at least, several multiples of the SOA + expire interval to allow for reasonable interaction + between the various timer and expiry dates. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-nodes</strong></span></span></dt> +<dd> + <p> + Specify the maximum number of nodes to be + examined in each quantum when signing a zone with + a new DNSKEY. The default is + <code class="literal">100</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-signatures</strong></span></span></dt> +<dd> + <p> + Specify a threshold number of signatures that + will terminate processing a quantum when signing + a zone with a new DNSKEY. The default is + <code class="literal">10</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-type</strong></span></span></dt> +<dd> + <p> + Specify a private RDATA type to be used when generating + signing state records. The default is + <code class="literal">65534</code>. + </p> + <p> + It is expected that this parameter may be removed + in a future version once there is a standard type. + </p> + <p> + Signing state records are used to internally by + <span class="command"><strong>named</strong></span> to track the current state of + a zone-signing process, i.e., whether it is still active + or has been completed. The records can be inspected + using the command + <span class="command"><strong>rndc signing -list <em class="replaceable"><code>zone</code></em></strong></span>. + Once <span class="command"><strong>named</strong></span> has finished signing + a zone with a particular key, the signing state + record associated with that key can be removed from + the zone by running + <span class="command"><strong>rndc signing -clear <em class="replaceable"><code>keyid/algorithm</code></em> <em class="replaceable"><code>zone</code></em></strong></span>. + To clear all of the completed signing state + records for a zone, use + <span class="command"><strong>rndc signing -clear all <em class="replaceable"><code>zone</code></em></strong></span>. + </p> + </dd> +<dt> +<span class="term"><span class="command"><strong>min-refresh-time</strong></span>, </span><span class="term"><span class="command"><strong>max-refresh-time</strong></span>, </span><span class="term"><span class="command"><strong>min-retry-time</strong></span>, </span><span class="term"><span class="command"><strong>max-retry-time</strong></span></span> +</dt> +<dd> + <p> + These options control the server's behavior on refreshing a + zone (querying for SOA changes) or retrying failed + transfers. Usually the SOA values for the zone are used, + up to a hard-coded maximum expiry of 24 weeks. However, + these values are set by the master, giving slave server + administrators little control over their contents. + </p> + <p> + These options allow the administrator to set a minimum and + maximum refresh and retry time in seconds per-zone, + per-view, or globally. These options are valid for + slave and stub zones, and clamp the SOA refresh and + retry times to the specified values. + </p> + <p> + The following defaults apply. + <span class="command"><strong>min-refresh-time</strong></span> 300 seconds, + <span class="command"><strong>max-refresh-time</strong></span> 2419200 seconds + (4 weeks), <span class="command"><strong>min-retry-time</strong></span> 500 seconds, + and <span class="command"><strong>max-retry-time</strong></span> 1209600 seconds + (2 weeks). + </p> + </dd> +<dt><span class="term"><span class="command"><strong>edns-udp-size</strong></span></span></dt> +<dd> + <p> + Sets the maximum advertised EDNS UDP buffer size in + bytes, to control the size of packets received from + authoritative servers in response to recursive queries. + Valid values are 512 to 4096 (values outside this range + will be silently adjusted to the nearest value within + it). The default value is 4096. + </p> + <p> + The usual reason for setting + <span class="command"><strong>edns-udp-size</strong></span> to a non-default value + is to get UDP answers to pass through broken firewalls + that block fragmented packets and/or block UDP DNS + packets that are greater than 512 bytes. + </p> + <p> + When <span class="command"><strong>named</strong></span> first queries a remote + server, it will advertise a UDP buffer size of 512, as + this has the greatest chance of success on the first try. + </p> + <p> + If the initial response times out, <span class="command"><strong>named</strong></span> + will try again with plain DNS, and if that is successful, + it will be taken as evidence that the server does not + support EDNS. After enough failures using EDNS and + successes using plain DNS, <span class="command"><strong>named</strong></span> + will default to plain DNS for future communications + with that server. (Periodically, <span class="command"><strong>named</strong></span> + will send an EDNS query to see if the situation has + improved.) + </p> + <p> + However, if the initial query is successful with + EDNS advertising a buffer size of 512, then + <span class="command"><strong>named</strong></span> will advertise progressively + larger buffer sizes on successive queries, until + responses begin timing out or + <span class="command"><strong>edns-udp-size</strong></span> is reached. + </p> + <p> + The default buffer sizes used by <span class="command"><strong>named</strong></span> + are 512, 1232, 1432, and 4096, but never exceeding + <span class="command"><strong>edns-udp-size</strong></span>. (The values 1232 and + 1432 are chosen to allow for an IPv4/IPv6 encapsulated + UDP message to be sent without fragmentation at the + minimum MTU sizes for Ethernet and IPv6 networks.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-udp-size</strong></span></span></dt> +<dd> + <p> + Sets the maximum EDNS UDP message size + <span class="command"><strong>named</strong></span> will send in bytes. + Valid values are 512 to 4096 (values outside this + range will be silently adjusted to the nearest + value within it). The default value is 4096. + </p> + <p> + This value applies to responses sent by a server; to + set the advertised buffer size in queries, see + <span class="command"><strong>edns-udp-size</strong></span>. + </p> + <p> + The usual reason for setting + <span class="command"><strong>max-udp-size</strong></span> to a non-default + value is to get UDP answers to pass through broken + firewalls that block fragmented packets and/or + block UDP packets that are greater than 512 bytes. + This is independent of the advertised receive + buffer (<span class="command"><strong>edns-udp-size</strong></span>). + </p> + <p> + Setting this to a low value will encourage additional + TCP traffic to the nameserver. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>masterfile-format</strong></span></span></dt> +<dd> + <p>Specifies + the file format of zone files (see + <a class="xref" href="Bv9ARM.ch06.html#zonefile_format" title="Additional File Formats">the section called “Additional File Formats”</a>). + The default value is <code class="constant">text</code>, which is the + standard textual representation, except for slave zones, + in which the default value is <code class="constant">raw</code>. + Files in other formats than <code class="constant">text</code> are + typically expected to be generated by the + <span class="command"><strong>named-compilezone</strong></span> tool, or dumped by + <span class="command"><strong>named</strong></span>. + </p> + <p> + Note that when a zone file in a different format than + <code class="constant">text</code> is loaded, <span class="command"><strong>named</strong></span> + may omit some of the checks which would be performed for a + file in the <code class="constant">text</code> format. In particular, + <span class="command"><strong>check-names</strong></span> checks do not apply + for the <code class="constant">raw</code> format. This means + a zone file in the <code class="constant">raw</code> format + must be generated with the same check level as that + specified in the <span class="command"><strong>named</strong></span> configuration + file. Also, <code class="constant">map</code> format files are + loaded directly into memory via memory mapping, with only + minimal checking. + </p> + <p> + This statement sets the + <span class="command"><strong>masterfile-format</strong></span> for all zones, + but can be overridden on a per-zone or per-view basis + by including a <span class="command"><strong>masterfile-format</strong></span> + statement within the <span class="command"><strong>zone</strong></span> or + <span class="command"><strong>view</strong></span> block in the configuration + file. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>masterfile-style</strong></span></span></dt> +<dd> + <p> + Specifies the formatting of zone files during dump + when the <code class="option">masterfile-format</code> is + <code class="constant">text</code>. (This option is ignored + with any other <code class="option">masterfile-format</code>.) + </p> + <p> + When set to <code class="constant">relative</code>, + records are printed in a multi-line format with owner + names expressed relative to a shared origin. When set + to <code class="constant">full</code>, records are printed in + a single-line format with absolute owner names. + The <code class="constant">full</code> format is most suitable + when a zone file needs to be processed automatically + by a script. The <code class="constant">relative</code> format + is more human-readable, and is thus suitable when a + zone is to be edited by hand. The default is + <code class="constant">relative</code>. + </p> + </dd> +<dt> +<a name="max-recursion-depth"></a><span class="term"><span class="command"><strong>max-recursion-depth</strong></span></span> +</dt> +<dd> + <p> + Sets the maximum number of levels of recursion + that are permitted at any one time while servicing + a recursive query. Resolving a name may require + looking up a name server address, which in turn + requires resolving another name, etc; if the number + of indirections exceeds this value, the recursive + query is terminated and returns SERVFAIL. The + default is 7. + </p> + </dd> +<dt> +<a name="max-recursion-queries"></a><span class="term"><span class="command"><strong>max-recursion-queries</strong></span></span> +</dt> +<dd> + <p> + Sets the maximum number of iterative queries that + may be sent while servicing a recursive query. + If more queries are sent, the recursive query + is terminated and returns SERVFAIL. Queries to + look up top level domains such as "com" and "net" + and the DNS root zone are exempt from this limitation. + The default is 75. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-delay</strong></span></span></dt> +<dd> + <p> + The delay, in seconds, between sending sets of notify + messages for a zone. The default is five (5) seconds. + </p> + <p> + The overall rate that NOTIFY messages are sent for all + zones is controlled by <span class="command"><strong>serial-query-rate</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-rsa-exponent-size</strong></span></span></dt> +<dd> + <p> + The maximum RSA exponent size, in bits, that will + be accepted when validating. Valid values are 35 + to 4096 bits. The default zero (0) is also accepted + and is equivalent to 4096. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>prefetch</strong></span></span></dt> +<dd> + <p> + When a query is received for cached data which + is to expire shortly, <span class="command"><strong>named</strong></span> can + refresh the data from the authoritative server + immediately, ensuring that the cache always has an + answer available. + </p> + <p> + The <code class="option">prefetch</code> specifies the + "trigger" TTL value at which prefetch of the current + query will take place: when a cache record with a + lower TTL value is encountered during query processing, + it will be refreshed. Valid trigger TTL values are 1 to + 10 seconds. Values larger than 10 seconds will be silently + reduced to 10. + Setting a trigger TTL to zero (0) causes + prefetch to be disabled. + The default trigger TTL is <code class="literal">2</code>. + </p> + <p> + An optional second argument specifies the "eligibility" + TTL: the smallest <span class="emphasis"><em>original</em></span> + TTL value that will be accepted for a record to be + eligible for prefetching. The eligibility TTL must + be at least six seconds longer than the trigger TTL; + if it isn't, <span class="command"><strong>named</strong></span> will silently + adjust it upward. + The default eligibility TTL is <code class="literal">9</code>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>v6-bias</strong></span></span></dt> +<dd> + <p> + When determining the next nameserver to try + preference IPv6 nameservers by this many milliseconds. + The default is <code class="literal">50</code> milliseconds. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="builtin"></a>Built-in server information zones</h4></div></div></div> + + <p> + The server provides some helpful diagnostic information + through a number of built-in zones under the + pseudo-top-level-domain <code class="literal">bind</code> in the + <span class="command"><strong>CHAOS</strong></span> class. These zones are part + of a + built-in view (see <a class="xref" href="Bv9ARM.ch06.html#view_statement_grammar" title="view Statement Grammar">the section called “<span class="command"><strong>view</strong></span> Statement Grammar”</a>) of + class + <span class="command"><strong>CHAOS</strong></span> which is separate from the + default view of class <span class="command"><strong>IN</strong></span>. Most global + configuration options (<span class="command"><strong>allow-query</strong></span>, + etc) will apply to this view, but some are locally + overridden: <span class="command"><strong>notify</strong></span>, + <span class="command"><strong>recursion</strong></span> and + <span class="command"><strong>allow-new-zones</strong></span> are + always set to <strong class="userinput"><code>no</code></strong>, and + <span class="command"><strong>rate-limit</strong></span> is set to allow + three responses per second. + </p> + <p> + If you need to disable these zones, use the options + below, or hide the built-in <span class="command"><strong>CHAOS</strong></span> + view by + defining an explicit view of class <span class="command"><strong>CHAOS</strong></span> + that matches all clients. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>version</strong></span></span></dt> +<dd> + <p> + The version the server should report + via a query of the name <code class="literal">version.bind</code> + with type <span class="command"><strong>TXT</strong></span>, class <span class="command"><strong>CHAOS</strong></span>. + The default is the real version number of this server. + Specifying <span class="command"><strong>version none</strong></span> + disables processing of the queries. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>hostname</strong></span></span></dt> +<dd> + <p> + The hostname the server should report via a query of + the name <code class="filename">hostname.bind</code> + with type <span class="command"><strong>TXT</strong></span>, class <span class="command"><strong>CHAOS</strong></span>. + This defaults to the hostname of the machine hosting the + name server as + found by the gethostname() function. The primary purpose of such queries + is to + identify which of a group of anycast servers is actually + answering your queries. Specifying <span class="command"><strong>hostname none;</strong></span> + disables processing of the queries. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>server-id</strong></span></span></dt> +<dd> + <p> + The ID the server should report when receiving a Name + Server Identifier (NSID) query, or a query of the name + <code class="filename">ID.SERVER</code> with type + <span class="command"><strong>TXT</strong></span>, class <span class="command"><strong>CHAOS</strong></span>. + The primary purpose of such queries is to + identify which of a group of anycast servers is actually + answering your queries. Specifying <span class="command"><strong>server-id none;</strong></span> + disables processing of the queries. + Specifying <span class="command"><strong>server-id hostname;</strong></span> will cause <span class="command"><strong>named</strong></span> to + use the hostname as found by the gethostname() function. + The default <span class="command"><strong>server-id</strong></span> is <span class="command"><strong>none</strong></span>. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="empty"></a>Built-in Empty Zones</h4></div></div></div> + + <p> + The <span class="command"><strong>named</strong></span> server has some built-in + empty zones (SOA and NS records only). + These are for zones that should normally be answered locally + and which queries should not be sent to the Internet's root + servers. The official servers which cover these namespaces + return NXDOMAIN responses to these queries. In particular, + these cover the reverse namespaces for addresses from + RFC 1918, RFC 4193, RFC 5737 and RFC 6598. They also include the + reverse namespace for IPv6 local address (locally assigned), + IPv6 link local addresses, the IPv6 loopback address and the + IPv6 unknown address. + </p> + <p> + The server will attempt to determine if a built-in zone + already exists or is active (covered by a forward-only + forwarding declaration) and will not create an empty + zone in that case. + </p> + <p> + The current list of empty zones is: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem">10.IN-ADDR.ARPA</li> +<li class="listitem">16.172.IN-ADDR.ARPA</li> +<li class="listitem">17.172.IN-ADDR.ARPA</li> +<li class="listitem">18.172.IN-ADDR.ARPA</li> +<li class="listitem">19.172.IN-ADDR.ARPA</li> +<li class="listitem">20.172.IN-ADDR.ARPA</li> +<li class="listitem">21.172.IN-ADDR.ARPA</li> +<li class="listitem">22.172.IN-ADDR.ARPA</li> +<li class="listitem">23.172.IN-ADDR.ARPA</li> +<li class="listitem">24.172.IN-ADDR.ARPA</li> +<li class="listitem">25.172.IN-ADDR.ARPA</li> +<li class="listitem">26.172.IN-ADDR.ARPA</li> +<li class="listitem">27.172.IN-ADDR.ARPA</li> +<li class="listitem">28.172.IN-ADDR.ARPA</li> +<li class="listitem">29.172.IN-ADDR.ARPA</li> +<li class="listitem">30.172.IN-ADDR.ARPA</li> +<li class="listitem">31.172.IN-ADDR.ARPA</li> +<li class="listitem">168.192.IN-ADDR.ARPA</li> +<li class="listitem">64.100.IN-ADDR.ARPA</li> +<li class="listitem">65.100.IN-ADDR.ARPA</li> +<li class="listitem">66.100.IN-ADDR.ARPA</li> +<li class="listitem">67.100.IN-ADDR.ARPA</li> +<li class="listitem">68.100.IN-ADDR.ARPA</li> +<li class="listitem">69.100.IN-ADDR.ARPA</li> +<li class="listitem">70.100.IN-ADDR.ARPA</li> +<li class="listitem">71.100.IN-ADDR.ARPA</li> +<li class="listitem">72.100.IN-ADDR.ARPA</li> +<li class="listitem">73.100.IN-ADDR.ARPA</li> +<li class="listitem">74.100.IN-ADDR.ARPA</li> +<li class="listitem">75.100.IN-ADDR.ARPA</li> +<li class="listitem">76.100.IN-ADDR.ARPA</li> +<li class="listitem">77.100.IN-ADDR.ARPA</li> +<li class="listitem">78.100.IN-ADDR.ARPA</li> +<li class="listitem">79.100.IN-ADDR.ARPA</li> +<li class="listitem">80.100.IN-ADDR.ARPA</li> +<li class="listitem">81.100.IN-ADDR.ARPA</li> +<li class="listitem">82.100.IN-ADDR.ARPA</li> +<li class="listitem">83.100.IN-ADDR.ARPA</li> +<li class="listitem">84.100.IN-ADDR.ARPA</li> +<li class="listitem">85.100.IN-ADDR.ARPA</li> +<li class="listitem">86.100.IN-ADDR.ARPA</li> +<li class="listitem">87.100.IN-ADDR.ARPA</li> +<li class="listitem">88.100.IN-ADDR.ARPA</li> +<li class="listitem">89.100.IN-ADDR.ARPA</li> +<li class="listitem">90.100.IN-ADDR.ARPA</li> +<li class="listitem">91.100.IN-ADDR.ARPA</li> +<li class="listitem">92.100.IN-ADDR.ARPA</li> +<li class="listitem">93.100.IN-ADDR.ARPA</li> +<li class="listitem">94.100.IN-ADDR.ARPA</li> +<li class="listitem">95.100.IN-ADDR.ARPA</li> +<li class="listitem">96.100.IN-ADDR.ARPA</li> +<li class="listitem">97.100.IN-ADDR.ARPA</li> +<li class="listitem">98.100.IN-ADDR.ARPA</li> +<li class="listitem">99.100.IN-ADDR.ARPA</li> +<li class="listitem">100.100.IN-ADDR.ARPA</li> +<li class="listitem">101.100.IN-ADDR.ARPA</li> +<li class="listitem">102.100.IN-ADDR.ARPA</li> +<li class="listitem">103.100.IN-ADDR.ARPA</li> +<li class="listitem">104.100.IN-ADDR.ARPA</li> +<li class="listitem">105.100.IN-ADDR.ARPA</li> +<li class="listitem">106.100.IN-ADDR.ARPA</li> +<li class="listitem">107.100.IN-ADDR.ARPA</li> +<li class="listitem">108.100.IN-ADDR.ARPA</li> +<li class="listitem">109.100.IN-ADDR.ARPA</li> +<li class="listitem">110.100.IN-ADDR.ARPA</li> +<li class="listitem">111.100.IN-ADDR.ARPA</li> +<li class="listitem">112.100.IN-ADDR.ARPA</li> +<li class="listitem">113.100.IN-ADDR.ARPA</li> +<li class="listitem">114.100.IN-ADDR.ARPA</li> +<li class="listitem">115.100.IN-ADDR.ARPA</li> +<li class="listitem">116.100.IN-ADDR.ARPA</li> +<li class="listitem">117.100.IN-ADDR.ARPA</li> +<li class="listitem">118.100.IN-ADDR.ARPA</li> +<li class="listitem">119.100.IN-ADDR.ARPA</li> +<li class="listitem">120.100.IN-ADDR.ARPA</li> +<li class="listitem">121.100.IN-ADDR.ARPA</li> +<li class="listitem">122.100.IN-ADDR.ARPA</li> +<li class="listitem">123.100.IN-ADDR.ARPA</li> +<li class="listitem">124.100.IN-ADDR.ARPA</li> +<li class="listitem">125.100.IN-ADDR.ARPA</li> +<li class="listitem">126.100.IN-ADDR.ARPA</li> +<li class="listitem">127.100.IN-ADDR.ARPA</li> +<li class="listitem">0.IN-ADDR.ARPA</li> +<li class="listitem">127.IN-ADDR.ARPA</li> +<li class="listitem">254.169.IN-ADDR.ARPA</li> +<li class="listitem">2.0.192.IN-ADDR.ARPA</li> +<li class="listitem">100.51.198.IN-ADDR.ARPA</li> +<li class="listitem">113.0.203.IN-ADDR.ARPA</li> +<li class="listitem">255.255.255.255.IN-ADDR.ARPA</li> +<li class="listitem">0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA</li> +<li class="listitem">1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA</li> +<li class="listitem">8.B.D.0.1.0.0.2.IP6.ARPA</li> +<li class="listitem">D.F.IP6.ARPA</li> +<li class="listitem">8.E.F.IP6.ARPA</li> +<li class="listitem">9.E.F.IP6.ARPA</li> +<li class="listitem">A.E.F.IP6.ARPA</li> +<li class="listitem">B.E.F.IP6.ARPA</li> +<li class="listitem">EMPTY.AS112.ARPA</li> +<li class="listitem">HOME.ARPA</li> +</ul></div> +<p> + </p> + <p> + Empty zones are settable at the view level and only apply to + views of class IN. Disabled empty zones are only inherited + from options if there are no disabled empty zones specified + at the view level. To override the options list of disabled + zones, you can disable the root zone at the view level, for example: +</p> +<pre class="programlisting"> + disable-empty-zone "."; +</pre> +<p> + </p> + <p> + If you are using the address ranges covered here, you should + already have reverse zones covering the addresses you use. + In practice this appears to not be the case with many queries + being made to the infrastructure servers for names in these + spaces. So many in fact that sacrificial servers were needed + to be deployed to channel the query load away from the + infrastructure servers. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p> + The real parent servers for these zones should disable all + empty zone under the parent zone they serve. For the real + root servers, this is all built-in empty zones. This will + enable them to return referrals to deeper in the tree. + </p> +</div> + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>empty-server</strong></span></span></dt> +<dd> + <p> + Specify what server name will appear in the returned + SOA record for empty zones. If none is specified, then + the zone's name will be used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>empty-contact</strong></span></span></dt> +<dd> + <p> + Specify what contact name will appear in the returned + SOA record for empty zones. If none is specified, then + "." will be used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>empty-zones-enable</strong></span></span></dt> +<dd> + <p> + Enable or disable all empty zones. By default, they + are enabled. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>disable-empty-zone</strong></span></span></dt> +<dd> + <p> + Disable individual empty zones. By default, none are + disabled. This option can be specified multiple times. + </p> + </dd> +</dl></div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="acache"></a>Additional Section Caching</h4></div></div></div> + + + <p> + The additional section cache, also called <span class="command"><strong>acache</strong></span>, + is an internal cache to improve the response performance of BIND 9. + When additional section caching is enabled, BIND 9 will + cache an internal short-cut to the additional section content for + each answer RR. + Note that <span class="command"><strong>acache</strong></span> is an internal caching + mechanism of BIND 9, and is not related to the DNS caching + server function. + </p> + + <p> + Additional section caching does not change the + response content (except the RRsets ordering of the additional + section, see below), but can improve the response performance + significantly. + It is particularly effective when BIND 9 acts as an authoritative + server for a zone that has many delegations with many glue RRs. + </p> + + <p> + In order to obtain the maximum performance improvement + from additional section caching, setting + <span class="command"><strong>additional-from-cache</strong></span> + to <span class="command"><strong>no</strong></span> is recommended, since the current + implementation of <span class="command"><strong>acache</strong></span> + does not short-cut of additional section information from the + DNS cache data. + </p> + + <p> + One obvious disadvantage of <span class="command"><strong>acache</strong></span> is + that it requires much more + memory for the internal cached data. + Thus, if the response performance does not matter and memory + consumption is much more critical, the + <span class="command"><strong>acache</strong></span> mechanism can be + disabled by setting <span class="command"><strong>acache-enable</strong></span> to + <span class="command"><strong>no</strong></span>. + It is also possible to specify the upper limit of memory + consumption + for acache by using <span class="command"><strong>max-acache-size</strong></span>. + </p> + + <p> + Additional section caching also has a minor effect on the + RRset ordering in the additional section. + Without <span class="command"><strong>acache</strong></span>, + <span class="command"><strong>cyclic</strong></span> order is effective for the additional + section as well as the answer and authority sections. + However, additional section caching fixes the ordering when it + first caches an RRset for the additional section, and the same + ordering will be kept in succeeding responses, regardless of the + setting of <span class="command"><strong>rrset-order</strong></span>. + The effect of this should be minor, however, since an + RRset in the additional section + typically only contains a small number of RRs (and in many cases + it only contains a single RR), in which case the + ordering does not matter much. + </p> + + <p> + The following is a summary of options related to + <span class="command"><strong>acache</strong></span>. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>acache-enable</strong></span></span></dt> +<dd> + <p> + If <span class="command"><strong>yes</strong></span>, additional section caching is + enabled. The default value is <span class="command"><strong>no</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>acache-cleaning-interval</strong></span></span></dt> +<dd> + <p> + The server will remove stale cache entries, based on an LRU + based + algorithm, every <span class="command"><strong>acache-cleaning-interval</strong></span> minutes. + The default is 60 minutes. + If set to 0, no periodic cleaning will occur. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-acache-size</strong></span></span></dt> +<dd> + <p> + The maximum amount of memory in bytes to use for the server's acache. + When the amount of data in the acache reaches this limit, + the server + will clean more aggressively so that the limit is not + exceeded. + In a server with multiple views, the limit applies + separately to the + acache of each view. + The default is <code class="literal">16M</code>. + </p> + </dd> +</dl></div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="content_filtering"></a>Content Filtering</h4></div></div></div> + + <p> + <acronym class="acronym">BIND</acronym> 9 provides the ability to filter + out DNS responses from external DNS servers containing + certain types of data in the answer section. + Specifically, it can reject address (A or AAAA) records if + the corresponding IPv4 or IPv6 addresses match the given + <code class="varname">address_match_list</code> of the + <span class="command"><strong>deny-answer-addresses</strong></span> option. + It can also reject CNAME or DNAME records if the "alias" + name (i.e., the CNAME alias or the substituted query name + due to DNAME) matches the + given <code class="varname">namelist</code> of the + <span class="command"><strong>deny-answer-aliases</strong></span> option, where + "match" means the alias name is a subdomain of one of + the <code class="varname">name_list</code> elements. + If the optional <code class="varname">namelist</code> is specified + with <span class="command"><strong>except-from</strong></span>, records whose query name + matches the list will be accepted regardless of the filter + setting. + Likewise, if the alias name is a subdomain of the + corresponding zone, the <span class="command"><strong>deny-answer-aliases</strong></span> + filter will not apply; + for example, even if "example.com" is specified for + <span class="command"><strong>deny-answer-aliases</strong></span>, + </p> +<pre class="programlisting">www.example.com. CNAME xxx.example.com.</pre> + + <p> + returned by an "example.com" server will be accepted. + </p> + + <p> + In the <code class="varname">address_match_list</code> of the + <span class="command"><strong>deny-answer-addresses</strong></span> option, only + <code class="varname">ip_addr</code> + and <code class="varname">ip_prefix</code> + are meaningful; + any <code class="varname">key_id</code> will be silently ignored. + </p> + + <p> + If a response message is rejected due to the filtering, + the entire message is discarded without being cached, and + a SERVFAIL error will be returned to the client. + </p> + + <p> + This filtering is intended to prevent "DNS rebinding attacks," in + which an attacker, in response to a query for a domain name the + attacker controls, returns an IP address within your own network or + an alias name within your own domain. + A naive web browser or script could then serve as an + unintended proxy, allowing the attacker + to get access to an internal node of your local network + that couldn't be externally accessed otherwise. + See the paper available at + <a class="link" href="http://portal.acm.org/citation.cfm?id=1315245.1315298" target="_top"> + http://portal.acm.org/citation.cfm?id=1315245.1315298 + </a> + for more details about the attacks. + </p> + + <p> + For example, if you own a domain named "example.net" and + your internal network uses an IPv4 prefix 192.0.2.0/24, + you might specify the following rules: + </p> + +<pre class="programlisting">deny-answer-addresses { 192.0.2.0/24; } except-from { "example.net"; }; +deny-answer-aliases { "example.net"; }; +</pre> + + <p> + If an external attacker lets a web browser in your local + network look up an IPv4 address of "attacker.example.com", + the attacker's DNS server would return a response like this: + </p> + +<pre class="programlisting">attacker.example.com. A 192.0.2.1</pre> + + <p> + in the answer section. + Since the rdata of this record (the IPv4 address) matches + the specified prefix 192.0.2.0/24, this response will be + ignored. + </p> + + <p> + On the other hand, if the browser looks up a legitimate + internal web server "www.example.net" and the + following response is returned to + the <acronym class="acronym">BIND</acronym> 9 server + </p> + +<pre class="programlisting">www.example.net. A 192.0.2.2</pre> + + <p> + it will be accepted since the owner name "www.example.net" + matches the <span class="command"><strong>except-from</strong></span> element, + "example.net". + </p> + + <p> + Note that this is not really an attack on the DNS per se. + In fact, there is nothing wrong for an "external" name to + be mapped to your "internal" IP address or domain name + from the DNS point of view. + It might actually be provided for a legitimate purpose, + such as for debugging. + As long as the mapping is provided by the correct owner, + it is not possible or does not make sense to detect + whether the intent of the mapping is legitimate or not + within the DNS. + The "rebinding" attack must primarily be protected at the + application that uses the DNS. + For a large site, however, it may be difficult to protect + all possible applications at once. + This filtering feature is provided only to help such an + operational environment; + it is generally discouraged to turn it on unless you are + very sure you have no other choice and the attack is a + real threat for your applications. + </p> + + <p> + Care should be particularly taken if you want to use this + option for addresses within 127.0.0.0/8. + These addresses are obviously "internal", but many + applications conventionally rely on a DNS mapping from + some name to such an address. + Filtering out DNS records containing this address + spuriously can break such applications. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="rpz"></a>Response Policy Zone (RPZ) Rewriting</h4></div></div></div> + + <p> + <acronym class="acronym">BIND</acronym> 9 includes a limited + mechanism to modify DNS responses for requests + analogous to email anti-spam DNS blacklists. + Responses can be changed to deny the existence of domains (NXDOMAIN), + deny the existence of IP addresses for domains (NODATA), + or contain other IP addresses or data. + </p> + + <p> + Response policy zones are named in the + <span class="command"><strong>response-policy</strong></span> option for the view or among the + global options if there is no response-policy option for the view. + Response policy zones are ordinary DNS zones containing RRsets + that can be queried normally if allowed. + It is usually best to restrict those queries with something like + <span class="command"><strong>allow-query { localhost; };</strong></span>. + Note that zones using <span class="command"><strong>masterfile-format map</strong></span> + cannot be used as policy zones. + </p> + + <p> + A <span class="command"><strong>response-policy</strong></span> option can support + multiple policy zones. To maximize performance, a radix + tree is used to quickly identify response policy zones + containing triggers that match the current query. This + imposes an upper limit of 32 on the number of policy zones + in a single <span class="command"><strong>response-policy</strong></span> option; more + than that is a configuration error. + </p> + + <p> + Five policy triggers can be encoded in RPZ records. + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>RPZ-CLIENT-IP</strong></span></span></dt> +<dd> + <p> + IP records are triggered by the IP address of the + DNS client. + Client IP address triggers are encoded in records that have + owner names that are subdomains of + <span class="command"><strong>rpz-client-ip</strong></span> relativized to the + policy zone origin name + and encode an address or address block. + IPv4 addresses are represented as + <strong class="userinput"><code>prefixlength.B4.B3.B2.B1.rpz-client-ip</code></strong>. + The IPv4 prefix length must be between 1 and 32. + All four bytes, B4, B3, B2, and B1, must be present. + B4 is the decimal value of the least significant byte of the + IPv4 address as in IN-ADDR.ARPA. + </p> + + <p> + IPv6 addresses are encoded in a format similar + to the standard IPv6 text representation, + <strong class="userinput"><code>prefixlength.W8.W7.W6.W5.W4.W3.W2.W1.rpz-client-ip</code></strong>. + Each of W8,...,W1 is a one to four digit hexadecimal number + representing 16 bits of the IPv6 address as in the standard + text representation of IPv6 addresses, but reversed as in + IP6.ARPA. (Note that this representation of IPv6 + address is different from IP6.ARPA where each hex + digit occupies a label.) + All 8 words must be present except when one set of consecutive + zero words is replaced with <strong class="userinput"><code>.zz.</code></strong> + analogous to double colons (::) in standard IPv6 text + encodings. + The IPv6 prefix length must be between 1 and 128. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>QNAME</strong></span></span></dt> +<dd> + <p> + QNAME policy records are triggered by query names of + requests and targets of CNAME records resolved to generate + the response. + The owner name of a QNAME policy record is + the query name relativized to the policy zone. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RPZ-IP</strong></span></span></dt> +<dd> + <p> + IP triggers are IP addresses in an + A or AAAA record in the ANSWER section of a response. + They are encoded like client-IP triggers except as + subdomains of <span class="command"><strong>rpz-ip</strong></span>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RPZ-NSDNAME</strong></span></span></dt> +<dd> + <p> + NSDNAME triggers match names of authoritative servers + for the query name, a parent of the query name, a CNAME for + query name, or a parent of a CNAME. + They are encoded as subdomains of + <span class="command"><strong>rpz-nsdname</strong></span> relativized + to the RPZ origin name. + NSIP triggers match IP addresses in A and + AAAA RRsets for domains that can be checked against NSDNAME + policy records. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RPZ-NSIP</strong></span></span></dt> +<dd> + <p> + NSIP triggers match the IP addresses of authoritative + servers. They are enncoded like IP triggers, except as + subdomains of <span class="command"><strong>rpz-nsip</strong></span>. + NSDNAME and NSIP triggers are checked only for names with at + least <span class="command"><strong>min-ns-dots</strong></span> dots. + The default value of <span class="command"><strong>min-ns-dots</strong></span> is + 1, to exclude top level domains. + </p> + <p> + If a name server's IP address is not yet known, + <span class="command"><strong>named</strong></span> will recursively look up + the IP address before applying an RPZ-NSIP rule. + This can cause a processing delay. To speed up + processing at the cost of precision, the + <span class="command"><strong>nsip-wait-recurse</strong></span> option + can be used: when set to <strong class="userinput"><code>no</code></strong>, + RPZ-NSIP rules will only be applied when a name + servers's IP address has already been looked up and + cached. If a server's IP address is not in the + cache, then the RPZ-NSIP rule will be ignored, + but the address will be looked up in the + background, and the rule will be applied + to subsequent queries. The default is + <strong class="userinput"><code>yes</code></strong>, meaning RPZ-NSIP + rules should always be applied even if an + address needs to be looked up first. + </p> + </dd> +</dl></div> +<p> + </p> + + <p> + The query response is checked against all response policy zones, + so two or more policy records can be triggered by a response. + Because DNS responses are rewritten according to at most one + policy record, a single record encoding an action (other than + <span class="command"><strong>DISABLED</strong></span> actions) must be chosen. + Triggers or the records that encode them are chosen for the + rewriting in the following order: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem">Choose the triggered record in the zone that appears + first in the <span class="command"><strong>response-policy</strong></span> option. + </li> +<li class="listitem">Prefer CLIENT-IP to QNAME to IP to NSDNAME to NSIP + triggers in a single zone. + </li> +<li class="listitem">Among NSDNAME triggers, prefer the + trigger that matches the smallest name under the DNSSEC ordering. + </li> +<li class="listitem">Among IP or NSIP triggers, prefer the trigger + with the longest prefix. + </li> +<li class="listitem">Among triggers with the same prefix length, + prefer the IP or NSIP trigger that matches + the smallest IP address. + </li> +</ol></div> +<p> + </p> + + <p> + When the processing of a response is restarted to resolve + DNAME or CNAME records and a policy record set has + not been triggered, + all response policy zones are again consulted for the + DNAME or CNAME names and addresses. + </p> + + <p> + RPZ record sets are any types of DNS record except + DNAME or DNSSEC that encode actions or responses to + individual queries. + Any of the policies can be used with any of the triggers. + For example, while the <span class="command"><strong>TCP-only</strong></span> policy is + commonly used with <span class="command"><strong>client-IP</strong></span> triggers, + it can be used with any type of trigger to force the use of + TCP for responses with owner names in a zone. + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>PASSTHRU</strong></span></span></dt> +<dd> + <p> + The whitelist policy is specified + by a CNAME whose target is <span class="command"><strong>rpz-passthru</strong></span>. + It causes the response to not be rewritten + and is most often used to "poke holes" in policies for + CIDR blocks. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>DROP</strong></span></span></dt> +<dd> + <p> + The blacklist policy is specified + by a CNAME whose target is <span class="command"><strong>rpz-drop</strong></span>. + It causes the response to be discarded. + Nothing is sent to the DNS client. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>TCP-Only</strong></span></span></dt> +<dd> + <p> + The "slip" policy is specified + by a CNAME whose target is <span class="command"><strong>rpz-tcp-only</strong></span>. + It changes UDP responses to short, truncated DNS responses + that require the DNS client to try again with TCP. + It is used to mitigate distributed DNS reflection attacks. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>NXDOMAIN</strong></span></span></dt> +<dd> + <p> + The domain undefined response is encoded + by a CNAME whose target is the root domain (.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>NODATA</strong></span></span></dt> +<dd> + <p> + The empty set of resource records is specified by + CNAME whose target is the wildcard top-level + domain (*.). + It rewrites the response to NODATA or ANCOUNT=1. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>Local Data</strong></span></span></dt> +<dd> + <p> + A set of ordinary DNS records can be used to answer queries. + Queries for record types not the set are answered with + NODATA. + </p> + + <p> + A special form of local data is a CNAME whose target is a + wildcard such as *.example.com. + It is used as if were an ordinary CNAME after the asterisk (*) + has been replaced with the query name. + The purpose for this special form is query logging in the + walled garden's authority DNS server. + </p> + </dd> +</dl></div> +<p> + </p> + + <p> + All of the actions specified in all of the individual records + in a policy zone + can be overridden with a <span class="command"><strong>policy</strong></span> clause in the + <span class="command"><strong>response-policy</strong></span> option. + An organization using a policy zone provided by another + organization might use this mechanism to redirect domains + to its own walled garden. + </p> +<div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>GIVEN</strong></span></span></dt> +<dd> + <p>The placeholder policy says "do not override but + perform the action specified in the zone." + </p> + </dd> +<dt><span class="term"><span class="command"><strong>DISABLED</strong></span></span></dt> +<dd> + <p> + The testing override policy causes policy zone records to do + nothing but log what they would have done if the + policy zone were not disabled. + The response to the DNS query will be written (or not) + according to any triggered policy records that are not + disabled. + Disabled policy zones should appear first, + because they will often not be logged + if a higher precedence trigger is found first. + </p> + </dd> +<dt> +<span class="term"><span class="command"><strong>PASSTHRU</strong></span>, </span><span class="term"><span class="command"><strong>DROP</strong></span>, </span><span class="term"><span class="command"><strong>TCP-Only</strong></span>, </span><span class="term"><span class="command"><strong>NXDOMAIN</strong></span>, </span><span class="term"><span class="command"><strong>NODATA</strong></span></span> +</dt> +<dd> + <p> + override with the corresponding per-record policy. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>CNAME domain</strong></span></span></dt> +<dd> + <p> + causes all RPZ policy records to act as if they were + "cname domain" records. + </p> + </dd> +</dl></div> +<p> + </p> + + <p> + By default, the actions encoded in a response policy zone + are applied only to queries that ask for recursion (RD=1). + That default can be changed for a single policy zone or + all response policy zones in a view + with a <span class="command"><strong>recursive-only no</strong></span> clause. + This feature is useful for serving the same zone files + both inside and outside an RFC 1918 cloud and using RPZ to + delete answers that would otherwise contain RFC 1918 values + on the externally visible name server or view. + </p> + + <p> + Also by default, RPZ actions are applied only to DNS requests + that either do not request DNSSEC metadata (DO=0) or when no + DNSSEC records are available for request name in the original + zone (not the response policy zone). This default can be + changed for all response policy zones in a view with a + <span class="command"><strong>break-dnssec yes</strong></span> clause. In that case, RPZ + actions are applied regardless of DNSSEC. The name of the + clause option reflects the fact that results rewritten by RPZ + actions cannot verify. + </p> + + <p> + No DNS records are needed for a QNAME or Client-IP trigger. + The name or IP address itself is sufficient, + so in principle the query name need not be recursively resolved. + However, not resolving the requested + name can leak the fact that response policy rewriting is in use + and that the name is listed in a policy zone to operators of + servers for listed names. To prevent that information leak, by + default any recursion needed for a request is done before any + policy triggers are considered. Because listed domains often + have slow authoritative servers, this default behavior can cost + significant time. + The <span class="command"><strong>qname-wait-recurse no</strong></span> option + overrides that default behavior when recursion cannot + change a non-error response. + The option does not affect QNAME or client-IP triggers + in policy zones listed + after other zones containing IP, NSIP and NSDNAME triggers, because + those may depend on the A, AAAA, and NS records that would be + found during recursive resolution. It also does not affect + DNSSEC requests (DO=1) unless <span class="command"><strong>break-dnssec yes</strong></span> + is in use, because the response would depend on whether or not + RRSIG records were found during resolution. + Using this option can cause error responses such as SERVFAIL to + appear to be rewritten, since no recursion is being done to + discover problems at the authoritative server. + </p> + + <p> + The TTL of a record modified by RPZ policies is set from the + TTL of the relevant record in policy zone. It is then limited + to a maximum value. + The <span class="command"><strong>max-policy-ttl</strong></span> clause changes the + maximum seconds from its default of 5. + </p> + + <p> + For example, you might use this option statement + </p> +<pre class="programlisting"> response-policy { zone "badlist"; };</pre> + <p> + and this zone statement + </p> +<pre class="programlisting"> zone "badlist" {type master; file "master/badlist"; allow-query {none;}; };</pre> + <p> + with this zone file + </p> +<pre class="programlisting">$TTL 1H +@ SOA LOCALHOST. named-mgr.example.com (1 1h 15m 30d 2h) + NS LOCALHOST. + +; QNAME policy records. There are no periods (.) after the owner names. +nxdomain.domain.com CNAME . ; NXDOMAIN policy +*.nxdomain.domain.com CNAME . ; NXDOMAIN policy +nodata.domain.com CNAME *. ; NODATA policy +*.nodata.domain.com CNAME *. ; NODATA policy +bad.domain.com A 10.0.0.1 ; redirect to a walled garden + AAAA 2001:2::1 +bzone.domain.com CNAME garden.example.com. + +; do not rewrite (PASSTHRU) OK.DOMAIN.COM +ok.domain.com CNAME rpz-passthru. + +; redirect x.bzone.domain.com to x.bzone.domain.com.garden.example.com +*.bzone.domain.com CNAME *.garden.example.com. + + +; IP policy records that rewrite all responses containing A records in 127/8 +; except 127.0.0.1 +8.0.0.0.127.rpz-ip CNAME . +32.1.0.0.127.rpz-ip CNAME rpz-passthru. + +; NSDNAME and NSIP policy records +ns.domain.com.rpz-nsdname CNAME . +48.zz.2.2001.rpz-nsip CNAME . + +; blacklist and whitelist some DNS clients +112.zz.2001.rpz-client-ip CNAME rpz-drop. +8.0.0.0.127.rpz-client-ip CNAME rpz-drop. + +; force some DNS clients and responses in the example.com zone to TCP +16.0.0.1.10.rpz-client-ip CNAME rpz-tcp-only. +example.com CNAME rpz-tcp-only. +*.example.com CNAME rpz-tcp-only. + +</pre> + <p> + RPZ can affect server performance. + Each configured response policy zone requires the server to + perform one to four additional database lookups before a + query can be answered. + For example, a DNS server with four policy zones, each with all + four kinds of response triggers, QNAME, IP, NSIP, and + NSDNAME, requires a total of 17 times as many database + lookups as a similar DNS server with no response policy zones. + A <acronym class="acronym">BIND9</acronym> server with adequate memory and one + response policy zone with QNAME and IP triggers might achieve a + maximum queries-per-second rate about 20% lower. + A server with four response policy zones with QNAME and IP + triggers might have a maximum QPS rate about 50% lower. + </p> + + <p> + Responses rewritten by RPZ are counted in the + <span class="command"><strong>RPZRewrites</strong></span> statistics. + </p> + + <p> + The <span class="command"><strong>log</strong></span> clause can be used to optionally + turn off rewrite logging for a particular response policy + zone. By default, all rewrites are logged. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="rrl"></a>Response Rate Limiting</h4></div></div></div> + + <p> + Excessive almost identical UDP <span class="emphasis"><em>responses</em></span> + can be controlled by configuring a + <span class="command"><strong>rate-limit</strong></span> clause in an + <span class="command"><strong>options</strong></span> or <span class="command"><strong>view</strong></span> statement. + This mechanism keeps authoritative BIND 9 from being used + in amplifying reflection denial of service (DoS) attacks. + Short truncated (TC=1) responses can be sent to provide + rate-limited responses to legitimate clients within + a range of forged, attacked IP addresses. + Legitimate clients react to dropped or truncated response + by retrying with UDP or with TCP respectively. + </p> + + <p> + This mechanism is intended for authoritative DNS servers. + It can be used on recursive servers but can slow + applications such as SMTP servers (mail receivers) and + HTTP clients (web browsers) that repeatedly request the + same domains. + When possible, closing "open" recursive servers is better. + </p> + + <p> + Response rate limiting uses a "credit" or "token bucket" scheme. + Each combination of identical response and client + has a conceptual account that earns a specified number + of credits every second. + A prospective response debits its account by one. + Responses are dropped or truncated + while the account is negative. + Responses are tracked within a rolling window of time + which defaults to 15 seconds, but can be configured with + the <span class="command"><strong>window</strong></span> option to any value from + 1 to 3600 seconds (1 hour). + The account cannot become more positive than + the per-second limit + or more negative than <span class="command"><strong>window</strong></span> + times the per-second limit. + When the specified number of credits for a class of + responses is set to 0, those responses are not rate limited. + </p> + + <p> + The notions of "identical response" and "DNS client" + for rate limiting are not simplistic. + All responses to an address block are counted as if to a + single client. + The prefix lengths of addresses blocks are + specified with <span class="command"><strong>ipv4-prefix-length</strong></span> (default 24) + and <span class="command"><strong>ipv6-prefix-length</strong></span> (default 56). + </p> + + <p> + All non-empty responses for a valid domain name (qname) + and record type (qtype) are identical and have a limit specified + with <span class="command"><strong>responses-per-second</strong></span> + (default 0 or no limit). + All empty (NODATA) responses for a valid domain, + regardless of query type, are identical. + Responses in the NODATA class are limited by + <span class="command"><strong>nodata-per-second</strong></span> + (default <span class="command"><strong>responses-per-second</strong></span>). + Requests for any and all undefined subdomains of a given + valid domain result in NXDOMAIN errors, and are identical + regardless of query type. + They are limited by <span class="command"><strong>nxdomains-per-second</strong></span> + (default <span class="command"><strong>responses-per-second</strong></span>). + This controls some attacks using random names, but + can be relaxed or turned off (set to 0) + on servers that expect many legitimate + NXDOMAIN responses, such as from anti-spam blacklists. + Referrals or delegations to the server of a given + domain are identical and are limited by + <span class="command"><strong>referrals-per-second</strong></span> + (default <span class="command"><strong>responses-per-second</strong></span>). + </p> + + <p> + Responses generated from local wildcards are counted and limited + as if they were for the parent domain name. + This controls flooding using random.wild.example.com. + </p> + + <p> + All requests that result in DNS errors other + than NXDOMAIN, such as SERVFAIL and FORMERR, are identical + regardless of requested name (qname) or record type (qtype). + This controls attacks using invalid requests or distant, + broken authoritative servers. + By default the limit on errors is the same as the + <span class="command"><strong>responses-per-second</strong></span> value, + but it can be set separately with + <span class="command"><strong>errors-per-second</strong></span>. + </p> + + <p> + Many attacks using DNS involve UDP requests with forged source + addresses. + Rate limiting prevents the use of BIND 9 to flood a network + with responses to requests with forged source addresses, + but could let a third party block responses to legitimate requests. + There is a mechanism that can answer some legitimate + requests from a client whose address is being forged in a flood. + Setting <span class="command"><strong>slip</strong></span> to 2 (its default) causes every + other UDP request to be answered with a small truncated (TC=1) + response. + The small size and reduced frequency, and so lack of + amplification, of "slipped" responses make them unattractive + for reflection DoS attacks. + <span class="command"><strong>slip</strong></span> must be between 0 and 10. + A value of 0 does not "slip": + no truncated responses are sent due to rate limiting, + all responses are dropped. + A value of 1 causes every response to slip; + values between 2 and 10 cause every n'th response to slip. + Some error responses including REFUSED and SERVFAIL + cannot be replaced with truncated responses and are instead + leaked at the <span class="command"><strong>slip</strong></span> rate. + </p> + + <p> + (NOTE: Dropped responses from an authoritative server may + reduce the difficulty of a third party successfully forging + a response to a recursive resolver. The best security + against forged responses is for authoritative operators + to sign their zones using DNSSEC and for resolver operators + to validate the responses. When this is not an option, + operators who are more concerned with response integrity + than with flood mitigation may consider setting + <span class="command"><strong>slip</strong></span> to 1, causing all rate-limited + responses to be truncated rather than dropped. This reduces + the effectiveness of rate-limiting against reflection attacks.) + </p> + + <p> + When the approximate query per second rate exceeds + the <span class="command"><strong>qps-scale</strong></span> value, + then the <span class="command"><strong>responses-per-second</strong></span>, + <span class="command"><strong>errors-per-second</strong></span>, + <span class="command"><strong>nxdomains-per-second</strong></span> and + <span class="command"><strong>all-per-second</strong></span> values are reduced by the + ratio of the current rate to the <span class="command"><strong>qps-scale</strong></span> value. + This feature can tighten defenses during attacks. + For example, with + <span class="command"><strong>qps-scale 250; responses-per-second 20;</strong></span> and + a total query rate of 1000 queries/second for all queries from + all DNS clients including via TCP, + then the effective responses/second limit changes to + (250/1000)*20 or 5. + Responses sent via TCP are not limited + but are counted to compute the query per second rate. + </p> + + <p> + Rate limiters for different name spaces maintain + separate counters: If, for example, there is a + <span class="command"><strong>rate-limit</strong></span> statement for "com" and + another for "example.com", queries matching "example.com" + will not be debited against the rate limiter for "com". + </p> + + <p> + If a <span class="command"><strong>rate-limit</strong></span> statement does not specify a + <span class="command"><strong>domain</strong></span>, then it applies to the root domain + (".") and thus affects the entire DNS namespace, except those + portions covered by other <span class="command"><strong>rate-limit</strong></span> + statements. + </p> + + <p> + Communities of DNS clients can be given their own parameters or no + rate limiting by putting + <span class="command"><strong>rate-limit</strong></span> statements in <span class="command"><strong>view</strong></span> + statements instead of the global <span class="command"><strong>option</strong></span> + statement. + A <span class="command"><strong>rate-limit</strong></span> statement in a view replaces, + rather than supplementing, a <span class="command"><strong>rate-limit</strong></span> + statement among the main options. + DNS clients within a view can be exempted from rate limits + with the <span class="command"><strong>exempt-clients</strong></span> clause. + </p> + + <p> + UDP responses of all kinds can be limited with the + <span class="command"><strong>all-per-second</strong></span> phrase. This rate + limiting is unlike the rate limiting provided by + <span class="command"><strong>responses-per-second</strong></span>, + <span class="command"><strong>errors-per-second</strong></span>, and + <span class="command"><strong>nxdomains-per-second</strong></span> on a DNS server + which are often invisible to the victim of a DNS + reflection attack. Unless the forged requests of the + attack are the same as the legitimate requests of the + victim, the victim's requests are not affected. Responses + affected by an <span class="command"><strong>all-per-second</strong></span> limit + are always dropped; the <span class="command"><strong>slip</strong></span> value + has no effect. An <span class="command"><strong>all-per-second</strong></span> + limit should be at least 4 times as large as the other + limits, because single DNS clients often send bursts + of legitimate requests. For example, the receipt of a + single mail message can prompt requests from an SMTP + server for NS, PTR, A, and AAAA records as the incoming + SMTP/TCP/IP connection is considered. The SMTP server + can need additional NS, A, AAAA, MX, TXT, and SPF records + as it considers the STMP <span class="command"><strong>Mail From</strong></span> + command. Web browsers often repeatedly resolve the + same names that are repeated in HTML <IMG> tags + in a page. <span class="command"><strong>all-per-second</strong></span> is similar + to the rate limiting offered by firewalls but often + inferior. Attacks that justify ignoring the contents + of DNS responses are likely to be attacks on the DNS + server itself. They usually should be discarded before + the DNS server spends resources make TCP connections + or parsing DNS requests, but that rate limiting must + be done before the DNS server sees the requests. + </p> + + <p> + The maximum size of the table used to track requests and + rate limit responses is set with <span class="command"><strong>max-table-size</strong></span>. + Each entry in the table is between 40 and 80 bytes. + The table needs approximately as many entries as the number + of requests received per second. + The default is 20,000. + To reduce the cold start of growing the table, + <span class="command"><strong>min-table-size</strong></span> (default 500) + can set the minimum table size. + Enable <span class="command"><strong>rate-limit</strong></span> category logging to monitor + expansions of the table and inform + choices for the initial and maximum table size. + </p> + + <p> + Use <span class="command"><strong>log-only yes</strong></span> to test rate limiting parameters + without actually dropping any requests. + </p> + + <p> + Responses dropped by rate limits are included in the + <span class="command"><strong>RateDropped</strong></span> and <span class="command"><strong>QryDropped</strong></span> + statistics. + Responses that truncated by rate limits are included in + <span class="command"><strong>RateSlipped</strong></span> and <span class="command"><strong>RespTruncated</strong></span>. + </p> + </div> + + <div class="section"> +<div class="titlepage"></div> + <p> + Named supports NXDOMAIN redirection via two methods: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem">Redirect zone <a class="xref" href="Bv9ARM.ch06.html#zone_statement_grammar" title="zone Statement Grammar">the section called “<span class="command"><strong>zone</strong></span> + Statement Grammar”</a> +</li> +<li class="listitem">Redirect namespace</li> +</ul></div> +<p> + </p> + <p> + With both methods when named gets a NXDOMAIN response + it examines a separate namespace to see if the NXDOMAIN + response should be replaced with an alternative response. + </p> + <p> + With a redirect zone (<span class="command"><strong>zone "." { type redirect; };</strong></span>), the + data used to replace the NXDOMAIN is held in a single + zone which is not part of the normal namespace. All the + redirect information is contained in the zone; there are + no delegations. + </p> + <p> + With a redirect namespace (<span class="command"><strong>option { nxdomain-redirect + <suffix> };</strong></span>) the data used to replace the + NXDOMAIN is part of the normal namespace and is looked up by + appending the specified suffix to the original query name. + This roughly doubles the cache required to process NXDOMAIN + responses as you have the original NXDOMAIN response and + the replacement data or a NXDOMAIN indicating that there + is no replacement. + </p> + <p> + If both a redirect zone and a redirect namespace are configured, + the redirect zone is tried first. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="server_statement_grammar"></a><span class="command"><strong>server</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>server</strong></span> <em class="replaceable"><code>netprefix</code></em> { + <span class="command"><strong>bogus</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>edns</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>edns-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>edns-version</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>keys</strong></span> <em class="replaceable"><code>server_key</code></em>; + <span class="command"><strong>max-udp-size</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] + [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>provide-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>query-source</strong></span> ( ( [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv4_address</code></em> | * ) ] + <span class="command"><strong>port</strong></span> ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>query-source-v6</strong></span> ( ( [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( + <em class="replaceable"><code>integer</code></em> | * ) ] ) | ( [ [ address ] ( <em class="replaceable"><code>ipv6_address</code></em> | * ) ] + <span class="command"><strong>port</strong></span> ( <em class="replaceable"><code>integer</code></em> | * ) ) ) [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>request-expire</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-nsid</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>send-cookie</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>tcp-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>transfer-format</strong></span> ( many-answers | one-answer ); + <span class="command"><strong>transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>dscp</strong></span> <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) + ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfers</strong></span> <em class="replaceable"><code>integer</code></em>; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="server_statement_definition_and_usage"></a><span class="command"><strong>server</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>server</strong></span> statement defines + characteristics + to be associated with a remote name server. If a prefix length is + specified, then a range of servers is covered. Only the most + specific + server clause applies regardless of the order in + <code class="filename">named.conf</code>. + </p> + + <p> + The <span class="command"><strong>server</strong></span> statement can occur at + the top level of the + configuration file or inside a <span class="command"><strong>view</strong></span> + statement. + If a <span class="command"><strong>view</strong></span> statement contains + one or more <span class="command"><strong>server</strong></span> statements, only + those + apply to the view and any top-level ones are ignored. + If a view contains no <span class="command"><strong>server</strong></span> + statements, + any top-level <span class="command"><strong>server</strong></span> statements are + used as + defaults. + </p> + + <p> + If you discover that a remote server is giving out bad data, + marking it as bogus will prevent further queries to it. The + default + value of <span class="command"><strong>bogus</strong></span> is <span class="command"><strong>no</strong></span>. + </p> + <p> + The <span class="command"><strong>provide-ixfr</strong></span> clause determines + whether + the local server, acting as master, will respond with an + incremental + zone transfer when the given remote server, a slave, requests it. + If set to <span class="command"><strong>yes</strong></span>, incremental transfer + will be provided + whenever possible. If set to <span class="command"><strong>no</strong></span>, + all transfers + to the remote server will be non-incremental. If not set, the + value + of the <span class="command"><strong>provide-ixfr</strong></span> option in the + view or + global options block is used as a default. + </p> + + <p> + The <span class="command"><strong>request-ixfr</strong></span> clause determines + whether + the local server, acting as a slave, will request incremental zone + transfers from the given remote server, a master. If not set, the + value of the <span class="command"><strong>request-ixfr</strong></span> option in + the view or global options block is used as a default. It may + also be set in the zone block and, if set there, it will + override the global or view setting for that zone. + </p> + + <p> + IXFR requests to servers that do not support IXFR will + automatically + fall back to AXFR. Therefore, there is no need to manually list + which servers support IXFR and which ones do not; the global + default + of <span class="command"><strong>yes</strong></span> should always work. + The purpose of the <span class="command"><strong>provide-ixfr</strong></span> and + <span class="command"><strong>request-ixfr</strong></span> clauses is + to make it possible to disable the use of IXFR even when both + master + and slave claim to support it, for example if one of the servers + is buggy and crashes or corrupts data when IXFR is used. + </p> + + <p> + The <span class="command"><strong>request-expire</strong></span> clause determines + whether the local server, when acting as a slave, will + request the EDNS EXPIRE value. The EDNS EXPIRE value + indicates the remaining time before the zone data will + expire and need to be be refreshed. This is used + when a secondary server transfers a zone from another + secondary server; when transferring from the primary, the + expiration timer is set from the EXPIRE field of the SOA + record instead. + The default is <span class="command"><strong>yes</strong></span>. + </p> + + <p> + The <span class="command"><strong>edns</strong></span> clause determines whether + the local server will attempt to use EDNS when communicating + with the remote server. The default is <span class="command"><strong>yes</strong></span>. + </p> + + <p> + The <span class="command"><strong>edns-udp-size</strong></span> option sets the + EDNS UDP size that is advertised by <span class="command"><strong>named</strong></span> + when querying the remote server. Valid values are 512 + to 4096 bytes (values outside this range will be silently + adjusted to the nearest value within it). This option + is useful when you wish to advertise a different value + to this server than the value you advertise globally, + for example, when there is a firewall at the remote + site that is blocking large replies. (Note: Currently, + this sets a single UDP size for all packets sent to the + server; <span class="command"><strong>named</strong></span> will not deviate from + this value. This differs from the behavior of + <span class="command"><strong>edns-udp-size</strong></span> in <span class="command"><strong>options</strong></span> + or <span class="command"><strong>view</strong></span> statements, where it specifies + a maximum value. The <span class="command"><strong>server</strong></span> statement + behavior may be brought into conformance with the + <span class="command"><strong>options/view</strong></span> behavior in future releases.) + </p> + + <p> + The <span class="command"><strong>edns-version</strong></span> option sets the + maximum EDNS VERSION that will be sent to the server(s) + by the resolver. The actual EDNS version sent is still + subject to normal EDNS version negotiation rules (see + RFC 6891), the maximum EDNS version supported by the + server, and any other heuristics that indicate that a + lower version should be sent. This option is intended + to be used when a remote server reacts badly to a given + EDNS version or higher; it should be set to the highest + version the remote server is known to support. Valid + values are 0 to 255; higher values will be silently + adjusted. This option will not be needed until higher + EDNS versions than 0 are in use. + </p> + + <p> + The <span class="command"><strong>max-udp-size</strong></span> option sets the + maximum EDNS UDP message size <span class="command"><strong>named</strong></span> + will send. Valid values are 512 to 4096 bytes (values + outside this range will be silently adjusted). This + option is useful when you know that there is a firewall + that is blocking large replies from <span class="command"><strong>named</strong></span>. + </p> + + <p> + The <span class="command"><strong>tcp-only</strong></span> option sets the transport + protocol to TCP. The default is to use the UDP transport + and to fallback on TCP only when a truncated response + is received. + </p> + + <p> + The server supports two zone transfer methods. The first, <span class="command"><strong>one-answer</strong></span>, + uses one DNS message per resource record transferred. <span class="command"><strong>many-answers</strong></span> packs + as many resource records as possible into a message. <span class="command"><strong>many-answers</strong></span> is + more efficient, but is only known to be understood by <acronym class="acronym">BIND</acronym> 9, <acronym class="acronym">BIND</acronym> + 8.x, and patched versions of <acronym class="acronym">BIND</acronym> + 4.9.5. You can specify which method + to use for a server with the <span class="command"><strong>transfer-format</strong></span> option. + If <span class="command"><strong>transfer-format</strong></span> is not + specified, the <span class="command"><strong>transfer-format</strong></span> + specified + by the <span class="command"><strong>options</strong></span> statement will be + used. + </p> + + <p><span class="command"><strong>transfers</strong></span> + is used to limit the number of concurrent inbound zone + transfers from the specified server. If no + <span class="command"><strong>transfers</strong></span> clause is specified, the + limit is set according to the + <span class="command"><strong>transfers-per-ns</strong></span> option. + </p> + + <p> + The <span class="command"><strong>keys</strong></span> clause identifies a + <span class="command"><strong>key_id</strong></span> defined by the <span class="command"><strong>key</strong></span> statement, + to be used for transaction security (TSIG, <a class="xref" href="Bv9ARM.ch04.html#tsig" title="TSIG">the section called “TSIG”</a>) + when talking to the remote server. + When a request is sent to the remote server, a request signature + will be generated using the key specified here and appended to the + message. A request originating from the remote server is not + required + to be signed by this key. + </p> + + <p> + Only a single key per server is currently supported. + </p> + + <p> + The <span class="command"><strong>transfer-source</strong></span> and + <span class="command"><strong>transfer-source-v6</strong></span> clauses specify + the IPv4 and IPv6 source + address to be used for zone transfer with the remote server, + respectively. + For an IPv4 remote server, only <span class="command"><strong>transfer-source</strong></span> can + be specified. + Similarly, for an IPv6 remote server, only + <span class="command"><strong>transfer-source-v6</strong></span> can be + specified. + For more details, see the description of + <span class="command"><strong>transfer-source</strong></span> and + <span class="command"><strong>transfer-source-v6</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + + <p> + The <span class="command"><strong>notify-source</strong></span> and + <span class="command"><strong>notify-source-v6</strong></span> clauses specify the + IPv4 and IPv6 source address to be used for notify + messages sent to remote servers, respectively. For an + IPv4 remote server, only <span class="command"><strong>notify-source</strong></span> + can be specified. Similarly, for an IPv6 remote server, + only <span class="command"><strong>notify-source-v6</strong></span> can be specified. + </p> + + <p> + The <span class="command"><strong>query-source</strong></span> and + <span class="command"><strong>query-source-v6</strong></span> clauses specify the + IPv4 and IPv6 source address to be used for queries + sent to remote servers, respectively. For an IPv4 + remote server, only <span class="command"><strong>query-source</strong></span> can + be specified. Similarly, for an IPv6 remote server, + only <span class="command"><strong>query-source-v6</strong></span> can be specified. + </p> + + <p> + The <span class="command"><strong>request-nsid</strong></span> clause determines + whether the local server will add a NSID EDNS option + to requests sent to the server. This overrides + <span class="command"><strong>request-nsid</strong></span> set at the view or + option level. + </p> + + <p> + The <span class="command"><strong>send-cookie</strong></span> clause determines + whether the local server will add a COOKIE EDNS option + to requests sent to the server. This overrides + <span class="command"><strong>send-cookie</strong></span> set at the view or + option level. The <span class="command"><strong>named</strong></span> server may + determine that COOKIE is not supported by the remote server + and not add a COOKIE EDNS option to requests. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="statschannels"></a><span class="command"><strong>statistics-channels</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>statistics-channels</strong></span> { + <span class="command"><strong>inet</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> | + * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ + <span class="command"><strong>allow</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... + } ]; +}; +</pre> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="statistics_channels"></a><span class="command"><strong>statistics-channels</strong></span> Statement Definition and + Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>statistics-channels</strong></span> statement + declares communication channels to be used by system + administrators to get access to statistics information of + the name server. + </p> + + <p> + This statement intends to be flexible to support multiple + communication protocols in the future, but currently only + HTTP access is supported. + It requires that BIND 9 be compiled with libxml2 and/or + json-c (also known as libjson0); the + <span class="command"><strong>statistics-channels</strong></span> statement is + still accepted even if it is built without the library, + but any HTTP access will fail with an error. + </p> + + <p> + 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 + 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, + use an <span class="command"><strong>ip_addr</strong></span> of <code class="literal">::</code>. + </p> + + <p> + If no port is specified, port 80 is used for HTTP channels. + The asterisk "<code class="literal">*</code>" cannot be used for + <span class="command"><strong>ip_port</strong></span>. + </p> + + <p> + The attempt of opening a statistics channel is + restricted by the optional <span class="command"><strong>allow</strong></span> clause. + Connections to the statistics channel are permitted based on the + <span class="command"><strong>address_match_list</strong></span>. + If no <span class="command"><strong>allow</strong></span> clause is present, + <span class="command"><strong>named</strong></span> accepts connection + attempts from any address; since the statistics may + contain sensitive internal information, it is highly + recommended to restrict the source of connection requests + appropriately. + </p> + + <p> + If no <span class="command"><strong>statistics-channels</strong></span> statement is present, + <span class="command"><strong>named</strong></span> will not open any communication channels. + </p> + + <p> + The statistics are available in various formats and views + depending on the URI used to access them. For example, if + the statistics channel is configured to listen on 127.0.0.1 + port 8888, then the statistics are accessible in XML format at + <a class="link" href="http://127.0.0.1:8888/" target="_top">http://127.0.0.1:8888/</a> or + <a class="link" href="http://127.0.0.1:8888/xml" target="_top">http://127.0.0.1:8888/xml</a>. A CSS file is + included which can format the XML statistics into tables + when viewed with a stylesheet-capable browser, and into + charts and graphs using the Google Charts API when using a + javascript-capable browser. + </p> + + <p> + Applications that depend on a particular XML schema + can request + <a class="link" href="http://127.0.0.1:8888/xml/v2" target="_top">http://127.0.0.1:8888/xml/v2</a> for version 2 + of the statistics XML schema or + <a class="link" href="http://127.0.0.1:8888/xml/v3" target="_top">http://127.0.0.1:8888/xml/v3</a> for version 3. + If the requested schema is supported by the server, then + it will respond; if not, it will return a "page not found" + error. + </p> + + <p> + Broken-out subsets of the statistics can be viewed at + <a class="link" href="http://127.0.0.1:8888/xml/v3/status" target="_top">http://127.0.0.1:8888/xml/v3/status</a> + (server uptime and last reconfiguration time), + <a class="link" href="http://127.0.0.1:8888/xml/v3/server" target="_top">http://127.0.0.1:8888/xml/v3/server</a> + (server and resolver statistics), + <a class="link" href="http://127.0.0.1:8888/xml/v3/zones" target="_top">http://127.0.0.1:8888/xml/v3/zones</a> + (zone statistics), + <a class="link" href="http://127.0.0.1:8888/xml/v3/net" target="_top">http://127.0.0.1:8888/xml/v3/net</a> + (network status and socket statistics), + <a class="link" href="http://127.0.0.1:8888/xml/v3/mem" target="_top">http://127.0.0.1:8888/xml/v3/mem</a> + (memory manager statistics), + <a class="link" href="http://127.0.0.1:8888/xml/v3/tasks" target="_top">http://127.0.0.1:8888/xml/v3/tasks</a> + (task manager statistics), and + <a class="link" href="http://127.0.0.1:8888/xml/v3/traffic" target="_top">http://127.0.0.1:8888/xml/v3/traffic</a> + (traffic sizes). + </p> + + <p> + The full set of statistics can also be read in JSON format at + <a class="link" href="http://127.0.0.1:8888/json" target="_top">http://127.0.0.1:8888/json</a>, + with the broken-out subsets at + <a class="link" href="http://127.0.0.1:8888/json/v1/status" target="_top">http://127.0.0.1:8888/json/v1/status</a> + (server uptime and last reconfiguration time), + <a class="link" href="http://127.0.0.1:8888/json/v1/server" target="_top">http://127.0.0.1:8888/json/v1/server</a> + (server and resolver statistics), + <a class="link" href="http://127.0.0.1:8888/json/v1/zones" target="_top">http://127.0.0.1:8888/json/v1/zones</a> + (zone statistics), + <a class="link" href="http://127.0.0.1:8888/json/v1/net" target="_top">http://127.0.0.1:8888/json/v1/net</a> + (network status and socket statistics), + <a class="link" href="http://127.0.0.1:8888/json/v1/mem" target="_top">http://127.0.0.1:8888/json/v1/mem</a> + (memory manager statistics), + <a class="link" href="http://127.0.0.1:8888/json/v1/tasks" target="_top">http://127.0.0.1:8888/json/v1/tasks</a> + (task manager statistics), and + <a class="link" href="http://127.0.0.1:8888/json/v1/traffic" target="_top">http://127.0.0.1:8888/json/v1/traffic</a> + (traffic sizes). + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="trusted-keys"></a><span class="command"><strong>trusted-keys</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>trusted-keys</strong></span> { <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em> + <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>quoted_string</code></em>; ... }; +</pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="trusted_keys"></a><span class="command"><strong>trusted-keys</strong></span> Statement Definition + and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>trusted-keys</strong></span> statement defines + DNSSEC security roots. DNSSEC is described in <a class="xref" href="Bv9ARM.ch04.html#DNSSEC" title="DNSSEC">the section called “DNSSEC”</a>. A security root is defined when the + public key for a non-authoritative zone is known, but + cannot be securely obtained through DNS, either because + it is the DNS root zone or because its parent zone is + unsigned. Once a key has been configured as a trusted + key, it is treated as if it had been validated and + proven secure. The resolver attempts DNSSEC validation + on all DNS data in subdomains of a security root. + </p> + <p> + All keys (and corresponding zones) listed in + <span class="command"><strong>trusted-keys</strong></span> are deemed to exist regardless + of what parent zones say. Similarly for all keys listed in + <span class="command"><strong>trusted-keys</strong></span> only those keys are + used to validate the DNSKEY RRset. The parent's DS RRset + will not be used. + </p> + <p> + The <span class="command"><strong>trusted-keys</strong></span> statement can contain + multiple key entries, each consisting of the key's + domain name, flags, protocol, algorithm, and the Base64 + representation of the key data. + Spaces, tabs, newlines and carriage returns are ignored + in the key data, so the configuration may be split up into + multiple lines. + </p> + <p> + <span class="command"><strong>trusted-keys</strong></span> may be set at the top level + of <code class="filename">named.conf</code> or within a view. If it is + set in both places, they are additive: keys defined at the top + level are inherited by all views, but keys defined in a view + are only used within that view. + </p> + <p> + Validation below specified names can be temporarily disabled + by using <span class="command"><strong>rndc nta</strong></span>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="managed_keys"></a><span class="command"><strong>managed-keys</strong></span> Statement Grammar</h3></div></div></div> + <pre class="programlisting"> +<span class="command"><strong>managed-keys</strong></span> { <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>string</code></em> <em class="replaceable"><code>integer</code></em> + <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>integer</code></em> <em class="replaceable"><code>quoted_string</code></em>; ... }; +</pre> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="managed-keys"></a><span class="command"><strong>managed-keys</strong></span> Statement Definition + and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>managed-keys</strong></span> statement, like + <span class="command"><strong>trusted-keys</strong></span>, defines DNSSEC + security roots. The difference is that + <span class="command"><strong>managed-keys</strong></span> can be kept up to date + automatically, without intervention from the resolver + operator. + </p> + <p> + Suppose, for example, that a zone's key-signing + key was compromised, and the zone owner had to revoke and + replace the key. A resolver which had the old key in a + <span class="command"><strong>trusted-keys</strong></span> statement would be + unable to validate this zone any longer; it would + reply with a SERVFAIL response code. This would + continue until the resolver operator had updated the + <span class="command"><strong>trusted-keys</strong></span> statement with the new key. + </p> + <p> + If, however, the zone were listed in a + <span class="command"><strong>managed-keys</strong></span> statement instead, then the + zone owner could add a "stand-by" key to the zone in advance. + <span class="command"><strong>named</strong></span> would store the stand-by key, and + when the original key was revoked, <span class="command"><strong>named</strong></span> + would be able to transition smoothly to the new key. It would + also recognize that the old key had been revoked, and cease + using that key to validate answers, minimizing the damage that + the compromised key could do. + </p> + <p> + A <span class="command"><strong>managed-keys</strong></span> statement contains a list of + the keys to be managed, along with information about how the + keys are to be initialized for the first time. The only + initialization method currently supported is + <code class="literal">initial-key</code>. + This means the <span class="command"><strong>managed-keys</strong></span> statement must + contain a copy of the initializing key. (Future releases may + allow keys to be initialized by other methods, eliminating this + requirement.) + </p> + <p> + Consequently, a <span class="command"><strong>managed-keys</strong></span> statement + appears similar to a <span class="command"><strong>trusted-keys</strong></span>, differing + in the presence of the second field, containing the keyword + <code class="literal">initial-key</code>. The difference is, whereas the + keys listed in a <span class="command"><strong>trusted-keys</strong></span> continue to be + trusted until they are removed from + <code class="filename">named.conf</code>, an initializing key listed + in a <span class="command"><strong>managed-keys</strong></span> statement is only trusted + <span class="emphasis"><em>once</em></span>: for as long as it takes to load the + managed key database and start the RFC 5011 key maintenance + process. + </p> + <p> + The first time <span class="command"><strong>named</strong></span> runs with a managed key + configured in <code class="filename">named.conf</code>, it fetches the + DNSKEY RRset directly from the zone apex, and validates it + using the key specified in the <span class="command"><strong>managed-keys</strong></span> + statement. If the DNSKEY RRset is validly signed, then it is + used as the basis for a new managed keys database. + </p> + <p> + From that point on, whenever <span class="command"><strong>named</strong></span> runs, it + sees the <span class="command"><strong>managed-keys</strong></span> statement, checks to + make sure RFC 5011 key maintenance has already been initialized + for the specified domain, and if so, it simply moves on. The + key specified in the <span class="command"><strong>managed-keys</strong></span> + statement is not used to validate answers; it has been + superseded by the key or keys stored in the managed keys database. + </p> + <p> + The next time <span class="command"><strong>named</strong></span> runs after a name + has been <span class="emphasis"><em>removed</em></span> from the + <span class="command"><strong>managed-keys</strong></span> statement, the corresponding + zone will be removed from the managed keys database, + and RFC 5011 key maintenance will no longer be used for that + domain. + </p> + <p> + In the current implementation, the managed keys database + is stored as a master-format zone file. + </p> + <p> + On servers which do not use views, this file is named + <code class="filename">managed-keys.bind</code>. When views are in + use, there will be a separate managed keys database for each + view; the filename will be the view name (or, if a view name + contains characters which would make it illegal as a filename, + a hash of the view name), followed by + the suffix <code class="filename">.mkeys</code>. + </p> + <p> + When the key database is changed, the zone is updated. + As with any other dynamic zone, changes will be written + into a journal file, e.g., + <code class="filename">managed-keys.bind.jnl</code> or + <code class="filename">internal.mkeys.jnl</code>. + Changes are committed to the master file as soon as + possible afterward; this will usually occur within 30 + seconds. So, whenever <span class="command"><strong>named</strong></span> is using + automatic key maintenance, the zone file and journal file + can be expected to exist in the working directory. + (For this reason among others, the working directory + should be always be writable by <span class="command"><strong>named</strong></span>.) + </p> + <p> + If the <span class="command"><strong>dnssec-validation</strong></span> option is + set to <strong class="userinput"><code>auto</code></strong>, <span class="command"><strong>named</strong></span> + will automatically initialize a managed key for the + root zone. The key that is used to initialize the key + maintenance process is stored in <code class="filename">bind.keys</code>; + the location of this file can be overridden with the + <span class="command"><strong>bindkeys-file</strong></span> option. As a fallback + in the event no <code class="filename">bind.keys</code> can be + found, the initializing key is also compiled directly + into <span class="command"><strong>named</strong></span>. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="view_statement_grammar"></a><span class="command"><strong>view</strong></span> Statement Grammar</h3></div></div></div> + +<pre class="programlisting"><span class="command"><strong>view</strong></span> <em class="replaceable"><code>view_name</code></em> [ <em class="replaceable"><code>class</code></em> ] <span class="command"><strong>{</strong></span> + <span class="command"><strong>match-clients {</strong></span> <em class="replaceable"><code>address_match_list</code></em> <span class="command"><strong>}</strong></span> ; + <span class="command"><strong>match-destinations {</strong></span> <em class="replaceable"><code>address_match_list</code></em> <span class="command"><strong>}</strong></span> ; + <span class="command"><strong>match-recursive-only</strong></span> <em class="replaceable"><code>yes_or_no</code></em> ; + [ <em class="replaceable"><code>view_option</code></em> ; ... ] + [ <em class="replaceable"><code>zone_statement</code></em> ; ... ] +<span class="command"><strong>} </strong></span>; +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="view_statement"></a><span class="command"><strong>view</strong></span> Statement Definition and Usage</h3></div></div></div> + + <p> + The <span class="command"><strong>view</strong></span> statement is a powerful + feature + of <acronym class="acronym">BIND</acronym> 9 that lets a name server + answer a DNS query differently + depending on who is asking. It is particularly useful for + implementing + split DNS setups without having to run multiple servers. + </p> + + <p> + Each <span class="command"><strong>view</strong></span> statement defines a view + of the + DNS namespace that will be seen by a subset of clients. A client + matches + a view if its source IP address matches the + <code class="varname">address_match_list</code> of the view's + <span class="command"><strong>match-clients</strong></span> clause and its + destination IP address matches + the <code class="varname">address_match_list</code> of the + view's + <span class="command"><strong>match-destinations</strong></span> clause. If not + specified, both + <span class="command"><strong>match-clients</strong></span> and <span class="command"><strong>match-destinations</strong></span> + default to matching all addresses. In addition to checking IP + addresses + <span class="command"><strong>match-clients</strong></span> and <span class="command"><strong>match-destinations</strong></span> + can also take <span class="command"><strong>keys</strong></span> which provide an + mechanism for the + client to select the view. A view can also be specified + as <span class="command"><strong>match-recursive-only</strong></span>, which + means that only recursive + requests from matching clients will match that view. + The order of the <span class="command"><strong>view</strong></span> statements is + significant — + a client request will be resolved in the context of the first + <span class="command"><strong>view</strong></span> that it matches. + </p> + + <p> + Zones defined within a <span class="command"><strong>view</strong></span> + statement will + only be accessible to clients that match the <span class="command"><strong>view</strong></span>. + By defining a zone of the same name in multiple views, different + zone data can be given to different clients, for example, + "internal" + and "external" clients in a split DNS setup. + </p> + + <p> + Many of the options given in the <span class="command"><strong>options</strong></span> statement + can also be used within a <span class="command"><strong>view</strong></span> + statement, and then + apply only when resolving queries with that view. When no + view-specific + value is given, the value in the <span class="command"><strong>options</strong></span> statement + is used as a default. Also, zone options can have default values + specified + in the <span class="command"><strong>view</strong></span> statement; these + view-specific defaults + take precedence over those in the <span class="command"><strong>options</strong></span> statement. + </p> + + <p> + Views are class specific. If no class is given, class IN + is assumed. Note that all non-IN views must contain a hint zone, + since only the IN class has compiled-in default hints. + </p> + + <p> + If there are no <span class="command"><strong>view</strong></span> statements in + the config + file, a default view that matches any client is automatically + created + in class IN. Any <span class="command"><strong>zone</strong></span> statements + specified on + the top level of the configuration file are considered to be part + of + this default view, and the <span class="command"><strong>options</strong></span> + statement will + apply to the default view. If any explicit <span class="command"><strong>view</strong></span> + statements are present, all <span class="command"><strong>zone</strong></span> + statements must + occur inside <span class="command"><strong>view</strong></span> statements. + </p> + + <p> + Here is an example of a typical split DNS setup implemented + using <span class="command"><strong>view</strong></span> statements: + </p> + +<pre class="programlisting">view "internal" { + // This should match our internal networks. + match-clients { 10.0.0.0/8; }; + + // Provide recursive service to internal + // clients only. + recursion yes; + + // Provide a complete view of the example.com + // zone including addresses of internal hosts. + zone "example.com" { + type master; + file "example-internal.db"; + }; +}; + +view "external" { + // Match all clients not matched by the + // previous view. + match-clients { any; }; + + // Refuse recursive service to external clients. + recursion no; + + // Provide a restricted view of the example.com + // zone containing only publicly accessible hosts. + zone "example.com" { + type master; + file "example-external.db"; + }; +}; +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="zone_statement_grammar"></a><span class="command"><strong>zone</strong></span> + Statement Grammar</h3></div></div></div> + +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> ( master | primary ); + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-transfer</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-update</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>also-notify</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>alt-transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>alt-transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>auto-dnssec</strong></span> ( allow | maintain | off ); + <span class="command"><strong>check-dup-records</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-integrity</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>check-mx</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-mx-cname</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-names</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-sibling</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>check-spf</strong></span> ( warn | ignore ); + <span class="command"><strong>check-srv-cname</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>check-wildcard</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>database</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dialup</strong></span> ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>dlz</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dnssec-dnskey-kskonly</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>dnssec-secure-to-insecure</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-update-mode</strong></span> ( maintain | no-resign ); + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>inline-signing</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>ixfr-from-differences</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>journal</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>key-directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>max-journal-size</strong></span> ( unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-zone-ttl</strong></span> ( unlimited | <em class="replaceable"><code>ttlval</code></em> ); + <span class="command"><strong>notify</strong></span> ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>notify-delay</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-to-soa</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>serial-update-method</strong></span> ( date | increment | unixtime ); + <span class="command"><strong>sig-signing-nodes</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-signatures</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-type</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-validity-interval</strong></span> <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>update-check-ksk</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>update-policy</strong></span> ( local | { ( deny | grant ) <em class="replaceable"><code>string</code></em> ( 6to4-self | external | krb5-self | krb5-selfsub | krb5-subdomain | ms-self | ms-selfsub | ms-subdomain | name | self | selfsub | selfwild | subdomain | tcp-self | wildcard | zonesub ) [ <em class="replaceable"><code>string</code></em> ] <em class="replaceable"><code>rrtypelist</code></em>; ... }; + <span class="command"><strong>zero-no-soa-ttl</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> ( slave | secondary ); + <span class="command"><strong>allow-notify</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-transfer</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-update-forwarding</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>also-notify</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>alt-transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>alt-transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>auto-dnssec</strong></span> ( allow | maintain | off ); + <span class="command"><strong>check-names</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>database</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dialup</strong></span> ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>dlz</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>dnssec-dnskey-kskonly</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>dnssec-update-mode</strong></span> ( maintain | no-resign ); + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>inline-signing</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>ixfr-from-differences</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>journal</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>key-directory</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>masters</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>max-journal-size</strong></span> ( unlimited | <em class="replaceable"><code>sizeval</code></em> ); + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-out</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>multi-master</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>notify</strong></span> ( explicit | master-only | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>notify-delay</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>notify-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>notify-to-soa</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-expire</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>request-ixfr</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>sig-signing-nodes</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-signatures</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-signing-type</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>sig-validity-interval</strong></span> <em class="replaceable"><code>integer</code></em> [ <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>try-tcp-refresh</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>update-check-ksk</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>use-alt-transfer-source</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zero-no-soa-ttl</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> hint; + <span class="command"><strong>check-names</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>delegation-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> stub; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>check-names</strong></span> ( fail | warn | ignore ); + <span class="command"><strong>database</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>delegation-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>dialup</strong></span> ( notify | notify-passive | passive | refresh | <em class="replaceable"><code>boolean</code></em> ); + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>masters</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-idle-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-transfer-time-in</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-refresh-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>min-retry-time</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>multi-master</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>transfer-source</strong></span> ( <em class="replaceable"><code>ipv4_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>transfer-source-v6</strong></span> ( <em class="replaceable"><code>ipv6_address</code></em> | * ) [ port ( <em class="replaceable"><code>integer</code></em> | * ) ] [ dscp <em class="replaceable"><code>integer</code></em> ]; + <span class="command"><strong>use-alt-transfer-source</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> static-stub; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>server-addresses</strong></span> { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ]; ... }; + <span class="command"><strong>server-names</strong></span> { <em class="replaceable"><code>quoted_string</code></em>; ... }; + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> forward; + <span class="command"><strong>delegation-only</strong></span> <em class="replaceable"><code>boolean</code></em>; + <span class="command"><strong>forward</strong></span> ( first | only ); + <span class="command"><strong>forwarders</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>ipv4_address</code></em> | <em class="replaceable"><code>ipv6_address</code></em> ) [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ]; ... }; +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> redirect; + <span class="command"><strong>allow-query</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>allow-query-on</strong></span> { <em class="replaceable"><code>address_match_element</code></em>; ... }; + <span class="command"><strong>dlz</strong></span> <em class="replaceable"><code>string</code></em>; + <span class="command"><strong>file</strong></span> <em class="replaceable"><code>quoted_string</code></em>; + <span class="command"><strong>masterfile-format</strong></span> ( map | raw | text ); + <span class="command"><strong>masterfile-style</strong></span> ( full | relative ); + <span class="command"><strong>masters</strong></span> [ port <em class="replaceable"><code>integer</code></em> ] [ dscp <em class="replaceable"><code>integer</code></em> ] { ( <em class="replaceable"><code>masters</code></em> | <em class="replaceable"><code>ipv4_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] | <em class="replaceable"><code>ipv6_address</code></em> [ port <em class="replaceable"><code>integer</code></em> ] ) [ key <em class="replaceable"><code>string</code></em> ]; ... }; + <span class="command"><strong>max-records</strong></span> <em class="replaceable"><code>integer</code></em>; + <span class="command"><strong>max-zone-ttl</strong></span> ( unlimited | <em class="replaceable"><code>ttlval</code></em> ); + <span class="command"><strong>zone-statistics</strong></span> ( full | terse | none | <em class="replaceable"><code>boolean</code></em> ); +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>type</strong></span> delegation-only; +}; +</pre> +<pre class="programlisting"> +<span class="command"><strong>zone</strong></span> <em class="replaceable"><code>string</code></em> [ <em class="replaceable"><code>class</code></em> ] { + <span class="command"><strong>in-view</strong></span> <em class="replaceable"><code>string</code></em>; +}; +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="zone_statement"></a><span class="command"><strong>zone</strong></span> Statement Definition and Usage</h3></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="zone_types"></a>Zone Types</h4></div></div></div> + <p> + The <span class="command"><strong>type</strong></span> keyword is required + for the <span class="command"><strong>zone</strong></span> configuration unless + it is an <span class="command"><strong>in-view</strong></span> configuration. Its + acceptable values include: <code class="varname">delegation-only</code>, + <code class="varname">forward</code>, <code class="varname">hint</code>, + <code class="varname">master</code>, <code class="varname">redirect</code>, + <code class="varname">slave</code>, <code class="varname">static-stub</code>, + and <code class="varname">stub</code>. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col class="1"> +<col width="4.017in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="varname">master</code> + </p> + </td> +<td> + <p> + The server has a master copy of the data + for the zone and will be able to provide authoritative + answers for + it. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">slave</code> + </p> + </td> +<td> + <p> + A slave zone is a replica of a master + zone. The <span class="command"><strong>masters</strong></span> list + specifies one or more IP addresses + of master servers that the slave contacts to update + its copy of the zone. + Masters list elements can also be names of other + masters lists. + By default, transfers are made from port 53 on the + servers; this can + be changed for all servers by specifying a port number + before the + list of IP addresses, or on a per-server basis after + the IP address. + Authentication to the master can also be done with + per-server TSIG keys. + If a file is specified, then the + replica will be written to this file whenever the zone + is changed, + and reloaded from this file on a server restart. Use + of a file is + recommended, since it often speeds server startup and + eliminates + a needless waste of bandwidth. Note that for large + numbers (in the + tens or hundreds of thousands) of zones per server, it + is best to + use a two-level naming scheme for zone filenames. For + example, + a slave server for the zone <code class="literal">example.com</code> might place + the zone contents into a file called + <code class="filename">ex/example.com</code> where <code class="filename">ex/</code> is + just the first two letters of the zone name. (Most + operating systems + behave very slowly if you put 100000 files into + a single directory.) + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">stub</code> + </p> + </td> +<td> + <p> + A stub zone is similar to a slave zone, + except that it replicates only the NS records of a + master zone instead + of the entire zone. Stub zones are not a standard part + of the DNS; + they are a feature specific to the <acronym class="acronym">BIND</acronym> implementation. + </p> + + <p> + Stub zones can be used to eliminate the need for glue + NS record + in a parent zone at the expense of maintaining a stub + zone entry and + a set of name server addresses in <code class="filename">named.conf</code>. + This usage is not recommended for new configurations, + and BIND 9 + supports it only in a limited way. + In <acronym class="acronym">BIND</acronym> 4/8, zone + transfers of a parent zone + included the NS records from stub children of that + zone. This meant + that, in some cases, users could get away with + configuring child stubs + only in the master server for the parent zone. <acronym class="acronym">BIND</acronym> + 9 never mixes together zone data from different zones + in this + way. Therefore, if a <acronym class="acronym">BIND</acronym> 9 master serving a parent + zone has child stub zones configured, all the slave + servers for the + parent zone also need to have the same child stub + zones + configured. + </p> + + <p> + Stub zones can also be used as a way of forcing the + resolution + of a given domain to use a particular set of + authoritative servers. + For example, the caching name servers on a private + network using + RFC1918 addressing may be configured with stub zones + for + <code class="literal">10.in-addr.arpa</code> + to use a set of internal name servers as the + authoritative + servers for that domain. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">static-stub</code> + </p> + </td> +<td> + <p> + A static-stub zone is similar to a stub zone + with the following exceptions: + the zone data is statically configured, rather + than transferred from a master server; + when recursion is necessary for a query that + matches a static-stub zone, the locally + configured data (nameserver names and glue addresses) + is always used even if different authoritative + information is cached. + </p> + <p> + Zone data is configured via the + <span class="command"><strong>server-addresses</strong></span> and + <span class="command"><strong>server-names</strong></span> zone options. + </p> + <p> + The zone data is maintained in the form of NS + and (if necessary) glue A or AAAA RRs + internally, which can be seen by dumping zone + databases by <span class="command"><strong>rndc dumpdb -all</strong></span>. + The configured RRs are considered local configuration + parameters rather than public data. + Non recursive queries (i.e., those with the RD + bit off) to a static-stub zone are therefore + prohibited and will be responded with REFUSED. + </p> + <p> + Since the data is statically configured, no + zone maintenance action takes place for a static-stub + zone. + For example, there is no periodic refresh + attempt, and an incoming notify message + will be rejected with an rcode of NOTAUTH. + </p> + <p> + Each static-stub zone is configured with + internally generated NS and (if necessary) + glue A or AAAA RRs + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">forward</code> + </p> + </td> +<td> + <p> + A "forward zone" is a way to configure + forwarding on a per-domain basis. A <span class="command"><strong>zone</strong></span> statement + of type <span class="command"><strong>forward</strong></span> can + contain a <span class="command"><strong>forward</strong></span> + and/or <span class="command"><strong>forwarders</strong></span> + statement, + which will apply to queries within the domain given by + the zone + name. If no <span class="command"><strong>forwarders</strong></span> + statement is present or + an empty list for <span class="command"><strong>forwarders</strong></span> is given, then no + forwarding will be done for the domain, canceling the + effects of + any forwarders in the <span class="command"><strong>options</strong></span> statement. Thus + if you want to use this type of zone to change the + behavior of the + global <span class="command"><strong>forward</strong></span> option + (that is, "forward first" + to, then "forward only", or vice versa, but want to + use the same + servers as set globally) you need to re-specify the + global forwarders. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">hint</code> + </p> + </td> +<td> + <p> + The initial set of root name servers is + specified using a "hint zone". When the server starts + up, it uses + the root hints to find a root name server and get the + most recent + list of root name servers. If no hint zone is + specified for class + IN, the server uses a compiled-in default set of root + servers hints. + Classes other than IN have no built-in defaults hints. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">redirect</code> + </p> + </td> +<td> + <p> + Redirect zones are used to provide answers to + queries when normal resolution would result in + NXDOMAIN being returned. + Only one redirect zone is supported + per view. <span class="command"><strong>allow-query</strong></span> can be + used to restrict which clients see these answers. + </p> + <p> + If the client has requested DNSSEC records (DO=1) and + the NXDOMAIN response is signed then no substitution + will occur. + </p> + <p> + To redirect all NXDOMAIN responses to + 100.100.100.2 and + 2001:ffff:ffff::100.100.100.2, one would + configure a type redirect zone named ".", + with the zone file containing wildcard records + that point to the desired addresses: + <code class="literal">"*. IN A 100.100.100.2"</code> + and + <code class="literal">"*. IN AAAA 2001:ffff:ffff::100.100.100.2"</code>. + </p> + <p> + To redirect all Spanish names (under .ES) one + would use similar entries but with the names + "*.ES." instead of "*.". To redirect all + commercial Spanish names (under COM.ES) one + would use wildcard entries called "*.COM.ES.". + </p> + <p> + Note that the redirect zone supports all + possible types; it is not limited to A and + AAAA records. + </p> + <p> + Because redirect zones are not referenced + directly by name, they are not kept in the + zone lookup table with normal master and slave + zones. Consequently, it is not currently possible + to use + <span class="command"><strong>rndc reload + <em class="replaceable"><code>zonename</code></em></strong></span> + to reload a redirect zone. However, when using + <span class="command"><strong>rndc reload</strong></span> without specifying + a zone name, redirect zones will be reloaded along + with other zones. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">delegation-only</code> + </p> + </td> +<td> + <p> + This is used to enforce the delegation-only + status of infrastructure zones (e.g. COM, + NET, ORG). Any answer that is received + without an explicit or implicit delegation + in the authority section will be treated + as NXDOMAIN. This does not apply to the + zone apex. This should not be applied to + leaf zones. + </p> + <p> + <code class="varname">delegation-only</code> has no + effect on answers received from forwarders. + </p> + <p> + See caveats in <a class="xref" href="Bv9ARM.ch06.html#root_delegation_only"><span class="command"><strong>root-delegation-only</strong></span></a>. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="class"></a>Class</h4></div></div></div> + + <p> + The zone's name may optionally be followed by a class. If + a class is not specified, class <code class="literal">IN</code> (for <code class="varname">Internet</code>), + is assumed. This is correct for the vast majority of cases. + </p> + <p> + The <code class="literal">hesiod</code> class is + named for an information service from MIT's Project Athena. It + is + used to share information about various systems databases, such + as users, groups, printers and so on. The keyword + <code class="literal">HS</code> is + a synonym for hesiod. + </p> + <p> + Another MIT development is Chaosnet, a LAN protocol created + in the mid-1970s. Zone data for it can be specified with the <code class="literal">CHAOS</code> class. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="zone_options"></a>Zone Options</h4></div></div></div> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>allow-notify</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>allow-notify</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>allow-query</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-query-on</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>allow-query-on</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-transfer</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>allow-transfer</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-update</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>allow-update</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>update-policy</strong></span></span></dt> +<dd> + <p> + Specifies a "Simple Secure Update" policy. See + <a class="xref" href="Bv9ARM.ch06.html#dynamic_update_policies" title="Dynamic Update Policies">the section called “Dynamic Update Policies”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>allow-update-forwarding</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>allow-update-forwarding</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#access_control" title="Access Control">the section called “Access Control”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>also-notify</strong></span></span></dt> +<dd> + <p> + Only meaningful if <span class="command"><strong>notify</strong></span> + is + active for this zone. The set of machines that will + receive a + <code class="literal">DNS NOTIFY</code> message + for this zone is made up of all the listed name servers + (other than + the primary master) for the zone plus any IP addresses + specified + with <span class="command"><strong>also-notify</strong></span>. A port + may be specified + with each <span class="command"><strong>also-notify</strong></span> + address to send the notify + messages to a port other than the default of 53. + A TSIG key may also be specified to cause the + <code class="literal">NOTIFY</code> to be signed by the + given key. + <span class="command"><strong>also-notify</strong></span> is not + meaningful for stub zones. + The default is the empty list. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-names</strong></span></span></dt> +<dd> + <p> + This option is used to restrict the character set and + syntax of + certain domain names in master files and/or DNS responses + received from the + network. The default varies according to zone type. For <span class="command"><strong>master</strong></span> zones the default is <span class="command"><strong>fail</strong></span>. For <span class="command"><strong>slave</strong></span> + zones the default is <span class="command"><strong>warn</strong></span>. + It is not implemented for <span class="command"><strong>hint</strong></span> zones. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-mx</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-mx</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-spf</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-spf</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-wildcard</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-wildcard</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-integrity</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-integrity</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>check-sibling</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>check-sibling</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zero-no-soa-ttl</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>zero-no-soa-ttl</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>update-check-ksk</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>update-check-ksk</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-loadkeys-interval</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dnssec-loadkeys-interval</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-update-mode</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dnssec-update-mode</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-dnskey-kskonly</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dnssec-dnskey-kskonly</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>try-tcp-refresh</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>try-tcp-refresh</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>database</strong></span></span></dt> +<dd> + <p> + Specify the type of database to be used for storing the + zone data. The string following the <span class="command"><strong>database</strong></span> keyword + is interpreted as a list of whitespace-delimited words. + The first word + identifies the database type, and any subsequent words are + passed + as arguments to the database to be interpreted in a way + specific + to the database type. + </p> + <p> + The default is <strong class="userinput"><code>"rbt"</code></strong>, BIND 9's + native in-memory + red-black-tree database. This database does not take + arguments. + </p> + <p> + Other values are possible if additional database drivers + have been linked into the server. Some sample drivers are + included + with the distribution but none are linked in by default. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dialup</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dialup</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>delegation-only</strong></span></span></dt> +<dd> + <p> + The flag only applies to forward, hint and stub + zones. If set to <strong class="userinput"><code>yes</code></strong>, + then the zone will also be treated as if it is + also a delegation-only type zone. + </p> + <p> + See caveats in <a class="xref" href="Bv9ARM.ch06.html#root_delegation_only"><span class="command"><strong>root-delegation-only</strong></span></a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>file</strong></span></span></dt> +<dd> + <p> + Set the zone's filename. In <span class="command"><strong>master</strong></span>, + <span class="command"><strong>hint</strong></span>, and <span class="command"><strong>redirect</strong></span> + zones which do not have <span class="command"><strong>masters</strong></span> + defined, zone data is loaded from this file. In + <span class="command"><strong>slave</strong></span>, <span class="command"><strong>stub</strong></span>, and + <span class="command"><strong>redirect</strong></span> zones which do have + <span class="command"><strong>masters</strong></span> defined, zone data is + retrieved from another server and saved in this file. + This option is not applicable to other zone types. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>forward</strong></span></span></dt> +<dd> + <p> + Only meaningful if the zone has a forwarders + list. The <span class="command"><strong>only</strong></span> value causes + the lookup to fail + after trying the forwarders and getting no answer, while <span class="command"><strong>first</strong></span> would + allow a normal lookup to be tried. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>forwarders</strong></span></span></dt> +<dd> + <p> + Used to override the list of global forwarders. + If it is not specified in a zone of type <span class="command"><strong>forward</strong></span>, + no forwarding is done for the zone and the global options are + not used. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ixfr-base</strong></span></span></dt> +<dd> + <p> + Was used in <acronym class="acronym">BIND</acronym> 8 to + specify the name + of the transaction log (journal) file for dynamic update + and IXFR. + <acronym class="acronym">BIND</acronym> 9 ignores the option + and constructs the name of the journal + file by appending "<code class="filename">.jnl</code>" + to the name of the + zone file. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ixfr-tmp-file</strong></span></span></dt> +<dd> + <p> + Was an undocumented option in <acronym class="acronym">BIND</acronym> 8. + Ignored in <acronym class="acronym">BIND</acronym> 9. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>journal</strong></span></span></dt> +<dd> + <p> + Allow the default journal's filename to be overridden. + The default is the zone's filename with "<code class="filename">.jnl</code>" appended. + This is applicable to <span class="command"><strong>master</strong></span> and <span class="command"><strong>slave</strong></span> zones. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-journal-size</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-journal-size</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#server_resource_limits" title="Server Resource Limits">the section called “Server Resource Limits”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-records</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-records</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#server_resource_limits" title="Server Resource Limits">the section called “Server Resource Limits”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-time-in</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-transfer-time-in</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-idle-in</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-transfer-idle-in</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-time-out</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-transfer-time-out</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-transfer-idle-out</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>max-transfer-idle-out</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-delay</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify-delay</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-to-soa</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify-to-soa</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>pubkey</strong></span></span></dt> +<dd> + <p> + In <acronym class="acronym">BIND</acronym> 8, this option was + intended for specifying + a public zone key for verification of signatures in DNSSEC + signed + zones when they are loaded from disk. <acronym class="acronym">BIND</acronym> 9 does not verify signatures + on load and ignores the option. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>zone-statistics</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>zone-statistics</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>server-addresses</strong></span></span></dt> +<dd> + <p> + Only meaningful for static-stub zones. + This is a list of IP addresses to which queries + should be sent in recursive resolution for the + zone. + A non empty list for this option will internally + configure the apex NS RR with associated glue A or + AAAA RRs. + </p> + <p> + For example, if "example.com" is configured as a + static-stub zone with 192.0.2.1 and 2001:db8::1234 + in a <span class="command"><strong>server-addresses</strong></span> option, + the following RRs will be internally configured. + </p> +<pre class="programlisting">example.com. NS example.com. +example.com. A 192.0.2.1 +example.com. AAAA 2001:db8::1234</pre> + <p> + These records are internally used to resolve + names under the static-stub zone. + For instance, if the server receives a query for + "www.example.com" with the RD bit on, the server + will initiate recursive resolution and send + queries to 192.0.2.1 and/or 2001:db8::1234. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>server-names</strong></span></span></dt> +<dd> + <p> + Only meaningful for static-stub zones. + This is a list of domain names of nameservers that + act as authoritative servers of the static-stub + zone. + These names will be resolved to IP addresses when + <span class="command"><strong>named</strong></span> needs to send queries to + these servers. + To make this supplemental resolution successful, + these names must not be a subdomain of the origin + name of static-stub zone. + That is, when "example.net" is the origin of a + static-stub zone, "ns.example" and + "master.example.com" can be specified in the + <span class="command"><strong>server-names</strong></span> option, but + "ns.example.net" cannot, and will be rejected by + the configuration parser. + </p> + <p> + A non empty list for this option will internally + configure the apex NS RR with the specified names. + For example, if "example.com" is configured as a + static-stub zone with "ns1.example.net" and + "ns2.example.net" + in a <span class="command"><strong>server-names</strong></span> option, + the following RRs will be internally configured. + </p> +<pre class="programlisting">example.com. NS ns1.example.net. +example.com. NS ns2.example.net. +</pre> + <p> + These records are internally used to resolve + names under the static-stub zone. + For instance, if the server receives a query for + "www.example.com" with the RD bit on, the server + initiate recursive resolution, + resolve "ns1.example.net" and/or + "ns2.example.net" to IP addresses, and then send + queries to (one or more of) these addresses. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-validity-interval</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>sig-validity-interval</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-nodes</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>sig-signing-nodes</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-signatures</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>sig-signing-signatures</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>sig-signing-type</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>sig-signing-type</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-source</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>transfer-source</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>transfer-source-v6</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>transfer-source-v6</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>alt-transfer-source</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>alt-transfer-source</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>alt-transfer-source-v6</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>alt-transfer-source-v6</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>use-alt-transfer-source</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>use-alt-transfer-source</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-source</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify-source</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>notify-source-v6</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>notify-source-v6</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#zone_transfers" title="Zone Transfers">the section called “Zone Transfers”</a>. + </p> + </dd> +<dt> +<span class="term"><span class="command"><strong>min-refresh-time</strong></span>, </span><span class="term"><span class="command"><strong>max-refresh-time</strong></span>, </span><span class="term"><span class="command"><strong>min-retry-time</strong></span>, </span><span class="term"><span class="command"><strong>max-retry-time</strong></span></span> +</dt> +<dd> + <p> + See the description in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ixfr-from-differences</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>ixfr-from-differences</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + (Note that the <span class="command"><strong>ixfr-from-differences</strong></span> + <strong class="userinput"><code>master</code></strong> and + <strong class="userinput"><code>slave</code></strong> choices are not + available at the zone level.) + </p> + </dd> +<dt><span class="term"><span class="command"><strong>key-directory</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>key-directory</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>auto-dnssec</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>auto-dnssec</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>serial-update-method</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>serial-update-method</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>inline-signing</strong></span></span></dt> +<dd> + <p> + If <code class="literal">yes</code>, this enables + "bump in the wire" signing of a zone, where a + unsigned zone is transferred in or loaded from + disk and a signed version of the zone is served, + with possibly, a different serial number. This + behavior is disabled by default. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>multi-master</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>multi-master</strong></span> in + <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>masterfile-format</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>masterfile-format</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#tuning" title="Tuning">the section called “Tuning”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>max-zone-ttl</strong></span></span></dt> +<dd> + <p> + See the description of <span class="command"><strong>max-zone-ttl</strong></span> + in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a>. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>dnssec-secure-to-insecure</strong></span></span></dt> +<dd> + <p> + See the description of + <span class="command"><strong>dnssec-secure-to-insecure</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#boolean_options" title="Boolean Options">the section called “Boolean Options”</a>. + </p> + </dd> +</dl></div> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="dynamic_update_policies"></a>Dynamic Update Policies</h4></div></div></div> + + <p><acronym class="acronym">BIND</acronym> 9 supports two alternative + methods of granting clients the right to perform + dynamic updates to a zone, configured by the + <span class="command"><strong>allow-update</strong></span> and + <span class="command"><strong>update-policy</strong></span> option, respectively. + </p> + <p> + The <span class="command"><strong>allow-update</strong></span> clause is a simple + access control list. Any client that matches + the ACL is granted permission to update any record + in the zone. + </p> + <p> + The <span class="command"><strong>update-policy</strong></span> clause + allows more fine-grained control over what updates are + allowed. It specifies a set of rules, in which each rule + either grants or denies permission for one or more + names in the zone to be updated by one or more + identities. Identity is determined by the key that + signed the update request using either TSIG or SIG(0). + In most cases, <span class="command"><strong>update-policy</strong></span> rules + only apply to key-based identities. There is no way + to specify update permissions based on client source + address. + </p> + <p> + <span class="command"><strong>update-policy</strong></span> rules are only meaningful + for zones of type <span class="command"><strong>master</strong></span>, and are + not allowed in any other zone type. + It is a configuration error to specify both + <span class="command"><strong>allow-update</strong></span> and + <span class="command"><strong>update-policy</strong></span> at the same time. + </p> + <p> + A pre-defined <span class="command"><strong>update-policy</strong></span> rule can be + switched on with the command + <span class="command"><strong>update-policy local;</strong></span>. + Using this in a zone causes + <span class="command"><strong>named</strong></span> to generate a TSIG session key + when starting up and store it in a file; this key can then + be used by local clients to update the zone while + <span class="command"><strong>named</strong></span> is running. + By default, the session key is stored in the file + <code class="filename">/var/run/named/session.key</code>, the key name + is "local-ddns", and the key algorithm is HMAC-SHA256. + These values are configurable with the + <span class="command"><strong>session-keyfile</strong></span>, + <span class="command"><strong>session-keyname</strong></span> and + <span class="command"><strong>session-keyalg</strong></span> options, respectively. + A client running on the local system, if run with appropriate + permissions, may read the session key from the key file and + use it to sign update requests. The zone's update + policy will be set to allow that key to change any record + within the zone. Assuming the key name is "local-ddns", + this policy is equivalent to: + </p> + + <pre class="programlisting">update-policy { grant local-ddns zonesub any; }; + </pre> + + <p> + ...with the additional restriction that only clients + connecting from the local system will be permitted to send + updates. + </p> + <p> + Note that only one session key is generated by + <span class="command"><strong>named</strong></span>; all zones configured to use + <span class="command"><strong>update-policy local</strong></span> will accept the same key. + </p> + <p> + The command <span class="command"><strong>nsupdate -l</strong></span> implements this + feature, sending requests to localhost and signing them using + the key retrieved from the session key file. + </p> + + <p> + Other rule definitions look like this: + </p> + +<pre class="programlisting"> +( <span class="command"><strong>grant</strong></span> | <span class="command"><strong>deny</strong></span> ) <em class="replaceable"><code>identity</code></em> <em class="replaceable"><code>ruletype</code></em> [<span class="optional"> <em class="replaceable"><code>name</code></em> </span>] [<span class="optional"> <em class="replaceable"><code>types</code></em> </span>] +</pre> + + <p> + Each rule grants or denies privileges. Rules are checked + in the order in which they are specified in the + <span class="command"><strong>update-policy</strong></span> statement. Once a message + has successfully matched a rule, the operation is immediately + granted or denied, and no further rules are examined. There + are 13 types of rules; the rule type is specified by the + <span class="command"><strong>ruletype</strong></span> field, and the interpretation + of other fields varies depending on the rule type. + </p> + <p> + In general, a rule is matched when the + key that signed an update request matches the + <span class="command"><strong>identity</strong></span> field, the name of the record + to be updated matches the <span class="command"><strong>name</strong></span> field + (in the manner specified by the <span class="command"><strong>ruletype</strong></span> + field), and the type of the record to be updated matches the + <span class="command"><strong>types</strong></span> field. Details for each rule type + are described below. + </p> + <p> + The <span class="command"><strong>identity</strong></span> field must be set to + a fully-qualified domain name. In most cases, this + represensts the name of the TSIG or SIG(0) key that must be + used to sign the update request. If the specified name is a + wildcard, it is subject to DNS wildcard expansion, and the + rule may apply to multiple identities. When a TKEY exchange + has been used to create a shared secret, the identity of + the key used to authenticate the TKEY exchange will be + used as the identity of the shared secret. Some rule types + use identities matching the client's Kerberos principal + (e.g, <strong class="userinput"><code>"host/machine@REALM"</code></strong>) or + Windows realm (<strong class="userinput"><code>machine$@REALM</code></strong>). + </p> + <p> + The <em class="replaceable"><code>name</code></em> field also specifies + a fully-qualified domain name. This often + represents the name of the record to be updated. + Interpretation of this field is dependent on rule type. + </p> + <p> + If no <span class="command"><strong>types</strong></span> are explicitly specified, + then a rule matches all types except RRSIG, NS, SOA, NSEC + and NSEC3. Types may be specified by name, including + "ANY" (ANY matches all types except NSEC and NSEC3, + which can never be updated). Note that when an attempt + is made to delete all records associated with a name, + the rules are checked for each existing record type. + </p> + <p> + The <em class="replaceable"><code>ruletype</code></em> field has 16 + values: + <code class="varname">name</code>, <code class="varname">subdomain</code>, + <code class="varname">wildcard</code>, <code class="varname">self</code>, + <code class="varname">selfsub</code>, <code class="varname">selfwild</code>, + <code class="varname">krb5-self</code>, <code class="varname">ms-self</code>, + <code class="varname">krb5-selfsub</code>, <code class="varname">ms-selfsub</code>, + <code class="varname">krb5-subdomain</code>, + <code class="varname">ms-subdomain</code>, + <code class="varname">tcp-self</code>, <code class="varname">6to4-self</code>, + <code class="varname">zonesub</code>, and <code class="varname">external</code>. + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.819in" class="1"> +<col width="3.681in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="varname">name</code> + </p> + </td> +<td> + <p> + Exact-match semantics. This rule matches + when the name being updated is identical + to the contents of the + <em class="replaceable"><code>name</code></em> field. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">subdomain</code> + </p> + </td> +<td> + <p> + This rule matches when the name being updated + is a subdomain of, or identical to, the + contents of the <em class="replaceable"><code>name</code></em> + field. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">zonesub</code> + </p> + </td> +<td> + <p> + This rule is similar to subdomain, except that + it matches when the name being updated is a + subdomain of the zone in which the + <span class="command"><strong>update-policy</strong></span> statement + appears. This obviates the need to type the zone + name twice, and enables the use of a standard + <span class="command"><strong>update-policy</strong></span> statement in + multiple zones without modification. + </p> + <p> + When this rule is used, the + <em class="replaceable"><code>name</code></em> field is omitted. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">wildcard</code> + </p> + </td> +<td> + <p> + The <em class="replaceable"><code>name</code></em> field + is subject to DNS wildcard expansion, and + this rule matches when the name being updated + is a valid expansion of the wildcard. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">self</code> + </p> + </td> +<td> + <p> + This rule matches when the name of the record + being updated matches the contents of the + <em class="replaceable"><code>identity</code></em> field. + The <em class="replaceable"><code>name</code></em> field + is ignored. To avoid confusion, it is recommended + that this field be set to the same value as the + <em class="replaceable"><code>identity</code></em> field or to + "." + </p> + <p> + The <code class="varname">self</code> rule type is + most useful when allowing one key per + name to update, where the key has the same + name as the record to be updated. In this case, + the <em class="replaceable"><code>identity</code></em> field + can be specified as <code class="constant">*</code> + (an asterisk). + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">selfsub</code> + </p> + </td> +<td> + <p> + This rule is similar to <code class="varname">self</code> + except that subdomains of <code class="varname">self</code> + can also be updated. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">selfwild</code> + </p> + </td> +<td> + <p> + This rule is similar to <code class="varname">self</code> + except that only subdomains of + <code class="varname">self</code> can be updated. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ms-self</code> + </p> + </td> +<td> + <p> + When a client sends an UPDATE using a Windows + machine principal (for example, 'machine$@REALM'), + this rule allows records with the absolute name + of 'machine.REALM' to be updated. + </p> + <p> + The realm to be matched is specified in the + <em class="replaceable"><code>identity</code></em> field. + </p> + <p> + The <em class="replaceable"><code>name</code></em> field has + no effect on this rule; it should be set to "." + as a placeholder. + </p> + <p> + For example, + <strong class="userinput"><code>grant EXAMPLE.COM ms-self . A AAAA</code></strong> + allows any machine with a valid principal in + the realm <strong class="userinput"><code>EXAMPLE.COM</code></strong> to update + its own address records. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ms-selfsub</code> + </p> + </td> +<td> + <p> + This is similar to <span class="command"><strong>ms-self</strong></span> + except it also allows updates to any subdomain of + the name specified in the Windows machine + principal, not just to the name itself. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">ms-subdomain</code> + </p> + </td> +<td> + <p> + When a client sends an UPDATE using a Windows + machine principal (for example, 'machine$@REALM'), + this rule allows any machine in the specified + realm to update any record in the zone or in a + specified subdomain of the zone. + </p> + <p> + The realm to be matched is specified in the + <em class="replaceable"><code>identity</code></em> field. + </p> + <p> + The <em class="replaceable"><code>name</code></em> field + specifies the subdomain that may be updated. + If set to "." (or any other name at or above + the zone apex), any name in the zone can be + updated. + </p> + <p> + For example, if <span class="command"><strong>update-policy</strong></span> + for the zone "example.com" includes + <strong class="userinput"><code>grant EXAMPLE.COM ms-subdomain hosts.example.com. A AAAA</code></strong>, + any machine with a valid principal in + the realm <strong class="userinput"><code>EXAMPLE.COM</code></strong> will + be able to update address records at or below + "hosts.example.com". + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">krb5-self</code> + </p> + </td> +<td> + <p> + When a client sends an UPDATE using a + Kerberos machine principal (for example, + 'host/machine@REALM'), this rule allows + records with the absolute name of 'machine' + to be updated provided it has been authenticated + by REALM. This is similar but not identical + to <span class="command"><strong>ms-self</strong></span> due to the + 'machine' part of the Kerberos principal + being an absolute name instead of a unqualified + name. + </p> + <p> + The realm to be matched is specified in the + <em class="replaceable"><code>identity</code></em> field. + </p> + <p> + The <em class="replaceable"><code>name</code></em> field has + no effect on this rule; it should be set to "." + as a placeholder. + </p> + <p> + For example, + <strong class="userinput"><code>grant EXAMPLE.COM krb5-self . A AAAA</code></strong> + allows any machine with a valid principal in + the realm <strong class="userinput"><code>EXAMPLE.COM</code></strong> to update + its own address records. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">krb5-selfsub</code> + </p> + </td> +<td> + <p> + This is similar to <span class="command"><strong>krb5-self</strong></span> + except it also allows updates to any subdomain of + the name specified in the 'machine' part of the + Kerberos principal, not just to the name itself. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">krb5-subdomain</code> + </p> + </td> +<td> + <p> + This rule is identical to + <span class="command"><strong>ms-subdomain</strong></span>, except that it works + with Kerberos machine principals (i.e., + 'host/machine@REALM') rather than Windows machine + principals. + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">tcp-self</code> + </p> + </td> +<td> + <p> + This rule allows updates that have been sent via + TCP and for which the standard mapping from the + client's IP address into the + <code class="literal">in-addr.arpa</code> and + <code class="literal">ip6.arpa</code> + namespaces match the name to be updated. + The <span class="command"><strong>identity</strong></span> field must match + that name. The <span class="command"><strong>name</strong></span> field + should be set to ".". + Note that, since identity is based on the client's + IP address, it is not necessary for update request + messages to be signed. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + It is theoretically possible to spoof these TCP + sessions. + </div> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">6to4-self</code> + </p> + </td> +<td> + <p> + This allows the name matching a 6to4 IPv6 prefix, + as specified in RFC 3056, to be updated by any + TCP connection from either the 6to4 network or + from the corresponding IPv4 address. This is + intended to allow NS or DNAME RRsets to be added + to the <code class="literal">ip6.arpa</code> reverse tree. + </p> + <p> + The <span class="command"><strong>identity</strong></span> field must match + the 6to4 prefix in <code class="literal">ip6.arpa</code>. + The <span class="command"><strong>name</strong></span> field should + be set to ".". + Note that, since identity is based on the client's + IP address, it is not necessary for update request + messages to be signed. + </p> + <p> + In addition, if specified for an + <code class="literal">ip6.arpa</code> name outside of the + <code class="literal">2.0.0.2.ip6.arpa</code> namespace, + the corresponding /48 reverse name can be updated. + For example, TCP/IPv6 connections + from 2001:DB8:ED0C::/48 can update records at + <code class="literal">C.0.D.E.8.B.D.0.1.0.0.2.ip6.arpa</code>. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + It is theoretically possible to spoof these TCP + sessions. + </div> + </td> +</tr> +<tr> +<td> + <p> + <code class="varname">external</code> + </p> + </td> +<td> + <p> + This rule allows <span class="command"><strong>named</strong></span> + to defer the decision of whether to allow a + given update to an external daemon. + </p> + <p> + The method of communicating with the daemon is + specified in the <em class="replaceable"><code>identity</code></em> + field, the format of which is + "<code class="constant">local:</code><em class="replaceable"><code>path</code></em>", + where <em class="replaceable"><code>path</code></em> is the location + of a UNIX-domain socket. (Currently, "local" is the + only supported mechanism.) + </p> + <p> + Requests to the external daemon are sent over the + UNIX-domain socket as datagrams with the following + format: + </p> + <pre class="programlisting"> + Protocol version number (4 bytes, network byte order, currently 1) + Request length (4 bytes, network byte order) + Signer (null-terminated string) + Name (null-terminated string) + TCP source address (null-terminated string) + Rdata type (null-terminated string) + Key (null-terminated string) + TKEY token length (4 bytes, network byte order) + TKEY token (remainder of packet)</pre> + <p> + The daemon replies with a four-byte value in + network byte order, containing either 0 or 1; 0 + indicates that the specified update is not + permitted, and 1 indicates that it is. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="multiple_views"></a>Multiple views</h4></div></div></div> + + <p> + When multiple views are in use, a zone may be + referenced by more than one of them. Often, the views + will contain different zones with the same name, allowing + different clients to receive different answers for the same + queries. At times, however, it is desirable for multiple + views to contain identical zones. The + <span class="command"><strong>in-view</strong></span> zone option provides an efficient + way to do this: it allows a view to reference a zone that + was defined in a previously configured view. Example: + </p> + <pre class="programlisting"> +view internal { + match-clients { 10/8; }; + + zone example.com { + type master; + file "example-external.db"; + }; +}; + +view external { + match-clients { any; }; + + zone example.com { + in-view internal; + }; +}; + </pre> + <p> + An <span class="command"><strong>in-view</strong></span> option cannot refer to a view + that is configured later in the configuration file. + </p> + <p> + A <span class="command"><strong>zone</strong></span> statement which uses the + <span class="command"><strong>in-view</strong></span> option may not use any other + options with the exception of <span class="command"><strong>forward</strong></span> + and <span class="command"><strong>forwarders</strong></span>. (These options control + the behavior of the containing view, rather than changing + the zone object itself.) + </p> + <p> + Zone level acls (e.g. allow-query, allow-transfer) and + other configuration details of the zone are all set + in the view the referenced zone is defined in. Care + need to be taken to ensure that acls are wide enough + for all views referencing the zone. + </p> + <p> + An <span class="command"><strong>in-view</strong></span> zone cannot be used as a + response policy zone. + </p> + <p> + An <span class="command"><strong>in-view</strong></span> zone is not intended to reference + a <span class="command"><strong>forward</strong></span> zone. + </p> + </div> + + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="zone_file"></a>Zone File</h2></div></div></div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="types_of_resource_records_and_when_to_use_them"></a>Types of Resource Records and When to Use Them</h3></div></div></div> + + <p> + This section, largely borrowed from RFC 1034, describes the + concept of a Resource Record (RR) and explains when each is used. + Since the publication of RFC 1034, several new RRs have been + identified + and implemented in the DNS. These are also included. + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="id-1.7.6.2.3"></a>Resource Records</h4></div></div></div> + + <p> + A domain name identifies a node. Each node has a set of + resource information, which may be empty. The set of resource + information associated with a particular name is composed of + separate RRs. The order of RRs in a set is not significant and + need not be preserved by name servers, resolvers, or other + parts of the DNS. However, sorting of multiple RRs is + permitted for optimization purposes, for example, to specify + that a particular nearby server be tried first. See <a class="xref" href="Bv9ARM.ch06.html#the_sortlist_statement" title="The sortlist Statement">the section called “The <span class="command"><strong>sortlist</strong></span> Statement”</a> and <a class="xref" href="Bv9ARM.ch06.html#rrset_ordering" title="RRset Ordering">the section called “RRset Ordering”</a>. + </p> + + <p> + The components of a Resource Record are: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.000in" class="1"> +<col width="3.500in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + owner name + </p> + </td> +<td> + <p> + The domain name where the RR is found. + </p> + </td> +</tr> +<tr> +<td> + <p> + type + </p> + </td> +<td> + <p> + An encoded 16-bit value that specifies + the type of the resource record. + </p> + </td> +</tr> +<tr> +<td> + <p> + TTL + </p> + </td> +<td> + <p> + The time-to-live of the RR. This field + is a 32-bit integer in units of seconds, and is + primarily used by + resolvers when they cache RRs. The TTL describes how + long a RR can + be cached before it should be discarded. + </p> + </td> +</tr> +<tr> +<td> + <p> + class + </p> + </td> +<td> + <p> + An encoded 16-bit value that identifies + a protocol family or instance of a protocol. + </p> + </td> +</tr> +<tr> +<td> + <p> + RDATA + </p> + </td> +<td> + <p> + The resource data. The format of the + data is type (and sometimes class) specific. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + The following are <span class="emphasis"><em>types</em></span> of valid RRs: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.875in" class="1"> +<col width="3.625in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + A + </p> + </td> +<td> + <p> + A host address. In the IN class, this is a + 32-bit IP address. Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + AAAA + </p> + </td> +<td> + <p> + IPv6 address. Described in RFC 1886. + </p> + </td> +</tr> +<tr> +<td> + <p> + A6 + </p> + </td> +<td> + <p> + IPv6 address. This can be a partial + address (a suffix) and an indirection to the name + where the rest of the + address (the prefix) can be found. Experimental. + Described in RFC 2874. + </p> + </td> +</tr> +<tr> +<td> + <p> + AFSDB + </p> + </td> +<td> + <p> + Location of AFS database servers. + Experimental. Described in RFC 1183. + </p> + </td> +</tr> +<tr> +<td> + <p> + APL + </p> + </td> +<td> + <p> + Address prefix list. Experimental. + Described in RFC 3123. + </p> + </td> +</tr> +<tr> +<td> + <p> + ATMA + </p> + </td> +<td> + <p> + ATM Address. + </p> + </td> +</tr> +<tr> +<td> + <p> + AVC + </p> + </td> +<td> + <p> + Application Visibility and Control record. + </p> + </td> +</tr> +<tr> +<td> + <p> + CAA + </p> + </td> +<td> + <p> + Identifies which Certificate Authorities can issue + certificates for this domain and what rules they + need to follow when doing so. Defined in RFC 6844. + </p> + </td> +</tr> +<tr> +<td> + <p> + CDNSKEY + </p> + </td> +<td> + <p> + Identifies which DNSKEY records should be published + as DS records in the parent zone. + </p> + </td> +</tr> +<tr> +<td> + <p> + CDS + </p> + </td> +<td> + <p> + Contains the set of DS records that should be published + by the parent zone. + </p> + </td> +</tr> +<tr> +<td> + <p> + CERT + </p> + </td> +<td> + <p> + Holds a digital certificate. + Described in RFC 2538. + </p> + </td> +</tr> +<tr> +<td> + <p> + CNAME + </p> + </td> +<td> + <p> + Identifies the canonical name of an alias. + Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + CSYNC + </p> + </td> +<td> + <p> + Child-to-Parent Synchronization in DNS as described + in RFC 7477. + </p> + </td> +</tr> +<tr> +<td> + <p> + DHCID + </p> + </td> +<td> + <p> + Is used for identifying which DHCP client is + associated with this name. Described in RFC 4701. + </p> + </td> +</tr> +<tr> +<td> + <p> + DLV + </p> + </td> +<td> + <p> + A DNS Look-aside Validation record which contains + the records that are used as trust anchors for + zones in a DLV namespace. Described in RFC 4431. + </p> + </td> +</tr> +<tr> +<td> + <p> + DNAME + </p> + </td> +<td> + <p> + Replaces the domain name specified with + another name to be looked up, effectively aliasing an + entire + subtree of the domain name space rather than a single + record + as in the case of the CNAME RR. + Described in RFC 2672. + </p> + </td> +</tr> +<tr> +<td> + <p> + DNSKEY + </p> + </td> +<td> + <p> + Stores a public key associated with a signed + DNS zone. Described in RFC 4034. + </p> + </td> +</tr> +<tr> +<td> + <p> + DOA + </p> + </td> +<td> + <p> + Implements the Digital Object Architecture over + DNS. Experimental. + </p> + </td> +</tr> +<tr> +<td> + <p> + DS + </p> + </td> +<td> + <p> + Stores the hash of a public key associated with a + signed DNS zone. Described in RFC 4034. + </p> + </td> +</tr> +<tr> +<td> + <p> + EID + </p> + </td> +<td> + <p> + End Point Identifier. + </p> + </td> +</tr> +<tr> +<td> + <p> + EUI48 + </p> + </td> +<td> + <p> + A 48-bit EUI address. Described in RFC 7043. + </p> + </td> +</tr> +<tr> +<td> + <p> + EUI64 + </p> + </td> +<td> + <p> + A 64-bit EUI address. Described in RFC 7043. + </p> + </td> +</tr> +<tr> +<td> + <p> + GID + </p> + </td> +<td> + <p> + Reserved. + </p> + </td> +</tr> +<tr> +<td> + <p> + GPOS + </p> + </td> +<td> + <p> + Specifies the global position. Superseded by LOC. + </p> + </td> +</tr> +<tr> +<td> + <p> + HINFO + </p> + </td> +<td> + <p> + Identifies the CPU and OS used by a host. + Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + HIP + </p> + </td> +<td> + <p> + Host Identity Protocol Address. + Described in RFC 5205. + </p> + </td> +</tr> +<tr> +<td> + <p> + IPSECKEY + </p> + </td> +<td> + <p> + Provides a method for storing IPsec keying material in + DNS. Described in RFC 4025. + </p> + </td> +</tr> +<tr> +<td> + <p> + ISDN + </p> + </td> +<td> + <p> + Representation of ISDN addresses. + Experimental. Described in RFC 1183. + </p> + </td> +</tr> +<tr> +<td> + <p> + KEY + </p> + </td> +<td> + <p> + Stores a public key associated with a + DNS name. Used in original DNSSEC; replaced + by DNSKEY in DNSSECbis, but still used with + SIG(0). Described in RFCs 2535 and 2931. + </p> + </td> +</tr> +<tr> +<td> + <p> + KX + </p> + </td> +<td> + <p> + Identifies a key exchanger for this + DNS name. Described in RFC 2230. + </p> + </td> +</tr> +<tr> +<td> + <p> + L32 + </p> + </td> +<td> + <p> + Holds 32-bit Locator values for + Identifier-Locator Network Protocol. Described + in RFC 6742. + </p> + </td> +</tr> +<tr> +<td> + <p> + L64 + </p> + </td> +<td> + <p> + Holds 64-bit Locator values for + Identifier-Locator Network Protocol. Described + in RFC 6742. + </p> + </td> +</tr> +<tr> +<td> + <p> + LOC + </p> + </td> +<td> + <p> + For storing GPS info. Described in RFC 1876. + Experimental. + </p> + </td> +</tr> +<tr> +<td> + <p> + LP + </p> + </td> +<td> + <p> + Identifier-Locator Network Protocol. + Described in RFC 6742. + </p> + </td> +</tr> +<tr> +<td> + <p> + MB + </p> + </td> +<td> + <p> + Mail Box. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MD + </p> + </td> +<td> + <p> + Mail Destination. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MF + </p> + </td> +<td> + <p> + Mail Forwarder. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MG + </p> + </td> +<td> + <p> + Mail Group. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MINFO + </p> + </td> +<td> + <p> + Mail Information. + </p> + </td> +</tr> +<tr> +<td> + <p> + MR + </p> + </td> +<td> + <p> + Mail Rename. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + MX + </p> + </td> +<td> + <p> + Identifies a mail exchange for the domain with + a 16-bit preference value (lower is better) + followed by the host name of the mail exchange. + Described in RFC 974, RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + NAPTR + </p> + </td> +<td> + <p> + Name authority pointer. Described in RFC 2915. + </p> + </td> +</tr> +<tr> +<td> + <p> + NID + </p> + </td> +<td> + <p> + Holds values for Node Identifiers in + Identifier-Locator Network Protocol. Described + in RFC 6742. + </p> + </td> +</tr> +<tr> +<td> + <p> + NINFO + </p> + </td> +<td> + <p> + Contains zone status information. + </p> + </td> +</tr> +<tr> +<td> + <p> + NIMLOC + </p> + </td> +<td> + <p> + Nimrod Locator. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSAP + </p> + </td> +<td> + <p> + A network service access point. + Described in RFC 1706. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSAP-PTR + </p> + </td> +<td> + <p> + Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + NS + </p> + </td> +<td> + <p> + The authoritative name server for the + domain. Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSEC + </p> + </td> +<td> + <p> + Used in DNSSECbis to securely indicate that + RRs with an owner name in a certain name interval do + not exist in + a zone and indicate what RR types are present for an + existing name. + Described in RFC 4034. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSEC3 + </p> + </td> +<td> + <p> + Used in DNSSECbis to securely indicate that + RRs with an owner name in a certain name + interval do not exist in a zone and indicate + what RR types are present for an existing + name. NSEC3 differs from NSEC in that it + prevents zone enumeration but is more + computationally expensive on both the server + and the client than NSEC. Described in RFC + 5155. + </p> + </td> +</tr> +<tr> +<td> + <p> + NSEC3PARAM + </p> + </td> +<td> + <p> + Used in DNSSECbis to tell the authoritative + server which NSEC3 chains are available to use. + Described in RFC 5155. + </p> + </td> +</tr> +<tr> +<td> + <p> + NULL + </p> + </td> +<td> + <p> + This is an opaque container. + </p> + </td> +</tr> +<tr> +<td> + <p> + NXT + </p> + </td> +<td> + <p> + Used in DNSSEC to securely indicate that + RRs with an owner name in a certain name interval do + not exist in + a zone and indicate what RR types are present for an + existing name. + Used in original DNSSEC; replaced by NSEC in + DNSSECbis. + Described in RFC 2535. + </p> + </td> +</tr> +<tr> +<td> + <p> + OPENPGPKEY + </p> + </td> +<td> + <p> + Used to hold an OPENPGPKEY. + </p> + </td> +</tr> +<tr> +<td> + <p> + PTR + </p> + </td> +<td> + <p> + A pointer to another part of the domain + name space. Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + PX + </p> + </td> +<td> + <p> + Provides mappings between RFC 822 and X.400 + addresses. Described in RFC 2163. + </p> + </td> +</tr> +<tr> +<td> + <p> + RKEY + </p> + </td> +<td> + <p> + Resource key. + </p> + </td> +</tr> +<tr> +<td> + <p> + RP + </p> + </td> +<td> + <p> + Information on persons responsible + for the domain. Experimental. Described in RFC 1183. + </p> + </td> +</tr> +<tr> +<td> + <p> + RRSIG + </p> + </td> +<td> + <p> + Contains DNSSECbis signature data. Described + in RFC 4034. + </p> + </td> +</tr> +<tr> +<td> + <p> + RT + </p> + </td> +<td> + <p> + Route-through binding for hosts that + do not have their own direct wide area network + addresses. + Experimental. Described in RFC 1183. + </p> + </td> +</tr> +<tr> +<td> + <p> + SIG + </p> + </td> +<td> + <p> + Contains DNSSEC signature data. Used in + original DNSSEC; replaced by RRSIG in + DNSSECbis, but still used for SIG(0). + Described in RFCs 2535 and 2931. + </p> + </td> +</tr> +<tr> +<td> + <p> + SINK + </p> + </td> +<td> + <p> + The kitchen sink record. + </p> + </td> +</tr> +<tr> +<td> + <p> + SMIMEA + </p> + </td> +<td> + <p> + The S/MIME Security Certificate Association. + </p> + </td> +</tr> +<tr> +<td> + <p> + SOA + </p> + </td> +<td> + <p> + Identifies the start of a zone of authority. + Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + SPF + </p> + </td> +<td> + <p> + Contains the Sender Policy Framework information + for a given email domain. Described in RFC 4408. + </p> + </td> +</tr> +<tr> +<td> + <p> + SRV + </p> + </td> +<td> + <p> + Information about well known network + services (replaces WKS). Described in RFC 2782. + </p> + </td> +</tr> +<tr> +<td> + <p> + SSHFP + </p> + </td> +<td> + <p> + Provides a way to securely publish a secure shell key's + fingerprint. Described in RFC 4255. + </p> + </td> +</tr> +<tr> +<td> + <p> + TA + </p> + </td> +<td> + <p> + Trust Anchor. Experimental. + </p> + </td> +</tr> +<tr> +<td> + <p> + TALINK + </p> + </td> +<td> + <p> + Trust Anchor Link. Experimental. + </p> + </td> +</tr> +<tr> +<td> + <p> + TLSA + </p> + </td> +<td> + <p> + Transport Layer Security Certificate Association. + Described in RFC 6698. + </p> + </td> +</tr> +<tr> +<td> + <p> + TXT + </p> + </td> +<td> + <p> + Text records. Described in RFC 1035. + </p> + </td> +</tr> +<tr> +<td> + <p> + UID + </p> + </td> +<td> + <p> + Reserved. + </p> + </td> +</tr> +<tr> +<td> + <p> + UINFO + </p> + </td> +<td> + <p> + Reserved. + </p> + </td> +</tr> +<tr> +<td> + <p> + UNSPEC + </p> + </td> +<td> + <p> + Reserved. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + URI + </p> + </td> +<td> + <p> + Holds a URI. Described in RFC 7553. + </p> + </td> +</tr> +<tr> +<td> + <p> + WKS + </p> + </td> +<td> + <p> + Information about which well known + network services, such as SMTP, that a domain + supports. Historical. + </p> + </td> +</tr> +<tr> +<td> + <p> + X25 + </p> + </td> +<td> + <p> + Representation of X.25 network addresses. + Experimental. Described in RFC 1183. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + The following <span class="emphasis"><em>classes</em></span> of resource records + are currently valid in the DNS: + </p> + <div class="informaltable"> +<table border="1"> +<colgroup> +<col width="0.875in" class="1"> +<col width="3.625in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + IN + </p> + </td> +<td> + <p> + The Internet. + </p> + </td> +</tr> +<tr> +<td> + <p> + CH + </p> + </td> +<td> + <p> + Chaosnet, a LAN protocol created at MIT in the + mid-1970s. + Rarely used for its historical purpose, but reused for + BIND's + built-in server information zones, e.g., + <code class="literal">version.bind</code>. + </p> + </td> +</tr> +<tr> +<td> + <p> + HS + </p> + </td> +<td> + <p> + Hesiod, an information service + developed by MIT's Project Athena. It is used to share + information + about various systems databases, such as users, + groups, printers + and so on. + </p> + </td> +</tr> +</tbody> +</table> + </div> + + <p> + The owner name is often implicit, rather than forming an + integral + part of the RR. For example, many name servers internally form + tree + or hash structures for the name space, and chain RRs off nodes. + The remaining RR parts are the fixed header (type, class, TTL) + which is consistent for all RRs, and a variable part (RDATA) + that + fits the needs of the resource being described. + </p> + <p> + The meaning of the TTL field is a time limit on how long an + RR can be kept in a cache. This limit does not apply to + authoritative + data in zones; it is also timed out, but by the refreshing + policies + for the zone. The TTL is assigned by the administrator for the + zone where the data originates. While short TTLs can be used to + minimize caching, and a zero TTL prohibits caching, the + realities + of Internet performance suggest that these times should be on + the + order of days for the typical host. If a change can be + anticipated, + the TTL can be reduced prior to the change to minimize + inconsistency + during the change, and then increased back to its former value + following + the change. + </p> + <p> + The data in the RDATA section of RRs is carried as a combination + of binary strings and domain names. The domain names are + frequently + used as "pointers" to other data in the DNS. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="rr_text"></a>Textual expression of RRs</h4></div></div></div> + + <p> + RRs are represented in binary form in the packets of the DNS + protocol, and are usually represented in highly encoded form + when + stored in a name server or resolver. In the examples provided + in + RFC 1034, a style similar to that used in master files was + employed + in order to show the contents of RRs. In this format, most RRs + are shown on a single line, although continuation lines are + possible + using parentheses. + </p> + <p> + The start of the line gives the owner of the RR. If a line + begins with a blank, then the owner is assumed to be the same as + that of the previous RR. Blank lines are often included for + readability. + </p> + <p> + Following the owner, we list the TTL, type, and class of the + RR. Class and type use the mnemonics defined above, and TTL is + an integer before the type field. In order to avoid ambiguity + in + parsing, type and class mnemonics are disjoint, TTLs are + integers, + and the type mnemonic is always last. The IN class and TTL + values + are often omitted from examples in the interests of clarity. + </p> + <p> + The resource data or RDATA section of the RR are given using + knowledge of the typical representation for the data. + </p> + <p> + For example, we might show the RRs carried in a message as: + </p> + <div class="informaltable"> +<table border="1"> +<colgroup> +<col width="1.381in" class="1"> +<col width="1.020in" class="2"> +<col width="2.099in" class="3"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="literal">ISI.EDU.</code> + </p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">10 VENERA.ISI.EDU.</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">10 VAXA.ISI.EDU</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">VENERA.ISI.EDU</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">128.9.0.32</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.1.0.52</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">VAXA.ISI.EDU</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.2.0.27</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">128.9.0.33</code> + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + The MX RRs have an RDATA section which consists of a 16-bit + number followed by a domain name. The address RRs use a + standard + IP address format to contain a 32-bit internet address. + </p> + <p> + The above example shows six RRs, with two RRs at each of three + domain names. + </p> + <p> + Similarly we might see: + </p> + <div class="informaltable"> +<table border="1"> +<colgroup> +<col width="1.491in" class="1"> +<col width="1.067in" class="2"> +<col width="2.067in" class="3"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="literal">XX.LCS.MIT.EDU.</code> + </p> + </td> +<td> + <p> + <code class="literal">IN A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.0.0.44</code> + </p> + </td> +</tr> +<tr> +<td> </td> +<td> + <p> + <code class="literal">CH A</code> + </p> + </td> +<td> + <p> + <code class="literal">MIT.EDU. 2420</code> + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + This example shows two addresses for + <code class="literal">XX.LCS.MIT.EDU</code>, each of a different class. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="mx_records"></a>Discussion of MX Records</h3></div></div></div> + + <p> + As described above, domain servers store information as a + series of resource records, each of which contains a particular + piece of information about a given domain name (which is usually, + but not always, a host). The simplest way to think of a RR is as + a typed pair of data, a domain name matched with a relevant datum, + and stored with some additional type information to help systems + determine when the RR is relevant. + </p> + + <p> + MX records are used to control delivery of email. The data + specified in the record is a priority and a domain name. The + priority + controls the order in which email delivery is attempted, with the + lowest number first. If two priorities are the same, a server is + chosen randomly. If no servers at a given priority are responding, + the mail transport agent will fall back to the next largest + priority. + Priority numbers do not have any absolute meaning — they are + relevant + only respective to other MX records for that domain name. The + domain + name given is the machine to which the mail will be delivered. + It <span class="emphasis"><em>must</em></span> have an associated address record + (A or AAAA) — CNAME is not sufficient. + </p> + <p> + For a given domain, if there is both a CNAME record and an + MX record, the MX record is in error, and will be ignored. + Instead, + the mail will be delivered to the server specified in the MX + record + pointed to by the CNAME. + For example: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.708in" class="1"> +<col width="0.444in" class="2"> +<col width="0.444in" class="3"> +<col width="0.976in" class="4"> +<col width="1.553in" class="5"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="literal">example.com.</code> + </p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">10</code> + </p> + </td> +<td> + <p> + <code class="literal">mail.example.com.</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">10</code> + </p> + </td> +<td> + <p> + <code class="literal">mail2.example.com.</code> + </p> + </td> +</tr> +<tr> +<td> + <p></p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">MX</code> + </p> + </td> +<td> + <p> + <code class="literal">20</code> + </p> + </td> +<td> + <p> + <code class="literal">mail.backup.org.</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">mail.example.com.</code> + </p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.0.0.1</code> + </p> + </td> +<td> + <p></p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">mail2.example.com.</code> + </p> + </td> +<td> + <p> + <code class="literal">IN</code> + </p> + </td> +<td> + <p> + <code class="literal">A</code> + </p> + </td> +<td> + <p> + <code class="literal">10.0.0.2</code> + </p> + </td> +<td> + <p></p> + </td> +</tr> +</tbody> +</table> + </div> +<p> + Mail delivery will be attempted to <code class="literal">mail.example.com</code> and + <code class="literal">mail2.example.com</code> (in + any order), and if neither of those succeed, delivery to <code class="literal">mail.backup.org</code> will + be attempted. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="Setting_TTLs"></a>Setting TTLs</h3></div></div></div> + + <p> + The time-to-live of the RR field is a 32-bit integer represented + in units of seconds, and is primarily used by resolvers when they + cache RRs. The TTL describes how long a RR can be cached before it + should be discarded. The following three types of TTL are + currently + used in a zone file. + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.750in" class="1"> +<col width="4.375in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + SOA + </p> + </td> +<td> + <p> + The last field in the SOA is the negative + caching TTL. This controls how long other servers will + cache no-such-domain + (NXDOMAIN) responses from you. + </p> + <p> + The maximum time for + negative caching is 3 hours (3h). + </p> + </td> +</tr> +<tr> +<td> + <p> + $TTL + </p> + </td> +<td> + <p> + The $TTL directive at the top of the + zone file (before the SOA) gives a default TTL for every + RR without + a specific TTL set. + </p> + </td> +</tr> +<tr> +<td> + <p> + RR TTLs + </p> + </td> +<td> + <p> + Each RR can have a TTL as the second + field in the RR, which will control how long other + servers can cache it. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + All of these TTLs default to units of seconds, though units + can be explicitly specified, for example, <code class="literal">1h30m</code>. + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="ipv4_reverse"></a>Inverse Mapping in IPv4</h3></div></div></div> + + <p> + Reverse name resolution (that is, translation from IP address + to name) is achieved by means of the <span class="emphasis"><em>in-addr.arpa</em></span> domain + and PTR records. Entries in the in-addr.arpa domain are made in + least-to-most significant order, read left to right. This is the + opposite order to the way IP addresses are usually written. Thus, + a machine with an IP address of 10.1.2.3 would have a + corresponding + in-addr.arpa name of + 3.2.1.10.in-addr.arpa. This name should have a PTR resource record + whose data field is the name of the machine or, optionally, + multiple + PTR records if the machine has more than one name. For example, + in the [<span class="optional">example.com</span>] domain: + </p> + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.125in" class="1"> +<col width="4.000in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <code class="literal">$ORIGIN</code> + </p> + </td> +<td> + <p> + <code class="literal">2.1.10.in-addr.arpa</code> + </p> + </td> +</tr> +<tr> +<td> + <p> + <code class="literal">3</code> + </p> + </td> +<td> + <p> + <code class="literal">IN PTR foo.example.com.</code> + </p> + </td> +</tr> +</tbody> +</table> + </div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + The <span class="command"><strong>$ORIGIN</strong></span> lines in the examples + are for providing context to the examples only — they do not + necessarily + appear in the actual usage. They are only used here to indicate + that the example is relative to the listed origin. + </p> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="zone_directives"></a>Other Zone File Directives</h3></div></div></div> + + <p> + The Master File Format was initially defined in RFC 1035 and + has subsequently been extended. While the Master File Format + itself + is class independent all records in a Master File must be of the + same + class. + </p> + <p> + Master File Directives include <span class="command"><strong>$ORIGIN</strong></span>, <span class="command"><strong>$INCLUDE</strong></span>, + and <span class="command"><strong>$TTL.</strong></span> + </p> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="atsign"></a>The <span class="command"><strong>@</strong></span> (at-sign)</h4></div></div></div> + + <p> + When used in the label (or name) field, the asperand or + at-sign (@) symbol represents the current origin. + At the start of the zone file, it is the + <<code class="varname">zone_name</code>> (followed by + trailing dot). + </p> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="origin_directive"></a>The <span class="command"><strong>$ORIGIN</strong></span> Directive</h4></div></div></div> + + <p> + Syntax: <span class="command"><strong>$ORIGIN</strong></span> + <em class="replaceable"><code>domain-name</code></em> + [<span class="optional"><em class="replaceable"><code>comment</code></em></span>] + </p> + <p><span class="command"><strong>$ORIGIN</strong></span> + sets the domain name that will be appended to any + unqualified records. When a zone is first read in there + is an implicit <span class="command"><strong>$ORIGIN</strong></span> + <<code class="varname">zone_name</code>><span class="command"><strong>.</strong></span> + (followed by trailing dot). + The current <span class="command"><strong>$ORIGIN</strong></span> is appended to + the domain specified in the <span class="command"><strong>$ORIGIN</strong></span> + argument if it is not absolute. + </p> + +<pre class="programlisting"> +$ORIGIN example.com. +WWW CNAME MAIN-SERVER +</pre> + + <p> + is equivalent to + </p> + +<pre class="programlisting"> +WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. +</pre> + + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="include_directive"></a>The <span class="command"><strong>$INCLUDE</strong></span> Directive</h4></div></div></div> + + <p> + Syntax: <span class="command"><strong>$INCLUDE</strong></span> + <em class="replaceable"><code>filename</code></em> + [<span class="optional"> +<em class="replaceable"><code>origin</code></em> </span>] + [<span class="optional"> <em class="replaceable"><code>comment</code></em> </span>] + </p> + <p> + Read and process the file <code class="filename">filename</code> as + if it were included into the file at this point. If <span class="command"><strong>origin</strong></span> is + specified the file is processed with <span class="command"><strong>$ORIGIN</strong></span> set + to that value, otherwise the current <span class="command"><strong>$ORIGIN</strong></span> is + used. + </p> + <p> + The origin and the current domain name + revert to the values they had prior to the <span class="command"><strong>$INCLUDE</strong></span> once + the file has been read. + </p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + <p> + RFC 1035 specifies that the current origin should be restored + after + an <span class="command"><strong>$INCLUDE</strong></span>, but it is silent + on whether the current + domain name should also be restored. BIND 9 restores both of + them. + This could be construed as a deviation from RFC 1035, a + feature, or both. + </p> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="ttl_directive"></a>The <span class="command"><strong>$TTL</strong></span> Directive</h4></div></div></div> + + <p> + Syntax: <span class="command"><strong>$TTL</strong></span> + <em class="replaceable"><code>default-ttl</code></em> + [<span class="optional"> +<em class="replaceable"><code>comment</code></em> </span>] + </p> + <p> + Set the default Time To Live (TTL) for subsequent records + with undefined TTLs. Valid TTLs are of the range 0-2147483647 + seconds. + </p> + <p><span class="command"><strong>$TTL</strong></span> + is defined in RFC 2308. + </p> + </div> + </div> + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="generate_directive"></a><acronym class="acronym">BIND</acronym> Master File Extension: the <span class="command"><strong>$GENERATE</strong></span> Directive</h3></div></div></div> + + <p> + Syntax: <span class="command"><strong>$GENERATE</strong></span> + <em class="replaceable"><code>range</code></em> + <em class="replaceable"><code>lhs</code></em> + [<span class="optional"><em class="replaceable"><code>ttl</code></em></span>] + [<span class="optional"><em class="replaceable"><code>class</code></em></span>] + <em class="replaceable"><code>type</code></em> + <em class="replaceable"><code>rhs</code></em> + [<span class="optional"><em class="replaceable"><code>comment</code></em></span>] + </p> + <p><span class="command"><strong>$GENERATE</strong></span> + is used to create a series of resource records that only + differ from each other by an + iterator. <span class="command"><strong>$GENERATE</strong></span> can be used to + easily generate the sets of records required to support + sub /24 reverse delegations described in RFC 2317: + Classless IN-ADDR.ARPA delegation. + </p> + +<pre class="programlisting">$ORIGIN 0.0.192.IN-ADDR.ARPA. +$GENERATE 1-2 @ NS SERVER$.EXAMPLE. +$GENERATE 1-127 $ CNAME $.0</pre> + + <p> + is equivalent to + </p> + +<pre class="programlisting">0.0.0.192.IN-ADDR.ARPA. NS SERVER1.EXAMPLE. +0.0.0.192.IN-ADDR.ARPA. NS SERVER2.EXAMPLE. +1.0.0.192.IN-ADDR.ARPA. CNAME 1.0.0.0.192.IN-ADDR.ARPA. +2.0.0.192.IN-ADDR.ARPA. CNAME 2.0.0.0.192.IN-ADDR.ARPA. +... +127.0.0.192.IN-ADDR.ARPA. CNAME 127.0.0.0.192.IN-ADDR.ARPA. +</pre> + + <p> + Generate a set of A and MX records. Note the MX's right hand + side is a quoted string. The quotes will be stripped when the + right hand side is processed. + </p> + +<pre class="programlisting"> +$ORIGIN EXAMPLE. +$GENERATE 1-127 HOST-$ A 1.2.3.$ +$GENERATE 1-127 HOST-$ MX "0 ."</pre> + + <p> + is equivalent to + </p> + +<pre class="programlisting">HOST-1.EXAMPLE. A 1.2.3.1 +HOST-1.EXAMPLE. MX 0 . +HOST-2.EXAMPLE. A 1.2.3.2 +HOST-2.EXAMPLE. MX 0 . +HOST-3.EXAMPLE. A 1.2.3.3 +HOST-3.EXAMPLE. MX 0 . +... +HOST-127.EXAMPLE. A 1.2.3.127 +HOST-127.EXAMPLE. MX 0 . +</pre> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="0.875in" class="1"> +<col width="4.250in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p><span class="command"><strong>range</strong></span></p> + </td> +<td> + <p> + This can be one of two forms: start-stop + or start-stop/step. If the first form is used, then step + is set to 1. start, stop and step must be positive + integers between 0 and (2^31)-1. start must not be + larger than stop. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>lhs</strong></span></p> + </td> +<td> + <p>This + describes the owner name of the resource records + to be created. Any single <span class="command"><strong>$</strong></span> + (dollar sign) + symbols within the <span class="command"><strong>lhs</strong></span> string + are replaced by the iterator value. + + To get a $ in the output, you need to escape the + <span class="command"><strong>$</strong></span> using a backslash + <span class="command"><strong>\</strong></span>, + e.g. <span class="command"><strong>\$</strong></span>. The + <span class="command"><strong>$</strong></span> may optionally be followed + by modifiers which change the offset from the + iterator, field width and base. + + Modifiers are introduced by a + <span class="command"><strong>{</strong></span> (left brace) immediately following the + <span class="command"><strong>$</strong></span> as + <span class="command"><strong>${offset[,width[,base]]}</strong></span>. + For example, <span class="command"><strong>${-20,3,d}</strong></span> + subtracts 20 from the current value, prints the + result as a decimal in a zero-padded field of + width 3. + + Available output forms are decimal + (<span class="command"><strong>d</strong></span>), octal + (<span class="command"><strong>o</strong></span>), hexadecimal + (<span class="command"><strong>x</strong></span> or <span class="command"><strong>X</strong></span> + for uppercase) and nibble + (<span class="command"><strong>n</strong></span> or <span class="command"><strong>N</strong></span>\ + for uppercase). The default modifier is + <span class="command"><strong>${0,0,d}</strong></span>. If the + <span class="command"><strong>lhs</strong></span> is not absolute, the + current <span class="command"><strong>$ORIGIN</strong></span> is appended + to the name. + </p> + <p> + In nibble mode the value will be treated as + if it was a reversed hexadecimal string + with each hexadecimal digit as a separate + label. The width field includes the label + separator. + </p> + <p> + For compatibility with earlier versions, + <span class="command"><strong>$$</strong></span> is still recognized as + indicating a literal $ in the output. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ttl</strong></span></p> + </td> +<td> + <p> + Specifies the time-to-live of the generated records. If + not specified this will be inherited using the + normal TTL inheritance rules. + </p> + <p><span class="command"><strong>class</strong></span> + and <span class="command"><strong>ttl</strong></span> can be + entered in either order. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>class</strong></span></p> + </td> +<td> + <p> + Specifies the class of the generated records. + This must match the zone class if it is + specified. + </p> + <p><span class="command"><strong>class</strong></span> + and <span class="command"><strong>ttl</strong></span> can be + entered in either order. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>type</strong></span></p> + </td> +<td> + <p> + Any valid type. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>rhs</strong></span></p> + </td> +<td> + <p> + <span class="command"><strong>rhs</strong></span>, optionally, quoted string. + </p> + </td> +</tr> +</tbody> +</table> + </div> + <p> + The <span class="command"><strong>$GENERATE</strong></span> directive is a <acronym class="acronym">BIND</acronym> extension + and not part of the standard zone file format. + </p> + <p> + BIND 8 did not support the optional TTL and CLASS fields. + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="zonefile_format"></a>Additional File Formats</h3></div></div></div> + + <p> + In addition to the standard textual format, BIND 9 + supports the ability to read or dump to zone files in + other formats. + </p> + <p> + The <code class="constant">raw</code> format is + a binary representation of zone data in a manner similar + to that used in zone transfers. Since it does not require + parsing text, load time is significantly reduced. + </p> + <p> + An even faster alternative is the <code class="constant">map</code> + format, which is an image of a <acronym class="acronym">BIND</acronym> 9 + in-memory zone database; it is capable of being loaded + directly into memory via the <span class="command"><strong>mmap()</strong></span> + function; the zone can begin serving queries almost + immediately. + </p> + <p> + For a primary server, a zone file in + <code class="constant">raw</code> or <code class="constant">map</code> + format is expected to be generated from a textual zone + file by the <span class="command"><strong>named-compilezone</strong></span> command. + For a secondary server or for a dynamic zone, it is automatically + generated (if this format is specified by the + <span class="command"><strong>masterfile-format</strong></span> option) when + <span class="command"><strong>named</strong></span> dumps the zone contents after + zone transfer or when applying prior updates. + </p> + <p> + If a zone file in a binary format needs manual modification, + it first must be converted to a textual form by the + <span class="command"><strong>named-compilezone</strong></span> command. All + necessary modification should go to the text file, which + should then be converted to the binary form by the + <span class="command"><strong>named-compilezone</strong></span> command again. + </p> + <p> + Note that <span class="command"><strong>map</strong></span> format is extremely + architecture-specific. A <code class="constant">map</code> + file <span class="emphasis"><em>cannot</em></span> be used on a system + with different pointer size, endianness or data alignment + than the system on which it was generated, and should in + general be used only inside a single system. + While <code class="constant">raw</code> format uses + network byte order and avoids architecture-dependent + data alignment so that it is as portable as + possible, it is also primarily expected to be used + inside the same single system. To export a + zone file in either <code class="constant">raw</code> or + <code class="constant">map</code> format, or make a + portable backup of such a file, conversion to + <code class="constant">text</code> format is recommended. + </p> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="statistics"></a>BIND9 Statistics</h2></div></div></div> + + <p> + <acronym class="acronym">BIND</acronym> 9 maintains lots of statistics + information and provides several interfaces for users to + get access to the statistics. + The available statistics include all statistics counters + that were available in <acronym class="acronym">BIND</acronym> 8 and + are meaningful in <acronym class="acronym">BIND</acronym> 9, + and other information that is considered useful. + </p> + + <p> + The statistics information is categorized into the following + sections. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="3.300in" class="1"> +<col width="2.625in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p>Incoming Requests</p> + </td> +<td> + <p> + The number of incoming DNS requests for each OPCODE. + </p> + </td> +</tr> +<tr> +<td> + <p>Incoming Queries</p> + </td> +<td> + <p> + The number of incoming queries for each RR type. + </p> + </td> +</tr> +<tr> +<td> + <p>Outgoing Queries</p> + </td> +<td> + <p> + The number of outgoing queries for each RR + type sent from the internal resolver. + Maintained per view. + </p> + </td> +</tr> +<tr> +<td> + <p>Name Server Statistics</p> + </td> +<td> + <p> + Statistics counters about incoming request processing. + </p> + </td> +</tr> +<tr> +<td> + <p>Zone Maintenance Statistics</p> + </td> +<td> + <p> + Statistics counters regarding zone maintenance + operations such as zone transfers. + </p> + </td> +</tr> +<tr> +<td> + <p>Resolver Statistics</p> + </td> +<td> + <p> + Statistics counters about name resolution + performed in the internal resolver. + Maintained per view. + </p> + </td> +</tr> +<tr> +<td> + <p>Cache DB RRsets</p> + </td> +<td> + <p> + The number of RRsets per RR type and nonexistent + names stored in the cache database. + If the exclamation mark (!) is printed for a RR + type, it means that particular type of RRset is + known to be nonexistent (this is also known as + "NXRRSET"). If a hash mark (#) is present then + the RRset is marked for garbage collection. + Maintained per view. + </p> + </td> +</tr> +<tr> +<td> + <p>Socket I/O Statistics</p> + </td> +<td> + <p> + Statistics counters about network related events. + </p> + </td> +</tr> +</tbody> +</table> + </div> + + <p> + A subset of Name Server Statistics is collected and shown + per zone for which the server has the authority when + <span class="command"><strong>zone-statistics</strong></span> is set to + <strong class="userinput"><code>full</code></strong> (or <strong class="userinput"><code>yes</code></strong> + for backward compatibility. See the description of + <span class="command"><strong>zone-statistics</strong></span> in <a class="xref" href="Bv9ARM.ch06.html#options" title="options Statement Definition and Usage">the section called “<span class="command"><strong>options</strong></span> Statement Definition and + Usage”</a> + for further details. + </p> + + <p> + These statistics counters are shown with their zone and + view names. The view name is omitted when the server is + not configured with explicit views.</p> + + <p> + There are currently two user interfaces to get access to the + statistics. + One is in the plain text format dumped to the file specified + by the <span class="command"><strong>statistics-file</strong></span> configuration option. + The other is remotely accessible via a statistics channel + when the <span class="command"><strong>statistics-channels</strong></span> statement + is specified in the configuration file + (see <a class="xref" href="Bv9ARM.ch06.html#statschannels" title="statistics-channels Statement Grammar">the section called “<span class="command"><strong>statistics-channels</strong></span> Statement Grammar”</a>.) + </p> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="statsfile"></a>The Statistics File</h3></div></div></div> + + <p> + The text format statistics dump begins with a line, like: + </p> + <p> + <span class="command"><strong>+++ Statistics Dump +++ (973798949)</strong></span> + </p> + <p> + The number in parentheses is a standard + Unix-style timestamp, measured as seconds since January 1, 1970. + + Following + that line is a set of statistics information, which is categorized + as described above. + Each section begins with a line, like: + </p> + + <p> + <span class="command"><strong>++ Name Server Statistics ++</strong></span> + </p> + + <p> + Each section consists of lines, each containing the statistics + counter value followed by its textual description. + See below for available counters. + For brevity, counters that have a value of 0 are not shown + in the statistics file. + </p> + + <p> + The statistics dump ends with the line where the + number is identical to the number in the beginning line; for example: + </p> + <p> + <span class="command"><strong>--- Statistics Dump --- (973798949)</strong></span> + </p> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="statistics_counters"></a>Statistics Counters</h3></div></div></div> + + <p> + The following tables summarize statistics counters that + <acronym class="acronym">BIND</acronym> 9 provides. + For each row of the tables, the leftmost column is the + abbreviated symbol name of that counter. + These symbols are shown in the statistics information + accessed via an HTTP statistics channel. + The rightmost column gives the description of the counter, + which is also shown in the statistics file + (but, in this document, possibly with slight modification + for better readability). + Additional notes may also be provided in this column. + When a middle column exists between these two columns, + it gives the corresponding counter name of the + <acronym class="acronym">BIND</acronym> 8 statistics, if applicable. + </p> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="stats_counters"></a>Name Server Statistics Counters</h4></div></div></div> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="1.150in" class="2"> +<col width="3.350in" class="3"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>BIND8 Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>Description</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Requestv4</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RQ</strong></span></p> + </td> +<td> + <p> + IPv4 requests received. + Note: this also counts non query requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Requestv6</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RQ</strong></span></p> + </td> +<td> + <p> + IPv6 requests received. + Note: this also counts non query requests. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqEdns0</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with EDNS(0) received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqBadEDNSVer</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with unsupported EDNS version received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqTSIG</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with TSIG received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqSIG0</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with SIG(0) received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqBadSIG</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requests with invalid (TSIG or SIG(0)) signature. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ReqTCP</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RTCP</strong></span></p> + </td> +<td> + <p> + TCP requests received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>AuthQryRej</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RUQ</strong></span></p> + </td> +<td> + <p> + Authoritative (non recursive) queries rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RecQryRej</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RURQ</strong></span></p> + </td> +<td> + <p> + Recursive queries rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>XfrRej</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RUXFR</strong></span></p> + </td> +<td> + <p> + Zone transfer requests rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateRej</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RUUpd</strong></span></p> + </td> +<td> + <p> + Dynamic update requests rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Response</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SAns</strong></span></p> + </td> +<td> + <p> + Responses sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RespTruncated</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Truncated responses sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RespEDNS0</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses with EDNS(0) sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RespTSIG</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses with TSIG sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RespSIG0</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses with SIG(0) sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QrySuccess</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in a successful answer. + This means the query which returns a NOERROR response + with at least one answer RR. + This corresponds to the + <span class="command"><strong>success</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryAuthAns</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in authoritative answer. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNoauthAns</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SNaAns</strong></span></p> + </td> +<td> + <p> + Queries resulted in non authoritative answer. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryReferral</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in referral answer. + This corresponds to the + <span class="command"><strong>referral</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNxrrset</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in NOERROR responses with no data. + This corresponds to the + <span class="command"><strong>nxrrset</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QrySERVFAIL</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SFail</strong></span></p> + </td> +<td> + <p> + Queries resulted in SERVFAIL. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryFORMERR</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SFErr</strong></span></p> + </td> +<td> + <p> + Queries resulted in FORMERR. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNXDOMAIN</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SNXD</strong></span></p> + </td> +<td> + <p> + Queries resulted in NXDOMAIN. + This corresponds to the + <span class="command"><strong>nxdomain</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryRecursion</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RFwdQ</strong></span></p> + </td> +<td> + <p> + Queries which caused the server + to perform recursion in order to find the final answer. + This corresponds to the + <span class="command"><strong>recursion</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryDuplicate</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RDupQ</strong></span></p> + </td> +<td> + <p> + Queries which the server attempted to + recurse but discovered an existing query with the same + IP address, port, query ID, name, type and class + already being processed. + This corresponds to the + <span class="command"><strong>duplicate</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryDropped</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Recursive queries for which the server + discovered an excessive number of existing + recursive queries for the same name, type and + class and were subsequently dropped. + This is the number of dropped queries due to + the reason explained with the + <span class="command"><strong>clients-per-query</strong></span> + and + <span class="command"><strong>max-clients-per-query</strong></span> + options + (see the description about + <a class="xref" href="Bv9ARM.ch06.html#clients-per-query"><span class="command"><strong>clients-per-query</strong></span></a>.) + This corresponds to the + <span class="command"><strong>dropped</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryFailure</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Other query failures. + This corresponds to the + <span class="command"><strong>failure</strong></span> counter + of previous versions of + <acronym class="acronym">BIND</acronym> 9. + Note: this counter is provided mainly for + backward compatibility with the previous versions. + Normally a more fine-grained counters such as + <span class="command"><strong>AuthQryRej</strong></span> and + <span class="command"><strong>RecQryRej</strong></span> + that would also fall into this counter are provided, + and so this counter would not be of much + interest in practice. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNXRedir</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in NXDOMAIN that were redirected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryNXRedirRLookup</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries resulted in NXDOMAIN that were redirected + and resulted in a successful remote lookup. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>XfrReqDone</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Requested zone transfers completed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateReqFwd</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Update requests forwarded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateRespFwd</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Update responses forwarded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateFwdFail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Dynamic update forward failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateDone</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Dynamic updates completed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateFail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Dynamic updates failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>UpdateBadPrereq</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Dynamic updates rejected due to prerequisite failure. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RateDropped</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses dropped by rate limits. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RateSlipped</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Responses truncated by rate limits. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>RPZRewrites</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Response policy zone rewrites. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="zone_stats"></a>Zone Maintenance Statistics Counters</h4></div></div></div> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="3.350in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>Description</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyOutv4</strong></span></p> + </td> +<td> + <p> + IPv4 notifies sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyOutv6</strong></span></p> + </td> +<td> + <p> + IPv6 notifies sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyInv4</strong></span></p> + </td> +<td> + <p> + IPv4 notifies received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyInv6</strong></span></p> + </td> +<td> + <p> + IPv6 notifies received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NotifyRej</strong></span></p> + </td> +<td> + <p> + Incoming notifies rejected. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>SOAOutv4</strong></span></p> + </td> +<td> + <p> + IPv4 SOA queries sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>SOAOutv6</strong></span></p> + </td> +<td> + <p> + IPv6 SOA queries sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>AXFRReqv4</strong></span></p> + </td> +<td> + <p> + IPv4 AXFR requested. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>AXFRReqv6</strong></span></p> + </td> +<td> + <p> + IPv6 AXFR requested. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>IXFRReqv4</strong></span></p> + </td> +<td> + <p> + IPv4 IXFR requested. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>IXFRReqv6</strong></span></p> + </td> +<td> + <p> + IPv6 IXFR requested. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>XfrSuccess</strong></span></p> + </td> +<td> + <p> + Zone transfer requests succeeded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>XfrFail</strong></span></p> + </td> +<td> + <p> + Zone transfer requests failed. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="resolver_stats"></a>Resolver Statistics Counters</h4></div></div></div> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="1.150in" class="2"> +<col width="3.350in" class="3"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>BIND8 Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>Description</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Queryv4</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SFwdQ</strong></span></p> + </td> +<td> + <p> + IPv4 queries sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Queryv6</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SFwdQ</strong></span></p> + </td> +<td> + <p> + IPv6 queries sent. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Responsev4</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RR</strong></span></p> + </td> +<td> + <p> + IPv4 responses received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Responsev6</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RR</strong></span></p> + </td> +<td> + <p> + IPv6 responses received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>NXDOMAIN</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RNXD</strong></span></p> + </td> +<td> + <p> + NXDOMAIN received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>SERVFAIL</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RFail</strong></span></p> + </td> +<td> + <p> + SERVFAIL received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>FORMERR</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RFErr</strong></span></p> + </td> +<td> + <p> + FORMERR received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>OtherError</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RErr</strong></span></p> + </td> +<td> + <p> + Other errors received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>EDNS0Fail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + EDNS(0) query failures. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Mismatch</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RDupR</strong></span></p> + </td> +<td> + <p> + Mismatch responses received. + The DNS ID, response's source address, + and/or the response's source port does not + match what was expected. + (The port must be 53 or as defined by + the <span class="command"><strong>port</strong></span> option.) + This may be an indication of a cache + poisoning attempt. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Truncated</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Truncated responses received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Lame</strong></span></p> + </td> +<td> + <p><span class="command"><strong>RLame</strong></span></p> + </td> +<td> + <p> + Lame delegations received. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>Retry</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SDupQ</strong></span></p> + </td> +<td> + <p> + Query retries performed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QueryAbort</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Queries aborted due to quota control. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QuerySockFail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Failures in opening query sockets. + One common reason for such failures is a + failure of opening a new socket due to a + limitation on file descriptors. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QueryTimeout</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Query timeouts. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>GlueFetchv4</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SSysQ</strong></span></p> + </td> +<td> + <p> + IPv4 NS address fetches invoked. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>GlueFetchv6</strong></span></p> + </td> +<td> + <p><span class="command"><strong>SSysQ</strong></span></p> + </td> +<td> + <p> + IPv6 NS address fetches invoked. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>GlueFetchv4Fail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + IPv4 NS address fetch failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>GlueFetchv6Fail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + IPv6 NS address fetch failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ValAttempt</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + DNSSEC validation attempted. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ValOk</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + DNSSEC validation succeeded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ValNegOk</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + DNSSEC validation on negative information succeeded. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>ValFail</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + DNSSEC validation failed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong>QryRTTnn</strong></span></p> + </td> +<td> + <p><span class="command"><strong></strong></span></p> + </td> +<td> + <p> + Frequency table on round trip times (RTTs) of + queries. + Each <span class="command"><strong>nn</strong></span> specifies the corresponding + frequency. + In the sequence of + <span class="command"><strong>nn_1</strong></span>, + <span class="command"><strong>nn_2</strong></span>, + ..., + <span class="command"><strong>nn_m</strong></span>, + the value of <span class="command"><strong>nn_i</strong></span> is the + number of queries whose RTTs are between + <span class="command"><strong>nn_(i-1)</strong></span> (inclusive) and + <span class="command"><strong>nn_i</strong></span> (exclusive) milliseconds. + For the sake of convenience we define + <span class="command"><strong>nn_0</strong></span> to be 0. + The last entry should be represented as + <span class="command"><strong>nn_m+</strong></span>, which means the + number of queries whose RTTs are equal to or over + <span class="command"><strong>nn_m</strong></span> milliseconds. + </p> + </td> +</tr> +</tbody> +</table> + </div> + + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="socket_stats"></a>Socket I/O Statistics Counters</h4></div></div></div> + + <p> + Socket I/O statistics counters are defined per socket + types, which are + <span class="command"><strong>UDP4</strong></span> (UDP/IPv4), + <span class="command"><strong>UDP6</strong></span> (UDP/IPv6), + <span class="command"><strong>TCP4</strong></span> (TCP/IPv4), + <span class="command"><strong>TCP6</strong></span> (TCP/IPv6), + <span class="command"><strong>Unix</strong></span> (Unix Domain), and + <span class="command"><strong>FDwatch</strong></span> (sockets opened outside the + socket module). + In the following table <span class="command"><strong><TYPE></strong></span> + represents a socket type. + Not all counters are available for all socket types; + exceptions are noted in the description field. + </p> + + <div class="informaltable"> + <table border="1"> +<colgroup> +<col width="1.150in" class="1"> +<col width="3.350in" class="2"> +</colgroup> +<tbody> +<tr> +<td> + <p> + <span class="emphasis"><em>Symbol</em></span> + </p> + </td> +<td> + <p> + <span class="emphasis"><em>Description</em></span> + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>Open</strong></span></p> + </td> +<td> + <p> + Sockets opened successfully. + This counter is not applicable to the + <span class="command"><strong>FDwatch</strong></span> type. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>OpenFail</strong></span></p> + </td> +<td> + <p> + Failures of opening sockets. + This counter is not applicable to the + <span class="command"><strong>FDwatch</strong></span> type. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>Close</strong></span></p> + </td> +<td> + <p> + Sockets closed. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>BindFail</strong></span></p> + </td> +<td> + <p> + Failures of binding sockets. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>ConnFail</strong></span></p> + </td> +<td> + <p> + Failures of connecting sockets. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>Conn</strong></span></p> + </td> +<td> + <p> + Connections established successfully. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>AcceptFail</strong></span></p> + </td> +<td> + <p> + Failures of accepting incoming connection requests. + This counter is not applicable to the + <span class="command"><strong>UDP</strong></span> and + <span class="command"><strong>FDwatch</strong></span> types. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>Accept</strong></span></p> + </td> +<td> + <p> + Incoming connections successfully accepted. + This counter is not applicable to the + <span class="command"><strong>UDP</strong></span> and + <span class="command"><strong>FDwatch</strong></span> types. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>SendErr</strong></span></p> + </td> +<td> + <p> + Errors in socket send operations. + This counter corresponds + to <span class="command"><strong>SErr</strong></span> counter of + <span class="command"><strong>BIND</strong></span> 8. + </p> + </td> +</tr> +<tr> +<td> + <p><span class="command"><strong><TYPE>RecvErr</strong></span></p> + </td> +<td> + <p> + Errors in socket receive operations. + This includes errors of send operations on a + connected UDP socket notified by an ICMP error + message. + </p> + </td> +</tr> +</tbody> +</table> + </div> + </div> + + <div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bind8_compatibility"></a>Compatibility with <span class="emphasis"><em>BIND</em></span> 8 Counters</h4></div></div></div> + + <p> + Most statistics counters that were available + in <span class="command"><strong>BIND</strong></span> 8 are also supported in + <span class="command"><strong>BIND</strong></span> 9 as shown in the above tables. + Here are notes about other counters that do not appear + in these tables. + </p> + + <div class="variablelist"><dl class="variablelist"> +<dt><span class="term"><span class="command"><strong>RFwdR,SFwdR</strong></span></span></dt> +<dd> + <p> + These counters are not supported + because <span class="command"><strong>BIND</strong></span> 9 does not adopt + the notion of <span class="emphasis"><em>forwarding</em></span> + as <span class="command"><strong>BIND</strong></span> 8 did. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RAXFR</strong></span></span></dt> +<dd> + <p> + This counter is accessible in the Incoming Queries section. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>RIQ</strong></span></span></dt> +<dd> + <p> + This counter is accessible in the Incoming Requests section. + </p> + </dd> +<dt><span class="term"><span class="command"><strong>ROpts</strong></span></span></dt> +<dd> + <p> + This counter is not supported + because <span class="command"><strong>BIND</strong></span> 9 does not care + about IP options in the first place. + </p> + </dd> +</dl></div> + </div> + </div> + </div> + + </div> +<div class="navfooter"> +<hr> +<table width="100%" summary="Navigation footer"> +<tr> +<td width="40%" align="left"> +<a accesskey="p" href="Bv9ARM.ch05.html">Prev</a> </td> +<td width="20%" align="center"> </td> +<td width="40%" align="right"> <a accesskey="n" href="Bv9ARM.ch07.html">Next</a> +</td> +</tr> +<tr> +<td width="40%" align="left" valign="top">Chapter 5. The <acronym class="acronym">BIND</acronym> 9 Lightweight Resolver </td> +<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td> +<td width="40%" align="right" valign="top"> Chapter 7. <acronym class="acronym">BIND</acronym> 9 Security Considerations</td> +</tr> +</table> +</div> +<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.11.5-P4 (Extended Support Version)</p> +</body> +</html> |