Fehlersuche und Support

Vorgehen

Sammle zuerst die Fakten, dann suchst du das Symptom in den Tabellen unten:

1. Meldet ein Benutzer einen Fehler, lass dir die Request-ID (req_...) geben und schlage sie mit der Support-Referenz nach.
2. Lies das kombinierte Journal (siehe Wiederherstellung).
3. Lies die Journale der betroffenen Units: journalctl -u <unit> -n 50 --no-pager.
4. Erstelle auf jedem betroffenen Host ein Support-Bundle.

Symptome rund um den Workspace haben eine eigene Tabelle im Kapitel Workspace.

Werkzeuge für den Support

Drei Werkzeuge, von der engsten zur weitesten Sicht:

Fehlerreferenz (Request-ID)

Jede API-Antwort trägt eine Request-ID: req_ plus 32 Hex-Zeichen, im Header X-Request-ID und bei Fehlern zusätzlich in error.request_id. Das Panel zeigt sie in jeder Fehlermeldung unter Technische Referenz. Kam keine Serverantwort an, zeigt das Panel stattdessen eine Browser-Referenz (brw_...) – zu der gibt es keinen Server-Trace.

Frag deine Benutzer nach dieser Referenz und schlage sie auf dem Control-Host nach (als root oder nova-controlpanel):

php /opt/nova-controlpanel/application/current/src/api/bin/nova-support-reference.php req_0123456789abcdef0123456789abcdef

Die Ausgabe ist ein JSON-Dokument (nova.support-reference.v1) mit:

• der Anfrage: Route, Status, öffentlicher Fehlercode und der interne Ablehnungscode dahinter (request.internal_code, nur für Administratoren);
• den Operationen, die die Anfrage ausgelöst hat, mit Operations-Events, Jobs, Versuchen und den Ergebnissen der Node Agents;
• Workspace-Jobs mit ihren Versuchen und Node-Befehlen.

Enthalten sind nur IDs, Zustände, Codes und Zeiten – nie Nutzdaten oder Geheimnisse. Mit --no-operations überspringst du den Operations-Teil (nützlich, wenn Operations nicht läuft).

Request-Traces werden 30 Tage aufbewahrt (nova-application-support-trace-retention.timer, stündlich). Administratoren finden dieselbe Abfrage im Panel unter Support-Referenzen → Referenz nachschlagen, Reseller mit operations.read für ihre eigenen Mandanten. Jede Abfrage wird auditiert.

Für jede abgelehnte Anfrage schreibt die Anwendung zusätzlich eine Zeile ins PHP-Fehlerlog: nova-refusal request_id=req_... status=... public_code=... internal_code=.... Der Nova-Pool setzt kein eigenes error_log; wo die Zeile landet, hängt von den PHP-FPM-Vorgaben ab:

grep -r req_... /var/log/apache2-nova/ /var/log/php8.3-fpm.log   # unter Debian: php8.4-fpm.log

Ressourcenverlauf und Operation-Timelines

• GET /history/{resourceType}/{resourceId}: geschwärzter Verlauf einer Website, Datenbank, DNS-Zone oder Mail-Ressource; im Panel aus den Backup- und Ressourcenansichten verlinkt.
• Betrieb & Diagnose (Administratoren): Operationen mit Timeline und Nachweisen, Vorfälle, Audit-Stream, Fleet und Topologie, Zertifikatsinventar.
• Aufträge & Verlauf: Jobs mit ihren Versuchen; abbrechen, wo erlaubt.

Was du an den Support schickst

1. Die Request-Referenz(en) und den Zeitpunkt des Fehlers.
2. Die Ausgabe der Support-Referenz-CLI dazu.
3. Ein Support-Bundle vom Control-Host (mit --reference für die wichtigste Anfrage) und von jedem beteiligten Node.
4. Den Zustand des kombinierten Journals (siehe Wiederherstellung).

Support-Bundle

nova-support-bundle sammelt die Diagnosefakten eines Hosts in einem Archiv, das du gefahrlos an den Support schicken kannst. Es enthält nie Geheimnisse, Passwörter, private Schlüssel, Tokens, Sitzungsdaten, Mailinhalte, Kundendateien oder Datenbankzeilen.

Der Node-Agent-Installer legt das Werkzeug auf jedem Nova-Host (Control-Host und jeder Node) als /usr/local/sbin/nova-support-bundle an (Modus 0750, nur root). Starte es als root:

nova-support-bundle                                  # letzte 24 Stunden, Archiv in /root
nova-support-bundle --since 2h --output /var/tmp     # kürzeres Fenster, anderes Verzeichnis
nova-support-bundle --reference req_0123456789abcdef0123456789abcdef   # Control-Host

Bei Erfolg gibt das Werkzeug den Archivpfad und dessen SHA-256 aus. Das Archiv heißt nova-support-<host>-<UTC-Zeit>.tar.gz, gehört root und hat Modus 0600.

Bei jedem Exit-Code ungleich 0 bleibt kein (auch kein halbes) Archiv zurück.

Inhalt

Was nie gesammelt wird

• Geheimnisspeicher und Schlüsselmaterial: /etc/nova-controlpanel/secrets/*, *.key, private Schlüssel in Bundles, TSIG-Keyrings, DKIM- und Backup-Schlüssel, Zugangsdateien, Werte aus runtime.env außerhalb der Identitäts-Allowlist.
• Das Installationsprofil und die Laufzeitkonfiguration selbst (gelesen werden nur schema_version und Fleet-Adresse/-Ports).
• Sitzungen, Cookies, Zugangsdaten, Tokens, API-Keys, Passwörter.
• Mail-Spools, Postfachinhalte, Website-Dateien, Datenbankzeilen.
• Konfigurations-Dumps (doveconf -n, named-checkconf -p, php-fpm -tt).

Schwärzung und Abschluss-Scanner

Jede Datei durchläuft zwei unabhängige Stufen:

1. Schwärzung: Schlüsselbasierte Regeln entfernen Werte von Passwort-, Secret-, Token-, Key-, Cookie-, Session- und Credential-Feldern (auch MYSQL_PWD), dazu PEM-Blöcke, SSH-Schlüssel, Bearer/Basic/Digest-Zugangsdaten, Benutzerangaben in URLs und hochentropisches Base64. E-Mail-Adressen werden zu <email:…> – einem nicht umkehrbaren Kürzel, das innerhalb eines Bundles stabil bleibt, damit du Zeilen zuordnen kannst. IP-Adressen, Commit-IDs, SHA-256-Werte und präfixierte IDs (req_…, node_…) bleiben erhalten.
2. Abschluss-Scanner: Er prüft jede Datei – auch MANIFEST.json und SUMMARY.txt – erneut auf dieselben Muster. Jeder Fund lehnt das gesamte Bundle ab (Exit 3) und nennt nur Datei, Zeile und Regel, nie den Treffer selbst.

Vor dem Versenden prüfen

Lies SUMMARY.txt, bevor du das Archiv verschickst. Eine schnelle Gegenprobe:

tar -xzOf /root/nova-support-*.tar.gz --wildcards '*/SUMMARY.txt'
tar -xzOf /root/nova-support-*.tar.gz | grep -E -- '-----BEGIN|PRIVATE KEY|MYSQL_PWD=[^[]' || echo CLEAN

Symptome und Lösungen

Host und Netzwerk

Installer-Eingaben

Ausführungskette (auf den Nodes passiert nichts)

DNS

Mail

Web

Datenbanken

Topologie, Zertifikate, fail2ban

Upgrade, Rollback, Wiederherstellung

Lizenz, Update-Kanal, Node-Zulassung

Umzug

Workspace (Kurzliste)

Mehr dazu im Kapitel Workspace.

Bekannte Grenzen von 1.0

Geplant für 1.0.1

• Stärkerer Spamschutz: Lernen aus dem Junk-Ordner, Postscreen, DNSBL und Schwellwerte pro Postfach.

Geplant für 1.1 oder später

• Eigenes Import-Konto pro Datenbank beim Umzug. In 1.0 spielt der Import Datenbank-Dumps mit administrativen Rechten auf dem Zielserver ein; prüfe deshalb die Integrität des Quellservers vor dem Umzug (siehe Umzug).
• Direktes Upgrade eines Servers der Legacy-Basis an Ort und Stelle (1.0 zieht auf neue Hosts um).
• Ubuntu 26.04 LTS (PHP 8.5 als Standard), Dark Mode, Abrechnung, Offsite-Backups.
• Public-Suffix-Liste für die Beanspruchung verwalteter Domains.

Nicht in 1.0 enthalten

• Domainregistrierung: Domains bleiben beim Registrar, nur NS- und DNSSEC-Einträge zeigen auf Nova.
• Abrechnung und Rechnungsstellung.
• PowerDNS, PostgreSQL und XFS als Web-Speicher werden nicht als Installationsoption angeboten.
• CGI-Ausführung für Websites.
• XMPP, APS, OpenVZ und die Traffic-Historie des bisherigen Hosting-Panels meldet der Umzug, übernimmt sie aber nicht; Daten aus dessen Abrechnungsmodul werden nicht importiert.

Verhalten, das du kennen solltest

• Geschützte Ordner sind mit Apache im Betrieb erprobt; der nginx-Renderer ist durch Tests abgedeckt.
• Hinter dem SNI-Router protokolliert Apache für Anfragen, die schon vor der Request-Zeile scheitern (HTTP 400), 127.0.0.1 statt der Client-Adresse. fail2ban nutzt diese Zeilen nicht.
• ClamAV prüft Anhänge, nicht den reinen Nachrichtentext. Bis zum ersten Signatur-Download (etwa 250 MB) wird Mail ungeprüft zugestellt. clamd braucht etwa 1–1,5 GB RAM.
• Solange das Fallback-Fenster eines Umzugs offen ist, lassen sich umgezogene Benutzer geschützter Ordner nicht ändern.
• Importierte geschützte Ordner zeigen als Realm-Text „Restricted“ statt des bisherigen Textes.
• Ein gelöschtes Postfach behält seinen verschlüsselten Passwort-Eintrag (für ein Rollback nötig); ohne aktives Postfach ist er unbrauchbar.