Forensic Logging Library

A Kea Hooks Library from ISC

Forensic Logging Library

Forensic Logging Library is a Kea DHCP extension library.

Kea extension libraries extend the base functionality of the open source Kea DHCP server. This library is supported with Kea 1.1 and later versions.



Logs all available client and device identifying information.

Independent logging channel, is unaffected by changes in your regular logging configuration.

Separate daily log files collated by address type and prefixes.

Additional logged information:

  • Timestamp
  • Lease length
  • Hardware address
  • Client-id
  • DUID
  • Circuit-id
  • Subscriber-id
  • Remote-id
  • Relay address
  • Interface-id

Kea Hooks libraries extend the base functionality of the open source Kea DHCP server. The Forensic Logging library is a premium feature of the Kea server, offered to ISC support subscribers.


Many Internet providers are subject to legal requirements to record information about the addresses they have leased to DHCPv4 and DHCPv6 clients, in order to respond to law enforcement requests for information. This library is designed to help meet those requirements. This library will record a detailed log of lease assignments and renewals into a series of separate log files.


If the provided forensic logs are sufficient to meet your local requirements, then use the library as is. If your jurisdiction requires recording other information, this library provides a template or example for creating your own custom logging specification. ISC engineers are available to extend the library to accommodate your specific requirements.


The forensic 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 Kea 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 possible performance penalties.


While you may be tempted to process regular Kea logs to extract this information, there are a number of pitfalls that might make this approach unreliable. Kea does not recycle leases that passed its expiration timer immediately, so there is no reliable record of when a lease is no longer in use. Under certain conditions, another device may reuse the lease. The Forensic logging library was designed for accuracy and completeness despite these complicating factors. ISC therefore recommends using the Forensic Logging library, rather than filtering regular log files.

Example Setup

"hooks-libraries": [ { 
   "parameters": {
     "path": "/var/kea/",

Example Log Entry

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

Questions and Answers

How can I get the Forensic Logging Library?
The Forensic Logging library is available to ISC customers with a current Kea DHCP support contract. To become a Kea support subscriber, contact ISC at

How is the library distributed?
The Forensic Logging 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 under all ISC support contracts

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:28 pm