[master] improve prefetch doc

diff --git a/CHANGES b/CHANGES
index 66cba77f0a3072375ca7f5d04b1f7916d790ec57..fcd52335fba053b6f32c595d0e52e124c485d7da 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,10 @@
-3703.  [func]          Prefetch about to expire records if they are queried
-                       for, see prefetch option for details. [RT #35041]
+3703.  [func]          To improve recursive resolver performance, cache
+                       records which are still being requested by clients
+                       can now be automatically refreshed from the
+                       authoritative server before they expire, reducing
+                       or eliminating the time window in which no answer
+                       is available in the cache. See the "prefetch" option
+                       for more details. [RT #35041]
 
 3702.  [func]          'dnssec-coverage -l' option specifies a length
                        of time to check for coverage; events further into

diff --git a/README b/README
index b849995612e1954950764c8c247ae67a4a5709fc..72368002f7581d966ecf8fc28cc8e5d56b751f91 100644 (file)
--- a/README
+++ b/README
@@ -1,104 +1,116 @@
 BIND 9
 
-        BIND version 9 is a major rewrite of nearly all aspects of the
-        underlying BIND architecture.  Some of the important features of
-        BIND 9 are:
+       BIND version 9 is a major rewrite of nearly all aspects of the
+       underlying BIND architecture.  Some of the important features of
+       BIND 9 are:
 
-                - DNS Security
-                        DNSSEC (signed zones)
-                        TSIG (signed DNS requests)
+               - DNS Security
+                       DNSSEC (signed zones)
+                       TSIG (signed DNS requests)
 
-                - IP version 6
-                        Answers DNS queries on IPv6 sockets
-                        IPv6 resource records (AAAA)
-                        Experimental IPv6 Resolver Library
+               - IP version 6
+                       Answers DNS queries on IPv6 sockets
+                       IPv6 resource records (AAAA)
+                       Experimental IPv6 Resolver Library
 
-                - DNS Protocol Enhancements
-                        IXFR, DDNS, Notify, EDNS0
-                        Improved standards conformance
+               - DNS Protocol Enhancements
+                       IXFR, DDNS, Notify, EDNS0
+                       Improved standards conformance
 
-                - Views
-                        One server process can provide multiple "views" of
-                        the DNS namespace, e.g. an "inside" view to certain
-                        clients, and an "outside" view to others.
+               - Views
+                       One server process can provide multiple "views" of
+                       the DNS namespace, e.g. an "inside" view to certain
+                       clients, and an "outside" view to others.
 
-                - Multiprocessor Support
+               - Multiprocessor Support
 
-                - Improved Portability Architecture
+               - Improved Portability Architecture
 
 
-        BIND version 9 development has been underwritten by the following
-        organizations:
+       BIND version 9 development has been underwritten by the following
+       organizations:
 
-                Sun Microsystems, Inc.
-                Hewlett Packard
-                Compaq Computer Corporation
-                IBM
-                Process Software Corporation
-                Silicon Graphics, Inc.
-                Network Associates, Inc.
-                U.S. Defense Information Systems Agency
-                USENIX Association
-                Stichting NLnet - NLnet Foundation
-                Nominum, Inc.
+               Sun Microsystems, Inc.
+               Hewlett Packard
+               Compaq Computer Corporation
+               IBM
+               Process Software Corporation
+               Silicon Graphics, Inc.
+               Network Associates, Inc.
+               U.S. Defense Information Systems Agency
+               USENIX Association
+               Stichting NLnet - NLnet Foundation
+               Nominum, Inc.
 
-        For a summary of functional enhancements in previous
-        releases, see the HISTORY file.
+       For a summary of functional enhancements in previous
+       releases, see the HISTORY file.
 
-        For a detailed list of user-visible changes from
-        previous releases, see the CHANGES file.
+       For a detailed list of user-visible changes from
+       previous releases, see the CHANGES file.
 
-        For up-to-date release notes and errata, see
-        http://www.isc.org/software/bind9/releasenotes
+       For up-to-date release notes and errata, see
+       http://www.isc.org/software/bind9/releasenotes
 
 BIND 9.10.0
 
-        BIND 9.10.0 includes a number of changes from BIND 9.9 and earlier
-        releases.  New features include:
-
-         - DNS Response-rate limiting (DNS RRL) blunts the impact of
-           reflection and amplification attacks.
-         - New zone file format "map" is an image of a zone database
-           that can be loaded directly into memory, allowing much faster
-           zone loading.
-         - Substantial improvement in response-policy zone (RPZ)
-           performance.  Up to 32 response-policy zones can be
-           configured with minimal performance loss.
-         - New RPZ client-IP triggers and drop policies.
-         - ACLs can now be specified based on geographic location
-           using the MaxMind GeoIP databases.
-         - New XML schema (version 3) for the statistics channel
-           includes many new statistics and uses a flattened XML tree
-           for faster parsing.
-         - A new stylesheet, based on the Google Charts API, displays
-           XML statistics in charts and graphs on javascript-enabled
-           browsers.
-         - The statistics channel can now provide data in JSON
-           format as well as XML.
-         - The internal and export versions of the BIND libraries
-           (libisc, libdns, etc) have been unified so that external
-           library clients can use the same libraries as BIND itself.
-         - New 'dnssec-coverage' tool to check DNSSEC key coverage
-           for a zone and report if a lapse in signing coverage has
-           been inadvertently scheduled.
-         - Signing algorithm flexibility and other improvements
-           for the "rndc" control channel.
-         - 'named-checkzone' and 'named-compilezone' can now read
-           journal files, allowing them to process dynamic zones.
-         - Multiple DLZ databases can now be configured.  Individual
-           zones can be configured to be served from a specific DLZ
-           database.  DLZ databases now serve zones of type "master"
-           and "redirect".
-         - "rndc zonestatus" reports information about a specified zone.
-         - "named" now listens on IPv6 as well as IPv4 interfaces
-           by default.
+       BIND 9.10.0 includes a number of changes from BIND 9.9 and earlier
+       releases.  New features include:
+
+        - DNS Response-rate limiting (DNS RRL) blunts the impact of
+          reflection and amplification attacks.
+        - New zone file format "map" is an image of a zone database
+          that can be loaded directly into memory, allowing much faster
+          zone loading.
+        - Substantial improvement in response-policy zone (RPZ)
+          performance.  Up to 32 response-policy zones can be
+          configured with minimal performance loss.
+        - To improve recursive resolver performance, cache records
+          which are still being requested by clients can now be
+          automatically refreshed from the authoritative server
+          before they expire, reducing or eliminating the time
+          window in which no answer is available in the cache.
+        - New RPZ client-IP triggers and drop policies.
+        - ACLs can now be specified based on geographic location
+          using the MaxMind GeoIP databases.
+        - New XML schema (version 3) for the statistics channel
+          includes many new statistics and uses a flattened XML tree
+          for faster parsing.
+        - A new stylesheet, based on the Google Charts API, displays
+          XML statistics in charts and graphs on javascript-enabled
+          browsers.
+        - The statistics channel can now provide data in JSON
+          format as well as XML.
+        - The internal and export versions of the BIND libraries
+          (libisc, libdns, etc) have been unified so that external
+          library clients can use the same libraries as BIND itself.
+        - New 'dnssec-coverage' tool to check DNSSEC key coverage
+          for a zone and report if a lapse in signing coverage has
+          been inadvertently scheduled.
+        - Signing algorithm flexibility and other improvements
+          for the "rndc" control channel.
+        - 'named-checkzone' and 'named-compilezone' can now read
+          journal files, allowing them to process dynamic zones.
+        - Multiple DLZ databases can now be configured.  Individual
+          zones can be configured to be served from a specific DLZ
+          database.  DLZ databases now serve zones of type "master"
+          and "redirect".
+        - "rndc zonestatus" reports information about a specified zone.
+        - "named" now listens on IPv6 as well as IPv4 interfaces
+          by default.
         - "named" now preserves the capitalization of names when
-           responding to queries.
-         - New 'named-rrchecker' tool to verify the syntactic
-           correctness of individual resource records.
-         - When re-signing a zone, the new "dnssec-signzone -Q" option
-           drops signatures from keys that are still published but are
-           no longer active.
+          responding to queries.
+        - new "dnssec-importkey" command allows the use of offline
+          DNSSEC keys with automatic DNSKEY management.
+        - New 'named-rrchecker' tool to verify the syntactic
+          correctness of individual resource records.
+        - When re-signing a zone, the new "dnssec-signzone -Q" option
+          drops signatures from keys that are still published but are
+          no longer active.
+        - "named-checkconf -px" will print the contents of configuration
+          files with the shared secrets obscured, making it easier to
+          share configuration (e.g. when submitting a bug report)
+          without revealing private information.
+
 
 BIND 9.9.0
 

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index b1dd4169e5a23f4f2afeb64cce93b7ca486f6083..158e4f7109dfdfcef34eb22e15a0bc7f469be7f9 100644 (file)
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -8737,17 +8737,36 @@ avoid-v6-udp-ports { 40000; range 50000 60000; };
               </listitem>
             </varlistentry>
 
-            <varlistentry>
-              <term><command>prefetch</command></term>
-              <listitem>
+           <varlistentry>
+             <term><command>prefetch</command></term>
+             <listitem>
                <para>
-                 Specifies the trigger ttl value (range [1..10])
-                 at which prefetch of the current query will be
-                 made and optionally the minimum ttl value that will be
-                 accepted for the records to be candidates for
-                 prefetching.  The defaults are 2 and 9 respectively.
-                 Setting a trigger ttl value of 0 will disable
-                 prefetching.  A minimum delta of 6 is enforced.
+                 When a query is received for cached data which
+                 is to expire shortly, <command>named</command> can
+                 refresh the data from the authoritative server
+                 immediately, ensuring that the cache always has an
+                 answer available.
+               </para>
+               <para>
+                 The <option>prefetch</option> specifies the the
+                 "trigger" TTL value at which prefetch of the current
+                 query will take place: when a cache record with a
+                 lower TTL value is encountered during query processing,
+                 it will be refreshed.  Valid trigger TTL values are 1 to
+                 10 seconds.  Setting a trigger TTL to zero disables
+                 prefetch.
+               <para>
+                 An optional second argument can be used
+                 to set the smallest <emphasis>original</emphasis>
+                 TTL value that will be accepted for a record to be
+                 eligible for prefetching.  The difference between
+                 the trigger TTL and the eligibility TTL must be
+                 at least 6 seconds.
+               </para>
+               </para>
+                 The default trigger and eligibility TTLs are
+                 <literal>2</literal> and <literal>9</literal>,
+                 respectively.
                </para>
              </listitem>
            </varlistentry>