DDI/docs/INSTALL.md

Installation

scripts/install.sh richtet die drei Rollen der DDI-Suite auf einem Linux-Host ein: den Management-Server (server), den DNS-Agent mit BIND (agent-dns) und den DHCP-Agent mit Kea (agent-dhcp). Die Rollen lassen sich beliebig auf Hosts verteilen oder kombinieren. Entscheidungen dazu: ADR 0024.

Voraussetzungen

Systeme	Debian 12 und 13, Ubuntu 22.04 und 24.04 LTS, Rocky Linux/AlmaLinux/RHEL 9
Architekturen	amd64 (x86_64), arm64 (aarch64, z. B. Raspberry Pi 4/5 mit 64-Bit-System)
Rechte	root (sudo)
Init-System	systemd
Netz	Zugriff auf die Paketquellen der Distribution, auf git.beugsiud.de (Release-Artefakte) und für agent-dhcp auf dl.cloudsmith.io (ISC-Kea-Pakete); der Server prüft https://license.beugsiud.de (nur Warnung)
Zeit	synchronisierte Uhr (NTP), sonst warnt der Installer

Richtwerte stehen in docs/SYSTEM-REQUIREMENTS.md; der Installer prüft vorab (Abschnitt 3 dort, Schwellen als Variablen oben im Skript). Mehrere Rollen auf einem Host: RAM und Platte addieren sich, bei CPU zählt das Maximum.

Prüfung	Warnung	Abbruch
CPU-Kerne	Server < 2	–
RAM	Server < 3,5 GiB, je Agent < 900 MiB	Server < 1,8 GiB, je Agent < 450 MiB
Freier Platz im Dateisystem von /var/lib	Server < 20 GiB, je Agent < 5 GiB	Server < 4 GiB, je Agent < 1 GiB
Freier Platz für /usr/local/bin	–	< 200 MiB
Ports	8001/tcp (Kea-HA) belegt; 53 nur von systemd-resolved auf 127.0.0.53 belegt	8443/8444 belegt (nicht vom Server), 53 belegt (nicht von named), 67/udp belegt (nicht von kea-dhcp4)
Versionen	BIND < 9.18, Kea < 3.0 (keine HA)	PostgreSQL < 13, Kea < 2.6
Netz	Lizenzserver nicht erreichbar (Server), Agent-API des Servers nicht erreichbar (Agents mit --server)	ISC-Repository nicht erreichbar (--kea-source isc)
Zeit	Uhr nicht per NTP synchronisiert	–

--force macht aus jedem Abbruch eine Warnung; nicht unterstützte Systeme und Architekturen bleiben ein Abbruch.

Herunterladen, prüfen, ausführen

Das Skript bitte nicht per curl … | sudo bash ausführen, sondern erst herunterladen und lesen:

curl -fsSLO https://git.beugsiud.de/beug.k/DDI/raw/branch/main/scripts/install.sh
less install.sh              # ansehen, was es tut
chmod +x install.sh
sudo ./install.sh --role server --dry-run   # zeigt nur, was passieren würde
sudo ./install.sh --role server

Für eine feste Version das Skript aus dem Tag statt aus main laden, z. B. https://git.beugsiud.de/beug.k/DDI/raw/tag/v0.7.0/scripts/install.sh, und --version v0.7.0 angeben.

Ohne --version installiert das Skript das neueste Release (/api/v1/repos/beug.k/DDI/releases/latest). Es lädt die Tarballs der gewählten Rollen und SHA256SUMS von https://git.beugsiud.de/beug.k/DDI/releases/download/<tag>/ und prüft jede Prüfsumme. Ist im Skript ein öffentlicher Signaturschlüssel hinterlegt (RELEASE_PUBLIC_KEY_PEM), muss außerdem die Ed25519-Signatur SHA256SUMS.sig gültig sein; solange die Releases nicht signiert werden, weist das Skript darauf hin, dass nur die Prüfsummen geprüft wurden.

Typischer Ablauf

1. Server installieren:

   sudo ./install.sh --role server --public-url https://ddi.example.org:8443
   

   Am Ende stehen die URL der Oberfläche und ein einmaliges Administrator-Passwort (Benutzer admin). Es steht nur auf dem Bildschirm, nicht im Log, und muss bei der ersten Anmeldung geändert werden. Interaktiv fragt der Installer nach einem Lizenzschlüssel (optional, Eingabe auch später in der Oberfläche möglich).

2. Agent registrieren: In der Oberfläche unter Agents ein Enrollment-Token für die Rolle anlegen. Die Oberfläche zeigt zwei gleichwertige Befehle: den Installer-Aufruf für einen neuen Host und ddi-agent-dns enroll --server <host>:8444 --token <token> --ca-hash sha256:<hex> für einen Host, auf dem der Agent schon installiert ist. Auf einem neuen Host:

   sudo ./install.sh --role agent-dns --server ddi.example.org:8444 \
     --token <token> --ca-hash sha256:<hex>
   

   Für den DHCP-Agent entsprechend --role agent-dhcp mit einem Token der Rolle dhcp. Pro Aufruf wird genau ein Agent registriert.

   Ohne Token wird der Agent installiert und sein Dienst eingeschaltet; systemd startet ihn erst, wenn eine Identität vorhanden ist (ConditionPathExists). Registrieren lässt er sich danach auf zwei Wegen: den Installer erneut mit --server --token --ca-hash aufrufen oder den enroll-Befehl aus der Oberfläche als root ausführen. Dieser übergibt die Identität an den Dienstbenutzer (bind bzw. _kea) und startet den Dienst (systemctl enable --now; mit --no-start nicht). Ein Agent, der mit einer älteren Version von Hand registriert wurde und nicht läuft, wird durch install.sh --upgrade repariert.

3. Prüfen: In der Oberfläche erscheinen die Agents als verbunden; nach dem ersten Ausrollen liefern BIND und Kea die Konfiguration.

Alle drei Rollen auf einem Host: sudo ./install.sh --role server,agent-dns,agent-dhcp, danach die Agents wie in Schritt 2 registrieren (Server-Adresse ist der eigene Hostname).

Optionen

Option	Bedeutung
--role <rolle>	server, agent-dns, agent-dhcp; mehrfach oder mit Komma getrennt
--version <tag>	Release, Standard: neuestes
--from-dir <verzeichnis>	Release-Artefakte (Tarballs, SHA256SUMS, ggf. SHA256SUMS.sig) aus einem Verzeichnis statt Download (offline, Tests)
--git-token <token>	Zugriffstoken, falls Releases eine Anmeldung brauchen (alternativ DDI_GIT_TOKEN); wird nie geloggt
--server <host:port>, --token <token>, --ca-hash sha256:<hex>	Registrierung eines Agents (Werte aus dem Enrollment-Befehl der Oberfläche)
--server-name <name>	TLS-Name des Servers, falls er vom Host in --server abweicht (steht dann im Befehl der Oberfläche)
--kea-source isc|distro	Kea aus dem ISC-Repository (Standard, Kea 3.x mit HA) oder aus der Distribution (ohne HA, siehe unten)
--public-url <url>	URL der Oberfläche, Standard https://<fqdn>:8443; ihr Hostname ist auch die Agent-API-Adresse (<host>:8444)
--tls-cert <datei>, --tls-key <datei>	eigenes Zertifikat (PEM, mit Kette) und Schlüssel; ohne erzeugt der Installer ein selbstsigniertes Zertifikat
--license-key-file <datei>	Lizenzschlüssel aktivieren; Fehler (ungültig, Lizenzserver nicht erreichbar) sind nur Warnungen
--upgrade	Binaries und Units ersetzen, Dienste neu starten
--uninstall	Rollen entfernen, Konfiguration und Daten bleiben
--purge	mit --uninstall: auch Konfiguration, Daten, Datenbank, Schlüssel und Dienstbenutzer löschen
--dry-run	nur anzeigen, nichts ändern
--non-interactive	nie nachfragen (zum Ändern ist dann --yes nötig)
--yes	Rückfrage mit Ja beantworten
--force	Vorabprüfung nur warnen lassen

Umgebung: DDI_RELEASE_BASE_URL ersetzt die Download-Adresse (<tag> darin wird durch die Version ersetzt; ohne <tag> ist es das Verzeichnis der Artefakte), DDI_GIT_TOKEN.

Was wird wo installiert

Gemeinsam für alle Rollen:

Pfad	Inhalt
/usr/local/bin/ddi-server, ddi-agent-dns, ddi-agent-dhcp	Binaries
/etc/systemd/system/<binary>.service	systemd-Units (gehärtet, siehe ADR 0024)
/etc/ddi-suite/	Konfiguration (Verzeichnis 0755, Dateien einzeln geschützt)
/var/lib/ddi-suite/	Zustand (server/, agent-dns/, agent-dhcp/)
/var/log/ddi-suite/install.log	Protokoll des Installers (ohne Tokens, Schlüssel und Passwörter)
/usr/local/share/doc/ddi-suite/	Lizenztexte

Server

Pakete	PostgreSQL der Distribution (Debian/Ubuntu postgresql, EL9 postgresql-server aus dem Modul-Stream ≥ 15, höchster verfügbarer), openssl, curl
Benutzer	Systembenutzer ddi-suite
Datenbank	Rolle und Datenbank ddi-suite, Anmeldung per Peer-Authentifizierung über den Unix-Socket (kein Passwort)
/etc/ddi-suite/server.yaml	Konfiguration (0640 root:ddi-suite)
/etc/ddi-suite/master.key	Master-Key (0400 ddi-suite) – sichern, ohne ihn sind verschlüsselte Daten verloren
/etc/ddi-suite/tls/	TLS-Zertifikat und Schlüssel der Oberfläche
Ports	8443/tcp (Oberfläche, API), 8444/tcp (Agent-API)

DNS-Agent (läuft als BIND-Benutzer bind bzw. named)

	Debian/Ubuntu	EL9
Pakete	bind9, bind9-utils, bind9-dnsutils	bind9.18, bind9.18-utils (sonst bind, Warnung unter 9.18)
BIND-Konfiguration	/etc/bind/named.conf, named.conf.options	/etc/named.conf
Dateien des Agents	/etc/bind/ddi-suite/	/etc/named/ddi-suite/
Zonendateien	/var/lib/bind/ddi-suite/ (inkl. secondary/)	ebenso, SELinux-Typ named_cache_t
Agent-Konfiguration	/etc/ddi-suite/agent-dns.yaml	ebenso

Der Installer fügt in named.conf einen markierten Block ein (// BEGIN ddi-suite … bis // END ddi-suite …), der ddi-suite-keys.conf und ddi-suite.conf einbindet, und im options-Block einen zweiten mit ddi-suite-options.conf. Anweisungen der Distribution, die der Generator selbst setzt (recursion, allow-recursion, forwarders, allow-transfer), sowie listen-on, listen-on-v6 und allow-query, die BIND auf localhost beschränken (Standard auf EL9), werden mit dem Präfix //ddi-suite-disabled: auskommentiert. Beim Deinstallieren werden die Blöcke entfernt und die Zeilen wiederhergestellt. Danach prüft named-checkconf die Konfiguration; scheitert sie, stellt der Installer die Originale wieder her.

DHCP-Agent (läuft als Kea-Benutzer _kea bzw. kea)

Pakete	isc-kea-dhcp4, isc-kea-hooks aus dem ISC-Repository isc/kea-3-2 (Cloudsmith). Der Schlüssel des Repositorys wird nur mit dem Fingerabdruck 360D0B03DFE219DB0F9FEA4C720DD962343B440F akzeptiert. Auf EL9 wird zusätzlich EPEL aktiviert (die ISC-Pakete brauchen log4cplus).
Dienst	isc-kea-dhcp4-server (Debian/Ubuntu) bzw. kea-dhcp4 (EL9)
Drop-in /etc/systemd/system/<kea-unit>.service.d/10-ddi-suite.conf	setzt KEA_CONTROL_SOCKET_DIR=/run/kea: Die ISC-Pakete sind mit /var/run/kea übersetzt und vergleichen Pfade wörtlich, der Generator verwendet /run/kea. Dieselbe Variable bekommt der DHCP-Agent (für kea-dhcp4 -t).
/etc/kea/kea-dhcp4.conf	Startkonfiguration ohne Subnetze mit Control-Socket /run/kea/kea4-ctrl-socket, Lease-Datei /var/lib/kea/kea-leases4.csv und Hook lease_cmds; das Original bleibt als kea-dhcp4.conf.ddi-suite-orig erhalten. Der Agent überschreibt die Datei mit jeder Revision.
HA-Dateien	/etc/kea/ddi-suite-ha-user, ddi-suite-ha-password (schreibt der Agent, wenn ein HA-Cluster konfiguriert ist)
Agent-Konfiguration	/etc/ddi-suite/agent-dhcp.yaml

Mit --kea-source distro kommt Kea aus der Distribution (Debian 12: 2.2, Debian 13: 2.6, Ubuntu 22.04: 2.0, Ubuntu 24.04: 2.4). Diese Versionen können keine HA mit Dateien für Benutzer und Passwort; außerdem schreibt der Generator Hook-Bibliotheken ohne Pfad, was erst Kea 3.x auflöst. Der Weg ist für Hosts ohne Zugang zu Cloudsmith gedacht und nicht Teil der CI-Tests.

Die Agents laufen nicht als root, sondern als Benutzer des Dienstes, den sie verwalten (Drop-in /etc/systemd/system/<binary>.service.d/10-user.conf). Zonen-Verzeichnis, Kea-Konfiguration und Pfade entsprechen den Standard-Einstellungen des Generators auf dem Server; deshalb lassen sich Agents verschiedener Distributionen in einem Cluster mischen.

Erneut ausführen, Upgrade, Deinstallation

• Erneut ausführen ist sicher: Vorhandene Konfiguration, Master-Key, Datenbank und Agent-Identität werden nie überschrieben. Ein zweiter Lauf mit denselben Optionen meldet nothing to change (0 changes). Weicht ein installiertes Binary vom Release ab, bleibt es mit einer Warnung stehen.
• Upgrade: sudo ./install.sh --upgrade (ohne --role für alle installierten Rollen, optional --version). Ersetzt Binaries und Units, startet die Dienste neu; Datenbankmigrationen laufen beim Serverstart. Vorher Datenbank und /etc/ddi-suite/master.key sichern.
• Deinstallation: sudo ./install.sh --uninstall stoppt und entfernt Dienste, Units und Binaries und nimmt die Einbindung aus named.conf heraus. Konfiguration, Zustand, Zonendateien, Kea-Konfiguration, Datenbank und Master-Key bleiben erhalten; BIND, Kea und PostgreSQL laufen weiter.
• Vollständig entfernen: sudo ./install.sh --uninstall --purge löscht zusätzlich /etc/ddi-suite, /var/lib/ddi-suite, die Datenbank ddi-suite samt Rolle, den Benutzer ddi-suite, die Zonendateien, die Dateien des DNS-Agents unter /etc/bind bzw. /etc/named und stellt die ursprüngliche kea-dhcp4.conf wieder her. Das geht auch nach einem einfachen --uninstall. Pakete und das ISC-Repository bleiben installiert.

Fehlerfälle

• Bricht ein Lauf ab, entfernt der Installer die in diesem Lauf angelegten Dateien, Verzeichnisse, Benutzer und die neu angelegte Datenbank und stellt geänderte Dateien wieder her; installierte Pakete bleiben. Details stehen in /var/log/ddi-suite/install.log.
• Dienste: systemctl status ddi-server ddi-agent-dns ddi-agent-dhcp, Logs mit journalctl -u <dienst>, Zustand eines Agents mit sudo -u bind ddi-agent-dns status (bzw. als _kea/kea für ddi-agent-dhcp).
• Ein selbstsigniertes Zertifikat lässt sich später ersetzen: Dateien in /etc/ddi-suite/tls/ austauschen (Schlüssel 0640 root:ddi-suite) und systemctl restart ddi-server.