Foreman Smart Proxy DHCP Kea API
A Foreman Smart Proxy plugin to provide DHCP management by interacting with the ISC Kea API. This provider allows Foreman to view subnets and leases and to create and delete host reservations directly via Kea's JSON-RPC interface.
[!NOTE] This plugin currently supports IPv4 only.
[[TOC]]
Compatibility
- ISC Kea: >= 3.0.0
Features
- Adds ISC Kea as a DHCP provider for Foreman.
- Fetches subnet and pool information directly from the Kea API.
- Fetches active lease information.
- Provides host reservation management (add/delete).
- Provides lease deletion via
lease4-del. - Suggests the next available IP address from a subnet's pool.
- Passes next-server, PXE boot file, DNS servers, NTP servers, and domain-name to Kea.
- Round-trips reservation options (PXE settings, DNS, routers) so Foreman can pre-fill them on edit.
- Exposes subnet-level DHCP options (next-server, boot-file-name, DNS, NTP) to Foreman's UI.
- Automatic cache refresh with configurable TTL.
- Optional subnet filtering to manage only a subset of Kea's subnets.
Prerequisites
- A running Foreman Smart Proxy instance.
- A running ISC Kea DHCP server.
- Network connectivity from the Smart Proxy server to the Kea server's API endpoint (default port 8000).
[!WARNING] The Kea server must be configured with the
host_cmdsandlease_cmdshook libraries loaded for thedhcp4service. This plugin will not function without them.
Installation
First, install the gem on your Foreman Smart Proxy server:
gem install smart_proxy_dhcp_kea_api
Register the gem with the Smart Proxy bundler by creating a file
in /usr/share/foreman-proxy/bundler.d/:
echo "gem 'smart_proxy_dhcp_kea_api'" \
> /usr/share/foreman-proxy/bundler.d/dhcp_kea_api.rb
Then run bundle install and restart the proxy:
cd /usr/share/foreman-proxy && bundle install
systemctl restart foreman-proxy
Configuration
Configuration is done in two files in the
/etc/foreman-proxy/settings.d/ directory.
1. Enable the DHCP Module
First, enable the main DHCP module and tell it to use this plugin as its provider.
File: /etc/foreman-proxy/settings.d/dhcp.yml
---
:enabled: true
:use_provider: dhcp_kea_api
# It is highly recommended to enable the ping check for unused
# IPs to prevent conflicts.
:ping_free_ip: true
2. Configure the Kea Provider
Next, create a configuration file for the Kea provider itself.
File: /etc/foreman-proxy/settings.d/dhcp_kea_api.yml
This file enables the provider and contains all the settings needed to connect to your Kea API server.
| Setting | Default | Required | Description |
|---|---|---|---|
:enabled |
false |
Yes | Enables this provider. |
:kea_api_url |
http://127.0.0.1:8000/ |
Yes | Kea API endpoint URL. |
:kea_api_username |
nil |
No | HTTP Basic Auth username. |
:kea_api_password |
nil |
No | HTTP Basic Auth password. |
:open_timeout |
5 |
No | Connect timeout (seconds). |
:read_timeout |
10 |
No | Response timeout (seconds). |
:blacklist_duration_minutes |
5 |
No | IP blacklist duration (min). |
:cache_ttl |
60 |
No | Cache refresh interval (sec). |
:managed_subnets |
nil |
No | CIDRs to manage (all if unset). |
Example configuration:
---
:enabled: true
:kea_api_url: http://127.0.0.1:8000/
:kea_api_username: admin
:kea_api_password: secret
:cache_ttl: 120
:managed_subnets:
- 192.168.1.0/24
- 10.0.0.0/16
Verifying the Installation
Due to lazy loading, the plugin connects to Kea on the first DHCP request after a proxy restart, not at boot time.
Check /var/log/foreman-proxy/proxy.log for messages like
Loaded subnet 192.168.x.x/255.255.255.0 and mapped to Kea ID 1
to confirm the connection is working. If the connection fails,
the first DHCP request will return an error and the log will
contain the details.
Contributing
Bug reports and pull requests are welcome on this project's GitLab page.