# Kea DHCP to Unbound DNS Registration

*February 7, 2026*
 — by JameZUK

> This plugin bridges the gap between the Kea DHCP server (IPv4 & IPv6) and Unbound DNS on OPNsense. It automatically registers hostnames for DHCP clients into the Unbound DNS subsystem, restoring dynamic DNS functionality with robust dual-stack support.



## Features

- **Smart Update Logic:** Intelligently handles dual-stack environments. It preserves existing IPv4 records when adding IPv6 (and vice versa), eliminating race conditions.
- **Automatic PTR Generation:** Automatically generates reverse DNS (Pointer) records in both standard and `in-addr.arpa` formats.
- **Persistence & Repair:** Includes `rc.syshook.d` scripts to ensure patches survive OPNsense firmware updates and system reboots.
- **Dedicated Logging:** Writes detailed, timestamped activity logs to `/var/log/kea-unbound.log` with automatic rotation via `newsyslog`.
- **Smart Hostnames:** Automatically generates hostnames from MAC addresses or DUIDs if the client device does not provide one.
- **Non-Destructive:** Uses OPNsense's native hook system to inject configuration safely without modifying core system files.

## Prerequisites

Before installing, ensure the following services are enabled in OPNsense:

- **Kea DHCPv4** and/or **Kea DHCPv6**.
- **Unbound DNS**.
- **Kea Control Agent:** This service must be enabled for the plugin to function correctly.
  1. Navigate to **Services > Kea DHCP > Control Agent**.
  2. Enable the service and click **Save**.
  3. Start/Restart the service.

## Installation

### Option 1: Direct Installation (Recommended)

You can install the pre-compiled package directly via the OPNsense shell (SSH).

1. Log in to your OPNsense router via SSH.
2. Run the following command:

```sh
pkg add https://github.com/flaviuvlaicu/kea-unbound/raw/refs/heads/main/os-kea-unbound-3.3.9.pkg
```

> **Note:** You may see a "misconfigured" warning next to the plugin in the OPNsense web interface. This is cosmetic and expected when installing packages manually outside of a signed repository.

### Option 2: Build from Source

If you prefer to build the package yourself:

1. Download the `build_plugin.sh` script from this repository.
2. Upload the script to your OPNsense router.
3. Run the following commands:

```sh
chmod +x build_plugin.sh
./build_plugin.sh
pkg add ./os-kea-unbound-3.3.9.pkg
```

## Configuration

Once installed, you must enable the registration feature in the Kea settings.

### IPv4 Configuration

1. Navigate to **Services > Kea DHCP > Kea DHCPv4 > Settings**.
2. Locate the **General Settings** section.
3. Tick the checkbox: **Register Leases in Unbound (via os-kea-unbound)**.
4. Click **Save**.

### IPv6 Configuration

1. Navigate to **Services > Kea DHCP > Kea DHCPv6 > Settings**.
2. Locate the **General Settings** section.
3. Tick the checkbox: **Register Leases in Unbound (via os-kea-unbound)**.
4. Click **Save**.

### Apply Changes

- Restart Kea DHCPv4.
- Restart Kea DHCPv6.

The plugin will immediately begin processing lease events.

## Upgrading

To prevent configuration conflicts or service crashes during an upgrade, follow this "Clean Upgrade" procedure.

1. **Disable Hooks:**
   - Navigate to **Services > Kea DHCP > Settings**.
   - Uncheck the **Register Leases in Unbound** box and click **Save**.
   - This safely detaches the hook from Kea configuration files.

2. **Replace Package:**
   - Log in via SSH and run:

   ```sh
   pkg delete os-kea-unbound
   pkg add ./os-kea-unbound-3.3.9.pkg
   ```

3. **Re-Enable Hooks:**
   - Return to **Services > Kea DHCP > Settings**.
   - Check the **Register Leases in Unbound** box and click **Save**.
   - Restart the Kea services.

## Troubleshooting & Recovery

If Kea fails to start after an upgrade (e.g., due to a lingering invalid path), use these recovery methods.

### 1. Manual Bypass (CLI)

If the web interface is inaccessible or Kea is crashing, run these commands via SSH to surgically remove the hook configuration. This will allow Kea to start without the plugin.

```sh
sed -i '' '/"hooks-libraries"/,/\]/d' /usr/local/etc/kea/kea-dhcp4.conf
sed -i '' '/"hooks-libraries"/,/\]/d' /usr/local/etc/kea/kea-dhcp6.conf
service kea-dhcp4 restart
service kea-dhcp6 restart
```

### 2. Restore Configuration

If the OPNsense configuration is corrupted, you can restore a previous backup from the console:

1. Access the console (SSH or physical screen).
2. Select **Option 13** (Restore a backup).
3. Select a configuration timestamped prior to the failed upgrade.

### 3. Factory Reset

In the event of a total lockout where no other method works:

1. Access the console.
2. Select **Option 4** (Reset to factory defaults).
3. Once the system reboots (default IP: `192.168.1.1`), restore your configuration via the Web GUI.

## Verification

### 1. Check the Log File

Watch the dedicated log file for real-time updates:

```sh
tail -f /var/log/kea-unbound.log
```

**Output Example:**

```
2026-01-19 18:42:05 [info] Added AAAA for client-device.example.com (2001:db8::1001)
2026-01-19 18:42:08 [info] Added A for smart-device.example.com (192.168.1.10)
```

### 2. Run Health Check

A diagnostic script is provided to validate the installation:

```sh
./healthcheck.sh
```

### 3. Query Unbound Directly

Check if a host is resolvable in the live system:

```sh
unbound-control -c /var/unbound/unbound.conf list_local_data | grep "smart-device"
```

## Uninstallation

To remove the plugin and revert all changes:

```sh
pkg delete os-kea-unbound
```

This will automatically remove the hook script, rotation configuration, and restore the original Kea configuration files. You should restart the Kea services after uninstallation.


---
*Source: [https://vlaicu.io/posts/kea-unbound/](https://vlaicu.io/posts/kea-unbound/)*