Files
rust-discovery/docs/linux-updater-compatible-bootstrap-plan.md
2026-11-16 15:25:46 +01:00

238 lines
15 KiB
Markdown

# Linux-Updater: erhaltender Bootstrap und erste reale Abnahme
Stand 16. November 2026. **Plan und tatsächliche lesende Vorprüfung; noch keine
Installation, kein Dienstwechsel und kein Apply.** Der koordinierende
Rootprozess führt Zieländerungen und WebUI-Abnahmen durch. Die neue Datei
`deploy/linux_updater_bootstrap.py` besitzt ausschließlich `inspect` und lokale
Paketvorbereitung `prepare`; sie implementiert keinen versteckten Applymodus.
## Tatsächlich gelesen
`python3 deploy/linux_updater_bootstrap.py inspect` las die bestehende
Cloud-Linux-VM über den vorhandenen streng geparsten SSH-Zugang mit bestätigtem
Hostschlüssel. Der private Originalbeleg liegt in
`devstate/linux-updater-bootstrap/eb9ad00e-0229-4ebf-8ba4-09861bb246c5/read-only.json`.
Boot: `45aba743-be1d-4ae5-ba00-139fb9363bfe`.
| Gegenstand | Tatsächlicher Zustand |
|---|---|
| Agent | aktiv/enabled, SHA256 `0a7ad6eefaefda79ee80b6a41b2df904e9e7f50ae6ebeed01b98c25b6ce5c06f` |
| General/Full | beide aktiv, gemeinsame Binary `79442727c3ba31cda02a8bc0e67481f14db9f39fc07520a880a90b64f10f1eaf`; General enabled, Full disabled |
| Updater | Unit, Binary, Konfigurations- und Stateverzeichnis fehlen |
| APT/Legacy | inaktiv/disabled, keine beobachteten General-Rollbacktimer |
| Agentjournal | 30 Aufträge, kein offener Auftrag, kein Fault, Integrität ok |
| Agentverbrauch | 27 Verbräuche und 27 Startzeugen, kein offener Verbrauch |
| Rootverbrauch | 19 Verbräuche und 19 Startzeugen, kein offener Verbrauch/Fault |
Die Root-Evidenzaggregate blieben lesend gebunden an
`def53ce39f60ebe6815352df2ef1980d5170569519bbca0a9e132d3eecb470d1`,
die Agent-Evidenz an
`61e54815aecb8b5625ff7a8e5b09a5a509ba39d23f3682ad5c969bcb93ff7836`.
Dies sind Hashes der auf dem Ziel gehashten Originalstart-/Outcomebytes mit
Grantbezug, kein Export von Jobausgaben. Die Vorprüfung exportiert ausschließlich
öffentliche Konfigurationsfelder, feste Unit-/Binärhashes und Dateimetadaten.
Private Schlüssel und Agentumgebungsdatei wurden ausschließlich `stat`-geprüft.
Die vorhandenen Datenbanken wurden read-only im tatsächlich vorhandenen
DELETE-Journalmodus geöffnet; es entstanden keine WAL-/SHM-Sidecars.
Der erste lesende Versuch stoppte beim Stabilitätsvergleich einer öffentlichen
Datei, weil der Vergleich auch die durch Lesen veränderliche atime einschloss.
Die Korrektur vergleicht Identität, Größe, mtime und ctime; der nächste vollständige
Read bestand. Der TLS-Selektor wird anhand seines tatsächlichen Felds `version`
behandelt. Kein fehlgeschlagener Read wurde als Bootstraperfolg ausgegeben.
## Verbindliche Reihenfolge
Die bisherigen Images sind kein geeigneter Rückfall für den neuen Updater:
ihnen fehlen Decoder-/Owner-/Healthteile. Deshalb zunächst **kompatible neue
Baseline**, erst anschließend ein separat genehmigtes Update auf andere Bytes.
„Release 0“ bezeichnet unten die Baselinegeneration mit positiver Sequenz 1;
Sequenz 0 ist im Releasecodec ungültig.
1. Den gemeinsamen Quellsatz einfrieren. Agent, Helper und stabilen Updater für
Linux x86-64 bauen, genaue Quellen-/Listen-/Hashbelege aufbewahren und die
dafür vorgesehenen nicht destruktiven Vertragsprüfungen zuerst auf der
tatsächlichen Cloud-Linux-VM ausführen. Containerfixtures, die feste vorhandene
Agent-Statepfade voraussetzen, dort ausdrücklich nicht starten.
2. Einen frischen Ziel-CAS und den zentral geschlossenen Devtestscope prüfen.
Agent, General und Full in einem begrenzten administrativen Dienstwechsel
stoppen; APT/Legacy bleiben geschlossen. Beide ursprünglichen Sperren halten.
DB-Dateien, Identität, PKI und sämtliche Originalzeilen/Outcomebytes erhalten.
Alte Binaries create-only als historische Bootstrapbelege aufbewahren.
3. Die kompatiblen neuen Agent-/Helperbytes an den bisherigen festen Zielpfaden
bereitstellen und den Full-Konfigurations-/Policy-/Binärpin auf genau diese
Helperbytes binden. Generalpolicy und Generalpin bleiben erhalten. Keine
APT-Rezept-/Proofanpassung und kein Paketjob. Eine geänderte gemeinsame
Helperbinary ist **kein** neuer APT-Laufzeitqualifikationsnachweis.
4. General, Full und Agent genau einmal starten, tatsächliche neue PID/Birth/
Image-/Unitzeugen lesen, normale signierte Agent-/Helpersynchronisierung und
passives Inventar nachweisen. Erst daraus den öffentlichen tatsächlichen
Baselinequalifikationsbeleg bilden; er enthält keinen Hash einer noch zu
erzeugenden Baseline/Registry/Policy, sodass keine Hashzirkularität entsteht.
5. Auf dem Server getrennte Release-/Baselinesignier- und Healthschlüssel
erzeugen. Keine privaten Schlüssel verlassen den Server. Der Releasekey
bleibt Root vorbehalten; der separate Healthkey wird ausschließlich dem
vorhandenen unprivilegierten Gateway-Dienst als geschützte PEM-Datei zugänglich
gemacht. Der tatsächliche Handler `/agent/v1/update-health` läuft im Gateway.
Job- und Zeitsignierer werden nicht wiederverwendet.
6. Release-0-Manifest exakt für die kompatibel installierten Agent-/Helperbytes
signieren, daraus den kanonischen Initialrecord mit Sequenz/Floor 1,
tatsächlicher Aktivierungszeit, Bootstrapqualifikationshash und
`rolled_back=false` bilden und separat signieren. Identität und bestehende
Journale werden nicht durch diese Recorddatei ersetzt.
7. Die neue feste Updaterunit installieren, reale Unit-Inodes/Kompositionen
nachlesen und die vollständige 21-Unit-Registry plus tatsächliche etwaige
Rollbacktimer erzeugen. Geschützte Registry enthält den Baselinebeleg und
den unveränderten Readervertrag; dazu die tatsächlichen PID-/User-/Cgroup-
Namespace-/Procidentitäten. Erst dann Registryhash und signierte Baseline
in der lokalen Policy binden. Keine Unit-Pins aus einem Quelltext statt der
tatsächlich installierten Dateien übernehmen.
8. Den Updater einmal als eigenes Root-Systemd-Programm starten; sein eigener
PID/Birth/Image/Unitbeleg muss passen. Danach den Full-Aufruf
`update_observe_v1` als tatsächlicher UID-993-Agent prüfen. Nur daraus
gültige Apply-/Checkcapabilities und CandidatePreview veröffentlichen.
9. Release 1 als tatsächlich neue Codepaarbytes bauen, beispielsweise aus
demselben eingefrorenen Runtimequellsatz mit sauberer Version 0.1.1 und
eigener nachvollziehbarer Buildprovenienz. Der bereits gebundene stabile
Updater bleibt unverändert. Full rendert den neuen Konfigurations-/Pinwechsel
aus dem unabhängig geprüften Kandidaten. Veröffentlichung im bestehenden
Tenantkatalog erzeugt noch keinen ausführbaren Job.
10. MCP muss einen persistenten `pending_approval`-Plan für genau diese Bytes
erstellen. Der tatsächliche sichtbar simulierte Devtest-WebUIprincipal
genehmigt interaktiv. Vorher keine Jobwirkung oder Startgrants. Danach
genau einen ursprünglichen Verbrauch, Staging, Stop/Lock/Census/Swap/Start,
neuen unabhängigen signierten Sync-/Baseinventar-Healthbeleg und endgültigen
Originalrecord-/Floor-/Outcomestand prüfen. Nach diesem Abnahmeschritt
Dokumentation und Code nach Gitea pushen.
## Pfade und Berechtigungen
| Pfad | Geplante Bindung |
|---|---|
| `/usr/local/libexec/rmm-agent-updater` | qualifiziertes stabiles ELF, Root:Root, 0755; nie Teil des Job-Codepaars |
| `/etc/systemd/system/rmm-agent-updater.service` | feste geprüfte Rootunit, 0644, kein automatischer Wiederanlauf eines unsicheren Handoffs |
| `/etc/rmm-agent-updater` | Root:Root, 0755; keine Schreibrechte für Agent/Gruppe/Andere |
| `binding.json` dort | vorhandenes öffentliches Binding, Root:Root 0600 |
| `policy.json`, `keyring.json`, `health-key.json` dort | öffentliche geschützte Trustmetadaten, Root:Root 0644 |
| `reader-registry.json`, `retained-files.json` dort | feste lokal provisionierte tatsächliche Belege; Root besitzt die Schreibautorität |
| `/var/lib/rmm-agent-updater` | ursprünglicher privater Record-FS-Vertrag: Root:Root 0700 |
| `installed-record.json`, Recordarchive/Handoffs | private Rootdateien/-verzeichnisse, 0600/0700; keine öffentliche Projektion |
| Agentcache | fester vorhandener UID-993-Statebaum; neue Unterverzeichnisse 0700, Prefetchdateien 0600 |
Der Agent erhält die **öffentlichen Recordbytes** über dieselbe authentisierte
Full-Antwort wie den aktuellen gemessenen Zustand. Hash, Binding und exakte
Predecessor-/Floorwerte werden geprüft. Der bestehende private Recordport wird
hierfür nicht auf öffentliche Dateirechte umgestellt. Full schreibt dabei nichts.
Die Retainedliste bindet mindestens die drei bestehenden DB-Dateien, zwei
ursprünglichen Locks, öffentliche Binding-/Identitäts-/Jobkeydateien, die
Original-PKI-Dateien sowie den tatsächlichen TLS-Selektor und die aktuell aktive
TLS-Version. Für Schlüssel ausschließlich Dateimetadaten, nie Schlüsselbytes.
Unit-/Binär-/Trustdateien erhalten ihre getrennten eigenen Hash-/FD-Pins.
## Bekannter kontrollierter Fehlerfall
Der vorbereitete Linuxrückweg qualifiziert zunächst einen tatsächlich gescheiterten
neuen Fullstart nach bereits erfolgreichem Generalstart. Ein allgemeines
`exit 1`-Helperfixture genügt dafür nicht: dieselbe Binary bedient beide Rollen
und würde bereits General scheitern lassen. Ein separater privater, signierter
Fixturequellsatz muss General normal bedienen und ausschließlich den neuen
Fullstart vor Arbeitsaufnahme eindeutig beenden; kein Produktions-Failureflag
oder versteckter ausführbarer Sonderkanal wird dafür eingeführt.
Die derzeitige Fullunit hat `Restart=on-failure` mit 5 Sekunden. Ein solcher
weiter geplanter automatischer Wiederanlauf ist kein bekannter geschlossener
Fehler. Für diesen Test muss bereits **vor Baseline/Registry** ein ausdrücklich
geprüfter `Restart=no`-Full-Override zum qualifizierten kompatiblen Setup gehören,
oder ein tatsächlich terminaler Startlimitfall unabhängig bewiesen sein.
Eine nachträgliche ungepinnte Unitänderung während des Updatejobs ist verboten.
Die tatsächlichen negativen Start-/Stopbelege, Rückführung beider Codeversionen,
Originalfristen sowie frisch signierte Vorgänger-Health müssen anschließend
nativ bestehen. Unklare Rename-/Socket-/Startantworten bleiben Unknown und
werden weder wiederholt noch als bekannte Rückführung ausgegeben.
## Stand der Ausführung
Tatsächlich abgeschlossen sind der lesende Zielbeleg, lokale
Python-Syntaxprüfung der Vorbereitung und das unten abgegrenzte lokale Buildpack.
Quell- und Containerprüfungen der Runtime
stehen separat in [Runtimequellen](agent-updater-runtime-source.md). Bootstrap,
Schlüsselprovisionierung, neuer Dienststart, passiver qualifizierter Fullbeleg,
WebUI-genehmigter Apply und native Rückführung sind **geplant, nicht ausgeführt**.
## Eingefrorenes Linux-Buildpack, tatsächlich lokal gebaut
`deploy/linux_updater_qualification.py build` erstellte den unveränderten Fall
`devstate/linux-updater-qualification/21d20391-6102-4996-8a7a-efbd3e78bd7d`.
615 öffentliche Eingabedateien wurden mit vorherigem/nachherigem Hashvergleich
eingefroren; Zugangsdaten, Devstate und Schlüssel gehören nicht zum Paket.
Source0 verwendet Workspaceversion 0.1.0. Source1 unterscheidet sich ausschließlich
in `Cargo.toml` und den erbenden internen Paketversionen in `Cargo.lock` (0.1.1).
Externe Abhängigkeiten bleiben exakt gleich. Windowsquellen wurden ausschließlich
als Provenienz mitkopiert; dieser Linuxlauf qualifiziert sie nicht.
Beide Quellsätze bestanden `cargo clippy --locked --offline` mit `--all-targets
-- -D warnings` für Agent, Agentcore, Domain, Helper, Linuxupdater, Worker,
Handoff und Updatehistory. Source0 linkte Agent, Helper und stabilen Updater als
Release; Source1 Agent und Helper. Beide neuen Paarbytes unterscheiden sich
tatsächlich von Source0. Der stabile Updater wird ausschließlich aus Source0
verwendet. Alle Befehle liefen ohne Netzwerk in Docker mit schreibgeschütztem
Sourcebaum, eigenem Targetcache und gepinntem Builder
`sha256:9a76ad3744ebfdddae96ca10001ce8291c1b332fb54c8df5eea0e8e999ac6fc6`.
| Artefakt unter `artifacts/` im Fall | SHA-256 |
|---|---|
| `source0/rmm-agent` | `61a073f44be95a9e2a9edf816104fa198452f9512bc099b59b4931000fc98b1e` |
| `source0/rmm-privileged-helper` | `8fdc6ded02278eb18e64003d0bc7bf45d452cd48ded0450e6e900ca66e44d449` |
| `source0/rmm-agent-updater` | `dec6336728eac8af1e0d84d4921c7c9ecbcc45bc4619d357d346b716336be90a` |
| `source1/rmm-agent` | `c27319f312294f96583a2ecb14c9b1ed0b54e205c70dcd156ae511a1dc254e63` |
| `source1/rmm-privileged-helper` | `89b28db3afe870c667297dff97ad7a042c550ccce1f712d69108e8de672ad450` |
Manifesthash: `9ed5f153fe76665150aaab298c4b21d74d7199b2312a28fa23aa9e30b13ddd08`.
Source0-Archiv: `9b9e16c754f233c8675057aa44f89f86c2574ced0ba9d85d60157402363008de`;
Source1-Archiv: `b2bdf4962a1beacf27903263952f4db025dbadfd7705fecc0b02dea3b32dde61`.
Die vollständigen Einzeldateimanifeste und exakten Docker-/Cargoargumente samt
Exitcodes und Loghashes liegen im Fall. Acht Unit-/Integrationsexecutables
wurden gebaut und ihre tatsächlichen Testnamen aufgezeichnet. Nur die im
Manifest explizit aufgeführten 18 Filter sind für den nächsten VM-Schritt
vorgesehen: sieben zielgerichtete Parser-/Ack-/Sync-/SQLiteverträge und elf reine
Handoffverträge. Diese 18 liefen im isolierten lokalen Container erfolgreich.
Andere gelinkte Tests sind durch dieses Paket nicht zur Zielausführung vorgesehen.
Noch keines dieser Programme wurde durch diesen Buildschritt auf der Cloud-VM
ausgeführt; kein Produktdienst oder Zieljournal wurde geändert.
Diese Aussage beschreibt ausschließlich den damaligen Buildschritt. Der spätere
koordinierte native Lauf aller 18 vorgesehenen Filter auf der Cloud-Linux-VM
bestand; dessen Originalbelege und Abgrenzung stehen in
[Compatible-Linux-Vertragsprüfungen](updater-compatible-linux-contracts.md).
Er ersetzt weiterhin keinen tatsächlichen Updaterjob.
Der erste erhaltene Fall `7c030441-81e0-4235-9565-0b413b0cedae` scheiterte
an `items_after_test_module` im Linuxunit-Testtarget. Das Parser-Testmodul wurde
ohne Verhaltensänderung ans Dateiende verschoben; der erfolgreiche Fall entstand
anschließend aus einem neuen Snapshot. Der fehlgeschlagene Originalbeleg bleibt
erhalten.
## ARM64-Serverbuild, geplant und nicht ausgeführt
Der Source0-Quellsatz enthält auch den aktuellen Server-/Zeitbrokerquellcode.
Für die später separat koordinierte Serverbereitstellung muss dieser exakte
Archivhash auf dem ARM64-Server geprüft und jede reguläre Archivdatei gegen
`source0-inputs.json` geprüft werden. Der vorhandene ARM64-Rustbuilder wird erst
mit `docker image inspect` auf Architektur/OS/Image-ID geprüft und danach über
seine tatsächliche Image-ID angesprochen. In einem neuen eigenen Targetcache
und ohne Netzwerk sind dort geplant:
```text
cargo clippy --locked --offline -p rmm-server -p rmm-time-broker-linux --all-targets -- -D warnings
cargo build --locked --offline --release -p rmm-server -p rmm-time-broker-linux --bins
```
Der Container erhält den verifizierten Quellsatz ausschließlich lesend sowie
private temporäre Verzeichnisse. Artefakte müssen anschließend als tatsächliche
AArch64-ELFs, mit Hash/Buildlog/Image-ID und unverändertem Eingabemanifest
nachgewiesen werden. Keine Dockerfile-APT-Schritte, Netzwerkdownloads oder
Abhängigkeitsänderungen sind Teil dieses Plans. Serverdienste, bestehende
Ingress-/Broker-/Zeitpins und private Signierschlüssel werden durch einen
Build nicht geändert. Der lokale x86-64-Lauf ist kein ARM64-Buildnachweis.