Host Reservations Commands

A Kea Hooks Library from ISC

Kea Hook Libraries

The Host Commands Library is a Kea Hook library.

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

This Kea Hook library is supported for use with Kea 1.2 and later versions.

 

Feature Details

Add, get or delete host reservations on the fly, without interrupting your service. The host reservations could feature:

  • Device identified by hw-address, client-id, duid, circuit-id or almost anything else (flex-id)
  • An IPv4 address
  • Multiple IPv6 addresses
  • Multiple IPv6 prefixes
  • DHCPv4/DHCPv6 options
  • Hostname
  • Assign to a client class
  • Set specific DHCPv4 fields (hostname, next-server, etc.)

Uninterrupted

All operations are done without interrupting your service.

The Kea DHCP server is a fully functional DHCP server. Its operation is defined by a configuration file but, through a REST management interface, certain features can be controlled executed by sending it commands. A set of basic commands (such as retrieve configuration, write configuration to a named file, etc.) are provided with Kea.

An important feature of Kea is the definition and storage of host reservations in SQL databases (MySQL or PostgreSQL). The Host Commands Library extends the set of supplied commands with ones allowing the management of host reservations. In particular, it adds commands to:

 

  1. Inspect current host reservations, checking whether specific address or IPv6 prefix is reserved or whether a given device with specific identifier has a reservation. This gives you a confirmation that the information in your database is correct.
  2. Add new reservations. The input parameters are checked by Kea before they are inserted into the database. This includes basic checks (e.g. missing mandatory parameter), but also more complex ones, like checking whether a host with the same pair of (identifier-type, identifier) is already declared in the same subnet. This gives you confidence that your reservation data are consistent.
  3. Remove reservations. These can be identified by address (“I don’t want address X to be reserved anymore”) or host (“I don’t want the device Y to have any reservations”). The commands delete all records related to the reservations.

Example Set-up

// Instruct DHCPv4 or DHCPv6 to load the library
 "hooks-libraries": [{
   "library": "libdhcp_host_cmds.so"
 }]

Add and Remove a Reservation

Add a simple host reservation:
"command": "reservation-add",
"arguments": {
   "reservation": {
      "subnet-id": 1,
      "hw-address": "1b:1c:1d:1e:1f",
      "ip-address": "192.0.2.202"
   }
}

Delete a reservation for a specific device:
"command": "reservation-del",
"arguments": {
   "subnet-id": 4,
   "identifier-type": "client-id",
   "identifier": "’office-printer7’"
}

Retrieve a reservation

Check if address 192.0.2.202 is reserved:
 "command": "reservation-get",
 "arguments": {
    "subnet-id": 1,
    "ip-address": "192.0.2.202"
 }
Example response:
 "arguments": {
   "boot-file-name": "bootfile.efi",
   "client-classes": [],
   "hostname": "alice.example.org",
   "hw-address": "01:02:03:04:05:06",
   "ip-address": "192.0.2.100",
   "next-server": "192.0.0.2",
   "option-data": [ ],
   "server-hostname": "srv.isc.org"
 },
 "result": 0,
 "text": "Host found."

All examples have outer { } removed for brevity.

Questions and Answers

How can I get the Host Commands Library?
The Host Commands library is available to ISC customers with a current Kea DHCP support contract. For information about how to become a Kea support subscriber, contact ISC at info@isc.org.

How is the library distributed?
The Host Commands 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 can I use it?
Loading the library is easy. An example snippet for your Kea configuration file is shown above. More examples are available in Kea User’s Guide and sample configuration files provided with the code. Commands are issued either via command channel (JSON structures sent over Unix domain socket) or REST interface (JSON structures sent over REST interface that uses http protocol).

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++.

Can I continue using it 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:42 pm