From 5a23e7abd157e39eb4ce98081c708bbeea12246f Mon Sep 17 00:00:00 2001
From: Evan Hunt <each@isc.org>
Date: Fri, 21 Feb 2020 13:08:49 -0800
Subject: [PATCH] document max-ixfr-ratio

---
 doc/arm/Bv9ARM-book.xml | 53 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 48 insertions(+), 5 deletions(-)

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index 89c54f9654..a006816a29 100644
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -1474,30 +1474,43 @@ controls {
 
       <para>
 	The incremental zone transfer (IXFR) protocol is a way for
-	slave servers to transfer only changed data, instead of having to
+	secondary servers to transfer only changed data, instead of having to
 	transfer the entire zone. The IXFR protocol is specified in RFC
 	1995. See <xref linkend="proposed_standards"/>.
       </para>
 
       <para>
-	When acting as a master, <acronym>BIND</acronym> 9
+	When acting as a primary server, <acronym>BIND</acronym> 9
 	supports IXFR for those zones
 	where the necessary change history information is available. These
-	include master zones maintained by dynamic update and slave zones
+	include primary zones maintained by dynamic update and secondary zones
 	whose data was obtained by IXFR.  For manually maintained master
-	zones, and for slave zones obtained by performing a full zone
+	zones, and for secondary zones obtained by performing a full zone
 	transfer (AXFR), IXFR is supported only if the option
 	<command>ixfr-from-differences</command> is set
 	to <userinput>yes</userinput>.
       </para>
 
       <para>
-	When acting as a slave, <acronym>BIND</acronym> 9 will
+	When acting as a secondary server, <acronym>BIND</acronym> 9 will
 	attempt to use IXFR unless
 	it is explicitly disabled. For more information about disabling
 	IXFR, see the description of the <command>request-ixfr</command> clause
 	of the <command>server</command> statement.
       </para>
+
+      <para>
+	When a secondary server receives a zone via AXFR, it creates a
+	new copy of the zone database and then swaps it into place; during
+	the loading process, queries continue to be served from the old
+	database with no interference. When receiving a zone via IXFR,
+	however, changes are applied to the running zone, which may
+	degrade query performance during the transfer.  If a server
+	receiving an IXFR request determines that the response size would
+	be similar in size to an AXFR response, it may wish to send AXFR
+	instead. The threshold at which this determination is made can
+	be configured using the <command>max-ixfr-ratio</command> option.
+      </para>
     </section>
 
     <section xml:id="split_dns"><info><title>Split DNS</title></info>
@@ -4656,6 +4669,25 @@ badresp:1,adberr:0,findfail:0,valfail:0]
 	    </listitem>
 	  </varlistentry>
 
+	  <varlistentry>
+	    <term><command>max-ixfr-ratio</command></term>
+	    <listitem>
+	      <para>
+		Sets the size threshold (expressed as a percentage
+		of the size of the full zone) beyond which
+		<command>named</command> will choose to use an AXFR
+		response rather than IXFR when answering zone transfer
+		requests.  See <xref linkend="incremental_zone_transfers"/>.
+	      </para>
+	      <para>
+		The minimum value is <literal>1%</literal>. The keyword
+		<literal>unlimited</literal> disables ratio checking and
+		allows IXFRs of any size.  The default is
+		<literal>100%</literal>.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+
 	  <varlistentry>
 	    <term><command>new-zones-directory</command></term>
 	    <listitem>
@@ -12424,6 +12456,17 @@ view "external" {
 		</listitem>
 	      </varlistentry>
 
+	      <varlistentry>
+		<term><command>max-ixfr-ratio</command></term>
+		<listitem>
+		  <para>
+		    See the description of
+		    <command>max-ixfr-ratio</command> in
+		    <xref linkend="options"/>.
+		  </para>
+		</listitem>
+	      </varlistentry>
+
 	      <varlistentry>
 		<term><command>max-journal-size</command></term>
 		<listitem>