]>

Although Kea offers a lot of flexibility, there may be cases where its behavior needs customisation. To accommodate this possibility, Kea includes the idea of "Hooks". This feature lets Kea load one or more dynamically-linked libraries (known as "hooks libraries") and, at various points in its processing ("hook points"), call functions in them. Those functions perform whatever custom processing is required. Hooks libraries are attached to individual Kea processes, not to Kea as a whole. This means (for example) that it is possible to associate one set of libraries with the DHCP4 server and a different set to the DHCP6 server. Another point to note is that it is possible for a process to load multiple libraries. When processing reaches a hook point, Kea calls the hooks library functions attached to it. If multiple libraries have attached a function to a given hook point, Kea calls all of them, in the order in which the libraries are specified in the configuration file. The order may be important: consult the documentation of the libraries to see if this is the case. The next section describes how to configure hooks libraries. If you are interested in writing your own hooks library, information can be found in the Kea Developer's Guide.

The hooks libraries for a given process are configured using the hooks-libraries keyword in the configuration for that process. (Note that the word "hooks" is plural). The value of the keyword is an array of map structures, each structure corresponding to a hooks library. For example, to set up two hooks libraries for the DHCPv4 server, the configuration would be: "Dhcp4": { : "hooks-libraries": [ { "library": "/opt/charging.so" }, { "library": "/opt/local/notification.so", "parameters": { "mail": "spam@example.com", "floor": 13, "debug": false, "users": [ "alice", "bob", "charlie" ], "languages": { "french": "bonjour", "klingon": "yl'el" } } } ] : } This is a change to the syntax used in Kea 0.9.2 and earlier, where hooks-libraries was a list of strings, each string being the name of a library. The change was made in Kea 1.0 to facilitate the specification of library-specific parameters, a capability available in Kea 1.1.0 onwards. The library reloading behavior has changed in Kea 1.1. Libraries are reloaded, even if their list hasn't changed. Kea does that, because the parameters specified for the library (or the files those parameters point to) may have changed. Libraries may have additional parameters. Those are not mandatory in the sense that there may be libraries that don't require them. However, for specific library there is often specific requirement for specify certain set of parameters. Please consult the documentation for your library for details. In the example above, the first library has no parameters. The second library has five parameters, specifying mail (string parameter), floor (integer parameter), debug (boolean parameter) and even lists (list of strings) and maps (containing strings). Nested parameters could be used if the library supports it. This topic is explained in detail in the Hooks Developer's Guide in the "Configuring Hooks Libraries" section. Notes: The full path to each library should be given. As noted above, order may be important - consult the documentation for each library. An empty list has the same effect as omitting the hooks-libraries configuration element all together. There is one case where this is not true: if Kea is running with a configuration that contains a hooks-libraries item, and that item is removed and the configuration reloaded, the removal will be ignored and the libraries remain loaded. As a workaround, instead of removing the hooks-libraries item, change it to an empty list. This will be fixed in a future version of Kea. At the present time, only the kea-dhcp4 and kea-dhcp6 processes support hooks libraries.

As described above, the hooks functionality provides a way to customize a Kea server without modifying the core code. ISC has chosen to take advantage of this feature to provide functions that may only be useful to a subset of Kea users. To this end ISC has created some hooks libraries; these discussed in the following sections. Some of these libraries will be available with the base code while others will be shared with organizations supporting development of Kea , possibly as a 'benefit' or 'thank you' for helping to sustain the larger Kea project. If you would like to get access to those libraries, please consider taking out a support contract: this includes professional support, advance security notifications, input into our roadmap planning, and many other benefits, while helping making Kea sustainable in the long term. Currently the following libraries are available or planned from ISC: Name Availability Since Description user_chk Kea sources Kea 0.8 Reads known users list from a file. Unknown users will be assigned a lease from the last subnet defined in the configuration file, e.g. to redirect them a captive portal. This demonstrates how an external source of information can be used to influence the Kea allocation engine. This hook is part of the Kea source code and is available in the src/hooks/dhcp/user_chk directory. Forensic Logging Support customers Kea 1.1.0 This library provides hooks that record a detailed log of lease assignments and renewals into a set of log files. In many legal jurisdictions companies, especially ISPs, must record information about the addresses they have leased to DHCP clients. This library is designed to help with that requirement. If the information that it records is sufficient it may be used directly. If your jurisdiction requires that you save a different set of information, you may use it as a template or example and create your own custom logging hooks. Lightweight 4over6 Support customers Autumn 2016 Lightweight 4over6 (RFC 7596) is a new IPv6 transition technology that provides IPv4 as a service in IPv6-only network. It assumes that dual-stack clients will get a regular IPv6 address and IPv6 prefix, but only a fraction of an IPv4 address. The fraction is specified as port-set, which is essentially a range of TCP and UDP ports a client can use. By doing the transition on the client side, this technology eliminates the need to deploy expensive Carrier Grade NATs within the operator's network. The problem on the DHCP side is the non-trivial logic behind it: each client needs to receive an unique set of lightweight 4over6 options (RFC 7598), that include the IPv4 address (shared among several clients), port-set (which is unique among clients sharing the same IPv4 address) and a number of additional parameters. This hooks library will generate values of those options dynamically, thus eliminating the need to manually configure values for each client separately. ISC hopes to see more hooks libraries become available as time progresses, both developed internally and externally. Since this list may evolve dynamically, we decided to keep it on a wiki page, available at this link: http://kea.isc.org/wiki/Hooks. If you are a developer or are aware of any hooks libraries not listed there, please send a note to the kea-users or kea-dev mailing lists and someone will update it.

The user_chk library is the first hooks library published by ISC. It attempts to serve several purposes: To assign "new" or "unregistered" users to a restricted subnet, while "known" or "registered" users are assigned to unrestricted subnets. To allow DHCP response options or vendor option values to be customized based upon user identity. To provide a real time record of the user registration activity which can be sampled by an external consumer. To serve as a demonstration of various capabilities possible using the hooks interface. Once loaded, the library allows segregating incoming requests into known and unknown clients. For known clients, the packets are processed mostly as usual, except it is possible to override certain options being sent. That can be done on a per host basis. Clients that are not on the known hosts list will be treated as unknown and will be assigned to the last subnet defined in the configuration file. As an example of use, this behavior may be used to put unknown users into a separate subnet that leads to a walled garden, where they can only access a registration portal. Once they fill in necessary data, their details are added to the known clients file and they get a proper address after their device is restarted. This library was developed several years before the host reservation mechanism has become available. Currently host reservation is much more powerful and flexible, but nevertheless the user_chk capability to consult and external source of information about clients and alter Kea's behavior is useful and remains of educational value. The library reads the /tmp/user_chk_registry.txt file while being loaded and each time an incoming packet is processed. The file is expected to have each line contain a self-contained JSON snippet which must have the following two entries: type, whose value is "HW_ADDR" for IPv4 users or "DUID" for IPv6 users id, whose value is either the hardware address or the DUID from the request formatted as a string of hex digits, with or without ":" delimiters. and may have the zero or more of the following entries: bootfile whose value is the pathname of the desired file tftp_server whose value is the hostname or IP address of the desired server A sample user registry file is shown below: { "type" : "HW_ADDR", "id" : "0c:0e:0a:01:ff:04", "bootfile" : "/tmp/v4bootfile" } { "type" : "HW_ADDR", "id" : "0c:0e:0a:01:ff:06", "tftp_server" : "tftp.v4.example.com" } { "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:04", "bootfile" : "/tmp/v6bootfile" } { "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:06", "tftp_server" : "tftp.v6.example.com" } As with any other hooks libraries provided by ISC, internals of the user_chk code are well documented. You can take a look at the Kea Developer's Guide section dedicated to the user_chk library that discusses how the code works internally. That, together with our general entries in Hooks Framework section should give you some pointers how to extend this library and perhaps even write your own from scratch.

This section describes the forensic log hooks library. This library provides hooks that record a detailed log of lease assignments and renewals into a set of log files. Currently this library is only available to ISC customers with a support contract. In many legal jurisdictions companies, especially ISPs, must record information about the addresses they have leased to DHCP clients. This library is designed to help with that requirement. If the information that it records is sufficient it may be used directly. If your jurisdiction requires that you save a different set of information you may use it as a template or example and create your own custom logging hooks. This logging is done as a set of hooks to allow it to be customized to any particular need. Modifying a hooks library is easier and safer than updating the core code. In addition by using the hooks features those users who don't need to log this information can leave it out and avoid any performance penalties.

The names for the log files have the following form: path/base-name.CCYYMMDD.txt The "path" and "base-name" are supplied in the configuration as described below see . The next part of the name is the date the log file was started, with four digits for year, two digits for month and two digits for day. The file is rotated on a daily basis. When running Kea servers for both DHCPv4 and DHCPv6 the log names must be distinct. See the examples in .

For DHCPv4 the library creates entries based on DHCPREQUEST messages and corresponding DHCPv4 leases intercepted by lease4_select (for new leases) and lease4_renew (for renewed leases) hooks. An entry is a single string with no embedded end-of-line markers and has the following sections: address duration device-id {client-info} {relay-info} Where: address - the leased IPv4 address given out and whether it was assigned or renewed. duration - the lease lifetime expressed in days (if present), hours, minutes and seconds. A lease lifetime of 0xFFFFFFFF will be denoted with the text "infinite duration". device-id - the client's hardware address shown as numerical type and hex digit string. client-info - the DHCP client id option (61) if present, shown as a hex string. relay-info - for relayed packets the giaddr and the RAI circuit-id, remote-id and subscriber-id options (option 82 sub options: 1, 2 and 6) if present. The circuit id and remote id are presented as hex strings For instance (line breaks added for readability, they would not be present in the log file). Address: 192.2.1.100 has been renewed for 1 hrs 52 min 15 secs to a device with hardware address: hwtype=1 08:00:2b:02:3f:4e, client-id: 17:34:e2:ff:09:92:54 connected via relay at address: 192.2.16.33, identified by circuit-id: 68:6f:77:64:79 and remote-id: 87:f6:79:77:ef

For DHCPv6 the library creates entries based on lease management actions intercepted by the lease6_select (for new leases), lease6_renew (for renewed leases) and lease6_rebind (for rebound leases). An entry is a single string with no embedded end-of-line markers and has the following sections: address duration device-id {relay-info}* Where: address - the leased IPv6 address or prefix given out and whether it was assigned or renewed. duration - the lease lifetime expressed in days (if present), hours, minutes and seconds. A lease lifetime of 0xFFFFFFFF will be denoted with the text "infinite duration". device-id - the client's DUID and hardware address (if present). relay-info - for relayed packets the content of relay agent messages, remote-id (code 37), subscriber-id (code 38) and interface-id (code 18) options if present. Note that interface-id option, if present, identifies the whole interface the relay agent received the message on. This typically translates to a single link in your network, but it depends on your specific network topology. Nevertheless, this is useful information to better scope down the location of the device, so it is being recorded, if present. For instance (line breaks added for readability, they would not be present in the log file). Address:2001:db8:1:: has been assigned for 0 hrs 11 mins 53 secs to a device with DUID: 17:34:e2:ff:09:92:54 and hardware address: hwtype=1 08:00:2b:02:3f:4e (from Raw Socket) connected via relay at address: fe80::abcd for client on link address: 3001::1, hop count: 1, identified by remote-id: 01:02:03:04:0a:0b:0c:0d:0e:0f and subscriber-id: 1a:2b:3c:4d:5e:6f

To use this functionality the hook library must be included in the configuration of the desired DHCP server modules. The legal_log library is installed alongside the Kea libraries in [kea-install-dir]/lib where kea-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 legal_log library could be done with the following Kea4 configuration: "Dhcp4": { "hooks-libraries": [ { "library": "/usr/local/lib/libdhcp_legal_log.so", "parameters": { "path": "/var/kea/var", "base-name": "kea-forensic4" } }, ... ] } To configure it for kea-dhcp6, the commands are simply as shown below: "Dhcp6": { "hooks-libraries": [ { "library": "/usr/local/lib/libdhcp_legal_log.so", "parameters": { "path": "/var/kea/var", "base-name": "kea-forensic6" } }, ... ] } Two Hook Library parameters are supported: path - the directory in which the forensic file(s) will be written. The default value is [prefix]/kea/var. The directory must exist. base-name - an arbitrary value which is used in conjunction with the current system date to form the current forensic file name. It defaults to kea-legal.

Hook libraries can have their own configuration parameters. That is convenient if the parameter applies to the whole library. However, sometimes it is very useful if certain configuration entities are extended with additional configuration data. This is where the concept of user contexts comes in. A sysadmin can define an arbitrary set of data and attach it to Kea structures, as long as the data is specified as JSON map. In particular, it is possible to define fields that are integers, strings, boolean, lists and maps. It is possible to define nested structures of arbitrary complexity. Kea does not use that data on its own, simply stores and makes it available for the hook libraries. As of Kea 1.2, the only structures that allow user contexts are address and prefix pools, but it is expected to extend other structures with the user context capability.