From: Francis Dupont Date: Wed, 2 Oct 2019 19:57:31 +0000 (+0200) Subject: [219-allow-an-option-value-to-be-set-from-an-expression] Added docs X-Git-Tag: Kea-1.7.1~39 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a5682fe596d1def010f8ddce30df89df3180ebbb;p=thirdparty%2Fkea.git [219-allow-an-option-value-to-be-set-from-an-expression] Added docs --- diff --git a/doc/sphinx/arm/hooks.rst b/doc/sphinx/arm/hooks.rst index e91673b160..23487b3c89 100644 --- a/doc/sphinx/arm/hooks.rst +++ b/doc/sphinx/arm/hooks.rst @@ -156,6 +156,7 @@ of the libraries can be verified with this command: $ 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 @@ -329,6 +330,12 @@ loaded by the correct process per the table below. | | |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| @@ -1158,6 +1165,75 @@ In the DHCPv6 case, the corresponding query will look similar to 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 diff --git a/src/hooks/dhcp/flex_option/flex_option.dox b/src/hooks/dhcp/flex_option/flex_option.dox index 22691c56d4..7f444ca1f2 100644 --- a/src/hooks/dhcp/flex_option/flex_option.dox +++ b/src/hooks/dhcp/flex_option/flex_option.dox @@ -19,14 +19,96 @@ This documentation is stand-alone: you should have read and understood the Kea Developer's Guide 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 "/lib" where 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. */