Fehlersuche
Typische Störungen mit Ursache und Abhilfe sowie eine Übersicht wichtiger Fehlermeldungen
Zielgruppe: Technische Administration
Überblick
Dieses Kapitel ordnet typische Störungen nach Symptom. Zu jedem Symptom findest du die wahrscheinliche Ursache und die Abhilfe. Am Ende steht eine Tabelle mit wichtigen Fehlermeldungen. Die Meldungen des Servers erscheinen in der Sprache der Oberfläche; dieses Kapitel zitiert sie in der deutschen Fassung.
Erste Anlaufstellen
| Quelle | Inhalt |
|---|---|
| Seite Systemstatus | Zustand von Datenbank, Redis, Objektspeicher, Worker und opsi-Server, siehe Systemstatus |
| Seite Jobs | vollständiges Protokoll jedes Jobs mit Fehlermeldung, siehe Jobs |
docker compose ps -a | welche Container laufen, welche beendet sind (mit Exit-Code) |
docker logs opbweb-api | Start, Migrationen, Anmeldung, LDAP |
docker logs opbweb-worker | Jobs, opsi-Verbindung |
docker logs opbweb-garage-init | Einrichtung des Objektspeichers |
| Statusleiste der Oberfläche | „Backend nicht verbunden“, wenn die API nicht antwortet; orangefarbener Hinweis bei Problemen mit dem opsi-Server |
Stack startet nicht
| Symptom | Ursache | Abhilfe |
|---|---|---|
start.sh meldet „.env fehlt – bitte ./setup-opbweb.sh ausführen (im Entwickler-Checkout: ./setup-opbweb.sh –dev).“ | keine .env | ./setup-opbweb.sh (oder cp .env.example .env) |
| API startet nicht, Log: „Secret file not found: …“ | Secret-Datei fehlt, etwa weil der Stack mit docker compose statt mit ./start.sh gestartet wurde | ./start.sh verwenden oder ./scripts/init-secrets.sh ausführen |
| API beendet sich nach etwa 60 Sekunden, Log: „Database not reachable: …“ | MariaDB nicht bereit oder Passwort passt nicht zum Volume | docker logs opbweb-db prüfen; bei geändertem db_password.txt siehe Konfiguration |
| api, worker und frontend starten nicht, garage-init mit Exit-Code ungleich 0 | Einrichtung des Objektspeichers fehlgeschlagen | docker logs opbweb-garage-init; „ERROR: No admin token found“ bedeutet fehlendes secrets/garage_admin_token.txt |
| garage-init meldet dauerhaft „Not ready yet, retrying in 2s…“ | Garage startet nicht oder das Admin-Token passt nicht | docker logs opbweb-garage; Token in secrets/ nicht nachträglich ändern |
| Log der API: „No users and no ADMIN_PASSWORD configured - no initial admin created“ | secrets/admin_password.txt leer oder fehlt bei leerer Benutzertabelle | Datei füllen bzw. von init-secrets.sh anlegen lassen, Stack neu starten |
Anmeldung
„Benutzername oder Passwort falsch.“ Bei lokalen Konten zählt jeder Fehlversuch. Nach 5 Fehlversuchen von derselben Adresse ist das Konto für diese Adresse 15 Minuten gesperrt: „Konto gesperrt bis HH:MM Uhr.“ Von anderen Adressen kann sich der Benutzer weiter anmelden; für alle gesperrt wird das Konto erst nach 50 Fehlversuchen. Nach 20 Fehlversuchen von einer Adresse (über alle Konten) antwortet oPBWeb mit „Zu viele fehlgeschlagene Anmeldungen von dieser Adresse.“ Ein Administrator hebt die Sperre unter Benutzer und Rollen mit Sperre aufheben auf; auch Passwort setzen entsperrt das Konto. Siehe Benutzer und Rollen .
Passwort des einzigen Administrators vergessen. Ein Werkzeug zum Zurücksetzen ohne Anmeldung gibt es nicht. Ein anderer Administrator (lokal oder über eine LDAP-Gruppe) kann das Passwort setzen. Lege deshalb früh ein zweites Administrator-Konto an. secrets/admin_password.txt wirkt nur beim allerersten Start.
„Konto ist deaktiviert.“ Das Konto ist in oPBWeb deaktiviert. Ein Administrator aktiviert es unter Benutzer und Rollen wieder.
LDAP-Meldungen („Verzeichnisdienst nicht erreichbar.“, „Keine Berechtigung für oPBWeb (keine passende Gruppe).“): siehe LDAP-Anmeldung .
Nach dem Neuladen der Seite oder nach etwa 15 Minuten wieder abgemeldet. Die Sitzung wird über das Cookie opbweb_refresh erneuert. Steht COOKIE_SECURE=true, während oPBWeb nur per HTTP erreichbar ist, speichert der Browser das Cookie nicht. Setze COOKIE_SECURE passend zum Protokoll und starte mit ./start.sh neu.
„Sitzung abgelaufen.“ Das Token ist ungültig oder wurde widerrufen, zum Beispiel nach einer Abmeldung, nach 7 Tagen ohne Erneuerung oder nach einem Wechsel von secrets/jwt_secret_key.txt. Neu anmelden.
Verbindung zum opsi-Server
Den Zustand zeigt die Zeile opsi-Server im Systemstatus, mit einem Eintrag je Configserver; dazu kommt der farbige Punkt vor jedem Configserver in der Ansicht Depots. Der Worker prüft alle Configserver alle 5 Minuten; nach einer Änderung kannst du unter Depots → Configserver mit Verbindung testen sofort prüfen. Die Einrichtung beschreibt Configserver .
| Symptom | Ursache | Abhilfe |
|---|---|---|
| „noch nicht geprüft“ | Worker gerade gestartet | bis zum nächsten Prüflauf warten (Standard 5 Minuten) oder Verbindung testen |
| „Kein Configserver eingerichtet (Depots → Configserver hinzufügen).“ | kein Configserver hinterlegt | unter Depots mit + einen Configserver hinzufügen |
| „Für den opsi-Server ist kein CA-Zertifikat hinterlegt (Depots → Configserver).“ | TLS-Prüfung ohne CA | Vom Server holen, Fingerabdruck vergleichen, Vertrauen, Speichern |
| TLS- oder Zertifikatsfehler trotz CA | URL mit IP-Adresse statt Hostname; das Zertifikat von opsiconfd lautet auf den FQDN | URL mit FQDN eintragen, z. B. https://opsi.example.local:4447 |
| „Der Server liefert ein anderes CA-Zertifikat als hinterlegt (Rotation?)“, im Systemstatus „Server liefert ein neues CA-Zertifikat, bitte unter Depots übernehmen“ | opsi hat seine CA erneuert | unter Depots beim betroffenen Configserver Neues Zertifikat übernehmen; bis dahin schlagen Verbindungen fehl, sobald der Server die neue CA verwendet |
| „CA-Zertifikat läuft in N Tagen ab“ | Warnung 60 Tage vor Ablauf | CA auf dem opsi-Server erneuern lassen und anschließend übernehmen |
| „… hat keine opsi-Admin-Rechte“, im Systemstatus „Anmeldung ohne Admin-Rechte“ | technischer Benutzer ist kein opsi-Admin | Benutzer in die Admin-Gruppe von opsi aufnehmen |
| HTTP 403 bei Aufrufen trotz richtigem Passwort | admin-networks in opsiconfd schließt die Adresse des Workers aus | siehe admin-networks |
| „Configserver nicht erreichbar: …“ | Netz, DNS oder Firewall zwischen Worker und Port 4447 | Erreichbarkeit aus dem Worker prüfen (siehe unten) |
| „Ein Configserver mit dieser URL ist bereits eingerichtet: …“ | dieselbe URL soll ein zweites Mal angelegt werden | vorhandenen Configserver in der Liste auswählen |
| im Job-Protokoll „Depot … gehört bereits zum Configserver … und wird übersprungen“ | derselbe opsi-Server ist unter zwei URLs eingerichtet | doppelten Configserver entfernen |
| Anmeldung am opsi-Server schlägt nach einer Wiederherstellung fehl | opsi_key_private.pem passt nicht zur Datenbank | Passwort des technischen Benutzers neu eintragen |
Erreichbarkeit aus dem Worker-Container prüfen (Beispiel; -k nur für diesen Test, weil die opsi-CA im Container nicht bekannt ist):
docker exec opbweb-worker curl -sk -o /dev/null -w '%{http_code}\n' https://opsi.example.local:4447/
Eine HTTP-Statusnummer zeigt, dass Namensauflösung und Verbindung funktionieren. Ein Fehler wie „Could not resolve host“ oder ein Timeout weist auf DNS oder Firewall hin.
Bauen
Fehler beim Bauen stehen im Protokoll des Jobs „Bauen“ unter Jobs.
| Meldung | Abhilfe |
|---|---|
| „Script Datei (Aktion) fehlt in CLIENT_DATA.“ | Das in den Produktdaten eingetragene Script fehlt im Paket. Datei hochladen oder Eintrag korrigieren. |
| „Für diese Version läuft bereits ein Build.“ | Ende des laufenden Builds abwarten. |
| „Die Version wurde während des Builds geändert. Bitte erneut bauen.“ | Während des Builds wurde gespeichert. Erneut Bauen. |
| „Version X ist freigegeben; zum Neubauen „Zurück auf Entwurf“.“ | Freigegebene Versionen sind schreibgeschützt. Zurück auf Entwurf oder Neue Version. |
| „Archiv konnte nicht erstellt werden: …“ | Details in der Meldung prüfen; häufig fehlt Speicherplatz auf dem Host oder der Objektspeicher ist nicht erreichbar. |
| „Das Paket kann so nicht gebaut werden.“ | Die Prüfung vor dem Bauen hat Fehler gefunden; jeder Fehler steht einzeln im Job-Protokoll. Korrigieren und erneut Bauen. |
Installieren und Deinstallieren
| Symptom oder Meldung | Ursache | Abhilfe |
|---|---|---|
| Installieren … ist ausgegraut bzw. „Die Version wurde noch nicht gebaut oder seit dem letzten Bauen geändert. Bitte zuerst bauen.“ | kein aktueller Build | erneut Bauen |
| „Für das Depot Depot (Stufe) ist die Rolle Releaser nötig.“ | produktives Depot, Rolle Packager | Releaser beauftragen oder Depot-Stufe prüfen, siehe Depot-Verwaltung |
| „Depot Depot ist deaktiviert oder nicht mehr vorhanden.“ | Depot in oPBWeb deaktiviert oder vom Configserver nicht mehr gemeldet | Abgleichen unter Depots, ggf. Depot aktivieren |
| „Installation fehlgeschlagen auf: …“ | Fehler von opsiconfd beim Upload oder bei depot_installPackage | Job-Protokoll und Log von opsiconfd prüfen |
| Produkt im Depot als „gesperrt“ markiert | eine abgebrochene Installation hat die Sperre hinterlassen | unter Depots → Installierte Produkte markieren und Entsperren (n), oder im Installationsdialog „Installation erzwingen (force), auch wenn das Produkt gesperrt ist“ |
| „[Depot] Depot ist zu lange durch einen anderen Job belegt.“ | ein anderer Job hält das Depot länger als 6 Stunden | unter Jobs den laufenden Job prüfen; bei hängendem Worker docker restart opbweb-worker |
| Upload großer Pakete bricht ab | Zeitlimit für Upload und Installation erreicht | OPSI_INSTALL_TIMEOUT_SECONDS erhöhen; bei vielen Depots auch JOB_TIMEOUT_SECONDS |
| Job endet mit „Abgebrochen: Zeitlimit des Jobs überschritten oder Worker beendet.“ | Job länger als JOB_TIMEOUT_SECONDS oder Worker neu gestartet | Limit erhöhen bzw. Job neu starten; eine dabei freigegebene, nirgends installierte Version ist wieder ein Entwurf |
| Version ist freigegeben, obwohl die Installation fehlschlug | oPBWeb gibt die Version beim Start des Installations-Jobs frei | gewollt; für Änderungen Zurück auf Entwurf oder Neue Version |
Worker nicht erreichbar
Symptome: Im Systemstatus meldet die Zeile Worker „kein Lebenszeichen“ oder „letztes Lebenszeichen vor N s“; Jobs bleiben im Zustand wartend; der Dateimanager unter Depots meldet „Worker nicht erreichbar.“ oder „Der Worker antwortet nicht.“
Ursachen und Abhilfe:
- Prüfe, ob der Container läuft:
docker compose ps worker. - Lies das Log:
docker logs --tail=200 opbweb-worker. Häufige Ursachen sind fehlende Secrets, keine Verbindung zu Redis oder ein Fehler beim Start. - Starte den Worker neu:
docker restart opbweb-worker. - „Der Worker antwortet nicht.“ kann auch bedeuten, dass der Worker ausgelastet ist. Er führt höchstens 10 Jobs gleichzeitig aus; Dateimanager-Aufrufe warten höchstens 60 Sekunden. Warte laufende Jobs ab und versuche es erneut.
Objektspeicher
| Symptom | Ursache | Abhilfe |
|---|---|---|
| Systemstatus Objektspeicher: „Bucket ‘packages’ fehlt“ | garage-init lief nicht oder nicht erfolgreich | docker logs opbweb-garage-init, dann ./start.sh |
| Zugriff auf den Objektspeicher verweigert, etwa nach einer Wiederherstellung | S3-Zugangsdaten im Volume garage-credentials passen nicht zum Schlüssel in Garage | ./stop.sh, docker volume rm opbweb_garage-credentials, ./start.sh |
| Dateien lassen sich nicht öffnen, Systemstatus meldet fehlende Blobs | Datenbank und Objektspeicher stammen aus unterschiedlichen Zeitpunkten | konsistente Sicherung zurückspielen, siehe Sicherung und Wiederherstellung ; betroffene Versionen neu bauen |
| Speicherplatz auf dem Host wird knapp | alte Blobs und Build-Ergebnisse gelöschter Pakete | Bereinigen … im Systemstatus
; Belegung der Volumes mit docker system df -v prüfen |
Uploads und Zeitlimits
| Symptom | Ursache | Abhilfe |
|---|---|---|
| Upload bricht mit HTTP 413 ab | Datei größer als 20 GB (client_max_body_size) | Datei verkleinern oder auf anderem Weg ins Paket bringen, etwa über die Workbench |
| „Netzwerkfehler beim Hochladen“ | Verbindung zwischen Browser und Server abgebrochen, Proxy dazwischen mit eigenem Limit | vorgeschaltete Proxys und Firewalls auf Größen- und Zeitlimits prüfen |
| lange Anfragen brechen nach etwa 11 Minuten ab | nginx-Timeout von 660 Sekunden ohne Datenfluss zur API | lange Vorgänge laufen als Jobs; bei eigenen Proxys davor ähnliche Timeouts setzen |
Hochgeladene Dateien, die nicht verarbeitet wurden, löscht der Worker nach 24 Stunden.
HTTPS und Zertifikate
| Symptom | Ursache | Abhilfe |
|---|---|---|
| HTTPS antwortet nicht, nur HTTP | certs/fullchain.pem oder certs/key.pem fehlt oder ist falsch benannt | Dateinamen prüfen; Log von opbweb-frontend zeigt „Kein TLS-Zertifikat – HTTP auf Port 80“ |
| Frontend startet nicht nach Zertifikatswechsel | Zertifikat und Schlüssel passen nicht zusammen oder sind beschädigt | docker logs opbweb-frontend; Paar prüfen |
| neues Zertifikat wird nicht ausgeliefert | nginx liest Zertifikate nur beim Start | docker restart opbweb-frontend |
| HTTP geht nach Umstellung von HTTPS zurück im Browser nicht mehr | HSTS-Header (ein Jahr) im Browser gespeichert | bei HTTPS bleiben oder HSTS-Eintrag im Browser löschen |
| Abmeldung nach Neuladen | COOKIE_SECURE passt nicht zum Protokoll | siehe Anmeldung |
Wichtige Fehlermeldungen
| Meldung | Bedeutung | Abhilfe |
|---|---|---|
| Nicht angemeldet. | kein Token mitgeschickt | neu anmelden |
| Sitzung abgelaufen. | Token ungültig oder widerrufen | neu anmelden |
| Konto nicht verfügbar. | Konto gelöscht oder deaktiviert | Administrator fragen |
| Keine Berechtigung für diese Aktion. | Rolle reicht nicht (HTTP 403) | Rolle prüfen |
| Benutzername oder Passwort falsch. | falsche Anmeldedaten oder unbekannter Benutzer | Eingabe prüfen; Sperre nach 5 Fehlversuchen von derselben Adresse |
| Zu viele fehlgeschlagene Anmeldungen von dieser Adresse. | 20 Fehlversuche von einer Adresse innerhalb von 15 Minuten | warten |
| Konto gesperrt bis HH:MM Uhr. | lokale Sperre nach Fehlversuchen | warten oder Sperre aufheben |
| Konto ist deaktiviert. | Konto in oPBWeb deaktiviert | Konto aktivieren |
| Verzeichnisdienst nicht erreichbar. | LDAP-Verbindung oder -Suche fehlgeschlagen | LDAP-Anmeldung |
| Keine Berechtigung für oPBWeb (keine passende Gruppe). | LDAP-Anmeldung ohne passende Gruppe | Gruppenzuordnung prüfen |
| Der letzte aktive Administrator kann nicht entfernt (bzw. gelöscht) werden. | Schutz des letzten Administrators | zuerst einen weiteren Administrator anlegen |
| Version X ist freigegeben (installiert) und schreibgeschützt. … | Bearbeiten einer freigegebenen Version | Zurück auf Entwurf oder Neue Version |
| Script Datei (Aktion) fehlt in CLIENT_DATA. | Script fehlt beim Bauen | Datei ergänzen |
| Die Version wurde noch nicht gebaut oder seit dem letzten Bauen geändert. Bitte zuerst bauen. | Installieren ohne aktuellen Build | Bauen |
| Für das Depot Depot (Stufe) ist die Rolle Releaser/Packager nötig. | Stufen-Regel der Depots | Rolle oder Depot-Stufe prüfen |
| [Depot] Depot ist zu lange durch einen anderen Job belegt. | Depot-Sperre länger als 6 h | hängenden Job bzw. Worker prüfen |
| Installation fehlgeschlagen auf: … | Fehler von opsiconfd | Job-Protokoll, opsiconfd-Log |
| Configserver nicht erreichbar: … | Netzwerk zum opsi-Server | Erreichbarkeit aus dem Worker prüfen |
| Kein Configserver eingerichtet (Depots → Configserver hinzufügen). | kein Configserver konfiguriert | Configserver unter Depots hinzufügen |
| Für den opsi-Server ist kein CA-Zertifikat hinterlegt (Depots → Configserver). | CA fehlt | Vom Server holen |
| Ein Configserver mit dieser URL ist bereits eingerichtet: Name | URL doppelt | vorhandenen Configserver verwenden |
| Der Server liefert ein anderes CA-Zertifikat als hinterlegt (Rotation?) | CA-Rotation | Neues Zertifikat übernehmen |
| Benutzer hat keine opsi-Admin-Rechte | technischer Benutzer ohne Admin-Rechte | Rechte in opsi vergeben |
| {Methode}: HTTP {Code} … | opsiconfd lehnt ab, bei 403 meist admin-networks | admin-networks |
| Worker nicht erreichbar. / Der Worker antwortet nicht. | Worker gestoppt oder ausgelastet | Worker nicht erreichbar |
| Download-Link ungültig oder abgelaufen. | Link älter als 2 Minuten | Download erneut anstoßen |
| Zum Löschen ist ein Probelauf nötig. / Der Probelauf fehlt oder ist älter als eine Stunde. Bitte erneut prüfen. | Bereinigung ohne gültigen Probelauf | neuen Probelauf starten |
| Es laufen gerade Importe oder Builds. Bitte nach deren Ende erneut starten. | Bereinigung blockiert | später erneut starten |
| Unerwarteter Fehler: … | nicht abgefangener Fehler im Job | Job-Protokoll und Log des Workers prüfen |
| Secret file not found: Pfad | Secret-Datei fehlt beim Start | ./start.sh bzw. init-secrets.sh |
| Database not reachable: … | Datenbank nach 60 s nicht erreichbar | Log von opbweb-db |