[#3587] Updated doc, messages, parsers, and UTs

/doc/sphinx/arm/classify.rst
/doc/sphinx/arm/dhcp4-srv.rst
/doc/sphinx/arm/dhcp6-srv.rst
/doc/sphinx/arm/hooks-class-cmds.rst
/doc/sphinx/arm/hooks-limits.rst
/src/bin/dhcp4/dhcp4_lexer.ll
/src/bin/dhcp4/dhcp4_messages.mes
/src/bin/dhcp4/dhcp4_srv.cc
/src/bin/dhcp4/tests/classify_unittest.cc
/src/bin/dhcp4/tests/config_parser_unittest.cc
/src/bin/dhcp6/dhcp6_messages.mes b/src/bin/dhcp6/dhcp6_messages.mes
/src/bin/dhcp6/dhcp6_srv.cc
/src/bin/dhcp6/tests/classify_unittest.cc
/src/bin/dhcp6/tests/config_parser_unittest.cc
/src/lib/dhcpsrv/tests/client_class_def_parser_unittest.cc
/src/share/api/class-get.json

Author: tmarkwalder

doc/sphinx/arm/classify.rst

@@ -736,11 +736,14 @@ A client class definition can contain the following properties:
    assigned to members of this class. In the case of a template class, these
    options are assigned to the generated spawned class.
  - The ``option-def`` list is not mandatory and is used to define custom options.
- - The ``only-if-required`` flag is not mandatory; when its value is set to
+ - The ``only-if-required`` has been replaced with ``only-in-additional-list`` and
+   is now deprecated. It will still be accepted as input for a time to allow users
+   to migrate but will eventually be unsupported.
+ - The ``only-in-additional-list`` flag is not mandatory; when its value is set to
    ``false`` (the default), membership is determined during classification and is
    available for subnet selection, for instance. When the value is set to
-   ``true``, membership is evaluated only when required and is usable only for
-   option configuration.
+   ``true``, membership is evaluated only if the class appears in an ``evaluate-
+   additional-classes`` list and is usable only for option configuration.
  - The ``user-context`` is not mandatory and represents a map with user-defined data
    and possibly configuration options for hook libraries.
  - The ``next-server`` parameter is not mandatory and configures the ``siaddr`` field in
@@ -907,18 +910,19 @@ expression for example purposes.
 Usually the ``test`` and ``template-test`` expressions are evaluated before
 subnet selection, but in some cases it is useful to evaluate it later when the
 subnet, shared network, or pools are known but output-option processing has not
-yet been done. For this purpose, the ``only-if-required`` flag, which is
+yet been done. For this purpose, the ``only-in-additional-list`` flag, which is
 ``false`` by default, allows the evaluation of the ``test`` expression or the
-``template-test`` expression only when it is required, i.e. in a
-``require-client-classes`` list of the selected pool, subnet, or shared network.
+``template-test`` expression only when it is required by the class's presence
+in the ``evaluate-additional-classes`` list of the selected pool, subnet, or
+shared network.
 
-The ``require-client-classes`` list, which is valid for pool, subnet,
+The ``evaluate-additional-classes`` list, which is valid for pool, subnet,
 and shared-network scope, specifies the classes which are evaluated in
 the second pass before output-option processing. The list is built in
-same precedence order of the option data, i.e. an option data item in
-a subnet takes precedence over one in a shared network, and also a
-required class in a subnet is added before one in a shared
-network. The mechanism is related to the ``only-if-required`` flag but
+same precedence order as the option data, i.e. an option data item in
+a subnet takes precedence over one in a shared network. An
+additional class in a subnet is added before one in a shared
+network. The mechanism is related to the ``only-in-additional-list`` flag but
 it is not mandatory that the flag be set to ``true``.
 
 .. note ::
@@ -1200,9 +1204,9 @@ value is obtained is determined as explained in the previous paragraphs.
 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 
+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.
 
@@ -1252,24 +1256,24 @@ being added to the response which occurs after lease assignment just
 before the response is to be sent to the client.
 
 
-When ``never-send`` for an option is true at any scope, all 
+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 
+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 
+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 
+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":  
+the option to members of class "melon":
 
 ::
 
@@ -1289,16 +1293,16 @@ the option to members of class "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".  
+"foo".
 
 .. note::
 
-    Though examples above are for DHCPv4, class-tagging syntax and 
-    behavior is the same for DHPCv6. 
+    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

@@ -3421,26 +3421,26 @@ DNS servers set to 192.0.2.1 and 192.0.2.2.
        ...
    }
 
-.. _dhcp4-required-class:
+.. _dhcp4-additional-class:
 
-Required Classification
-~~~~~~~~~~~~~~~~~~~~~~~
+Additional Classification
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In some cases it is useful to limit the scope of a class to a pool,
 subnet, or shared network. There are two parameters which are used
 to limit the scope of the class by instructing the server to evaluate test
 expressions when required.
 
-The first one is the per-class ``only-if-required`` flag, which is ``false``
-by default. When it is set to ``true``, the test expression of the class
-is not evaluated at the reception of the incoming packet but later, and
-only if the class evaluation is required.
-
-The second is ``require-client-classes``, which takes a list of class
+The ``evaluate-additional-classes``, which takes a list of class
 names and is valid in pool, subnet, and shared network scope. Classes in
-these lists are marked as required and evaluated after selection of this
+these lists are marked as additional and evaluated after selection of this
 specific pool/subnet/shared network and before output-option processing.
 
+The second one is the per-class ``only-in-additional-list`` flag, which is
+``false`` by default. When it is set to ``true``, the test expression of
+the class is not evaluated at the reception of the incoming packet but later,
+and only if the class is present in an ``evaluate-additional-classes`` list.
+
 In this example, a class is assigned to the incoming packet when the
 specified subnet is used:
 
@@ -3451,38 +3451,45 @@ specified subnet is used:
           {
               "name": "Client_foo",
               "test": "member('ALL')",
-              "only-if-required": true
+              "only-in-additional-list": true
           },
           ...
        ],
        "subnet4": [
            {
                "subnet": "192.0.2.0/24",
                "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
-               "require-client-classes": [ "Client_foo" ],
+               "evaluate-additional-classes": [ "Client_foo" ],
                ...
            },
            ...
        ],
        ...
    }
 
-Required evaluation can be used to express complex dependencies like
+Additional evaluation can be used to express complex dependencies like
 subnet membership. It can also be used to reverse the
 precedence; if ``option-data`` is set in a subnet, it takes precedence
 over ``option-data`` in a class. If ``option-data`` is moved to a
 required class and required in the subnet, a class evaluated earlier
 may take precedence.
 
-Required evaluation is also available at the shared network and pool levels.
-The order in which required classes are considered is: pool, subnet,
+Additional evaluation is also available at the shared network and pool levels.
+The order in which additional classes are considered is: pool, subnet,
 and shared network, i.e. in the same order from the way in which
 ``option-data`` is processed.
 
-Since Kea version 2.7.4 required client classes configured without
+Since Kea version 2.7.4 additional client classes configured without
 a test expression are unconditionally added, i.e. they are considered
 to always be evaluated to ``true``.
 
+.. note::
+
+   As of Kea version 2.7.4, ``only-if-required`` and ``require-client-classes``
+   have been renamed to ``only-in-additional-list`` and ``evaluate-additional-classes``
+   respectivley.  The original names will still be accepted as input to allow
+   users to migrate but will eventually be unsupported.
+
 .. note::
 
    Vendor-Identifying Vendor Options are a special case: for all other
@@ -5366,34 +5373,34 @@ For example:
             {
                 "name": "dependent-class",
                 "test": "member('KNOWN')",
-                "only-if-required": true
+                "only-in-additional-list": true
             }
         ]
     }
 
-The ``only-if-required`` parameter is needed here to force evaluation
+The ``only-in-additional-list`` parameter is needed here to force evaluation
 of the class after the lease has been allocated, and thus the reserved
 class has been also assigned.
 
 .. note::
 
    The classes specified in non-global host reservations
    are assigned to the processed packet after all classes with the
-   ``only-if-required`` parameter set to ``false`` have been evaluated.
+   ``only-in-additional-list`` parameter set to ``false`` have been evaluated.
    This means that these classes must not depend on the
    statically assigned classes from the host reservations. If
-   such a dependency is needed, the ``only-if-required`` parameter must
+   such a dependency is needed, the ``only-in-additional-list`` parameter must
    be set to ``true`` for the dependent classes. Such classes are
    evaluated after the static classes have been assigned to the packet.
    This, however, imposes additional configuration overhead, because
-   all classes marked as ``only-if-required`` must be listed in the
-   ``require-client-classes`` list for every subnet where they are used.
+   all classes marked as ``only-in-additional-list`` must be listed in the
+   ``evaluate-additional-classes`` list for every subnet where they are used.
 
 .. note::
 
    Client classes specified within the Kea configuration file may
    depend on the classes specified within the global host reservations.
-   In such a case the ``only-if-required`` parameter is not needed.
+   In such a case the ``only-in-additional-list`` parameter is not needed.
    Refer to :ref:`pool-selection-with-class-reservations4` and
    :ref:`subnet-selection-with-class-reservations4`
    for specific use cases.
@@ -6806,10 +6813,10 @@ the ``dhcp-server-identifier`` option. This option configuration is only
 supported at the subnet, shared network, client class, and global levels. It
 must not be specified at the host-reservation level.
 When configuring the ``dhcp-server-identifier`` option at client-class level, the
-class must not set the ``only-if-required`` flag, because this class would not
+class must not set the ``only-in-additional-list`` flag, because this class would not
 be evaluated before the server determines if the received DHCP message should
 be accepted for processing. Such classes are evaluated after subnet selection.
-See :ref:`dhcp4-required-class` for details.
+See :ref:`dhcp4-additional-class` for details.
 
 The following example demonstrates how to override the server identifier
 for a subnet:

doc/sphinx/arm/dhcp6-srv.rst

@@ -3153,26 +3153,26 @@ eRouter1.0 client class are allowed to use that pool.
        ...
    }
 
-.. _dhcp6-required-class:
+.. _dhcp6-additional-class:
 
-Required Classification
-~~~~~~~~~~~~~~~~~~~~~~~
+Additional Classification
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In some cases it is useful to limit the scope of a class to a pool,
 subnet, or shared network. There are two parameters which are used
 to limit the scope of the class by instructing the server to evaluate test
 expressions when required.
 
-The first one is the per-class ``only-if-required`` flag, which is ``false``
-by default. When it is set to ``true``, the test expression of the class
-is not evaluated at the reception of the incoming packet but later, and
-only if the class evaluation is required.
-
-The second is ``require-client-classes``, which takes a list of class
+The ``evaluate-additional-classes``, which takes a list of class
 names and is valid in pool, subnet, and shared network scope. Classes in
-these lists are marked as required and evaluated after selection of this
+these lists are marked as additional and evaluated after selection of this
 specific pool/subnet/shared network and before output-option processing.
 
+The second one is the per-class ``only-in-additional-list`` flag, which is
+``false`` by default. When it is set to ``true``, the test expression of
+the class is not evaluated at the reception of the incoming packet but later,
+and only if the class is present in an ``evaluate-additional-classes`` list.
+
 In this example, a class is assigned to the incoming packet when the
 specified subnet is used:
 
@@ -3183,7 +3183,7 @@ specified subnet is used:
           {
               "name": "Client_foo",
               "test": "member('ALL')",
-              "only-if-required": true
+              "only-in-additional-list": true
           },
           ...
        ],
@@ -3195,30 +3195,37 @@ specified subnet is used:
                         "pool": "2001:db8:1::-2001:db8:1::ffff"
                     }
                ],
-               "require-client-classes": [ "Client_foo" ],
+               "evaluate-additional-classes": [ "Client_foo" ],
                ...
            },
            ...
        ],
        ...
    }
 
-Required evaluation can be used to express complex dependencies like
+Additional evaluation can be used to express complex dependencies like
 subnet membership. It can also be used to reverse the
 precedence; if ``option-data`` is set in a subnet, it takes precedence
 over ``option-data`` in a class. If ``option-data`` is moved to a
 required class and required in the subnet, a class evaluated earlier
 may take precedence.
 
-Required evaluation is also available at shared network and pool/pd-pool
-levels. The order in which required classes are considered is:
+Additional evaluation is also available at shared network and pool/pd-pool
+levels. The order in which additional classes are considered is:
 (pd-)pool, subnet, and shared network, i.e. in the same order from the
 way in which ``option-data`` is processed.
 
-Since Kea version 2.7.4 required client classes configured without
+Since Kea version 2.7.4 additional classes configured without
 a test expression are unconditionally added, i.e. they are considered
 to always be evaluated to ``true``.
 
+.. note::
+
+   As of Kea version 2.7.4, ``only-if-required`` and ``require-client-classes``
+   have been renamed to ``only-in-additional-list`` and ``evaluate-additional-classes``
+   respectivley.  The original names will still be accepted as input to allow
+   users to migrate but will eventually be unsupported.
+
 .. _dhcp6-ddns-config:
 
 DDNS for DHCPv6
@@ -4656,34 +4663,34 @@ For example:
             {
                 "name": "dependent-class",
                 "test": "member('KNOWN')",
-                "only-if-required": true
+                "only-in-additional-list": true
             }
         ]
     }
 
-The ``only-if-required`` parameter is needed here to force
+The ``only-in-additional-list`` parameter is needed here to force
 evaluation of the class after the lease has been allocated and thus the
 reserved class has been also assigned.
 
 .. note::
 
    The classes specified in non-global host reservations
    are assigned to the processed packet after all classes with the
-   ``only-if-required`` parameter set to ``false`` have been evaluated.
+   ``only-in-additional-list` parameter set to ``false`` have been evaluated.
    This means that these classes must not depend on the
    statically assigned classes from the host reservations. If
-   such a dependency is needed, the ``only-if-required`` must
+   such a dependency is needed, the ``only-in-addtional-list`` must
    be set to ``true`` for the dependent classes. Such classes are
    evaluated after the static classes have been assigned to the packet.
    This, however, imposes additional configuration overhead, because
-   all classes marked as ``only-if-required`` must be listed in the
-   ``require-client-classes`` list for every subnet where they are used.
+   all classes marked as ``only-in-addtional-list`` must be listed in the
+   ``evaluate-additional-classes`` list for every subnet where they are used.
 
 .. note::
 
    Client classes specified within the Kea configuration file may
    depend on the classes specified within the global host reservations.
-   In such a case the ``only-if-required`` parameter is not needed.
+   In such a case the ``only-in-additional-list`` parameter is not needed.
    Refer to the :ref:`pool-selection-with-class-reservations6` and
    :ref:`subnet-selection-with-class-reservations6`
    for specific use cases.