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

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

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:

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:

./healthcheck.sh

3. Query Unbound Directly

Check if a host is resolvable in the live system:

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

Uninstallation

To remove the plugin and revert all changes:

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.