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

  1. Öffne die Stork-GUI (http://<IP-des-Stork-Servers>:8080).

  2. Navigiere zu Services → Machines → Unauthorized.

  3. Klicke bei Kea-01.holzfeind.mgmt auf Authorize.

  4. 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.

  1. Navigiere in Stork zu DHCP → Subnets und klicke auf New Subnet.

  2. 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)

  3. Speichere das Subnetz.

5. OPNsense DHCP Relay für das Zielnetz aktivieren

  1. Lokalen DHCPv4-Server deaktivieren: In OPNsense unter Services → DHCPv4 → [Ziel-Interface] den Haken bei Enable DHCP server on interface entfernen und speichern.

  2. 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.

  3. Firewall-Regel prüfen: Stelle sicher, dass UDP-Port 67 von OPNsense zur Management-IP 192.168.1.11 erlaubt ist.

6. Verifikation & Funktionstest

  1. Schließe einen Test-Client an das Ziel-VLAN an und fordere eine IP an:

    dhclient -r && dhclient
    
  2. Prüfe auf Kea-01, ob die IP-Vergabe in der Lease-Datei verzeichnet ist:

    cat /var/lib/kea/kea-leases4.csv
    
  3. In der Stork-Web-GUI unter DHCP → Subnets bzw. Leases ist die vergebene Adresse ebenfalls sichtbar.