Hook Libraries

Kea is modular in terms of its design. Certain functions, such as those for saving to an SQL database, first need to be loaded in the configuration. In this way, the free version of the software differs from the version with a commercial support contract. The free version includes only the hook libraries for BOOTP, flexible options, high availability (HA), the MySQL and PostgreSQL back ends, script execution, and API commands for managing leases and statistics.

The paid support version has a set of API commands that manage individual parts of the configuration (e.g., the subnets) directly with API calls. Calls like add-network are available in this case. Without these libraries, the only option is to use an API request to transfer the complete configuration.

If you want the DHCPv4 server to work with a PostgreSQL database and provide the commands for managing leases by API, you need the statements from Listing 4. The syntax for including libraries is always the same: library is followed by the matching storage path. Some of the libraries also require parameters, which you can specify after the parameters key.

"hooks-libraries": [{
 "library": "/usr/lib64/kea/hooks/libdhcp_lease_cmds.so",
 "parameters": {}
 }, {
 "library": "/usr/lib64/kea/hooks/libdhcp_pgsql_cb.so",
 "parameters": {}
}]

Database Back End

If you want Kea to store the leases in a database, the lease-database block in the configuration needs to look like that shown in Listing 5, but first you need to set up the database in line with the instructions in the Kea Administrator Reference Manual [3].

"lease-database": {
 "type": "postgresql",
 "name": "kea",
 "user": "dhcp",
 "password": "dhcp",
 "host": "localhost",
 "port": 5432,
 "lfc-interval": 3600
}

After creating the database and the matching account, you need to initialize the schema. The dhcpdb_create.pgsql SQL file, which creates all the required tables, is in /usr/share/kea/scripts/pgsql/ – the path can vary depending on the distribution.

If the database contains the leases, lease control by the API can be ignored, because the details can also be changed by SQL statements. Kea looks up the table for each assignment.

API Access

As mentioned earlier, although the control socket also allows control by the API, the primary approach is by the control agent. It provides its services on port 8000 in the default configuration but only accepts connections on localhost, which fortuitously means no authentication options. The documentation suggests the use of a reverse proxy such as Apache or NGINX if you want access with user authentication. Listing 6 shows a sample configuration for the control agent.

"Control-agent": {
 "http-host": "127.0.0.1",
 "http-port": 8000,
 "control-sockets": {
  "dhcp4": {
   "socket-type": "unix",
   "socket-name": "/run/kea/kea4-ctrl-socket"
  },
  "dhcp6": {
   "socket-type": "unix",
   "socket-name": "/run/kea/kea6-ctrl-socket"
  },
  "d2": {
   "socket-type": "unix",
   "socket-name": "/run/kea/kea-ddns-ctrl-socket"
  }
 }
}

You can enable Transport Layer Security (TLS) on the server, which means you have at least one potential approach to protecting access with TLS authentication. The API can be operated with the curl command from the first line of Listing 7, which asks the control agent for the API commands that the DHCP4 daemon supports.

$ curl -s -H "Content-type: application/json" -X POST -d '{ "command": "list-commands", "service": [ "dhcp4" ] }' http://localhost:8000
$ curl -s -H "Content-type: application/json" -X POST -d '{ "command": "lease4-add", "arguments":{"ip-address":"172.17.6.8", "hw-address": "52:54:00:8a:17:9f"}, "service": [ "dhcp4" ] }' http://localhost:8000/
[ { "result": 0, "text": "Lease for address 172.17.6.8, subnet-id 2 added." } ]
$ curl -s -H "Content-type: application/json" -X POST -d '{ "command": "lease4-del", "service": [ "dhcp4" ], "arguments": { "ip-address": "172.17.6.8", "subnet-id": 1} }' http://localhost:8000/

The output depends on the hook libraries you included. For example, the commands for managing DHCP leases do not appear until you include the hook library according to the procedure described above. The version without a support contract only allows changes to the configuration in the leases or in the full configuration.

The API call in the second line of Listing 7 creates a lease. In response, Kea sends the output shown in the next line of the listing. Kea autonomously determines the subnet ID when deleting the lease from its configuration. When creating leases, unlike when creating a host reservation, it is not possible to store separate DHCP parameters for the individual clients. The call in the last line of Listing 7 deletes a lease.

For example, if you want to add a new subnet definition to the configuration, without a support contract the only option is to download the entire configuration, parse the JSON block, add the new subnet to the correct part of the data structure, and then send the entire configuration back to the Kea server as a JSON block. The JSON block for downloading the configuration is shown in the first line of Listing 8.

{ "command": "config-get", "service": [ "dhcp4" ] }
{ "command": "config-set", "service": [ "dhcp4" ], arguments: { <complete config> } }
{ "command": "config-write", "service": [ "dhcp4" ], "arguments":{"filename":"/etc/kea/<test123>.json"} }

Further processing of the resulting JSON configuration is handled by the JSON library of your preferred programming language. After completing the desired changes, the call in the second line of Listing 8 loads the entire configuration, which, however, does not mean that the configuration has been saved yet. The API call in the last line takes care of that. After changing the configuration manually, you can also use the API config-reload command; it does not expect any arguments.