Zertifikate

Überblick

Nova verwendet auf seinen eigenen Hosts zwei Arten von Zertifikaten:

• das Panel-Zertifikat (/etc/nova-controlpanel/tls/panel.crt, Schlüssel panel.key): ein öffentlich vertrauenswürdiges Zertifikat, das das Panel, die Operations-Bridge und die internen Secret-Lease-Listener präsentieren;
• die Agent-Fabric: private CAs und Mutual-TLS-Zertifikate zwischen dem Control-Host und jedem Node Agent.

Zertifikate für Kunden-Websites (ACME) behandelt dieses Kapitel nicht.

Bestand

Ein Leaf-Zertifikat wird nie über die Laufzeit seiner CA hinaus ausgestellt: Die Fabric begrenzt die Gültigkeit auf die vollen Tage, die der CA noch bleiben, und verweigert die Ausstellung, wenn der CA weniger als ein Tag bleibt.

Ablauf im Blick behalten

• Fleet-Ansicht. Jeder Node Agent meldet in agent.health den Ablauf seiner eigenen Fabric-Zugangsdaten (Client-Bundle, Agent-CA, Lease-Bundles, Lease-Vertrauensanker) und des Coordinator-Zertifikats, das er gesehen hat. Betrieb & Diagnose → Fleet & Agenten zeigt pro Node die Spalte Fabric-Zertifikate und die Karte Zertifikate bald fällig: Warnung ab 60 Tagen oder weniger, kritisch ab 14 Tagen oder weniger (oder abgelaufen). Ein Node mit älterem Node Agent zeigt Nicht gemeldet.
• Panel-Zertifikat: nova-panel-certificate.sh status [--warn-days=30] [--fail-on-warning].

Kommandozeile für die Fabric. Auf jedem Host:

sh /opt/nova-controlpanel/application/current/src/installer/operations/nova-agent-fabric.sh status \
    "$PKI" /etc/nova-controlpanel/operations/agent-coordinator /etc/nova-controlpanel-node-agent --warn-days=60

Der Befehl gibt jedes Zertifikat mit not_after, days_remaining und ok/warning/expired aus. Mit --fail-on-warning endet er mit Exit-Code 2, sobald nicht alles in Ordnung ist – geeignet für eine Monitoring-Prüfung.

Node-Agent-Zertifikate erneuern (ohne Ausfall)

Private Schlüssel verlassen den Node nie; übertragen werden nur Anfragen und Zertifikate. Auf dem Node ist STATE das Node-State-Verzeichnis der Registrierung und CONFIG gleich /etc/nova-controlpanel-node-agent; auf dem Control-Host brauchst du PKI, das Operations-Root und OPERATIONS_DATABASE wie bei node-register.

# Node: neue Schlüssel und Anfragen für die Agent-Identität und jede installierte Lease-Identität
sh nova-agent-fabric.sh node-renew-request "$STATE" "$CONFIG"
# $STATE/renewal/request auf den Control-Host kopieren, dann:
sh nova-agent-fabric.sh node-renew-sign "$PKI" ./request ./renewed
# ./renewed auf den Node kopieren, dann:
sh nova-agent-fabric.sh node-renew-install "$STATE" ./renewed "$CONFIG"
# Control-Host: den Pin des Coordinators auf das erneuerte Agent-Zertifikat umstellen
OPERATIONS_DATABASE=... sh nova-agent-fabric.sh node-renew-register "$PKI" ./renewed "$OPERATIONS_ROOT"
# Node: das erneuerte Agent-Bundle zum installierten machen
sh nova-agent-fabric.sh node-renew-finish "$STATE" "$CONFIG"

Warum dabei kein Poll verloren geht:

• Die Lease-Listener akzeptieren jedes Lease-Zertifikat ihrer CA für den Node. node-renew-install ersetzt die Lease-Bundles deshalb sofort; die alten bleiben in $STATE/renewal/previous/.
• Der Coordinator pinnt genau ein Agent-Zertifikat. node-renew-install legt das erneuerte Agent-Bundle deshalb nur als client-bundle.next.pem bereit. Der Node Agent probiert es, sobald der Coordinator das installierte Bundle ablehnt, und arbeitet so ab dem Moment weiter, in dem node-renew-register den Pin umstellt.
• node-renew-finish behält das alte Bundle als client-bundle.previous.pem, das der Node Agent ebenfalls probiert. Auch wenn du node-renew-finish vor node-renew-register ausführst, geht kein Poll verloren. Die nächste Erneuerung ersetzt diese Datei.

Jeder Schritt ist wiederholbar (present), verweigert Material eines anderen Nodes oder einer anderen Zertifizierungsstelle und prüft jedes Zertifikat gegen den Node-lokalen Schlüssel und die Agent-CA, der der Node bereits vertraut.

Coordinator-Zertifikat erneuern

sh nova-agent-fabric.sh coordinator-renew "$PKI" [DAYS]
sh nova-agent-fabric.sh coordinator-renew-install "$PKI" /etc/nova-controlpanel/operations/agent-coordinator \
    /etc/nova-controlpanel/operations/agent-coordinator.env

Der Coordinator behält seinen Schlüssel. Nodes prüfen ihn nur über die Agent-CA und den Namen und akzeptieren das erneuerte Zertifikat deshalb sofort. coordinator-renew-install behält server-bundle.previous.pem, startet den Coordinator neu und wartet, bis er wieder lauscht (wenige Sekunden; ein Node-Agent-Poll in diesem Fenster wird von seinem Timer einfach wiederholt). Kommt der Coordinator nicht zurück, wird das vorherige Zertifikat wiederhergestellt und der Coordinator erneut gestartet.

CA-Rotation

Wichtig: Die CA-Rotation ist in Version 1.0 nicht automatisiert. Der folgende Ablauf beschreibt das vorgesehene Vorgehen.

Neue Installationen erhalten CAs mit 3650 Tagen Gültigkeit; die Erneuerung der Leaf-Zertifikate deckt damit die Lebensdauer einer typischen Installation ab. Eine Installation aus einer früheren Version hat CAs, die so lange gelten wie ihre Leaves (standardmäßig 825 Tage). Prüfe nova-agent-fabric.sh status "$PKI" und plane eine CA-Rotation deutlich vor dem Ablauf von agent-ca.pem. Jeder Schritt hält alte und neue CA parallel vertrauenswürdig, sodass nichts unterbrochen wird.

Agent-CA (Vertrauensanker: Coordinator-ca.pem = OPERATIONS_AGENT_CA, ca.pem jedes Nodes = NOVA_AGENT_CA_FILE; beides sind OpenSSL-CA-Dateien, die ein Bundle aus zwei CAs akzeptieren):

1. Lege die Nachfolger-CA neben der aktuellen an (agent-ca.next.pem/key, 3650 Tage).
2. Installiere das Bundle aktuell + nächste als ca.pem auf dem Coordinator und jedem Node (atomarer Austausch; der Coordinator liest es beim nächsten Neustart, Nodes beim nächsten Poll).
3. Erneuere das Coordinator-Zertifikat unter der neuen CA (coordinator-renew gegen den Nachfolger) und das Agent-Zertifikat jedes Nodes (node-renew-*, signiert vom Nachfolger). Weil beide Seiten beiden CAs vertrauen, akzeptieren sie jeweils beide Zertifikatsgenerationen.
4. Sobald status kein Zertifikat der alten CA mehr zeigt, ersetzt du die Bundles durch den Nachfolger allein und machst ihn zu agent-ca.pem.

Lease-Client-CAs (Vertrauensanker: client-ca.pem jedes internen Lease-Listeners, gepinnt über das Profilfeld client_ca_sha256): Hier gelten dieselben vier Schritte je Zweck. Der Application-Installer verweigert derzeit jedoch eine Änderung des gepinnten CA-Zertifikats; die Rotation der Lease-CAs wird deshalb noch nicht unterstützt.

Panel-Zertifikat ersetzen

Die Control Plane hat keinen eigenen ACME-Client. Du ersetzt das Zertifikat an Ort und Stelle:

Schritt 1 – Dateien ablegen. Lege das neue Zertifikat (Server-Zertifikat, gefolgt von den Zwischenzertifikaten) und den unverschlüsselten Schlüssel unter den Pfaden ab, die das Installationsprofil nennt (tls.certificate_source_file, tls.private_key_source_file). So kopiert ein späteres Reconfigure oder Upgrade dieselben Dateien.

Schritt 2 – prüfen, ohne etwas zu ändern:

sh /opt/nova-controlpanel/application/current/src/installer/operations/nova-panel-certificate.sh check CERT KEY

Schritt 3 – ersetzen:

sh .../nova-panel-certificate.sh replace CERT KEY [--lease-trust-root=FILE]

check und replace verweigern, bevor sich etwas ändert:

• einen privaten Schlüssel in der Zertifikatsdatei,
• einen verschlüsselten oder nicht passenden Schlüssel,
• ein abgelaufenes, noch nicht gültiges oder weniger als --min-days (7) gültiges Zertifikat,
• ein Zertifikat ohne Kette zu einer vertrauenswürdigen Wurzel für TLS-Server (System-Trust-Store oder --ca-file),
• ein Zertifikat, das den ServerName des Panels nicht enthält,
• ein Zertifikat ohne Kette zu einem Secret-Lease-Vertrauensanker der Node Agents (--lease-trust-root sowie jede /etc/nova-controlpanel-node-agent/*-secret-lease-ca.pem auf dem Host).

Der Lease-Vertrauensanker eines Nodes ist die Datei, mit der er registriert wurde (LEASE_SERVER_CA). Verwende dafür die öffentliche Wurzel (zum Beispiel ISRG Root X1), nicht ein Zwischenzertifikat, damit ein erneuertes Zertifikat derselben CA weiter funktioniert.

replace bewahrt das installierte Paar in /etc/nova-controlpanel/tls/previous/ auf, installiert das neue Paar mit dem bisherigen Besitzer, der Gruppe und dem Modus, führt den Konfigurationstest der Control-Plane-Instanz aus, lädt apache2@nova sanft neu und prüft, bis der Panel-Endpunkt das neue Zertifikat ausliefert. Bei jedem Fehler stellt es das vorherige Paar wieder her und lädt erneut. rollback tauscht auf dieselbe Weise zurück auf previous/. Der Befehl verweigert die Arbeit, solange eine Transaktion des Application-Installers offen ist.

Mit einem ACME-Client kopiert ein Deploy-Hook die erneuerten Dateien an die Profilpfade (reguläre Dateien, niemals Symlinks) und ruft damit replace auf.