[#3583] Updated doc

/doc/examples/kea4/all-keys.json
/doc/examples/kea6/all-keys.json
    Added client-classes to option-data

/doc/sphinx/arm/classify.rst
    Added new section "Option Class-Tagging"

/doc/sphinx/arm/dhcp4-srv.rst
/doc/sphinx/arm/dhcp6-srv.rst
    Added notes with pointers to new section

doc/examples/kea4/all-keys.json

@@ -695,6 +695,13 @@
                 // requested.
                 "always-send": false,
 
+                // An optional list of classes for which this option applies.
+                // If the the client matches any of the classes in this list the
+                // option will be applied. If the list is empty or is
+                // omitted this option will be applied regardless of class
+                // membership.
+                "client-classes": [ "class1", "class2" ],
+
                 // Option code. It is not required if the option name is
                 // provided.
                 "code": 6,
@@ -1049,6 +1056,13 @@
                                 // should be always sent or sent only when requested.
                                 "always-send": false,
 
+                                // An optional list of classes for which this option applies.
+                                // If the the client matches any of the classes in this list the
+                                // option will be applied. If the list is empty or is
+                                // omitted this option will be applied regardless of class
+                                // membership.
+                                "client-classes": [ ],
+
                                 // Option code.
                                 "code": 3,
 

doc/examples/kea6/all-keys.json

@@ -600,6 +600,13 @@
                 // requested.
                 "always-send": false,
 
+                // An optional list of classes for which this option applies.
+                // If the the client matches any of the classes in this list the
+                // option will be applied. If the list is empty or is
+                // omitted this option will be applied regardless of class
+                // membership.
+                "client-classes": [ "class1", "class2" ],
+
                 // Option code. It is not required if the option name is
                 // provided.
                 "code": 23,
@@ -977,6 +984,13 @@
                                 // should be always sent or sent only when requested.
                                 "always-send": false,
 
+                                // An optional list of classes for which this option applies.
+                                // If the the client matches any of the classes in this list the
+                                // option will be applied. If the list is empty or is
+                                // omitted this option will be applied regardless of class
+                                // membership.
+                                "client-classes": [ ],
+
                                 // Option code.
                                 "code": 7,
 

doc/sphinx/arm/classify.rst

@@ -1195,6 +1195,104 @@ the client requested. As the NTP server was defined twice, the server
 chooses only one of the values for the reply; the class from which the
 value is obtained is determined as explained in the previous paragraphs.
 
+.. _option-class-tagging:
+
+Option Class-Tagging
+====================
+
+Option class-tagging allows an option value to conditionally applied 
+to the response based on the client's class membership.  The effect is 
+similar to using an if-block in ISC DHCP to conditionally include 
+options at a given scope.  Class-tagging is done by specifying a list of
+one of more class names in the option's ``client-classes`` entry.
+
+Consider a case where members of a given class need the same value for
+one option but a subnet-specific value for another option.  The following
+example shows class-tagging used to give clients who belong to "GROUP1"
+a subnet-specific value for option "bar", while giving all members of "GROUP1"
+the same value for option "foo":
+
+::
+
+    {
+        "client-classes": [
+        {
+            "name": "GROUP1",
+            "test":"substring(option[123].hex,0,4) == 'ONE'",
+            "option-data": [{
+                "name": "foo",
+                "data": "somefile.txt"
+            }]
+        }],
+        "subnet4": [
+        {
+            "id": 1,
+            "subnet": "178.16.1.0/24",
+            "option-data": [{
+                "client-classes": ["GROUP1"],
+                "name": "bar",
+                "data": 123
+            }]
+        },
+        {
+            "id": 2,
+            "subnet": "178.16.2.0/24",
+            "option-data": [
+            {
+                "client-classes": ["GROUP1"],
+                "name": "bar",
+                "data": 789
+            }]
+        }]
+    }
+
+When ``never-send`` for an option is true at any scope, all 
+``client-classes`` entries for that option are ignored. The
+option will not included.
+
+When ``always-send`` is true at any scope, the option will be 
+included unless, the option determined by scope specifies 
+a ``client-classes`` list that does not contain any of the 
+client's classes.
+
+Otherwise, An option requested by the client will be included in 
+the response if  the option either does not specify ``client-classes``
+or the client belongs to at least one of the classes in ``client-classes``.
+
+When an option's class-tag does not match, it is as though 
+the option was not specified at that scope.  In the following
+example the option "foo" is specified for both the subnet and
+the pool.  The pool specification includes a class-tag that limits
+the option to members of class "melon":  
+
+::
+
+    {
+        "id": 100,
+        "subnet": "178.16.1.0/24",
+        "option-data"[{
+            "name": "foo",
+            "data": 456
+        }],
+        "pools": [{
+            "pool": "178.16.1.100 - 178.16.1.200"
+            "option-data"[{
+                "name": "foo",
+                "data": 123,
+                "client-classes" : [ "melon" ]
+            }]
+        }]
+    }]
+
+Clients that match class "melon" will have a value of 123 for option "foo",
+while clients that do not match "melon" will have a value of 456 for option
+"foo".  
+
+.. note::
+
+    Though examples above are for DHCPv4, class-tagging syntax and 
+    behavior is the same for DHPCv6. 
+
 Classes and Hooks
 =================
 

doc/sphinx/arm/dhcp4-srv.rst

@@ -1657,6 +1657,11 @@ responses on subnet ``192.0.3.0/24``. ``never-send`` has precedence over
    Both ``always-send`` and ``never-send`` have no effect on options
    which cannot be requested, for instance from a custom space.
 
+.. note::
+
+    Beginning with Kea 2.7.4, option inclusion can also be controlled through
+    option class-tagging, see :ref:`option-class-tagging`
+
 The ``name`` parameter specifies the option name. For a list of
 currently supported names, see :ref:`dhcp4-std-options-list`
 below. The ``code`` parameter specifies the option code, which must

doc/sphinx/arm/dhcp6-srv.rst

@@ -1658,6 +1658,11 @@ Options can also be specified in class or host-reservation scope. The
 current Kea options precedence order is (from most important to least): host
 reservation, pool, subnet, shared network, class, global.
 
+.. note::
+
+    Beginning with Kea 2.7.4, option inclusion can also be controlled through
+    option class-tagging, see :ref:`option-class-tagging`
+
 When a data field is a string and that string contains the comma (``,``;
 U+002C) character, the comma must be escaped with two backslashes (``\\,``;
 U+005C). This double escape is required because both the routine