OPNsense KEA DHCP Reservations Role

Overview

This role manages KEA DHCPv4 static reservations (MAC → IP mappings) with full CRUD operations.

Purpose

• Static IPs: Assign fixed IPs to devices by MAC address
• Full CRUD: Automatically creates, updates, and deletes reservations
• Per-Subnet: Reservations are tied to specific subnets
• Idempotent: Safe to run multiple times

Requirements

• Ansible 2.9 or higher
• OPNsense firewall with API access enabled
• os-kea plugin installed
• Subnets must exist before creating reservations
• API key with KEA permissions

Role Variables

Configuration Structure

opnsense_kea_dhcp_reservations_list:
  - subnet: "192.168.x.x/24"      # Must match existing subnet
    ip_address: "192.168.x.x"    # Static IP to assign
    hw_address: "2c:d8:de:89:d1:55"  # MAC address
    hostname: "device-name"        # Optional hostname
    description: "Device description"  # Optional

Delete Behavior

Reservations not in the config will be deleted from OPNsense. The code is the source of truth.

Example Playbook

---
- name: Configure KEA DHCP Reservations
  hosts: mint-vm
  gather_facts: false

  vars_files:
    - ../../roles/opnsense_kea_dhcp_reservations/vars/reservations.yml

  tasks:
    - name: Configure KEA DHCP reservations
      ansible.builtin.include_role:
        name: opnsense_kea_dhcp_reservations

Important Notes

1. Run subnets role first: Reservations reference subnets by CIDR
2. MAC format: Use lowercase with colons (e.g., aa:bb:cc:dd:ee:ff)
3. IP must be in subnet: The IP address must be within the subnet range

API Endpoints

• GET /api/kea/dhcpv4/search_reservation - List reservations
• GET /api/kea/dhcpv4/search_subnet - List subnets (for UUID lookup)
• POST /api/kea/dhcpv4/add_reservation - Create reservation
• POST /api/kea/dhcpv4/set_reservation/{uuid} - Update reservation
• POST /api/kea/dhcpv4/del_reservation/{uuid} - Delete reservation
• POST /api/kea/service/reconfigure - Apply changes

License

MIT