diff options
Diffstat (limited to 'contrib/bind9/doc/arm/Bv9ARM-book.xml')
| -rw-r--r-- | contrib/bind9/doc/arm/Bv9ARM-book.xml | 2041 |
1 files changed, 1785 insertions, 256 deletions
diff --git a/contrib/bind9/doc/arm/Bv9ARM-book.xml b/contrib/bind9/doc/arm/Bv9ARM-book.xml index 0013c2e7f689..c3517843175d 100644 --- a/contrib/bind9/doc/arm/Bv9ARM-book.xml +++ b/contrib/bind9/doc/arm/Bv9ARM-book.xml @@ -2,7 +2,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004-2010 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004-2011 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000-2003 Internet Software Consortium. - - Permission to use, copy, modify, and/or distribute this software for any @@ -18,7 +18,7 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- File: $Id: Bv9ARM-book.xml,v 1.380.14.28 2010-08-20 01:38:26 marka Exp $ --> +<!-- File: $Id: Bv9ARM-book.xml,v 1.478.8.2.2.1 2011-06-09 03:17:11 marka Exp $ --> <book xmlns:xi="http://www.w3.org/2001/XInclude"> <title>BIND 9 Administrator Reference Manual</title> @@ -31,6 +31,7 @@ <year>2008</year> <year>2009</year> <year>2010</year> + <year>2011</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -69,7 +70,7 @@ </para> <para> - This version of the manual corresponds to BIND version 9.6. + This version of the manual corresponds to BIND version 9.7. </para> </sect1> @@ -644,9 +645,9 @@ <para> ISC <acronym>BIND</acronym> 9 compiles and runs on a large number - of Unix-like operating systems and on NT-derived versions of - Microsoft Windows such as Windows 2000 and Windows XP. For an - up-to-date + of Unix-like operating systems and on + Microsoft Windows Server 2003 and 2008, and Windows XP and Vista. + For an up-to-date list of supported systems, see the README file in the top level directory of the BIND 9 source distribution. @@ -680,10 +681,13 @@ // Two corporate subnets we wish to allow queries from. acl corpnets { 192.168.4.0/24; 192.168.7.0/24; }; options { - directory "/etc/namedb"; // Working directory + // Working directory + directory "/etc/namedb"; + allow-query { corpnets; }; }; -// Provide a reverse mapping for the loopback address 127.0.0.1 +// Provide a reverse mapping for the loopback +// address 127.0.0.1 zone "0.0.127.in-addr.arpa" { type master; file "localhost.rev"; @@ -703,13 +707,18 @@ zone "0.0.127.in-addr.arpa" { <programlisting> options { - directory "/etc/namedb"; // Working directory - allow-query-cache { none; }; // Do not allow access to cache - allow-query { any; }; // This is the default - recursion no; // Do not provide recursive service + // Working directory + directory "/etc/namedb"; + // Do not allow access to cache + allow-query-cache { none; }; + // This is the default + allow-query { any; }; + // Do not provide recursive service + recursion no; }; -// Provide a reverse mapping for the loopback address 127.0.0.1 +// Provide a reverse mapping for the loopback +// address 127.0.0.1 zone "0.0.127.in-addr.arpa" { type master; file "localhost.rev"; @@ -719,7 +728,8 @@ zone "0.0.127.in-addr.arpa" { zone "example.com" { type master; file "example.com.db"; - // IP addresses of slave servers allowed to transfer example.com + // IP addresses of slave servers allowed to + // transfer example.com allow-transfer { 192.168.4.14; 192.168.5.53; @@ -881,7 +891,7 @@ zone "eng.example.com" { </para> <para> For more detail on ordering responses, check the - <command>rrset-order</command> substatement in the + <command>rrset-order</command> sub-statement in the <command>options</command> statement, see <xref endterm="rrset_ordering_title" linkend="rrset_ordering"/>. </para> @@ -1162,7 +1172,62 @@ zone "eng.example.com" { </varlistentry> <varlistentry> + <term><userinput>sign <replaceable>zone</replaceable> + <optional><replaceable>class</replaceable> + <optional><replaceable>view</replaceable></optional></optional></userinput></term> + <listitem> + <para> + Fetch all DNSSEC keys for the given zone + from the key directory (see + <command>key-directory</command> in + <xref linkend="options"/>). If they are within + their publication period, merge them into the + zone's DNSKEY RRset. If the DNSKEY RRset + is changed, then the zone is automatically + re-signed with the new key set. + </para> + <para> + This command requires that the + <command>auto-dnssec</command> zone option to be set + to <literal>allow</literal>, + <literal>maintain</literal>, or + <literal>create</literal>, and also requires + the zone to be configured to allow dynamic DNS. + See <xref linkend="dynamic_update_policies"/> for + more details. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>loadkeys <replaceable>zone</replaceable> + <optional><replaceable>class</replaceable> + <optional><replaceable>view</replaceable></optional></optional></userinput></term> + <listitem> + <para> + Fetch all DNSSEC keys for the given zone + from the key directory (see + <command>key-directory</command> in + <xref linkend="options"/>). If they are within + their publication period, merge them into the + zone's DNSKEY RRset. Unlike <command>rndc + sign</command>, however, the zone is not + immediately re-signed by the new keys, but is + allowed to incrementally re-sign over time. + </para> + <para> + This command requires that the + <command>auto-dnssec</command> zone option to + be set to <literal>maintain</literal> or + <literal>create</literal>, and also requires + the zone to be configured to allow dynamic DNS. + See <xref linkend="dynamic_update_policies"/> for + more details. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><userinput>freeze <optional><replaceable>zone</replaceable> <optional><replaceable>class</replaceable> @@ -1271,6 +1336,19 @@ zone "eng.example.com" { </varlistentry> <varlistentry> + <term><userinput>secroots + <optional><replaceable>view ...</replaceable></optional></userinput></term> + <listitem> + <para> + Dump the server's security roots to the secroots + file for the specified views. If no view is + specified, security roots for all + views are dumped. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><userinput>stop <optional>-p</optional></userinput></term> <listitem> <para> @@ -1383,6 +1461,65 @@ zone "eng.example.com" { </listitem> </varlistentry> + <varlistentry> + <term><userinput>addzone + <replaceable>zone</replaceable> + <optional><replaceable>class</replaceable> + <optional><replaceable>view</replaceable></optional></optional> + <replaceable>configuration</replaceable> + </userinput></term> + <listitem> + <para> + Add a zone while the server is running. This + command requires the + <command>allow-new-zones</command> option to be set + to <userinput>yes</userinput>. The + <replaceable>configuration</replaceable> string + specified on the command line is the zone + configuration text that would ordinarily be + placed in <filename>named.conf</filename>. + </para> + <para> + The configuration is saved in a file called + <filename><replaceable>hash</replaceable>.nzf</filename>, + where <replaceable>hash</replaceable> is a + cryptographic hash generated from the name of + the view. When <command>named</command> is + restarted, the file will be loaded into the view + configuration, so that zones that were added + can persist after a restart. + </para> + <para> + This sample <command>addzone</command> command + would add the zone <literal>example.com</literal> + to the default view: + </para> + <para> +<prompt>$ </prompt><userinput>rndc addzone example.com '{ type master; file "example.com.db"; };'</userinput> + </para> + <para> + (Note the brackets and semi-colon around the zone + configuration text.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>delzone + <replaceable>zone</replaceable> + <optional><replaceable>class</replaceable> + <optional><replaceable>view</replaceable></optional></optional> + </userinput></term> + <listitem> + <para> + Delete a zone while the server is running. + Only zones that were originally added via + <command>rndc addzone</command> can be deleted + in this matter. + </para> + </listitem> + </varlistentry> + </variablelist> <para> @@ -1488,7 +1625,8 @@ zone "eng.example.com" { <programlisting> key rndc_key { algorithm "hmac-md5"; - secret "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K"; + secret + "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K"; }; options { default-server 127.0.0.1; @@ -1514,7 +1652,8 @@ options { <programlisting> controls { - inet 127.0.0.1 allow { localhost; } keys { rndc_key; }; + inet 127.0.0.1 + allow { localhost; } keys { rndc_key; }; }; </programlisting> @@ -1641,14 +1780,27 @@ controls { <para> Dynamic update is enabled by including an - <command>allow-update</command> or <command>update-policy</command> - clause in the <command>zone</command> statement. The - <command>tkey-gssapi-credential</command> and - <command>tkey-domain</command> clauses in the - <command>options</command> statement enable the - server to negotiate keys that can be matched against those - in <command>update-policy</command> or - <command>allow-update</command>. + <command>allow-update</command> or an <command>update-policy</command> + clause in the <command>zone</command> statement. + </para> + + <para> + If the zone's <command>update-policy</command> is set to + <userinput>local</userinput>, updates to the zone + will be permitted for the key <varname>local-ddns</varname>, + which will be generated by <command>named</command> at startup. + See <xref linkend="dynamic_update_policies"/> for more details. + </para> + + <para> + Dynamic updates using Kerberos signed requests can be made + using the TKEY/GSS protocol by setting either the + <command>tkey-gssapi-keytab</command> option, or alternatively + by setting both the <command>tkey-gssapi-credential</command> + and <command>tkey-domain</command> options. Once enabled, + Kerberos signed requests will be matched against the update + policies for the zone, using the Kerberos principal as the + signer for the request. </para> <para> @@ -1660,7 +1812,7 @@ controls { </para> <sect2 id="journal"> - <title>The journal file</title> + <title>The journal file</title> <para> All changes made to a zone using dynamic update are stored @@ -1814,7 +1966,7 @@ controls { and <filename>site2.example.com</filename>, to the servers in the DMZ. These internal servers will have complete sets of information - for <filename>site1.example.com</filename>, <filename>site2.example.com</filename>,<emphasis/> <filename>site1.internal</filename>, + for <filename>site1.example.com</filename>, <filename>site2.example.com</filename>, <filename>site1.internal</filename>, and <filename>site2.internal</filename>. </para> <para> @@ -1927,26 +2079,32 @@ options { ... ... forward only; - forwarders { // forward to external servers + // forward to external servers + forwarders { <varname>bastion-ips-go-here</varname>; }; - allow-transfer { none; }; // sample allow-transfer (no one) - allow-query { internals; externals; }; // restrict query access - allow-recursion { internals; }; // restrict recursion + // sample allow-transfer (no one) + allow-transfer { none; }; + // restrict query access + allow-query { internals; externals; }; + // restrict recursion + allow-recursion { internals; }; ... ... }; -zone "site1.example.com" { // sample master zone +// sample master zone +zone "site1.example.com" { type master; file "m/site1.example.com"; - forwarders { }; // do normal iterative - // resolution (do not forward) + // do normal iterative resolution (do not forward) + forwarders { }; allow-query { internals; externals; }; allow-transfer { internals; }; }; -zone "site2.example.com" { // sample slave zone +// sample slave zone +zone "site2.example.com" { type slave; file "s/site2.example.com"; masters { 172.16.72.3; }; @@ -1985,15 +2143,20 @@ acl externals { bastion-ips-go-here; }; options { ... ... - allow-transfer { none; }; // sample allow-transfer (no one) - allow-query { any; }; // default query access - allow-query-cache { internals; externals; }; // restrict cache access - allow-recursion { internals; externals; }; // restrict recursion + // sample allow-transfer (no one) + allow-transfer { none; }; + // default query access + allow-query { any; }; + // restrict cache access + allow-query-cache { internals; externals; }; + // restrict recursion + allow-recursion { internals; externals; }; ... ... }; -zone "site1.example.com" { // sample slave zone +// sample slave zone +zone "site1.example.com" { type master; file "m/site1.foo.com"; allow-transfer { internals; externals; }; @@ -2187,9 +2350,8 @@ allow-update { key host1-host2. ;}; </para> <para> - You may want to read about the more powerful - <command>update-policy</command> statement in - <xref linkend="dynamic_update_policies"/>. + See <xref linkend="dynamic_update_policies"/> for a discussion of + the more flexible <command>update-policy</command> statement. </para> </sect2> @@ -2453,12 +2615,23 @@ allow-update { key host1-host2. ;}; <para> To enable <command>named</command> to validate answers from - other servers, the <command>dnssec-enable</command> and - <command>dnssec-validation</command> options must both be - set to yes (the default setting in <acronym>BIND</acronym> 9.5 - and later), and at least one trust anchor must be configured - with a <command>trusted-keys</command> statement in - <filename>named.conf</filename>. + other servers, the <command>dnssec-enable</command> option + must be set to <userinput>yes</userinput>, and the + <command>dnssec-validation</command> options must be set to + <userinput>yes</userinput> or <userinput>auto</userinput>. + </para> + + <para> + If <command>dnssec-validation</command> is set to + <userinput>auto</userinput>, then a default + trust anchor for the DNS root zone will be used. + If it is set to <userinput>yes</userinput>, however, + then at least one trust anchor must be configured + with a <command>trusted-keys</command> or + <command>managed-keys</command> statement in + <filename>named.conf</filename>, or DNSSEC validation + will not occur. The default setting is + <userinput>yes</userinput>. </para> <para> @@ -2471,7 +2644,14 @@ allow-update { key host1-host2. ;}; </para> <para> - <command>trusted-keys</command> are described in more detail + <command>managed-keys</command> are trusted keys which are + automatically kept up to date via RFC 5011 trust anchor + maintenance. + </para> + + <para> + <command>trusted-keys</command> and + <command>managed-keys</command> are described in more detail later in this document. </para> @@ -2484,45 +2664,59 @@ allow-update { key host1-host2. ;}; <para> After DNSSEC gets established, a typical DNSSEC configuration - will look something like the following. It has a one or + will look something like the following. It has one or more public keys for the root. This allows answers from outside the organization to be validated. It will also have several keys for parts of the namespace the organization - controls. These are here to ensure that <command>named</command> is immune - to compromises in the DNSSEC components of the security - of parent zones. + controls. These are here to ensure that <command>named</command> + is immune to compromises in the DNSSEC components of the security + of parent zones. </para> <programlisting> -trusted-keys { - +managed-keys { /* Root Key */ -"." 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwSJxrGkxJWoZu6I7PzJu/ - E9gx4UC1zGAHlXKdE4zYIpRhaBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3 - zy2Xy4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYghf+6fElrmLkdaz - MQ2OCnACR817DF4BBa7UR/beDHyp5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M - /lUUVRbkeg1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq66gKodQj+M - iA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ97S+LKUTpQcq27R7AT3/V5hRQxScI - Nqwcz4jYqZD2fQdgxbcDTClU0CRBdiieyLMNzXG3"; - -/* Key for our organization's forward zone */ -example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM65KbhTjrW1ZaARmPhEZZe - 3Y9ifgEuq7vZ/zGZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb4JKUbb - OTcM8pwXlj0EiX3oDFVmjHO444gLkBO UKUf/mC7HvfwYH/Be22GnC - lrinKJp1Og4ywzO9WglMk7jbfW33gUKvirTHr25GL7STQUzBb5Usxt - 8lgnyTUHs1t3JwCY5hKZ6CqFxmAVZP20igTixin/1LcrgX/KMEGd/b - iuvF4qJCyduieHukuY3H4XMAcR+xia2 nIUPvm/oyWR8BW/hWdzOvn - SCThlHf3xiYleDbt/o1OTQ09A0="; - -/* Key for our reverse zone. */ -2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwcxOdNax071L18QqZnQQQA - VVr+iLhGTnNGp3HoWQLUIzKrJVZ3zggy3WwNT6kZo6c0 - tszYqbtvchmgQC8CzKojM/W16i6MG/ea fGU3siaOdS0 - yOI6BgPsw+YZdzlYMaIJGf4M4dyoKIhzdZyQ2bYQrjyQ - 4LB0lC7aOnsMyYKHHYeRv PxjIQXmdqgOJGq+vsevG06 - zW+1xgYJh9rCIfnm1GX/KMgxLPG2vXTD/RnLX+D3T3UL - 7HJYHJhAZD5L59VvjSPsZJHeDCUyWYrvPZesZDIRvhDD - 52SKvbheeTJUm6EhkzytNN2SN96QRk8j/iI8ib"; + "." initial-key 257 3 3 "BNY4wrWM1nCfJ+CXd0rVXyYmobt7sEEfK3clRbGaTwS + JxrGkxJWoZu6I7PzJu/E9gx4UC1zGAHlXKdE4zYIpRh + aBKnvcC2U9mZhkdUpd1Vso/HAdjNe8LmMlnzY3zy2Xy + 4klWOADTPzSv9eamj8V18PHGjBLaVtYvk/ln5ZApjYg + hf+6fElrmLkdaz MQ2OCnACR817DF4BBa7UR/beDHyp + 5iWTXWSi6XmoJLbG9Scqc7l70KDqlvXR3M/lUUVRbke + g1IPJSidmK3ZyCllh4XSKbje/45SKucHgnwU5jefMtq + 66gKodQj+MiA21AfUVe7u99WzTLzY3qlxDhxYQQ20FQ + 97S+LKUTpQcq27R7AT3/V5hRQxScINqwcz4jYqZD2fQ + dgxbcDTClU0CRBdiieyLMNzXG3"; +}; + +trusted-keys { + /* Key for our organization's forward zone */ + example.com. 257 3 5 "AwEAAaxPMcR2x0HbQV4WeZB6oEDX+r0QM6 + 5KbhTjrW1ZaARmPhEZZe3Y9ifgEuq7vZ/z + GZUdEGNWy+JZzus0lUptwgjGwhUS1558Hb + 4JKUbbOTcM8pwXlj0EiX3oDFVmjHO444gL + kBOUKUf/mC7HvfwYH/Be22GnClrinKJp1O + g4ywzO9WglMk7jbfW33gUKvirTHr25GL7S + TQUzBb5Usxt8lgnyTUHs1t3JwCY5hKZ6Cq + FxmAVZP20igTixin/1LcrgX/KMEGd/biuv + F4qJCyduieHukuY3H4XMAcR+xia2nIUPvm + /oyWR8BW/hWdzOvnSCThlHf3xiYleDbt/o + 1OTQ09A0="; + + /* Key for our reverse zone. */ + 2.0.192.IN-ADDRPA.NET. 257 3 5 "AQOnS4xn/IgOUpBPJ3bogzwc + xOdNax071L18QqZnQQQAVVr+i + LhGTnNGp3HoWQLUIzKrJVZ3zg + gy3WwNT6kZo6c0tszYqbtvchm + gQC8CzKojM/W16i6MG/eafGU3 + siaOdS0yOI6BgPsw+YZdzlYMa + IJGf4M4dyoKIhzdZyQ2bYQrjy + Q4LB0lC7aOnsMyYKHHYeRvPxj + IQXmdqgOJGq+vsevG06zW+1xg + YJh9rCIfnm1GX/KMgxLPG2vXT + D/RnLX+D3T3UL7HJYHJhAZD5L + 59VvjSPsZJHeDCUyWYrvPZesZ + DIRvhDD52SKvbheeTJUm6Ehkz + ytNN2SN96QRk8j/iI8ib"; }; options { @@ -2575,6 +2769,13 @@ options { </sect2> </sect1> + + <xi:include href="dnssec.xml"/> + + <xi:include href="managed-keys.xml"/> + + <xi:include href="pkcs11.xml"/> + <sect1> <title>IPv6 Support in <acronym>BIND</acronym> 9</title> @@ -2653,7 +2854,8 @@ host 3600 IN AAAA 2001:db8::1 <programlisting> $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. -1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0 14400 IN PTR host.example.com. +1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0 14400 IN PTR ( + host.example.com. ) </programlisting> </sect2> @@ -2831,6 +3033,19 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. <row rowsep="0"> <entry colname="1"> <para> + <varname>namelist</varname> + </para> + </entry> + <entry colname="2"> + <para> + A list of one or more <varname>domain_name</varname> + elements. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> <varname>dotted_decimal</varname> </para> </entry> @@ -3224,7 +3439,8 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. <para> <programlisting>/* This is a <acronym>BIND</acronym> comment as in C */</programlisting> <programlisting>// This is a <acronym>BIND</acronym> comment as in C++</programlisting> - <programlisting># This is a <acronym>BIND</acronym> comment as in common UNIX shells and perl</programlisting> + <programlisting># This is a <acronym>BIND</acronym> comment as in common UNIX shells +# and perl</programlisting> </para> </sect3> <sect3> @@ -3439,6 +3655,17 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. </row> <row rowsep="0"> <entry colname="1"> + <para><command>managed-keys</command></para> + </entry> + <entry colname="2"> + <para> + lists DNSSEC keys to be kept up to date + using RFC 5011 trust anchor maintenance. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> <para><command>view</command></para> </entry> <entry colname="2"> @@ -3559,10 +3786,12 @@ $ORIGIN 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa. <title><command>controls</command> Statement Grammar</title> <programlisting><command>controls</command> { - [ inet ( ip_addr | * ) [ port ip_port ] allow { <replaceable> address_match_list </replaceable> } + [ inet ( ip_addr | * ) [ port ip_port ] + allow { <replaceable> address_match_list </replaceable> } keys { <replaceable>key_list</replaceable> }; ] [ inet ...; ] - [ unix <replaceable>path</replaceable> perm <replaceable>number</replaceable> owner <replaceable>number</replaceable> group <replaceable>number</replaceable> keys { <replaceable>key_list</replaceable> }; ] + [ unix <replaceable>path</replaceable> perm <replaceable>number</replaceable> owner <replaceable>number</replaceable> group <replaceable>number</replaceable> + keys { <replaceable>key_list</replaceable> }; ] [ unix ...; ] }; </programlisting> @@ -4031,32 +4260,30 @@ notrace</command>. All debugging messages in the server have a debug </para> <programlisting>channel default_syslog { - syslog daemon; // send to syslog's daemon - // facility - severity info; // only send priority info - // and higher -}; + // send to syslog's daemon facility + syslog daemon; + // only send priority info and higher + severity info; channel default_debug { - file "named.run"; // write to named.run in - // the working directory - // Note: stderr is used instead - // of "named.run" - // if the server is started - // with the '-f' option. - severity dynamic; // log at the server's - // current debug level + // write to named.run in the working directory + // Note: stderr is used instead of "named.run" if + // the server is started with the '-f' option. + file "named.run"; + // log at the server's current debug level + severity dynamic; }; channel default_stderr { - stderr; // writes to stderr - severity info; // only send priority info - // and higher + // writes to stderr + stderr; + // only send priority info and higher + severity info; }; channel null { - null; // toss anything sent to - // this channel + // toss anything sent to this channel + null; }; </programlisting> @@ -4308,12 +4535,14 @@ category notify { null; }; <para> The query log entry reports the client's IP address and port number, and the query name, - class and type. It also reports whether the + 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 use (E), if DO (DNSSEC Ok) was - set (D), or if CD (Checking Disabled) was set - (C). + EDNS was in use (E), if TCP was used (T), if + DO (DNSSEC Ok) was set (D), or if CD (Checking + Disabled) was set (C). After this the + destination address the query was sent to is + reported. </para> <para> @@ -4453,7 +4682,13 @@ category notify { null; }; The log message will look like as follows: </para> <para> - <computeroutput>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]</computeroutput> +<!-- NOTE: newlines and some spaces added so this would fit on page --> + <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] + </programlisting> </para> <para> The first part before the colon shows that a recursive @@ -4485,8 +4720,8 @@ category notify { null; }; <informaltable colsep="0" rowsep="0"> <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> - <colspec colname="1" colnum="1" colsep="0" /> - <colspec colname="2" colnum="2" colsep="0" /> + <colspec colname="1" colnum="1" colsep="0" colwidth="1.150in"/> + <colspec colname="2" colnum="2" colsep="0" colwidth="3.350in"/> <tbody> <row rowsep="0"> <entry colname="1"> @@ -4651,7 +4886,8 @@ category notify { null; }; </para> <programlisting><command>lwres</command> { - <optional> listen-on { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> + <optional> listen-on { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; + <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> <optional> view <replaceable>view_name</replaceable>; </optional> <optional> search { <replaceable>domain_name</replaceable> ; <optional> <replaceable>domain_name</replaceable> ; ... </optional> }; </optional> <optional> ndots <replaceable>number</replaceable>; </optional> @@ -4718,7 +4954,8 @@ category notify { null; }; <title><command>masters</command> Statement Grammar</title> <programlisting> -<command>masters</command> <replaceable>name</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> { ( <replaceable>masters_list</replaceable> | <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> <optional>key <replaceable>key</replaceable></optional> ) ; <optional>...</optional> }; +<command>masters</command> <replaceable>name</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> { ( <replaceable>masters_list</replaceable> | + <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> <optional>key <replaceable>key</replaceable></optional> ) ; <optional>...</optional> }; </programlisting> </sect2> @@ -4741,17 +4978,21 @@ category notify { null; }; </para> <programlisting><command>options</command> { + <optional> attach-cache <replaceable>cache_name</replaceable>; </optional> <optional> version <replaceable>version_string</replaceable>; </optional> <optional> hostname <replaceable>hostname_string</replaceable>; </optional> <optional> server-id <replaceable>server_id_string</replaceable>; </optional> <optional> directory <replaceable>path_name</replaceable>; </optional> <optional> key-directory <replaceable>path_name</replaceable>; </optional> + <optional> managed-keys-directory <replaceable>path_name</replaceable>; </optional> <optional> named-xfer <replaceable>path_name</replaceable>; </optional> + <optional> tkey-gssapi-keytab <replaceable>path_name</replaceable>; </optional> <optional> tkey-gssapi-credential <replaceable>principal</replaceable>; </optional> <optional> tkey-domain <replaceable>domainname</replaceable>; </optional> <optional> tkey-dhkey <replaceable>key_name</replaceable> <replaceable>key_tag</replaceable>; </optional> <optional> cache-file <replaceable>path_name</replaceable>; </optional> <optional> dump-file <replaceable>path_name</replaceable>; </optional> + <optional> bindkeys-file <replaceable>path_name</replaceable>; </optional> <optional> memstatistics <replaceable>yes_or_no</replaceable>; </optional> <optional> memstatistics-file <replaceable>path_name</replaceable>; </optional> <optional> pid-file <replaceable>path_name</replaceable>; </optional> @@ -4776,8 +5017,9 @@ category notify { null; }; <optional> maintain-ixfr-base <replaceable>yes_or_no</replaceable>; </optional> <optional> ixfr-from-differences (<replaceable>yes_or_no</replaceable> | <constant>master</constant> | <constant>slave</constant>); </optional> <optional> dnssec-enable <replaceable>yes_or_no</replaceable>; </optional> - <optional> dnssec-validation <replaceable>yes_or_no</replaceable>; </optional> - <optional> dnssec-lookaside <replaceable>domain</replaceable> trust-anchor <replaceable>domain</replaceable>; </optional> + <optional> dnssec-validation (<replaceable>yes_or_no</replaceable> | <constant>auto</constant>); </optional> + <optional> dnssec-lookaside ( <replaceable>auto</replaceable> | + <replaceable>domain</replaceable> trust-anchor <replaceable>domain</replaceable> ); </optional> <optional> dnssec-must-be-secure <replaceable>domain yes_or_no</replaceable>; </optional> <optional> dnssec-accept-expired <replaceable>yes_or_no</replaceable>; </optional> <optional> forward ( <replaceable>only</replaceable> | <replaceable>first</replaceable> ); </optional> @@ -4788,12 +5030,14 @@ category notify { null; }; ... }; </optional> <optional> check-names ( <replaceable>master</replaceable> | <replaceable>slave</replaceable> | <replaceable>response</replaceable> ) ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> + <optional> check-dup-records ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> <optional> check-mx ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> <optional> check-wildcard <replaceable>yes_or_no</replaceable>; </optional> <optional> check-integrity <replaceable>yes_or_no</replaceable>; </optional> <optional> check-mx-cname ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> <optional> check-srv-cname ( <replaceable>warn</replaceable> | <replaceable>fail</replaceable> | <replaceable>ignore</replaceable> ); </optional> <optional> check-sibling <replaceable>yes_or_no</replaceable>; </optional> + <optional> allow-new-zones { <replaceable>yes_or_no</replaceable> }; </optional> <optional> allow-notify { <replaceable>address_match_list</replaceable> }; </optional> <optional> allow-query { <replaceable>address_match_list</replaceable> }; </optional> <optional> allow-query-on { <replaceable>address_match_list</replaceable> }; </optional> @@ -4805,6 +5049,8 @@ category notify { null; }; <optional> allow-update { <replaceable>address_match_list</replaceable> }; </optional> <optional> allow-update-forwarding { <replaceable>address_match_list</replaceable> }; </optional> <optional> update-check-ksk <replaceable>yes_or_no</replaceable>; </optional> + <optional> dnssec-dnskey-kskonly <replaceable>yes_or_no</replaceable>; </optional> + <optional> dnssec-secure-to-insecure <replaceable>yes_or_no</replaceable> ;</optional> <optional> try-tcp-refresh <replaceable>yes_or_no</replaceable>; </optional> <optional> allow-v6-synthesis { <replaceable>address_match_list</replaceable> }; </optional> <optional> blackhole { <replaceable>address_match_list</replaceable> }; </optional> @@ -4816,12 +5062,12 @@ category notify { null; }; <optional> listen-on-v6 <optional> port <replaceable>ip_port</replaceable> </optional> { <replaceable>address_match_list</replaceable> }; </optional> <optional> query-source ( ( <replaceable>ip4_addr</replaceable> | <replaceable>*</replaceable> ) <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> | - <optional> address ( <replaceable>ip4_addr</replaceable> | <replaceable>*</replaceable> ) </optional> - <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> ) ; </optional> + <optional> address ( <replaceable>ip4_addr</replaceable> | <replaceable>*</replaceable> ) </optional> + <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> ) ; </optional> <optional> query-source-v6 ( ( <replaceable>ip6_addr</replaceable> | <replaceable>*</replaceable> ) - <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> | - <optional> address ( <replaceable>ip6_addr</replaceable> | <replaceable>*</replaceable> ) </optional> - <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> ) ; </optional> + <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> | + <optional> address ( <replaceable>ip6_addr</replaceable> | <replaceable>*</replaceable> ) </optional> + <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional> ) ; </optional> <optional> use-queryport-pool <replaceable>yes_or_no</replaceable>; </optional> <optional> queryport-pool-ports <replaceable>number</replaceable>; </optional> <optional> queryport-pool-updateinterval <replaceable>number</replaceable>; </optional> @@ -4842,13 +5088,15 @@ category notify { null; }; <optional> transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> alt-transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> - <optional> alt-transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> + <optional> alt-transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) + <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> use-alt-transfer-source <replaceable>yes_or_no</replaceable>; </optional> <optional> notify-delay <replaceable>seconds</replaceable> ; </optional> <optional> notify-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> notify-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> notify-to-soa <replaceable>yes_or_no</replaceable> ; </optional> - <optional> also-notify { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> + <optional> also-notify { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; + <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> <optional> max-ixfr-log-size <replaceable>number</replaceable>; </optional> <optional> max-journal-size <replaceable>size_spec</replaceable>; </optional> <optional> coresize <replaceable>size_spec</replaceable> ; </optional> @@ -4884,12 +5132,25 @@ category notify { null; }; <optional> random-device <replaceable>path_name</replaceable> ; </optional> <optional> max-cache-size <replaceable>size_spec</replaceable> ; </optional> <optional> match-mapped-addresses <replaceable>yes_or_no</replaceable>; </optional> + <optional> filter-aaaa-on-v4 ( <replaceable>yes_or_no</replaceable> | <replaceable>break-dnssec</replaceable> ); </optional> + <optional> filter-aaaa { <replaceable>address_match_list</replaceable> }; </optional> + <optional> dns64 <replaceable>IPv6-prefix</replaceable> { + <optional> clients { <replaceable>address_match_list</replaceable> }; </optional> + <optional> mapped { <replaceable>address_match_list</replaceable> }; </optional> + <optional> exclude { <replaceable>address_match_list</replaceable> }; </optional> + <optional> suffix IPv6-address; </optional> + <optional> recursive-only <replaceable>yes_or_no</replaceable>; </optional> + <optional> break-dnssec <replaceable>yes_or_no</replaceable>; </optional> + }; </optional>; + <optional> dns64-server <replaceable>name</replaceable> </optional> + <optional> dns64-contact <replaceable>name</replaceable> </optional> <optional> preferred-glue ( <replaceable>A</replaceable> | <replaceable>AAAA</replaceable> | <replaceable>NONE</replaceable> ); </optional> <optional> edns-udp-size <replaceable>number</replaceable>; </optional> <optional> max-udp-size <replaceable>number</replaceable>; </optional> <optional> root-delegation-only <optional> exclude { <replaceable>namelist</replaceable> } </optional> ; </optional> <optional> querylog <replaceable>yes_or_no</replaceable> ; </optional> - <optional> disable-algorithms <replaceable>domain</replaceable> { <replaceable>algorithm</replaceable>; <optional> <replaceable>algorithm</replaceable>; </optional> }; </optional> + <optional> disable-algorithms <replaceable>domain</replaceable> { <replaceable>algorithm</replaceable>; + <optional> <replaceable>algorithm</replaceable>; </optional> }; </optional> <optional> acache-enable <replaceable>yes_or_no</replaceable> ; </optional> <optional> acache-cleaning-interval <replaceable>number</replaceable>; </optional> <optional> max-acache-size <replaceable>size_spec</replaceable> ; </optional> @@ -4902,6 +5163,10 @@ category notify { null; }; <optional> disable-empty-zone <replaceable>zone_name</replaceable> ; </optional> <optional> zero-no-soa-ttl <replaceable>yes_or_no</replaceable> ; </optional> <optional> zero-no-soa-ttl-cache <replaceable>yes_or_no</replaceable> ; </optional> + <optional> resolver-query-timeout <replaceable>number</replaceable> ; </optional> + <optional> deny-answer-addresses { <replaceable>address_match_list</replaceable> } <optional> except-from { <replaceable>namelist</replaceable> } </optional>;</optional> + <optional> deny-answer-aliases { <replaceable>namelist</replaceable> } <optional> except-from { <replaceable>namelist</replaceable> } </optional>;</optional> + <optional> response-policy { <replaceable>zone_name</replaceable> <optional> policy <replaceable>given</replaceable> | <replaceable>no-op</replaceable> | <replaceable>nxdomain</replaceable> | <replaceable>nodata</replaceable> | <replaceable>cname domain</replaceable> </optional> ; } ; </optional> }; </programlisting> @@ -4923,6 +5188,102 @@ category notify { null; }; <variablelist> + <varlistentry> + <term><command>attach-cache</command></term> + <listitem> + <para> + 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. + </para> + + <para> + The <command>attach-cache</command> option + may also be specified in <command>view</command> + statements, in which case it overrides the + global <command>attach-cache</command> option. + </para> + + <para> + The <replaceable>cache_name</replaceable> specifies + the cache to be shared. + When the <command>named</command> 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. + </para> + + <para> + 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 <command>attach-cache</command> as a global + option with an arbitrary name. + </para> + + <para> + 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 + <command>attach-cache</command> option as a view A (or + B)'s option, referring to the other view name: + </para> + +<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 + ... + }; +</programlisting> + + <para> + 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: + <command>check-names</command>, + <command>cleaning-interval</command>, + <command>dnssec-accept-expired</command>, + <command>dnssec-validation</command>, + <command>max-cache-ttl</command>, + <command>max-ncache-ttl</command>, + <command>max-cache-size</command>, and + <command>zero-no-soa-ttl</command>. + </para> + + <para> + 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. + </para> + </listitem> + + </varlistentry> + <varlistentry> <term><command>directory</command></term> <listitem> @@ -4950,10 +5311,24 @@ category notify { null; }; 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. The directory specified must be an absolute - path. (Note that this option has no effect on the paths - for files containing non-DNSSEC keys such as the - <filename>rndc.key</filename>. + directory. (Note that this option has no effect on the + paths for files containing non-DNSSEC keys such as + <filename>bind.keys</filename>, + <filename>rndc.key</filename> or + <filename>session.key</filename>.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>managed-keys-directory</command></term> + <listitem> + <para> + The directory used to hold the files used to track managed keys. + By default it is the working directory. It there are no + views then the file <filename>managed-keys.bind</filename> + otherwise a SHA256 hash of the view name is used with + <filename>.mkeys</filename> extension added. </para> </listitem> </varlistentry> @@ -4973,19 +5348,33 @@ category notify { null; }; </varlistentry> <varlistentry> + <term><command>tkey-gssapi-keytab</command></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><command>tkey-gssapi-credential</command></term> <listitem> <para> 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 <filename>/etc/krb5.keytab</filename>. - Normally this principal is of the form - "<userinput>DNS/</userinput><varname>server.domain</varname>". - To use GSS-TSIG, <command>tkey-domain</command> - must also be set. + and the credential is a Kerberos principal which the + server can acquire through the default system key + file, normally <filename>/etc/krb5.keytab</filename>. + The location keytab file can be overridden using the + tkey-gssapi-keytab option. Normally this principal is + of the form "<userinput>DNS/</userinput><varname>server.domain</varname>". + To use GSS-TSIG, <command>tkey-domain</command> must + also be set if a specific keytab is not set with + tkey-gssapi-keytab. </para> </listitem> </varlistentry> @@ -5007,7 +5396,8 @@ category notify { null; }; should be the server's domain name, or an otherwise non-existent subdomain like "_tkey.<varname>domainname</varname>". If you are - using GSS-TSIG, this variable must be defined. + using GSS-TSIG, this variable must be defined, unless + you specify a specific keytab using tkey-gssapi-keytab. </para> </listitem> </varlistentry> @@ -5106,6 +5496,84 @@ category notify { null; }; </varlistentry> <varlistentry> + <term><command>bindkeys-file</command></term> + <listitem> + <para> + The pathname of a file to override the built-in trusted + keys provided by <command>named</command>. + See the discussion of <command>dnssec-lookaside</command> + and <command>dnssec-validation</command> for details. + If not specified, the default is + <filename>/etc/bind.keys</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>secroots-file</command></term> + <listitem> + <para> + The pathname of the file the server dumps + security roots to when instructed to do so with + <command>rndc secroots</command>. + If not specified, the default is <filename>named.secroots</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>session-keyfile</command></term> + <listitem> + <para> + The pathname of the file into which to write a TSIG + session key generated by <command>named</command> for use by + <command>nsupdate -l</command>. If not specified, the + default is <filename>/var/run/named/session.key</filename>. + (See <xref linkend="dynamic_update_policies"/>, and in + particular the discussion of the + <command>update-policy</command> statement's + <userinput>local</userinput> option for more + information about this feature.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>session-keyname</command></term> + <listitem> + <para> + The key name to use for the TSIG session key. + If not specified, the default is "local-ddns". + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>session-keyalg</command></term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>session-keyfile</command></term> + <listitem> + <para> + The pathname of the file into which to write a session TSIG + key for use by <command>nsupdate -l</command>. (See the + discussion of the <command>update-policy</command> + statement's <userinput>local</userinput> option for more + details on this feature.) + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><command>port</command></term> <listitem> <para> @@ -5167,14 +5635,14 @@ category notify { null; }; <para> DS queries are expected to be made to and be answered by delegation only zones. Such queries and responses are - treated as a exception to delegation-only processing + 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. </para> <para> If a delegation only zone server also serves a child zone it is not always possible to determine whether - a answer comes from the delegation only zone or the + 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 @@ -5223,21 +5691,46 @@ options { <term><command>dnssec-lookaside</command></term> <listitem> <para> - When set, <command>dnssec-lookaside</command> - 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 <command>dnssec-lookaside</command>, and - the normal DNSSEC validation - has left the key untrusted, the trust-anchor will be append 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 + When set, <command>dnssec-lookaside</command> 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 + <command>dnssec-lookaside</command>, 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. + </para> + <para> + If <command>dnssec-lookaside</command> is set to + <userinput>auto</userinput>, then built-in default + values for the DLV domain and trust anchor will be + used, along with a built-in key for validation. + </para> + <para> + The default DLV key is stored in the file + <filename>bind.keys</filename>; + <command>named</command> will load that key at + startup if <command>dnssec-lookaside</command> is set to + <constant>auto</constant>. A copy of the file is + installed along with <acronym>BIND</acronym> 9, and is + current as of the release date. If the DLV key expires, a + new copy of <filename>bind.keys</filename> can be downloaded + from <ulink>https://www.isc.org/solutions/dlv</ulink>. + </para> + <para> + (To prevent problems if <filename>bind.keys</filename> is + not found, the current key is also compiled in to + <command>named</command>. Relying on this is not + recommended, however, as it requires <command>named</command> + to be recompiled with a new key when the DLV key expires.) + </para> + <para> + NOTE: <command>named</command> only loads certain specific + keys from <filename>bind.keys</filename>: those for the + DLV zone and for the DNS root zone. The file cannot be + used to store keys for other zones. </para> </listitem> </varlistentry> @@ -5246,21 +5739,86 @@ options { <term><command>dnssec-must-be-secure</command></term> <listitem> <para> - Specify hierarchies which must be or may not be secure (signed and - validated). - If <userinput>yes</userinput>, then <command>named</command> will only accept - answers if they - are secure. - If <userinput>no</userinput>, then normal DNSSEC validation - applies - allowing for insecure answers to be accepted. - The specified domain must be under a <command>trusted-key</command> or - <command>dnssec-lookaside</command> must be - active. + Specify hierarchies which must be or may not be secure + (signed and validated). If <userinput>yes</userinput>, + then <command>named</command> will only accept answers if + they are secure. If <userinput>no</userinput>, then normal + DNSSEC validation applies allowing for insecure answers to + be accepted. The specified domain must be under a + <command>trusted-keys</command> or + <command>managed-keys</command> statement, or + <command>dnssec-lookaside</command> must be active. </para> </listitem> </varlistentry> + <varlistentry> + <term><command>dns64</command></term> + <listitem> + <para> + This directive instructs <command>named</command> 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 + <command>dns64</command> defines one DNS64 prefix. + Multiple DNS64 prefixes can be defined. + </para> + <para> + Compatible IPv6 prefixes have lengths of 32, 40, 48, 56, + 64 and 96 as per RFC 6052. + </para> + <para> + 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. <command>dns64-server</command> and + <command>dns64-contact</command> 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. + </para> + <para> + Each <command>dns64</command> supports an optional + <command>clients</command> ACL that determines which + clients are affected by this directive. If not defined, + it defaults to <userinput>any;</userinput>. + </para> + <para> + Each <command>dns64</command> supports an optional + <command>mapped</command> ACL that selects which + IPv4 addresses are to be mapped in the corresponding + A RRset. If not defined it defaults to + <userinput>any;</userinput>. + </para> + <para> + Each <command>dns64</command> supports an optional + <command>exclude</command> ACL that selects which + IPv6 addresses will be ignored for the purposes + of determining whether dns64 is to be applied. + Any non-matching address will prevent further + DNS64 processing from occurring for this client. + </para> + <para> + A optional <command>suffix</command> can also + be defined to set the bits trailing the mapped + IPv4 address bits. By default these bits are + set to <userinput>::</userinput>. The bits + matching the prefix and mapped IPv4 address + must be zero. + </para> +<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 ::; + }; +</programlisting> + </listitem> + </varlistentry> + </variablelist> <sect3 id="boolean_options"> @@ -5269,6 +5827,18 @@ options { <variablelist> <varlistentry> + <term><command>allow-new-zones</command></term> + <listitem> + <para> + If <userinput>yes</userinput>, then zones can be + added at runtime via <command>rndc addzone</command> + or deleted via <command>rndc delzone</command>. + The default is <userinput>no</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><command>auth-nxdomain</command></term> <listitem> <para> @@ -5755,6 +6325,7 @@ options { off on a per-zone basis by specifying <command>zone-statistics no</command> in the <command>zone</command> statement). + The default is <userinput>no</userinput>. These statistics may be accessed using <command>rndc stats</command>, which will dump them to the file listed @@ -5928,6 +6499,60 @@ options { </varlistentry> <varlistentry> + <term><command>filter-aaaa-on-v4</command></term> + <listitem> + <para> + This option is only available when + <acronym>BIND</acronym> 9 is compiled with the + <userinput>--enable-filter-aaaa</userinput> 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 <userinput>no</userinput>. + The <command>filter-aaaa-on-v4</command> option + may also be specified in <command>view</command> statements + to override the global <command>filter-aaaa-on-v4</command> + option. + </para> + <para> + If <userinput>yes</userinput>, + the DNS client is at an IPv4 address, in <command>filter-aaaa</command>, + 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. + </para> + <para> + If <userinput>break-dnssec</userinput>, + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><command>ixfr-from-differences</command></term> <listitem> <para> @@ -5996,7 +6621,15 @@ options { Enable DNSSEC validation in <command>named</command>. Note <command>dnssec-enable</command> also needs to be set to <userinput>yes</userinput> to be effective. - The default is <userinput>yes</userinput>. + If set to <userinput>no</userinput>, DNSSEC validation + is disabled. If set to <userinput>auto</userinput>, + DNSSEC validation is enabled, and a default + trust-anchor for the DNS root zone is used. If set to + <userinput>yes</userinput>, DNSSEC validation is enabled, + but a trust anchor must be manually configured using + a <command>trusted-keys</command> or + <command>managed-keys</command> statement. The default + is <userinput>yes</userinput>. </para> </listitem> </varlistentry> @@ -6007,7 +6640,9 @@ options { <para> Accept expired signatures when verifying DNSSEC signatures. The default is <userinput>no</userinput>. - Setting this option to "yes" leaves <command>named</command> vulnerable to replay attacks. + Setting this option to <userinput>yes</userinput> + leaves <command>named</command> vulnerable to + replay attacks. </para> </listitem> </varlistentry> @@ -6057,6 +6692,19 @@ options { </varlistentry> <varlistentry> + <term><command>check-dup-records</command></term> + <listitem> + <para> + Check master zones for records that are treated as different + by DNSSEC but are semantically equal in plain DNS. The + default is to <command>warn</command>. Other possible + values are <command>fail</command> and + <command>ignore</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><command>check-mx</command></term> <listitem> <para> @@ -6161,13 +6809,49 @@ options { <term><command>update-check-ksk</command></term> <listitem> <para> - When regenerating the RRSIGs following a UPDATE - request to a secure zone, check the KSK flag on - the DNSKEY RR to determine if this key should be - used to generate the RRSIG. This flag is ignored - if there are not DNSKEY RRs both with and without - a KSK. - The default is <command>yes</command>. + When set to the default value of <literal>yes</literal>, + check the KSK bit in each key to determine how the key + should be used when generating RRSIGs for a secure zone. + </para> + <para> + 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 <literal>no</literal>, + 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 <command>dnssec-signzone -z</command> + command line option. + </para> + <para> + When this option is set to <literal>yes</literal>, 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>dnssec-dnskey-kskonly</command></term> + <listitem> + <para> + When this option and <command>update-check-ksk</command> + are both set to <literal>yes</literal>, 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 + <command>dnssec-signzone -x</command> command line option. + </para> + <para> + The default is <command>no</command>. If + <command>update-check-ksk</command> is set to + <literal>no</literal>, this option is ignored. </para> </listitem> </varlistentry> @@ -6183,6 +6867,34 @@ options { </listitem> </varlistentry> + <varlistentry> + <term><command>dnssec-secure-to-insecure</command></term> + <listitem> + <para> + 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 <command>no</command>. + If set to <command>yes</command>, and if the DNSKEY RRset + at the zone apex is deleted, all RRSIG and NSEC records + will be removed from the zone as well. + </para> + <para> + 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.) + </para> + <para> + Note that if a zone has been configured with + <command>auto-dnssec maintain</command> and the + private keys remain accessible in the key repository, + then the zone will be automatically signed again the + next time <command>named</command> is started. + </para> + </listitem> + </varlistentry> + </variablelist> </sect3> @@ -6495,6 +7207,29 @@ options { </listitem> </varlistentry> + <varlistentry> + <term><command>filter-aaaa</command></term> + <listitem> + <para> + Specifies a list of addresses to which + <command>filter-aaaa-on-v4</command> + is applies. The default is <userinput>any</userinput>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>resolver-query-timeout</command></term> + <listitem> + <para> + The amount of time the resolver will spend attempting + to resolve a recursive query before failing. The + default is <literal>10</literal> and the maximum is + <literal>30</literal>. Setting it to <literal>0</literal> + will result in the default being used. + </para> + </listitem> + </varlistentry> </variablelist> </sect3> @@ -7542,20 +8277,26 @@ avoid-v6-udp-ports { 40000; range 50000 60000; }; </para> <programlisting>sortlist { - { localhost; // IF the local host - { localnets; // THEN first fit on the - 192.168.1/24; // following nets + // 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; }; }; }; - { 192.168.1/24; // IF on class C 192.168.1 - { 192.168.1/24; // THEN use .1, or .2 or .3 + // 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; }; }; }; - { 192.168.2/24; // IF on class C 192.168.2 - { 192.168.2/24; // THEN use .2, or .1 or .3 + // 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; }; }; }; - { 192.168.3/24; // IF on class C 192.168.3 - { 192.168.3/24; // THEN use .3, or .1 or .2 + // 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; }; }; }; - { { 192.168.4/24; 192.168.5/24; }; // if .4 or .5, prefer that net + // IF .4 or .5 THEN prefer that net + { { 192.168.4/24; 192.168.5/24; }; }; };</programlisting> @@ -7772,7 +8513,7 @@ avoid-v6-udp-ports { 40000; range 50000 60000; }; DNSSEC signatures automatically generated as a result of dynamic updates (<xref linkend="dynamic_update"/>) will expire. There - is a optional second field which specifies how + 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 @@ -7877,7 +8618,7 @@ avoid-v6-udp-ports { 40000; range 50000 60000; }; <para> Sets the advertised EDNS UDP buffer size in bytes to control the size of packets received. - Valid values are 512 to 4096 (values outside this range + Valid values are 1024 to 4096 (values outside this range will be silently adjusted). The default value is 4096. The usual reason for setting <command>edns-udp-size</command> to a non-default @@ -7885,24 +8626,36 @@ avoid-v6-udp-ports { 40000; range 50000 60000; }; firewalls that block fragmented packets and/or block UDP packets that are greater than 512 bytes. </para> + <para> + <command>named</command> will fallback to using 512 bytes + if it get a series of timeout at the initial value. 512 + bytes is not being offered to encourage sites to fix their + firewalls. Small EDNS UDP sizes will result in the + excessive use of TCP. + </para> </listitem> </varlistentry> <varlistentry> <term><command>max-udp-size</command></term> - <listitem> - <para> - Sets the maximum EDNS UDP message size <command>named</command> will - send in bytes. Valid values are 512 to 4096 (values outside - this range will be silently adjusted). The default + <listitem> + <para> + Sets the maximum EDNS UDP message size + <command>named</command> will send in bytes. + Valid values are 512 to 4096 (values outside this + range will be silently adjusted). The default value is 4096. The usual reason for setting - <command>max-udp-size</command> 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. + <command>max-udp-size</command> 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 (<command>edns-udp-size</command>). </para> + <para> + Setting this to a low value will encourage additional + TCP traffic to the nameserver. + </para> </listitem> </varlistentry> @@ -8081,7 +8834,7 @@ avoid-v6-udp-ports { 40000; range 50000 60000; }; <para> Named 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 a empty zone in that case. + and will not create an empty zone in that case. </para> <para> The current list of empty zones is: @@ -8308,6 +9061,282 @@ XXX: end of RFC1918 addresses #defined out --> </sect3> + <sect3> + <title>Content Filtering</title> + <para> + <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 + <varname>address_match_list</varname> of the + <command>deny-answer-addresses</command> 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 <varname>namelist</varname> of the + <command>deny-answer-aliases</command> option, where + "match" means the alias name is a subdomain of one of + the <varname>name_list</varname> elements. + If the optional <varname>namelist</varname> is specified + with <command>except-from</command>, 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 <command>deny-answer-aliases</command> + filter will not apply; + for example, even if "example.com" is specified for + <command>deny-answer-aliases</command>, + </para> +<programlisting>www.example.com. CNAME xxx.example.com.</programlisting> + + <para> + returned by an "example.com" server will be accepted. + </para> + + <para> + In the <varname>address_match_list</varname> of the + <command>deny-answer-addresses</command> option, only + <varname>ip_addr</varname> + and <varname>ip_prefix</varname> + are meaningful; + any <varname>key_id</varname> will be silently ignored. + </para> + + <para> + 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. + </para> + + <para> + 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 + <ulink> + http://portal.acm.org/citation.cfm?id=1315245.1315298 + </ulink> + for more details about the attacks. + </para> + + <para> + 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: + </para> + +<programlisting>deny-answer-addresses { 192.0.2.0/24; } except-from { "example.net"; }; +deny-answer-aliases { "example.net"; }; +</programlisting> + + <para> + 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: + </para> + +<programlisting>attacker.example.com. A 192.0.2.1</programlisting> + + <para> + 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. + </para> + + <para> + 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>BIND</acronym> 9 server + </para> + +<programlisting>www.example.net. A 192.0.2.2</programlisting> + + <para> + it will be accepted since the owner name "www.example.net" + matches the <command>except-from</command> element, + "example.net". + </para> + + <para> + 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. + </para> + + <para> + 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. + </para> + </sect3> + + <sect3> + <title>Response Policy Zone (RPZ) Rewriting</title> + <para> + <acronym>BIND</acronym> 9 includes an intentionally limited + mechanism to modify DNS responses for recursive requests + similar to email anti-spam DNS blacklists. + All response policy zones are named in the + <command>response-policy</command> option for the view or among the + global options if there is no response-policy option for the view. + </para> + + <para> + The rules encoded in a response policy zone (RPZ) are applied + only to responses to queries that ask for recursion (RD=1). + RPZs are normal DNS zones containing RRsets + that can be queried normally if allowed. + It is usually best to restrict those queries with something like + <command>allow-query {none; };</command> or + <command>allow-query { 127.0.0.1; };</command>. + </para> + + <para> + There are four kinds of RPZ rewrite rules. QNAME rules are + applied to query names in requests and to targets of CNAME + records resolved in the process of generating the response. + The owner name of a QNAME rule is the query name relativized + to the RPZ. + The records in a rewrite rule are usually A, AAAA, or special + CNAMEs, but can be any type except DNAME. + </para> + + <para> + IP rules are triggered by addresses in A and AAAA records. + All IP addresses in A or AAAA RRsets are tested and the rule + longest prefix is applied. Ties between rules with equal prefixes + are broken in favor of the first RPZ mentioned in the + response-policy option. + The rule matching the smallest IP address is chosen among equal + prefix rules from a single RPZ. + IP rules are expressed in RRsets with owner names that are + subdomains of rpz-ip and encoding an IP address block, reversed + as in IN-ARPA. + prefix.B.B.B.B with prefix between 1 and 32 and B between 1 and 255 + encodes an IPv4 address. + IPv6 addresses are encoded by with prefix.W.W.W.W.W.W.W.W or + prefix.WORDS.zz.WORDS. The words in the standard IPv6 text + representation are reversed, "::" is replaced with ".zz.", + and ":" becomes ".". + </para> + + <para> + NSDNAME rules match names in NS RRsets for the response or a + parent. They are encoded as subdomains of rpz-nsdomain relativized + to the RPZ origin name. + </para> + + <para> + NSIP rules match IP addresses in A and AAAA RRsets for names of + responsible servers or the names that can be matched by NSDNAME + rules. The are encoded like IP rules except as subdomains of + rpz-nsip. + </para> + + <para> + Authority verification issues and variations in authority data in + the current version of <acronym>BIND</acronym> 9 can cause + inconsistent results from NSIP and NSDNAME. So they are available + only when <acronym>BIND</acronym> is built with the + <userinput>--enable-rpz-nsip</userinput> or + <userinput>--enable-rpz-nsdname</userinput> options + on the "configure" command line. + </para> + + <para> + Four policies can be expressed. + The <command>NXDOMAIN</command> policy causes a NXDOMAIN response + and is expressed with an RRset consisting of a single CNAME + whose target is the root domain (.). + <command>NODATA</command> generates NODATA or ANCOUNT=1 regardless + of query type. + It is expressed with a CNAME whose target is the wildcard + top-level domain (*.). + The <command>NO-OP</command> policy does not change the response + and is used to "poke holes" in policies for larger CIDR blocks or in + zones named later in the <command>response-policy</command> option. + The NO-OP policy is expressed by a CNAME with a target consisting + of the variable part of the owner name, such as "example.com." for + a QNAME rule or "128.1.0.0.127." for an IP rule. + The <command>CNAME</command> policy is used to replace the RRsets + of response. + A and AAAA RRsets are most common and useful to capture + an evil domain in a walled garden, but any valid set of RRsets + is possible. + </para> + + <para> + All of the policies in an RPZ can be overridden with a + <command>policy</command> clause. + <command>given</command> says "do not override." + <command>no-op</command> says "do nothing" regardless of the policy + in RPZ records. + <command>nxdomain</command> causes all RPZ rules to generate + NXDOMAIN results. + <command>nodata</command> gives nodata. + <command>cname domain</command> causes all RPZ rules to act as if + the consisted of a "cname domain" record. + </para> + + <para> + For example, you might use this option statement + </para> +<programlisting>response-policy { zone "bl"; };</programlisting> + <para> + and this zone statement + </para> +<programlisting>zone "bl" {type master; file "example/bl"; allow-query {none;}; };</programlisting> + <para> + with this zone file + </para> +<programlisting>$TTL 1H +@ SOA LOCALHOST. named-mgr.example.com (1 1h 15m 30d 2h) + +; QNAME rules +nxdomain.domain.com CNAME . +nodata.domain.com CNAME *. +bad.domain.com A 10.0.0.1 + AAAA 2001:2::1 +ok.domain.com CNAME ok.domain.com. +*.badzone.domain.com CNAME garden.example.com. + +; IP rules rewriting all answers for 127/8 except 127.0.0.1 +8.0.0.0.127.ip CNAME . +32.1.0.0.127.ip CNAME 32.1.0.0.127. + +; NSDNAME and NSIP rules +ns.domain.com.rpz-nsdname CNAME . +48.zz.2.2001.rpz-nsip CNAME . +</programlisting> + </sect3> </sect2> <sect2 id="server_statement_grammar"> @@ -8327,8 +9356,10 @@ XXX: end of RFC1918 addresses #defined out --> <optional> transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> notify-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> notify-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> - <optional> query-source <optional> address ( <replaceable>ip_addr</replaceable> | <replaceable>*</replaceable> ) </optional> <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional>; </optional> - <optional> query-source-v6 <optional> address ( <replaceable>ip_addr</replaceable> | <replaceable>*</replaceable> ) </optional> <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional>; </optional> + <optional> query-source <optional> address ( <replaceable>ip_addr</replaceable> | <replaceable>*</replaceable> ) </optional> + <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional>; </optional> + <optional> query-source-v6 <optional> address ( <replaceable>ip_addr</replaceable> | <replaceable>*</replaceable> ) </optional> + <optional> port ( <replaceable>ip_port</replaceable> | <replaceable>*</replaceable> ) </optional>; </optional> <optional> use-queryport-pool <replaceable>yes_or_no</replaceable>; </optional> <optional> queryport-pool-ports <replaceable>number</replaceable>; </optional> <optional> queryport-pool-updateinterval <replaceable>number</replaceable>; </optional> @@ -8526,7 +9557,8 @@ XXX: end of RFC1918 addresses #defined out --> <title><command>statistics-channels</command> Statement Grammar</title> <programlisting><command>statistics-channels</command> { - [ inet ( ip_addr | * ) [ port ip_port ] [allow { <replaceable> address_match_list </replaceable> } ]; ] + [ inet ( ip_addr | * ) [ port ip_port ] + [ allow { <replaceable> address_match_list </replaceable> } ]; ] [ inet ...; ] }; </programlisting> @@ -8590,7 +9622,7 @@ XXX: end of RFC1918 addresses #defined out --> </sect2> - <sect2> + <sect2 id="trusted-keys"> <title><command>trusted-keys</command> Statement Grammar</title> <programlisting><command>trusted-keys</command> { @@ -8632,6 +9664,136 @@ XXX: end of RFC1918 addresses #defined out --> in the key data, so the configuration may be split up into multiple lines. </para> + <para> + <command>trusted-keys</command> may be set at the top level + of <filename>named.conf</filename> 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. + </para> + </sect2> + + <sect2> + <title><command>managed-keys</command> Statement Grammar</title> + +<programlisting><command>managed-keys</command> { + <replaceable>string</replaceable> initial-key <replaceable>number</replaceable> <replaceable>number</replaceable> <replaceable>number</replaceable> <replaceable>string</replaceable> ; + <optional> <replaceable>string</replaceable> initial-key <replaceable>number</replaceable> <replaceable>number</replaceable> <replaceable>number</replaceable> <replaceable>string</replaceable> ; <optional>...</optional></optional> +}; +</programlisting> + + </sect2> + <sect2 id="managed-keys"> + <title><command>managed-keys</command> Statement Definition + and Usage</title> + <para> + The <command>managed-keys</command> statement, like + <command>trusted-keys</command>, defines DNSSEC + security roots. The difference is that + <command>managed-keys</command> can be kept up to date + automatically, without intervention from the resolver + operator. + </para> + <para> + 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 + <command>trusted-keys</command> 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 + <command>trusted-keys</command> statement with the new key. + </para> + <para> + If, however, the zone were listed in a + <command>managed-keys</command> statement instead, then the + zone owner could add a "stand-by" key to the zone in advance. + <command>named</command> would store the stand-by key, and + when the original key was revoked, <command>named</command> + 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. + </para> + <para> + A <command>managed-keys</command> 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 (as of + <acronym>BIND</acronym> 9.7.0) is <literal>initial-key</literal>. + This means the <command>managed-keys</command> statement must + contain a copy of the initializing key. (Future releases may + allow keys to be initialized by other methods, eliminating this + requirement.) + </para> + <para> + Consequently, a <command>managed-keys</command> statement + appears similar to a <command>trusted-keys</command>, differing + in the presence of the second field, containing the keyword + <literal>initial-key</literal>. The difference is, whereas the + keys listed in a <command>trusted-keys</command> continue to be + trusted until they are removed from + <filename>named.conf</filename>, an initializing key listed + in a <command>managed-keys</command> statement is only trusted + <emphasis>once</emphasis>: for as long as it takes to load the + managed key database and start the RFC 5011 key maintenance + process. + </para> + <para> + The first time <command>named</command> runs with a managed key + configured in <filename>named.conf</filename>, it fetches the + DNSKEY RRset directly from the zone apex, and validates it + using the key specified in the <command>managed-keys</command> + statement. If the DNSKEY RRset is validly signed, then it is + used as the basis for a new managed keys database. + </para> + <para> + From that point on, whenever <command>named</command> runs, it + sees the <command>managed-keys</command> 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 <command>managed-keys</command> is not + used to validate answers; it has been superseded by the key or + keys stored in the managed keys database. + </para> + <para> + The next time <command>named</command> runs after a name + has been <emphasis>removed</emphasis> from the + <command>managed-keys</command> 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. + </para> + <para> + <command>named</command> only maintains a single managed keys + database; consequently, unlike <command>trusted-keys</command>, + <command>managed-keys</command> may only be set at the top + level of <filename>named.conf</filename>, not within a view. + </para> + <para> + In the current implementation, the managed keys database is + stored as a master-format zone file called + <filename>managed-keys.bind</filename>. When the key database + is changed, the zone is updated. As with any other dynamic + zone, changes will be written into a journal file, + <filename>managed-keys.bind.jnl</filename>. They are committed + to the master file as soon as possible afterward; in the case + of the managed key database, this will usually occur within 30 + seconds. So, whenever <command>named</command> is using + automatic key maintenance, those two files can be expected to + exist in the working directory. (For this reason among others, + the working directory should be always be writable by + <command>named</command>.) + </para> + <para> + If the <command>dnssec-lookaside</command> option is + set to <userinput>auto</userinput>, <command>named</command> + will automatically initialize a managed key for the + zone <literal>dlv.isc.org</literal>. The key that is + used to initialize the key maintenance process is built + into <command>named</command>, and can be overridden + from <command>bindkeys-file</command>. + </para> </sect2> <sect2 id="view_statement_grammar"> @@ -8746,11 +9908,12 @@ XXX: end of RFC1918 addresses #defined out --> // This should match our internal networks. match-clients { 10.0.0.0/8; }; - // Provide recursive service to internal clients only. + // Provide recursive service to internal + // clients only. recursion yes; - // Provide a complete view of the example.com zone - // including addresses of internal hosts. + // Provide a complete view of the example.com + // zone including addresses of internal hosts. zone "example.com" { type master; file "example-internal.db"; @@ -8758,14 +9921,15 @@ XXX: end of RFC1918 addresses #defined out --> }; view "external" { - // Match all clients not matched by the previous view. + // 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. + // Provide a restricted view of the example.com + // zone containing only publicly accessible hosts. zone "example.com" { type master; file "example-external.db"; @@ -8784,8 +9948,9 @@ view "external" { <optional> allow-query-on { <replaceable>address_match_list</replaceable> }; </optional> <optional> allow-transfer { <replaceable>address_match_list</replaceable> }; </optional> <optional> allow-update { <replaceable>address_match_list</replaceable> }; </optional> - <optional> update-policy { <replaceable>update_policy_rule</replaceable> <optional>...</optional> }; </optional> - <optional> also-notify { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> + <optional> update-policy <replaceable>local</replaceable> | { <replaceable>update_policy_rule</replaceable> <optional>...</optional> }; </optional> + <optional> also-notify { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; + <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> <optional> check-names (<constant>warn</constant>|<constant>fail</constant>|<constant>ignore</constant>) ; </optional> <optional> check-mx (<constant>warn</constant>|<constant>fail</constant>|<constant>ignore</constant>) ; </optional> <optional> check-wildcard <replaceable>yes_or_no</replaceable>; </optional> @@ -8821,6 +9986,7 @@ view "external" { <optional> min-retry-time <replaceable>number</replaceable> ; </optional> <optional> max-retry-time <replaceable>number</replaceable> ; </optional> <optional> key-directory <replaceable>path_name</replaceable>; </optional> + <optional> auto-dnssec <constant>allow</constant>|<constant>maintain</constant>|<constant>create</constant>|<constant>off</constant>; </optional> <optional> zero-no-soa-ttl <replaceable>yes_or_no</replaceable> ; </optional> }; @@ -8832,8 +9998,11 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea <optional> allow-transfer { <replaceable>address_match_list</replaceable> }; </optional> <optional> allow-update-forwarding { <replaceable>address_match_list</replaceable> }; </optional> <optional> update-check-ksk <replaceable>yes_or_no</replaceable>; </optional> + <optional> dnssec-dnskey-kskonly <replaceable>yes_or_no</replaceable>; </optional> + <optional> dnssec-secure-to-insecure <replaceable>yes_or_no</replaceable> ; </optional> <optional> try-tcp-refresh <replaceable>yes_or_no</replaceable>; </optional> - <optional> also-notify { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> + <optional> also-notify { <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; + <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> <optional> check-names (<constant>warn</constant>|<constant>fail</constant>|<constant>ignore</constant>) ; </optional> <optional> dialup <replaceable>dialup_option</replaceable> ; </optional> <optional> file <replaceable>string</replaceable> ; </optional> @@ -8846,7 +10015,9 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea <optional> ixfr-from-differences <replaceable>yes_or_no</replaceable>; </optional> <optional> ixfr-tmp-file <replaceable>string</replaceable> ; </optional> <optional> maintain-ixfr-base <replaceable>yes_or_no</replaceable> ; </optional> - <optional> masters <optional>port <replaceable>ip_port</replaceable></optional> { ( <replaceable>masters_list</replaceable> | <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> <optional>key <replaceable>key</replaceable></optional> ) ; <optional>...</optional> }; </optional> + <optional> masters <optional>port <replaceable>ip_port</replaceable></optional> { ( <replaceable>masters_list</replaceable> | <replaceable>ip_addr</replaceable> + <optional>port <replaceable>ip_port</replaceable></optional> + <optional>key <replaceable>key</replaceable></optional> ) ; <optional>...</optional> }; </optional> <optional> max-ixfr-log-size <replaceable>number</replaceable> ; </optional> <optional> max-transfer-idle-in <replaceable>number</replaceable> ; </optional> <optional> max-transfer-idle-out <replaceable>number</replaceable> ; </optional> @@ -8859,7 +10030,8 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea <optional> transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> alt-transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> - <optional> alt-transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> + <optional> alt-transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) + <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> use-alt-transfer-source <replaceable>yes_or_no</replaceable>; </optional> <optional> notify-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> notify-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> @@ -8877,7 +10049,7 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea type hint; file <replaceable>string</replaceable> ; <optional> delegation-only <replaceable>yes_or_no</replaceable> ; </optional> - <optional> check-names (<constant>warn</constant>|<constant>fail</constant>|<constant>ignore</constant>) ; // Not Implemented. </optional> + <optional> check-names (<constant>warn</constant>|<constant>fail</constant>|<constant>ignore</constant>) ; </optional> // Not Implemented. }; zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replaceable></optional> { @@ -8891,14 +10063,18 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea <optional> masterfile-format (<constant>text</constant>|<constant>raw</constant>) ; </optional> <optional> forward (<constant>only</constant>|<constant>first</constant>) ; </optional> <optional> forwarders { <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> - <optional> masters <optional>port <replaceable>ip_port</replaceable></optional> { ( <replaceable>masters_list</replaceable> | <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> <optional>key <replaceable>key</replaceable></optional> ) ; <optional>...</optional> }; </optional> + <optional> masters <optional>port <replaceable>ip_port</replaceable></optional> { ( <replaceable>masters_list</replaceable> | <replaceable>ip_addr</replaceable> + <optional>port <replaceable>ip_port</replaceable></optional> + <optional>key <replaceable>key</replaceable></optional> ) ; <optional>...</optional> }; </optional> <optional> max-transfer-idle-in <replaceable>number</replaceable> ; </optional> <optional> max-transfer-time-in <replaceable>number</replaceable> ; </optional> <optional> pubkey <replaceable>number</replaceable> <replaceable>number</replaceable> <replaceable>number</replaceable> <replaceable>string</replaceable> ; </optional> <optional> transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> - <optional> transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> + <optional> transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) + <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> alt-transfer-source (<replaceable>ip4_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> - <optional> alt-transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> + <optional> alt-transfer-source-v6 (<replaceable>ip6_addr</replaceable> | <constant>*</constant>) + <optional>port <replaceable>ip_port</replaceable></optional> ; </optional> <optional> use-alt-transfer-source <replaceable>yes_or_no</replaceable>; </optional> <optional> zone-statistics <replaceable>yes_or_no</replaceable> ; </optional> <optional> database <replaceable>string</replaceable> ; </optional> @@ -8910,6 +10086,14 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea }; zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replaceable></optional> { + type static-stub; + <optional> allow-query { <replaceable>address_match_list</replaceable> }; </optional> + <optional> server-addresses { <optional> <replaceable>ip_addr</replaceable> ; ... </optional> }; </optional> + <optional> server-names { <optional> <replaceable>namelist</replaceable> </optional> }; </optional> + <optional> zone-statistics <replaceable>yes_or_no</replaceable> ; </optional> +}; + +zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replaceable></optional> { type forward; <optional> forward (<constant>only</constant>|<constant>first</constant>) ; </optional> <optional> forwarders { <optional> <replaceable>ip_addr</replaceable> <optional>port <replaceable>ip_port</replaceable></optional> ; ... </optional> }; </optional> @@ -9056,6 +10240,55 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea <row rowsep="0"> <entry colname="1"> <para> + <varname>static-stub</varname> + </para> + </entry> + <entry colname="2"> + <para> + 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. + </para> + <para> + Zone data is configured via the + <command>server-addresses</command> and + <command>server-names</command> zone options. + </para> + <para> + 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 <command>rndc dumpdb -all</command>. + 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. + </para> + <para> + 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. + </para> + <para> + Each static-stub zone is configured with + internally generated NS and (if necessary) + glue A or AAAA RRs + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> <varname>forward</varname> </para> </entry> @@ -9270,6 +10503,7 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea received from the network. The default varies according to zone type. For <command>master</command> zones the default is <command>fail</command>. For <command>slave</command> zones the default is <command>warn</command>. + It is not implemented for <command>hint</command> zones. </para> </listitem> </varlistentry> @@ -9335,6 +10569,16 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea </varlistentry> <varlistentry> + <term><command>dnssec-dnskey-kskonly</command></term> + <listitem> + <para> + See the description of + <command>dnssec-dnskey-kskonly</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><command>try-tcp-refresh</command></term> <listitem> <para> @@ -9569,6 +10813,84 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea </varlistentry> <varlistentry> + <term><command>server-addresses</command></term> + <listitem> + <para> + 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. + </para> + <para> + For example, if "example.com" is configured as a + static-stub zone with 192.0.2.1 and 2001:db8::1234 + in a <command>server-addresses</command> option, + the following RRs will be internally configured. + </para> +<programlisting>example.com. NS example.com. +example.com. A 192.0.2.1 +example.com. AAAA 2001:db8::1234</programlisting> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>server-names</command></term> + <listitem> + <para> + 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 + <command>named</command> 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 + <command>server-names</command> option, but + "ns.example.net" cannot, and will be rejected by + the configuration parser. + </para> + <para> + 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 <command>server-names</command> option, + the following RRs will be internally configured. + </para> +<programlisting>example.com. NS ns1.example.net. +example.com. NS ns2.example.net. +</programlisting> + <para> + 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. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><command>sig-validity-interval</command></term> <listitem> <para> @@ -9716,6 +11038,51 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea </varlistentry> <varlistentry> + <term><command>auto-dnssec</command></term> + <listitem> + <para> + Zones configured for dynamic DNS may also use this + option to allow varying levels of automatic DNSSEC key + management. There are four possible settings: + </para> + <para> + <command>auto-dnssec allow;</command> permits + keys to be updated and the zone fully re-signed + whenever the user issues the command <command>rndc sign + <replaceable>zonename</replaceable></command>. + </para> + <para> + <command>auto-dnssec maintain;</command> includes the + above, but also automatically adjusts the zone's DNSSEC + keys on schedule, according to the keys' timing metadata + (see <xref linkend="man.dnssec-keygen"/> and + <xref linkend="man.dnssec-settime"/>). The command + <command>rndc sign + <replaceable>zonename</replaceable></command> causes + <command>named</command> to load keys from the key + repository and sign the zone with all keys that are + active. + <command>rndc loadkeys + <replaceable>zonename</replaceable></command> causes + <command>named</command> 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. + </para> + <para> + <command>auto-dnssec create;</command> includes the + above, but also allows <command>named</command> + to create new keys in the key repository when needed. + (NOTE: This option is not yet implemented; the syntax is + being reserved for future use.) + </para> + <para> + The default setting is <command>auto-dnssec off</command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><command>multi-master</command></term> <listitem> <para> @@ -9735,6 +11102,16 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea </listitem> </varlistentry> + <varlistentry> + <term><command>dnssec-secure-to-insecure</command></term> + <listitem> + <para> + See the description of + <command>dnssec-secure-to-insecure</command> in <xref linkend="boolean_options"/>. + </para> + </listitem> + </varlistentry> + </variablelist> </sect3> @@ -9753,15 +11130,14 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea record of any name in the zone. </para> <para> - The <command>update-policy</command> clause is new - in <acronym>BIND</acronym> 9 and allows more fine-grained - control over what updates are allowed. A set of rules - is specified, where each rule either grants or denies - permissions for one or more names to be updated by - one or more identities. If the dynamic update request - message is signed (that is, it includes either a TSIG - or SIG(0) record), the identity of the signer can be - determined. + The <command>update-policy</command> clause + allows more fine-grained control over what updates are + allowed. A set of rules is specified, where each rule + either grants or denies permissions for one or more + names to be updated by one or more identities. If + the dynamic update request message is signed (that is, + it includes either a TSIG or SIG(0) record), the + identity of the signer can be determined. </para> <para> Rules are specified in the <command>update-policy</command> @@ -9773,24 +11149,53 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea only examines the signer of a message; the source address is not relevant. </para> + <para> + There is a pre-defined <command>update-policy</command> + rule which can be switched on with the command + <command>update-policy local;</command>. + Switching on this rule in a zone causes + <command>named</command> to generate a TSIG session + key and place it in a file, and to allow that key + to update the zone. (By default, the file is + <filename>/var/run/named/session.key</filename>, the key + name is "local-ddns" and the key algorithm is HMAC-SHA256, + but these values are configurable with the + <command>session-keyfile</command>, + <command>session-keyname</command> and + <command>session-keyalg</command> options, respectively). + </para> + <para> + A client running on the local system, and with appropriate + permissions, may read that file and use the key 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: + </para> + + <programlisting>update-policy { grant local-ddns zonesub any; }; + </programlisting> <para> - This is how a rule definition looks: + The command <command>nsupdate -l</command> sends update + requests to localhost, and signs them using the session key. + </para> + + <para> + Other rule definitions look like this: </para> <programlisting> -( <command>grant</command> | <command>deny</command> ) <replaceable>identity</replaceable> <replaceable>nametype</replaceable> <replaceable>name</replaceable> <optional> <replaceable>types</replaceable> </optional> +( <command>grant</command> | <command>deny</command> ) <replaceable>identity</replaceable> <replaceable>nametype</replaceable> <optional> <replaceable>name</replaceable> </optional> <optional> <replaceable>types</replaceable> </optional> </programlisting> <para> Each rule grants or denies privileges. Once a message has successfully matched a rule, the operation is immediately - granted - or denied and no further rules are examined. A rule is matched - when the signer matches the identity field, the name matches the - name field in accordance with the nametype field, and the type - matches - the types specified in the type field. + granted or denied and no further rules are examined. A rule + is matched when the signer matches the identity field, the + name matches the name field in accordance with the nametype + field, and the type matches the types specified in the type + field. </para> <para> No signer is required for <replaceable>tcp-self</replaceable> @@ -9817,7 +11222,7 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea </para> <para> - The <replaceable>nametype</replaceable> field has 12 + The <replaceable>nametype</replaceable> field has 13 values: <varname>name</varname>, <varname>subdomain</varname>, <varname>wildcard</varname>, <varname>self</varname>, @@ -9825,7 +11230,8 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea <varname>krb5-self</varname>, <varname>ms-self</varname>, <varname>krb5-subdomain</varname>, <varname>ms-subdomain</varname>, - <varname>tcp-self</varname> and <varname>6to4-self</varname>. + <varname>tcp-self</varname>, <varname>6to4-self</varname>, + <varname>zonesub</varname>, and <varname>external</varname>. </para> <informaltable> <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table"> @@ -9863,6 +11269,28 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea <row rowsep="0"> <entry colname="1"> <para> + <varname>zonesub</varname> + </para> + </entry> <entry colname="2"> + <para> + This rule is similar to subdomain, except that + it matches when the name being updated is a + subdomain of the zone in which the + <command>update-policy</command> statement + appears. This obviates the need to type the zone + name twice, and enables the use of a standard + <command>update-policy</command> statement in + multiple zones without modification. + </para> + <para> + When this rule is used, the + <replaceable>name</replaceable> field is omitted. + </para> + </entry> + </row> + <row rowsep="0"> + <entry colname="1"> + <para> <varname>wildcard</varname> </para> </entry> <entry colname="2"> @@ -9950,7 +11378,7 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea </entry> <entry colname="2"> <para> Allow the 6to4 prefix to be update by any TCP - conection from the 6to4 network or from the + connection from the 6to4 network or from the corresponding IPv4 address. This is intended to allow NS or DNAME RRsets to be added to the reverse tree. @@ -9961,14 +11389,56 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea </note> </entry> </row> + <row rowsep="0"> + <entry colname="1"> + <para> + <varname>external</varname> + </para> + </entry> <entry colname="2"> + <para> + This rule allows <command>named</command> + to defer the decision of whether to allow a + given update to an external daemon. + </para> + <para> + The method of communicating with the daemon is + specified in the <replaceable>identity</replaceable> + field, the format of which is + "<constant>local:</constant><replaceable>path</replaceable>", + where <replaceable>path</replaceable> is the location + of a UNIX-domain socket. (Currently, "local" is the + only supported mechanism.) + </para> + <para> + Requests to the external daemon are sent over the + UNIX-domain socket as datagrams with the following + format: + </para> + <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)</programlisting> + <para> + 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. + </para> + </entry> + </row> </tbody> </tgroup> </informaltable> <para> In all cases, the <replaceable>name</replaceable> - field must - specify a fully-qualified domain name. + field must specify a fully-qualified domain name. </para> <para> @@ -11381,7 +12851,7 @@ WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM. </para> <programlisting>$ORIGIN 0.0.192.IN-ADDR.ARPA. -$GENERATE 1-2 0 NS SERVER$.EXAMPLE. +$GENERATE 1-2 @ NS SERVER$.EXAMPLE. $GENERATE 1-127 $ CNAME $.0</programlisting> <para> @@ -11396,6 +12866,32 @@ $GENERATE 1-127 $ CNAME $.0</programlisting> 127.0.0.192.IN-ADDR.ARPA. CNAME 127.0.0.0.192.IN-ADDR.ARPA. </programlisting> + <para> + 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. + </para> + +<programlisting> +$ORIGIN EXAMPLE. +$GENERATE 1-127 HOST-$ A 1.2.3.$ +$GENERATE 1-127 HOST-$ MX "0 ."</programlisting> + + <para> + is equivalent to + </para> + +<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 . +</programlisting> + <informaltable colsep="0" rowsep="0"> <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="3Level-table"> <colspec colname="1" colnum="1" colsep="0" colwidth="0.875in"/> @@ -11445,20 +12941,30 @@ $GENERATE 1-127 $ CNAME $.0</programlisting> Available output forms are decimal (<command>d</command>), octal - (<command>o</command>) and hexadecimal + (<command>o</command>), hexadecimal (<command>x</command> or <command>X</command> - for uppercase). The default modifier is + for uppercase) and nibble + (<command>n</command> or <command>N</command>\ + for uppercase). The default modifier is <command>${0,0,d}</command>. If the <command>lhs</command> is not absolute, the current <command>$ORIGIN</command> is appended to the name. </para> - <para> - For compatibility with earlier versions, <command>$$</command> is still - recognized as indicating a literal $ in the output. - </para> - </entry> - </row> + <para> + 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. + </para> + <para> + For compatibility with earlier versions, + <command>$$</command> is still recognized as + indicating a literal $ in the output. + </para> + </entry> + </row> <row rowsep="0"> <entry colname="1"> <para><command>ttl</command></para> @@ -11497,8 +13003,7 @@ $GENERATE 1-127 $ CNAME $.0</programlisting> </entry> <entry colname="2"> <para> - At present the only supported types are - PTR, CNAME, DNAME, A, AAAA and NS. + Any valid type. </para> </entry> </row> @@ -11508,8 +13013,7 @@ $GENERATE 1-127 $ CNAME $.0</programlisting> </entry> <entry colname="2"> <para> - <command>rhs</command> is a domain name. It is processed - similarly to lhs. + <command>rhs</command>, optionally, quoted string. </para> </entry> </row> @@ -11668,9 +13172,12 @@ $GENERATE 1-127 $ CNAME $.0</programlisting> </entry> <entry colname="2"> <para> - The number of RRsets per RR type (positive - or negative) and nonexistent names stored in the - cache database. + 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"). Maintained per view. </para> </entry> @@ -12639,6 +14146,13 @@ $GENERATE 1-127 $ CNAME $.0</programlisting> <entry colname="3"> <para> 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 <command>port</command> option.) + This may be an indication of a cache + poisoning attempt. </para> </entry> </row> @@ -13106,14 +14620,17 @@ $GENERATE 1-127 $ CNAME $.0</programlisting> </para> <programlisting> -// Set up an ACL named "bogusnets" that will block RFC1918 space -// and some reserved space, which is commonly used in spoofing attacks. +// Set up an ACL named "bogusnets" that will block +// RFC1918 space and some reserved space, which is +// commonly used in spoofing attacks. acl bogusnets { - 0.0.0.0/8; 1.0.0.0/8; 2.0.0.0/8; 192.0.2.0/24; 224.0.0.0/3; - 10.0.0.0/8; 172.16.0.0/12; 192.168.0.0/16; + 0.0.0.0/8; 1.0.0.0/8; 2.0.0.0/8; 192.0.2.0/24; + 224.0.0.0/3; 10.0.0.0/8; 172.16.0.0/12; + 192.168.0.0/16; }; -// Set up an ACL called our-nets. Replace this with the real IP numbers. +// Set up an ACL called our-nets. Replace this with the +// real IP numbers. acl our-nets { x.x.x.x/24; x.x.x.x/21; }; options { ... @@ -14756,8 +16273,12 @@ zone "example.com" { </bibliography> </sect2> </sect1> + + <xi:include href="libdns.xml"/> + </appendix> + <reference id="Bv9ARM.ch10"> <title>Manual pages</title> <xi:include href="../../bin/dig/dig.docbook"/> @@ -14765,15 +16286,23 @@ zone "example.com" { <xi:include href="../../bin/dnssec/dnssec-dsfromkey.docbook"/> <xi:include href="../../bin/dnssec/dnssec-keyfromlabel.docbook"/> <xi:include href="../../bin/dnssec/dnssec-keygen.docbook"/> + <xi:include href="../../bin/dnssec/dnssec-revoke.docbook"/> + <xi:include href="../../bin/dnssec/dnssec-settime.docbook"/> <xi:include href="../../bin/dnssec/dnssec-signzone.docbook"/> <xi:include href="../../bin/check/named-checkconf.docbook"/> <xi:include href="../../bin/check/named-checkzone.docbook"/> <xi:include href="../../bin/named/named.docbook"/> + <xi:include href="../../bin/tools/named-journalprint.docbook"/> <!-- named.conf.docbook and others? --> <xi:include href="../../bin/nsupdate/nsupdate.docbook"/> <xi:include href="../../bin/rndc/rndc.docbook"/> <xi:include href="../../bin/rndc/rndc.conf.docbook"/> - <xi:include href="../../bin/rndc/rndc-confgen.docbook"/> + <xi:include href="../../bin/confgen/rndc-confgen.docbook"/> + <xi:include href="../../bin/confgen/ddns-confgen.docbook"/> + <xi:include href="../../bin/tools/arpaname.docbook"/> + <xi:include href="../../bin/tools/genrandom.docbook"/> + <xi:include href="../../bin/tools/isc-hmac-fixup.docbook"/> + <xi:include href="../../bin/tools/nsec3hash.docbook"/> </reference> </book> |