Aktuelle Version vom 26. Oktober 2026, 11:21 Uhr

Server-Profile

Ein Server im REST-Modul ist ein eigenständiges TLS-Profil mit einer eigenen HTTP-Server-Instanz. In OBS können beliebig viele Server-Profile parallel betrieben werden, jedes mit eigenem Modus, eigenen Zertifikaten und eigenen Bindungen.

Typische Einsatzfälle für mehrere Profile:

Ein Public-Profil mit Standard-TLS auf Port 443 für externe Konsumenten.
Ein Internal-mTLS-Profil auf einem internen Port für Microservices, die zwingend ein Client-Zertifikat vorlegen müssen.
Ein Debug-Profil mit Plain-HTTP auf 127.0.0.1, ausschliesslich für lokale Tests.

Aufruf

Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Server

Felder des Server-Profils

Feld	Beschreibung
Nr	Eindeutige Nummer 1-99, einmalig vergeben, kann später nicht mehr geändert werden
Name	Sprechender Name, eindeutig - erscheint in Protokoll, Statistik und Endpunkt-Zuordnung
Aktiv	Profil wird beim Start des REST-Dienstes geladen. Inaktive Profile starten nicht
zusätzliche Infos	Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
kein SSL	Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
mTLS-Modus aktiv	Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
Zertifikat (cert)	PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
Schlüssel (key)	PEM-Inhalt des privaten Schlüssels
Root-Zertifikat (ca)	PEM-Inhalt des CA-Zertifikats, gegen das '
Rate-Limit-Fenster	Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
Erfolgsanfragen	Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
Fehlanfragen	Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
Anfragen	Erlaubte Anfragen des gesamten Profils je Fenster. Leer/0 = Standard 600
max. Verbindungen	Obergrenze gleichzeitiger Verbindungen (`rsv_max_conn`). Leer/0 = unbegrenzt. Sie deckt auch laufende Datei-Downloads ab, weil der Platz erst beim Trennen frei wird. Bei Überschreitung trennt der Server ohne HTTP-Antwort - der Wert gehört deutlich über den Normalbetrieb, als Reissleine
max. Anfragen	Obergrenze gleichzeitig verarbeiteter Anfragen (`rsv_max_parallel`). Leer/0 = unbegrenzt. Bei Überschreitung antwortet der Server 503 mit `Retry-After`, der Client darf es also gleich erneut versuchen
keine Kompression	Antworten dieses Profils werden nicht gepackt (`rsv_no_gzip`). Ohne Haken packt der Server JSON- und Textantworten ab 1024 Byte mit gzip, sofern der Client sie über `Accept-Encoding` annimmt. Der Haken betrifft nur die Antwortrichtung - komprimierte Anfragen nimmt der Server weiterhin entgegen

HINWEIS: max. Verbindungen und max. Anfragen sind die beiden

Lastgrenzen des Profils. Davon zu unterscheiden sind die festen Grenzen der persistenten Verbindungen - 10 Sekunden Leerlauf, 100 Anfragen je Verbindung -, die nicht der Last dienen, sondern der Hygiene und nicht einstellbar sind. Siehe REST-Server, Abschnitt Persistente

Verbindungen.

Die Inhalte der Zertifikate werden direkt in OBS als Text gespeichert. Zur Laufzeit schreibt der Server die PEM-Inhalte für den Bruchteil einer Sekunde in ein Temp-Verzeichnis, damit OpenSSL sie beim Start lesen kann; danach werden die Temp-Dateien sofort wieder gelöscht.

Modi

Modus	Voraussetzungen	Anwendung
Standard-TLS	Zertifikat + Schlüssel	Für den Betrieb, auch wenn der Server nur intern, hinter einem Reverse-Proxy oder per VPN erreichbar ist
mTLS	Zertifikat + Schlüssel + Root-Zert.	Maschine-zu-Maschine-Kommunikation, in der jeder Client mit Cert validiert wird
Plain-HTTP	Haken kein SSL	Ausschliesslich lokale Tests. Erkennt TLS-Versuche auf dem Plain-Port und trennt sie direkt

Beide Richtungen werden erkannt: Eine unverschlüsselte Anfrage an einen TLS-Port (http statt https) beantwortet der Server mit HTTP 400 und einem Klartext-Hinweis. Die Abweisung erfolgt vor Authentifizierung, Rate-Limit und Endpunkt-Skript - ein falsch konfigurierter Client löst also keine Verarbeitung aus.

HINWEIS: Bei Standard-TLS und mTLS fährt der Server ohne Zertifikat und Schlüssel gar nicht erst hoch. Bei aktiver Erneuerung trägt der Dienst beides selbst ein. Plain-HTTP umgeht TLS komplett und ist nicht für Produktivumgebungen geeignet.

TLS-Version, Cipher und Zertifikats-Rotation

TLS-Version: Der Server erzwingt TLS 1.2. Die Cipher-Liste ist auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AEAD-Verfahren (AES-GCM, ChaCha20-Poly1305) beschränkt; CBC, statisches RSA-KEX und DHE sind ausgeschlossen.
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 noch über HTTPS an. Beim Profil Kein SSL wird der Header bewusst nicht gesetzt - der Browser würde ihn sonst speichern und die Erzwingung auch auf produktive Sitzungen anwenden.
Rotation: Bei automatischer Erneuerung tauscht der Dienst das Zertifikat selbst und startet dabei nur das betroffene Server-Profil neu; die übrigen Profile und der Dienst laufen weiter. Bei manueller Pflege ändern Sie die PEM-Inhalte und starten den REST-Dienst neu - bis dahin läuft das alte Zertifikat weiter.
Certificate-Pinning: Mobile Clients können den Server-Public-Key pinnen. Zertifikatswechsel daher rechtzeitig ankündigen und mit einem Backup-Pin vorbereiten - der neue Pin muss vor dem Wechsel in einer Client-Version ausgerollt sein, sonst sperrt sich die App aus.

Automatische Zertifikatserneuerung

Der REST-Server kann sein TLS-Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Prüfarten, Voraussetzungen, Einrichtung, Ablauf und Konsolenbefehle beschreibt Zertifikatserneuerung.

Felder

Registerkarte 4 Zertifikaterneuerung:

Feld	Beschreibung
Automatische Erneuerung	deaktiviert = aus. Produktivbetrieb = der Dienst beantragt und erneuert das Zertifikat selbst. Testbetrieb = nur für Testsysteme, siehe Testbetrieb
Zertifikatsname (FQDN)	Der Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist
Kontakt bei der CA	Optional. Die Zertifizierungsstelle schickt an diese Adresse Warnungen, wenn ein Zertifikat abzulaufen droht
Zertifikat gültig bis	Ablaufdatum des aktiven Zertifikats
Testzertifikat aus Staging	Gesetzt, wenn das aktive Zertifikat aus dem Testbetrieb stammt
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
Selbsttest bestanden	Ergebnis dieser Prüfung

Die Felder ab Zertifikat gültig bis füllt der Dienst selbst; sie dienen der Anzeige.

Registerkarte 5 DNS-Prüfung:

Feld	Beschreibung
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, 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

HINWEIS: Die Zugangsdaten stehen im Klartext im Server-Profil. Verwenden Sie Token, die nur die nötige Zone ändern dürfen.

Rate-Limit je Profil

Jedes Server-Profil führt eigene Zähler und kann eigene Schwellen haben. Ein Profil, das gerade überrannt wird, bremst damit die anderen Profile nicht mit aus - das Public-Profil und das interne mTLS-Profil sind voneinander unabhängig.

Gezählt wird pro Schlüssel, und der Schlüssel ist der API-Key des Zugangs. Sendet ein Konsument keinen API-Key (Zugang mit *), wird ersatzweise auf die IP-Adresse gezählt.

HINWEIS: Das ist der wichtigste Punkt bei mobilen Anwendungen: Sitzen alle

Benutzer hinter einer gemeinsamen Firmen-IP und sendet die App keinen eigenen API-Key, teilen sich alle Benutzer einen Zähler. Mit den Standardwerten sind das 10 Fehlversuche für den ganzen Betrieb pro Minute - nach ein paar falschen Passworteingaben steht die Abteilung. Für solche Profile die Schwellen bewusst

höher setzen oder jedem Konsumenten einen eigenen API-Key geben.

Dasselbe gilt hinter einem Reverse-Proxy: Alle Anfragen kommen dort von der IP-Adresse des Proxys, und alle Konsumenten ohne API-Key teilen sich einen Zähler. Der Header X-Forwarded-For ändert daran nichts, er wird nur protokolliert.

Bleiben alle vier Felder leer (bzw. 0), gelten die Standardwerte. Die Werte werden beim Start des REST-Dienstes gelesen - eine Änderung wird erst nach einem Neustart wirksam.

Validierung beim Speichern

Immer geprüft wird:

Nr und Name sind vergeben, Nr liegt zwischen 1 und 99.
Nr und Name sind eindeutig.
Eingetragene Zertifikate und Schlüssel liegen im PEM-Format vor.
Ein eingetragener Zertifikatsname enthält keine Adresse, keinen Port und keine Leerzeichen.

Nur bei aktivem Profil zusätzlich:

Ohne kein SSL und ohne automatische Erneuerung sind Zertifikat und Schlüssel vorhanden.
Bei mTLS-Modus aktiv ist das Root-Zertifikat vorhanden.
Bei aktiver Erneuerung ist der Zertifikatsname vergeben, und kein SSL ist nicht gesetzt.

HINWEIS: Ein nicht aktives Profil dürfen Sie unvollständig speichern - es wird beim Start des Dienstes nicht geladen. Was Sie eintragen, wird trotzdem auf Plausibilität geprüft.

Bindungen

Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Pro Server-Profil können mehrere Bindungen existieren, z.B. um die gleiche TLS-Konfiguration parallel auf 443 und 8443 anzubieten.

Aufruf

In der Server-Liste den gewünschten Server markieren und F6 drücken. Es öffnet sich die zum Server gehörende Bindungs-Liste.

Felder

Feld	Beschreibung
Host	IP-Adresse oder Hostname, auf dem gelauscht wird. 0.0.0.0 = alle IPv4-Adressen; 127.0.0.1 = nur lokal; explizite IPs binden gezielt auf eine Netzwerkkarte
Port	TCP-Port (1-65535). 443/8443 für HTTPS, frei wählbar für Debug-Profile
Aktiv	Bindung wird beim Server-Start geladen
Standard	Markiert die Standard-Bindung des Servers. Pro Server-Profil ist nur eine Standard-Bindung erlaubt

Wirksamkeit

Bindungen werden ausschliesslich beim Start des REST-Dienstes geladen. Änderungen werden daher erst nach einem Neustart aktiv. Bis dahin laufen die alten Bindungen weiter.

Listen-Funktionen

In der Server-Liste:

Einfg - neues Server-Profil
Return - vorhandenes Profil bearbeiten
F4 - Sortierung wählen
F6 - Bindungs-Liste des markierten Servers