Version 19 (modified by vicky, 20 months ago) (diff)


Kea Hooks

Kea allows extending DHCP operation by loading third party libraries that can extract information or even change how the server behaves. This mechanism is called hooks. This page lists currently available hook libraries.

While currently this list is small, it seems to be growing steadily. We hope this trend to continue in the near future. If you have developed your own hooks, feel free to announce them on kea-dev, kea-users and extend this page with appropriate entry.

Loading hooks is easy. This example below will load a hook library called user_chk. If the library doesn't need any parameters, the parameters clause can be skipped altogether. For more details, see User's Guide, Section 14.

"Dhcp4": {
    "hooks-libraries": [
            "library": "/opt/"
            "parameters": {

If you are interested in technical details, see Developer's Guide, Section Hooks framework.

List of currently available hooks

No. Hook name License Author Link Description
1. user_chk MPL2.0 ISC User check is an example hook application that reads known users list from a file. If the user is not known, it will be assigned a lease from the last subnet defined in the configuration file, e.g. to redirect him into a captive portal. This showcases how externals source of information can be used to influence Kea allocation engine. This hook is part of the Kea sources and is available in src/hooks/dhcp/user_chk directory. Documentation.
2. options_to_options ? Ola Thoresen This hook takes the value from different options in a DHCPREQUEST and inserts them into (other) options in a DHCPREPLY. Example usage is to take the value from an Option 82 string, and insert it in an Option 43 sub option, to direct the dhcp client to the correct config file in an auto provisioning scenario.
3. legal_logging EULA (1) ISC This library provides hooks that record a detailed log of lease assignments and renewals into a set of log files. This can be very useful for forensic purposes and to meet legal obligations. Documentation
4. pxe-replace4 BSD 3 clause Michael Gugino This module utilizes hooks api to replace pxe options (siaddr, option 66, 67) via web request.
5. flex_id EULA (1) ISC Kea software provides a way to handle host reservations that include addresses, prefixes, options, client classes and other features. The reservation can be based on hardware address, DUID, circuit-id or client-id in DHCPv4 and using hardware address or DUID in DHCPv6. However, there are sometimes scenario where the reservation is more complex, e.g. uses other options that mentioned above, uses part of specific options or perhaps even a combination of several options and fields to uniquely identify a client. Those scenarios are addressed by the Flexible Identifiers hook application. Documentation
6. host_cmds EULA (1) ISC Extends remote management (REST API and control channel) to manage host reservations stored in a back end database. Provides commands for adding, retrieving and deleting host reservations.
7. runscript ? Baptiste Jonglez Hook that allows to run an external script at all hook points provided by Kea, passing information to the script as environment variables.
8. lease_cmds MPL2.0 ISC This library provides an interface that can manipulate leases in an unified, safe way for all supported backends (memfile, MySQL, PostgreSQL, Cassandra). It allows things previously impossible: manipulate leases in memfile while Kea is running, sanity check changes, check lease existence and remove all leases belonging to specific subnet. It can also catch more obscure errors, like adding a lease with subnet-id that does not exist in the configuration or configuring a lease to use an address that is outside of the subnet to which it is supposed to belong. Documentation
9. subnet_cmds EULA (2) ISC Extends remote management (REST API and control channel) to manage subnets and shared networks. Allows listing, getting, adding and deleting subnets and shared networks. Also allows making existing subnet to become a part of shared subnet and remove subnet from shared networks. Documentation
10. stats_cmds MPL 2.0 ISC Improves reporting of lease statistics when using a shared lease database backend with multiple Kea servers Documentation
11. radius EULA ISC Integration with RADIUS for access control and accounting are supported. Kea is able to send Access-Request messages and alter its behavior depending on the responses. Specific IP addresses may be assigned (if Framed-IP-Address or Framed-IPv6-Address is received), client can be assigned to specific pool (if Framed-Pool or Framed-IPv6-Pool is received) or denied service altogether (if Access-Reject is received). Kea can also send accounting messages to RADIUS accounting servers. As with other features, this supports both IPv4 and IPv6. Documentation
12. host_cache EULA ISC Some of the optional backends may be slow to respond. The host caching library creates a local cache on the Kea server of host reservations on the backend to improve performance. Documentation
13. high_availability EULA ISC Two Kea instances can now be configured to run as a pair to provide higher availability. Two modes are supported. In hot standby mode there is a primary instance handling all traffic and sending updates to its secondary partner. The secondary monitors the health of the primary and is able to take over automatically in case the primary fails. In load balancing mode both partners are active and are handling approximately half of the traffic traffic. In case of a failure of either server, the partner is able to take over responding to all traffic directed to both servers. Support for additional backup servers is implemented. The solution supports both IPv4 and IPv6 and can work with any backend, including memfile. Note that this is NOT an implementation of the IETF standard DHCPv4 failover (which does not support DHCPv6). Documentation

(1) Part of kea-premium package, available for purchase. Also, provided to all Kea support customers.

(2) Available to all Kea support customers.

This list is maintained in chronological order. Please add new entries at the end.