[4259] Updated admin guide and spec files

Revamped discussion of FQDN name generation and use of the
    replace-client-name parameter in the v4 and v6 guides.

doc/guide/dhcp4-srv.xml

@@ -129,7 +129,7 @@ strings <userinput>path</userinput>/kea-dhcp4 | sed -n 's/;;;; //p'
         If the file already exists and contains the PID of a live process,
         the server will issue a DHCP4_ALREADY_RUNNING log message and exit. It
         is possible, though unlikely, that the file is a remnant of a system crash
-        and the process to which the PID belongs is unrelated to Kea.  In such a 
+        and the process to which the PID belongs is unrelated to Kea.  In such a
         case it would be necessary to manually delete the PID file.
       </para>
 
@@ -1777,7 +1777,7 @@ It is merely echoed by the server
     </section>
 
     <section id="dhcp4-ddns-config">
-      <title>Configuring DHCPv4 for DDNS</title>
+      <title>DDNS for DHCPv4</title>
       <para>
       As mentioned earlier, kea-dhcp4 can be configured to generate requests to the
       DHCP-DDNS server (referred to here as "D2" ) to update DNS entries.  These requests are known as
@@ -1852,7 +1852,7 @@ It is merely echoed by the server
       <command>"override-client-update": false</command>
       </simpara></listitem>
       <listitem><simpara>
-      <command>"replace-client-name": false</command>
+      <command>"replace-client-name": "never"</command>
       </simpara></listitem>
       <listitem><simpara>
       <command>"generated-prefix": "myhost"</command>
@@ -2078,38 +2078,62 @@ It is merely echoed by the server
       supply a portion or all of that name based upon what it receives from
       the client in the DHCP REQUEST.</para>
       <para>
-      The rules for determining the FQDN option are as follows:
+       The basic rules for constructing the FQDN that will be used for DNS
+       entries are:
       <orderedlist>
       <listitem><para>
-      If configured to do, so ignore the DHCPREQUEST contents and generate a
+        If the DHCPREQUEST contains the client FQDN option, the candidate name
-      FQDN using a configurable prefix and suffix.
+        is taken from there, otherwise it is taken from the Host Name option.
       </para></listitem>
       <listitem><para>
-      If the DHCPREQUEST contains the client FQDN option, the candidate
+        If the candidate name is a partial (i.e. unqualified) name then add a
-      name is taken from there, otherwise it is taken from the Host Name option.
+        configurable suffix to the name and use the result as the FQDN.
-      The candidate name may then be modified:
-      <orderedlist>
-      <listitem><para>
-      If the candidate name is a fully qualified domain name, use it.
       </para></listitem>
       <listitem><para>
-      If the candidate name is a partial (i.e. unqualified) name then
+        If the candidate name provided is empty, generate a FQDN using a
-      add a configurable suffix to the name and use the result as the FQDN.
+        configurable prefix and suffix.
       </para></listitem>
       <listitem><para>
-      If the candidate name is a empty, generate a FQDN using a
+        If the client provided neither option, then no DNS action will be taken.
-      configurable prefix and suffix.
       </para></listitem>
       </orderedlist>
+        These rules can amended by setting the
+        <command>replace-client-name</command> parameter which provides the
+        following modes of behavior:
+      <itemizedlist>
+      <listitem><para>
+        <command>never</command> - Use the name the client sent.  If the client
+        sent no name, do not generate one.  This is the default mode.
       </para></listitem>
-      </orderedlist>
+      <listitem><para>
-      To instruct kea-dhcp4 to always generate the FQDN for a client, set the
+        <command>always</command> - Replace the name the client sent. If the
-      parameter <command>replace-client-name</command> to true as follows:
+        client sent no name, generate one for them.
+      </para></listitem>
+      <listitem><para>
+        <command>when_present</command> - Replace the name the client sent.
+        If the client sent no name, do not generate one.
+      </para></listitem>
+      <listitem><para>
+        <command>when_not_present</command> - Use the name the client sent.
+        If the client sent no name, generate one for them.
+      </para></listitem>
+      </itemizedlist>
+    <note>
+    Note that formerly, this parameter was a boolean and permitted only values
+    of <command>true</command> and <command>false</command>.  Boolean values
+    will still be accepted but may eventually be deprecated. A value of
+    <command>true</command> equates to <command>when_present</command>,
+    <command>false</command> equates to <command>never</command>.
+    </note>
+
+      For example, To instruct kea-dhcp4 to always generate the FQDN for a
+      client, set the parameter <command>replace-client-name</command> to
+      <command>always</command> as follows:
       </para>
 <screen>
 "Dhcp4": {
     "dhcp-ddns": {
-        <userinput>"replace-client-name": true</userinput>,
+        <userinput>"replace-client-name": "always"</userinput>,
         ...
     },
     ...

doc/guide/dhcp6-srv.xml

@@ -1744,7 +1744,7 @@ should include options from the isc option space:
     </section>
 
     <section id="dhcp6-ddns-config">
-      <title>Configuring DHCPv6 for DDNS</title>
+      <title>DDNS for DHCPv6</title>
       <para>
       As mentioned earlier, kea-dhcp6 can be configured to generate requests to
       the DHCP-DDNS server (referred to here as "D2") to update
@@ -1820,7 +1820,7 @@ should include options from the isc option space:
       <command>"override-client-update": false</command>
       </simpara></listitem>
       <listitem><simpara>
-      <command>"replace-client-name": false</command>
+      <command>"replace-client-name": "never"</command>
       </simpara></listitem>
       <listitem><simpara>
       <command>"generated-prefix": "myhost"</command>
@@ -2041,42 +2041,67 @@ should include options from the isc option space:
       <section id="dhcpv6-fqdn-name-generation">
       <title>kea-dhcp6 name generation for DDNS update requests</title>
 
-      <para>Each NameChangeRequest must of course include the fully qualified domain
+      <para>Each NameChangeRequest must of course include the fully qualified
-      name whose DNS entries are to be affected.  kea-dhcp6 can be configured to
+      domain name whose DNS entries are to be affected.  kea-dhcp6 can be
-      supply a portion or all of that name based upon what it receives from
+      configured to supply a portion or all of that name based upon what it
-      the client in the DHCP REQUEST.</para>
+      receives from the client in the DHCP REQUEST.</para>
+      <para>
+       The basic rules for constructing the FQDN that will be used for DNS
+       entries are:
+      <orderedlist>
+      <listitem><para>
+        If the DHCPREQUEST contains the client FQDN option, the candidate name
+        is taken from there.
+      </para></listitem>
+      <listitem><para>
+        If the candidate name is a partial (i.e. unqualified) name then add a
+        configurable suffix to the name and use the result as the FQDN.
+      </para></listitem>
+      <listitem><para>
+        If the candidate name provided is empty, generate a FQDN using a
+        configurable prefix and suffix.
+      </para></listitem>
+      <listitem><para>
+        If the client provided neither option, then no DNS action will be taken.
+      </para></listitem>
+      </orderedlist>
+        These rules can amended by setting the
+        <command>replace-client-name</command> parameter which provides the
+        following modes of behavior:
+      <itemizedlist>
+      <listitem><para>
+        <command>never</command> - Use the name the client sent.  If the client
+        sent no name, do not generate one.  This is the default mode.
+      </para></listitem>
+      <listitem><para>
+        <command>always</command> - Replace the name the client sent. If the
+        client sent no name, generate one for them.
+      </para></listitem>
+      <listitem><para>
+        <command>when_present</command> - Replace the name the client sent.
+        If the client sent no name, do not generate one.
+      </para></listitem>
+      <listitem><para>
+        <command>when_not_present</command> - Use the name the client sent.
+        Supply the name if the client did not.
+      </para></listitem>
+      </itemizedlist>
+    <note>
+    Note that formerly, this parameter was a boolean and permitted only values
+    of <command>true</command> and <command>false</command>.  Boolean values
+    will still be accepted but may eventually be deprecated. A value of
+    <command>true</command> equates to <command>when_present</command>,
+    <command>false</command> equates to <command>never</command>.
+    </note>
 
-      <para>The rules for determining the FQDN option are as follows:
+      For example, To instruct kea-dhcp6 to always generate the FQDN for a
-      <orderedlist>
+      client, set the parameter <command>replace-client-name</command> to
-      <listitem><para>
+      <command>always</command> as follows:
-      If configured to do so ignore the REQUEST contents and generate a
-      FQDN using a configurable prefix and suffix.
-      </para></listitem>
-      <listitem><para>
-      Otherwise, using the domain name value from the client FQDN option as
-      the candidate name:
-      <orderedlist>
-      <listitem><para>
-      If the candidate name is a fully qualified domain name then use it.
-      </para></listitem>
-      <listitem><para>
-      If the candidate name is a partial (i.e. unqualified) name then
-      add a configurable suffix to the name and use the result as the FQDN.
-      </para></listitem>
-      <listitem><para>
-      If the candidate name is a empty then generate a FQDN using a
-      configurable prefix and suffix.
-      </para></listitem>
-      </orderedlist>
-      </para></listitem>
-      </orderedlist>
-      To instruct kea-dhcp6 to always generate a FQDN, set the parameter
-      "replace-client-name" to true:
       </para>
 <screen>
 "Dhcp6": {
     "dhcp-ddns": {
-        <userinput>"replace-client-name": true</userinput>,
+        <userinput>"replace-client-name": "always"</userinput>,
         ...
     },
     ...

src/bin/dhcp4/dhcp4.spec

@@ -607,9 +607,9 @@
             },
             {
                 "item_name": "replace-client-name",
-                "item_type": "boolean",
+                "item_type": "string",
                 "item_optional": true,
-                "item_default": false,
+                "item_default": "never",
                 "item_description": "Should server replace the domain-name supplied by the client"
             },
             {

src/bin/dhcp6/dhcp6.spec

@@ -711,9 +711,9 @@
             },
             {
                 "item_name": "replace-client-name",
-                "item_type": "boolean",
+                "item_type": "string",
                 "item_optional": true,
-                "item_default": false,
+                "item_default": "never",
                 "item_description": "Should server replace the domain-name supplied by the client"
             },
             {

src/bin/dhcp6/dhcp6_messages.mes

@@ -1,4 +1,4 @@
-# Copyright (C) 2012-2015 Internet Systems Consortium, Inc. ("ISC")
+# Copyright (C) 2012-2016 Internet Systems Consortium, Inc. ("ISC")
 #
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this