Anleitungen

Überblick

Kurze Abläufe für die Aufgaben, die du als Administrator tatsächlich erledigst. Jede Anleitung verweist auf das Kapitel mit den Details. Platzhalter wie in Installation.

Einen Web-Node hinzufügen

1. Prüfe, ob die Lizenz einen weiteren Node abdeckt (nova-update license status); sonst verweigert node-register ihn (Lizenz).
2. Bereite den Host vor (Voraussetzungen), hänge ein frisches, unformatiertes Volume an und nimm den Host ins private Netz auf.
3. Auf dem Node: Host-Layer --roles web, dann der Node Agent (Installation).
4. Quota-Volume: bash /opt/nova-controlpanel-node-agent/deploy/nova-web-node-quota.sh setup /dev/disk/by-id/<volume> /var/www/nova-controlpanel, dann ... verify.
5. Registriere den Node mit der Rolle web und den Lease-Zwecken user-access und web. Verwende eine neue Node-ID und Server-ID (node_ plus 22 bis 59 Zeichen, srv_ plus 8 bis 59).
6. Trage die Schreib-Capabilities in /etc/nova-controlpanel-node-agent/runtime.env ein (Liste unten) sowie NOVA_AGENT_PLATFORM_PUBLISHER=systemd-socket-v1. Führe install-nova-node-agent.sh erneut aus (seine Vorprüfung kontrolliert die Quota) und finalize-nova-node-agent-update.sh / --discard-rollback; aktiviere den Timer.
7. Als Owner: Lege einen Plattform-Server für den Node an (web_server und file_server), füge seine PHP-Runtime hinzu und gleiche den Web-PHP-Katalog ab.
8. Biete den Node in einem Plan an: Vorlagen-Selektor web.nodes. Bestehende Kunden behalten ihre Platzierung; neue Websites von Kunden in diesem Plan können den Node nutzen.
9. Workspace auf diesem Node: siehe Workspace.

Schreib-Capabilities für einen Web-Node:

platform.php-runtime.apply.v1,platform.server.apply.v1,platform.address.apply.v1,platform.config.apply.v1,platform.directive.apply.v1,web.execute.v1,web.php.apply.v1,web.php.rollback.v1

dazu der User-Access-Satz:

access.ftp-account.apply.v1,access.shell-account.apply.v1,access.webdav-account.apply.v1,scheduling.website-cron.apply.v1

Hinweis: Speichere nach dem Beitritt eines Nodes jeden Abschnitt der globalen Konfiguration und jede Direktive einmal, damit der Node die aktuellen Werte erhält; bis dahin läuft er mit Standardwerten (Tagesbetrieb).

Ein separater Web-Node muss nicht in der Fleet-Topologie stehen. DNS- und Mail-Nodes brauchen dagegen einen Topologie-Eintrag, siehe „Die Fleet-Topologie ändern“.

Einen DNS-Secondary hinzufügen

1. Neuer Host mit dem dns-Host-Layer und dem Node Agent; registriere ihn mit der Rolle dns-secondary und dem Lease-Zweck dns. Ein Secondary läuft nie auf dem Host des DNS-Primary.
2. Auf dem Node: activate-nova-bind-dynamic-zones.sh activate; Capabilities dns.secondary.apply.v1,dns.keyring.apply.v1,platform.server.apply.v1,platform.address.apply.v1,platform.config.apply.v1; nova-controlpanel-dns-engine.socket und den Agent-Timer aktivieren.
3. Als Owner: Plattform-Server nur mit dns_server, dann den Endpunkt des Nodes (öffentlicher Nameserver-FQDN mit abschließendem Punkt, private Transferadresse) unter Systemverwaltung → DNS-Server & TSIG (/nova/infrastructure/dns-fleet) oder mit PUT /api/next/v1/dns-node-endpoints/{node_id}.
4. Erlaube 53/tcp und 53/udp zwischen den Transferadressen von Primary und Secondary.
5. Nimm den Node in den Selektor dns.secondary-nodes der Pläne auf.

Nova erzeugt den TSIG-Schlüssel für das Paar, installiert die Keyrings auf beiden Nodes und repliziert die Primärzonen des Plans bei ihrer nächsten Änderung oder ihrem nächsten Abgleich.

Wichtig: Der Node muss in der Fleet-Topologie stehen (bis zu acht Secondaries). Einen noch nicht enthaltenen Node fügst du nach seiner Registrierung und vor Schritt 3 mit einem Topologiewechsel hinzu.

DNS-TSIG-Schlüssel rotieren

Als Owner unter Systemverwaltung → DNS-Server & TSIG (/nova/infrastructure/dns-fleet) oder mit POST /api/next/v1/dns-tsig-keys/rotations. Die neuen Schlüssel werden an die Keyrings verteilt, bevor die alten außer Dienst gehen. Die Seite zeigt jedes Schlüsselpaar und den Keyring-Zustand pro Node. Eine zeitgesteuerte Rotation gibt es noch nicht.

Firewall-Verwaltung aktivieren

Firewall-Änderungen brauchen einen unabhängigen Wiederherstellungsweg; deshalb bleiben sie aus, bis du ihn bereitstellst.

1. Erzeuge ein Ed25519-Schlüsselpaar außerhalb des Panel-Hosts. Bewahre den geheimen Schlüssel offline auf.
2. Auf dem Panel-Host: Installiere den öffentlichen Schlüssel (base64url, ohne Padding) als /etc/nova-controlpanel/firewall-recovery-public-key.base64 (root, 0644).
3. Auf jedem Node, dessen Firewall Nova verwaltet, trägst du in /etc/nova-controlpanel-node-agent/runtime.env als zusammengehörigen Satz ein: NOVA_AGENT_FIREWALL_RECOVERY_PUBLIC_KEY_BASE64=<same key>, NOVA_AGENT_MANAGEMENT_TCP_PORT=22, NOVA_AGENT_MANAGEMENT_PROBE_ADDRESS=<independent recovery or control address>. Dann ergänzt du platform.firewall.apply.v1 bei den Schreib-Capabilities. Prüfe mit php /opt/nova-controlpanel-node-agent/apps/node-agent/bin/verify-platform-administration-firewall-configuration.php.
4. Als Owner: Gib dem Plattform-Server die Firewall-Rolle (PATCH /api/next/v1/servers/{id} mit {"firewall_server":true}).
5. Jeder Firewall-Schreibvorgang braucht eine Wiederherstellungs-Bestätigung für genau diese Regelsatz-Revision unter /etc/nova-controlpanel/firewall-recovery/<server_id>.json, signiert außerhalb des Panel-Hosts. Ohne sie antwortet der Schreibvorgang mit 409 FIREWALL_SAFETY_REQUIRED.

Wichtig: Achte darauf, dass deine Firewall-Regeln SSH, den Panel-Port und die internen Ports (19443, Lease-Ports, Gateway-Port, DNS-Transfers) für die Fleet offen halten.

Plan, Reseller und Kunde anlegen

1. Kunden & Leistungen → Vorlagen: Lege eine Kundenvorlage mit den Limits (Dimensionen) und Platzierungen an (web.nodes, mail.nodes, database.nodes, dns.primary-nodes, dns.secondary-nodes, PHP-Modi) und veröffentliche sie. Nicht aufgeführte Dimensionen sind deaktiviert.
2. Kunden & Leistungen → Reseller / Kunden → Neu: Das Onboarding zeigt eine Vorschau (15 Minuten gültig, ohne Wirkung) und wendet sie dann mit dem Initialpasswort an. Nur Administratoren legen Reseller an.
3. Domainzuordnung: Weise die Domains des Kunden zu (verwaltete Domains). Schreibvorgänge für DNS, Mail und Web zu einer Domain brauchen diese Zuordnung.
4. Bitte den Kunden, eine Wiederherstellungsadresse zu verifizieren (Einstellungen → Sicherheit) und MFA einzurichten.

Ein Planwechsel ist eine Kontoänderung (API: PATCH /clients/{id} mit {"plan":{"template_version_id":"ctv_..."}}; eigene Abweichungen des Kunden bleiben erhalten). Ein gekündigtes Konto kann nach 24 Stunden gelöscht werden, wenn delete-preview keine Hindernisse zeigt.

Die Fleet-Topologie ändern

Damit fügst du einen Node hinzu, ergänzt eine Rolle, entfernst eine leere Rolle oder einen leeren Node oder ersetzt einen Node.

Vorbereiten

Planen

Schreibe die neue Topologie in eine neue Datei und lass Nova die Deklaration berechnen:

umask 077
php /opt/nova-controlpanel/application/current/src/api/bin/native-topology-change.php plan \
    /etc/nova-controlpanel/operations-client/agent-fleet.json $IN/agent-fleet-2.json > $IN/topology-change-2.json

Prüfe sie. Kopiere das aktive Profil nach $IN/profile-topology-2.json und ändere nur native_dns.topology_source_file (auf die neue Datei); andere Änderungen gehören in eine eigene Rekonfiguration.

Ändern, prüfen, akzeptieren

$I reconfigure "$COMB" "$SHA" $IN/profile-topology-2.json "$S" --topology-change $IN/topology-change-2.json
$I verify      "$COMB" "$SHA" $IN/profile-topology-2.json "$S"
$I accept      "$COMB" "$SHA" $IN/profile-topology-2.json "$S"

Ein rollback vor dem Akzeptieren stellt die vorherige Topologie wieder her.

Danach

• Nach einem hinzugefügten Node oder einer Rolle: Plattform-Server und Dienste, Schreib-Capabilities des Nodes, bei Bedarf fresh-installation-enable.php, Plan-Platzierungen.
• Nach einer entfernten Rolle: den Fabric-Rollenablauf mit dem reduzierten Satz ausführen.
• Nach einem entfernten Node: seine Registrierung widerrufen (OPERATIONS_DATABASE=... php /opt/nova-controlpanel/operations/bin/agent-node.php revoke NODE_ID) und den Host stilllegen.

Der Control-Plane-Node wird nie hinzugefügt oder entfernt und behält master und web.

Weitere Kurzverweise

Zertifikate erneuern

Den Ablauf siehst du unter Betrieb & Diagnose → Fleet & Agenten (Fabric-Zertifikate, Warnung ab 60 Tagen) und mit nova-panel-certificate.sh status. Vollständiges Verfahren: Zertifikate.

Eine fail2ban-Sperre aufheben

Betrieb & Diagnose → Fleet & Agenten → fail2ban-Sperren: Server wählen, Gesperrte Adressen abrufen, Entsperren. Dafür braucht der Node host-security.fail2ban.v1 in seinen Schreib-Capabilities (ein früher registrierter Node zusätzlich einen node-register-Lauf auf dem Control-Host). Auf dem Host selbst: nova-fail2ban.sh unban ADDRESS [JAIL]. Nimm Administrator- und Fleet-Netze mit nova-fail2ban.sh install --ignore-ip=... auf, damit sie nie gesperrt werden. Details: Sicherheit.

Die Lizenz installieren oder erneuern

nova-update license show-id liefert die Installations-ID. Für sie wird die Lizenz ausgestellt; installiere sie mit nova-update license install FILE (oder unter Einstellungen › Lizenz, Step-up erforderlich) und prüfe mit nova-update license status. Eine Verlängerung ist eine neue Lizenz mit späterem issued_at. Siehe Lizenz.

Einen verlorenen zweiten Faktor zurücksetzen

Hat ein Administrator (oder der Owner) den Authenticator und alle Wiederherstellungscodes verloren, führt ein Root-Operator auf dem Control-Host aus:

php /opt/nova-controlpanel/application/current/src/api/application/bin/nova-identity-mfa-break-glass.php reset <login|prn_id> '<reason>'

Prüfe vorher die Identität der anfragenden Person über einen unabhängigen Kanal. Siehe Sicherheit.

Externer SMTP-Relay

Die Mailzustellung der Application (Wiederherstellungs-, Sicherheits- und Support-Mails sowie Step-up-Codes per E-Mail) funktioniert nur, wenn der Host Mails an die Ziel-Mailserver ausliefern kann. Sperrt dein Provider oder das Netz ausgehende Verbindungen auf TCP/25, hilft auch der Umweg über den internen Mail-Node nicht. Dann richtest du einen authentifizierten SMTP-Relay ein.

Benötigte Angaben

• Hostname des Relays;
• Port 587 mit STARTTLS oder Port 465 mit implizitem TLS;
• Benutzername;
• Passwort oder ein vom Anbieter ausgestelltes App-Passwort;
• autorisierte Absenderadresse und Absendername;
• ein Server-Zertifikat einer vertrauenswürdigen CA, dessen Name zum Hostnamen des Relays passt.

Wichtig: Gib Secrets nur über das schreibgeschützte Feld der Systemkonfiguration in Nova ein. Sie gehören in kein Repository, in keine Protokolldatei und in keinen Chat.

Einrichten

Unter Einstellungen → Systemkonfiguration → Mail setzt du:

• SMTP-Zustellung aktiviert;
• SMTP-Host und Port;
• Verschlüsselung (tls für STARTTLS oder ssl für implizites TLS);
• SMTP-Benutzer und SMTP-Passwort;
• Absenderadresse und -name des Administrators.

Dieselbe Änderung ist über die authentifizierte API /api/next/v1/system-config/mail möglich. Sie ist an eine Revision gebunden und braucht die aktuelle bearbeitbare Revision, ein einmal verwendbares CSRF-Token und einen Idempotency-Key. Das Passwort ist nur schreibbar und erscheint danach nur noch als smtp_password_configured=true.

Abnahme

Bevor du E-Mail als verfügbar betrachtest, muss alles Folgende gelingen:

1. TLS verbindet sich zum konfigurierten Hostnamen mit vollständiger Zertifikatsprüfung.
2. Die SMTP-Authentifizierung gelingt, ohne Zugangsdaten preiszugeben.
3. Eine Reauthentifizierungs-Anfrage liefert 202 und stellt genau eine Nachricht in die Warteschlange.
4. Das Empfängerpostfach erhält diese Nachricht im vorgesehenen Zeitfenster.
5. Der Einmalcode wird einmal akzeptiert, erzeugt genau eine Capability-Freigabe und wird bei Wiederverwendung abgelehnt.
6. Die Mail-Warteschlange enthält keine zurückgestellten oder unzustellbaren Reste dieses Tests.
7. Browser-Benachrichtigungen funktionieren unabhängig davon weiter.

Zurücknehmen

Notiere vor der Änderung des Mail-Abschnitts dessen Revision und die nicht geheimen Werte. Bei einem Fehler stellst du die vorherigen nicht geheimen Werte über dieselbe Oberfläche oder API wieder her und löschst oder ersetzt das Relay-Passwort über den dafür vorgesehenen Secret-Ablauf. Bearbeite die Datenbank nicht direkt.

Hinweis: Browser-Push bleibt ein Benachrichtigungskanal für den Betrieb. Er ersetzt bewusst nicht die unabhängige E-Mail- oder Wiederherstellungscode-Bestätigung, die der Step-up verlangt.

Web-Statistik (Beta)

Die Nova-Web-Statistik ist in Version 1.0 eine optionale Beta pro Website, die neben AWStats/Webalizer läuft. AWStats bleibt die Standardstatistik; die Beta dient dazu, beide auf echten Servern zu vergleichen, bevor Novas Statistik AWStats in Version 1.1 ablöst.

Seitenaufrufe und Bytes sollten wenige Prozent vom „viewed“-Traffic in AWStats abweichen; eindeutige Besucher liegen niedriger (Adresskürzung, tägliche Zählung). Ist eine klassische Engine aktiv, verlinkt die Statistikseite auf deren Ausgabe (/stats/). Vorläufige Tage (heute, gestern vor Tagesabschluss) werden heller dargestellt.

Prüfungen für Betreiber

• Node: systemctl status nova-controlpanel-web-statistics.service – die JSON-Quittung enthält ein nova_beta-Objekt mit processed, failed (Code pro Website) und forgotten (Beta abgeschaltet oder Website entfernt).
• Application: nova-application-web-statistics.service gibt submitted, pending, days_recorded, unavailable (Operations oder Node-Capability nicht bereit) und purged aus.
• Die lesende Node-Capability web.statistics.collect wird bei der Registrierung für die Rolle web aktiviert. Ein früher registrierter Node erhält sie, wenn das kombinierte Upgrade auf dieses Release akzeptiert wird; nur ein Node ohne erfassten Rollensatz braucht noch einen Rollenwechsel oder eine neue Registrierung. Ein Eintrag in NOVA_AGENT_WRITE_CAPABILITIES ist nicht nötig.