Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche: Unterschied zwischen den Versionen

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
K MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/Betrieb und Fehlersuche nach OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel)
MINERVA-Rademacker (Diskussion | Beiträge)
Protokoll und Statistik über F10/F8 in der Pflege, API_KEY_INVALID bei fremdem Server-Profil; Link auf Pflege [Volltext ersetzt]
 
(2 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 7: Zeile 7:
== Protokoll ==
== Protokoll ==


Die Tabelle <code>RESTSRV_PROTO</code> enthält die '''Auffälligkeiten''' des Betriebs. Erfolgreiche Anfragen stehen dort nicht, sie stehen in der [[#Statistik|Statistik]]. Ausgenommen sind einzelne Ereignisse wie Anmeldungen am JWT-Endpunkt, siehe [[#Typische Meldungen|Typische Meldungen]].
Die Tabelle <code>RESTSRV_PROTO</code> enthält die '''Auffälligkeiten''' des Betriebs. Das Protokoll öffnen Sie in OBS in der Liste der Server-Profile der [[OBS/Kostenpflichtige Module/REST-Server/Pflege|Pflege]] mit {{F10}} und ''A Protokoll''. Erfolgreiche Anfragen stehen dort nicht, sie stehen in der [[#Statistik|Statistik]]. Ausgenommen sind einzelne Ereignisse wie Anmeldungen am JWT-Endpunkt, siehe [[#Typische Meldungen|Typische Meldungen]].


Ins Protokoll gehen:
Ins Protokoll gehen:
Zeile 51: Zeile 51:
| <code>JWTAuthentication</code> || Token konnte nicht geprüft werden
| <code>JWTAuthentication</code> || Token konnte nicht geprüft werden
|-
|-
| <code>ACME</code>, <code>ACME-WARNUNG</code>, <code>ACME-FEHLER</code> || Automatische Zertifikatserneuerung, siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]]
| <code>ACME</code>, <code>ACME-WARNUNG</code>, <code>ACME-FEHLER</code> || Automatische Zertifikatserneuerung, siehe [[OBS/Kostenpflichtige Module/REST-Server/Zertifikatserneuerung|Zertifikatserneuerung]]
|}
|}


Zeile 86: Zeile 86:
| <code>REST-Server [<Profil>] gestartet</code> || Das Server-Profil nimmt Anfragen an
| <code>REST-Server [<Profil>] gestartet</code> || Das Server-Profil nimmt Anfragen an
|-
|-
| <code>Bindung fuer <IP-Adresse>:<Port> auf Server [<Profil>] angelegt</code> || Eine Bindung ist aktiv
| <code>Bindung für <IP-Adresse>:<Port> auf Server [<Profil>] angelegt</code> || Eine Bindung ist aktiv
|-
|-
| <code>Fehler: Bindung fuer <IP-Adresse> auf Server [<Profil>] konnte nicht angelegt werden</code> || Die Bindung ist nicht aktiv
| <code>Fehler: Bindung für <IP-Adresse> auf Server [<Profil>] konnte nicht angelegt werden</code> || Die Bindung ist nicht aktiv
|-
|-
| <code>Fehler: Server [<Profil>] konnte nicht gestartet werden (<Grund>)</code> || Das Server-Profil läuft nicht. Den Grund nennt die Klammer
| <code>Fehler: Server [<Profil>] konnte nicht gestartet werden (<Grund>)</code> || Das Server-Profil läuft nicht. Den Grund nennt die Klammer
Zeile 98: Zeile 98:
| <code>Server [<Profil>]: SSL-TLS aktiv (Standard-TLS ohne Client-Cert)</code> || TLS ist eingerichtet, ohne mTLS
| <code>Server [<Profil>]: SSL-TLS aktiv (Standard-TLS ohne Client-Cert)</code> || TLS ist eingerichtet, ohne mTLS
|-
|-
| <code>Server [<Profil>]: SSL-TLS aktiv (mTLS - alle Clients muessen Cert vorlegen)</code> || TLS mit mTLS ist eingerichtet
| <code>Server [<Profil>]: SSL-TLS aktiv (mTLS - alle Clients müssen Cert vorlegen)</code> || TLS mit mTLS ist eingerichtet
|-
|-
| <code>Server [<Profil>]: Plain-HTTP aktiv (no_ssl=1, Debug-Modus)</code> || Das Profil läuft mit '''kein SSL (Plain-HTTP - nur für Debug!)'''
| <code>Server [<Profil>]: Plain-HTTP aktiv (no_ssl=1, Debug-Modus)</code> || Das Profil läuft mit '''kein SSL (Plain-HTTP - nur für Debug!)'''
Zeile 106: Zeile 106:
| <code>Fehler: Server [<Profil>]: rsv_root_cert fehlt - mTLS aktiv erfordert CA-Zertifikat</code> || '''mTLS-Modus aktiv''' ist gesetzt, '''Root-Zertifikat (ca)''' ist aber leer
| <code>Fehler: Server [<Profil>]: rsv_root_cert fehlt - mTLS aktiv erfordert CA-Zertifikat</code> || '''mTLS-Modus aktiv''' ist gesetzt, '''Root-Zertifikat (ca)''' ist aber leer
|-
|-
| <code>Warnung: Server [<Profil>]: rsv_cert traegt NUR das Server-Zertifikat, kein Zwischenzertifikat. …</code> || Die Zertifikatskette ist unvollständig. Hängen Sie das Zwischenzertifikat hinter das Server-Zertifikat an
| <code>Warnung: Server [<Profil>]: rsv_cert trägt NUR das Server-Zertifikat, kein Zwischenzertifikat. …</code> || Die Zertifikatskette ist unvollständig. Hängen Sie das Zwischenzertifikat hinter das Server-Zertifikat an
|-
|-
| <code>Server [<Profil>]: ACHTUNG, Zertifikats-Pin hat sich geändert: <neu> statt <alt>. Alle bisher ausgegebenen Zugangscodes sind damit ungültig.</code> || Der Schlüssel des Serverzertifikats hat sich geändert. Geräte mit dem alten Pin verbinden sich nicht mehr
| <code>Server [<Profil>]: ACHTUNG, Zertifikats-Pin hat sich geändert: <neu> statt <alt>. Alle bisher ausgegebenen Zugangscodes sind damit ungültig.</code> || Der Schlüssel des Serverzertifikats hat sich geändert. Geräte mit dem alten Pin verbinden sich nicht mehr
Zeile 116: Zeile 116:
| <code>TLS-Handshake erst nach Verbindungsaufbau von <IP-Adresse> (Methode …) - mit 400 abgewiesen</code> || Wie vorher, der Client hat aber erst später gesendet
| <code>TLS-Handshake erst nach Verbindungsaufbau von <IP-Adresse> (Methode …) - mit 400 abgewiesen</code> || Wie vorher, der Client hat aber erst später gesendet
|-
|-
| <code>Ungueltige Anfragezeile von <IP-Adresse> (Methode …) - mit 400 abgewiesen</code> || Die Anfrage war kein gültiges HTTP
| <code>Ungültige Anfragezeile von <IP-Adresse> (Methode …) - mit 400 abgewiesen</code> || Die Anfrage war kein gültiges HTTP
|-
|-
| <code>Verbindungs-Fehler von <IP-Adresse>: <Klasse> (<Grund>)</code> || Die Verbindung ist vor oder während des TLS-Handshakes gescheitert, z.B. fehlendes Client-Zertifikat bei mTLS
| <code>Verbindungs-Fehler von <IP-Adresse>: <Klasse> (<Grund>)</code> || Die Verbindung ist vor oder während des TLS-Handshakes gescheitert, z.B. fehlendes Client-Zertifikat bei mTLS
Zeile 122: Zeile 122:
| <code>Peer-Cert-Verifikation fehlgeschlagen: depth=…, err=… (…), subject=…</code> || Das Client-Zertifikat ließ sich nicht gegen das '''Root-Zertifikat (ca)''' prüfen
| <code>Peer-Cert-Verifikation fehlgeschlagen: depth=…, err=… (…), subject=…</code> || Das Client-Zertifikat ließ sich nicht gegen das '''Root-Zertifikat (ca)''' prüfen
|-
|-
| <code>Rate-Limit ueberschritten [<Profil>] <Verb> <Pfad> (…, key=…, retry=<n>s) [trace=…]</code> || Die Anfrage wurde mit 429 abgewiesen
| <code>Rate-Limit überschritten [<Profil>] <Verb> <Pfad> (…, key=…, retry=<n>s) [trace=…]</code> || Die Anfrage wurde mit 429 abgewiesen
|-
|-
| <code>Andrangsgrenze erreicht [<Profil>] <Verb> <Pfad> (<n> von <max>) [trace=…]</code> || '''max. Anfragen''' war erreicht, Antwort 503
| <code>Andrangsgrenze erreicht [<Profil>] <Verb> <Pfad> (<n> von <max>) [trace=…]</code> || '''max. Anfragen''' war erreicht, Antwort 503
Zeile 128: Zeile 128:
| <code>Unbehandelter Fehler [<Verb> <Pfad>] [trace=…]: <Grund></code> || Unerwarteter Fehler, Antwort 500. Für diese Anfrage gibt es keine Statistikzeile
| <code>Unbehandelter Fehler [<Verb> <Pfad>] [trace=…]: <Grund></code> || Unerwarteter Fehler, Antwort 500. Für diese Anfrage gibt es keine Statistikzeile
|-
|-
| <code>Vorheriger API-Key benutzt von <IP-Adresse> (gueltig bis <Zeitpunkt>)</code> || Ein Gerät verwendet nach einem Schlüsseltausch noch den alten API-Key. So sehen Sie, welche Geräte den neuen Zugangscode noch nicht eingelesen haben
| <code>Vorheriger API-Key benutzt von <IP-Adresse> (gültig bis <Zeitpunkt>)</code> || Ein Gerät verwendet nach einem Schlüsseltausch noch den alten API-Key. So sehen Sie, welche Geräte den neuen Zugangscode noch nicht eingelesen haben
|-
|-
| <code>JWT-Token erstellt</code>, <code>JWT-Token rotiert (Refresh)</code> || Anmeldung bzw. Erneuerung am JWT-Endpunkt war erfolgreich
| <code>JWT-Token erstellt</code>, <code>JWT-Token rotiert (Refresh)</code> || Anmeldung bzw. Erneuerung am JWT-Endpunkt war erfolgreich
Zeile 134: Zeile 134:
| <code>JWT-Logout: Sitzung gesperrt (<n> Zeilen)</code> || Die Abmeldung war erfolgreich
| <code>JWT-Logout: Sitzung gesperrt (<n> Zeilen)</code> || Die Abmeldung war erfolgreich
|-
|-
| <code>TokenStore: WIEDERVORLAGE eines verbrauchten Refresh-Token (…) - Sitzung wird gesperrt</code> || Ein bereits verbrauchtes Refresh-Token wurde erneut vorgelegt. Der Server sperrt die ganze Sitzung, siehe [[OBS/Kostenpflichtige Module/RESTServer/Anmeldung mit JWT|Anmeldung mit JWT]]
| <code>TokenStore: WIEDERVORLAGE eines verbrauchten Refresh-Token (…) - Sitzung wird gesperrt</code> || Ein bereits verbrauchtes Refresh-Token wurde erneut vorgelegt. Der Server sperrt die ganze Sitzung, siehe [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]
|-
|-
| <code>TokenStore: Sitzung konnte nicht hinterlegt werden: <Grund></code> || Die Sitzung ließ sich nicht in <code>RESTSRV_TOKEN</code> schreiben. Die Anmeldung scheitert mit 503
| <code>TokenStore: Sitzung konnte nicht hinterlegt werden: <Grund></code> || Die Sitzung ließ sich nicht in <code>RESTSRV_TOKEN</code> schreiben. Die Anmeldung scheitert mit 503
|-
|-
| <code>Idempotenz: gespeicherte Antwort zurueckgespielt (…)</code> || Eine Wiederholung mit demselben ''Idempotency-Key'' hat die gespeicherte Antwort erhalten
| <code>Idempotenz: gespeicherte Antwort zurückgespielt (…)</code> || Eine Wiederholung mit demselben ''Idempotency-Key'' hat die gespeicherte Antwort erhalten
|-
|-
| <code>Idempotenz: offene Reservierung seit <Zeitpunkt> - … manuelle Klaerung noetig</code> || Ein Schreibvorgang wurde hart abgebrochen. Ob er gewirkt hat, ist offen, siehe [[#Wartung der Server-Tabellen|Wartung der Server-Tabellen]]
| <code>Idempotenz: offene Reservierung seit <Zeitpunkt> - … manuelle Klärung nötig</code> || Ein Schreibvorgang wurde hart abgebrochen. Ob er gewirkt hat, ist offen, siehe [[#Wartung der Server-Tabellen|Wartung der Server-Tabellen]]
|-
|-
| <code>WebHook: <Kennung></code> || Ein WebHook-Endpunkt wurde aufgerufen
| <code>WebHook: <Kennung></code> || Ein WebHook-Endpunkt wurde aufgerufen
Zeile 147: Zeile 147:
== Statistik ==
== Statistik ==


Die Tabelle <code>RESTSRV_STATS</code> enthält eine Zeile je Anfrage, die bis zur Verarbeitung kommt. Dazu gehören auch Anfragen, die bei der Authentifizierung abgewiesen werden. Die Statistik zeigt damit alle verarbeiteten Anfragen, das Protokoll die Auffälligkeiten.
Die Tabelle <code>RESTSRV_STATS</code> enthält eine Zeile je Anfrage, die bis zur Verarbeitung kommt. Dazu gehören auch Anfragen, die bei der Authentifizierung abgewiesen werden. Die Statistik zeigt damit alle verarbeiteten Anfragen, das Protokoll die Auffälligkeiten. In OBS öffnet {{F8}} in den Listen der Server-Profile, Zugänge und Endpunkte der [[OBS/Kostenpflichtige Module/REST-Server/Pflege|Pflege]] die Statistik des markierten Eintrags. Die Statistik aller Anfragen öffnet {{F10}} in der Liste der Server-Profile mit ''B Statistik''.


{| class="wikitable"
{| class="wikitable"
Zeile 200: Zeile 200:
== Fehlersuche mit der Trace-ID ==
== Fehlersuche mit der Trace-ID ==


Jede Antwort des REST-Servers trägt den Header ''X-Trace-Id''. Fehlerantworten enthalten denselben Wert zusätzlich als <code>traceId</code> im <code>error</code>-Objekt. Aufbau der Fehlerantwort und Bedeutung der Codes beschreibt [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]].
Jede Antwort des REST-Servers trägt den Header ''X-Trace-Id''. Fehlerantworten enthalten denselben Wert zusätzlich als <code>traceId</code> im <code>error</code>-Objekt. Aufbau der Fehlerantwort und Bedeutung der Codes beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]].


# Lassen Sie sich die Trace-ID vom Client geben, z.B. aus dem Log der App oder aus den Entwicklerwerkzeugen des Browsers.
# Lassen Sie sich die Trace-ID vom Client geben, z.B. aus dem Log der App oder aus den Entwicklerwerkzeugen des Browsers.
Zeile 233: Zeile 233:
! Erscheinung !! Ursache !! Abhilfe
! Erscheinung !! Ursache !! Abhilfe
|-
|-
| Verbindung bricht ab oder 400 mit dem Text „Ungueltige Anfragezeile.“ || Der Client verwendet <code>https://</code>, das Profil läuft mit '''kein SSL (Plain-HTTP - nur für Debug!)''' || <code>http://</code> verwenden oder das Profil auf TLS umstellen. Im Betrieb nur TLS-Profile verwenden
| Verbindung bricht ab oder 400 mit dem Text „Ungültige Anfragezeile.“ || Der Client verwendet <code>https://</code>, das Profil läuft mit '''kein SSL (Plain-HTTP - nur für Debug!)''' || <code>http://</code> verwenden oder das Profil auf TLS umstellen. Im Betrieb nur TLS-Profile verwenden
|-
|-
| 400 mit dem Text „Dieser Port erwartet eine TLS-Verbindung. …“ || Der Client verwendet <code>http://</code> auf einem TLS-Profil || <code>https://</code> verwenden
| 400 mit dem Text „Dieser Port erwartet eine TLS-Verbindung. …“ || Der Client verwendet <code>http://</code> auf einem TLS-Profil || <code>https://</code> verwenden
Zeile 241: Zeile 241:
| 401 <code>CLIENT_CERT_INVALID</code> || Das Client-Zertifikat passt nicht zum '''mTLS-Subject''' des Zugangs || '''mTLS-Subject''' oder Client-Zertifikat korrigieren
| 401 <code>CLIENT_CERT_INVALID</code> || Das Client-Zertifikat passt nicht zum '''mTLS-Subject''' des Zugangs || '''mTLS-Subject''' oder Client-Zertifikat korrigieren
|-
|-
| 401 <code>API_KEY_INVALID</code> || API-Key unbekannt, oder nach einem Schlüsseltausch ist die Frist des vorherigen Keys abgelaufen || '''API-Key''' im Zugang prüfen. Neuen Zugangscode ausgeben
| 401 <code>API_KEY_INVALID</code> || API-Key unbekannt, Zugang gehört zu einem anderen Server-Profil, oder nach einem Schlüsseltausch ist die Frist des vorherigen Keys abgelaufen || '''API-Key''' und '''Server''' im Zugang prüfen. Neuen Zugangscode ausgeben
|-
|-
| 403 <code>FORBIDDEN_ROLE</code> „Zugriff verweigert“ || Zugang nicht '''Aktiv''', Anfrage nicht vom eingetragenen '''Host''', '''CORS-Origin''' nicht erlaubt oder Zugang für den Endpunkt nicht freigeschaltet || Grund im Protokoll nachlesen, dann Zugang bzw. Freischaltung korrigieren
| 403 <code>FORBIDDEN_ROLE</code> „Zugriff verweigert“ || Zugang nicht '''Aktiv''', Anfrage nicht vom eingetragenen '''Host''', '''CORS-Origin''' nicht erlaubt oder Zugang für den Endpunkt nicht freigeschaltet || Grund im Protokoll nachlesen, dann Zugang bzw. Freischaltung korrigieren
Zeile 251: Zeile 251:
| 415 <code>UNSUPPORTED_MEDIA_TYPE</code> bei einem Upload || '''Datei-Upload''' ist am Endpunkt nicht gesetzt || '''Datei-Upload''' setzen
| 415 <code>UNSUPPORTED_MEDIA_TYPE</code> bei einem Upload || '''Datei-Upload''' ist am Endpunkt nicht gesetzt || '''Datei-Upload''' setzen
|-
|-
| 429 <code>RATE_LIMITED</code> || Zu viele Anfragen oder Fehlanfragen im Rate-Limit-Fenster. Alle Geräte mit demselben API-Key teilen sich einen Zähler || ''Retry-After'' abwarten. Bei vielen Fehlanfragen den API-Key prüfen. Grenzen am [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profil]] anpassen
| 429 <code>RATE_LIMITED</code> || Zu viele Anfragen oder Fehlanfragen im Rate-Limit-Fenster. Alle Geräte mit demselben API-Key teilen sich einen Zähler || ''Retry-After'' abwarten. Bei vielen Fehlanfragen den API-Key prüfen. Grenzen am [[OBS/Kostenpflichtige Module/REST-Server/Server-Profile|Server-Profil]] anpassen
|-
|-
| 503 <code>SERVICE_UNAVAILABLE</code> mit ''Retry-After: 2'' || '''max. Anfragen''' am Server-Profil ist erreicht || Anfrage wiederholen. Bei Dauerlast die Grenze am Server-Profil prüfen
| 503 <code>SERVICE_UNAVAILABLE</code> mit ''Retry-After: 2'' || '''max. Anfragen''' am Server-Profil ist erreicht || Anfrage wiederholen. Bei Dauerlast die Grenze am Server-Profil prüfen
Zeile 298: Zeile 298:
|}
|}


Zu den <code>cert</code>-Befehlen siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]].
Zu den <code>cert</code>-Befehlen siehe [[OBS/Kostenpflichtige Module/REST-Server/Zertifikatserneuerung|Zertifikatserneuerung]].


{{Hinweis|Filter und Anzeigestufe wirken nur auf die Anzeige. Wiederholt sich dieselbe Meldung aus derselben Quelle, zeigt die Konsole sie höchstens einmal in 15 Minuten und nennt die Zahl der unterdrückten Wiederholungen. <code>RESTSRV_PROTO</code> enthält trotzdem jede Zeile.}}
{{Hinweis|Filter und Anzeigestufe wirken nur auf die Anzeige. Wiederholt sich dieselbe Meldung aus derselben Quelle, zeigt die Konsole sie höchstens einmal in 15 Minuten und nennt die Zahl der unterdrückten Wiederholungen. <code>RESTSRV_PROTO</code> enthält trotzdem jede Zeile.}}
Zeile 304: Zeile 304:
== Betrieb hinter einem Reverse-Proxy ==
== Betrieb hinter einem Reverse-Proxy ==


Ein Reverse-Proxy nimmt die Anfragen von außen an und reicht sie an den REST-Dienst weiter. Wann sich das lohnt, beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]].
Ein Reverse-Proxy nimmt die Anfragen von außen an und reicht sie an den REST-Dienst weiter. Wann sich das lohnt, beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Öffentliche Freigabe|Öffentliche Freigabe]].


Am Proxy richten Sie ein:
Am Proxy richten Sie ein:
Zeile 346: Zeile 346:


== Siehe auch ==
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/RESTServer/Anmeldung mit JWT|Anmeldung mit JWT]]
* [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]
* [[OBS/Kostenpflichtige Module/REST-Server/Pflege|Pflege]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/REST-Server/Zertifikatserneuerung|Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]]
* [[OBS/Kostenpflichtige Module/REST-Server/Öffentliche Freigabe|Öffentliche Freigabe]]

Aktuelle Version vom 17. November 2026, 11:53 Uhr

Betrieb und Fehlersuche

Diese Seite beschreibt, was der REST-Server im laufenden Betrieb aufzeichnet und wie Sie damit Störungen eingrenzen. Sie richtet sich an Administratoren und Betreuer der OBS-Installation sowie an Entwickler, die eine eigene Anbindung testen. Jede Antwort trägt eine Korrelations-ID. Mit ihr finden Sie zu jeder Anfrage Statistik und Protokoll, ohne dass interne Details nach außen gehen.

Protokoll

Die Tabelle RESTSRV_PROTO enthält die Auffälligkeiten des Betriebs. Das Protokoll öffnen Sie in OBS in der Liste der Server-Profile der Pflege mit F10 und A Protokoll. Erfolgreiche Anfragen stehen dort nicht, sie stehen in der Statistik. Ausgenommen sind einzelne Ereignisse wie Anmeldungen am JWT-Endpunkt, siehe Typische Meldungen.

Ins Protokoll gehen:

  • abgewiesene und fehlerhafte Anfragen, auch fachliche Ablehnungen durch das Endpunkt-Skript
  • Verbindungs- und TLS-Fehler
  • Fehler und ausgewählte Ereignisse rund um JWT und Sitzungen
  • Start des Servers, Bindungen, Zertifikat und Zertifikats-Pin
  • Skriptfehler
  • die Nutzung des vorherigen API-Keys nach einem Schlüsseltausch
  • Abweisungen durch Rate-Limit und Andrangsgrenze

Spalten

Feld Inhalt
rp_date Datum
rp_time Uhrzeit
rp_host Quelle der Zeile, siehe unten
rp_text Meldung
rp_trace Korrelations-ID der Anfrage, gleich dem Header X-Trace-Id der Antwort. Leer bei Meldungen ohne Anfragebezug

Mögliche Werte in rp_host:

Wert Bedeutung
Name des Zugangs Die Anfrage war einem Zugang zugeordnet
IP-Adresse Die Anfrage war keinem Zugang zugeordnet, z.B. bei unbekanntem API-Key, Rate-Limit oder Andrangsgrenze
System Start, Bindungen, Zertifikat, Aufräumläufe
TLS:<Profil> Verbindungs- und TLS-Fehler eines Server-Profils, Klartext auf einem TLS-Port
TLS Abgelehntes Client-Zertifikat bei mTLS
JWTAuthentication Token konnte nicht geprüft werden
ACME, ACME-WARNUNG, ACME-FEHLER Automatische Zertifikatserneuerung, siehe Zertifikatserneuerung

Fehlerzeile einer Anfrage

Je fehlgeschlagener Anfrage schreibt der Server genau eine Fehlerzeile:

Fehler <Kennung> [<Status> <HTTP-Verb> <Pfad>] [trace=<Korrelations-ID>]: <Meldung>

  • Kennung: Bei Fehlern, die der Server selbst feststellt, eine interne Kennung, z.B. Y00C71CSDV. Sie steht auch als uid in der Fehlerantwort. Setzt das Endpunkt-Skript eine Fehlerantwort (Status ab 400), steht hier dessen error.code. Fehlt das error-Objekt, steht hier der Code zum Status und als Meldung „Antwort ohne error-Objekt“.
  • Meldung: die ausführliche Begründung. Der Client erhält nur eine allgemeine Meldung, z.B. „Zugriff verweigert“.

Beispiel für einen unbekannten API-Key. Host ist hier die IP-Adresse:

Fehler Y00C71CSDV [401 GET /service/app/settings] [trace=20261117T091512345-00002A]: Kein Account mit diesem API-Key gefunden

Maskierung

Werte aus der Anfrage stammen vom Absender. Der Server schreibt sie deshalb nur bereinigt in Protokoll und Statistik:

  • Steuerzeichen erscheinen als \xNN, ungültiges UTF-8 als \uFFFD.
  • Der Pfad wird nach 200 Zeichen gekürzt und endet dann mit ....
  • Parameter im Query-String mit den Namen password, pass, token, secret, apikey, api_key, authorization, cookie und proxy-authorization erscheinen als ***.
  • Schickt der Client den Header X-Forwarded-For, hängt der Server dessen Wert als [xff=…] an die Meldung an, siehe Betrieb hinter einem Reverse-Proxy.

Typische Meldungen

Platzhalter in spitzen Klammern stehen für die Werte im Einzelfall.

Meldung Bedeutung
REST-Server [<Profil>] gestartet Das Server-Profil nimmt Anfragen an
Bindung für <IP-Adresse>:<Port> auf Server [<Profil>] angelegt Eine Bindung ist aktiv
Fehler: Bindung für <IP-Adresse> auf Server [<Profil>] konnte nicht angelegt werden Die Bindung ist nicht aktiv
Fehler: Server [<Profil>] konnte nicht gestartet werden (<Grund>) Das Server-Profil läuft nicht. Den Grund nennt die Klammer
Warnung: Kein aktiver Server in RESTSRV_SERVER konfiguriert Kein Server-Profil ist Aktiv
Fehler: Modul nicht aktiv Das Modul REST-Server ist nicht freigeschaltet. Der Dienst startet keinen Server
Server [<Profil>]: SSL-TLS aktiv (Standard-TLS ohne Client-Cert) TLS ist eingerichtet, ohne mTLS
Server [<Profil>]: SSL-TLS aktiv (mTLS - alle Clients müssen Cert vorlegen) TLS mit mTLS ist eingerichtet
Server [<Profil>]: Plain-HTTP aktiv (no_ssl=1, Debug-Modus) Das Profil läuft mit kein SSL (Plain-HTTP - nur für Debug!)
Fehler: Server [<Profil>]: SSL/TLS-Konfiguration fehlt (rsv_cert/rsv_key) - Server kann nicht starten Zertifikat (cert) oder Schlüssel (key) fehlt am Server-Profil
Fehler: Server [<Profil>]: rsv_root_cert fehlt - mTLS aktiv erfordert CA-Zertifikat mTLS-Modus aktiv ist gesetzt, Root-Zertifikat (ca) ist aber leer
Warnung: Server [<Profil>]: rsv_cert trägt NUR das Server-Zertifikat, kein Zwischenzertifikat. … Die Zertifikatskette ist unvollständig. Hängen Sie das Zwischenzertifikat hinter das Server-Zertifikat an
Server [<Profil>]: ACHTUNG, Zertifikats-Pin hat sich geändert: <neu> statt <alt>. Alle bisher ausgegebenen Zugangscodes sind damit ungültig. Der Schlüssel des Serverzertifikats hat sich geändert. Geräte mit dem alten Pin verbinden sich nicht mehr
Klartext-HTTP-Anfrage auf TLS-Port von <IP-Adresse> (<Verb> <Pfad>) - mit 400 abgewiesen Ein Client hat http:// statt https:// verwendet
Plain-HTTP-Profil: TLS-Handshake-Versuch von <IP-Adresse> Ein Client hat https:// auf einem Profil ohne TLS verwendet. Die Verbindung wurde getrennt
TLS-Handshake erst nach Verbindungsaufbau von <IP-Adresse> (Methode …) - mit 400 abgewiesen Wie vorher, der Client hat aber erst später gesendet
Ungültige Anfragezeile von <IP-Adresse> (Methode …) - mit 400 abgewiesen Die Anfrage war kein gültiges HTTP
Verbindungs-Fehler von <IP-Adresse>: <Klasse> (<Grund>) Die Verbindung ist vor oder während des TLS-Handshakes gescheitert, z.B. fehlendes Client-Zertifikat bei mTLS
Peer-Cert-Verifikation fehlgeschlagen: depth=…, err=… (…), subject=… Das Client-Zertifikat ließ sich nicht gegen das Root-Zertifikat (ca) prüfen
Rate-Limit überschritten [<Profil>] <Verb> <Pfad> (…, key=…, retry=<n>s) [trace=…] Die Anfrage wurde mit 429 abgewiesen
Andrangsgrenze erreicht [<Profil>] <Verb> <Pfad> (<n> von <max>) [trace=…] max. Anfragen war erreicht, Antwort 503
Unbehandelter Fehler [<Verb> <Pfad>] [trace=…]: <Grund> Unerwarteter Fehler, Antwort 500. Für diese Anfrage gibt es keine Statistikzeile
Vorheriger API-Key benutzt von <IP-Adresse> (gültig bis <Zeitpunkt>) Ein Gerät verwendet nach einem Schlüsseltausch noch den alten API-Key. So sehen Sie, welche Geräte den neuen Zugangscode noch nicht eingelesen haben
JWT-Token erstellt, JWT-Token rotiert (Refresh) Anmeldung bzw. Erneuerung am JWT-Endpunkt war erfolgreich
JWT-Logout: Sitzung gesperrt (<n> Zeilen) Die Abmeldung war erfolgreich
TokenStore: WIEDERVORLAGE eines verbrauchten Refresh-Token (…) - Sitzung wird gesperrt Ein bereits verbrauchtes Refresh-Token wurde erneut vorgelegt. Der Server sperrt die ganze Sitzung, siehe Anmeldung mit JWT
TokenStore: Sitzung konnte nicht hinterlegt werden: <Grund> Die Sitzung ließ sich nicht in RESTSRV_TOKEN schreiben. Die Anmeldung scheitert mit 503
Idempotenz: gespeicherte Antwort zurückgespielt (…) Eine Wiederholung mit demselben Idempotency-Key hat die gespeicherte Antwort erhalten
Idempotenz: offene Reservierung seit <Zeitpunkt> - … manuelle Klärung nötig Ein Schreibvorgang wurde hart abgebrochen. Ob er gewirkt hat, ist offen, siehe Wartung der Server-Tabellen
WebHook: <Kennung> Ein WebHook-Endpunkt wurde aufgerufen

Statistik

Die Tabelle RESTSRV_STATS enthält eine Zeile je Anfrage, die bis zur Verarbeitung kommt. Dazu gehören auch Anfragen, die bei der Authentifizierung abgewiesen werden. Die Statistik zeigt damit alle verarbeiteten Anfragen, das Protokoll die Auffälligkeiten. In OBS öffnet F8 in den Listen der Server-Profile, Zugänge und Endpunkte der Pflege die Statistik des markierten Eintrags. Die Statistik aller Anfragen öffnet F10 in der Liste der Server-Profile mit B Statistik.

Feld Inhalt
rs_date, rs_time Datum und Uhrzeit
rs_host IP-Adresse der Verbindung
rs_account Kennung des Zugangs. Leer, wenn die Anfrage keinem Zugang zugeordnet werden konnte
rs_endpoint Kennung des Endpunkts. Leer, wenn kein Endpunkt gefunden wurde
rs_cmd HTTP-Verb. Am JWT-Endpunkt Authenticate für die Anmeldung bzw. Refresh für die Erneuerung
rs_request Angefragter Pfad, maskiert wie im Protokoll, höchstens 200 Zeichen
rs_response HTTP-Status der Antwort, bei Dateien auch 206 und 416
rs_runtime Laufzeit in Millisekunden
rs_trace Korrelations-ID, gleich X-Trace-Id und rp_trace
rs_server Server-Profil, über das die Anfrage hereinkam

Keine Statistikzeile erhalten:

  • CORS-Preflight-Anfragen (OPTIONS)
  • Anfragen, die das Rate-Limit mit 429 abweist
  • Anfragen, die die Andrangsgrenze mit 503 abweist
  • die 400-Abweisungen beim Verbindungsaufbau: Klartext auf einem TLS-Port, ungültige Anfragezeile
  • Anfragen mit unerwartetem Fehler (500, Protokollzeile „Unbehandelter Fehler“)

Bis auf OPTIONS stehen diese Fälle im Protokoll.

Aufbewahrung

Tabelle Aufbewahrung
RESTSRV_PROTO Gekappt bei 40.000 Sätzen
RESTSRV_STATS Gekappt bei 100.000 Sätzen
RESTSRV_IDEMPOTENCY Gespeicherte Antworten 30 Tage
RESTSRV_TOKEN Bis Access- und Refresh-Token abgelaufen sind

Brauchen Sie Protokoll oder Statistik länger, sichern Sie die Tabellen rechtzeitig.

Fehlersuche mit der Trace-ID

Jede Antwort des REST-Servers trägt den Header X-Trace-Id. Fehlerantworten enthalten denselben Wert zusätzlich als traceId im error-Objekt. Aufbau der Fehlerantwort und Bedeutung der Codes beschreibt HTTP-Schnittstelle.

  1. Lassen Sie sich die Trace-ID vom Client geben, z.B. aus dem Log der App oder aus den Entwicklerwerkzeugen des Browsers.
  2. Suchen Sie die Statistikzeile. Sie zeigt Zugang, Endpunkt, Status, Laufzeit und Server-Profil.
  3. Suchen Sie die Protokollzeilen. Sie nennen den Grund, den der Client nicht erhält.
  4. Gibt es keine Statistikzeile, suchen Sie im Protokoll nach der Trace-ID oder nach Uhrzeit und IP-Adresse, z.B. bei Rate-Limit, Andrangsgrenze oder TLS-Fehlern.
SELECT rs_date, rs_time, rs_host, rs_cmd, rs_request, rs_response, rs_runtime, rs_server
FROM RESTSRV_STATS
WHERE rs_trace = '20261117T091512345-00002A';

SELECT rp_date, rp_time, rp_host, rp_text
FROM RESTSRV_PROTO
WHERE rp_trace = '20261117T091512345-00002A';

Meldungen ohne Anfragebezug haben keine Trace-ID, z.B. Start, Bindungen, Zertifikat oder TLS-Fehler beim Verbindungsaufbau. Sie finden diese über rp_host:

SELECT rp_date, rp_time, rp_host, rp_text
FROM RESTSRV_PROTO
WHERE rp_host IN ('System', 'TLS') OR rp_host LIKE 'TLS:%'
ORDER BY rp_date DESC, rp_time DESC;

Häufige Fehlerbilder

Die Meldung an den Client ist bewusst allgemein. Den Grund finden Sie jeweils über die Trace-ID im Protokoll.

Erscheinung Ursache Abhilfe
Verbindung bricht ab oder 400 mit dem Text „Ungültige Anfragezeile.“ Der Client verwendet https://, das Profil läuft mit kein SSL (Plain-HTTP - nur für Debug!) http:// verwenden oder das Profil auf TLS umstellen. Im Betrieb nur TLS-Profile verwenden
400 mit dem Text „Dieser Port erwartet eine TLS-Verbindung. …“ Der Client verwendet http:// auf einem TLS-Profil https:// verwenden
Verbindung bricht beim Aufbau ab, im Protokoll Verbindungs-Fehler oder Peer-Cert-Verifikation fehlgeschlagen mTLS-Modus aktiv ist gesetzt, der Client legt kein oder kein vertrauenswürdiges Client-Zertifikat vor Client-Zertifikat installieren. Root-Zertifikat (ca) am Server-Profil prüfen
401 CLIENT_CERT_INVALID Das Client-Zertifikat passt nicht zum mTLS-Subject des Zugangs mTLS-Subject oder Client-Zertifikat korrigieren
401 API_KEY_INVALID API-Key unbekannt, Zugang gehört zu einem anderen Server-Profil, oder nach einem Schlüsseltausch ist die Frist des vorherigen Keys abgelaufen API-Key und Server im Zugang prüfen. Neuen Zugangscode ausgeben
403 FORBIDDEN_ROLE „Zugriff verweigert“ Zugang nicht Aktiv, Anfrage nicht vom eingetragenen Host, CORS-Origin nicht erlaubt oder Zugang für den Endpunkt nicht freigeschaltet Grund im Protokoll nachlesen, dann Zugang bzw. Freischaltung korrigieren
404 NOT_FOUND Kein Pfad-Template passt, die Segmentzahl stimmt nicht, der Endpunkt ist nicht Aktiv oder einem anderen Server zugeordnet Endpunkt prüfen. Änderungen an Endpunkten wirken nach spätestens 60 Sekunden
405 METHOD_NOT_ALLOWED Das Endpunkt-Skript hat keine Methode für dieses HTTP-Verb Methode im Skript ergänzen. Der Header Allow nennt die vorhandenen
415 UNSUPPORTED_MEDIA_TYPE bei einem Upload Datei-Upload ist am Endpunkt nicht gesetzt Datei-Upload setzen
429 RATE_LIMITED Zu viele Anfragen oder Fehlanfragen im Rate-Limit-Fenster. Alle Geräte mit demselben API-Key teilen sich einen Zähler Retry-After abwarten. Bei vielen Fehlanfragen den API-Key prüfen. Grenzen am Server-Profil anpassen
503 SERVICE_UNAVAILABLE mit Retry-After: 2 max. Anfragen am Server-Profil ist erreicht Anfrage wiederholen. Bei Dauerlast die Grenze am Server-Profil prüfen
400 IDEMPOTENCY_KEY_MISSING Schreibende Anfrage ohne Header Idempotency-Key Der Client sendet je Vorgang einen Idempotency-Key
409 IDEMPOTENCY_UNRESOLVED Ein früherer Versuch mit demselben Key wurde hart abgebrochen Fachdaten prüfen, siehe Wartung der Server-Tabellen
503 bei Anmeldung oder Abmeldung am JWT-Endpunkt Die Sitzung ließ sich in RESTSRV_TOKEN nicht schreiben bzw. nicht sperren Protokoll unter TokenStore: prüfen. Fehlt die Tabelle, Datenbankabgleich durchführen. Eine gescheiterte Abmeldung muss der Client wiederholen
Gerät wird unerwartet abgemeldet Ein Refresh-Token wurde doppelt verwendet, die Sitzung ist gesperrt Im Protokoll nach WIEDERVORLAGE suchen
Neue Bindung antwortet nicht Bindungen liest der Dienst beim Start REST-Dienst neu starten

Konsole

Startet der REST-Server ohne den Parameter /service, zeigt er eine Konsole. Sie enthält ein Live-Log und einen festen Kopfbereich mit den gerade laufenden Anfragen. Als Windows-Dienst gestartet gibt es keine Konsole. Die Meldungen stehen dann nur in RESTSRV_PROTO.

Befehl Wirkung
show <handle> Details einer Anfrage: Anfrage, Protokollzeilen, Antwort. Das Handle steht in der Abschlusszeile der Anfrage, z.B. 7F
1 … 9 Auswahl einer Anfrage im Kopfbereich, mit mouse on auch per Klick
ps Laufende Anfragen auflisten
level <stufe> Anzeigestufe: quiet, normal oder debug. Ohne Angabe nennt die Konsole die aktuelle Stufe
filter <ausdruck> Anzeige einschränken: path=<text>, account=<name>, status>=<code>. filter aus hebt die Einschränkung auf
panel on / panel off Kopfbereich ein- bzw. ausschalten. Ausgeschaltet lässt sich das Konsolenfenster wieder zurückblättern
mouse on / mouse off Auswahl per Klick. Eingeschaltet lässt sich Text nicht mehr mit der Maus markieren
cert Zustand der automatischen Zertifikatserneuerung
cert renew Erneuerung sofort anstoßen. Der Verlauf steht im Protokoll
cert test Selbsttest gegen die Staging-Umgebung der Zertifizierungsstelle
help / ? Befehlsliste anzeigen
exit / quit Server geordnet beenden

Zu den cert-Befehlen siehe Zertifikatserneuerung.

HINWEIS: Filter und Anzeigestufe wirken nur auf die Anzeige. Wiederholt sich dieselbe Meldung aus derselben Quelle, zeigt die Konsole sie höchstens einmal in 15 Minuten und nennt die Zahl der unterdrückten Wiederholungen. RESTSRV_PROTO enthält trotzdem jede Zeile.

Betrieb hinter einem Reverse-Proxy

Ein Reverse-Proxy nimmt die Anfragen von außen an und reicht sie an den REST-Dienst weiter. Wann sich das lohnt, beschreibt Öffentliche Freigabe.

Am Proxy richten Sie ein:

  • Zertifikat: Das öffentlich gültige Zertifikat liegt am Proxy. Für die Strecke zum REST-Server genügt dort ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes, dem der Proxy vertraut. Auch dieses läuft ab und muss rechtzeitig getauscht werden.
  • Weiterleitung: per HTTPS an https://<Server des REST-Dienstes>:<Port>. Eine Weiterleitung per http:// an ein TLS-Profil weist der REST-Server mit 400 ab.
  • Header: alle HTTP-Methoden und Header unverändert durchreichen, insbesondere apikey, Authorization und Idempotency-Key. X-Trace-Id in der Antwort nicht entfernen. Den Header X-Forwarded-For mit der IP-Adresse des Clients setzen.
  • Anfragegröße: nicht kleiner als die maximale Dateigröße (MB) der Upload-Endpunkte.
  • Firewall: den Port des REST-Servers intern nur für den Proxy öffnen.

Hinter dem Proxy sieht der REST-Server als Absender nur den Proxy. Das wirkt sich so aus:

Bereich Auswirkung
Protokoll rp_host bzw. die IP-Adresse in der Meldung ist die des Proxys. Den Wert von X-Forwarded-For hängt der Server als [xff=…] an Meldungen zu einer Anfrage an, höchstens 100 Zeichen. Meldungen beim Verbindungsaufbau tragen ihn nicht
Statistik rs_host ist die IP-Adresse des Proxys. X-Forwarded-For steht dort nicht
Host-Beschränkung Der Host eines Zugangs wird mit der IP-Adresse des Proxys verglichen. Einzelne Clients lassen sich nicht unterscheiden
Rate-Limit Anfragen mit API-Key zählen wie gewohnt je Key. Alle Anfragen ohne API-Key teilen sich den Zähler der Proxy-Adresse
ACHTUNG: X-Forwarded-For ist eine Angabe des Absenders. Der REST-Server protokolliert den Wert nur. Für Host-Beschränkung und Rate-Limit verwendet er ihn nicht.

Wartung der Server-Tabellen

Die Tabellen des REST-Servers räumen sich selbst auf. Ein regelmäßiger Eingriff ist nicht nötig.

Tabelle Aufräumen
RESTSRV_PROTO, RESTSRV_STATS Gekappt, siehe Aufbewahrung
RESTSRV_IDEMPOTENCY Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen, die älter als 24 Stunden sind, meldet der Server im Protokoll und löscht sie dann. Der Aufräumlauf läuft beim Start und danach höchstens stündlich
RESTSRV_TOKEN Zeilen werden gelöscht, wenn Access- und Refresh-Token abgelaufen sind. Gesperrte Sitzungen bleiben bis dahin stehen. Der Aufräumlauf läuft beim Start und danach höchstens stündlich

Eine offene Reservierung entsteht nur, wenn ein Schreibvorgang hart abgebrochen wurde, z.B. weil der Dienst beendet wurde. Ob der Vorgang gewirkt hat, ist dann offen. Wiederholt der Client ihn, erhält er 409 IDEMPOTENCY_UNRESOLVED. Prüfen Sie anhand der Protokollzeile die Fachdaten. Soll der Client vor Ablauf der 24 Stunden weitermachen, löschen Sie den Eintrag nach der Prüfung in RESTSRV_IDEMPOTENCY.

Siehe auch