Kea DHCP and Stork on AWS User Guide

Overview

ISC Kea is a modern, high performance open source DHCPv4 and DHCPv6 server with a clean JSON configuration, a full management API and pluggable back ends. Stork is its companion web dashboard and monitoring UI: it monitors one or more Kea servers and surfaces their daemons, subnets, shared networks, address pools, host reservations and pool and lease utilisation from a single screen.

This cloudimg image runs ISC Kea 3.0.3, the Stork 2.4.1 server and agent, and a bundled PostgreSQL 16 on one instance. The Stork server, PostgreSQL and the Kea control channel all bind to the loopback interface only; a host nginx reverse proxy terminates TLS on port 443 in front of the Stork UI, and plain HTTP on port 80 redirects to HTTPS. PostgreSQL's data cluster lives on a dedicated data volume mounted at /var/lib/postgresql, so your monitoring database survives OS-disk changes and is resizable independently.

Security is enforced from first boot. Stork ships a default admin / admin login; this image rotates it to a unique password generated for the individual instance before the TLS port is reachable, and the default login is proven rejected. The PostgreSQL role password, the Kea control API credential and the self-signed TLS certificate are all generated per instance too. The local Kea is registered and monitored in the dashboard automatically. Backed by 24/7 cloudimg support.

What is included:

• ISC Kea 3.0.3 (MPL-2.0), a modern DHCPv4/DHCPv6 server, with an HTTP control channel on loopback
• The Stork 2.4.1 server and agent (MPL-2.0), the local Kea pre-registered and monitored on first boot
• A bundled PostgreSQL 16 on loopback, its data cluster on a dedicated data volume at /var/lib/postgresql
• nginx terminating TLS on port 443 in front of the Stork UI; port 80 redirects to HTTPS
• The default Stork admin login rotated to a per-instance password, plus per-instance PostgreSQL, Kea control and TLS secrets, all generated on first boot and written to a root-only file
• A safe-by-default Kea that serves no network interface out of the box, with a demo subnet so the dashboard renders real content
• postgresql, isc-kea-dhcp4-server, isc-stork-server, isc-stork-agent and nginx as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An AWS account, an EC2 key pair in the target region, and a VPC with a public subnet. m5.large (2 vCPU / 8 GiB RAM) is the recommended instance type. Security group inbound: allow 22/tcp from your management network for SSH and 443/tcp for the Stork web UI (optionally 80/tcp, which only redirects to HTTPS).

Step 1 - Launch the AMI

Subscribe to the listing in AWS Marketplace, then launch an instance from the AMI into your VPC with the security group described above. Choose the m5.large instance type and attach your EC2 key pair. First boot rotates the Stork admin login, generates the per-instance secrets and TLS certificate, and registers the local Kea, so the dashboard is ready within a couple of minutes of launch.

Step 2 - Connect to your instance

Connect over SSH as the default login user for the operating system variant you launched. The login user differs per OS, so use the row for your variant:

ssh -i your-key.pem ubuntu@<public-ip>

Step 3 - Read your unique credentials

On first boot the instance rotates the Stork admin password and generates the Kea control API credential, writing them along with the resolved web URL to a root-only file. Read it with sudo:

sudo cat /root/kea-dhcp-stork-credentials.txt

You will see the Stork URL, the admin username and per-instance STORK_ADMIN_PASSWORD, and the Kea control API credentials (KEA_CTRL_USER / KEA_CTRL_PASSWORD). There is no default or shared login anywhere in the image; every secret is unique to this instance.

Step 4 - Verify the services and the security model

Confirm every component is running:

systemctl is-active postgresql isc-kea-dhcp4-server isc-stork-server isc-stork-agent nginx

All five report active. Confirm the TLS front door answers and that plain HTTP redirects:

curl -sk -o /dev/null -w 'healthz(443): %{http_code}\n' https://127.0.0.1/healthz
curl -s  -o /dev/null -w 'http(80) redirect: %{http_code}\n' http://127.0.0.1/

You should see healthz(443): 200 and http(80) redirect: 301. Now confirm that the Stork server, PostgreSQL and the Kea control channel all bind to the loopback interface only, so nothing but the TLS front door is exposed:

sudo ss -ltn | awk 'NR>1{print $4}' | grep -E ':5432$|:8000$|:8080$|:8081$' | sort -u

Every product port comes back on 127.0.0.1 (127.0.0.1:5432 PostgreSQL, 127.0.0.1:8000 the Kea control socket, 127.0.0.1:8080 the Stork REST server, 127.0.0.1:8081 the Stork agent). The only public listeners are 22, 80 and 443.

Step 5 - Confirm the login model over TLS

The default admin / admin login is rejected — it was rotated on first boot:

curl -sk -o /dev/null -w 'default admin/admin: %{http_code}\n' -X POST -H 'Content-Type: application/json' \
  --data '{"authenticationMethodId":"internal","identifier":"admin","secret":"admin"}' \
  https://127.0.0.1/api/sessions

That returns a non-200 (the default password no longer works). The per-instance admin password authenticates over TLS and returns 200:

curl -sk -o /dev/null -w 'per-instance admin: %{http_code}\n' -X POST -H 'Content-Type: application/json' \
  --data '{"authenticationMethodId":"internal","identifier":"admin","secret":"<STORK_ADMIN_PASSWORD>"}' \
  https://127.0.0.1/api/sessions

Step 6 - Query the local Kea through its control API

The local Kea's HTTP control channel is bound to loopback and protected with the per-instance basic-auth credential from your credentials file. Query its running configuration — the demo subnet 192.0.2.0/24 comes back:

KP=$(sudo grep '^KEA_CTRL_PASSWORD=' /root/kea-dhcp-stork-credentials.txt | cut -d= -f2-)
curl -s -u "stork:${KP}" -H 'Content-Type: application/json' \
  -X POST --data '{"command":"config-get"}' http://127.0.0.1:8000/ | grep -o '192.0.2.0/24' | head -1

Without the credential the same endpoint answers 401, and it is unreachable off the loopback interface.

Step 7 - Sign in to the Stork web UI

Open the Stork UI in a browser at https://<instance-public-ip>/. The instance uses a per-instance self-signed TLS certificate, so accept the browser certificate warning (or front it with your own domain and certificate). Sign in with the admin username and the STORK_ADMIN_PASSWORD from your credentials file.

The DHCP dashboard shows the monitored Kea, its DHCPv4 daemon, the subnet count and address-pool statistics at a glance:

The subnets view lists each subnet with its address pools and utilisation — here the demo 192.0.2.0/24 subnet with its pool 192.0.2.100 - 192.0.2.200:

The machines view shows the local Kea already registered and authorised, with its agent version, monitored DHCPv4 daemon and resource usage:

Step 8 - Point Kea at your own network

Out of the box the bundled Kea serves no network interface (interfaces-config is empty), so the image can never act as a rogue DHCP server on your VPC; the demo subnet exists only so the dashboard renders real content. To serve your own network, edit the interfaces-config and subnet4 sections of /etc/kea/kea-dhcp4.conf, then restart Kea:

sudo systemctl restart isc-kea-dhcp4-server

The change is reflected in Stork automatically as the agent re-polls the Kea. To monitor additional Kea servers, install a Stork agent on each and register it with this Stork server from Services → Machines → Installing Stork Agent on a New Machine.

Step 9 - Data volume

PostgreSQL's data cluster lives on a dedicated data volume mounted at /var/lib/postgresql:

df -h /var/lib/postgresql | tail -1

Because it is a separate EBS volume, you can snapshot it with EBS snapshots or AWS Backup and resize it independently of the OS disk as the estate of monitored Kea servers grows.

Support

cloudimg provides 24/7 technical support for this product by email and live chat at support@cloudimg.co.uk. We help with deployment, binding Kea to your own network interfaces and subnets, adding further Kea servers to the Stork dashboard, reverse-proxy termination with your own domain and TLS certificate, and backup planning for the monitoring database.

Kea and Stork are trademarks of Internet Systems Consortium. This image is not affiliated with, endorsed by, or sponsored by ISC; the Kea and Stork names and logos are used nominatively to identify the open-source software shipped in this image.