KeyHelp-Fehlersuche: Ereignisprotokolle, Aufgaben-Logs, Prozess-Manager und Paketliste nutzen

Wenn auf einem KeyHelp-Server etwas nicht funktioniert, greifen viele Administratoren sofort zur Shell und durchsuchen Konfigurationsdateien. Das Panel bringt aber schon mehrere Werkzeuge mit, die den Fehler eingrenzen: die „Ereignis-Protokolle“, die „Protokolle“ der Wartungsjobs, die „Server-Dienst-Verwaltung“, den „Prozess-Manager“, die Webserver-Protokolle je Domain und die Liste der installierten Softwarepakete. Diese Anleitung zeigt an drei bewusst ausgelösten Fehlern, wo sie im Panel auftauchen und in welchen Dateien und Tabellen Sie dieselben Informationen auf dem Server finden. Sie richtet sich an Administratoren eines Servers, der wie in KeyHelp installieren und absichern eingerichtet ist. Getestet haben wir mit KeyHelp 26.1.1 auf Debian 12.15.

Voraussetzungen

• Ein Server mit KeyHelp (getestet: 26.1.1, Build 3698, Debian 12.15) und Zugang als Administrator.
• SSH-Zugang als root, um die Funde aus dem Panel in den Dateien nachzuvollziehen und Fehler zu beheben, die das Panel selbst nicht mehr erreicht.
• Ein Testkunde mit Domain. In dieser Anleitung heißt er kunde1 mit der Domain kunde1.example.de.
• Wenn Sie die Fehler wie hier selbst auslösen möchten: am besten eine Testinstanz oder ein Snapshot, kein Produktivserver.

Schritt 1: Die Werkzeuge im Panel finden

Melden Sie sich als Administrator an und öffnen Sie im Admin-Bereich „Systemstatus“. Die Seite gruppiert die Diagnosewerkzeuge in Kacheln. Für die Fehlersuche sind diese wichtig:

• „Allgemein“: „Installierte Softwarepakete“ (dazu „Aktive Sitzungen“ und das Pro-Feature „Monitoring“).
• „Prozesse“: „Prozess-Manager“ und „Server-Dienst-Verwaltung“.
• „E-Mail“: „E-Mail-Protokoll“ und „E-Mail-Warteschlange“.
• „Control Panel“: „Ereignis-Protokolle“ und „Protokolle“.

Die Webserver-Protokolle einer einzelnen Domain erreichen Sie nicht über den Systemstatus, sondern unter „Domains“ über das Symbol „Protokolle anzeigen“ in der Zeile der Domain.

Auf unserem frisch installierten Testserver stand im Ereignisprotokoll schon eine Warnung aus der Installation: „Failed to automatically acquire a Let's Encrypt certificate for server services after install. Possible reasons: hostname is not resolvable.“ Der Testserver hatte keinen öffentlich auflösbaren Hostnamen, die Meldung war also erklärbar.

Verifizieren: KeyHelp ist installiert und meldet seine Version:

keyhelp version

KeyHelp          : 26.1.1 (Build 3698)
Operating System : Debian 12.15 (64-bit)

Schritt 2: Einen Konfigurationsfehler im Ereignisprotokoll finden

Als ersten Fehler haben wir eine fehlerhafte Apache-Anweisung eingetragen: unter „Domains“ bei kunde1.example.de über „Domain bearbeiten“, Bereich „Apache-Einstellungen“, im HTTP-Feld die Zeile Header always sett X-Test "1" (Tippfehler „sett“ statt „set“). Das Panel speicherte ohne Einwand und meldete „Die Domain kunde1.example.de wurde aktualisiert.“

Geschrieben wird die Konfiguration erst beim nächsten Minutenlauf des Wartungsjobs. Im Test speicherten wir um 21:16:39 Uhr, um 21:17:01 Uhr stand unter „Systemstatus“ > „Ereignis-Protokolle“ ein Eintrag der Stufe „Kritisch“ mit dem Kanal „Maintenance (update)“:

Die Tabelle hat die Spalten „Datum“, „Stufe“, „Nachricht“, „Benutzer“, „IP-Adresse“ und „Kanal“. Am Kanal erkennen Sie, wer etwas ausgelöst hat: „User Interface“ für Klicks im Panel, „Maintenance (update)“ für den Wartungsjob. Unter „Optionen“ gibt es eine Suche über „Alle Felder“ oder einzelne Spalten.

Dieselben Einträge liegen in der KeyHelp-Datenbank in der Tabelle event_logs. Mit einer Abfrage auf die Stufen ab „Hinweis“ filtern Sie Routinemeldungen heraus:

mariadb keyhelp -e "SELECT date, level_name, channel, LEFT(message, 60) FROM event_logs WHERE level >= 250 ORDER BY id DESC LIMIT 5;"

date	level_name	channel	LEFT(message, 60)
2026-10-01 21:24:46.644918	NOTICE	User Interface	Service ftp stopped.
2026-10-01 21:24:24.556633	NOTICE	User Interface	Service ftp stopped.
2026-10-01 21:24:00.866972	NOTICE	User Interface	Service ftp stopped.
2026-10-01 21:17:01.377460	CRITICAL	Maintenance (update)	Apache reported syntax errors.\nAH00526: Syntax error on line

Die Stufe „Kritisch“ heißt in der Datenbank CRITICAL mit dem Zahlenwert 500, „Info“ ist INFO mit 200, „Hinweis“ ist NOTICE mit 250. Die drei Einträge zum FTP-Dienst stammen aus Schritt 4.

Verifizieren: Der Fehler ist echt, Apache lehnt die Konfiguration ab:

cat /etc/apache2/keyhelp/custom_vhosts/*
apache2ctl configtest

Header always sett X-Test "1"
AH00526: Syntax error on line 1 of /etc/apache2/keyhelp/custom_vhosts/kunde1_kunde1.example.de_http.conf:
first argument must be 'add', 'set', 'setifempty', 'append', 'merge', 'unset', 'echo', 'note', 'edit', or 'edit*'.
Action 'configtest' failed.

Schritt 3: Die Aufgaben-Logs unter „Protokolle“ lesen

Das Ereignisprotokoll sagt, dass etwas schiefging. Was KeyHelp in diesem Moment tat und welche Folgen der Fehler hatte, steht in den Protokollen der Wartungsjobs. Öffnen Sie „Systemstatus“ > „Protokolle“. Die Seite beschreibt sich selbst so: „Hier können Sie Protokolleinträge für alle systembezogenen Aufgaben und Wartungsarbeiten einsehen, die das Control Panel im Hintergrund durchführt.“ Unter „Protokolldatei auswählen“ standen im Test fünf Dateien zur Wahl: „Aufgaben abarbeiten | update.log“, „Aufräumarbeiten durchführen | cleanup.log“, „Speicherplatz berechnen | diskspace.log“, „master.log“ und „install.log“. Für Konfigurationsänderungen ist update.log zuständig.

Die wichtigste Zeile ist no reload due syntax error: KeyHelp lädt Apache bei einem Syntaxfehler nicht neu. Die laufenden Websites bleiben dadurch erreichbar, im Test lieferte kunde1.example.de nach dem Fehler weiter HTTP 200. Da Apache nicht neu geladen wird, gehen wir davon aus, dass auch andere Änderungen aus diesem Lauf erst nach der Korrektur aktiv werden; einzeln geprüft haben wir das nicht. Die Dateien liegen auf dem Server unter /var/log/keyhelp/cronjob/, eine Suche nach Fehlern geht schneller als das Blättern im Panel:

grep ERROR /var/log/keyhelp/cronjob/update.log

[2026-10-01 21:17:01] ERROR | Apache: syntax error: 
[2026-10-01 21:17:01] ERROR | Apache: no reload due syntax error
[2026-10-01 21:17:01] ERROR | Apache/PHP-FPM: failed to reload

Das allgemeine Apache-Fehlerprotokoll /var/log/apache2/error.log und das Journal von apache2 enthielten zu diesem Fehler im Test nichts, weil KeyHelp nach dem fehlgeschlagenen configtest auf das Neuladen verzichtete. Die Fehlermeldung „The Apache error log may have more information.“ führt hier also ins Leere. Wie die Wartungsjobs angestoßen werden, erklärt die Anleitung KeyHelp-Wartungsintervalle und keyhelp run.

Verifizieren: Wir haben das HTTP-Feld im Panel geleert und gespeichert. Im nächsten Lauf um 21:27:02 Uhr verschwand die Datei unter custom_vhosts, apache2ctl configtest meldete „Syntax OK“, und update.log zeigte „Apache: reloading apache“ ohne neue ERROR-Zeile.

Schritt 4: Einen gestoppten Dienst erkennen

Als zweiten Fehler haben wir den FTP-Server auf der Shell angehalten:

systemctl stop proftpd; systemctl is-active proftpd; date

inactive
Thu Oct  1 21:21:01 UTC 2026

Im Panel zeigt „Systemstatus“ > „Server-Dienst-Verwaltung“ den Zustand an. Die Seite teilt die Dienste in „Webhosting-Dienste“, „E-Mail-Dienste“ und „Sonstige Dienste“, ProFTPD stand nun auf „Inaktiv“. Auf dem Dashboard meldete die Kachel „Dienst-/Portüberwachung“ für „FTP“ auf Port 21 „Offline“.

„Anzeigen“ in der Spalte „Details“ öffnet die Ausgabe von systemctl status samt den letzten Journalzeilen. In der Spalte „Aktionen“ stehen die Symbole „Dienst starten“, „Dienst stoppen“ und „Dienst neu starten“. Ein Klick auf „Dienst starten“ brachte ProFTPD zurück, das Panel meldete „Der Dienst wurde gestartet.“

Zwei Beobachtungen aus dem Test sollten Sie kennen. Erstens erschien das Stoppen auf der Shell nicht im Ereignisprotokoll, auch zwei Minuten später nicht. Wer nur dort nachsieht, bemerkt einen ausgefallenen Dienst nicht. Zweitens protokollierte KeyHelp jede Dienstaktion aus dem Panel als „Service ftp stopped.“, auch die beiden Starts (siehe Abfrage in Schritt 2: Start um 21:24:00, Stopp um 21:24:24, Start um 21:24:46). Verlassen Sie sich beim Rekonstruieren also auf die Uhrzeit und das Journal des Dienstes, nicht auf den Wortlaut.

Verifizieren: Nach dem Start aus dem Panel liefen alle betroffenen Dienste:

systemctl is-active apache2 proftpd php8.2-fpm

active
active
active

Schritt 5: Einen Skriptfehler im Webserver-Protokoll finden

Der dritte Fehler betrifft eine einzelne Website: Ein PHP-Skript ruft eine nicht existierende Funktion auf und liefert HTTP 500. Im Ereignisprotokoll erschien dazu im Test kein Eintrag. Öffnen Sie unter „Domains“ in der Zeile der Domain das Symbol „Protokolle anzeigen“. Die Seite „Webserver-Protokolle“ führt Zugriffs- und Fehlerprotokoll in einer Tabelle zusammen, mit den Spalten „Datum“, „Client-IP“, „User-Agent“, „HTTP-Code“ und „Nachricht“.

Die Seite bietet außerdem „Echtzeit-Überwachung starten“ und „Aktualisieren“, die Echtzeitansicht haben wir nicht ausprobiert. Unter „Zugriffs-Protokolle“ und „Fehler-Protokolle“ lassen sich die vollständigen Dateien herunterladen. Auf dem Server liegen sie je Domain im Home-Verzeichnis des Kunden, wie die von KeyHelp erzeugte VirtualHost-Datei zeigt:

grep -E "DocumentRoot|ErrorLog|CustomLog" /etc/apache2/keyhelp/vhosts/kunde1.conf | sort -u

  DocumentRoot "/home/users/kunde1/www/"
  ErrorLog "/home/users/kunde1/logs/kunde1.example.de/error.log"
  ErrorLog "/home/users/kunde1/logs/kunde1.server.example.de/error.log"
  ErrorLog "/home/users/kunde1/logs/www.kunde1.example.de/error.log"

Verifizieren: Der Aufruf liefert 500, und die letzte Zeile im Fehlerprotokoll nennt Datei und Zeile:

tail -2 /home/users/kunde1/logs/kunde1.example.de/error.log

[Thu Oct 01 21:25:15.421410 2026] [proxy_fcgi:error] [pid 1339:tid 1397] [client 127.0.0.1:46244] AH01071: Got error 'PHP message: PHP Fatal error:  Uncaught Error: Call to undefined function undefined_function_xyz() in /home/users/kunde1/www/fehler.php:2\nStack trace:\n#0 {main}\n  thrown in /home/users/kunde1/www/fehler.php on line 2'

Schritt 6: Hängende Prozesse im Prozess-Manager beenden

Ist der Server langsam, hilft „Systemstatus“ > „Prozess-Manager“. Wir haben auf der Shell unter der Kennung kunde1 eine PHP-Endlosschleife gestartet (php -r 'while(true){}'). Der Prozess-Manager zeigte danach unter „Aktuelle CPU-Auslastung“ die Aufteilung „Durch System“ 2,50 % und „Durch Kunden“ 49,70 %. Die Test-VM hatte zwei CPU-Kerne, eine voll ausgelastete Schleife ergab also knapp 50 %. Im Reiter „Prozesse nach Benutzern“ stand kunde1 mit einem Prozess und derselben Auslastung.

„Prozesse beenden“ öffnet eine Rückfrage: „Bitte bestätigen Sie die Beendigung aller Prozesse, die unter folgendem Benutzer laufen.“ Nach „Okay“ war der Prozess weg, und das Ereignisprotokoll verzeichnete „All processes of user kunde1 killed.“ Laut Rückfrage beendet die Schaltfläche alle Prozesse des Benutzers, nicht nur den auffälligen. Die Wirkung auf laufende PHP-FPM-Prozesse haben wir nicht beobachtet. Zur „Speicher-Auslastung“ weist die Seite darauf hin, dass sie angibt, „wie viel Speicher ein Prozess verbrauchen würde, wenn er der einzige auf dem System laufende Prozess wäre“.

Verifizieren: Nach dem Beenden lief kein Prozess des Kunden mehr, die zugehörige Unit meldete den Abbruch durch ein Signal:

     Active: failed (Result: signal) since Thu 2026-10-01 21:28:18 UTC; 10s ago

Schritt 7: Versionen in der Paketliste prüfen

Bei Fehlern nach Updates oder für eine Supportanfrage brauchen Sie die genauen Versionen. „Systemstatus“ > „Installierte Softwarepakete“ listet alle Debian-Pakete mit „Name“, „Version“ und „Beschreibung“, im Test „554 Einträge gesamt“. Ein Suchfeld gab es nicht, nutzen Sie die Suchfunktion des Browsers.

Verifizieren: Die Werte entsprechen dem, was dpkg auf dem Server meldet:

dpkg-query -W -f="\${Package}\t\${Version}\n" apache2 clamav proftpd-core keyhelp

dpkg-query: no packages found matching keyhelp
apache2	2.4.68-1~deb12u1
clamav	1.4.3+dfsg-1~deb12u2
proftpd-core	1.3.8+dfsg-4+deb12u5

KeyHelp selbst ist kein Debian-Paket und taucht deshalb nicht in der Liste auf. Seine Version zeigt keyhelp version (Schritt 1).

Typische Fehler

• „Apache reported syntax errors.“ im Ereignisprotokoll: Eine Anweisung in den Apache-Einstellungen einer Domain ist fehlerhaft. Die Meldung nennt Datei und Zeile. Korrigieren Sie das Feld im Panel, nicht nur die Datei, sonst schreibt KeyHelp den Fehler beim nächsten Lauf zurück.
• Änderungen werden nicht wirksam, obwohl das Panel „wurde aktualisiert“ meldet: Suchen Sie in update.log nach „Apache: no reload due syntax error“. Im Test lud KeyHelp den Webserver wegen der fehlerhaften Anweisung nicht neu.
• Dienst ausgefallen, aber kein Eintrag im Ereignisprotokoll: Ein außerhalb des Panels gestoppter Dienst wurde im Test nicht protokolliert. Prüfen Sie die „Server-Dienst-Verwaltung“ oder die Kachel „Dienst-/Portüberwachung“ auf dem Dashboard.
• HTTP 500 ohne Hinweis im Ereignisprotokoll: Skriptfehler standen im Test in den Webserver-Protokollen der Domain, etwa „Call to undefined function undefined_function_xyz()“ im Test.

Häufige Fragen

Prüft KeyHelp Apache-Anweisungen schon beim Speichern?

Nein. Im Test speicherte das Panel die fehlerhafte Zeile ohne Warnung. Der Syntaxfehler fiel erst beim nächsten Minutenlauf des Wartungsjobs auf, im Test 22 Sekunden nach dem Speichern.

Wo liegen die Logdateien der Panel-Aufgaben?

Unter /var/log/keyhelp/cronjob/ (update.log, cleanup.log, diskspace.log, master.log), das Installationsprotokoll unter /var/log/keyhelp/install.log. Es sind dieselben Dateien, die Sie unter „Protokolle“ auswählen.

Wo finde ich Probleme mit E-Mails?

Im „Systemstatus“ gibt es dafür „E-Mail-Protokoll“ und „E-Mail-Warteschlange“. Diese Anleitung behandelt sie nicht, ausführlich geht es darum in KeyHelp: Mailzustellung debuggen.

Testumfang

Wir haben auf KeyHelp 26.1.1 drei Fehler ausgelöst (fehlerhafte Apache-Anweisung, gestoppter FTP-Server, PHP-Fehler mit HTTP 500) und eine Endlosschleife eines Kunden beendet, jeweils im Panel und in Dateien, Datenbank und Journal nachvollzogen. Auffällig: Dienstaktionen aus dem Panel hießen im Protokoll immer „stopped“, manuelles Stoppen blieb ungeloggt. Benachrichtigungs-Mails, E-Mail-Protokoll und Pro-Funktionen haben wir nicht geprüft. Lösen Sie auf einer Testinstanz einen Fehler aus, um die Werkzeuge vor dem Ernstfall zu kennen.

Fazit

Für die Fehlersuche in KeyHelp bietet sich diese Reihenfolge an: Ereignisprotokoll für das Was, update.log für die Folgen, Server-Dienst-Verwaltung für den Zustand der Dienste, Webserver-Protokolle für Fehler einzelner Websites und Prozess-Manager für Lastprobleme. Alle Angaben im Panel finden Sie auch auf dem Server wieder, in /var/log/keyhelp/cronjob/, in der Tabelle event_logs und unter /home/users/BENUTZER/logs/. Vorsicht bei Diensten, die außerhalb des Panels gestoppt werden: Sie hinterließen im Test im Ereignisprotokoll keine Spur.

Weiterführende Anleitungen und Quellen

• KeyHelp installieren und absichern
• KeyHelp-Wartungsintervalle verstehen und mit keyhelp run auslösen
• KeyHelp: Zusätzliche Apache-Anweisungen für Header, Rewrite und Caching
• KeyHelp: Mailzustellung debuggen mit Logs, Bounces und Reverse DNS
• KeyHelp Knowledge Base: Konfigurationsdateien und Speicherpfade
• Keyweb: KeyHelp, alle Funktionen im Überblick