1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
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.
*/
|
