diff options
Diffstat (limited to 'src/hooks/dhcp/flex_option/flex_option.dox')
| -rw-r--r-- | src/hooks/dhcp/flex_option/flex_option.dox | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/src/hooks/dhcp/flex_option/flex_option.dox b/src/hooks/dhcp/flex_option/flex_option.dox new file mode 100644 index 0000000..9fc84d6 --- /dev/null +++ b/src/hooks/dhcp/flex_option/flex_option.dox @@ -0,0 +1,142 @@ +// Copyright (C) 2019-2022 Internet Systems Consortium, Inc. ("ISC") +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +/** + +@page libdhcp_flex_option Kea Flexible Option Hooks Library + +@section libdhcp_flex_optionIntro Introduction + +Welcome to Kea Flexible Option Hooks Library. This documentation is +addressed to developers who are interested in the internal operation +of the Flexible Option library. This file provides information needed +to understand and perhaps extend this library. + +This documentation is stand-alone: you should have read and understood +the <a href="https://reports.kea.isc.org/dev_guide/">Kea +Developer's Guide</a> and in particular its section about hooks. + +@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. + +## Configuring the DHCP Modules + +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: + +@code +"Dhcp4": { + "hooks-libraries": [ + { "library": "/usr/local/lib/libdhcp_flex_option.so", + "parameters": { + "options": [ + { + "code": 100, + "add": "concat(relay4[2].hex, 'abc')", + "csv-format": false + } + ] + } + }, + ... + ] +} +@endcode + +To configure it for kea-dhcp6, the commands are simply as shown below: + +@code +"Dhcp6": { + "hooks-libraries": [ + { "library": "/usr/local/lib/libdhcp_flex_option.so", + "parameters": { + "options": [ + { + "code": 100, + "add": "concat(relay6[0].option[37].hex, 'abc')", + "csv-format": false + } + ] + } + }, + ... + ] +} +@endcode + +The sole parameter is a options list of options with: + - @b code - Specifies the option code. + - @b name - Specifies 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. + - @b 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. + - @b 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. + - @b csv-format - Specifies the option format used for input. If not + specified, it will default to false (raw data). When enabled, the option + data will be parsed using csv format and packed according to the option + definition. + - @b client-class - Specifies the guard i.e. the client class the query + must belong to. + +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 to set the +empty value to the option in a option-data clause. + +The sub-option support is similar to the option one with in addition: + - @b container-add - Specifies if the container option should be created + when it does not exist (default behavior) in add and supersede actions. + - @b container-remove - Specifies if the container option should be + removed when the sub-option removal left it empty (default behavior) + in remove action. +Sub-option configuration is a list in a @b sub-option entry of the container +option configuration. + +## 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 and sub-option +the action is applied by the template @c 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. + +In case any other library sets the SKIP flag before pkt4_send or pkt6_send, an +exception with the message "the packet pack already handled" will be thrown, to +indicate that the action can not be properly performed. +To fix this, all other libraries which might set the SKIP flag must appear +in the server configuration after this library. + +@section libdhcp_flex_optionMTCompatibility Multi-Threading Compatibility + +The libdhcp_flex_option hooks library is compatible with multi-threading. + +*/ |