2533. [doc] ARM: document @ (at-sign). [RT #17144

diff --git a/CHANGES b/CHANGES
index bb0f284409d6a83ee81ae61c61b2d4abd87ec3e7..029580f70061dab32fd798a5ef22573ffd998b49 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -100,6 +100,8 @@
 2688.  [bug]           Use INTERFACE_F_POINTTOPOINT, not IFF_POINTOPOINT,
                        to decide to fetch the destination address. [RT #20305]
 
+2533.  [doc]           ARM: document @ (at-sign). [RT #17144]
+
        --- 9.5.2 released ---
 
 2681.  [bug]           IPSECKEY RR of gateway type 3 was not correctly

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index 334f9be2a49599e3593aa2ecf3fc902c606d3c06..156ea83840450a5d6badd84fbbab8c82c89012fc 100644 (file)
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -35,7 +35,7 @@
  - PERFORMANCE OF THIS SOFTWARE.
 -->
 
-<!-- File: $Id: Bv9ARM-book.xml,v 1.340.24.46 2009/11/10 19:47:34 each Exp $ -->
+<!-- File: $Id: Bv9ARM-book.xml,v 1.340.24.47 2009/12/03 03:39:45 marka Exp $ -->
 <book xmlns:xi="http://www.w3.org/2001/XInclude">
   <title>BIND 9 Administrator Reference Manual</title>
 
@@ -2444,14 +2444,17 @@ allow-update { key host1-host2. ;};
          To enable <command>named</command> to respond appropriately
          to DNS requests from DNSSEC aware clients,
          <command>dnssec-enable</command> must be set to yes.
+          (This is the default setting.)
         </para>
 
        <para>
          To enable <command>named</command> to validate answers from
-         other servers both <command>dnssec-enable</command> and
-         <command>dnssec-validation</command> must be set and some
-         <command>trusted-keys</command> must be configured
-         into <filename>named.conf</filename>.
+         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>.
         </para>
          
        <para>
@@ -2530,6 +2533,41 @@ options {
          the root key is not valid.
        </note>
 
+       <para>
+         When DNSSEC validation is enabled and properly configured,
+         the resolver will reject any answers from signed, secure zones
+         which fail to validate, and will return SERVFAIL to the client.
+       </para>
+
+       <para>
+         Responses may fail to validate for any of several reasons,
+         including missing, expired, or invalid signatures, a key which
+         does not match the DS RRset in the parent zone, or an insecure
+         response from a zone which, according to its parent, should have
+         been secure.  
+       </para>
+
+       <note>
+         <para>
+           When the validator receives a response from an unsigned zone
+           that has a signed parent, it must confirm with the parent
+           that the zone was intentionally left unsigned.  It does
+           this by verifying, via signed and validated NSEC/NSEC3 records,
+           that the parent zone contains no DS records for the child.
+         </para>
+         <para>
+           If the validator <emphasis>can</emphasis> prove that the zone
+           is insecure, then the response is accepted.  However, if it
+           cannot, then it must assume an insecure response to be a
+           forgery; it rejects the response and logs an error.
+         </para>
+         <para>
+            The logged error reads "insecurity proof failed" and
+            "got insecure response; parent indicates it should be secure".
+           (Prior to BIND 9.7, the logged error was "not insecure".
+            This referred to the zone, not the response.)
+         </para>
+       </note>
       </sect2>
 
     </sect1>
@@ -2538,10 +2576,9 @@ options {
 
       <para>
         <acronym>BIND</acronym> 9 fully supports all currently
-        defined forms of IPv6
-        name to address and address to name lookups.  It will also use
-        IPv6 addresses to make queries when running on an IPv6 capable
-        system.
+        defined forms of IPv6 name to address and address to name
+        lookups.  It will also use IPv6 addresses to make queries when
+        running on an IPv6 capable system.
       </para>
 
       <para>
@@ -4323,8 +4360,7 @@ category notify { null; };
                     <para>
                       Lame servers.  These are misconfigurations
                       in remote servers, discovered by BIND 9 when trying to
-                      query
-                      those servers during resolution.
+                      query those servers during resolution.
                     </para>
                   </entry>
                 </row>
@@ -11031,6 +11067,16 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea
             Master File Directives include <command>$ORIGIN</command>, <command>$INCLUDE</command>,
             and <command>$TTL.</command>
           </para>
+          <sect3>
+            <title>The <command>@</command> (at-sign)</title>
+            <para>
+              When used in the label (or name) field, the asperand or
+              at-sign (@) symbol represents the current origin.
+              At the start of the zone file, it is the 
+              &lt;<varname>zone_name</varname>&gt; (followed by
+              trailing dot).
+            </para>
+          </sect3>
           <sect3>
             <title>The <command>$ORIGIN</command> Directive</title>
             <para>
@@ -11042,7 +11088,8 @@ zone <replaceable>zone_name</replaceable> <optional><replaceable>class</replacea
              sets the domain name that will be appended to any
               unqualified records. When a zone is first read in there
               is an implicit <command>$ORIGIN</command>
-              &lt;<varname>zone-name</varname>&gt;<command>.</command>
+              &lt;<varname>zone_name</varname>&gt;<command>.</command>
+              (followed by trailing dot).
               The current <command>$ORIGIN</command> is appended to
               the domain specified in the <command>$ORIGIN</command>
               argument if it is not absolute.