Fork notice: This is netbox-kea-ng, an independently maintained fork of netbox-kea by Devon Mar. It is published to PyPI as netbox-kea-ng and tracked in this repository. Upstream changes are periodically merged where applicable.

NetBox plugin for the Kea DHCP server. Manage your DHCP infrastructure directly from NetBox — view daemon status, search and manage leases, manage host reservations, configure subnets/pools/options, and keep your NetBox IPAM synchronized with live Kea data via a background job.

• View Kea daemon status (Control Agent + DHCPv4/DHCPv6 daemons)
• Full DHCPv4 and DHCPv6 support
• Search, view, delete and export DHCP leases
• Search for NetBox devices/VMs directly from DHCP leases
• View DHCP subnets from Kea configuration
• REST API and GraphQL support for Server objects

Host Reservations

• Full CRUD for DHCPv4 and DHCPv6 reservations via host_cmds hook
• Identifier types: hw-address (v4), DUID (v6), client-id, flex-id, circuit-id, remote-id
• Per-reservation DHCP options
• Journal entries on add/edit/delete

Subnet Management

• Add, edit and delete subnets (requires subnet_cmds or config-set)
• Pool management (add/delete pools per subnet)
• Shared network management (add/edit/delete)
• Per-subnet and global DHCP option editing

IPAM Sync

• Sync active leases → NetBox IPAddress (status active)
• Sync reservations → NetBox IPAddress (status reserved)
• Sync button on individual leases and reservations
• Bulk sync for entire lease tables
• Pending-change detection: badge on leases where a reservation exists at a different IP
• MAC address sync → NetBox MACAddress
• Sets dns_name on IPAddress for automatic DNS sync via netbox-dns IPAMDNSsync

Periodic Background Sync (requires rqworker)

• Automatic Kea→NetBox IPAM sync on a configurable interval (default 5 minutes)
• Syncs all leases and reservations from all configured servers
• Visible in NetBox System → Background Jobs

DHCP Control

• Enable/disable DHCPv4 and DHCPv6 daemons from the NetBox UI

Dual-URL Server

• Optional separate URLs for DHCPv4 and DHCPv6 Control Agents
• Supports environments where v4 and v6 are served by separate Kea processes

Global / Cross-Server Views

• Combined dashboard, lease, reservation, subnet and shared-network views across all servers

Lease Add / Edit / Bulk Import

• Add and edit individual leases
• Bulk import leases from CSV

• NetBox 4.3, 4.4 or 4.5
• Kea Control Agent
• lease_cmds hook library (for lease search and management)
• host_cmds hook library (optional, for reservation management)
• subnet_cmds hook library (optional, for subnet add/edit/delete)

The plugin degrades gracefully when optional hooks are absent — tabs for unavailable features are hidden automatically.

Tested with Kea v2.4.1 using the memfile lease database. Other versions and databases should also work.

Add netbox-kea-ng to your local_requirements.txt (or install with pip):

pip install netbox-kea-ng

In configuration.py:

PLUGINS = ["netbox_kea"]

Optionally configure plugin settings (see Configuration):

PLUGINS_CONFIG = {
    "netbox_kea": {
        "kea_timeout": 30,
        "sync_interval_minutes": 5,
        "sync_leases_enabled": True,
        "sync_reservations_enabled": True,
        "sync_prefixes_enabled": True,
        "sync_ip_ranges_enabled": True,
        "sync_max_leases_per_server": 50000,
        "stale_ip_cleanup": "remove",
    }
}

./manage.py migrate

The periodic IPAM sync job runs via NetBox's built-in rqworker. If you're not already running it:

./manage.py rqworker

The Kea IPAM Sync job will appear under System → Background Jobs and runs on the configured interval.

All settings are under PLUGINS_CONFIG["netbox_kea"]:

Configure one Server URL that points to the Kea Control Agent:

When DHCPv4 and DHCPv6 are served by separate Kea processes (each with its own Control Agent):

The main CA URL (ca_url) is required and acts as a fallback for any protocol without a dedicated URL. By default, both DHCPv4 URL and DHCPv6 URL use CA-level credentials; see Per-protocol credentials below for optional overrides.

When connecting directly to DHCP daemons (bypassing the Control Agent), you can configure separate credentials per protocol:

If per-protocol credentials are not set, the CA-level credentials (ca_username/ca_password) are used as the default for all connections.

Each server has optional overrides for the IPAM sync job:

These fields override the global PLUGINS_CONFIG values for that specific server.

The Kea IPAM Sync job runs automatically when rqworker is active:

1. Iterates all configured Server objects
2. For each server: fetches all active leases (v4 + v6) and all reservations
3. Creates or updates NetBox IPAddress objects:
   • Leases → status=active, dns_name set from Kea hostname
   • Reservations → status=reserved, dns_name set from Kea hostname
4. Cleans up stale IPs (configurable via stale_ip_cleanup)
5. One server failing does not block others
6. Summary logged per server and in total

View job history, next scheduled time and logs under System → Background Jobs → Kea IPAM Sync.

The sync interval can be changed live via the NetBox admin without restarting the worker — edit the interval field on the job object.

When netbox-dns with IPAMDNSsync is installed:

1. The IPAM sync sets dns_name on IPAddress objects from the Kea hostname
2. IPAMDNSsync picks up dns_name changes via Django signals
3. A/AAAA/PTR records are created automatically (provided matching DNS views + zones exist)

No additional configuration is required — the integration is automatic when both plugins are present.

Add custom links to NetBox models to navigate directly to Kea lease searches.

Replace <Kea Server ID> with your server's object ID (visible in the top-right corner of the server detail page as netbox_kea.server:<ID>).

Content type: IPAM > Prefix

URL: https://netbox.example.com/plugins/kea/servers/<Kea Server ID>/leases{{ object.prefix.version }}/?q={{ object.prefix }}&by=subnet

Content types: DCIM > Interface, Virtualization > Interface

DHCPv4 URL: https://netbox.example.com/plugins/kea/servers/<Kea Server ID>/leases4/?q={{ object.mac_address }}&by=hw

DHCPv6 URL: https://netbox.example.com/plugins/kea/servers/<Kea Server ID>/leases6/?q={{ object.mac_address }}&by=hw

Content types: DCIM > Device, Virtualization > Virtual Machine

DHCPv4 URL: https://netbox.example.com/plugins/kea/servers/<Kea Server ID>/leases4/?q={{ object.name|lower }}&by=hostname

DHCPv6 URL: https://netbox.example.com/plugins/kea/servers/<Kea Server ID>/leases6/?q={{ object.name|lower }}&by=hostname

You can substitute {{ object.name|lower }} with a custom field: {{ object.cf.<your_field>|lower }}.

# Install dev dependencies
uv sync

# Lint
uv run ruff check netbox_kea/
uv run ruff format --check netbox_kea/

# REUSE compliance check
uv run reuse lint

# Format
uv run ruff format netbox_kea/

# Install pre-commit hooks
uv run pre-commit install

# Build wheel (required before integration tests)
uv build

# Run unit tests (no Docker required)
uv run pytest -q

# Run integration tests (requires Docker — see tests/test_setup.sh)
./tests/test_setup.sh
uv run pytest tests/ --tracing=retain-on-failure -v --cov=netbox_kea --cov-report=xml

See CHANGELOG for version history.

Apache-2.0 — original code by Devon Mar, fork maintained by Marcin Zieba.