Updates

Grundprinzip

Releases von Nova Control Panel sind mit Ed25519 signiert; die Signierschlüssel werden offline gehalten. Der Hersteller stellt die Releases auf seinem Release-Server als statische Dateien bereit. Jeder Nova-Host prüft selbst auf neue Releases und lädt sie selbst herunter. Das Panel zeigt nur „Update verfügbar“.

Wichtig: Ein Update einzuspielen ist immer eine bewusste root-Aktion auf dem Host. Nova installiert Updates nie automatisch.

Ein Upgrade ist eine Transaktion: Es wird geprüft, bevor es aktiv wird, rollt automatisch zurück, wenn eine Stufe oder die abschließende Prüfung fehlschlägt, und bleibt umkehrbar, bis du es akzeptierst. Nach accept gibt es keinen Rollback mehr.

Beide Wege enden in derselben Transaktion: preflight-upgrade, upgrade (mit automatischem Rollback), accept und nach einem Rollback rearm-upgrade.

Hinweis: Der Update-Kanal ist mit Version 1.0 neu. Nutze für deine ersten produktiven Updates --no-accept und prüfe die Installation, bevor du das Rollback-Fenster schließt.

Vertrauensmodell

Ein Host auf stable oder beta vertraut nur der Rolle release. Der dev-Schlüssel wird nur hinterlegt, wenn der Kanal dev gewählt ist, und beim Verlassen des Kanals wieder entfernt. Ein dev-Schlüssel kann so nie einen Stable- oder Beta-Host erreichen. Ein widerrufenes Release wird nie angeboten oder eingespielt; läuft ein Host auf einem widerrufenen Release, zeigt er current_revoked.

Kanäle

• Versionen folgen Semantic Versioning, inklusive Pre-Release-Reihenfolge. Stable trägt kein Suffix, Dev ist -dev.*, Beta ist jedes andere Pre-Release (-beta.N, -rc.N).
• Jede Installation folgt genau einem Kanal. Er steht in /etc/nova-controlpanel/update/config.json und wird bei der Neuinstallation mit --update-channel oder später mit nova-update configure --channel gesetzt.
• Panel-Karte und GET /system/update-status zeigen den Kanal.

Wichtig: Es gibt nie ein Downgrade. Nach einem Wechsel von beta auf stable bleibt die installierte Version, bis Stable diese oder eine neuere Version veröffentlicht. Bis dahin meldet check AHEAD OF CHANNEL (channel_state ahead_of_channel), und apply verweigert ältere Versionen (NOVA_UPDATE_RELEASE_NOT_NEWER).

Lizenz und Updates

Auf dem Control-Host entscheidet die installierte Lizenz, welche Releases abgedeckt sind (siehe Lizenz):

• Ein Release, das nach update_entitlement_until + grace_days veröffentlicht wurde, wird nicht angeboten. check meldet NOT ENTITLED (Kanalstatus not_entitled), fetch/apply verweigern mit NOVA_UPDATE_LICENSE_ENTITLEMENT_ENDED.
• Laufen nach Ende der Kulanzzeit mehr Knoten als lizenziert, wird jedes Update verweigert (NOVA_UPDATE_LICENSE_OVER_LIMIT).
• Community (1 Knoten) hat keinen Stichtag.
• Die installierte Version läuft immer weiter.
• nova-update license status|show-id|install|remove|trust verwaltet die Lizenz als root.

Einrichtung

Neuer Control-Host

Der kombinierte Installer übernimmt die Vertrauensanker gleich bei der Installation:

install-nova-combined-runtime.py install … --release-keys keys/release/<n>.json [--update-channel beta]
install-nova-combined-runtime.py install … --release-keys … --update-channel dev --dev-keys keys/dev/<n>.json

Er prüft die Schlüsselkette vor jeder Änderung, hinterlegt sie nach erfolgreicher Installation und schreibt /etc/nova-controlpanel/update/config.json mit Kanal und den Pfaden zu Zertifikat und Schlüssel des Operations-Bridge-Servers. Bewahre <n>.json zusammen mit 1.json…n-1.json und deren .sig-Dateien auf.

Ältere Hosts und Satelliten

Auf einem Host, der vor den signierten Releases installiert wurde, oder auf einem Satelliten hinterlegst du die Schlüsselliste von Hand:

nova-update trust --role release /path/keys/release/<n>.json

Gleiche dabei die Schlüssel-IDs über einen zweiten Kanal ab.

Update-Quelle

nova-update configure --source-url https://updates.example.net/nova/ --update-key-file /root/update-key \
    [--channel stable|beta|dev] [--dev-keys FILE] \
    [--bridge-server-certificate /root/nova-inputs/ops-server.crt --bridge-server-key /root/nova-inputs/ops-server.key]

• Jede Installation hat einen eigenen Update-Schlüssel (16 bis 512 Zeichen). Er wird als Authorization: Bearer <key> gesendet und unter /etc/nova-controlpanel/update/update-key (root 0600) gespeichert, nie ausgegeben.
• Der Release-Server muss per HTTPS mit einem Zertifikat erreichbar sein, dem der System-CA-Speicher vertraut. Weiterleitungen lehnt nova-update ab.
• configure aktiviert den Timer, sobald eine Quelle gesetzt ist. --no-source deaktiviert ihn (Offline-Host).
• Satelliten richtest du mit nova-update configure --role node … ein.

Installierte Bestandteile

Der Node-Agent-Installer legt auf jedem Nova-Host /usr/local/sbin/nova-update (root 0750) und nova-controlpanel-update-check.service/.timer an.

• Der Timer führt check täglich zu einer zufälligen Zeit innerhalb von 6 Stunden aus, aber nur, solange eine Quelle konfiguriert ist.
• Ein fehlgeschlagener Check wird im Status vermerkt und endet mit Exit-Code 0; er beeinträchtigt den Host also nie.

Update über den Kanal

Auf dem Control-Host, als root:

nova-update status
nova-update check                     # prüft Schlüssel, Kanal-Index, Ablauf, Sequenz; zeigt abgedeckte Releases
nova-update fetch 1.1.0               # fortsetzbarer Download nach /var/lib/nova-controlpanel/updates/releases/1.1.0/
nova-update apply 1.1.0 --no-accept   # Stage, profile-1.1.0.json ableiten, preflight-upgrade, upgrade (automatischer Rollback)
# Installation prüfen, dann
nova-update accept

• Ohne --no-accept akzeptiert apply direkt nach einem erfolgreich geprüften Upgrade. Für Produktivsysteme nimm --no-accept.
• Benötigt ein Release ein neueres Profilschema ohne mitgelieferten Migrationsschritt, verweigert apply mit NOVA_UPDATE_PROFILE_SCHEMA_REQUIRED und einer genauen Meldung.
• Bewahre releases/<version>/ des aktiven Release und seines Vorgängers auf. Das Installer-Journal verweist dorthin.

Satelliten-Knoten

Nachdem der Control-Host das Release akzeptiert hat, auf jedem Satelliten:

nova-update node check
nova-update node apply 1.1.0

node apply prüft dasselbe signierte Artefakt, entpackt daraus den Node Agent, installiert und prüft ihn (install-nova-node-agent.sh, verify-nova-node-agent.py), rollt bei einem Fehler automatisch zurück (rollback-nova-node-agent.sh) und schließt mit finalize-nova-node-agent-update.sh --discard-rollback ab.

Rollback vor accept

Ein fehlgeschlagenes upgrade rollt innerhalb des Installers automatisch zurück. Nach apply --no-accept kannst du auch selbst zurückrollen, mit dem Installer des betreffenden Release:

python3 /var/lib/nova-controlpanel/updates/releases/<v>/trusted/src/installer/operations/install-nova-combined-runtime.py rollback <candidate> <sha256> <profile> <stage>

Die Pfade stehen im Journal. Hinterlegte Schlüssel und die Update-Konfiguration liegen außerhalb jedes Release-Verzeichnisses und bleiben bei Upgrades und Rollbacks erhalten.

Offline-Hosts

Lege die Release-Datei, ihre .sig und die Index-Dateien (<channel>.json und .sig) aller Kanäle, die der Host sieht, nebeneinander auf den Host. Dann:

nova-update configure --no-source
nova-update apply /media/usb/nova-controlpanel-1.1.0-debian13.tar.gz [--index /media/usb]
nova-update node apply /media/usb/nova-controlpanel-1.1.0-debian13.tar.gz      # Satellit

Es gelten dieselben Regeln für Signatur, Ablauf, Widerruf, Schutz vor Zurückspielen und kein Downgrade. Bring einen frisch signierten Index mit, denn ein abgelaufener wird abgelehnt.

Was ein Upgrade ändern darf

Der Installer prüft all das vor jeder Änderung und antwortet sonst mit combined update changes stateful ... oder ... differs from predecessor.

Vor dem Upgrade

Prüfe den Host:

J=/var/lib/nova-controlpanel/installer/combined/transaction.json
python3 -c "import json;j=json.load(open('$J'));print(j['state'],j.get('operation'),j['candidate'])"
# erwartet: accepted ...
pgrep -a unattended          # kein Paketlauf aktiv
nova-update license status   # Lizenz deckt Updates ab

Der Vorgänger muss accepted sein. Nach einem zurückgerollten Upgrade lies zuerst den Abschnitt „Rearm nach einem zurückgerollten Upgrade“ weiter unten.

Lies die Release-Hinweise und beachte vor einem Upgrade auf ein Release mit diesen Voraussetzungen:

• MFA und Step-up. Ein Profil mit nativen Schreibvorgängen wird nur mit native_identity_mfa.enabled, native_identity_mfa.enrollment_enabled und native_capability_elevation.enabled zugelassen. Aktiviere sie gegebenenfalls mit dem aktuellen Release per Rekonfiguration und lass jeden Administrator zuerst TOTP einrichten.
• PHP-Einstellungen von Administratoren. Notiere native Websites mit nicht leerem php.open_basedir oder einer PHP.ini-Zeile außerhalb der Kunden-Allowlist; ein Administrator speichert jede davon nach dem Upgrade einmal neu (siehe Sicherheit). Jede Website erhält beim nächsten Anwenden die deaktivierten PHP-Funktionen und das verwaltete open_basedir; Sitzungen enden einmalig.
• Host-Markierung. Bestehende Hosts behalten /etc/ncp-fresh-os-disposable; das neue /etc/nova-controlpanel/host-platform ist für sie optional.
• Lizenz. Eine Installation von vor der Lizenzierung erhält mit dem Upgrade eine Installations-ID (nova-update license show-id). Übergib --license-keys $KEYS/keys/license/<n>.json an preflight-upgrade und upgrade oder hinterlege die Liste später mit nova-update license trust. Ohne Lizenz läuft sie als Community-Edition; mit mehr als einem Knoten ist sie dann over_limit: Knoten laufen weiter, keiner kann hinzukommen, Updates bleiben 30 Tage ab der Installation abgedeckt. Installiere in dieser Zeit eine Lizenz.
• Topologie. Ein Upgrade ändert nie die Topologie; dafür gibt es eine eigene Topologieänderung (siehe Anleitungen).

Pakete auf dem Host

Das versiegelte Paket-Bundle eines Kandidaten wird in der Operations-Stufe des Upgrades installiert. Die Sperrliste ist eine Untergrenze, keine feste Version: Ein Paket in oder über der gesperrten Version besteht; Sicherheitsupdates blockieren nie ein Upgrade.

• Ohne Firmware. Neue Bundles enthalten keine Hardware-Firmware und keinen CPU-Microcode (linux-firmware*, *-microcode, iucode-tool, firmware-*). Ein Upgrade installiert nur, was die neue Sperrliste braucht, und entfernt nie ein Paket der alten. Vorhandene Firmware- und Microcode-Pakete bleiben installiert.
• Ohne Ghostscript. Die PDF-Vorschau im Workspace rendert im Browser (pdf.js); das Bundle enthält ghostscript und dessen Abhängigkeiten (libgs*, fonts-urw-base35, poppler-data, libjbig2dec0) nicht mehr. Ein Host, der es hat, behält es.
• Rollback und Pakete. Ein Rollback entfernt die vom Update hinzugefügten Pakete (sofern kein anderes Paket sie jetzt braucht) und stellt den vorherigen Stand wieder her. Er stuft nie ein Paket herunter.

Wichtig: Behalte diese Pakete, bis das Upgrade akzeptiert ist, denn ein Rollback prüft den Vorgänger gegen dessen eigene Sperrliste.

Nach accept kannst du sie entfernen:

apt-get -s purge ghostscript && apt-get -s autoremove --purge     # zuerst prüfen
apt-get purge ghostscript && apt-get autoremove --purge
# Ubuntu, optional: linux-image-extra-virtual, linux-image-generic, linux-firmware*, intel-microcode,
# amd64-microcode, iucode-tool. Keep linux-modules-extra-$(uname -r) on web nodes (ext4 quota module).

Ohne linux-image-extra-virtual braucht jeder neue Kernel auf einem Web-Knoten sein eigenes linux-modules-extra-<kernel>; der Quota-Kernel-Hook meldet einen Kernel ohne dieses Paket.

Capabilities nach dem Upgrade

Automatischer Abgleich bei accept

Die Operations-Stufe von accept führt agent-node.php reconcile-capabilities aus. Jeder aktive Knoten mit erfasstem Rollensatz erhält die Capabilities, die der neue Vertrag für seine Rollen vorsieht und die noch fehlen (z. B. die lesenden web.statistics.collect oder node.address.observe). Ein Update braucht also keine erneute Einbindung.

• Bestehende Einträge werden nie geändert, auch keine, die du deaktiviert hast.
• Widerrufene und aufgegebene Knoten sowie Knoten ohne erfassten Rollensatz werden nur gemeldet. Ein Knoten ohne Rollensatz braucht weiterhin einen Rollenwechsel (node-role-request ... node-role-install) oder eine neue Einbindung.
• Der Bericht steht in der Ausgabe von accept (JSON). Schlägt der Abgleich fehl, schlägt die Annahme fehl; führe accept erneut aus. Ein Rollback vergibt nichts.

Schreibende Capabilities freischalten

Eine schreibende Capability mit activation: local-explicit führt ein Knoten erst aus, wenn sie in seiner /etc/nova-controlpanel-node-agent/runtime.env steht:

# auf dem Knoten: bestehende Liste behalten und ergänzen
NOVA_AGENT_WRITE_CAPABILITIES=...,<new capability>.v1

Der Node Agent liest die Datei beim nächsten Poll. Fehlt der Eintrag, endet der Befehl auf dem Knoten mit error (AGENT_RUNTIME_CAPABILITY_UNAVAILABLE oder NOVA_AGENT_CAPABILITY_DISABLED).

Lesende Capabilities (web.statistics.collect, node.address.observe, Beobachtungen und Prüfungen) brauchen keinen Schalter.

Manuelles Upgrade

Platzhalter wie im Kapitel Installation. NEW ist eine neue, vertrauenswürdige Kopie des Ziel-Release, z. B. /root/nova-src-<tag>. Behalte die alte Kopie, bis das Upgrade akzeptiert ist; Rollback und Rearm brauchen sie.

1. Host prüfen

Wie unter „Vor dem Upgrade“ beschrieben.

2. Neuen Kandidaten bauen

Wie im Kapitel Installation, in NEW, mit derselben Plattform und – wenn die Installation den Workspace nutzt – mit --native.

3. Zielprofil anlegen

Kopiere das aktive Profil in eine neue Datei. Bearbeite nie das aktive Profil: Es ist die Rollback-Referenz, und seine Prüfsumme steht im Journal.

ACTIVE=$(python3 -c "import json;print(json.load(open('$J'))['profile'])")
P=$IN/profile-$TAG.json
cp -p "$ACTIVE" "$P"
# set candidate.source_commit and candidate.archive_sha256 (Application archive of the NEW candidate)
# add the sections of a newer profile version if the release notes ask for them,
# v28 may leave native_backup_download out: the upgrade then keeps the installed setting (see below)

Der Installer akzeptiert die Profilversionen v13 bis v28.

Hinweis: Backup-Downloads behalten bei einem Upgrade ihre Einstellung. Ein v28-Profil ohne native_backup_download übernimmt genau den installierten Stand: an bleibt an, aus bleibt aus, und eine Laufzeit von vor den Downloads (Profil v27 oder älter) bleibt aus. Dasselbe gilt beim Update-Kanal. Zum Einschalten siehe Backups.

4. Stage und Preflight (nur lesend)

COMB=/root/cand/combined-$TAG.tar.gz; SHA=$(sha256sum "$COMB" | cut -d' ' -f1); S=/root/stage-parent/stage-$TAG
I="python3 $NEW/src/installer/operations/install-nova-combined-runtime.py"
python3 "$NEW/tools/application-release/NovaCombinedCandidate.py" stage "$COMB" "$SHA" "$P" "$S"
$I preflight-upgrade "$COMB" "$SHA" "$P" "$S" [--license-keys ...] [--release-keys ...]

Erwartet: PASS: combined Nova update preflight; no update or activation was performed.

Der Preflight prüft den akzeptierten Vorgänger erneut, kontrolliert die zustandsbehafteten Eingaben, plant das Paket-Update (simuliert mit apt-get --simulate, es wird nichts heruntergeladen) und prüft, ob der neue Kandidat Datenbank und Owner verifizieren kann. Ein fehlgeschlagener Preflight ändert nichts; behebe die Ursache und wiederhole ihn.

5. Upgrade

$I upgrade "$COMB" "$SHA" "$P" "$S" --bridge-server-certificate "$IN/ops-server.crt" --bridge-server-key "$IN/ops-server.key" \
    [--license-keys ...] [--release-keys ...]

Erwartet: PASS: combined Nova update installed and verified; rollback window remains open.

Reihenfolge der Stufen: Operations (mit Paket-Update), Host, Bridge, Node Agent, Datenbank, Owner, Application. Die Application-Stufe entwickelt das Datenbankschema innerhalb ihrer Transaktion weiter (vorher wird ein privater mariadb-dump erstellt).

Bei einem Fehler rollt der Installer alle Stufen in umgekehrter Reihenfolge zurück, stellt den Paketstand wieder her, prüft den Vorgänger und endet mit dem Journal-Status rolled-back:

FAIL: <cause>; automatically rolled back, journal state rolled-back

Panel und Websites laufen dann wieder auf dem Vorgänger. Mach vor dem nächsten Versuch mit dem Abschnitt „Rearm“ weiter.

6. Prüfen, dann akzeptieren

Prüfe die Installation (siehe Tagesbetrieb), dann:

$I accept "$COMB" "$SHA" "$P" "$S"

Erwartet: der Capability-Bericht (JSON, nova.agent-node-enrollment.v1), PASS: Nova-owned Operations runtime accepted; its previous runtime was retired. und als letzte Zeile PASS: combined Nova runtime accepted; component rollback checkpoints retired.

• accept führt die vollständige Prüfung erneut aus, einschließlich der Bereitschaft aller Settlement-Worker. Ist ein Worker noch nicht bereit, warte eine Minute und führe accept erneut aus; die Annahme lässt sich fortsetzen.
• Danach schalte neue local-explicit-Capabilities auf den Knoten frei und entferne bei Bedarf nicht mehr benötigte Pakete (siehe oben).

Wichtig: Nach der Annahme bleibt das vorherige Release als letzter guter Stand auf der Platte, die Rollback-Checkpoints sind aber weg. Es gibt keinen unterstützten Befehl zurück zum Vorgänger; der Weg zurück ist eine Wiederherstellung aus deinen eigenen Backups und Snapshots (siehe Wiederherstellung).

7. Weitere Hosts aktualisieren

Nachdem der Control-Host akzeptiert ist, auf jedem anderen Host mit einer sauberen Kopie desselben Release in $SRC:

umask 022
sh $SRC/src/operations/deploy/install-nova-node-agent.sh $SRC/src/operations /
systemctl daemon-reload
systemctl start nova-controlpanel-node-agent.service          # ein Poll; Journal prüfen
journalctl -u nova-controlpanel-node-agent.service -n 5 --no-pager
sh $SRC/src/operations/deploy/finalize-nova-node-agent-update.sh / --discard-rollback

• Auf DNS-Knoten zusätzlich systemctl restart nova-controlpanel-dns-engine.socket.
• Vor finalize stellt sh $SRC/src/operations/deploy/rollback-nova-node-agent.sh / den vorherigen Node Agent wieder her.
• Bringt ein Release ein neues Rollenpaket mit, führe auf dem Knoten erneut nova-host-bootstrap.py --mode install --roles <roles> aus; es installiert nur, was fehlt.
• Separate Web-Knoten mit Workspace-Knoten: install-nova-workspace-node.sh install und accept mit dem neuen Kandidaten (siehe Workspace).

Rearm nach einem zurückgerollten Upgrade

Nach einem automatischen oder manuellen Rollback bleiben die abgelehnten Kopien von Operations und Node Agent auf der Platte (/opt/nova-controlpanel/.operations.previous, /opt/.nova-controlpanel-node-agent.previous). Der nächste Preflight verweigert dann mit combined update predecessor operations has an unresolved rolled-back payload.

1. Lies die Fehlerzeile und das Journal. Prüfe, ob Panel und eine Website antworten.
2. Sammle vor jeder Änderung nova-support-bundle --since 2h für die Analyse.
3. Führe den Rearm aus (siehe unten).
4. Behebe die Ursache und beginne erneut bei Schritt 4 des manuellen Upgrades (mit demselben oder einem neueren Kandidaten): preflight-upgrade, upgrade, accept.

rearm-upgrade prüft den wiederhergestellten Vorgänger, vergleicht die abgelehnten Kopien byteweise mit dem abgelehnten Kandidaten und entfernt sie erst dann:

# alle Argumente stammen aus dem zurückgerollten Journal
python3 -c "import json;j=json.load(open('$J'));print(j['candidate'],j['candidate_sha256'],j['profile'],j['stage'])"
python3 <TRUSTED CHECKOUT OF THE REJECTED CANDIDATE>/src/installer/operations/install-nova-combined-runtime.py \
    rearm-upgrade <candidate> <candidate_sha256> <profile> <stage>

Erwartet: PASS: combined rolled-back upgrade rearmed; verified rejected payloads removed: operations, node. Über den Update-Kanal genügt nova-update rearm.

Wichtig: Nutze die Kopie des abgelehnten Kandidaten; eine neuere lehnt die abgelehnten Kopien ab. Das im Journal genannte Profil muss unverändert vorhanden sein – bearbeite oder lösche das Zielprofil eines fehlgeschlagenen Upgrades nicht vor dem Rearm.

Fehlerbehandlung üben (nur Testhost)

Die Installer haben Fehlerpunkte zum Üben. Nutze sie nur auf einem Testhost mit demselben Release, nie produktiv:

Ein sinnvoller Ablauf: preflight-upgrade → NOVA_INSTALLER_FAILPOINT=after-activation ... upgrade (schlägt fehl, automatischer Rollback, Journal rolled-back) → rearm-upgrade → preflight-upgrade → upgrade → accept.

Betriebssystem-Updates

Jederzeit erlaubt, auch zwischen Upgrade und Annahme:

• apt-get update && apt-get upgrade und unattended-upgrades;
• ein Neustart für einen neuen Kernel (siehe Wiederherstellung);
• apt-mark hold (Nova bewegt nie ein gehaltenes Paket; ein Upgrade, das eine neuere Version davon braucht, wird verweigert, bis du den Hold aufhebst);
• zusätzliche Pakete installieren, außer dem jeweils anderen Webserver und den SQL-Map-Paketen der Legacy-Basis (dovecot-mysql, postfix-mysql, pure-ftpd-mysql);
• apt-get autoremove.

Nicht erlaubt (das nächste verify, accept oder Upgrade lehnt den Host ab):

• ein Paket entfernen, das Nova benötigt;
• unter die Sperrliste herunterstufen;
• ein Paket aus einem anderen Quellpaket ersetzen (Fremd-Repository);
• ein Distributions-Upgrade (z. B. von noble auf das nächste Release).

Paketebene nach einem OS-Update prüfen (aus der Kopie des aktiven Kandidaten):

STAGE=$(python3 -c "import json;print(json.load(open('$J'))['stage'])")
PKG=$STAGE/payload/packages.tar.gz
bash $SRC/src/installer/operations/bootstrap-nova-operations-runtime.sh verify-packages \
    $STAGE/src/operations / "$PLATFORM" apache "$PKG" "$(sha256sum "$PKG" | cut -d' ' -f1)"

Bricht der Preflight mit package update dependencies unsatisfiable on this host ab, trägt der Host bereits neuere Distributionspakete, als das Bundle erwartet. Es hat sich nichts geändert. Installiere die genannten Pakete aus dem Distributionsarchiv (z. B. apt-get install php8.3-gd) und wiederhole den Preflight.

Fehlercodes

Codes erscheinen im Status als last_error_code und in der CLI als FAIL [...].