LINBO Patchless

Automatische, modellspezifische Windows-Treiberintegration für linuxmuster.net und linuxmuster-linbo7 – ohne Änderung am LINBO-Kern.

Das Projekt nutzt den nativen <image>.driverpostsync-Hook von LINBO. Beim Sync lädt der Client zuerst nur die kleinen match.conf-Dateien aller dem Image zugeordneten Hardwareprofile. Er gleicht Hersteller und Modell mit seiner lokalen DMI-Information ab und lädt anschließend ausschließlich die vollständig passenden Treiberpakete nach C:\Drivers\LINBO. Beliebig viele Hardwareprofile können dasselbe Golden Image versorgen. Beim nächsten Windows-Start installiert ein einmalig im Golden Image vorbereiteter Scheduled Task alle gefundenen INF-Treiber mit pnputil als SYSTEM.

Das Projekt ist noch jung. Vor dem Einsatz in produktiven Schulen sollten Backup, Testimage und ein gestufter Rollout eingeplant werden.

Schnellstart: installieren und nutzen

Unterstützt werden linuxmuster.net 7.3 auf Ubuntu 24.04 und linuxmuster.net 7.4 auf Ubuntu 26.04, jeweils auf amd64 und mit linuxmuster-linbo7 >= 4.3.33-0. Die fertige .deb liegt unter GitHub Releases, nicht unter „Packages“ und nicht im Quellcode-ZIP. Sie wird direkt auf dem linuxmuster-Server mit APT installiert. apt update ist wichtig, damit APT bei Bedarf gleichzeitig eine neuere offizielle LINBO-Version auswählen kann:

sudo apt update
apt-cache policy linuxmuster-linbo7
sudo apt install ./linbo-patchless_1.1.2+lm73.1_amd64.deb
systemctl status linbo-patchless --no-pager

Ist auf einem 7.3-Server noch linuxmuster-linbo7 < 4.3.33-0 installiert, aktualisiert APT dieses Paket aus dem bereits eingerichteten offiziellen linuxmuster.net-Repository, sofern dort eine passende Version angeboten wird. Die Abhängigkeit darf nicht mit --force-depends umgangen werden, weil erst LINBO 4.3.33 den benötigten nativen .driverpostsync-Hook bereitstellt.

Bei einer frischen Installation erkennt das Paket die interne Server-IP und richtet den Dienst automatisch ein. Danach im Admin-Netz http://<server-ip>:3001/ öffnen, beispielsweise http://10.0.0.14:3001/. Die Beispiel-IP ist nicht fest programmiert.

Für den ersten produktiven Durchlauf:

1. In Windows das Golden Image starten, in der Patchless-Oberfläche Install-LinboPatchlessTask.ps1 herunterladen und einmal in einer als Administrator gestarteten PowerShell ausführen:

   Set-ExecutionPolicy -Scope Process Bypass
   .\Install-LinboPatchlessTask.ps1

2. Diese Windows-Änderung anschließend wie gewohnt in das LINBO-Golden-Image übernehmen. Dieser Schritt ist nur einmal pro Image nötig; das Skript installiert noch keine Treiber.

3. In Patchless „Neues Profil“ wählen und das gewünschte, aus den LINBO-Inventaren gruppierte Hardwaremodell auswählen.

4. Ein Treiberpaket als ZIP, 7z oder EXE hochladen, match.conf prüfen und das Profil dem gewünschten Windows-Image zuweisen. Für weitere Hardwareklassen die Schritte 3 und 4 wiederholen und jeweils dasselbe Image wählen.

5. Auf einem Testclient in LINBO „Sync + Start“ ausführen. Beim Sync werden zuerst nur die kleinen Matchregeln und danach ausschließlich das passende Treiberpaket übertragen. Der vorbereitete SYSTEM-Task übernimmt passende signierte INF-Treiber beim Windows-Start automatisch mit pnputil.

6. Das Ergebnis im Windows-Gerätemanager und in C:\ProgramData\LINBO-Patchless\driver-install.log prüfen. Der LINBO-Teil protokolliert zusätzlich nach /cache/linbo-driverpostsync.log. Fordert Windows einen Neustart an, diesen einmal durchführen. Danach sollte Get-ScheduledTaskInfo -TaskName LINBO-Patchless-Driver-Install für den letzten Tasklauf LastTaskResult : 0 melden.

Spätere Treiberpakete werden nur noch in der Weboberfläche aktualisiert. Das PowerShell-Skript muss nicht für jeden Client oder jedes Paket erneut laufen. Bei einem Programmupdate wird das neue .deb wieder mit apt install ./... installiert; Profile und Hostkonfiguration bleiben erhalten.

Funktionsumfang

• vorhandene LINBO-Inventare aus /var/log/linuxmuster/linbo/<hostname>_hwinfo.gz als einzige Hardwarequelle
• DMI-, PCI- und USB-Erkennung samt Windows-Hardware-IDs
• keine direkte Verbindung von Patchless zu LINBO-Clients und keine Schlüssel-Injektion in linbofs
• Treiberprofile mit match.conf, Datei-Upload und ZIP-/7z-/EXE-Extraktion
• mehrere Hardwareprofile pro Image mit DMI-Match vor dem großen Pakettransfer
• Image-Zuweisung und automatische, atomische .driverpostsync-Generierung
• persistenter SYSTEM-Startup-Task mit protokolliertem, wiederholbarem Installer
• Bereinigung alter Client-Caches, Treiberziele und alter RunOnce-Einträge
• an die erkannte interne Server-IP oder ersatzweise localhost gebundene REST-API und vollständige Weboberfläche
• gehärteter systemd-Dienst, Readiness-/Liveness-Checks, strukturierte Logs
• Unit-/API-Tests und GitHub-Actions-CI

Ablauf

LINBO-Client -> *_hwinfo.gz auf Server -> Hardwareprofile -> gemeinsames Image
      -> <image>.driverpostsync -> match.conf -> DMI-Match
      -> nur passende Treiber laden -> Windows pnputil

Das Serverinventar wird von LINBO automatisch erzeugt, wenn im gemounteten Client-Cache noch kein hwinfo.gz liegt. Eine funktionierende Cache-Partition ist dafür Voraussetzung; ein lediglich in linuxmuster angelegter oder nur bis zur LINBO-Oberfläche gestarteter Client besitzt noch nicht zwingend ein Inventar. Deshalb zeigt die Oberfläche Alter und „veraltet“-Status an. Ein direkter Ersatzscan gegen den Client steht bewusst nicht zur Verfügung: Ohne serverseitige Inventardatei kann Patchless kein Profil für den Client erzeugen. In diesem Fall muss zunächst die LINBO-Cache-Partition initialisiert und der Client erneut in LINBO gestartet werden, damit LINBO das Inventar auf den Server überträgt.

Patchless öffnet im Normalbetrieb keine Verbindung zu LINBO-Clients. Es erzeugt keinen Client-SSH-Schlüssel, legt keinen Public Key unter /root/.ssh ab und verändert linbofs nicht. Der spätere Treibertransfer erfolgt ausschließlich durch den nativen LINBO-Hook über das vorhandene read-only-rsync-Modul.

Was „patchless“ konkret bedeutet

Die Treiber müssen nicht mehr von Hand in jedem Windows-System und auch nicht vorab im Golden Image installiert werden. Ein vorbereitetes Golden Image kann auf unterschiedliche Hardware ausgerollt werden; LINBO legt beim Sync nur die für das jeweilige Modell passenden Pakete in das offline gemountete Windows. Windows übernimmt sie beim nächsten Start automatisch in den Driver Store und bindet passende Geräte ein.

Phase	Häufigkeit	Aufgabe
Golden Image vorbereiten	einmal pro Windows-Image	Das PowerShell-Skript registriert und schützt den SYSTEM-Startup-Task. Es installiert noch keinen Gerätetreiber.
Profil verwalten	bei neuen oder aktualisierten Treibern	Pro Hardwareklasse ein Paket ablegen; mehrere Profile dürfen dasselbe Image verwenden.
LINBO-Sync	pro Client/Rollout	Erst kleine Matchregeln prüfen, dann nur passende Treiber samt Installer nach C:\Drivers\LINBO kopieren.
Windows-Start	automatisch	Der vorbereitete Task ruft pnputil als SYSTEM auf; eine Benutzeranmeldung ist nicht nötig.

Das funktioniert für normale, zum Gerät und zur Windows-Version passende, signierte INF-/Plug-and-Play-Treiber. Ein Hersteller-EXE kann als Archivquelle dienen, muss aber tatsächlich INF-Dateien enthalten; dessen Setup-Programm, Zusatzsoftware, Firmware-Updater oder Lizenzdialoge werden nicht ausgeführt. Windows muss außerdem bereits ohne das neue Paket bis zum Task Scheduler starten können. Bootkritische Storage-Treiber bleiben daher ein eigener Offline-DISM- bzw. Golden-Image-Fall.

Warum der einmalige Windows-Schritt notwendig ist und welche Grenzen gelten, beschreibt docs/WINDOWS-DRIVER-FLOW.md. Eine sehr detaillierte Gesamtdarstellung mit Komponenten-, Sequenz-, Zustands- und Datenflussdiagrammen, dem rein serverseitigen Betriebsablauf sowie einer konkreten Repository- und PR-Karte für das Upstreaming steht in docs/TECHNICAL-ARCHITECTURE.md.

Kompatibilität

• linuxmuster.net 7.3 auf Ubuntu 24.04 (amd64)
• linuxmuster.net 7.4 auf Ubuntu 26.04 (amd64)
• linuxmuster-linbo7 >= 4.3.33-0 für den nativen <image>.driverpostsync-Hook
• private, ausschließlich von Patchless verwendete Node.js-Laufzeit 24.18.0
• privater 7-Zip-Extractor 26.02 für 7z-/EXE-Pakete; ZIP wird zusätzlich intern verarbeitet

Node.js und 7-Zip liegen paketintern unter /usr/lib/linbo-patchless/runtime/. Das Paket ersetzt weder Ubuntus /usr/bin/node noch dessen 7zip-Paket und benötigt auf dem Zielserver kein NodeSource- oder anderes Fremd-Repository. Dadurch kann auf Ubuntu 24.04 die von Noble gelieferte Systemversion unverändert bleiben.

Auf einem 7.3-System mit älterem LINBO zeigt apt-cache policy linuxmuster-linbo7 die installierte und die aus den offiziellen linuxmuster.net-Paketquellen verfügbare Version. Bei der Patchless-Installation aktualisiert APT LINBO automatisch, wenn der konfigurierte Kandidat mindestens 4.3.33-0 ist. Gibt es keinen passenden Kandidaten, müssen zuerst die offiziellen linuxmuster.net-Paketquellen bzw. der 7.3-Paketstand aktualisiert werden; eine erzwungene Installation ist nicht unterstützt.

Der vollständige End-to-End-Ablauf ist auf linuxmuster/LINBO 7.4.5 mit einem Windows-Testclient vom Modell LENOVO 21L4S00P00 bestätigt: „Sync + Start“, Ausführung als SYSTEM, Treiberübernahme mit pnputil, Entfernen des einmaligen Batches und ein abschließender Tasklauf mit LastTaskResult : 0. Das Paket 1.1.2+lm73.1 ergänzt dafür den Ubuntu-24.04-/linuxmuster-7.3-Paketpfad, ohne die sicherheitsrelevanten Laufzeitversionen abzusenken.

Der reale Pfad und Hook-Ablauf wurden zunächst auf einem frischen linuxmuster-/LINBO-7.4.5-Server auf Ubuntu 26.04 geprüft und anschließend im oben beschriebenen Windows-End-to-End-Rollout bestätigt. Verwendet wird:

/srv/linbo/images/<image>/<image>.driverpostsync
/srv/linbo/drivers/<profil>/

Ein Image wird nur angeboten, wenn <image>.qcow2 im gleichnamigen Verzeichnis existiert. Der Image-Basisname darf keinen Punkt enthalten, weil LINBO Companion-Dateien sonst nicht verlässlich demselben Image zuordnet. Die vollständigen Befunde stehen in docs/REFERENCE-SERVER.md.

Installation

Der unterstützte Installationsweg ist das Debian-Paket. Es wird nicht direkt ausgeführt, sondern mit APT installiert, damit alle Systemabhängigkeiten aufgelöst werden:

sudo apt update
apt-cache policy linuxmuster-linbo7
sudo apt install ./linbo-patchless_1.1.2+lm73.1_amd64.deb

Das amd64-Paket enthält die bereits gebauten produktiven Node-Abhängigkeiten, Node.js 24.18.0 und 7-Zip 26.02. Es benötigt während der Installation weder Zugriff auf npm noch ein zusätzliches APT-Repository. Die privaten Programme werden nur für Patchless unter /usr/lib/linbo-patchless/runtime/ installiert und überschreiben keine Ubuntu-Systempakete. Das Paket:

• installiert die übrigen Systemabhängigkeiten wie innoextract über deklarierte Paketabhängigkeiten,
• prüft Ubuntu 24.04 oder 26.04 sowie linuxmuster-linbo7 >= 4.3.33-0,
• verwendet ausschließlich die mitgelieferten, fest versionierten Node.js- und 7-Zip-Programme,
• liest Hardware ausschließlich aus den von LINBO serverseitig abgelegten Inventardateien,
• verbindet sich nicht mit LINBO-Clients, erzeugt keine Client-Schlüssel und injiziert keine Schlüssel in linbofs,
• richtet Benutzer, Konfiguration, Rechte, ACLs und den systemd-Dienst ein,
• behält Konfiguration und Treiberprofile bei Paketupdates bei.

install.sh bleibt vorerst als Entwicklungs- und Migrationsweg für Ubuntu 26.04 bestehen. Auf linuxmuster 7.3/Ubuntu 24.04 muss das hier beschriebene .deb verwendet werden. Für reproduzierbare Servertests und Updates ist das Paket auch auf 7.4 der bevorzugte Weg. Beim Wechsel entfernt die Paketkonfiguration ausschließlich die eindeutig erkannte alte systemd-Unit aus /etc/systemd/system, damit diese den Paketdienst nicht überschreibt. Eine unbekannte lokale Unit wird nicht gelöscht, sondern führt zu einer klaren Fehlermeldung. Der alte Anwendungsbaum unter /opt/linbo-patchless bleibt zunächst als Rückfallkopie erhalten.

Bei einer frischen Debian-Installation ermittelt der Konfigurator die interne Adresse des linuxmuster-Servers bevorzugt aus dessen addc-Eintrag in der devices.csv. Die Adresse muss privat und tatsächlich auf dem Server gebunden sein. Patchless ist danach direkt unter http://<ermittelte-server-ip>:3001/ erreichbar. Auf dem Referenzserver lautet die URL beispielsweise http://10.0.0.14:3001/; diese IP ist nicht im Paket fest einprogrammiert.

Findet der Konfigurator keine eindeutige private Serveradresse, bleibt der Dienst auf 127.0.0.1 beschränkt. Dann genügt für einen einzelnen Administrationszugriff ein SSH-Tunnel:

ssh -L 3001:127.0.0.1:3001 root@<server>

Danach ist die Oberfläche lokal unter http://127.0.0.1:3001/ erreichbar. Dieser Tunnel transportiert ausschließlich den administrativen HTTP-Zugriff zwischen Arbeitsplatz und Server. Er ist kein Patchless-Zugriff auf LINBO-Clients und ersetzt kein Hardwareinventar.

Für den dauerhaften Mehrbenutzerbetrieb ist ein HTTPS-Reverse-Proxy vorgesehen; eine gehärtete Vorlage steht in docs/REVERSE-PROXY.md. Da Patchless selbst keine Benutzeranmeldung besitzt, muss dieser Proxy Administratoren authentifizieren. Eine bestehende alte Konfiguration mit implizitem Wildcard-Bind 0.0.0.0 wird aus Sicherheitsgründen auf localhost migriert. Bei einer frischen Installation wird stattdessen die oben beschriebene konkrete interne Server-IP erkannt.

Die automatisch erkannte Konfiguration entspricht diesen drei Werten in /etc/linbo-patchless/env:

PATCHLESS_HOST=10.0.0.14
PATCHLESS_ALLOW_PLAINTEXT_REMOTE=true
PATCHLESS_ALLOWED_HOSTS=10.0.0.14

Anschließend genügt:

systemctl restart linbo-patchless

Die Oberfläche ist dann ohne Tunnel unter der jeweiligen Server-IP erreichbar. Die Bindung an eine konkrete interne IP ist sicherer als 0.0.0.0, stellt aber keine Anmeldung bereit: Jeder Client, der diese Adresse und den Port erreichen kann, kann Patchless bedienen. Produktiv sollte der Zugriff deshalb auf ein Admin-VLAN bzw. per Firewall eingeschränkt oder über einen authentifizierenden HTTPS-Reverse-Proxy veröffentlicht werden.

Bedienung

Windows-Golden-Image einmalig vorbereiten

Vollautomatische Installation ohne Benutzeranmeldung funktioniert erst, wenn der persistente SYSTEM-Task im Windows-Golden-Image registriert wurde. Das Skript steht im Repository als Install-LinboPatchlessTask.ps1 und außerdem ohne Repository-Zugriff in der Weboberfläche bzw. unter /downloads/Install-LinboPatchlessTask.ps1 bereit. Es wird einmal in einer als Administrator gestarteten Windows PowerShell ausgeführt:

Set-ExecutionPolicy -Scope Process Bypass
.\Install-LinboPatchlessTask.ps1

Get-ScheduledTask -TaskName LINBO-Patchless-Driver-Install
Get-Content C:\ProgramData\LINBO-Patchless\startup-task-ready
icacls C:\Drivers

Erst danach die Installation in das LINBO-Image übernehmen. Das Skript:

• installiert selbst keine Gerätetreiber und muss nicht für jedes Treiberpaket oder jeden Client erneut ausgeführt werden,
• registriert einen persistenten AtStartup-Task als SYSTEM mit höchster Ausführungsstufe,
• schützt Runner und C:\Drivers so, dass normale Benutzer den später als SYSTEM ausgeführten Batch nicht verändern können,
• verifiziert Trigger, Principal, Enabled-State und Action,
• schreibt erst nach erfolgreicher Prüfung den Marker C:\ProgramData\LINBO-Patchless\startup-task-ready.

Neue Treiber werden danach nur noch serverseitig bereitgestellt und einem Image zugewiesen. Nach LINBO-Sync und Windows-Start verarbeitet derselbe Task die jeweils mitgelieferten INF-Dateien. Das Bootstrap-Skript muss nur erneut ausgeführt werden, wenn der Task entfernt, beschädigt oder durch eine neuere Projektversion bewusst aktualisiert wurde; es ist idempotent und kann zur Reparatur erneut laufen.

Nach einem abgeschlossenen Treiberlauf löscht sich der einmalige Installer. Der permanente Task prüft bei späteren normalen Windows-Starts nur kurz, ob ein neuer Installer bereitliegt, und beendet sich ansonsten ohne erneuten pnputil-Lauf. Ein neuer LINBO-Sync stellt das Paket erneut bereit; auch der offizielle PnPUtil-Code 259 (kein passendes Gerät oder bereits besserer bzw. neuerer Treiber aktiv) gilt dabei als terminaler, nicht erneut zu versuchender Zustand.

Der LINBO-Hook vertraut nur auf die Kombination aus registrierter Taskdatei und exaktem Projektmarker. Fehlt eines davon, bleibt aus Kompatibilitätsgründen ein !LinboDriverInstall-RunOnce-Fallback aktiv. Dieser wird erst bei der Anmeldung eines Administrators ausgeführt und ist deshalb kein unbeaufsichtigter Automatikpfad. Die Offline-Prüfung kann nicht erkennen, ob ein zuvor korrekt registrierter Task später in Windows deaktiviert oder verändert wurde. Der Taskstatus muss deshalb beim Testrollout erneut kontrolliert werden.

Treiber verwalten

1. „Neues Profil“ wählen und ein aus den LINBO-Inventaren zusammengefasstes Hardwaremodell auswählen.
2. Treiberpaket hochladen oder entpacken.
3. match.conf prüfen und bei Bedarf mehrere product-Zeilen ergänzen.
4. Das Profil einem Windows-Image zuweisen.
5. Für jede weitere Hardwareklasse ein eigenes Profil anlegen und demselben Image zuweisen. Eine neue Imagekopie ist dafür nicht erforderlich.
6. Auf einem Testclient jeder Hardwareklasse in LINBO „Sync + Start“ ausführen.
7. Clientlog unter /cache/linbo-driverpostsync.log, persistentes Windows-Log unter C:\ProgramData\LINBO-Patchless\driver-install.log und den Gerätemanager prüfen. Einen von Windows angeforderten Neustart durchführen und danach LastTaskResult kontrollieren.

Beim Archivupload zeigt die Oberfläche den echten Übertragungsfortschritt mit Prozent, Datenmenge, Geschwindigkeit und Restzeitschätzung. Sobald alle Bytes auf dem Server liegen, wechselt sie zuverlässig in die serverseitigen Stufen „vorbereiten“, „Inhalt prüfen“, „Speicher prüfen“, „entpacken“, „validieren“, „Profil aktivieren“ und „aufräumen“. Für diese Stufen gibt es bewusst keine erfundene Prozentzahl; stattdessen werden die reale Stufe und ihre Laufzeit angezeigt.

Ein hochgeladenes Archiv darf höchstens 2 GiB groß sein. Der entpackte Inhalt ist standardmäßig auf 8 GiB begrenzt; diese Schranke schützt vor Archivbomben und kann mit PATCHLESS_ARCHIVE_MAX_EXTRACTED_GIB auf einen ganzzahligen Wert von 1 bis 8 GiB abgesenkt werden. Für den atomischen, rückrollbaren Import prüft Patchless vorab den freien Speicher und benötigt ungefähr das Doppelte der entpackten Größe, die Größe des vorhandenen Profils und 512 MiB Reserve.

Der beim Anlegen gewählte Inventareintrag dient nur als DMI-Quelle: Sein Hostname wird nicht im Profil gespeichert. Patchless übernimmt ausschließlich DMI-Hersteller und -Modell. Nach der Zuweisung zu einem LINBO-Image wird das Profil automatisch auf beliebig vielen Clients dieses Images mit passender Hardware berücksichtigt. Die Oberfläche gruppiert beispielsweise 87 exakt gleiche DMI-Werte zu einem Eintrag Dell Inc. · Latitude 5520 — 87 Inventare. Diese Zahl ist eine Orientierung, keine feste Zielhostliste: Da product beim Sync als Teilstring geprüft wird, kann das Profil auch weitere passende Modellvarianten treffen. Jeder Client entscheidet anhand seiner eigenen DMI-Daten, ob das Profil passt.

Das übliche Schul-Setup ist damit ausdrücklich ein Golden Image mit mehreren Hardwareprofilen: beispielsweise Lenovo, Dell, HP und Fujitsu zeigen alle auf win11_pro_edu. Beim Sync werden zunächst nur ihre kleinen Matchdateien übertragen. Ein Lenovo-Client lädt danach nur das Lenovo-Payload; die großen Dell-, HP- und Fujitsu-Pakete landen weder in seinem vollständigen Profilcache noch in Windows.

Auch mehrere Modelle desselben Herstellers können ein gemeinsames Treiberprofil verwenden, sofern das Paket wirklich für alle Modelle geeignet ist. Dazu werden weitere product-Zeilen ergänzt; sie sind als ODER-Verknüpfung zu verstehen. Raum, linuxmuster-Gruppe und Hostname sind derzeit keine Matching-Kriterien. Ein Profil ist außerdem aktuell genau einem LINBO-Image zugeordnet; umgekehrt kann ein Image beliebig viele Profile enthalten.

Beispiel für match.conf:

[match]
vendor = Dell Inc.
product = Latitude 5520
product = Latitude 5530

vendor ist genau einmal verpflichtend und wird einschließlich Groß-/Kleinschreibung exakt verglichen; nur vendor = * trifft alle Hersteller. Fehlt eine product-Zeile oder lautet sie product = *, trifft das Profil alle Produkte des gewählten Herstellers. Andere product-Werte werden einschließlich Groß-/Kleinschreibung als Teilstring des DMI-Produktnamens verglichen. Ein fehlender [match]-Abschnitt, ein vertippter oder unbekannter Schlüssel oder ein leerer bzw. mehrfacher Vendor wird abgelehnt und das Profil auf dem Client geschlossen übersprungen. Innerhalb von [match] sind ausschließlich vendor und product zulässig; Kommentarzeilen dürfen mit # oder ; beginnen.

Wichtige API-Endpunkte

Die API besitzt keine eigene Anmeldung. Das Debian-Paket bindet sie an die eindeutig erkannte interne Server-IP oder ersatzweise nur an localhost. Der direkte LAN-Zugriff muss per Firewall/Admin-VLAN begrenzt werden; ein Remote-Proxy muss den Zugriff authentifizieren.

Methode	Pfad	Zweck
GET	/health/live	reine Prozess-Liveness
GET	/health	Readiness mit Pfad-, Inventar- und qcow2-Verzeichnis-Prüfung
GET	/api/v1/drivers/hwinfo/server	vorhandene LINBO-Serverinventare
GET	/api/v1/drivers/hwinfo/server?details=true	Inventare einschließlich PCI-/USB-Details
POST	/api/v1/drivers/create-profile-from-inventory	Profil aus { "hostname": "..." }
GET	/api/v1/drivers/profiles	Profile auflisten
GET/DELETE	/api/v1/drivers/profiles/:name	Profil lesen/löschen
GET/PUT	/api/v1/drivers/profiles/:name/match-conf	Matching lesen/ändern
GET/DELETE	/api/v1/drivers/profiles/:name/files	Dateien auflisten/löschen
POST	/api/v1/drivers/profiles/:name/upload	einzelne Datei hochladen
POST	/api/v1/drivers/profiles/:name/extract	ZIP, 7z oder EXE sicher entpacken
GET	/api/v1/drivers/profiles/:name/extraction-status	aktive serverseitige Entpackstufe abfragen
PUT/DELETE	/api/v1/drivers/profiles/:name/image	Image zuweisen/entfernen
GET	/api/v1/drivers/available-images	gültige LINBO-Images auflisten

Beispiel:

PATCHLESS_HOST="$(sed -n 's/^PATCHLESS_HOST=//p' /etc/linbo-patchless/env)"
curl "http://${PATCHLESS_HOST}:3001/api/v1/drivers/hwinfo/server"

Konfiguration

Produktive Einstellungen liegen in /etc/linbo-patchless/env; eine vollständige Vorlage steht in .env.example.

Besonders wichtig:

Variable	Standard/Zweck
PATCHLESS_HOST	bei frischer Paketinstallation automatisch erkannte interne Server-IP; bei uneindeutiger Erkennung 127.0.0.1
PATCHLESS_ALLOW_PLAINTEXT_REMOTE	ausdrückliche Betreiberbestätigung für einen unsicheren Remote-Bind
PATCHLESS_ALLOWED_HOSTS	explizite Hostnamen oder IP-Adressen für HTTP-Anfragen; keine Wildcards
DRIVERS_BASE	/srv/linbo/drivers
LINBO_DIR	/srv/linbo
LINBO_HWINFO_DIR	/var/log/linuxmuster/linbo
LINBO_DEVICES_CSV	Sophomorix-Hostzuordnung
HWINFO_STALE_HOURS	Inventaralter bis Warnung, Standard 168
PATCHLESS_ARCHIVE_MAX_EXTRACTED_GIB	maximales entpacktes Archiv, ganzzahlig 1–8 GiB; Standard 8
SEVEN_ZIP_BIN	automatisch erkanntes 7zz oder 7z, mindestens 25.01

Betrieb und Diagnose

systemctl status linbo-patchless
journalctl -u linbo-patchless -f
PATCHLESS_HOST="$(sed -n 's/^PATCHLESS_HOST=//p' /etc/linbo-patchless/env)"
curl -fsS "http://${PATCHLESS_HOST}:3001/health"

Die Image-Verzeichnisse behalten ihre linuxmuster-Eigentümer. Der Dienst erhält auf vorhandenen Image-Verzeichnissen benannte ACLs zum atomischen Ersetzen der Hookdateien sowie eine vererbte ACL am Image-Root. Wird ein neues Verzeichnis mit Modus 0755 angelegt, kann dessen ACL-Maske das vererbte Schreibrecht jedoch auf r-x begrenzen. /health prüft deshalb jedes gültige qcow2-Verzeichnis und wird in diesem Fall degraded; anschließend sudo linbo-patchless-configure ausführen. Auch Restore oder Austausch von /srv/linbo/images kann ACL-Metadaten entfernen.

Profil- und Image-Mutationen werden prozessintern serialisiert. Schlägt das atomische Publizieren eines Hooks fehl, werden image.conf bzw. ein zum Löschen vorgemerktes Profil zurückgerollt. Beim Dienststart werden vorhandene Zuweisungen und bereits publizierte Hooks neu abgeglichen; verwaiste Hooks werden als Cleanup-Tombstone erhalten. Unterbrochene Archivtransaktionen und Profil-Löschungen werden über private Workspaces bzw. Commit-Journale kontrolliert wiederhergestellt oder abgeschlossen.

Auf dem Client wird jedes Profil zunächst in ein Staging-Verzeichnis geladen und erst nach erfolgreichem rsync atomisch aktiviert. Bei einem Netzfehler bleibt der letzte vollständige Cache erhalten. Der Hook beendet sich zudem vor jedem Cache-, Registry- oder Zielzugriff, wenn unter /mnt kein Windows-System erkannt wird.

Der Task kann nur Treiber installieren, nachdem Windows bereits bis zum Systemstart gelangt ist. Bootkritische Storage-/Massenspeichertreiber, ohne die Windows nicht startet, benötigen weiterhin ein vorbereitetes Image oder einen zukünftigen Offline-DISM-Workflow; sie sind kein geeigneter Patchless-Fall.

Der Container in docker-compose.yml bindet Port 3001 standardmäßig nur an 127.0.0.1 und ist für Entwicklung und API-Tests gedacht. Er ersetzt keine Installation auf dem linuxmuster-Server, solange die realen LINBO-Pfade und Serverinventare nicht gezielt eingebunden werden.

Entwicklung

npm ci
npm test
docker compose config
docker compose up --build
./scripts/build-deb.sh

Details zu Sicherheitsgrenzen stehen in SECURITY.md, priorisierte Weiterentwicklungen in docs/ROADMAP.md und Hinweise zum Paketbau in packaging/README.md.

Lizenz

GNU General Public License v3.0 only