[3432] Miscellaneous modifications to DHCP-DDNS documentation made during review

diff --git a/doc/guide/bind10-guide.xml b/doc/guide/bind10-guide.xml
index 273ce6c94c9ae4fb713e0fd0265fe49021a29150..d65e0fba8b26074accc8d916c0e4da450619d73b 100644 (file)
--- a/doc/guide/bind10-guide.xml
+++ b/doc/guide/bind10-guide.xml
@@ -5302,29 +5302,32 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
       <section id="d2-tsig-key-list-config">
         <title>TSIG Key List</title>
         <para>
-        DDNS protocol can be conducted with or without TSIG as defined in
-        RFC 2845. This configuration section allows the administrator to
-        define the dictionary of TSIG keys which may be used.  To use TSIG
-        when working with a specific DDNS Domain that key must be defined in
-        the TSIG Key List and referenced by name in that domain's configuration
-        entry.
-
-        When the domain D2 has matched to a change request has a TSIG key
-        associated with it, D2 will use that key to sign DNS update messages
-        sent to and verify repsonses received from DNS server(s). For each TSIG
-        key required by the DNS servers that D2 will be working with there must
-        be a corresponding TSIG key in the TSIG Key list.
-        </para>
+        A DDNS protocol exchange can be conducted with or without TSIG
+        (defined in <ulink url="http://tools.ietf/org/html/rfc2845">RFC
+        2845</ulink>). This configuration section allows the administrator
+        to define the set of TSIG keys that may be used in such
+        exchanges.</para>
+
+        <para>To use TSIG when updating entries in a DNS Domain,
+        a key must be defined in the TSIG Key List and referenced by
+        name in that domain's configuration entry.  When D2 matches a
+        change request to a domain, it checks whether the domain has
+        a TSIG key associated with it.  If so, D2 will use that key to
+        sign DNS update messages sent to and verify repsonses received
+        from the domain's DNS server(s). For each TSIG key required by
+        the DNS servers that D2 will be working with there must be a
+        corresponding TSIG key in the TSIG Key list.</para>
+
         <para>
-        As one might gather from its name, this section is a list of
-        TSIG keys. Each entry describes a TSIG key used by one or
-        more DNS servers to authenticate requests and sign responses.
-        Each entry has three parameters:
+        As one might gather from the name, the tsig_key section of the
+        D2 configuration lists the TSIG keys.  Each entry describes a
+        TSIG key used by one or more DNS servers to authenticate requests
+        and sign responses.  Every entry in the list has three parameters:
         <itemizedlist>
           <listitem>
             <simpara>
               <command>name</command> &mdash;
-              is a unique text label used to identify this key within the
+              a unique text label used to identify this key within the
               list.  This value is used to specify which key (if any) should be
               used when updating a specific domain. So long as it is unique its
               content is arbitrary, although for clarity and ease of maintenance
@@ -5366,16 +5369,16 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
               <command>secret</command> &mdash;
               is used to specify the shared secret key code for this key.  This value is
               case sensitive and must exactly match the value specified on the DNS server(s).
-              This is a base64 encoded text value that can be located if dnssec public and
-              private key files.
+              It is a base64-encoded text value.
             </simpara>
           </listitem>
         </itemizedlist>
         </para>
         <para>
-        Suppose that a domain D2 will be updating is maintained by a BIND9 DNS server which
-        is using TSIG with that domain.  Suppose further that the entry for the TSIG key in 
-        BIND9's named.conf file looks like this:
+        As an example, suppose that a domain D2 will be updating is
+        maintained by a BIND9 DNS server which requires dynamic updates
+        to be secured with TSIG.  Suppose further that the entry for
+        the TSIG key in BIND9's named.conf file looks like this:
 <screen>
    :
    key "key.four.example.com." {
@@ -5384,23 +5387,23 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
    };
    :
 </screen>
-        By default, the TSIG Key list is empty.
+        By default, the TSIG Key list is empty:
 <screen>
 <userinput>> config show DhcpDdns/tsig_keys</userinput>
 DhcpDdns/tsig_keys  []  list  (default)
 </screen>
-        So we must first create a new key in the list:
+        We must first create a new key in the list:
 <screen>
 <userinput>> config add DhcpDdns/tsig_keys</userinput>
 </screen>
-        Displaying the new element, reveals this:
+        Displaying the new element, reveals:
 <screen>
 <userinput>> config show DhcpDdns/tsig_keys[0]</userinput>
 DhcpDdns/tsig_keys[0]/name  ""  string  (default)
 DhcpDdns/tsig_keys[0]/algorithm "HMAC-MD5"  string  (modified)
 DhcpDdns/tsig_keys[0]/secret  ""  string  (default)
 </screen>
-        Now we simple set all three values to match BIND9's key:
+        Now set all three values to match BIND9's key:
 <screen>
 <userinput>> config set DhcpDdns/tsig_keys[0]/name "key.four.example.com"</userinput>
 <userinput>> config set DhcpDdns/tsig_keys[0]/algorithm "HMAC-SHA224"</userinput>