[trac4101] Update per review comments

Notable items:
Removed a lot of the classification text from dhcp4.xml and dhcp6.xml
leaving a brief description with a pointer to the main text and some
examples.

Added more examples

doc/guide/classify.xml

@@ -32,8 +32,8 @@
       It is envisaged that client classification will be used for changing the
       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
+      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
       options and, for DHCPv4 cable modems, the setting of specific options for use with
       the TFTP server address and the boot file field.
@@ -58,7 +58,7 @@
       When determining which options to include in the response the server will examine
       the union of options from all of the assigned classes. In the case two or more
       classes include the same option, the value from the first class examined will
-      be used.  Similarly if two or more classes are associated with a subnet, the
+      be used.  Similarly if two or more classes are  associated with subnets, the
       first class examined will be used. In the future the processing order of the
       various classes may be specified but for now it is being left unspecified and
       may change in future releases.
@@ -201,17 +201,47 @@
           </tgroup>
         </table>
 
-      The substring operator "substring(value, start, length)" accepts both positive and
-      negative values for the starting position and the length.  For "start", a value of
-      0 is the first byte in the string while -1 is the last byte.  If the starting
-      point is outside of the original string an empty string is returned.  "length"
-      is the number of bytes to extract.  A negative number means to count towards
-      the beginning of the string but doesn't include the byte pointed to by "start".
-      The special value "all" means to return all bytes from start to the end of the
-      string.  If length is longer than the remaining portion of the string then
-      the entire remaining portion is returned.
+        <section>
+          <title>Substring</title>
+          The substring operator "substring(value, start, length)" accepts both positive and
+          negative values for the starting position and the length.  For "start", a value of
+          0 is the first byte in the string while -1 is the last byte.  If the starting
+          point is outside of the original string an empty string is returned.  "length"
+          is the number of bytes to extract.  A negative number means to count towards
+          the beginning of the string but doesn't include the byte pointed to by "start".
+          The special value "all" means to return all bytes from start to the end of the
+          string.  If length is longer than the remaining portion of the string then
+          the entire remaining portion is returned.  Some examples may be helpful:
+
+          <itemizedlist>
+          <listitem><para>
+            substring('foobar', 0, 6) == 'foobar'
+          </para></listitem>
+          <listitem><para>
+            substring('foobar', 3, 3) == 'bar'
+          </para></listitem>
+          <listitem><para>
+            substring('foobar', 3, all) == 'bar'
+          </para></listitem>
+          <listitem><para>
+            substring('foobar', 1, 4) == 'ooba'
+          </para></listitem>
+          <listitem><para>
+            substring('foobar', -5, 4) == 'ooba'
+          </para></listitem>
+          <listitem><para>
+            substring('foobar', -1, -4) == 'ooba'
+          </para></listitem>
+          <listitem><para>
+            substring('foobar', 5, -4) == 'ooba'
+          </para></listitem>
+          <listitem><para>
+            substring('foobar', 10, 2) == ''
+          </para></listitem>
+          </itemizedlist>
+        </section>
       </para>
-  </section>
+    </section>
 
   <note>
   <para>
@@ -242,9 +272,14 @@
       </para>
 
       <para>
+      In the following 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;. Members of this class will be given 192.0.2.1 and
+      192.0.2.2 as their domain name servers.
+
         <screen>
 "Dhcp4": {
-    "client-class": [<userinput>
+    "client-classes": [<userinput>
         {
             "name": "Client_foo",
             "test": "substring(option[61].text,0,3) == 'foo'",
@@ -265,10 +300,31 @@
       </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;.
-      Members of this class will be  given 192.0.2.1 and 192.0.2.2 as their domain name
-      servers.
+      This example shows a client class being defined for use by the DHCPv6 server.
+      In it the class named &quot;Client_enterprise&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). Members of this
+      class will be given an 2001:db8:0::1 and 2001:db8:2::1 as their domain name servers.
+        <screen>
+"Dhcp6": {
+    "client-classes": [<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>
   </section>
 
@@ -276,7 +332,11 @@
     <title>Configuring Subnets With Class Information</title>
       <para>
         In certain cases it beneficial to restrict access to certain subnets
-        only to clients that belong to a given class.
+        only to clients that belong to a given class using the "client-class"
+        keyword when defining the subnet.
+      </para>
+
+      <para>
         Let's assume that the server is connected to a network segment that uses
         the 192.0.2.0/24 prefix. The Administrator of that network has decided
         that addresses from range 192.0.2.10 to 192.0.2.20 are going to be
@@ -285,7 +345,7 @@
         configuration can be achieved in the following way:
         <screen>
 "Dhcp4": {
-    "client-class": [
+    "client-classes": [
         {
             "name": "Client_foo",
             "test": "substring(option[61].text,0,3) == 'foo'",
@@ -306,8 +366,43 @@
             "subnet": "192.0.2.0/24",
             "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
             "client-class": "Client_foo"
+        },
+        ...
+    ],</userinput>,
+    ...
+}</screen>
+      </para>
+
+      <para>
+     	The following example shows restricting access to a DHCPv6 subnet.  This
+        configuration will restrict use of the addresses 2001:db8:1::1 to
+        2001:db8:1::FFFF to members of the "Client_enterprise" class.
+
+        <screen>
+"Dhcp6": {
+    "client-classes": [
+        {
+            "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>
+    "subnet6": [
+        {
+            "subnet": "2001:db8:1::/64",
+            "pools": [ { "pool": "2001:db8:1::-2001:db8:1::ffff" } ],
+            "client-class": "Client_enterprise"
         }
-    ]</userinput>,
+    ],</userinput>
     ...
 }</screen>
       </para>

doc/guide/dhcp4-srv.xml

@@ -1567,14 +1567,26 @@ It is merely echoed by the server
 
       <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 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.
+      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 the assignment of leases from different
+      pools, the assignmen 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 seletion, assignment of different options, and, for cable modems, there
+      are specific options for use with the TFTP server address and the boot file field.
+      </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="classification-subnets"/>.
       </para>
 
       <para>
@@ -1594,18 +1606,6 @@ It is merely echoed by the server
       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.
@@ -1632,51 +1632,20 @@ It is merely echoed by the server
       </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>
-
+        <title>Configuring Classes Example</title>
         <para>
-        The option data is a list which defines any options that should be assigned
-        to members of this class.
-        </para>
+        The following example shows how to configure a class using an expression
+        and a subnet making use of that class. This configuration defines the
+        class named &quot;Client_foo&quot;.
+        It is comprised of all clients who's client ids (option 61) start with the
+        string &quot;foo&quot;. Members of this class will be given addresses 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. For a deeper discussion of the classification process see
+        <xref linkend="classify"/>.
 
-        <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>
+    "client-classes": [
         {
             "name": "Client_foo",
             "test": "substring(option[61].text,0,3) == 'foo'",
@@ -1689,40 +1658,35 @@ It is merely echoed by the server
                     "data": "192.0.2.1, 192.0.2.2"
                 }
             ]
-        }
-</userinput>
+        },
+        ...
+    ],
+    "subnet4": [
+        {
+            "subnet": "192.0.2.0/24",
+            "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
+            "client-class": "Client_foo"
+        },
+        ...
+    ],
     ...
 }</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>
+        This example shows a configuration using an automatcially generated
+        "VENDOR_CLASS_" class. The Administrator of the network has
+        decided that addresses from range 192.0.2.10 to 192.0.2.20 are
+        going to be managed by the Dhcp4 server and only clients belonging to the
+        docsis3.0 client class are allowed to use that pool.
 
-      <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
-        extension of a previous example from <xref linkend="dhcp4-address-config"/>.
-        Let's assume that the server is connected to a network segment that uses
-        the 192.0.2.0/24 prefix. The Administrator of that network has decided
-        that addresses from range 192.0.2.10 to 192.0.2.20 are going to be
-        managed by the Dhcp4 server. Only clients belonging to client class
-        VENDOR_CLASS_docsis3.0 are allowed to use this subnet. Such a
-        configuration can be achieved in the following way:
         <screen>
 "Dhcp4": {
     "subnet4": [
         {
-            <userinput>"subnet": "192.0.2.0/24",
+            "subnet": "192.0.2.0/24",
             "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
-            "client-class": "VENDOR_CLASS_docsis3.0"</userinput>
+            <userinput>"client-class": "VENDOR_CLASS_docsis3.0"</userinput>
         }
     ],
     ...
@@ -2770,7 +2734,7 @@ It is merely echoed by the server
         <para>
           In certain cases, it is useful to mix relay address information,
           introduced in <xref linkend="dhcp4-relay-override"/> with client
-          classification, explained in <xref linkend="dhcp4-subnet-class"/>.
+          classification, explained in <xref linkend="classify"/>.
           One specific example is cable network, where typically modems
           get addresses from a different subnet than all devices connected
           behind them.

doc/guide/dhcp6-srv.xml

@@ -1555,13 +1555,25 @@ should include options from the isc option space:
 
       <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 are only two mechanisms that are taking
-      advantage of client classification: subnet selection and assigning differnet
-      options.
+      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 the assignement of leases from different
+      pools, the assigment of different options (or different values of the same
+      options) etc. In the current release of the sofware however, there are
+      only two mechanisms that take advantage of client classification:
+      subnet selection and assignment of 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 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="classification-subnets"/>.
       </para>
 
       <para>
@@ -1581,80 +1593,26 @@ should include options from the isc option space:
       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="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>
+        <title>Configuring Classes Example</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>
+        The following example shows how to configure a class using an expression
+        and a subnet making use of that class. This configuration defines the
+        class named &quot;Client_enterprise&quot;. 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 for their domain name servers. For a deeper
+        discussion of the classification process see <xref linkend="classify"/>.
 
-        <para>
-          <screen>
+        <screen>
 "Dhcp6": {
-    "subnet6": [
-        {
-            "subnet": "2001:db8:1::/64",
-            "pools": [ { "pool": "2001:db8:1::-2001:db8:1::ffff" } ],
-            "client-class": "Client_enterprise"
-        }
-    ],
-    "client-class": [
-<userinput>
+    "client-classes": [
         {
             "name": "Client_enterprise",
             "test": "substring(option[2].hex,0,6) == 0x0002AABBCCDD'",
@@ -1667,35 +1625,26 @@ should include options from the isc option space:
                     "data": "2001:db8:0::1, 2001:db8:2::1"
                 }
             ]
+        },
+        ...
+    ],
+    "subnet6": [
+        {
+            "subnet": "2001:db8:1::/64",
+            "pools": [ { "pool": "2001:db8:1::-2001:db8:1::ffff" } ],
+            "client-class": "Client_enterprise"
         }
-</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>
+      </para>
 
-      <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
-        extension of a previous example from <xref linkend="dhcp6-address-config"/>.
-
-        Let's assume that the server is connected to a network segment that uses
-        the 2001:db8:1::/64 prefix. The Administrator of that network has
-        decided that addresses from range 2001:db8:1::1 to 2001:db8:1::ffff are
-        going to be managed by the Dhcp6 server. Only clients belonging to the
-        eRouter1.0 client class are allowed to use that pool. Such a
-        configuration can be achieved in the following way:
+      <para>
+      This example shows a configuration using an automatcially generated
+      "VENDOR_CLASS_" class. The Administrator of the network has
+      decided that addresses from range 2001:db8:1::1 to 2001:db8:1::ffff are
+      going to be managed by the Dhcp6 server and only clients belonging to the
+      eRouter1.0 client class are allowed to use that pool.
 
         <screen>
 "Dhcp6": {
@@ -2614,7 +2563,7 @@ should include options from the isc option space:
         <para>
           In certain cases, it is useful to mix relay address information,
           introduced in <xref linkend="dhcp6-relay-override"/> with client
-          classification, explained in <xref linkend="dhcp6-subnet-class"/>.
+          classification, explained in <xref linkend="classify"/>.
           One specific example is a cable network, where typically modems
           get addresses from a different subnet than all devices connected
           behind them.