[5073a] Updated docs and made deferredUnpack more robust to hooks

doc/guide/classify.xml

@@ -33,23 +33,30 @@
       behavior of almost any part of the DHCP message processing, including the assignment of
       leases from different pools, the assignment of different options (or different values of
       the same options) etc. In the current release of the software however, there are
-      only three mechanisms that take
-      advantage of client classification: subnet selection, assignment of different
+      only four mechanisms that take
+      advantage of client classification: subnet selection, definition of DHCPv4 private (codes 224-254) and code 43 options, assignment of different
       options and, for DHCPv4 cable modems, the setting of specific options for use with
       the TFTP server address and the boot file field.
       </para>
 
       <para>
-      The process of doing classification is conducted in three steps:
+      The process of doing classification is conducted in four steps:
       <orderedlist>
       <listitem><para>
       Assess an incoming packet and assign it to zero or more classes.
       </para></listitem>
       <listitem><para>
+      If a private or code 43 DHCPv4 option is received, decoding it
+      following its client class or global (or for option 43 last
+      resort) definition.
+      </para></listitem>
+      <listitem><para>
       Choose a subnet, possibly based on the class information.
       </para></listitem>
       <listitem><para>
       Assign options, again possibly based on the class information.
+      For DHCPv4 private and code 43 options this includes class local
+      option definitions.
       </para></listitem>
       </orderedlist>
       </para>

doc/guide/dhcp4-srv.xml

@@ -1521,6 +1521,52 @@ It is merely echoed by the server
      </note>
     </section>
 
+    <section id="dhcp4-private-opts">
+      <title>DHCPv4 Private Options</title>
+      <para>
+      Options with code between 224 and 254 are reserved for private use.
+      They can be defined at the global scope or at client class local
+      scope: this allows to use option definitions depending on context
+      and to set option data accordingly.
+      As the Vendor Specific Information option (code 43) can carry
+      in a not compatible way a raw binary value or sub-options this
+      mechanism is available for this option too.
+      </para>
+      <para>
+      The definition used to decode a VSI option is:
+      <orderedlist>
+      <listitem><para>
+      The local definition of a client class the incoming packet belongs to
+      </para></listitem>
+      <listitem><para>
+      If none, the global definition
+      </para></listitem>
+      <listitem><para>
+      If none, the last resort definition described in the next section
+      <xref linkend="dhcp4-vendor-opts"/> (backward compatible with
+      previous Kea versions).
+      </para></listitem>
+      </orderedlist>
+      </para>
+      <note>
+      <para>
+      This last resort definition for the Vendor Specific Information
+      option (code 43) is not compatible with a raw binary value.
+      So when there are some known cases where a raw binary value
+      will be used, a client class must be defined with a classification
+      expression matching these cases and an option definition for
+      the VSI option with a binary type and no encapsulation.
+      </para>
+      </note>
+      <note>
+      <para>
+      Option definitions in client classes is allowed only for these
+      limited option set (codes 43 and from 224 to 254), and only
+      for DHCPv4.
+      </para>
+      </note>
+    </section>
+
     <section id="dhcp4-vendor-opts">
       <title>DHCPv4 Vendor Specific Options</title>
       <para>

src/bin/dhcp4/dhcp4.dox

@@ -167,6 +167,12 @@ implemented within the context of the server and it has access to all objects
 which define its configuration (including dynamically created option
 definitions).
 
+Private (codes 224-254) and VSI (code 43) options are not decoded
+by @c LibDHCP::unpackOptions4 but by @ref isc::dhcp::Dhcpv4Srv::deferredUnpack
+function after classification. To make this function to perform or not
+deferred processing the simplest is to add or not the option code
+to the @ref isc::dhcp::Pkt4::deferredOptions list.
+
 @section dhcpv4DDNSIntegration DHCPv4 Server Support for the Dynamic DNS Updates
 The DHCPv4 server supports processing of the DHCPv4 Client FQDN option (RFC4702)
 and the DHCPv4 Host Name option (RFC2132). A client may send one of these options

src/bin/dhcp4/dhcp4_srv.cc

@@ -2867,13 +2867,17 @@ Dhcpv4Srv::deferredUnpack(Pkt4Ptr& query)
             continue;
         }
         // Get the existing option for its content and remove all
-        const OptionBuffer buf = query->getOption(code)->getData();
+        OptionPtr opt = query->getOption(code);
+        if (!opt) {
+            /* should not happen but do not crash anyway */
+            continue;
+        }
+        const OptionBuffer buf = opt->getData();
         while (query->delOption(code)) {
             /* continue */
         }
         // Unpack the option and add it
-        OptionPtr opt = def->optionFactory(Option::V4, code,
-                                           buf.cbegin(), buf.cend());
+        opt = def->optionFactory(Option::V4, code, buf.cbegin(), buf.cend());
         query->addOption(opt);
     }
 }