Skip to content
vgroppPublic

About

Lightweight web UI and dashboard for the ISC Kea DHCP server: leases, reservations, client classes, subnets. Self-hosted, Docker, no database.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Kea Roost: Web UI for the ISC Kea DHCP Server

CI License: MIT

Kea Roost is a lightweight, self-hosted web interface and dashboard for the ISC Kea DHCP server. Manage DHCP leases and reservations, client classes, subnets and pools in the browser, keep an HA pair in step and operate it, find out why a client gets its address, and see which devices on the network have no reservation yet.

It is a single Go binary with the frontend embedded, runs in Docker, and needs no database or agents. It talks to Kea exclusively through the Kea management API and takes no part in DHCP operation: if it stops, Kea keeps serving.

Tested with Kea 3.0.3 and 3.0.4, DHCPv4 and DHCPv6, on its own or as a hot-standby HA pair. Kea Roost is an independent project, not affiliated with or endorsed by ISC, and is licensed under the MIT License.

Why Kea Roost

Kea has no web interface of its own and is configured through JSON files and an API. ISC Stork is the official dashboard for larger deployments, with agents and a PostgreSQL database. Kea Roost is meant for a home lab or a small network: one container, no database, and everyday tasks such as turning a lease into a static DHCP reservation in two clicks.

Features

  • Leases and reservations: search, filters, MAC vendors, change the MAC, classes and DHCP options, and a reservation from a lease in two clicks.
  • Client classes, subnets and global options: edit classes with their tests, pools, gateway, DNS servers, lease lifetime, the additional classes of a subnet and the options for all clients. See Kea configuration.
  • Accounts: several users as admin or viewer, a login form, optional 2FA with TOTP, and setup of the first admin.
  • IPv6: leases, reservations, subnets and prefix delegation of a kea-dhcp6, linked to the IPv4 devices by MAC, with diagnostics and metrics.
  • Address map: every address at a glance, and the free ranges.
  • Several Kea servers and HA: every change reaches all servers, differences show up, and HA can be operated: maintenance, sync, reset. For IPv4 and IPv6.
  • Diagnostics: why a client gets its address, health of all servers, DHCP traffic, and a review of the configuration against the real network.
  • Devices: everything on the network, with arpmonitor and openwrt-ap-dashboard.
  • DNS names: a hosts file of all reservations, IPv4 and IPv6, for dnsmasq or CoreDNS.
  • Prometheus metrics: compatible with the common Kea exporters.
  • Audit log and backups: every change with its user and result.
  • Interface: Classic and Modern themes in light and dark, usable on a phone, without external resources or telemetry.

Screenshots

The pictures show invented devices.

Dashboard Address map
Kea Roost dashboard with DHCP server state, HA state, recent leases and pool utilization Address map of a subnet with reserved, leased and free addresses
Leases Reservations
Table of Kea DHCP leases with search, filters and MAC vendors Table of Kea DHCP host reservations with client classes
Devices Client details
Devices on the network with reservation state, WiFi access point and last seen time Client popup with lease, reservation, network, WiFi and why the client gets its address

Install with Docker Compose

Images for linux/amd64 and linux/arm64 are published to the GitHub Container Registry as ghcr.io/vgropp/kea-roost:

curl -LO https://raw.githubusercontent.com/vgropp/kea-roost/main/compose.yaml
curl -L -o .env https://raw.githubusercontent.com/vgropp/kea-roost/main/.env.example

In compose.yaml, uncomment the image line and delete the build and image lines below it. Set KEA_URL and the Kea password in .env, then start it:

docker compose up -d

The first start prints a setup code to the log. Open the interface and create the first admin with it:

docker compose logs kea-roost | grep "setup code"

latest follows the newest release. To stay on one, set KEA_ROOST_VERSION=0.8 for a release line or KEA_ROOST_VERSION=0.8.0 for exactly one version in .env. KEA_ROOST_VERSION=snapshot follows every tested commit on main, for trying out what comes next.

To build from source instead, keep compose.yaml as it is:

git clone https://github.com/vgropp/kea-roost
cd kea-roost
go run ./cmd/oui-update  # fetches the vendor table, needed once
cp .env.example .env     # then set KEA_URL and the passwords
docker compose up -d --build

The interface is served on port 8080 (MANAGER_PORT). Backups and the audit log live in the data volume. The container runs as an unprivileged user with a read-only root filesystem.

The container must reach the Kea control socket. For Kea on the Docker host, use host.docker.internal in KEA_URL and let Kea listen on an address the container can reach, not on 127.0.0.1. The service uses Docker's default bridge network, because hosts can block project networks from reaching local services.

Documentation

Page Content
Configuration Environment, Settings page, reverse proxy, MAC vendors, themes
Accounts First admin, roles, 2FA, failed logins, lost passwords
Kea configuration What kea-dhcp4 and kea-dhcp6 need: control socket and hooks
Several servers and HA Peers, comparing, operating HA
IPv6 kea-dhcp6 next to IPv4: setup, pages, linking DUIDs to devices
Address map Free ranges and how they are found
Diagnostics Client details, health, configuration review
Devices Devices page, arpmonitor and openwrt-ap-dashboard
DNS names Hosts file for a DNS server
Prometheus metrics Metrics and their names
Development Build and test without Docker

About

Lightweight web UI and dashboard for the ISC Kea DHCP server: leases, reservations, client classes, subnets. Self-hosted, Docker, no database.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages