Kea Flexible Option Hooks Library

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 Kea Developer's Guide and in particular its section about hooks.

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:

"Dhcp4": {
    "hooks-libraries": [
        {   "library": "/usr/local/lib/libdhcp_flex_option.so",
            "parameters": {
                "options": [
                    {
                        "code": 100,
                        "add": "concat(relay4[2].hex, 'abc')",
                        "csv-format": false
                    }
                ]
            }
        },
        ...
    ]
}

To configure it for kea-dhcp6, the commands are simply as shown below:

"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
                    }
                ]
            }
        },
        ...
    ]
}

The sole parameter is a options list of options with:

• code - Specifies the option code.
• name - Specifies the option name, at least the option code or name must be given.
• 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.
• 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.
• 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:

• container-add - Specifies if the container option should be created when it does not exist (default behavior) in add and supersede actions.
• 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 sub-option entry of the container option configuration.

Internal operation

The first function called in load() located in the flex_option_callouts.cc. It checks if the necessary parameter is passed and decodes the option configurations. unload() free the configuration.

Kea engine checks if the library has functions that match known hook point names. This library has two such functions: pkt4_send and pkt6_send, all located in flex_option_callouts.cc.

kea-dhcp4 server calls pkt4_send (and kea-dhcp6 pkt6_send) with the query and response packets. For each configured option and sub-option the action is applied by the template 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.

Multi-Threading Compatibility

The libdhcp_flex_option hooks library is compatible with multi-threading.