[trac4101] Update v4 and v6 pages

Update the v4 and v6 pages to reflect the new classification.
These are shortened versions of the main classification page.

Also update the option description to incude .text and .hex modifiers.

doc/guide/classify.xml

@@ -34,10 +34,10 @@
       It is envisaged that client classification will be used for changing the
       behavior of almost any part of the DHCP message processing, including assigning
       leases from different pools, assigning different options (or different values of
-      the same options) etc. For now, there are only two mechanisms that take
-      advantage of client classification: subnet selection and assigning different
-      options.  For cable modems there are specific options for use with the TFTP
-      server address and the boot file field.
+      the same options) etc. For now, there are only three mechanisms that take
+      advantage of client classification: subnet selection, assigning different
+      options and for DHCPv4 cable modems there are specific options for use with
+      the TFTP server address and the boot file field.
       </para>
 
       <para>
@@ -80,7 +80,7 @@
       <para>
         The power of the expressions in the classification step is deliberately
         limited in order to minimize the amount of time required to process each
-	expression. The expression for each class must be executed on each packet,
+        expression. The expression for each class must be executed on each packet,
         if they are overly complex or time consuming they may impact the performance
         of the server. If you need complex or time consuming expressions you
         should write a hook to perform the necessary work.
@@ -123,11 +123,17 @@
       <para>
       Expressions are pre-processed during the parsing of the configuration file
       and converted to an internal representation. This allows certain types of
-      errors (such as incorrect syntax) to be caught and logged. Other errors
-      (for example mistakes when setting up the values for a substring) won't be
-      caught and may affect the classification. In general if an expression has
-      a problem a log message will be emitted at the debug level and the result
-      will be an empty string.
+      errors to be caught and logged during parsing.  Examples of these errors
+      include incorrect number or types of arguments to an operator.  The
+      evaluation code will also check for this class of error and generally
+      throw an exception, though they should not occur in a normally functioning
+      system.
+      </para>
+
+      <para>
+      Other issues, for example the starting position of a substring being
+      outside of the substring or an option not existing in the packet, result
+      in the operator returning an empty string.
       </para>
 
       <para>
@@ -147,7 +153,7 @@
           <thead>
             <row>
               <entry>Name</entry>
-	      <entry>Example</entry>
+              <entry>Example</entry>
               <entry>Description</entry>
             </row>
           </thead>
@@ -155,7 +161,8 @@
 <row><entry>String</entry><entry>'example'</entry><entry>A string</entry></row>
 <row><entry>Hex String</entry><entry>0XABCD</entry><entry>A hexadecimal string</entry></row>
 <row><entry>Integer</entry><entry>123</entry><entry>An integer value</entry></row>
-<row><entry>Option</entry><entry>option[code]</entry><entry>The value of the option with code "code" from the packet</entry></row>
+<row><entry>Option Text</entry><entry>option[code].text</entry><entry>The value of the option with code "code" from the packet as text</entry></row>
+<row><entry>Option Hex</entry><entry>option[code].hex</entry><entry>The value of the option with code "code" from the packet as hex</entry></row>
           </tbody>
           </tgroup>
         </table>
@@ -169,7 +176,10 @@
 
       <para>
       Option extracts the value of the given option from the incoming packet. If the
-      packet doesn't contain the option it returns an empty string.
+      packet doesn't contain the option it returns an empty string.  The string can
+      be presented as text or hex with the ".text" or ".hex" modifiers.  In both
+      cases only the payload is presented the type code and length fields aren't
+      included.
       </para>
 
       <para>
@@ -214,7 +224,7 @@
       The name must exist and must be unique amongst all classes. The test
       expression and option data are optional.
       </para>
-      
+
       <para>
       The test expression is a string containing the logical expression used to
       determine membership in the class.  The entire expression is in double
@@ -240,7 +250,7 @@
 <userinput>
         {
             "name": "Client_foo",
-            "test": "substring(option[61],0,3) == 'foo'",
+            "test": "substring(option[61].text,0,3) == 'foo'",
             "option-data": [
                 {
                     "name": "doamin-name-servers",
@@ -291,7 +301,7 @@
     "client-class": [
         {
             "name": "Client_foo",
-            "test": "substring(option[61],0,3) == 'foo'",
+            "test": "substring(option[61].text,0,3) == 'foo'",
             "option-data": [
                 {
                     "name": "doamin-name-servers",

doc/guide/dhcp4-srv.xml

@@ -1558,58 +1558,154 @@ It is merely echoed by the server
 
     <section id="dhcp4-client-classifier">
       <title>Client Classification in DHCPv4</title>
-      <note>
       <para>
-        The DHCPv4 server has been extended to support limited client classification.
-        Although the current capability is modest, it is expected to be expanded
-        in the future. However, it is envisaged that the majority of client classification
-        extensions will be using hooks extensions.
+      The DHCPv4 server includes support for client classification.  At the
+      current time the capabilities of the classification process are limited
+      but it is expected they will be expanded in the future. For a deeper
+      discussion of the classification process see <xref linkend="classify"/>.
       </para>
-      </note>
-      <para>In certain cases it is useful to differentiate between different
-      types of clients and treat them differently. The process of doing
-      classification is conducted in two steps. The first step is to assess an
-      incoming packet and assign it to zero or more classes. This classification
-      is currently simple, but is expected to grow in capability soon. Currently
-      the server checks whether an incoming packet includes the vendor class identifier
-      option (60). If it does, the content of that option is prepended with
-      &quot;VENDOR_CLASS_&quot; then it is interpreted as a class. For example,
-      modern cable modems will send this option with value &quot;docsis3.0&quot;
-      and as a result the packet will belong to class &quot;VENDOR_CLASS_docsis3.0&quot;.
-      </para>
-
-      <para>It is envisaged that the client classification will be used for changing the
+
+      <para>
+      In certain cases it is useful to differentiate between different types of
+      clients and treat them accordingly. It is envisaged that client classification
+      will be used for changing the
       behavior of almost any part of the DHCP message processing, including assigning
       leases from different pools, assigning different options (or different values of
-      the same options) etc. For now, there are only two mechanisms that are taking
-      advantage of client classification: specific processing for cable modems and
-      subnet selection.</para>
+      the same options) etc. For now, there are only three mechanisms that are taking
+      advantage of client classification: subnet seletion, assigning different options,
+      and for cable modems there are 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 first step
+      is to assess an incoming packet and assign it to zero or more classes.  The
+      second step is to choose a subnet, possibly based on the class information.
+      The third step is to assign options again possibly based on the class
+      information.
+      </para>
+
+      <para>
+      There are two methods of doing classification. The first is automatic and relies
+      on examining the values in the vendor class options. Information from these
+      options is extracted and a class name is constructed from it and added to
+      the class list for the packet. The second allows you to specify an expression
+      that is evaluated for each packet. If the result is true the packet is
+      a member of the class.
+      </para>
 
       <para>
+      Kea can be instructed to limit access to given subnets based on class information.
+      This is particularly useful for cases where two types of devices share the
+      same link and are expected to be served from two different subnets. The
+      primary use case for such a scenario is cable networks. There are two
+      classes of devices: the cable modem itself, which should be handed a lease
+      from subnet A and all other devices behind the modem that should get a lease
+      from subnet B. That segregation is essential to prevent overly curious
+      users from playing with their cable modems. For details on how to set up
+      class restrictions on subnets, see <xref linkend="dhcp4-subnet-class"/>.
+      </para>
+
+      <note><para>
+        Care should be taken with client classification as it is easy for
+        clients that do not meet class criteria to be denied any service altogether.
+      </para></note>
+
+      <section>
+        <title>Using Vendor Class Information in Classification</title>
+        <para>
+        The server checks whether an incoming packet includes the vendor class identifier
+        option (60). If it does, the content of that option is prepended with
+        &quot;VENDOR_CLASS_&quot; then it is interpreted as a class. For example,
+        modern cable modems will send this option with value &quot;docsis3.0&quot;
+        and as a result the packet will belong to class &quot;VENDOR_CLASS_docsis3.0&quot;.
+        </para>
+
+        <para>
         For clients that belong to the VENDOR_CLASS_docsis3.0 class, the siaddr
         field is set to the value of next-server (if specified in a subnet). If
         there is a boot-file-name option specified, its value is also set in the
         file field in the DHCPv4 packet. For eRouter1.0 class, the siaddr is
         always set to 0.0.0.0. That capability is expected to be moved to
         an external hook library that will be dedicated to cable modems.
-      </para>
+        </para>
+      </section>
 
-      <para>
-        Kea can be instructed to limit access to given subnets based on class information.
-        This is particularly useful for cases where two types of devices share the
-        same link and are expected to be served from two different subnets. The
-        primary use case for such a scenario is cable networks. There are two
-        classes of devices: the cable modem itself, which should be handed a lease
-        from subnet A and all other devices behind the modem that should get a lease
-        from subnet B. That segregation is essential to prevent overly curious
-        users from playing with their cable modems. For details on how to set up
-        class restrictions on subnets, see <xref linkend="dhcp4-subnet-class"/>.
-      </para>
+      <section>
+        <title>Using Expressions in Classification</title>
+        <para>
+        The expression portion of classification contains operators and values.
+        Values are currently strings and operators take a string or strings and
+        return another string. When all the operations have completed
+        the result should be a value of &quot;true&quot; or &quot;false&quot;.
+        The packet belongs to
+        the class (and the class name is added to the list of classes) if the result
+        is &quot;true&quot;. Expressions are written in standard format and can be nested.
+        For more information about expressions see
+        <xref linkend="classification-using-expressions"/>
+        </para>
+      </section>
 
+      <section>
+        <title>Configuring Classes</title>
+        <para>
+        A class contains three items: a name, a test expression and option data.
+        The name must exist and must be unique amongst all classes. The test
+        expression and option data are optional.
+        </para>
 
-    <section id="dhcp4-subnet-class">
-      <title>Limiting Access to IPv4 Subnet to Certain Classes</title>
-      <para>
+        <para>
+        The test expression is a string containing the logical expression used to
+        determine membership in the class.  The entire expression is in double
+        quotes.
+        </para>
+
+        <para>
+        The option data is a list which defines any options that should be assigned
+        to members of this class.
+        </para>
+
+        <para>
+          <screen>
+"Dhcp4": {
+    "subnet4": [
+        {
+            "subnet": "192.0.2.0/24",
+            "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
+            "client-class": "Client_foo"
+        }
+    ],
+    "client-class": [
+<userinput>
+        {
+            "name": "Client_foo",
+            "test": "substring(option[61].text,0,3) == 'foo'",
+            "option-data": [
+                {
+                    "name": "doamin-name-servers",
+                    "code": 6,
+                    "space": "dhcp4",
+                    "csv-format": true,
+                    "data": "192.0.2.1, 192.0.2.2"
+                }
+            ]
+        }
+</userinput>
+    ...
+}</screen>
+        </para>
+
+        <para>
+        In this example the class named &quot;Client_foo&quot; is defined.  It is comprised
+        of all clients who's client ids (option 61) start with the string &quot;foo&quot;.
+        They will be given an address from 192.0.2.10 to 192.0.2.20 and 192.0.2.1
+        and 192.0.2.2 as their domain name servers.
+        </para>
+      </section>
+
+      <section id="dhcp4-subnet-class">
+        <title>Limiting Access to IPv4 Subnet to Certain Classes</title>
+        <para>
         In certain cases it beneficial to restrict access to certain subnets
         only to clients that belong to a given subnet. For details on client
         classes, see <xref linkend="dhcp4-client-classifier"/>. This is an
@@ -1631,13 +1727,8 @@ It is merely echoed by the server
     ],
     ...
 }</screen>
-      </para>
-
-      <para>
-        Care should be taken with client classification as it is easy for
-        clients that do not meet class criteria to be denied any service altogether.
-      </para>
-    </section>
+        </para>
+      </section>
     </section>
 
     <section id="dhcp4-ddns-config">

doc/guide/dhcp6-srv.xml

@@ -1545,49 +1545,146 @@ should include options from the isc option space:
 
     <section id="dhcp6-client-classifier">
       <title>Client Classification in DHCPv6</title>
-      <note>
+
       <para>
-        DHCPv6 server has been extended to support limited client classification.
-        Although the current capability is modest, it is expected to be expanded
-        in the future. It is envisaged that the majority of client classification
-        extensions will be using hooks extensions.
+      The DHCPv4 server includes support for client classification.  At the
+      current time the capabilities of the classification process are limited
+      but it is expected they will be expanded in the future. For a deeper
+      discussion of the classification process see <xref linkend="classify"/>.
       </para>
-      </note>
-      <para>In certain cases it is useful to differentiate between different types
-      of clients and treat them differently. The process of doing classification
-      is conducted in two steps. The first step is to assess an incoming packet and
-      assign it to zero or more classes. This classification is currently simple,
-      but is expected to grow in capability soon. Currently the server checks whether
-      the incoming packet includes vendor class option (16). If it has, the content
-      of that option is prepended with &quot;VENDOR_CLASS_&quot; then it is interpreted as a
-      class. For example, modern cable modems will send this option with value
-      &quot;docsis3.0&quot; and as a result the packet will belong to class
-      &quot;VENDOR_CLASS_docsis3.0&quot;.
-      </para>
-
-      <para>It is envisaged that the client classification will be used for changing
+
+      <para>
+      In certain cases it is useful to differentiate between different types
+      of clients and treat them differently. It is envisaged that the client
+      classification will be used for changing the
       behavior of almost any part of the DHCP engine processing, including assigning
       leases from different pools, assigning different option (or different values of
-      the same options) etc. For now, there is only one mechanism that is taking
-      advantage of client classification: subnet selection.</para>
+      the same options) etc. For now, there are only two mechanisms that are taking
+      advantage of client classification: subnet selection and assigning differnet
+      options.
+      </para>
 
       <para>
-        Kea can be instructed to limit access to given subnets based on class information.
-        This is particularly useful for cases where two types of devices share the
-        same link and are expected to be served from two different subnets. The
-        primary use case for such a scenario are cable networks. There are two
-        classes of devices: the cable modem itself, which should be handed a lease
-        from subnet A and all other devices behind modems that should get a lease
-        from subnet B. That segregation is essential to prevent overly curious
-        users from playing with their cable modems. For details on how to set up
-        class restrictions on subnets, see <xref linkend="dhcp6-subnet-class"/>.
+      The process of doing classification is conducted in three steps. The first step
+      is to assess an incoming packet and assign it to zero or more classes.  The
+      second step is to choose a subnet, possibly based on the class information.
+      The third step is to assign options again possibly based on the class
+      information.
       </para>
 
-    </section>
+      <para>
+      There are two methods of doing classification. The first is automatic and relies
+      on examining the values in the vendor class options. Information from these
+      options is extracted and a class name is constructed from it and added to
+      the class list for the packet. The second allows you to specify an expression
+      that is evaluated for each packet. If the result is true the packet is
+      a member of the class.
+      </para>
 
-    <section id="dhcp6-subnet-class">
-      <title>Limiting access to IPv6 subnet to certain classes</title>
       <para>
+      Kea can be instructed to limit access to given subnets based on class information.
+      This is particularly useful for cases where two types of devices share the
+      same link and are expected to be served from two different subnets. The
+      primary use case for such a scenario is cable networks. There are two
+      classes of devices: the cable modem itself, which should be handed a lease
+      from subnet A and all other devices behind the modem that should get a lease
+      from subnet B. That segregation is essential to prevent overly curious
+      users from playing with their cable modems. For details on how to set up
+      class restrictions on subnets, see <xref linkend="dhcp6-subnet-class"/>.
+      </para>
+
+      <note><para>
+        Care should be taken with client classification as it is easy for
+        clients that do not meet class criteria to be denied any service altogether.
+      </para></note>
+
+      <section>
+        <title>Using Vendor Class Information in Classification</title>
+        <para>
+        The server checks whether an incoming packet includes the vendor class
+        option (16). If it does, the content of that option is prepended with
+        &quot;VENDOR_CLASS_&quot; then it is interpreted as a class. For example,
+        modern cable modems will send this option with value &quot;docsis3.0&quot;
+        and as a result the packet will belong to class &quot;VENDOR_CLASS_docsis3.0&quot;.
+        </para>
+      </section>
+
+      <section>
+        <title>Using Expressions in Classification</title>
+        <para>
+        The expression portion of classification contains operators and values.
+        Values are currently strings and operators take a string or strings and
+        return another string. When all the operations have completed
+        the result should be a value of &quot;true&quot; or &quot;false&quot;.
+        The packet belongs to
+        the class (and the class name is added to the list of classes) if the result
+        is &quot;true&quot;. Expressions are written in standard format and can be nested.
+        For more information about expressions see
+        <xref linkend="classification-using-expressions"/>
+        </para>
+      </section>
+
+      <section>
+        <title>Configuring Classes</title>
+        <para>
+        A class contains three items: a name, a test expression and option data.
+        The name must exist and must be unique amongst all classes. The test
+        expression and option data are optional.
+        </para>
+
+        <para>
+        The test expression is a string containing the logical expression used to
+        determine membership in the class.  The entire expression is in double
+        quotes.
+        </para>
+
+        <para>
+        The option data is a list which defines any options that should be assigned
+        to members of this class.
+        </para>
+
+        <para>
+          <screen>
+"Dhcp6": {
+    "subnet6": [
+        {
+            "subnet": "2001:db8:1::/64",
+            "pools": [ { "pool": "2001:db8:1::-2001:db8:1::ffff" } ],
+            "client-class": "Client_enterprise"
+        }
+    ],
+    "client-class": [
+<userinput>
+        {
+            "name": "Client_enterprise",
+            "test": "substring(option[2].hex,0,6) == 0x0002AABBCCDD'",
+            "option-data": [
+                {
+                    "name": "dns-servers",
+                    "code": 23,
+                    "space": "dhcp6",
+                    "csv-format": true,
+                    "data": "2001:db8:0::1, 2001:db8:2::1"
+                }
+            ]
+        }
+</userinput>
+    ...
+}</screen>
+        </para>
+
+        <para>
+        In this example the class named &quot;Client_foo&quot; is defined.  It is comprised
+        of all clients who's client identifiers start with the given hex string (which
+        would indicate a DUID based on an enterprise id of 0xAABBCCDD).
+        They will be given an address from 2001:db8:1::0 to 2001:db8:1::FFFF and
+        2001:db8:0::1 and 2001:db8:2::1 their domain name servers.
+        </para>
+      </section>
+
+      <section id="dhcp6-subnet-class">
+        <title>Limiting access to IPv6 subnet to certain classes</title>
+        <para>
         In certain cases it beneficial to restrict access to certain subnets
         only to clients that belong to a given class. For details on client
         classes, see <xref linkend="dhcp6-client-classifier"/>. This is an
@@ -1616,15 +1713,10 @@ should include options from the isc option space:
     ...
 }
 </screen>
-      </para>
-
-      <para>
-        Care should be taken with client classification as it is easy for
-        clients that do not meet class criteria to be denied any service altogether.
-      </para>
+        </para>
+      </section>
     </section>
 
-
     <section id="dhcp6-ddns-config">
       <title>Configuring DHCPv6 for DDNS</title>
       <para>