Fehlerbehebung

Dieser Leitfaden ordnet die Diagnose nach Fehlersymptomen. Grundsatz: Zuerst mit ausschließlich lesenden Abfragen Belege sammeln, erst danach Änderungen vornehmen. Halten Sie bei jedem Schritt die Beobachtungen, ausgeführten Befehle und Exit-Codes sowie Abweichungen zwischen erwartetem und tatsächlichem Verhalten fest.

Gerät nicht erreichbar (SSH-Verbindung scheitert)

Grenzen Sie den Fehler schichtweise ein, statt unterschiedliche Ebenen gemeinsam zu beurteilen:

1. Gleichen Sie die Adresse mit dem Geräteverzeichnis ab; ähnlich aussehende Adressen dürfen nicht verwechselt werden;
2. Prüfen Sie nacheinander Namensauflösung, Routing, Erreichbarkeit des SSH-Ports und Authentifizierungsverfahren;
3. War das Gerät zuvor erreichbar und fällt plötzlich aus, vergleichen Sie den Zeitpunkt mit den letzten Updates oder Neustarts. Lassen Sie bei Bedarf vor Ort die serielle Konsole oder den physischen Gerätezustand prüfen.

Start schlägt fehl oder Gerät startet wiederholt neu

1. Sammeln Sie die Startausgabe, Protokolle des vorherigen Starts (journalctl -b -1), die Ursache eines Watchdog-Resets und Dateisystemfehler;
2. Bestimmen Sie die Fehlerphase: Bootloader, Kernel, Systemumschaltung, Dienststart, Watchdog-Reset oder Auslösung durch eine Anwendung;
3. Prüfen Sie den Startzähler (bootcount). Wiederholte Fehlstarts lösen die automatische Wiederherstellung aus: Nach Erreichen des Schwellwerts folgen Wiederherstellungsmodus und Partitions-Rollback, siehe A/B-Doppelsystem und Umschaltung;
4. Prüfen Sie mit jelina-info und jelina-auto-recovery --state den aktuellen Wiederherstellungsstatus.

Schalten Sie keine Partitionen manuell um und führen Sie keinen manuellen Rollback aus, solange die Ursache ungeklärt ist. Dadurch könnte der automatische Wiederherstellungsablauf beeinträchtigt werden.

System meldet den Zustand degraded

systemctl is-system-running
systemctl --failed --no-pager

Prüfen Sie fehlgeschlagene Dienste einzeln und anschließend die zentralen Dienste. Beachten Sie: Der Ausfall optionaler plattformspezifischer Dienste bedeutet nicht zwangsläufig eine Systemstörung. Ebenso ist es normal, dass einmalig ausgeführte Dienste nach Abschluss inaktiv sind.

Update bleibt hängen

1. Prüfen Sie Updatestatus und Fortschritt (jelina-info --get ota_status --json, jelina-local-ota -s);
2. Prüfen Sie, ob ein Update auf Bestätigung wartet. Bei aktivierter lokaler Bestätigung ist dies ein vorgesehener Richtlinienzustand und kein Stillstand;
3. Prüfen Sie den Geräteagentendienst und seine Protokolle;
4. Prüfen Sie freien Speicherplatz sowie Status und Prozesse des Update-Installationswerkzeugs;
5. Prüfen Sie die Erreichbarkeit des Updatepakets, Systemuhr, Namensauflösung und Zertifikate;
6. Prüfen Sie, ob die Installation bereits abgeschlossen ist und nur noch ein Neustart oder erneutes Einhängen zur Aktivierung aussteht.

Reichen Sie während der Diagnose keine Updates wiederholt ein und bestätigen Sie sie nicht mehrfach. Löschen Sie auch keine Statusmarkierungen für ausstehende Neustarts.

Anwendung oder Container nicht verfügbar

Prüfen Sie die einzelnen Schritte getrennt: Sollzustand, Image-Download, Containererstellung, Prozesszustand, Ports und Firewall sowie den Zustand der Anwendung selbst. Häufig verwendete Befehle:

docker ps                # Containerstatus
docker logs <Containername>      # Containerprotokolle

Erstellen Sie vom System verwaltete Container oder Dienste nicht manuell neu, bevor Sie den aktuellen Zustand als Diagnosegrundlage gesichert haben.

Datenträger voll oder Root-Dateisystem schreibgeschützt

1. Vergleichen Sie Speicher- und Inode-Belegung der Root- und Datenpartition (df -hT, df -i);
2. Prüfen Sie, ob das Gerät bereits im Temporary-Root-Modus läuft (jelina-enter-tmpfs-root --status), siehe Speicher und Datenpartition;
3. Unterscheiden Sie drei Fälle: eine absichtlich schreibgeschützte Systempartition als normales Systemdesign, einen Fehler der Datenpartition oder eine nicht ordnungsgemäß eingehängte Overlay-Schicht.

Löschen Sie keine unbekannten System- oder Paketverzeichnisse. Führen Sie im Temporary-Root-Modus keine regulären Anwendungsvorgänge aus.

Registrierung fehlgeschlagen oder Cloud-Verbindung offline

1. Prüfen Sie den Registrierungsstatus (jelina-manual-register --check), siehe Geräteregistrierung und Verbindung;
2. Prüfen Sie, ob der Offline-Modus aktiv ist;
3. Prüfen Sie Systemuhr, Namensauflösung, Routing, Zertifikate und Erreichbarkeit der Cloud-Endpunkte;
4. Prüfen Sie Status und Fehlermeldungen des Registrierungsdienstes und des Geräteagenten;
5. Ordnen Sie den Fehler ein: unvollständige Erstaktivierung, ungültige Zugangsdaten, Netzwerkfehler oder Zurückweisung durch die Cloud.

Dienst startet nicht

Prüfen Sie nacheinander die Startbedingungen des Dienstes, das Vorhandensein und die Berechtigungen der Programmdateien, den Skriptinterpreter und die Verfügbarkeit benötigter Mounts.

Fehler bei Uhrzeit oder Namensauflösung

• Zeitfehler äußern sich häufig durch fehlgeschlagene Zertifikatsprüfungen oder Cloud-Authentifizierung. Vergleichen Sie Systemzeit, Hardwareuhr und Protokolle des Zeitsynchronisierungsdienstes;
• Bei Fehlern der Namensauflösung prüfen Sie den Resolver-Dienst und die Netzwerkkonfiguration. Überschreiben Sie keine vom System erzeugten Resolver-Konfigurationsdateien manuell.

Grafische Oberfläche (GUI) nicht verfügbar

Ein über SSH geöffnetes Terminal besitzt in der Regel keine Desktop-Sitzungsumgebung. Leere Anzeigevariablen bedeuten daher keinen GUI-Fehler:

1. Prüfen Sie den Hauptschalter der Oberfläche und den Umfang etwaiger Deaktivierungen;
2. Prüfen Sie Oberflächeninstanzen und Sitzungsstatus (jelina-ui-ctl list, jelina-ui-ctl sessions);
3. Prüfen Sie die aktive grafische Anmeldesitzung und untersuchen Sie Prozessstatus und Protokolle der Oberfläche in der Umgebung des betreffenden Benutzers.

Historische Belege für Neustartprobleme

Auf manchen Geräten sind Leistungsarchive und dauerhafte Protokolle aktiviert. Sie helfen, den Systemzustand vor einem Neustart nachzuvollziehen:

journalctl --list-boots              # Systemstarts auflisten
journalctl -b -1 -p warning..alert   # Warnprotokolle des vorherigen Systemstarts
ls -1t /var/log/atop | head          # Historische Leistungsarchive

Zur Ursachenanalyse unerwarteter Neustarts müssen Startliste, Protokolle des vorherigen Starts, Watchdog-Reset-Ursache, Laufzeit sowie Update- und Partitionswechselverlauf gemeinsam betrachtet werden.

Weiterführende Dokumentation

• FAQ – Antworten auf häufige Fragen
• A/B-Doppelsystem und Umschaltung – Startzähler und Rollback
• Watchdog – Überwachung des Systemzustands
• Systemstatus und Informationen – Befehle zur Statusabfrage