Rework "rrset-order" documentation

Certain parts of the existing documentation for the "rrset-order"
statement are incorrect, others are ambiguous.  Rework the relevant
section of the ARM to make it clear and up-to-date with the source code.

(cherry picked from commit 2ac04dc9305438f424a3a11c540d505e44db013e)

diff --git a/doc/arm/Bv9ARM-book.xml b/doc/arm/Bv9ARM-book.xml
index 2c16e79073228918a50610451bf52ddef63f41de..69144b26d1b22ea29079af582d09ec30b93cc02a 100644 (file)
--- a/doc/arm/Bv9ARM-book.xml
+++ b/doc/arm/Bv9ARM-book.xml
@@ -8723,113 +8723,200 @@ avoid-v6-udp-ports { 40000; range 50000 60000; };
        </section>
        <section xml:id="rrset_ordering"><info><title xml:id="rrset_ordering_title">RRset Ordering</title></info>
 
-         <para>
-           When multiple records are returned in an answer, it may be
-           useful to configure the order of the records placed into the
-           response.
-           The <command>rrset-order</command> statement permits
-           configuration
-           of the ordering of the records in a multiple-record response.
-           See also the <command>sortlist</command> statement,
-           <xref linkend="the_sortlist_statement"/>.
-         </para>
-
-         <para>
-           An <command>order_spec</command> is defined as
-           follows:
-         </para>
-         <para>
-           <optional>class <replaceable>class_name</replaceable></optional>
-           <optional>type <replaceable>type_name</replaceable></optional>
-           <optional>name <replaceable>"domain_name"</replaceable></optional>
-           order <replaceable>ordering</replaceable>
-         </para>
-         <para>
-           If no class is specified, the default is <command>ANY</command>.
-           If no type is specified, the default is <command>ANY</command>.
-           If no name is specified, the default is "<command>*</command>" (asterisk).
-         </para>
-         <para>
-           The legal values for <command>ordering</command> are:
-         </para>
-         <informaltable colsep="0" rowsep="0">
-           <tgroup cols="2" colsep="0" rowsep="0" tgroupstyle="4Level-table">
-             <colspec colname="1" colnum="1" colsep="0" colwidth="0.750in"/>
-             <colspec colname="2" colnum="2" colsep="0" colwidth="3.750in"/>
-             <tbody>
-               <row rowsep="0">
-                 <entry colname="1">
-                   <para><command>fixed</command></para>
-                 </entry>
-                 <entry colname="2">
-                   <para>
-                     Records are returned in the order they
-                     are defined in the zone file.
-                   </para>
-                 </entry>
-               </row>
-               <row rowsep="0">
-                 <entry colname="1">
-                   <para><command>random</command></para>
-                 </entry>
-                 <entry colname="2">
-                   <para>
-                     Records are returned in a random order.
-                   </para>
-                 </entry>
-               </row>
-               <row rowsep="0">
-                 <entry colname="1">
-                   <para><command>cyclic</command></para>
-                 </entry>
-                 <entry colname="2">
-                   <para>
-                     Records are returned in a cyclic round-robin order, rotating by one record per query.
-                   </para>
-                   <para>
-                     If <acronym>BIND</acronym> is configured with the
-                     "--enable-fixed-rrset" option at compile time,
-                     the initial ordering of the RRset matches the
-                     one specified in the zone file.
-                   </para>
-                 </entry>
-               </row>
-             </tbody>
-           </tgroup>
-         </informaltable>
-         <para>
-           For example:
-         </para>
+          <note>
+            <simpara>
+              While alternating the order of records in a DNS response between
+              subsequent queries is a known load distribution technique, certain
+              caveats apply (mostly stemming from caching) which usually make it
+              a suboptimal choice for load balancing purposes when used on its
+              own.
+            </simpara>
+          </note>
+
+          <para>
+            The <command>rrset-order</command> statement permits configuration
+            of the ordering of the records in a multiple-record response.  See
+            also: <xref linkend="the_sortlist_statement"/>.
+          </para>
+
+          <para>
+            Each rule in an <command>rrset-order</command> statement is defined
+            as follows:
+          </para>
+
+          <para>
+            <optional>class <replaceable>&lt;class_name&gt;</replaceable></optional>
+            <optional>type <replaceable>&lt;type_name&gt;</replaceable></optional>
+            <optional>name <replaceable>"&lt;domain_name&gt;"</replaceable></optional>
+            order <replaceable>&lt;ordering&gt;</replaceable>
+          </para>
+
+          <para>
+            The default qualifiers for each rule are:
+            <itemizedlist>
+              <listitem>
+                If no <command>class</command> is specified, the default is
+                <command>ANY</command>.
+              </listitem>
+              <listitem>
+                If no <command>type</command> is specified, the default is
+                <command>ANY</command>.
+              </listitem>
+              <listitem>
+                If no <command>name</command> is specified, the default is
+                <command>*</command> (asterisk).
+              </listitem>
+            </itemizedlist>
+          </para>
+
+          <para>
+            <replaceable>&lt;domain_name&gt;</replaceable> only matches the name
+            itself, not any of its subdomains.  To make a rule match all
+            subdomains of a given name, a wildcard name
+            (<replaceable>*.&lt;domain_name&gt;</replaceable>) must be used.
+            Note that <replaceable>*.&lt;domain_name&gt;</replaceable> does
+            <emphasis>not</emphasis> match
+            <replaceable>&lt;domain_name&gt;</replaceable> itself; to specify
+            RRset ordering for a name and all of its subdomains, two separate
+            rules must be defined: one for
+            <replaceable>&lt;domain_name&gt;</replaceable> and one for
+            <replaceable>*.&lt;domain_name&gt;</replaceable>.
+          </para>
+
+          <para>
+            The legal values for <replaceable>&lt;ordering&gt;</replaceable>
+            are:
+          </para>
+
+          <variablelist>
+
+            <varlistentry>
+              <term><command>fixed</command></term>
+              <listitem>
+                <para>
+                  Records are returned in the order they are defined in the zone
+                  file.
+                </para>
+                <note>
+                  <simpara>
+                    The <command>fixed</command> option is only available if
+                    BIND is configured with
+                    <command>--enable-fixed-rrset</command> at compile time.
+                  </simpara>
+                </note>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><command>random</command></term>
+              <listitem>
+                <para>
+                  Records are returned in a random order.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><command>cyclic</command></term>
+              <listitem>
+                <para>
+                  Records are returned in a cyclic round-robin order, rotating
+                  by one record per query.
+                </para>
+              </listitem>
+            </varlistentry>
+
+          </variablelist>
+
+          <para>
+            By default, records are returned in random order.
+          </para>
+
+          <para>
+            Note that if multiple <command>rrset-order</command> statements are
+            present in the configuration file (at both the
+            <command>options</command> and <command>view</command> levels), they
+            are <emphasis>not</emphasis> combined; instead, the more-specific
+            one (<command>view</command>) replaces the less-specific one
+            (<command>options</command>).
+          </para>
+
+          <para>
+            If multiple rules within a single <command>rrset-order</command>
+            statement match a given RRset, the first matching rule is applied.
+          </para>
+
+          <para>
+            Example:
+          </para>
 
 <programlisting>rrset-order {
-   class IN type A name "host.example.com" order random;
-   order cyclic;
+    type A name "foo.isc.org" order random;
+    type AAAA name "foo.isc.org" order cyclic;
+    name "bar.isc.org" order fixed;
+    name "*.bar.isc.org" order random;
+    name "*.baz.isc.org" order cyclic;
 };
 </programlisting>
 
-         <para>
-           causes any responses for type A records in class IN, that
-           have "<literal>host.example.com</literal>" as a
-           suffix, to always be returned
-           in random order. All other records are returned in cyclic order.
-         </para>
-         <para>
-           If multiple <command>rrset-order</command> statements
-           appear, they are not combined; the last one applies.
-         </para>
-         <para>
-           By default, records are returned in random order.
-         </para>
+          <para>
+            With the above configuration, the following RRset ordering is used:
+          </para>
+
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry><para>QNAME</para></entry>
+                  <entry><para>QTYPE</para></entry>
+                  <entry><para>RRset Order</para></entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry><para><userinput>foo.isc.org</userinput></para></entry>
+                  <entry><para><userinput>A</userinput></para></entry>
+                  <entry><para><command>random</command></para></entry>
+                </row>
+                <row>
+                  <entry><para><userinput>foo.isc.org</userinput></para></entry>
+                  <entry><para><userinput>AAAA</userinput></para></entry>
+                  <entry><para><command>cyclic</command></para></entry>
+                </row>
+                <row>
+                  <entry><para><userinput>foo.isc.org</userinput></para></entry>
+                  <entry><para><userinput>TXT</userinput></para></entry>
+                  <entry><para><command>random</command></para></entry>
+                </row>
+                <row>
+                  <entry><para><userinput>sub.foo.isc.org</userinput></para></entry>
+                  <entry><para>all</para></entry>
+                  <entry><para><command>random</command></para></entry>
+                </row>
+                <row>
+                  <entry><para><userinput>bar.isc.org</userinput></para></entry>
+                  <entry><para>all</para></entry>
+                  <entry><para><command>fixed</command></para></entry>
+                </row>
+                <row>
+                  <entry><para><userinput>sub.bar.isc.org</userinput></para></entry>
+                  <entry><para>all</para></entry>
+                  <entry><para><command>random</command></para></entry>
+                </row>
+                <row>
+                  <entry><para><userinput>baz.isc.org</userinput></para></entry>
+                  <entry><para>all</para></entry>
+                  <entry><para><command>random</command></para></entry>
+                </row>
+                <row>
+                  <entry><para><userinput>sub.baz.isc.org</userinput></para></entry>
+                  <entry><para>all</para></entry>
+                  <entry><para><command>cyclic</command></para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
 
-         <note>
-           <simpara>
-             In this release of <acronym>BIND</acronym> 9, the
-             <command>rrset-order</command> statement does not support
-             "fixed" ordering by default.  Fixed ordering can be enabled
-             at compile time by specifying "--enable-fixed-rrset" on
-             the "configure" command line.
-           </simpara>
-         </note>
        </section>
 
        <section xml:id="tuning"><info><title>Tuning</title></info>