diff --git a/doc/examples/kea4/all-keys.json b/doc/examples/kea4/all-keys.json index a7a64dd153..4102bcdcea 100644 --- a/doc/examples/kea4/all-keys.json +++ b/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, diff --git a/doc/examples/kea6/all-keys.json b/doc/examples/kea6/all-keys.json index 0e8f83cdcb..a3d19a3c7c 100644 --- a/doc/examples/kea6/all-keys.json +++ b/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, diff --git a/doc/sphinx/arm/classify.rst b/doc/sphinx/arm/classify.rst index 3d60f63473..d7aaeac830 100644 --- a/doc/sphinx/arm/classify.rst +++ b/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 ================= diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index b0a30cceca..7e5eea68f9 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/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 diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 1f03f70a16..0f2ea7bee7 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/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