[3467] Updated user guide with option-data parameters optionality.

diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml
index d24e5bbedc0118c666fbf4628b3df8f2ebc2323a..1d75145c4a7bbd3fc692bad6235ba7e34bba9d05 100644 (file)
--- a/doc/guide/dhcp4-srv.xml
+++ b/doc/guide/dhcp4-srv.xml
@@ -552,6 +552,12 @@ temporarily override a list of interface names and listen on all interfaces.
 }</screen>
       </para>
 
+      <para>
+        Most of the parameters in the "option-data" structure are optional and
+        can be omitted in some circumstances as discussed in the
+        <xref linkend="dhcp4-option-data-defaults"/>.
+      </para>
+
       <para>
         It is possible to specify or override options on a per-subnet basis.  If
         clients connected to most of your subnets are expected to get the
@@ -589,15 +595,6 @@ temporarily override a list of interface names and listen on all interfaces.
 </screen>
       </para>
 
-    <note>
-      <para>
-        In future versions of Kea, it will not be necessary to specify
-        the <command>code</command>, <command>space</command>
-        and <command>csv-format</command> fields, as they will
-        be set automatically.
-      </para>
-    </note>
-
       <para>
         The currently supported standard DHCPv4 options are
         listed in <xref linkend="dhcp4-std-options-list"/>
@@ -1099,6 +1096,76 @@ temporarily override a list of interface names and listen on all interfaces.
     </para>
     </section>
 
+    <section id="dhcp4-option-data-defaults">
+      <title>Unspecified parameters for option configuration</title>
+      <para>In many cases it is not required to specify all parameters for
+      an option configuration and use the default values. However, it is
+      important to understand the implications of not specifing some of them
+      as it may result in configuration errors. The list below explains
+      the behavior of the server when a particular parameter is not explicitly
+      specified:
+
+      <itemizedlist>
+        <listitem>
+          <simpara><command>name</command> - the server requires an option name or
+          option code to identify an option. If this parameter is unspecified, the
+          option code must be specified.
+          </simpara>
+        </listitem>
+
+        <listitem>
+          <simpara><command>code</command> - the server requires an option name or
+          option code to identify an option. This parameter may be left unspecified if
+          the <command>name</command> parameter is specified. However, this also
+          requires that the particular option has its definition (it is either a
+          standard option or an administrator created a definition for the option
+          using an 'option-def' structure), as the option definition associates an
+          option with a particular name. It is possible to configure an option
+          for which there is no definition (unspecified option format).
+          Configuration of such options requires the use of option code.
+          </simpara>
+        </listitem>
+
+        <listitem>
+          <simpara><command>space</command> - if the option space is unspecified it
+          will default to 'dhcp4' which is an option space holding DHCPv4 standard
+          options.
+          </simpara>
+        </listitem>
+
+        <listitem>
+          <simpara><command>data</command> - if the option data is unspecified it
+          defaults to an empty value. The empty value is mostly used for the
+          options which have no payload (boolean options), but it is legal to specify
+          empty values for some options which carry variable length data and which
+          spec allows for the length of 0. For such options, the data parameter
+          may be omitted in the configuration.</simpara>
+        </listitem>
+
+        <listitem>
+          <simpara><command>csv-format</command> - if this value is not specified
+          and the definition for the particular option exists, the server will assume
+          that the option data is specified as a list of comma separated values to be
+          assigned to individual fields of the DHCP option. If the definition
+          does not exist for this option, the server will assume that the data
+          parameter contains the option payload in the binary format (represented
+          as a string of hexadecimal digits). Note that not specifying this
+          parameter doesn't imply that it defaults to a fixed value, but
+          the configuration data interpretation also depends on the presence
+          of the option definition. An administrator must be aware if the
+          definition for the particular option exists when this parameter
+          is not specified. It is generally recommended to not specify this
+          parameter only for the options for which the definition exists, e.g.
+          standard options. Setting <command>csv-format</command> to an explicit
+          value will cause the server to strictly check the format of the option
+          data specified.
+          </simpara>
+        </listitem>
+      </itemizedlist>
+      </para>
+
+    </section>
+
     <section id="dhcp4-stateless-configuration">
       <title>Stateless Configuration of DHCPv4 clients</title>
       <para>The DHCPv4 server supports the stateless client configuration whereby the

diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml
index 93ec7d71ab1ca1eb49d76a6037ac3bbf7995d811..4443005bc6e40f0b4574aedaa606f85ecde594ee 100644 (file)
--- a/doc/guide/dhcp6-srv.xml
+++ b/doc/guide/dhcp6-srv.xml
@@ -644,6 +644,13 @@ temporarily override a list of interface names and listen on all interfaces.
        to validate data correctness in hexadecimal is limited.
       </para>
 
+      <para>
+        Most of the parameters in the "option-data" structure are optional and
+        can be omitted in some circumstances as discussed in the
+        <xref linkend="dhcp6-option-data-defaults"/>.
+      </para>
+
+
     <para>
       It is possible to override options on a per-subnet basis.  If
       clients connected to most of your subnets are expected to get the
@@ -681,16 +688,6 @@ temporarily override a list of interface names and listen on all interfaces.
 </screen>
     </para>
 
-    <note>
-      <para>
-        In future versions of Kea, it will not be necessary to specify
-        the <command>code</command>, <command>space</command>
-        and <command>csv-format</command> fields, as they will
-        be set automatically.
-      </para>
-    </note>
-
-
     <para>
       The currently supported standard DHCPv6 options are
       listed in <xref linkend="dhcp6-std-options-list"/>.
@@ -1090,6 +1087,76 @@ should include options from the isc option space:
     </para>
     </section>
 
+    <section id="dhcp6-option-data-defaults">
+      <title>Unspecified parameters for option configuration</title>
+      <para>In many cases it is not required to specify all parameters for
+      an option configuration and use the default values. However, it is
+      important to understand the implications of not specifing some of them
+      as it may result in configuration errors. The list below explains
+      the behavior of the server when a particular parameter is not explicitly
+      specified:
+
+      <itemizedlist>
+        <listitem>
+          <simpara><command>name</command> - the server requires an option name or
+          option code to identify an option. If this parameter is unspecified, the
+          option code must be specified.
+          </simpara>
+        </listitem>
+
+        <listitem>
+          <simpara><command>code</command> - the server requires an option name or
+          option code to identify an option. This parameter may be left unspecified if
+          the <command>name</command> parameter is specified. However, this also
+          requires that the particular option has its definition (it is either a
+          standard option or an administrator created a definition for the option
+          using an 'option-def' structure), as the option definition associates an
+          option with a particular name. It is possible to configure an option
+          for which there is no definition (unspecified option format).
+          Configuration of such options requires the use of option code.
+          </simpara>
+        </listitem>
+
+        <listitem>
+          <simpara><command>space</command> - if the option space is unspecified it
+          will default to 'dhcp6' which is an option space holding DHCPv6 standard
+          options.
+          </simpara>
+        </listitem>
+
+        <listitem>
+          <simpara><command>data</command> - if the option data is unspecified it
+          defaults to an empty value. The empty value is mostly used for the
+          options which have no payload (boolean options), but it is legal to specify
+          empty values for some options which carry variable length data and which
+          spec allows for the length of 0. For such options, the data parameter
+          may be omitted in the configuration.</simpara>
+        </listitem>
+
+        <listitem>
+          <simpara><command>csv-format</command> - if this value is not specified
+          and the definition for the particular option exists, the server will assume
+          that the option data is specified as a list of comma separated values to be
+          assigned to individual fields of the DHCP option. If the definition
+          does not exist for this option, the server will assume that the data
+          parameter contains the option payload in the binary format (represented
+          as a string of hexadecimal digits). Note that not specifying this
+          parameter doesn't imply that it defaults to a fixed value, but
+          the configuration data interpretation also depends on the presence
+          of the option definition. An administrator must be aware if the
+          definition for the particular option exists when this parameter
+          is not specified. It is generally recommended to not specify this
+          parameter only for the options for which the definition exists, e.g.
+          standard options. Setting <command>csv-format</command> to an explicit
+          value will cause the server to strictly check the format of the option
+          data specified.
+          </simpara>
+        </listitem>
+      </itemizedlist>
+      </para>
+
+    </section>
+
     <section id="dhcp6-config-subnets">
       <title>IPv6 Subnet Selection</title>
       <para>