platform-docs/architecture/13-live-provisioning-boot.md

Live-Provisionierung und Boot-Modi

Status: Beschlossen Datum: 18.07.2026

Zweck dieses Dokuments

Dieses Dokument beschreibt, wie die Provisionierungs-ISO bootet, wie der automatisierte und der interaktive Ablauf sich unterscheiden, und wie der native Installer aus der Live-Umgebung heraus gestartet wird.

Es ergänzt 10-interactive-provisioning-flow.md (F-005), das den interaktiven Ablauf selbst beschreibt, um die Boot-Ebene davor.

Siehe ADR-0003 für die Entscheidung und ihre Begründung.

---

Ausgangslage

Die bisherige ISO basiert auf einer Fedora-DVD/Netinst-Struktur ohne Live-Umgebung. GRUB startet Anaconda direkt, mit einer über inst.ks= fest verdrahteten Kickstart-URL. Der gesamte in F-005 beschriebene Ablauf hat darauf keinen Einstiegspunkt.

Die neue ISO basiert stattdessen auf einem echten Live-Medium (erkennbar an /LiveOS/squashfs.img). scripts/installer.sh läuft als gewöhnliche Anwendung innerhalb dieser Live-Sitzung, mit vollem Zugriff auf Netzwerk (NetworkManager, WLAN), Bildschirm und Tastatur.

---

Boot-Ablauf

Boot
 ↓
GRUB-Menü (Countdown)
 ├── Zeitüberschreitung oder Standardeintrag
 │     ↓
 │   Live-Umgebung startet mit tuxflotte.mode=auto
 │
 └── manuelle Auswahl des zweiten Eintrags
       ↓
     Live-Umgebung startet mit tuxflotte.mode=interactive
 ↓
installer.sh liest tuxflotte.mode
 ↓
Netzwerk, Hardware, Aktivierung (wie bisher, "always"-Module)
 ↓
Moduswahl
 ├── auto
 │     ↓
 │   device.registration_status prüfen
 │     ├── existing    → Bereitstellungsvorlage automatisch wählen (is_default), Commit Point automatisch bestätigen
 │     └── registered  → Fail-Closed-Abbruch, Verweis auf interaktiven Ablauf
 │
 └── interactive
       ↓
     bisheriger F-005-Ablauf (Bereitstellungsvorlage-Auswahl, explizite Bestätigung)
 ↓
Runtime Blueprint erzeugen → Backend laden → backend_generate_config()
 ↓
backend_launch() startet den nativen Installer explizit aus der Live-Sitzung heraus

Beide Moduspfade laufen ab „Runtime Blueprint erzeugen" identisch weiter. Der Unterschied liegt ausschließlich davor: in der Frage, ob eine Bereitstellungsvorlage interaktiv gewählt und der Commit Point interaktiv bestätigt wird, oder ob beides automatisch anhand vorhandener Daten geschieht.

---

Auto-Modus-Gate

Der automatisierte Ablauf ersetzt keine Sicherheitsprüfung, sondern ersetzt nur, wer/wann die Bestätigung gibt: statt einer lokalen Benutzereingabe entscheidet ein bereits bestehender, geprüfter Zustand — eine Vorab-Freigabe, eine zentrale Freigabe, oder ein bereits bekannter Registrierungszustand.

Für ein bereits bekanntes Gerät (device.registration_status == "existing" in der Antwort von POST /api/v1/activate) läuft der automatisierte Ablauf wie bisher ohne weitere Bestätigung durch.

Für ein neues Gerät (registration_status == "registered") hängt der weitere Ablauf davon ab, ob eine aktive Enrollment Session (siehe 11-device-enrollment.md) es abdeckt:

• Mit abdeckender Enrollment Session: automatisierter Ablauf wie vorgesehen — die Vorab-Freigabe der Session genügt, kein weiterer Bestätigungsschritt nötig.
• Ohne abdeckende Enrollment Session (ADR-0008, 23.07.2026): das Gerät geht nach dem Identifikations-Handshake in einen Wartezustand über. Die destruktive Installation beginnt erst, nachdem ein Kunde über die künftige Verwaltungsoberfläche die Registrierung bestätigt und einen Workspace zugewiesen hat.

Ein unbekanntes Gerät ohne abdeckende Enrollment Session durchläuft damit weiterhin keine unbeaufsichtigte Installation ohne jede Bestätigung — nur die Quelle der Bestätigung ist im Auto-Modus jetzt zentral (Portal) statt lokal (Kiosk-Browser).

Das Fail-Closed-Prinzip aus 10-interactive-provisioning-flow.md gilt unverändert: Fehlt eine gültige Grundlage für die automatische Bestätigung (zum Beispiel eine unerwartete oder unlesbare Serverantwort, oder ein Wartezustand, der nie in eine Freigabe übergeht), bricht der Ablauf ab beziehungsweise verharrt im Wartezustand, statt ersatzweise eine Bestätigung anzunehmen.

---

Konsequenz für die Geräteregistrierung

Wer ein Gerät registriert, akzeptiert damit, dass dieses Gerät künftig ohne erneute interaktive Rückfrage automatisiert neu installiert werden kann, solange es über seinen Hardware-Fingerprint als bereits registriert erkannt wird.

Dies wird bei der Geräteregistrierung ausdrücklich kommuniziert (siehe 11-device-enrollment.md).

---

Nativer Installer aus der Live-Sitzung

Der native Installer wird nicht mehr über einen boot-zeitlichen Parameter gestartet.

Stattdessen ruft backend_launch() (siehe 06-backend-api.md) den nativen Installer explizit auf, mit der zuvor von backend_generate_config() erzeugten, lokal vorliegenden Konfiguration.

Die statische Kickstart-Datei sowie ihr Server-Endpoint (GET /installers/fedora-workstation/ks.cfg) entfallen damit.

---

WLAN-Zugangsdaten

Zwei getrennte Anwendungsfälle:

WLAN für die Live-Provisionierungsumgebung. Ohne Netzwerk ist der Provisioning-Server nicht erreichbar. Zugangsdaten für dieses Netzwerk müssen deshalb bereits im ISO-Build hinterlegt sein, nicht dynamisch vom Server geladen werden.

Konkretes Modell (entschieden 21.07.2026): Der Kunde hinterlegt im Kundenprofil eine Anforderung „Autoprovisionierung" samt den WLAN-Zugangsdaten für die Live-Provisionierungsumgebung, und löst darüber die Erzeugung einer für ihn personalisierten ISO aus (Self-Service, Download). Die Zugangsdaten werden dabei als NetworkManager-Verbindungsprofil zur Build-Zeit ins Live-Payload aufgenommen (analog zum bestehenden Mechanismus für etc/sudoers.d/90-tuxflotte und etc/xdg/autostart/tuxflotte-installer.desktop, siehe „Autostart von installer.sh" unten) — funktioniert sofort ab dem ersten Gerät, nicht erst ab dem zweiten.

Da die ISO für diesen Fall ohnehin personalisiert gebaut wird, wird bei dieser Gelegenheit auch das Volume-Label individualisiert (statt des sonst festen TUXFLOTTE, siehe „Konkrete Umsetzung" unten) — abgeleitet aus einer bestehenden Organisations-Kennung (z.B. Org-Kurzname/-Slug), nicht aus einem Freitextfeld, da die ISO9660-Volume-ID auf Großbuchstaben/Ziffern/Unterstrich und 32 Zeichen beschränkt ist und ein frei eingegebener Name eigene Sanitisierung bräuchte. Die GRUB-Configs und der CDLABEL-Kernel-Parameter werden für diesen Build entsprechend mitgeneriert, nicht nur die WLAN-Datei.

Verworfen wurde die Alternative, WLAN-Zugangsdaten interaktiv am ersten Gerät einzugeben und auf dem Stick selbst persistent zu machen (damit ab dem zweiten Gerät automatisch verbunden wird). Das hätte einen beschreibbaren, boot-übergreifend persistenten Bereich auf dem Stick vorausgesetzt (z.B. über dracut-Live-Overlay oder eine eigene Datenpartition) — eine reine ISO-Datei, roh auf einen Stick geschrieben (dd), bietet das nicht von selbst. Dafür wäre zusätzlich ein plattformübergreifendes Schreibwerkzeug nötig gewesen, das diesen Platz beim Erstellen des Sticks reserviert. Der Aufwand steht in keinem Verhältnis zum Nutzen, zumal dieser Ansatz ohnehin voraussetzt, dass der Kunde vorher durchs Profil geht — das serverseitige Modell liefert die bessere UX (automatisch ab Gerät 1) bei deutlich weniger Infrastruktur.

WLAN für das installierte Zielsystem. Dies ist eine dauerhafte, organisationsweite Vorgabe und gehört zum noch unspezifizierten Network Profile-Modell der Organization (siehe 09-data-model-v1.md). Die Anwendung erfolgt wie andere organisationsweite Vorgaben, nicht als Teil der Provisionierungs-Bootphase.

---

Konkrete Umsetzung (Stand 18.07.2026)

Als konkrete Basis wird eine Fedora-Cinnamon-Live-ISO verwendet, nicht Fedora Workstation Live. Für die Zwecke dieses Dokuments ist das austauschbar — entscheidend ist ausschließlich das Vorhandensein von /LiveOS/squashfs.img, nicht die konkrete Desktop-Umgebung.

Für eine spätere ISO-Überarbeitung festgehalten (21.07.2026): Der oben beschriebene EROFS-Bug ist keine allgemeine Live-Medien-Eigenschaft, sondern eine Fedora-spezifische, noch laufende Umstellung — offizieller Fedora-Change-Proposal ab Fedora 42 ("Switch to EROFS for Live Media"), getrieben von RHEL-10-Angleichung (RHEL 10 nutzt EROFS für seine Live-Medien). Ubuntus Live-/Install-Medien (casper/live-build) verwenden weiterhin klassisches SquashFS über mksquashfs/squashfs-tools — dasselbe Tooling, das dieses Projekt bereits für das Chromium-SquashFS-Experiment (ADR-0005, mittlerweile verworfen) problemlos genutzt hat. Eine Ubuntu-basierte Live-ISO als Basis wäre also vom EROFS-Bug gar nicht betroffen, bräuchte den Dracut-Hook-Umweg für das Installer-Payload aber vermutlich trotzdem nicht auf dieselbe Art zu umgehen, sondern könnte direkt im Payload arbeiten. Das ist kein Beschluss, nur ein für eine künftige ISO-Überarbeitung festgehaltener Prüfpunkt — mit dem Wechsel wäre auch anderes Branding-/Backend-Anpassungs-Ökosystem verbunden, nicht nur ein Filesystem-Detail.

Die gebaute ISO trägt ein eigenes Volume-Label TUXFLOTTE (per -volid in scripts/build.sh, create_iso()), statt des ursprünglichen Fedora-Labels der Quell-ISO. Reines Branding (21.07.2026 entschieden) — es wird aktuell von genau einem im Umlauf befindlichen USB-Stick ausgegangen, es gibt keine Anforderung, mehrere Sticks über das Label zu unterscheiden. Sollte sich das ändern, ist die Anpassung unkompliziert. Das Label ist funktional relevant, nicht nur kosmetisch: GRUB (search -l 'TUXFLOTTE') und der Kernel-Cmdline-Parameter root=live:CDLABEL=TUXFLOTTE lösen darüber beim Boot das Live-Root auf — beide Werte müssen exakt mit dem -volid übereinstimmen.

Ein eigenes, schlankeres Live-System anstelle des Fedora-Live-Images wurde geprüft und verworfen (21.07.2026): Der Aufwand, die dahinterliegende Live-Boot-Infrastruktur selbst zu pflegen (Kernel-/Initramfs-Kompatibilität, Firmware, Hardware-Erkennung über ein breites Gerätespektrum), steht in keinem Verhältnis zum Nutzen — zumal die bekannten Reibungspunkte (EROFS-Extraktionsfehler, Chromium-Nachinstallation, ISO-Größe) bereits mit kleinen, gut verstandenen Maßnahmen gelöst beziehungsweise geplant sind. Revisitieren, falls ISO-Größe/Boot-Zeit zu einem gemessenen operativen Problem wird oder eine dauerhafte Festlegung auf eine dann als Wartungslast spürbare Live-Basis ansteht.

Das in der Boot-Ablauf-Grafik oben genannte Kernel-Cmdline-Flag heißt konkret tuxflotte.mode und wird als tuxflotte.mode=auto beziehungsweise tuxflotte.mode=interactive an den Kernel übergeben, zusätzlich zu den vom Live-Medium ohnehin benötigten Parametern (root=live:CDLABEL=TUXFLOTTE rd.live.image) sowie vconsole.keymap=de. installer.sh soll den gewählten Modus zur Laufzeit aus /proc/cmdline lesen (siehe „Noch nicht umgesetzt" unten) — aktuell durchläuft es unabhängig vom Flag immer den vollständigen interaktiven Ablauf.

Das GRUB-Menü verwendet einen Countdown von 10 Sekunden; der Auto-Eintrag ist Index 0 und damit Standardauswahl. Ein dritter Menüpunkt zum Booten des bereits installierten lokalen Systems bleibt erhalten (vormals in 01-layered-provisioning.md als Anforderung an das Bootmenü genannt).

scripts/build.sh und scripts/extract.sh extrahieren die Quell-ISO über xorriso -osirrox statt über einen Loop-Mount und benötigen dadurch keine Root-Rechte mehr für den Build selbst.

Das Menü verwendet ein Farbschema in Markenblau (color_normal=blue/white, color_highlight=white/blue, angelehnt an rgb(52,101,164) aus pics/tuxflotte-beschriftet-schatten.svg). Das Logo selbst lässt sich darin nicht darstellen: Klassisches gfxterm malt bei jeder Zeichenzelle einen deckenden Hintergrund, wodurch ein background_image vollständig verdeckt wird — geprüft durch tatsächliches Booten der Variante mit Logo in QEMU. Ein sichtbares Logo bräuchte die GRUB-Theme-Engine (gfxmenu/theme.txt), die diese Live-ISO nicht mitbringt (leeres /boot/grub2/themes, kein x86_64-efi-Modulverzeichnis). Das Logo ist deshalb für den Plymouth-Bootsplash oder den Live-Desktop-Hintergrund vorgesehen, nicht für das GRUB-Menü.

Autostart von installer.sh

Das Installer-Payload wird nicht in /LiveOS/squashfs.img integriert — dieses Image ist trotz des Namens EROFS statt SquashFS, und die einzige verfügbare erofs-utils-Tooling-Version (auch frisch aus dem Quellcode gebaut) extrahiert das gepackte/fragmentierte Inode dieses konkreten Images fehlerhaft.

Der Fehler wurde zusätzlich direkt auf einem nativen Fedora 44 nachgestellt (die Build-Umgebung selbst ist Debian Bookworm) und trat dort identisch auf. Das bestätigt, dass es sich um einen echten erofs-utils-Bug handelt und nicht um eine Bookworm-spezifische Tooling-Lücke.

Präzisiert (21.07.2026): Der Fehler ist kein reines Versions-Nachhinken des Debian-Bookworm-Pakets (erofs-utils 1.5-1). Ein frischer Build direkt vom erofs-utils-dev-Branch (Commit vom 14.07.2026, Version 1.9.2) zeigt denselben Fehler gegen dieselbe squashfs.img. Ursache, per Quellcode nachvollzogen (fsck/main.c): Das Image nutzt EROFS' Fragments-Feature — eine spezielle, versteckte „Packed Inode" (hier nid 37), die Tail-Daten kleiner Dateien fürs gesamte Dateisystem gebündelt speichert. fsck.erofs --extract verarbeitet den Verzeichnisbaum zunächst korrekt vollständig (bestätigt per dump.erofs -S: 271.200 Dateien lesbar, keine Auffälligkeiten), behandelt diese eine Packed Inode aber in einem separaten Schritt danach — und dabei kollidiert die interne Pfadverwaltung mit dem Extraktions-Wurzelverzeichnis: im Test wurde der bereits vollständig extrahierte Verzeichnisbaum am Ende durch eine einzelne ca. 4,3-GB-Rohdatei gleichen Namens überschrieben. Der Fehler ist damit nicht nur ein sauberer Abbruch, sondern im Fehlerfall aktiv destruktiv gegenüber bereits extrahierten Daten.

Eine gezielte Suche (GitHub, linux-erofs-Mailingliste) fand keinen bestehenden Bugreport genau für diese Packed-Inode/Extract-Pfad-Kollision, wohl aber eine dokumentierte Historie anderer Pfad-Handling-Bugs im selben --extract-Codepfad (u.a. bereits gefixte Heap-Overflow- und Segfault-Fälle bei tiefen/langen Pfaden) — die Stelle gilt im Projekt selbst als bekanntermaßen fragil. Es gibt keinen erkennbaren Zeithorizont für einen Fix. Die gewählte Umgehung über den Dracut-Hook (Image gar nicht erst anfassen) bleibt damit nicht nur der pragmatische, sondern der einzig belastbare Ansatz — Extraktion ist für dieses Image nachweislich unzuverlässig, nicht nur unbequem.

Stattdessen nutzt der Build den offiziellen Dracut-Hook 20-apply-live-updates.sh (var/lib/dracut/hooks/pre-pivot/): Ein updates/-Verzeichnis direkt auf dem Boot-Medium (nicht im komprimierten Image) wird von Dracut automatisch vollständig in das Live-Root kopiert, bevor die Live-Sitzung startet — ganz ohne Image-Remastering.

scripts/build.sh (prepare_updates()) baut dieses Verzeichnis zur Build-Zeit aus scripts/, backends/, config/ (unter /opt/tuxflotte) sowie live-updates/etc/ zusammen:

• etc/xdg/autostart/tuxflotte-installer.desktop — startet beim Anmelden von liveuser automatisch Epiphany im Application-Mode (epiphany --application-mode --profile=/home/liveuser/.local/share/tuxflotte-kiosk, siehe ADR-0004/ADR-0006), der die Kiosk-Oberfläche unter /opt/tuxflotte/kiosk/index.html lädt. Adressleiste und Fenstermenü bleiben dabei sichtbar — bewusst hingenommen (ADR-0006), da der angezeigte Inhalt zentral vom Provisioning Server kommt und nicht sensibel ist.
• etc/sudoers.d/90-tuxflotte — liveuser erhält passwortloses sudo (angemessen für diese Wegwerf-Live-Umgebung).

Epiphany ist auf dem Fedora-Cinnamon-Live-Image bereits vorhanden, es sind keine zusätzlichen Build-Schritte nötig. Zwischen ADR-0004 und ADR-0006 wurde Chromium ausführlich evaluiert und wieder verworfen (vier verschiedene reale Boot-Fehlschläge in Folge — /etc/passwd-Überschreibung, Kernel Panic durch /usr-Überschreibung, minutenlange Bootzeit durch hunderttausende lose Dateien, dann ein /proc/self/exe-Ressourcenauflösungsfehler) — Details, Begründung und die dabei erarbeiteten, einzeln funktionierenden Techniken (Isolation unter /opt, Loader-Relokation, SquashFS-Verpackung) stehen in ADR-0005 und ADR-0006, falls das je wieder aufgegriffen wird.

xorriso übernimmt beim -map die Berechtigungen der lokalen Quelldateien in die ISO. Da liveusers uid (1000) sonst mitkopiert würde und sudo root-fremde sudoers.d-Dateien verweigert, setzt der Build -chown_r 0 /updates -- -chgrp_r 0 /updates -- explizit auf das gesamte updates/-Verzeichnis — ganz ohne lokales root beim Bauen.

Verifiziert per vollständigem Live-Boot in Proxmox (siehe roadmap/milestones.md, 2026-07-20): Autostart-Terminal öffnete sich zuverlässig, installer.sh durchlief alle Module bis zum sauberen Exit. Diese Verifikation stammt aus der Zeit vor dem Kiosk-UI-Umbau (Terminal statt Epiphany) — der Epiphany-Autostart selbst ist noch nicht mit dem aktuellen Build (inkl. TUXFLOTTE-Label, WLAN-Vorbereitung) per echtem Boot re-verifiziert.

Noch nicht umgesetzt: installer.sh liest tuxflotte.mode noch nicht aus und durchläuft deshalb immer den vollständigen interaktiven Ablauf, unabhängig vom gewählten Bootmenüeintrag. backend_launch()/backend_postinstall() bleiben Phase-1-Stubs — der native Installer wird noch nicht tatsächlich gestartet.

---

Zusammenfassung

Die Live-ISO ersetzt das direkte Booten in Anaconda durch eine vorgeschaltete, frei gestaltbare Live-Sitzung, in der installer.sh läuft.

Ein Bootmenü mit Countdown unterscheidet zwischen automatisiertem und interaktivem Ablauf; beide münden ab der Runtime-Blueprint-Erzeugung in denselben Codepfad.

Automatisierung ersetzt keine Sicherheitsprüfung, sondern bindet die Bestätigung an eine bereits bestehende, geprüfte Gerätezuordnung statt an eine Benutzereingabe.