[#3592] Updated ARM and added ChangeLog

modified:   ChangeLog
modified:   doc/sphinx/arm/classify.rst
modified:   doc/sphinx/arm/dhcp4-srv.rst
modified:   doc/sphinx/arm/dhcp6-srv.rst
modified:   doc/sphinx/arm/hooks-bootp.rst
modified:   doc/sphinx/arm/hooks-ha.rst

5 files changed, 101 insertions, 51 deletions

diff --git a/doc/sphinx/arm/classify.rst b/doc/sphinx/arm/classify.rst
index d6724ca9c4..d47c1abf69 100644
--- a/doc/sphinx/arm/classify.rst
+++ b/doc/sphinx/arm/classify.rst
@@ -1000,9 +1000,18 @@ Pool selection is performed after all host reservations lookups.
 Configuring Subnets With Class Information
 ==========================================
 
+.. note:
+
+    As of Kea 2.7.5, ``client-class`` (a single class name) has been replaced
+    with ``client-classes`` (a list of one or more class names) and is now
+    deprecated. It will still be accepted as input for a time to allow users
+    to migrate but will eventually be unsupported.
+
 In certain cases it is beneficial to restrict access to certain subnets
-only to clients that belong to a given class, using the ``client-class``
-keyword when defining the subnet.
+only to clients that belong to a given class, using the ``client-classes``
+parameter when defining the subnet.  This parameter may be used to sepcify
+a list of one or more classes to which clients must belong in order to
+use the subnet.
 
 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
@@ -1034,7 +1043,7 @@ this subnet. Such a configuration can be achieved in the following way:
                "id": 1,
                "subnet": "192.0.2.0/24",
                "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
-               "client-class": "Client_foo"
+               "client-classes": [ "Client_foo" ]
            },
            ...
        ],
@@ -1069,7 +1078,7 @@ configuration restricts use of the addresses in the range 2001:db8:1::1 to
                "id": 1,
                "subnet": "2001:db8:1::/64",
                "pools": [ { "pool": "2001:db8:1::-2001:db8:1::ffff" } ],
-               "client-class": "Client_enterprise"
+               "client-classes": "Client_enterprise"
            }
        ],
        ...
@@ -1080,9 +1089,17 @@ configuration restricts use of the addresses in the range 2001:db8:1::1 to
 Configuring Pools With Class Information
 ========================================
 
+.. note:
+
+    As of Kea 2.7.5, ``client-class`` (a single class name) has been replaced
+    with ``client-classes`` (a list of one or more class names) and is now
+    deprecated. It will still be accepted as input for a time to allow users
+    to migrate but will eventually be unsupported.
+
 Similar to subnets, in certain cases access to certain address or prefix
-pools must be restricted to only clients that belong to a given class,
-using the ``client-class`` when defining the pool.
+pools must be restricted to only clients that belong to at least one of a
+list of one or more classes, using the ``client-classes`` when defining
+the pool.
 
 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
@@ -1116,7 +1133,7 @@ to use this pool. Such a configuration can be achieved in the following way:
                "pools": [
                    {
                        "pool": "192.0.2.10 - 192.0.2.20",
-                       "client-class": "Client_foo"
+                       "client-classes": [ "Client_foo" ]
                    }
                ]
            },
@@ -1157,7 +1174,7 @@ configuration restricts use of the addresses in the range 2001:db8:1::1 to
                "pools": [
                    {
                        "pool": "2001:db8:1::-2001:db8:1::ffff",
-                       "client-class": "Client_foo"
+                       "client-classes": [ "Client_foo" ]
                    }
                ]
            },
diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst
index 899860c625..6a70511adf 100644
--- a/doc/sphinx/arm/dhcp4-srv.rst
+++ b/doc/sphinx/arm/dhcp4-srv.rst
@@ -3379,7 +3379,7 @@ class are allowed to use that pool.
                "id": 1,
                "subnet": "192.0.2.0/24",
                "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
-               "client-class": "VENDOR_CLASS_docsis3.0"
+               "client-classes": [ "VENDOR_CLASS_docsis3.0" ]
            }
        ],
        ...
@@ -3419,7 +3419,7 @@ DNS servers set to 192.0.2.1 and 192.0.2.2.
                "id": 1,
                "subnet": "192.0.2.0/24",
                "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
-               "client-class": "Client_foo"
+               "client-classes": [ "Client_foo" ]
            },
            ...
        ],
@@ -5912,7 +5912,7 @@ Pool Selection with Client Class Reservations
 Client classes can be specified in the Kea configuration file and/or via
 host reservations. The classes specified in the Kea configuration file are
 evaluated immediately after receiving the DHCP packet and therefore can be
-used to influence subnet selection using the ``client-class`` parameter
+used to influence subnet selection using the ``client-classes`` parameter
 specified in the subnet scope. The classes specified within the host
 reservations are fetched and assigned to the packet after the server has
 already selected a subnet for the client. This means that the client
@@ -5952,11 +5952,11 @@ within the subnet as follows:
                 "pools": [
                     {
                         "pool": "192.0.2.10-192.0.2.20",
-                        "client-class": "reserved_class"
+                        "client-classes": [ "reserved_class" ]
                     },
                     {
                         "pool": "192.0.2.30-192.0.2.40",
-                        "client-class": "unreserved_class"
+                        "client-classes": [ "unreserved_class" ]
                     }
                 ]
             }
@@ -6023,7 +6023,7 @@ following example:
                     "pools": [
                         {
                             "pool": "192.0.2.10-192.0.2.20",
-                            "client-class": "reserved_class"
+                            "client-classes": [ "reserved_class" ]
                         }
                     ]
                 },
@@ -6033,7 +6033,7 @@ following example:
                     "pools": [
                         {
                             "pool": "192.0.3.10-192.0.3.20",
-                            "client-class": "unreserved_class"
+                            "client-classes": [ "unreserved_class" ]
                         }
                     ]
                 }
@@ -6053,7 +6053,7 @@ In addition, the reservation for the client class must be specified at the
 global scope (global reservation) and ``reservations-global`` must be
 set to ``true``.
 
-In the example above, the ``client-class`` could also be specified at the
+In the example above, the ``client-classes`` could also be specified at the
 subnet level rather than the pool level, and would yield the same effect.
 
 .. _multiple-reservations-same-ip4:
@@ -6631,19 +6631,36 @@ Client Classification in Shared Networks
 
 Sometimes it is desirable to segregate clients into specific subnets
 based on certain properties. This mechanism is called client
-classification and is described in :ref:`classify`. Client
-classification can be applied to subnets belonging to shared networks in
+classification and is described in :ref:`classify`.
+
+Client classification can be applied to subnets belonging to shared networks in
 the same way as it is used for subnets specified outside of shared
 networks. It is important to understand how the server selects subnets
 for clients when client classification is in use, to ensure that the
 appropriate subnet is selected for a given client type.
 
-If a subnet is associated with a class, only the clients belonging to
-this class can use this subnet. If there are no classes specified for a
-subnet, any client connected to a given shared network can use this
-subnet. A common mistake is to assume that a subnet that includes a client
-class is preferred over subnets without client classes. Consider the
-following example:
+If a subnet is associated with one or more classes, only the clients belonging
+to at least one of these classes may this subnet. If there are no classes
+specified for a subnet, any client connected to a given shared network can use
+this subnet. A common mistake is to assume that a subnet that includes a client
+class is preferred over subnets without client classes.
+
+The ``client-classes`` parameter may be specified at the shared network, subnet,
+and/or pool scopes. If specified for a shared network, clients must belong to at
+least one of the classes specified for that network to be considered for subnets
+within that network. If specified for a subnet, clients must belong to at least
+one of the classes specified for that subnet to be considered for any of that
+subnet's pools.  If sepcified for a pool, clients must belong to at least one
+of the classes specified for that pool to be given a lease from that pool.
+
+.. note:
+
+    As of Kea 2.7.5, ``client-class`` (a single class name) has been replaced
+    with ``client-classes`` (a list of one or more class names) and is now
+    deprecated. It will still be accepted as input for a time to allow users
+    to migrate but will eventually be unsupported.
+
+Consider the following example:
 
 ::
 
@@ -6668,7 +6685,7 @@ following example:
                        "id": 2,
                        "subnet": "10.0.0.0/24",
                        "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ],
-                       "client-class": "b-devices"
+                       "client-classes": [ "b-devices" ]
                    }
                ]
            }
@@ -6715,13 +6732,13 @@ on option 93 values.
                        "id": 1,
                        "subnet": "192.0.2.0/26",
                        "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ],
-                       "client-class": "a-devices"
+                       "client-classes": [ "a-devices" ]
                    },
                    {
                        "id": 2,
                        "subnet": "10.0.0.0/24",
                        "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ],
-                       "client-class": "b-devices"
+                       "client-classes": [ "b-devices" ]
                    }
                ]
            }
@@ -6992,7 +7009,7 @@ everything connected behind the modems should get addresses from the
                "id": 1,
                "subnet": "10.1.1.0/24",
                "pools":  [ { "pool": "10.1.1.2 - 10.1.1.20" } ],
-               "client-class": "docsis3.0",
+               "client-classes": [ "docsis3.0" ],
                "relay": {
                    "ip-addresses": [ "10.1.1.1" ]
                }
diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst
index a1e0e8cf45..dadfe18435 100644
--- a/doc/sphinx/arm/dhcp6-srv.rst
+++ b/doc/sphinx/arm/dhcp6-srv.rst
@@ -3123,7 +3123,7 @@ servers set to 2001:db8:0::1 and 2001:db8:2::1.
                "id": 1,
                "subnet": "2001:db8:1::/64",
                "pools": [ { "pool": "2001:db8:1::-2001:db8:1::ffff" } ],
-               "client-class": "Client_enterprise"
+               "client-classes": [ "Client_enterprise" ]
            }
        ],
        ...
@@ -3147,7 +3147,7 @@ eRouter1.0 client class are allowed to use that pool.
                         "pool": "2001:db8:1::-2001:db8:1::ffff"
                     }
                 ],
-               "client-class": "VENDOR_CLASS_eRouter1.0"
+               "client-classes": [ "VENDOR_CLASS_eRouter1.0" ]
            }
        ],
        ...
@@ -5190,7 +5190,7 @@ Pool Selection with Client Class Reservations
 Client classes can be specified both in the Kea configuration file and/or
 via host reservations. The classes specified in the Kea configuration file are
 evaluated immediately after receiving the DHCP packet and therefore can be
-used to influence subnet selection using the ``client-class`` parameter
+used to influence subnet selection using the ``client-classes`` parameter
 specified in the subnet scope. The classes specified within the host
 reservations are fetched and assigned to the packet after the server has
 already selected a subnet for the client. This means that the client
@@ -5230,11 +5230,11 @@ within the subnet as follows:
                 "pools": [
                     {
                         "pool": "2001:db8:1::10-2001:db8:1::20",
-                        "client-class": "reserved_class"
+                        "client-classes": [ "reserved_class" ]
                     },
                     {
                         "pool": "2001:db8:1::30-2001:db8:1::40",
-                        "client-class": "unreserved_class"
+                        "client-classes": [ "unreserved_class" ]
                     }
                 ]
             }
@@ -5301,7 +5301,7 @@ following example:
                     "pools": [
                         {
                             "pool": "2001:db8:1::10-2001:db8:1::20",
-                            "client-class": "reserved_class"
+                            "client-classes": [ "reserved_class" ]
                         }
                     ]
                 },
@@ -5311,7 +5311,7 @@ following example:
                     "pools": [
                         {
                             "pool": "2001:db8:2::10-2001:db8:2::20",
-                            "client-class": "unreserved_class"
+                            "client-classes": [ "unreserved_class" ]
                         }
                     ]
                 }
@@ -5331,7 +5331,7 @@ In addition, the reservation for the client class must be specified at the
 global scope (global reservation) and ``reservations-global`` must be
 set to ``true``.
 
-In the example above, the ``client-class`` could also be specified at the
+In the example above, the ``client-classes`` could also be specified at the
 subnet level rather than the pool level, and would yield the same effect.
 
 .. _multiple-reservations-same-ip6:
@@ -5949,8 +5949,24 @@ If a subnet is associated with a class, only the clients belonging to
 this class can use this subnet. If there are no classes specified for a
 subnet, any client connected to a given shared network can use this
 subnet. A common mistake is to assume that the subnet that includes a client
-class is preferred over subnets without client classes. Consider the
-following example:
+class is preferred over subnets without client classes.
+
+The ``client-classes`` parameter may be specified at the shared network, subnet,
+and/or pool scopes. If specified for a shared network, clients must belong to at
+least one of the classes specified for that network to be considered for subnets
+within that network. If specified for a subnet, clients must belong to at least
+one of the classes specified for that subnet to be considered for any of that
+subnet's pools.  If sepcified for a pool, clients must belong to at least one
+of the classes specified for that pool to be given a lease from that pool.
+
+.. note:
+
+    As of Kea 2.7.5, ``client-class`` (a single class name) has been replaced
+    with ``client-classes`` (a list of one or more class names) and is now
+    deprecated. It will still be accepted as input for a time to allow users
+    to migrate but will eventually be unsupported.
+
+Consider the following example:
 
 .. code-block:: json
 
@@ -5977,7 +5993,7 @@ following example:
                        "id": 2,
                        "subnet": "2001:db8:3::/64",
                        "pools": [ { "pool": "2001:db8:3::20 - 2001:db8:3::ff" } ],
-                       "client-class": "b-devices"
+                       "client-classes": "b-devices"
                    }
                ]
            }
@@ -6027,13 +6043,13 @@ on option 1234 values.
                        "id": 1,
                        "subnet": "2001:db8:1::/64",
                        "pools": [ { "pool": "2001:db8:1::20 - 2001:db8:1::ff" } ],
-                       "client-class": "a-devices"
+                       "client-classes": [ "a-devices" ]
                    },
                    {
                        "id": 2,
                        "subnet": "2001:db8:3::/64",
                        "pools": [ { "pool": "2001:db8:3::20 - 2001:db8:3::ff" } ],
-                       "client-class": "b-devices"
+                       "client-classes": [ "b-devices" ]
                    }
                ]
            }
@@ -6542,7 +6558,7 @@ The following configuration can serve that situation:
                "pools": [
                    { "pool": "3000::2 - 3000::ffff" }
                ],
-               "client-class": "VENDOR_CLASS_docsis3.0",
+               "client-classes": [ "VENDOR_CLASS_docsis3.0" ],
                "relay": {
                    "ip-addresses": [ "3000::1" ]
                }
diff --git a/doc/sphinx/arm/hooks-bootp.rst b/doc/sphinx/arm/hooks-bootp.rst
index 7f8a749829..7e808fb8d0 100644
--- a/doc/sphinx/arm/hooks-bootp.rst
+++ b/doc/sphinx/arm/hooks-bootp.rst
@@ -64,12 +64,12 @@ to segregate BOOTP clients into separate pools. For example:
                {
                    // BOOTP clients will be handled here
                    "pool": "192.0.2.200 - 192.0.2.254",
-                   "client-class": "BOOTP"
+                   "client-classes":  [ "BOOTP" ]
                },
                {
                    // Regular DHCP clients will be handled here
                    "pool": "192.0.2.1 - 192.0.2.199",
-                   "client-class": "DHCP"
+                   "client-classes": [ "DHCP" ]
                }],
                ...
            },
diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst
index 1b479cdb6c..0e7878acbe 100644
--- a/doc/sphinx/arm/hooks-ha.rst
+++ b/doc/sphinx/arm/hooks-ha.rst
@@ -712,10 +712,10 @@ only difference that ``this-server-name`` should be set to "server2" and
            "subnet": "192.0.3.0/24",
            "pools": [{
                "pool": "192.0.3.100 - 192.0.3.150",
-               "client-class": "HA_server1"
+               "client-classes": [ "HA_server1 ]"
             }, {
                "pool": "192.0.3.200 - 192.0.3.250",
-               "client-class": "HA_server2"
+               "client-classes": [ "HA_server2" ]
             }],
 
             "option-data": [{
@@ -1022,16 +1022,16 @@ library configuration has been removed from this example.
            "subnet": "192.0.3.0/24",
            "pools": [{
                "pool": "192.0.3.100 - 192.0.3.125",
-               "client-class": "phones_server1"
+               "client-classes": [ "phones_server1" ]
            }, {
                "pool": "192.0.3.126 - 192.0.3.150",
-               "client-class": "laptops_server1"
+               "client-classes": [ "laptops_server1" ]
            }, {
                "pool": "192.0.3.200 - 192.0.3.225",
-               "client-class": "phones_server2"
+               "client-classes": [ "phones_server2" ]
            }, {
                "pool": "192.0.3.226 - 192.0.3.250",
-               "client-class": "laptops_server2"
+               "client-classes": [ "laptops_server2" ]
            }],
 
            "option-data": [{
@@ -1109,7 +1109,7 @@ The following is an example configuration of the primary server in a
            "subnet": "192.0.3.0/24",
            "pools": [{
                "pool": "192.0.3.100 - 192.0.3.250",
-               "client-class": "HA_server1"
+               "client-classes": [ "HA_server1" ]
            }],
 
            "option-data": [{