$ ls -l /usr/local/lib/kea/hooks/*.so
/usr/local/lib/kea/hooks/libdhcp_class_cmds.so
/usr/local/lib/kea/hooks/libdhcp_flex_id.so
+ /usr/local/lib/kea/hooks/libdhcp_flex_option.so
/usr/local/lib/kea/hooks/libdhcp_host_cmds.so
/usr/local/lib/kea/hooks/libdhcp_lease_cmds.so
/usr/local/lib/kea/hooks/libdhcp_legal_log.so
| | |packet is evaluated against that expression and its value is|
| | |then searched in the reservations database. |
+-----------------+---------------+------------------------------------------------------------+
+ | Flexible | Kea sources |This library provides hooks that compute option values |
+ | Option | (since 1.7.1) |instead of static configured values. An expression is |
+ | | |evaluated on the query packet. Defined add, supersede and |
+ | | |remove actions are applied on the response packet before |
+ | | |it is sent using the evaluation result. |
+ +-----------------+---------------+------------------------------------------------------------+
| Host Commands | Support |Kea provides a way to store host reservations in a |
| | customers |database. In many larger deployments it is useful to be able|
| | (since 1.2) |to manage that information while the server is running. This|
}
}
+.. _flex-option:
+
+flex_option Flexible Option for Option value settings
+=====================================================
+
+This sectiom describes a hook application dedicated to generate flexible
+option values in response packets. The Kea software provides a way to
+configure option values of response packets based on global configuration,
+client classes, shared networks, subnets, pools and host reservations but
+in all cases values are static. However, there are sometimes scenarios
+where the value should be computed from elements from the query packet.
+These scenarios are addressed by the Flexible Option hook application.
+
+This hook is available since Kea 1.7.1.
+
+.. note::
+
+ This library may only be loaded by the ``kea-dhp4`` or ``kea-dhp6``
+ process.
+
+The library allows the definition of an action per option using an
+expression on the query packer as for the Flex Indentifier hook library
+(See :ref:`flex-id`) or for client classification (See
+:ref:`classification-using-expressions` for a detailed description of
+the syntax available.) The ``add`` and ``supersede`` actions use an
+expression returning a string, doing nothing when it evaluates to
+the empty string. The ``remove`` application uses an expression returning
+true or false, doing 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 does the same 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 where an action applies is specified by its code point or
+by its name. At least the code or the name must be specified. The option
+space is the DHCPv4 or DHCPv6 spaces depending of the server where the
+hook library is loaded. Other spaces as vendor spaces could be supported
+in a further version.
+
+The library can be loaded in a similar way as other hook libraries. It takes
+a mandatory ``options`` parameter holding a list of per option parameter
+maps with code, name, add, supersede and remove actions. Action entries
+take a string value representing an expression.
+
+::
+
+ "Dhcp6": {
+ "hook_libraries": [
+ { "library": "/usr/local/lib/libdhcp_flex_option.so",
+ "parameters": {
+ "options": [
+ {
+ "code": 100,
+ "add": "concat(relay6[0].option[37].hex, 'abc')"
+ }
+ ]
+ }
+ },
+ ...
+ ]
+ }
+
+The flexible option library supports both DHCPv4 and DHCPv6.
+
.. _host-cmds:
host_cmds: Host Commands
the <a href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea
Developer's Guide</a> and in particular its section about hooks.
-@section flex_option Flexible Option Overview
+@section libdhcp_flex_optionUser Now To Use libdhcp_flex_option
+## Introduction
+libdhcp_flex_option is a hooks library which customize the option value
+setting mechanism by introducing values from expression evaluation.
+Instead of relying on static configured values, it allows user to define
+expressions and use values of that expressions computed for options
+added to response packets.
-Flexible Option (or flex_option) is a Hook library that can be loaded by
-either kea-dhcp4 and kea-dhcp6 servers to extend them with additional
-option value setting mechanisms.
+## Configuring the DHCP Modules
-@section flex_optionCode Flexible Option Code Overview
+It must be configured as a hook library for the desired DHCP server
+modules. Note that the flex_option library is installed alongside the
+Kea libraries in "<install-dir>/lib" where <install-dir> is determined
+by the --prefix option of the configure script. It defaults to
+"/usr/local". Assuming the default value then, configuring kea-dhcp4
+to load the flex_option library could be done with the following Kea4
+configuration:
-Todo
+@code
+"Dhcp4": {
+ "hook_libraries": [
+ { "library": "/usr/local/lib/libdhcp_flex_option.so",
+ "parameters": {
+ "options": [
+ {
+ "code": 100,
+ "add": "concat(relay4[2].hex, 'abc')"
+ }
+ ]
+ }
+ },
+ ...
+ ]
+}
+@endcode
+
+To configure it for kea-dhcp6, the commands are simply as shown below:
+
+@code
+"Dhcp6": {
+ "hook_libraries": [
+ { "library": "/usr/local/lib/libdhcp_flex_option.so",
+ "parameters": {
+ "options": [
+ {
+ "code": 100,
+ "add": "concat(relay6[0].option[37].hex, 'abc')"
+ }
+ ]
+ }
+ },
+ ...
+ ]
+}
+@endcode
+
+The parameter is rge options list of option configuration maps with:
+ - @b code - Specifies the option code.
+ - @b name - Speficies the option name, at least the option code or name
+ must be given.
+ - @b add - Specifies the add action: it takes a string expression on
+ the query packet. If the option does not already exist in the response
+ packet and the expression evaluates to a not empty value, the option
+ with the value is added to the response.
+ - @supersede - Specifies the supersede action: it takes a string expression
+ on the query packet. If the expression evaluates to a not empty value,
+ the option with the value is added to the response. If it already exists
+ it is overwritten.
+ - @remove - Specifies the remove action: it takes a boolean expression
+ on the query packet. If the expression evaluates to true and the option
+ already exists in the response packet, the option is removed from the
+ response. Only one action can be specified.
+
+Note for the rare options which can be empty this mechanism does not work.
+The proposed solution in this case is to use a client class.
+
+## Internal operation
+
+The first function called in @ref load() located in the
+flex_option_callouts.cc. It checks if the necessary parameter is passed and
+decodes the option configurations. @ref unload() free the configuration.
+
+Kea engine checks if the library has functions that match known hook point
+names. This library has two such functions: @ref pkt4_send and @ref pkt6_send,
+all located in flex_option_callouts.cc.
+
+kea-dhcp4 server calls @ref pkt4_send (and kea-dhcp6 @ref pkt6_send) with
+the query and response packets. For each configured option the action is
+applied by the template @ref process located in flex_option.h. When
+required the expression is evaluated on the query packet and the result
+is used by the action for instance to add a new option.
*/
projects / thirdparty / kea.git / commitdiff
