OBS/Kostenpflichtige Module/REST-Server/Server-Profile
Server-Profile
Ein Server-Profil ist eine eigenständige Instanz des REST-Servers mit eigenem Modus, eigenen Zertifikaten, eigenen Grenzen und eigenen Bindungen. Sie betreiben beliebig viele Profile parallel und trennen so öffentliche Zugriffe sauber von internen. Sie erreichen die Profile über Stammdaten → Z Weitere Stammdaten → REST-Server → Server.
Typische Einsatzfälle für mehrere Profile:
- Ein öffentliches Profil mit TLS auf Port 443 für externe Clients.
- Ein mTLS-Profil auf einem internen Port für Systeme, die ein Client-Zertifikat vorlegen müssen.
- Ein Debug-Profil mit Plain-HTTP, nur lokal erreichbar, für Tests.
Liste
Die Liste zeigt alle Server-Profile mit Name und Nr. Aktive Profile erscheinen fett.
Tasten und Schaltflächen
| Taste | Funktion |
|---|---|
| Einfg | Legt ein neues Server-Profil an. |
| ↩ Enter | Öffnet das markierte Profil in der Eingabemaske. |
| F4 | Wählt die Sortierung. |
| F6 | Schaltfläche F6 Binding: öffnet die Bindungen des markierten Profils, siehe Bindungen. |
Eingabemaske
↩ Enter öffnet die Eingabemaske REST-Server mit fünf Registerkarten. Ein neues Profil ist vorbelegt mit Aktiv, mTLS-Modus aktiv und den Standardwerten der Rate-Limits.
Die Einstellungen liest der REST-Dienst beim Start. Eine Änderung wirkt erst nach einem Neustart des Dienstes. Ausnahme sind die Angaben zur automatischen Erneuerung auf den Registerkarten 4 und 5: Sie liest der Dienst bei jeder Prüfung neu.
Registerkarte: 1 Stammdaten
| Feld | Bedeutung |
|---|---|
| Nr | Nummer des Profils von 1 bis 99. OBS schlägt die nächste freie Nummer vor. Nach dem Anlegen ist sie nicht mehr änderbar. |
| Name | Eindeutiger Name. Er erscheint in Protokoll, Statistik und bei der Zuordnung der Endpunkte. |
| zusätzliche Infos | Freitext zur Dokumentation. Wird nicht ausgewertet. |
| kein SSL (Plain-HTTP - nur für Debug!) | Das Profil spricht unverschlüsseltes HTTP. Die Zertifikatsfelder werden nicht ausgewertet. Nur für lokale Tests. |
| mTLS-Modus aktiv | Jeder Client muss ein gültiges Client-Zertifikat vorlegen. Geprüft wird gegen das Root-Zertifikat (ca). |
| keine Kompression | Antworten dieses Profils werden nicht mit gzip gepackt. Gepackte Anfragen nimmt der Server weiterhin an. Details: HTTP-Schnittstelle. |
| Aktiv | Der REST-Dienst lädt das Profil beim Start. Inaktive Profile starten nicht. |
Aus den Haken ergeben sich drei Betriebsarten:
| Betriebsart | Voraussetzungen | Anwendung |
|---|---|---|
| Standard-TLS | Zertifikat und Schlüssel | Betrieb, auch intern, hinter einem Reverse-Proxy oder im VPN. |
| mTLS | Zertifikat, Schlüssel und Root-Zertifikat, Haken mTLS-Modus aktiv | Maschine-zu-Maschine-Verbindungen, bei denen jeder Client ein Zertifikat vorlegt. |
| Plain-HTTP | Haken kein SSL (Plain-HTTP - nur für Debug!) | Nur lokale Tests. |
Falsch adressierte Verbindungen weist der Server vor jeder Verarbeitung ab:
httpan ein TLS-Profil: Antwort 400 mit dem Klartext-Hinweis „Dieser Port erwartet eine TLS-Verbindung. Die Anfrage wurde im Klartext gesendet - bitte https verwenden.“httpsan ein Plain-HTTP-Profil: Der Server trennt die Verbindung sofort. Kommt der TLS-Handshake erst nach dem Verbindungsaufbau, antwortet er mit 400. Im Protokoll steht die Meldung unter dem HostTLS:<Profil>.
Registerkarte: 2 Rate-Limits
| Feld | Standard | Bedeutung |
|---|---|---|
| Rate-Limit-Fenster | 60 | Länge des Zählfensters in Sekunden. |
| Erfolgsanfragen | 120 | Erlaubte Anfragen je Schlüssel und Fenster. |
| Fehlanfragen | 10 | Erlaubte Fehlanfragen je Schlüssel und Fenster. |
| Anfragen | 600 | Erlaubte Anfragen aller Clients des Profils je Fenster. |
| max. Verbindungen | 200 | Obergrenze gleichzeitig offener Verbindungen. Sie umfasst auch laufende Datei-Downloads. Darüber trennt der Server neue Verbindungen ohne HTTP-Antwort. Setzen Sie den Wert deutlich über den Normalbetrieb. |
| max. Anfragen | 16 | Obergrenze gleichzeitig verarbeiteter Anfragen. Darüber antwortet der Server mit 503 und Retry-After: 2. Der Client darf es also gleich erneut versuchen.
|
Die Spalte Standard nennt die Vorbelegung eines neuen Profils. Bei den vier Rate-Limit-Feldern gilt 0 als Standardwert, bei max. Verbindungen und max. Anfragen als unbegrenzt.
Jedes Profil führt eigene Zähler. Ein Profil unter Last bremst die anderen nicht aus.
Gezählt wird je Schlüssel. Schlüssel ist der Wert des Headers apikey, ohne Header die IP-Adresse. Alle Geräte mit demselben API-Key teilen sich also einen Zähler. Als Fehlanfrage zählt nur eine Anfrage, deren Zugang abgewiesen wird: API-Key unbekannt, Zugang inaktiv, Host-Beschränkung, Origin nicht erlaubt oder Client-Zertifikat passt nicht. Ein falsches Passwort bei der Anmeldung ist keine Fehlanfrage.
Was der Client bei einer Überschreitung erhält, beschreibt HTTP-Schnittstelle.
Registerkarte: 3 Zertifikate
Die Zertifikate stehen als Text im Profil. Tragen Sie sie im PEM-Format ein.
| Feld | Bedeutung |
|---|---|
| Zertifikat (cert) | Server-Zertifikat als vollständige Kette: zuerst das Server-Zertifikat, danach die Zwischenzertifikate. |
| Schlüssel (key) | Privater Schlüssel zum Server-Zertifikat. |
| Root-Zertifikat (ca) | Zertifikat der Zertifizierungsstelle, gegen das die Client-Zertifikate geprüft werden. Nur bei mTLS, sonst leer. |
Für TLS gilt:
- TLS-Version: Der Server spricht ausschließlich TLS 1.2. Die Verschlüsselungsverfahren sind auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AES-GCM oder ChaCha20-Poly1305 beschränkt.
- HSTS: Jede Antwort eines TLS-Profils trägt
Strict-Transport-Security: max-age=31536000; includeSubDomains. Ein Browser spricht die Adresse damit ein Jahr lang nur über HTTPS an. Plain-HTTP-Profile setzen den Header nicht. - Zertifikatswechsel: Bei automatischer Erneuerung tauscht der Dienst das Zertifikat selbst und startet nur das betroffene Profil neu. Bei Pflege von Hand tragen Sie die neuen PEM-Inhalte ein und starten den REST-Dienst neu. Bis dahin läuft das alte Zertifikat weiter.
Registerkarte: 4 Zertifikaterneuerung
Der REST-Server kann sein Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Einrichtung und Ablauf beschreibt Zertifikatserneuerung.
| Feld | Bedeutung |
|---|---|
| Automatische Erneuerung | deaktiviert: aus. Produktivbetrieb: Der Dienst beantragt und erneuert das Zertifikat selbst. Testbetrieb: nur für Testsysteme, siehe Testbetrieb. |
| Zertifikatsname (FQDN) | Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist. Für die Erneuerung muss er von außen auf diesen Server zeigen. |
| Kontakt bei der CA | Optional. E-Mail-Adresse, an die die Zertifizierungsstelle Warnungen schickt, wenn ein Zertifikat abzulaufen droht. |
| Zertifikat gültig bis | Ablaufdatum des aktiven Zertifikats. Erneuert wird ab 30 Tagen Restlaufzeit. |
| Testzertifikat aus Staging | Gesetzt, wenn das aktive Zertifikat aus dem Testbetrieb stammt. Ihm vertraut kein Client. |
| Zustand | idle: nichts zu tun. pending: Vorgang läuft. error: letzter Versuch fehlgeschlagen. |
| Letzte Meldung | Ergebnis des letzten Vorgangs. Im Störungsfall das erste Feld, in das Sie sehen. |
| Gesperrt bis | Nach einem Fehlschlag wartet der Dienst bis zu diesem Zeitpunkt, bevor er es erneut versucht. |
| Letzter Selbsttest am | Zeitpunkt der letzten Prüfung über das Testsystem der Zertifizierungsstelle. Sie läuft wöchentlich und prüft, ob der Server von außen erreichbar ist. |
| Selbsttest bestanden | Ergebnis dieser Prüfung. |
| Eigenes Zertifikat (Pin) | Der Dienst stellt für dieses Profil ein eigenes Zertifikat aus und berechnet den Pin. Für interne Netze ohne eigene Domain, siehe Eigenes Zertifikat und Pin. |
| Zertifikats-Pin | Pin des Schlüssels, mit dem das Profil TLS spricht, in der Form sha256/…. Der Dienst berechnet ihn. Nur Anzeige.
|
Die Felder von Zertifikat gültig bis bis Selbsttest bestanden sowie Zertifikats-Pin füllt der Dienst selbst.
Registerkarte: 5 DNS-Prüfung
| Feld | Bedeutung |
|---|---|
| Prüfart | http-01 (Port 80) oder dns-01 (DNS-Eintrag), siehe Welche Prüfart? |
| DNS-Anbieter | Nur dns-01: acme-dns, Hetzner, Cloudflare oder IONOS. |
| Adresse (acme-dns) | Nur acme-dns: Adresse der Instanz. Sie beginnt mit https://.
|
| Benutzer (acme-dns) | Nur acme-dns: Benutzer des Kontos. Bleiben Benutzer, Schlüssel und Name leer, legt der Dienst das Konto selbst an. |
| Schlüssel / API-Token | acme-dns: Passwort des Kontos. Hetzner und Cloudflare: API-Token. IONOS: API-Schlüssel in der Form Präfix.Secret.
|
| Name des TXT-Eintrags | Leer: _acme-challenge.<Zertifikatsname>. Bei CNAME-Delegation das Ziel des CNAME, bei acme-dns die fulldomain des Kontos.
|
Eigenes Zertifikat und Pin
In internen Netzen ohne eigene Domain ist keine Zertifizierungsstelle erreichbar. Für diesen Fall stellt der Dienst selbst ein Zertifikat aus, und die App vertraut über einen Pin genau diesem Schlüssel.
- Setzen Sie auf der Registerkarte 4 Zertifikaterneuerung den Haken Eigenes Zertifikat (Pin).
- Tragen Sie unter Zertifikatsname (FQDN) die Adresse ein, unter der das Gerät den Server erreicht. Auch eine IP-Adresse ist zulässig.
- Lassen Sie Zertifikat (cert) und Schlüssel (key) leer und starten Sie den REST-Dienst neu.
Fehlt Zertifikat oder Schlüssel, stellt der Dienst beim Start ein Zertifikat aus: RSA 3072, gültig 3650 Tage. Er berechnet den Pin und zeigt ihn unter Zertifikats-Pin. Ein vollständig hinterlegtes Zertifikat ändert er nie. Den Pin gibt OBS im Zugangscode an die App weiter.
Eigenes Zertifikat (Pin) schließt sich aus mit Automatische Erneuerung und mit kein SSL (Plain-HTTP - nur für Debug!). Pin-Format, Prüfung durch die App und Schlüsselwechsel beschreibt Zugangscode und Zertifikats-Pin.
Prüfungen beim Speichern
Was Sie eintragen, prüft OBS immer, auch bei einem nicht aktiven Profil:
- Nr und Name sind vergeben. Nr besteht nur aus Ziffern und liegt zwischen 1 und 99.
- Nr und Name sind eindeutig.
- Zertifikat (cert) und Schlüssel (key) liegen im PEM-Format vor. Bei kein SSL (Plain-HTTP - nur für Debug!) entfällt diese Prüfung.
- Zertifikatsname (FQDN) ist ein Name mit Punkt, ohne Adresse, Port, Leerzeichen und Platzhalter
*. Er beginnt und endet nicht mit Punkt oder Bindestrich. - Kontakt bei der CA ist eine E-Mail-Adresse.
- Eigenes Zertifikat (Pin) ist weder mit der automatischen Erneuerung noch mit kein SSL (Plain-HTTP - nur für Debug!) kombiniert.
- Adresse (acme-dns) beginnt mit
https://. Name des TXT-Eintrags ist ein gültiger Name.
Nur bei einem aktiven Profil prüft OBS zusätzlich:
- Ohne kein SSL (Plain-HTTP - nur für Debug!), ohne automatische Erneuerung und ohne Eigenes Zertifikat (Pin) sind Zertifikat und Schlüssel vorhanden.
- Bei mTLS-Modus aktiv ist das Root-Zertifikat vorhanden.
- Bei aktiver Erneuerung ist Zertifikatsname (FQDN) vergeben und kein SSL (Plain-HTTP - nur für Debug!) nicht gesetzt.
- Bei Eigenes Zertifikat (Pin) ohne hinterlegtes Zertifikat ist Zertifikatsname (FQDN) vergeben.
- Bei der Prüfart dns-01 ist ein DNS-Anbieter gewählt. Bei acme-dns ist die Adresse eingetragen, und Benutzer, Schlüssel und Name sind entweder alle gefüllt oder alle leer. Bei den übrigen Anbietern ist Schlüssel / API-Token gefüllt.
- Bei Testbetrieb fragt OBS vor dem Speichern nach, weil dem Testzertifikat kein Client vertraut.
Bindungen
Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Ein Profil kann mehrere Bindungen haben, z.B. um dieselbe TLS-Konfiguration auf zwei Ports anzubieten. Sie öffnen die Bindungen mit F6 in der Liste der Server-Profile.
Die Liste zeigt Host, Port und in Spalte D die Standard-Bindung. Aktive Bindungen erscheinen fett.
| Taste | Funktion |
|---|---|
| Einfg | Legt eine neue Bindung für dieses Profil an. |
| ↩ Enter | Öffnet die markierte Bindung in der Eingabemaske REST-Bindung. |
| F4 | Wählt die Sortierung. |
| Feld | Bedeutung |
|---|---|
| Host | IP-Adresse, auf der der Server lauscht. 0.0.0.0 steht für alle IPv4-Adressen. Eine bestimmte Adresse bindet an genau diese Netzwerkkarte. Pflichtfeld. |
| Port | TCP-Port. Pflichtfeld. |
| Server | Das Server-Profil, zu dem die Bindung gehört. Vorbelegt mit dem Profil, aus dem Sie die Liste geöffnet haben. |
| Aktiv | Der Dienst legt die Bindung beim Start an. |
| Standard | Markiert die Standard-Bindung des Profils. Ihren Port übernimmt der Dialog Zugangscode für OBS-Smart-App. Je Profil ist nur eine aktive Standard-Bindung erlaubt. |
Bindungen liest der Dienst nur beim Start. Bis zum Neustart laufen die alten Bindungen weiter. Lässt sich das Profil auf einer Bindung nicht starten, z.B. weil der Port belegt ist, steht im Protokoll:
Fehler: Server [<Name>] konnte nicht gestartet werden (…)