[#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

diff --git a/ChangeLog b/ChangeLog
index b6e24b1bed900ed500bbce462b645d0f20b0244e..3b362cf1ea08e8347fa337330b5363318f40ffac 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2306.  [func]          tmark
+       The parameter "client-class" (a single class name) in 
+       shared networks, subnets, and pools has been replaced with
+       "client-classes" (a list of one or more class names).
+       This applies to both kea-dhcp4 and kea-dhcp6.
+       (Gitlab #3592)
+
 2305.  [func]          fdupont
        Added a new "http-headers" parameter to the CA and
        HTTP control socket configuration sections which can
@@ -18,7 +25,7 @@
        generating DDNS update requests when leases are
        being reused due to lease caching.
        (Gitlab #3257)
-
+       
 Kea 2.7.4 (development) released on October 30, 2024
 
 2302.  [func]          tmark

diff --git a/doc/sphinx/arm/classify.rst b/doc/sphinx/arm/classify.rst
index d6724ca9c4485f2c28459ee05b19e8e60e32b8f7..d47c1abf697ddfa54ab7089615a89a6d9c25a54f 100644 (file)
--- 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 899860c6253d5a59fa1b461937b2e6be132dd602..6a70511adf1fdf8804d7ac08b18975fd49e0c73d 100644 (file)
--- 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 a1e0e8cf453a9cc04253c0c8629ab2dbb35cbaf3..dadfe18435302baae359424ac08be57b9363217b 100644 (file)
--- 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 7f8a749829960aeced6e21306fde49015c1e3a09..7e808fb8d029d0f659bdf64e01cd36de893a211d 100644 (file)
--- 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 1b479cdb6cedf06f7e5291e6bef64706f5719f5f..0e7878acbe59061462e2390768a144501078d652 100644 (file)
--- 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": [{