[deployment-guide/comm-rel: 385/727] Updated the SOA resource record description.

[jhradile]

commit 9603a58ba726c0186c1969554f29b27972d01d42
Author: Jaromir Hradilek <jhradile(a)redhat.com&gt;
Date:   Mon Aug 16 16:02:23 2010 +0200

    Updated the SOA resource record description.

 en-US/The_BIND_DNS_Server.xml |  134 ++++++++++++++++++++++++----------------
 1 files changed, 80 insertions(+), 54 deletions(-)
---
diff --git a/en-US/The_BIND_DNS_Server.xml b/en-US/The_BIND_DNS_Server.xml
index ebf7530..fdaeaab 100644
--- a/en-US/The_BIND_DNS_Server.xml
+++ b/en-US/The_BIND_DNS_Server.xml
@@ -1220,35 +1220,61 @@ IN  NS  dns2.example.com.</screen>
           <term><command>SOA</command></term>
           <listitem>
             <para>
-              This refers to the Start Of Authority resource record, which proclaims
important authoritative information about a namespace to the nameserver.
+              The <firstterm>Start of Authority</firstterm> record announces
important authoritative information about a namespace to the nameserver. Located after the
directives, it is the first resource record in a zone file. It takes the following form:
             </para>
+            <screen>@  IN  SOA 
<replaceable>primary-name-server</replaceable>
<replaceable>hostmaster-email</replaceable> (
+       <replaceable>serial-number</replaceable>
+       <replaceable>time-to-refresh</replaceable>
+       <replaceable>time-to-retry</replaceable>
+       <replaceable>time-to-expire</replaceable>
+       <replaceable>minimum-TTL</replaceable> )</screen>
             <para>
-              Located after the directives, an <command>SOA</command>
resource record is the first resource record in a zone file.
-            </para>
-            <para>
-              The following <!-- RHEL5:  example  -->shows the basic structure of
an <command>SOA</command> resource record:
-            </para>
-            <screen>@     IN     SOA   
<replaceable>&lt;primary-name-server&gt;</replaceable>
-              <replaceable>&lt;hostmaster-email&gt;</replaceable> (
-  <replaceable>&lt;serial-number&gt;</replaceable>
-              <replaceable>&lt;time-to-refresh&gt;</replaceable>
-              <replaceable>&lt;time-to-retry&gt;</replaceable>
-              <replaceable>&lt;time-to-expire&gt;</replaceable>
-              <replaceable>&lt;minimum-TTL&gt;
</replaceable>)</screen>
-            <para>
-              The <command>@</command> symbol places the
<command>$ORIGIN</command> directive (or the zone's name, if the
<command>$ORIGIN</command> directive is not set) as the namespace being
defined by this <command>SOA</command> resource record. The hostname of the
primary nameserver that is authoritative for this domain is the
<replaceable>&lt;primary-name-server&gt;</replaceable> directive, and
the email of the person to contact about this namespace is the
<replaceable>&lt;hostmaster-email&gt;</replaceable> directive.
-            </para>
-            <para>
-              The <replaceable>&lt;serial-number&gt;</replaceable>
directive is a numerical value incremented every time the zone file is altered to indicate
it is time for <command>named</command> to reload the zone. The
<replaceable>&lt;time-to-refresh&gt;</replaceable> directive is the
numerical value slave servers use to determine how long to wait before asking the master
nameserver if any changes have been made to the zone. The
<replaceable>&lt;serial-number&gt;</replaceable> directive is a
numerical value used by the slave servers to determine if it is using outdated zone data
and should therefore refresh it.
-            </para>
-            <para>
-              The <replaceable>&lt;time-to-retry&gt;</replaceable>
directive is a numerical value used by slave servers to determine the length of time to
wait before issuing a refresh request in the event that the master nameserver is not
answering. If the master has not replied to a refresh request before the amount of time
specified in the <replaceable>&lt;time-to-expire&gt;</replaceable>
directive elapses, the slave servers stop responding as an authority for requests
concerning that namespace.
-            </para>
-            <para>
-              In BIND 4 and 8, the
<replaceable>&lt;minimum-TTL&gt;</replaceable> directive is the
<!-- RHEL5:  quantity  -->amount of time other nameservers cache the zone's
information. However, in BIND 9, the
<replaceable>&lt;minimum-TTL&gt;</replaceable> directive defines how
long negative answers are cached for. Caching of negative answers can be set to a maximum
of 3 hours (<option>3H</option>).
+              The directives are as follows:
             </para>
+            <itemizedlist>
+              <listitem>
+                <para>
+                  The <literal>@</literal> symbol places the
<command>$ORIGIN</command> directive (or the zone's name if the
<command>$ORIGIN</command> directive is not set) as the namespace being
defined by this <command>SOA</command> resource record.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  The <replaceable>primary-name-server</replaceable>
directive is the hostname of the primary nameserver that is authoritative for this
domain.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  The <replaceable>hostmaster-email</replaceable> directive
is the email of the person to contact about the namespace.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  The <replaceable>serial-number</replaceable> directive is a
numerical value incremented every time the zone file is altered to indicate it is time for
the <systemitem class="service">named</systemitem> service to reload
the zone.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  The <replaceable>time-to-refresh</replaceable> directive is
the numerical value secondary nameservers use to determine how long to wait before asking
the primary nameserver if any changes have been made to the zone.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  The <replaceable>serial-number</replaceable> directive is a
numerical value used by the slave servers to determine if it is using outdated zone data
and should therefore refresh it.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  The <replaceable>time-to-retry</replaceable> directive is a
numerical value used by secondary nameservers to determine the length of time to wait
before issuing a refresh request in the event that the primary nameserver is not
answering. If the primary server has not replied to a refresh request before the amount of
time specified in the <replaceable>time-to-expire</replaceable> directive
elapses, the secondary servers stop responding as an authority for requests concerning
that namespace.
+                </para>
+              </listitem>
+              <listitem>
+                <para>
+                  In BIND 4 and 8, the <replaceable>minimum-TTL</replaceable>
directive is the amount of time other nameservers cache the zone's information. In
BIND 9, it defines how long negative answers are cached for. Caching of negative answers
can be set to a maximum of 3 hours (that is, <option>3H</option>).
+                </para>
+              </listitem>
+            </itemizedlist>
             <para>
-              When configuring BIND, all times are specified in seconds. However, it is
possible to use abbreviations when specifying units of time other than seconds, such as
minutes (<command>M</command>), hours (<command>H</command>), days
(<command>D</command>), and weeks (<command>W</command>). The
table in <xref linkend="tb-bind-seconds" /> shows an amount of time in
seconds and the equivalent time in another format.
+              When configuring BIND, all times are specified in seconds. However, it is
possible to use abbreviations when specifying units of time other than seconds, such as
minutes (<literal>M</literal>), hours (<literal>H</literal>), days
(<literal>D</literal>), and weeks (<literal>W</literal>). <xref
linkend="tb-bind-seconds" /> shows an amount of time in seconds and the
equivalent time in another format.
             </para>
             <table id="tb-bind-seconds">
               <title>Seconds compared to other time units</title>
@@ -1268,96 +1294,96 @@ IN  NS  dns2.example.com.</screen>
                 <tbody>
                   <row>
                     <entry>
-                      <command>60</command>
+                      60
                     </entry>
                     <entry>
-                      <command>1M</command>
+                      <literal>1M</literal>
                     </entry>
                   </row>
                   <row>
                     <entry>
-                      <command>1800</command>
+                      1800
                     </entry>
                     <entry>
-                      <command>30M</command>
+                      <literal>30M</literal>
                     </entry>
                   </row>
                   <row>
                     <entry>
-                      <command>3600</command>
+                      3600
                     </entry>
                     <entry>
-                      <command>1H</command>
+                      <literal>1H</literal>
                     </entry>
                   </row>
                   <row>
                     <entry>
-                      <command>10800</command>
+                      10800
                     </entry>
                     <entry>
-                      <command>3H</command>
+                      <literal>3H</literal>
                     </entry>
                   </row>
                   <row>
                     <entry>
-                      <command>21600</command>
+                      21600
                     </entry>
                     <entry>
-                      <command>6H</command>
+                      <literal>6H</literal>
                     </entry>
                   </row>
                   <row>
                     <entry>
-                      <command>43200</command>
+                      43200
                     </entry>
                     <entry>
-                      <command>12H</command>
+                      <literal>12H</literal>
                     </entry>
                   </row>
                   <row>
                     <entry>
-                      <command>86400</command>
+                      86400
                     </entry>
                     <entry>
-                      <command>1D</command>
+                      <literal>1D</literal>
                     </entry>
                   </row>
                   <row>
                     <entry>
-                      <command>259200</command>
+                      259200
                     </entry>
                     <entry>
-                      <command>3D</command>
+                      <literal>3D</literal>
                     </entry>
                   </row>
                   <row>
                     <entry>
-                      <command>604800</command>
+                      604800
                     </entry>
                     <entry>
-                      <command>1W</command>
+                      <literal>1W</literal>
                     </entry>
                   </row>
                   <row>
                     <entry>
-                      <command>31536000</command>
+                      31536000
                     </entry>
                     <entry>
-                      <command>365D</command>
+                      <literal>365D</literal>
                     </entry>
                   </row>
                 </tbody>
               </tgroup>
             </table>
-            <para>
-              The following example illustrates the form an
<command>SOA</command> resource record might take when it is populated with
real values.
-            </para>
-            <screen>@     IN     SOA    dns1.example.com.    
hostmaster.example.com. (
-      2001062501 ; serial
-      21600      ; refresh after 6 hours
-      3600       ; retry after 1 hour
-      604800     ; expire after 1 week
-      86400 )    ; minimum TTL of 1 day</screen>
+            <example id="example-bind-zone-rr-soa">
+              <title>Using the <command>SOA</command> resource
record</title>
+              <screen>@  IN  SOA  dns1.example.com.  hostmaster.example.com. (
+       2001062501 ; serial
+       21600      ; refresh after 6 hours
+       3600       ; retry after 1 hour
+       604800     ; expire after 1 week
+       86400 )    ; minimum TTL of 1 day</screen>
+            </example>
           </listitem>
         </varlistentry>
       </variablelist>