Diese Anleitung dokumentiert die schrittweise Einrichtung von ISC Kea 3 auf Debian 13 (Kea-01), dem zentralen ISC Stork Server auf einer separaten Debian-13-Instanz (Stork) sowie der Kopplung per OPNsense DHCP Relay.
1. Kea-01 Setup (Kea DHCPv4 Server)
Auf dem Server Kea-01 (Debian 13) wird Kea 3 mit nur einem Interface im Management-Netz betrieben (Management-IP z. B. 192.168.1.11). Es wird kein DHCP-Pool für das Management-Netz angelegt, damit dort kein DHCP-Dienst antwortet.
1.1 ISC Kea 3 Repository einbinden & Pakete installieren
Melde dich als root auf Kea-01 an und installiere das offizielle ISC Kea 3 Paket-Repository:
curl -1sLf 'https://dl.cloudsmith.io/public/isc/kea-3-0/setup.deb.sh' | bash
apt update
apt install -y isc-kea-dhcp4-server isc-kea-admin
Verifikation: kea-dhcp4 -V zeigt die installierte Kea 3.x-Version an.
1.2 Netzwerkschnittstelle ermitteln
Ermittle die Schnittstelle deines Management-Netzes:
ip -br link show
ip -br addr show
Ergebnis: Der Name der primären Schnittstelle (z. B. eth0 oder ens18) ist bekannt.
1.3 Grundkonfiguration /etc/kea/kea-dhcp4.conf erstellen
Erstelle die Startkonfiguration mit HTTP-Control-Socket (127.0.0.1:8004), leerer Subnetzliste ("subnet4": []) und dem Open-Source-Hook libdhcp_subnet_cmds.so, der für Subnetzänderungen über Stork benötigt wird.
Passe den Interface-Namen (hier eth0) bei Bedarf an:
cp /etc/kea/kea-dhcp4.conf /etc/kea/kea-dhcp4.conf.bak.$(date +%F_%H%M%S) 2>/dev/null || true
tee /etc/kea/kea-dhcp4.conf >/dev/null <<'EOF'
{
"Dhcp4": {
"interfaces-config": {
"interfaces": [ "eth0" ]
},
"control-sockets": [
{
"socket-type": "http",
"socket-address": "127.0.0.1",
"socket-port": 8004
}
],
"hooks-libraries": [
{
"library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_subnet_cmds.so"
}
],
"lease-database": {
"type": "memfile",
"persist": true,
"name": "/var/lib/kea/kea-leases4.csv",
"lfc-interval": 3600
},
"subnet4": [],
"loggers": [
{
"name": "kea-dhcp4",
"output_options": [
{ "output": "/var/log/kea/kea-dhcp4.log" }
],
"severity": "INFO"
}
]
}
}
EOF
1.4 Kea-Dienst prüfen und starten
Auf Debian 13 heißt die systemd-Unit isc-kea-dhcp4-server:
kea-dhcp4 -t /etc/kea/kea-dhcp4.conf
systemctl enable --now isc-kea-dhcp4-server
systemctl status isc-kea-dhcp4-server --no-pager
ss -tlnp | grep 8004
Verifikation: kea-dhcp4 -t beendet sich ohne Fehler, der Dienst ist active (running) und Port 8004 lauscht lokal auf 127.0.0.1.
2. Stork-Server Setup (Separater Debian-13-Host)
Auf einem separaten Debian-13-Host (Stork) werden PostgreSQL und der isc-stork-server installiert.
2.1 Paketquellen & PostgreSQL installieren
Führe als root auf dem Stork-Host aus:
apt update
apt install -y postgresql postgresql-contrib curl ca-certificates
systemctl enable --now postgresql
2.2 ISC Stork Repository einbinden & Stork-Server installieren
curl -1sLf 'https://dl.cloudsmith.io/public/isc/stork/setup.deb.sh' | bash
apt update
apt install -y isc-stork-server
2.3 PostgreSQL-Datenbank und -Benutzer einrichten
Erstelle den Datenbank-Benutzer und die Datenbank für Stork:
su - postgres -c "psql -c \"CREATE USER stork WITH PASSWORD 'DeinStarkesDBPasswort';\""
su - postgres -c "psql -c \"CREATE DATABASE stork OWNER stork;\""
2.4 Stork-Server Umgebungsvariablen anlegen
Hinterlege die Zugangsdaten in /etc/stork/server.env:
mkdir -p /etc/stork
tee /etc/stork/server.env >/dev/null <<'EOF'
STORK_DATABASE_HOST=127.0.0.1
STORK_DATABASE_PORT=5432
STORK_DATABASE_NAME=stork
STORK_DATABASE_USER_NAME=stork
STORK_DATABASE_PASSWORD=DeinStarkesDBPasswort
EOF
2.5 Datenbank-Setup ausführen & Stork-Dienst starten
set -a
[ -f /etc/stork/server.env ] && . /etc/stork/server.env
set +a
stork-server setup
systemctl enable --now isc-stork-server
systemctl status isc-stork-server --no-pager
ss -tlnp | grep 8080
Verifikation: Die Weboberfläche lauscht auf http://<IP-des-Stork-Servers>:8080. Der Log-in erfolgt initial mit admin / admin (Passwort beim ersten Anmelden ändern).
3. Stork-Agent auf Kea-01 installieren & verbinden
3.1 Namensauflösung / Hostname-Eintrag sicherstellen
Damit gRPC und die TLS-Zertifikatsprüfung zwischen Stork-Server und Agent ohne SAN-Fehler (x509: cannot validate certificate...) funktionieren:
Trage auf dem Stork-Server in /etc/hosts die Management-IP von Kea-01 ein:
echo "192.168.1..11 Kea-01.holzfeind.mgmt Kea-01" >> /etc/hosts
3.2 Agent auf Kea-01 installieren
Führe als root auf Kea-01 aus:
curl -1sLf 'https://dl.cloudsmith.io/public/isc/stork/setup.deb.sh' | bash
apt update
apt install -y isc-stork-agent
3.3 Agent beim Stork-Server registrieren
Registriere den Agenten als System-Benutzer stork-agent:
su -s /bin/sh stork-agent -c 'stork-agent register --server-url http://<IP-DES-STORK-SERVERS>:8080'
Gib auf Aufforderung die Zugangsdaten des Stork-Web-Admins ein.
3.4 Agent-Dienst aktivieren
systemctl enable --now isc-stork-agent
systemctl status isc-stork-agent --no-pager
3.5 Maschine in Stork GUI freischalten
-
Öffne die Stork-GUI (
http://<IP-des-Stork-Servers>:8080). -
Navigiere zu Services → Machines → Unauthorized.
-
Klicke bei
Kea-01.holzfeind.mgmtauf Authorize. -
Unter Services → Daemons erscheint nun der Status des Kea-DHCPv4-Daemons.
4. Ziel-Subnetz über die Stork-GUI anlegen
Da der subnet_cmds-Hook auf Kea-01 geladen ist, können Subnetze jetzt direkt in der Stork-GUI ohne Kea-Neustart angelegt werden.
-
Navigiere in Stork zu DHCP → Subnets und klicke auf New Subnet.
-
Trage die Werte für dein Ziel-VLAN ein (Beispiel):
-
Subnet:
192.168.2.0/24 -
Pools:
192.168.2.100 - 192.168.2.199 -
Daemon:
Kea-01(kea-dhcp4) -
DHCP Option
routers(Option 3):192.168.2.1(OPNsense Interface-IP) -
DHCP Option
domain-name-servers(Option 6):192.168.1.53(Technitium DNS Server)
-
-
Speichere das Subnetz.
5. OPNsense DHCP Relay für das Zielnetz aktivieren
-
Lokalen DHCPv4-Server deaktivieren: In OPNsense unter Services → DHCPv4 → [Ziel-Interface] den Haken bei Enable DHCP server on interface entfernen und speichern.
-
DHCP Relay aktivieren: In OPNsense unter Services → DHCPv4 → Relay:
-
Haken bei Enable setzen.
-
Betroffenes Interface auswählen.
-
Append circuit ID aktivieren (empfohlen).
-
Destination Server: Management-IP von Kea (
192.168.1..11) eintragen.
-
-
Firewall-Regel prüfen: Stelle sicher, dass UDP-Port
67von OPNsense zur Management-IP192.168.1.11erlaubt ist.
6. Verifikation & Funktionstest
-
Schließe einen Test-Client an das Ziel-VLAN an und fordere eine IP an:
dhclient -r && dhclient -
Prüfe auf
Kea-01, ob die IP-Vergabe in der Lease-Datei verzeichnet ist:cat /var/lib/kea/kea-leases4.csv -
In der Stork-Web-GUI unter DHCP → Subnets bzw. Leases ist die vergebene Adresse ebenfalls sichtbar.