[5275] Added discussion of conflict resolution to D2 admin guide section

doc/guide/ddns.xml

@@ -6,49 +6,96 @@
 
   <chapter id="dhcp-ddns-server">
     <title>The DHCP-DDNS Server</title>
-    <para>
-    The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of
-    the DDNS protocol (defined in <ulink url="http://tools.ietf.org/html/rfc2136">RFC 2136</ulink>)
-    on behalf of the DHCPv4 and DHCPv6
-    servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct
-    DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP
-    lease change events and then post these to D2. D2 attempts to match
-    each such request to the appropriate DNS server(s) and carry out the
-    necessary conversation with those servers to update the DNS data.
-    </para>
-    <para>
-    In order to match a request to the appropriate DNS servers, D2 must have a
-    catalog of servers from which to select. In fact, D2 has two such catalogs,
-    one for forward DNS and one for reverse DNS; these catalogs are referred
-    to as DDNS Domain Lists.  Each list consists of one or more named DDNS
-    Domains. Further, each DDNS Domain has a list of one or more DNS
-    servers that publish the DNS data for that domain.
-    </para>
-    <para>
-    When conducting forward domain matching, D2 will compare the FQDN in
-    the request against the name of each forward DDNS Domain. The domain
-    whose name matches the longest portion of the FQDN is considered the
-    best match.  For example, if the FQDN is "myhost.sample.example.com.",
-    and there are two forward domains in the catalog: "sample.example.com."
-    and "example.com.", the former is regarded as the best match.  In some
-    cases, it may not be possible to find a suitable match. Given the same two
-    forward domains there would be no match for the FQDN, "bogus.net", so the
-    request would be rejected.   Finally, if there are no forward DDNS Domains
-    defined, D2 will simply disregard the forward update portion of requests.
-    </para>
-    <para>
-    When conducting reverse domain matching, D2 constructs a reverse
-    FQDN from the lease address in the request and compare that against
-    the name of each reverse DDNS Domain. Again, the domain whose name matches
-    the longest portion of the FQDN is considered the best match. For instance,
-    if the lease address is "172.16.1.40" and there are two reverse domains in
-    the catalog: "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the
-    former is the best match.  As with forward matching, it is possible to not
-    find a suitable match.  Given the same two domains, there would be no
-    match for the lease address, "192.168.1.50", and the request would be
-    rejected. Finally, if there are no reverse DDNS Domains defined, D2 will
-    simply disregard the reverse update portion of requests.
+    <section id="dhcp-ddns-overview">
+      <title>Overview</title>
+      <para>
+      The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts
+      the client side of the DDNS protocol (defined in
+        <ulink url="http://tools.ietf.org/html/rfc2136">RFC 2136</ulink>)
+      on behalf of the DHCPv4 and DHCPv6 servers (kea-dhcp4 and kea-dhcp6
+      respectively). The DHCP servers construct DDNS update requests, known
+      as NameChangeRequests (NCRs), based upon DHCP lease change events and
+      then post these to D2. D2 attempts to match each such request to the
+      appropriate DNS server(s) and carry out the necessary conversation with
+      those servers to update the DNS data.
     </para>
+    <section id="dhcp-ddns-dns-server-selection">
+      <title>DNS Server selection</title>
+      <para>
+      In order to match a request to the appropriate DNS servers, D2 must have a
+      catalog of servers from which to select. In fact, D2 has two such catalogs,
+      one for forward DNS and one for reverse DNS; these catalogs are referred
+      to as DDNS Domain Lists.  Each list consists of one or more named DDNS
+      Domains. Further, each DDNS Domain has a list of one or more DNS
+      servers that publish the DNS data for that domain.
+      </para>
+      <para>
+      When conducting forward domain matching, D2 will compare the FQDN in
+      the request against the name of each forward DDNS Domain. The domain
+      whose name matches the longest portion of the FQDN is considered the
+      best match.  For example, if the FQDN is "myhost.sample.example.com.",
+      and there are two forward domains in the catalog: "sample.example.com."
+      and "example.com.", the former is regarded as the best match.  In some
+      cases, it may not be possible to find a suitable match. Given the same two
+      forward domains there would be no match for the FQDN, "bogus.net", so the
+      request would be rejected.   Finally, if there are no forward DDNS Domains
+      defined, D2 will simply disregard the forward update portion of requests.
+      </para>
+      <para>
+      When conducting reverse domain matching, D2 constructs a reverse
+      FQDN from the lease address in the request and compare that against
+      the name of each reverse DDNS Domain. Again, the domain whose name matches
+      the longest portion of the FQDN is considered the best match. For instance,
+      if the lease address is "172.16.1.40" and there are two reverse domains in
+      the catalog: "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the
+      former is the best match.  As with forward matching, it is possible to not
+      find a suitable match.  Given the same two domains, there would be no
+      match for the lease address, "192.168.1.50", and the request would be
+      rejected. Finally, if there are no reverse DDNS Domains defined, D2 will
+      simply disregard the reverse update portion of requests.
+      </para>
+    </section>
+    <section id="dhcp-ddns-conflict-resolution">
+      <title>Conflict Resolution</title>
+        <para>
+        D2 implements the conflict resolution strategy prescribed by
+        <ulink url="http://tools.ietf.org/html/rfc4703">RFC 4703</ulink>.
+        Conflict resolution is intended to prevent different clients from
+        mapping to the same FQDN at the same time.  To make this possible, the
+        RFC requires that forward DNS entries for a given FQDN must be
+        accompanied by a DHCID resource record (RR).  This record contains a
+        client identifier that uniquely identifies the client to whom the name
+        belongs. Furthermore, any DNS updater who wishes to update or remove
+        existing forward entries for an FQDN may only do so if their client
+        matches that of the DHCID RR.
+        </para>
+        <para>
+        In other words, the DHCID RR maps an FQDN to the client to whom it
+        belongs and thereafter only changes to that mapping should only be
+        done by or at the behest of that client.
+        </para>
+        <para>
+        Currently, conflict detection is always performed.  Future releases may
+        offer alternative behavior.
+        </para>
+    </section>
+    <section id="dhcp-ddns-dual-stack">
+      <title>Dual Stack Environments</title>
+      <para>
+        <ulink url="http://tools.ietf.org/html/rfc4703#section-5.2">RFC 4703,
+        sec. 5.2,</ulink> describes issues that may arise with dual stack
+        clients. These are clients that wish to have have both IPv4 and IPv6
+        mappings for the same FQDN.  In order for this work properly, such
+        clients are required to embed ther IPv6 DUID within their IPv4 client
+        identifier option as described in
+        <ulink url="http://tools.ietf.org/html/rfc4361">RFC 4703</ulink>.
+        In this way, DNS upates for both IPv4 and IPv6 can be managed under
+        the same DHCID RR. Support for this does not yet exist in Kea but is
+        called for in the ticket, http://kea.isc.org/ticket/4519, which we
+        hope to include in an upcoming release.
+      </para>
+    </section>
+    </section>
     <section id="dhcp-ddns-server-start-stop">
       <title>Starting and Stopping the DHCP-DDNS Server</title>