Flexible Identifier

A Kea Hook Library from ISC

Kea Hook Libraries

The Flexible Identifier Library is a Kea Hook library, and is included with any ISC Kea DHCP support subscription.

Kea Hook libraries extend the base functionality of the open source Kea DHCP server. The Flexible Identifier Library extends Kea’s host reservations feature.

This feature is supported with Kea 1.2 and later versions.


Construct device identifier using:

  • Standard options
  • Vendor options
  • Relay options
  • Custom options
  • Fixed fields
  • Packet meta-data
  • Concatenation, substring of any of the above

This identifier can be used to reserve or assign DHCP resources:

  • IPv4 or IPv6 addresses
  • IPv6 prefixes
  • DHCPv4 or DHCPv6 options
  • Hostname
  • Assign to a client class

Kea Hooks libraries extend the base functionality of the open source Kea DHCP server. The Flexible Identifier Library extends Kea’s host reservations feature by allowing the administrator to identify clients based on any criteria available.


Host reservations are typically based on a few standard client or connection attributes. DHCPv4 reservations can be based on hardware address, DUID, circuit-id or client-id.  DHCPv6 reservations use either the client hardware address or DUID.


Some deployments require more complex reservation criteria.  For example, some implementations may need to identify clients based on the interface-id option inserted by a relay agent, or require a combination of several options and fields to uniquely identify a client. For these scenarios you may want to use the Flexible Identifier Library to extend Kea’s standard functionality.


The Flexible Identifier Library uses the same notation used for client classification. The administrator can create an expression using any of the available device identifiers (list below) to be used as the client identifier. This expression is evaluated for each incoming packet, generating an identifier that is used to identify the client and select the appropriate reservation.


These expressions can be as simple as “option[17]” (which would use the content of option 17, the vendor specific option) or be complex as needed (see examples on the next page).  The expression can use any or all of IPv4 addresses, single or multiple IPv6 addresses, single or multiple IPv6 prefixes, hostnames, IPv4 options, IPv6 options, and many fixed fields in the DHCPv4 packet (such as filename, server-hostname, and boot-file-name).


Host reservations can include an IPv4 address, multiple IPv6 addresses, multiple IPv6 prefixes, a hostname, IPv4 options, IPv6 options, and many fixed fields in DHCPv4 (filename, server-hostname, and boot-file-name).

Example Setup

"reservations": [
{ // first host
   "flex-id": "'port1234'",
   "ip-addresses": [ "2001:db8::1" ]

{ // second host
   "flex-id": "'portC37X'",
   "prefixes": [ "2001:db8:1::/64" ],
   "hostname": "alice-laptop"

... // as many hosts as you need

// Expression defined once
"hooks-libraries": [{
   "library": "libdhcp_flex_id.so",
   "parameters": {

Example Expressions


Use the value of option 18 (interface-id) inserted by the first DHCPv6 relay (note there may be multiple DHCPv6 relays).

substring(relay4[2].hex, 0, 10)

Use the first 10 bytes of the value of sub-option 2 (that’s remote-id) from the relay agent information option (option 82) inserted by a DHCPv4 relay agent.


Look at vendor option for enterprise-id 4491 (DOCSIS), take sub-option 1026 (the cable modem MAC address option) and use its value.

concat(relay4[2].hex, relay4[6].hex)

Take sub-option 2 (remote-id) and sub-option 6 (Subscriber-Id) inserted by DHCPv4 relay agent, concatenate them and use the result as the identifier.

Questions and Answers

How can I get the Flexible Identifier Library?
The Flexible Identifier library is available to ISC customers with a current Kea DHCP support contract. To become a Kea support subscriber, contact ISC at info@isc.org.

How is the library distributed?
The Flexible Identifier library is an additional package that contains full source code for the library. It requires compilation, similar to regular Kea libraries. While the original source code is provided, its usage and redistribution is governed by a EULA. Licensed users may examine and modify the code for their own use, but are not allowed to re-distribute it in any form.

How do I use it?
Loading the library is easy. An example snippet for your Kea configuration file is shown above.

What documentation is available?
The Kea User’s guide explains how to use the library. There is also a Developer’s Guide, which explains the internals and is addressed to people who would like to extend and customize it. The library is written in C++.

What support is available?

ISC provides professional technical support for the open source software we develop. Annual support contracts are available at different levels, depending on the SLA you require. We have a dedicated support engineering staff and can provide 7 x 24 support for critical problems. This library is supported for Kea 1.2 and later versions.

Can I continue using the library after my support contract concludes?
Yes. Once you get the library from ISC, it is yours. We recommend that you continue with ISC support as long as you wish to use the library, so that you can receive any updates. While ISC does its best to limit this possibility, there may be changes in future Kea releases that would prevent you from using an out of date hooks library.

Last modified: May 10, 2017 at 12:50 pm