Adding upstream version 2.5.7.upstream/2.5.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 196 insertions, 0 deletions

diff --git a/doc/sphinx/arm/hooks-flex-option.rst b/doc/sphinx/arm/hooks-flex-option.rst
new file mode 100644
index 0000000..ffac090
--- /dev/null
+++ b/doc/sphinx/arm/hooks-flex-option.rst
@@ -0,0 +1,196 @@
+.. ischooklib:: libdhcp_flex_option.so
+.. _hooks-flex-option:
+
+``libdhcp_flex_option.so``: Flexible Option Actions for Option Value Settings
+=============================================================================
+
+This library allows administrators to define an action to take, for a given
+option, based upon on the result of an expression. These actions are carried
+out during the final stages of constructing a query response packet, just
+before it is sent to the client. The three actions currently supported are
+``add``, ``supersede``, and ``remove``.
+
+.. note::
+
+    :ischooklib:`libdhcp_flex_option.so` is part of the open source code and is
+    available to every Kea user.
+
+The syntax used for the action expressions is the same syntax used
+for client classification and the Flexible Identifier hook library;
+see either :ref:`classification-using-expressions` or :ref:`hooks-flex-id`
+for a detailed description of the syntax.
+
+The ``add`` and ``supersede`` actions use an expression returning a
+string, and do nothing if the string is empty. The
+``remove`` application uses an expression returning ``true`` or ``false``,
+and does nothing on ``false``. When it is necessary to set an option to the
+empty value this mechanism does not work, but a client class can be
+used instead.
+
+The ``add`` action adds an option only when the option does not already
+exist and the expression does not evaluate to the empty string.
+The ``supersede`` action is similar, but it overwrites the option value
+if it already exists. The ``remove`` action removes the option from
+the response packet if it already exists and the expression evaluates to
+true.
+
+The option to which an action applies may be specified by either its
+numeric code or its name; either the code or the name must be
+specified. The option space is DHCPv4 or DHCPv6, depending
+on the server where the hook library is loaded.
+
+Similar to other hook libraries, :ischooklib:`libdhcp_flex_option.so` can be loaded
+by either the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
+process. It takes a mandatory ``options`` parameter with a list of
+per-option parameter maps, with ``code``, ``name``, ``add``, ``supersede``, and
+``remove`` actions. Action entries take a string value representing an
+expression.
+
+.. code-block:: json
+
+ {
+    "Dhcp4": {
+        "hooks-libraries": [
+            {
+                "library": "/usr/local/lib/libdhcp_flex_option.so",
+                "parameters": {
+                    "options": [
+                        {
+                            "code": 67,
+                            "add": "ifelse(option[host-name].exists,concat(option[host-name].text,'.boot'),'')"
+                        }
+                    ]
+                }
+            }
+        ]
+    }
+ }
+
+If (and only if) the **query** includes a ``host-name`` option (code 12), a
+``boot-file-name`` option (code 67) is added to the response with the host name
+followed by ``.boot`` for content.
+
+A commonly discussed use case is modifying the DHCPv4 subnet mask option
+(code 1). The following example demonstrates that capability. All ingress
+packets identified by the gateway address 192.168.0.1 are met with a /32 subnet
+mask in the response.
+
+.. code-block:: json
+
+    {
+        "Dhcp4": {
+            "hooks-libraries": [
+                {
+                    "library": "/usr/local/lib/libdhcp_flex_option.so",
+                    "parameters": {
+                        "options": [
+                            {
+                                "code": 1,
+                                "supersede": "ifelse(pkt4.giaddr==192.168.0.1, '255.255.255.255', '')"
+                            }
+                        ]
+                    }
+                }
+            ]
+        }
+    }
+
+The flexible option library supports both DHCPv4 and DHCPv6.
+
+Since Kea 1.9.0, the ``add`` and ``supersede`` actions take an optional
+```csv-format``` boolean parameter. If not specified or set to ``false``, the
+option data is set using the raw value of the evaluated expression. When it is
+configured to ``true``, this value is parsed using the option definition from
+the option data specified in the configuration file. This eases option setting
+for options using complex record formats or fully qualified domain names.
+
+For instance, if the expression evaluation returns "example.com" and
+the option is defined with the ``fqdn`` type, the domain name will be
+encoded into DNS binary format.
+
+Since Kea 2.1.4, the ``client-class`` parameter specifies a class guard.
+It takes a client class name. If not empty, the client's packet needs to
+belong to specified class for this entry to be used.
+
+Since Kea 2.1.4, it is allowed to have multiple entries for the same option,
+but each entry must have exactly one action. If the option is not defined
+in the ``dhcp4`` for DHCPv4 or ``dhcp6`` for DHCPv6 you can specify the
+space where to find the option definition using its name with the new
+``space`` parameter.
+
+Since Kea 2.1.4, sub-options are supported with a new entry ``sub-options``
+which replaces the action in the configuration of the container option,
+i.e. the option where sub-options are located.
+
+The ``sub-options`` entry takes a list of sub-option configuration similar
+to the option one with:
+
+- ``code`` - specifies the sub-option code, either the ``code`` or ``name``
+  must be specified. When both are given they must match or the configuration
+  is rejected at load time.
+
+- ``name`` - specifies the sub-option name, either the ``code`` or ``name``
+  must be specified. When both are given they must match or the configuration
+  is rejected at load time.
+
+- ``space`` - specifies the space where the sub-option can be defined. This
+  parameter is optional because it can be found in the container option
+  definition. The configuration is rejected if no valid space name is
+  available at load time. Note that vendor spaces are supported for the
+  DHCPv4 ``vivso-suboptions`` and for the DHCPv6 ``vendor-opts``, both
+  pre-defined (e.g. DoCSIS vendor id 4491) or custom.
+
+- ``add`` - (action) adds a sub-option only if it does not already exist
+  and the expression does not evaluate to the empty string.
+
+- ``supersede`` - (action) adds or overwrites a sub-option if the expression
+  does not evaluate to the empty string.
+
+- ``remove`` - (action) removes a sub-option if it already exists and the
+  expression evaluates to true.
+
+- ``container-add`` - boolean value which specifies if the container option
+  should be created if it does not exit in the ``add`` and ``supersede``
+  action. When not specified, it defaults to true.
+
+- ``container-remove`` - boolean value which specifies if the container option
+  should be deleted if it remains empty after the removal of a sub-option by
+  the ``remove`` action. When not specified, it defaults to true.
+
+- ``csv-format`` - boolean value which specifies if the raw value of the
+  evaluated expression is used (false, default) or parsed using the sub-option
+  definition (true).
+
+- ``client-class`` - specifies if the sub-option entry must be skipped when
+  the **query** does not belong to the specified client class. Note the similar
+  parameter in the container option entry applies to the whole ``sub-options``
+  list.
+
+For instance this configuration adds a string sub-option in the DHCPv4
+``vendor-encapsulated-options`` (code 43) option. Note this option
+in last resort encapsulates the ``vendor-encapsulated-options`` space.
+
+.. code-block:: json
+
+ {
+    "Dhcp4": {
+        "hooks-libraries": [
+            {
+                "library": "/usr/local/lib/libdhcp_flex_option.so",
+                "parameters": {
+                    "options": [
+                        {
+                            "code": 43,
+                            "sub-options": [
+                                {
+                                   "code": 1,
+                                   "add": "'foobar'"
+                                }
+                            ]
+                        }
+                    ]
+                }
+            }
+        ]
+    }
+ }