← Zum vorherigen Versionsunterschied Zum nächsten Versionsunterschied →

Version vom 26. Oktober 2026, 10:31 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	Empfohlener Default für alle Server, die über das öffentliche Netz erreichbar sind
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

@@ Zeile 90: / Zeile 90: @@
 ==Automatische Zertifikatserneuerung==
-Der REST-Server kann sein TLS-Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen dabei auf Ihrem Server und verlassen ihn nicht.
+Der REST-Server kann sein TLS-Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Prüfarten, Voraussetzungen, Einrichtung, Ablauf und Konsolenbefehle beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]].
-===Voraussetzungen===
-* Ein öffentlicher Name, der von aussen auf diesen Server zeigt.
-* '''Port 80''' ist von aussen auf diesen Server weitergeleitet. Darüber prüft die Zertifizierungsstelle, dass Sie den Namen betreiben. Der Dienst öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.
-* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle sind erlaubt.
-{{Hinweis|Port 80 wird unabhängig davon benötigt, auf welchem Port der REST-Server selbst lauscht. Die Prüfung der Zertifizierungsstelle beginnt immer auf Port 80.}}
-{{Hinweis|Nimmt ein Reverse-Proxy die TLS-Verbindung von aussen an, braucht nur der Proxy das öffentliche Zertifikat. Die automatische Zertifikatserneuerung und die Weiterleitung von Port 80 auf den REST-Server entfallen dann. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung#Betrieb hinter einem Reverse-Proxy|Betrieb hinter einem Reverse-Proxy]].}}
 ===Felder===
@@ Zeile 109: / Zeile 99: @@
 ! Feld                       !! Beschreibung
 |-
-| Automatische Erneuerung    || ''deaktiviert'' = aus. ''Produktivbetrieb'' = der Dienst beantragt und erneuert das Zertifikat selbst. ''Testbetrieb'' = siehe Warnung unten
+| Automatische Erneuerung    || ''deaktiviert'' = aus. ''Produktivbetrieb'' = der Dienst beantragt und erneuert das Zertifikat selbst. ''Testbetrieb'' = nur für Testsysteme, siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Testbetrieb|Testbetrieb]]
 |-
 | Zertifikatsname (FQDN)     || Der Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist
@@ Zeile 125: / Zeile 115: @@
 | Gesperrt bis               || Nach einem Fehlschlag wartet der Dienst bis zu diesem Zeitpunkt, bevor er es erneut versucht
 |-
-| Letzter Selbsttest am      || Zeitpunkt der letzten Erreichbarkeitsprüfung
+| Letzter Selbsttest am      || Zeitpunkt der letzten Prüfung über das Testsystem der Zertifizierungsstelle
 |-
-| Selbsttest bestanden       || Ergebnis der letzten Erreichbarkeitsprüfung
+| Selbsttest bestanden       || Ergebnis dieser Prüfung
 |}
 Die Felder ab ''Zertifikat gültig bis'' füllt der Dienst selbst; sie dienen der Anzeige.
-===Ablauf===
+Registerkarte '''5 DNS-Prüfung''':
-Der Dienst sieht stündlich nach, ob etwas ansteht:
-# '''Selbsttest:''' Einmal wöchentlich prüft der Dienst über das Testsystem der Zertifizierungsstelle, ob Ihr Server von aussen erreichbar ist. Besteht der Test nicht, beantragt der Dienst kein Zertifikat.
-# '''Erneuerung:''' Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
-# '''Übernahme:''' Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet '''nur das betroffene Server-Profil''' neu.
-# '''Rückfall:''' Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.
-Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht - eine, zwei, vier, acht und höchstens 24 Stunden. Das verhindert, dass ein dauerhafter Fehler das Anfragekontingent der Zertifizierungsstelle aufbraucht.
-===Befehle in der Konsole===
 {| class="wikitable"
-! Befehl !! Wirkung
+! Feld                       !! Beschreibung
+|-
+| Prüfart                    || ''http-01 (Port 80)'' oder ''dns-01 (DNS-Eintrag)'', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Welche Prüfart?|Welche Prüfart?]]
+|-
+| DNS-Anbieter               || Nur dns-01: ''acme-dns'', ''Hetzner'', ''Cloudflare'' oder ''IONOS''
 |-
-| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
+| Adresse (acme-dns)         || Nur acme-dns: Adresse der Instanz, beginnt mit <code>https://</code>
 |-
-| <code>cert test</code> || Prüft sofort, ob der Server von aussen erreichbar ist. Beantragt kein Zertifikat
+| Benutzer (acme-dns)        || Nur acme-dns: Benutzer des Kontos. Bleiben Benutzer, Schlüssel und Name leer, legt der Dienst das Konto selbst an
 |-
-| <code>cert renew</code> || Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist
+| Schlüssel / API-Token      || acme-dns: Passwort des Kontos. Hetzner und Cloudflare: API-Token. IONOS: API-Schlüssel in der Form <code>Präfix.Secret</code>
+|-
+| Name des TXT-Eintrags      || Leer = <code>_acme-challenge.<Zertifikatsname></code>. Bei CNAME-Delegation das Ziel des CNAME, bei acme-dns die ''fulldomain'' des Kontos
 |}
-===Testbetrieb===
+{{Hinweis|Die Zugangsdaten stehen im Klartext im Server-Profil. Verwenden Sie Token, die nur die nötige Zone ändern dürfen.}}
-{{Achtung|Im '''Testbetrieb''' beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut '''kein''' Client - Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen; der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.}}
 ==Rate-Limit je Profil==