Commit a5682fe5 authored by Francis Dupont's avatar Francis Dupont

[219-allow-an-option-value-to-be-set-from-an-expression] Added docs

parent b391eeba
...@@ -156,6 +156,7 @@ of the libraries can be verified with this command: ...@@ -156,6 +156,7 @@ of the libraries can be verified with this command:
$ ls -l /usr/local/lib/kea/hooks/*.so $ ls -l /usr/local/lib/kea/hooks/*.so
/usr/local/lib/kea/hooks/libdhcp_class_cmds.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_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_host_cmds.so
/usr/local/lib/kea/hooks/libdhcp_lease_cmds.so /usr/local/lib/kea/hooks/libdhcp_lease_cmds.so
/usr/local/lib/kea/hooks/libdhcp_legal_log.so /usr/local/lib/kea/hooks/libdhcp_legal_log.so
...@@ -329,6 +330,12 @@ loaded by the correct process per the table below. ...@@ -329,6 +330,12 @@ loaded by the correct process per the table below.
| | |packet is evaluated against that expression and its value is| | | |packet is evaluated against that expression and its value is|
| | |then searched in the reservations database. | | | |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 | | 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| | | 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| | | (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: ...@@ -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_cmds: Host Commands host_cmds: Host Commands
......
...@@ -19,14 +19,96 @@ This documentation is stand-alone: you should have read and understood ...@@ -19,14 +19,96 @@ This documentation is stand-alone: you should have read and understood
the <a href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea the <a href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea
Developer's Guide</a> and in particular its section about hooks. 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 ## Configuring the DHCP Modules
either kea-dhcp4 and kea-dhcp6 servers to extend them with additional
option value setting mechanisms.
@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.
*/ */
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment