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.
Table of Contents
[[TOC]]
Compatibility
- Foreman Smart Proxy:
- ISC Kea: 3.0.0 or newer
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).
- Suggests the next available IP address from a subnet's pool.
- Passes next-server and PXE boot file to Kea
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
Add the gem to /usr/share/foreman-proxy/bundler.d/Gemfile.local.rb:
gem 'smart_proxy_dhcp_kea_api'
After installing the gem or changing its configuration, you must restart the foreman-proxy service for the changes to take effect.
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, you must 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 | Description | Default | Required |
|---|---|---|---|
:enabled |
Enables or disables this provider module. | false |
Yes |
:kea_api_url |
The full URL to your Kea API endpoint (HTTP or HTTPS). | http://127.0.0.1:8000/ |
Yes |
:kea_api_username |
The username for HTTP Basic Authentication (optional). | nil |
No |
:kea_api_password |
The password for HTTP Basic Authentication (optional). | nil |
No |
:open_timeout |
Time in seconds to wait for the initial connection to be established. | 5 |
No |
:read_timeout |
Time in seconds to wait for a response after connecting. | 10 |
No |
:blacklist_duration_minutes |
The duration in minutes to temporarily blacklist a suggested IP. | 5 |
No |
Verifying the Installation
The Smart Proxy will test its connection to the Kea API upon initialisation. Due to lazy loading, this check runs on the first DHCP request after a proxy restart, not during the initial boot sequence.
Check /var/log/foreman-proxy/proxy.log for a "Successfully connected to Kea API" message at that time to confirm everything is working. If the connection fails, the first DHCP request will fail with an error in the log, preventing further issues.
Contributing
Bug reports and pull requests are welcome on this project's GitLab page.