OBS/Kostenpflichtige Module/REST-Server/Zertifikatserneuerung: Unterschied zwischen den Versionen
Hinweis: nicht aufgeführte DNS-Anbieter über den OBS-Support [Volltext ersetzt] |
Menüpfad und Sprunglinks auf die Seite Pflege umgestellt [Volltext ersetzt] |
||
| (7 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
| Zeile 5: | Zeile 5: | ||
Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten. | Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten. | ||
{{Hinweis|Jedes Server-Profil braucht im Betrieb ein Zertifikat, auch hinter einem Reverse-Proxy und im VPN: | {{Hinweis|Jedes Server-Profil braucht im Betrieb ein Zertifikat, auch hinter einem Reverse-Proxy und im VPN: Eine App verbindet sich ausschließlich per HTTPS, und ohne Zertifikat startet das Profil nicht. ''kein SSL'' ist nur für lokale Tests gedacht. Das Zertifikat beziehen Sie entweder automatisch wie hier beschrieben, oder Sie hinterlegen es von Hand im Server-Profil und tauschen es vor Ablauf. In einem internen Netz ohne eigene Domain stellt OBS auf Wunsch selbst eines aus, siehe [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Eigenes Zertifikat und Pin|Eigenes Zertifikat und Pin]].}} | ||
{{Auf einen Blick|1= | {{Auf einen Blick|1= | ||
| Zeile 15: | Zeile 15: | ||
== Voraussetzungen == | == Voraussetzungen == | ||
* Ein Name, auf den das Zertifikat lautet, zum Beispiel ''obs. | * Ein Name, auf den das Zertifikat lautet, zum Beispiel ''obs.example.com''. Platzhalter-Zertifikate (''*.example.com'') werden nicht unterstützt. | ||
* Ein Server-Profil mit TLS, also ohne Haken '''kein SSL'''. | * Ein Server-Profil mit TLS, also ohne Haken '''kein SSL''' und ohne Haken '''Eigenes Zertifikat (Pin)''' - der Pin und die automatische Erneuerung schließen sich aus, weil jede Erneuerung einen neuen Schlüssel und damit einen neuen Pin erzeugt. | ||
* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (<code>acme-v02.api.letsencrypt.org</code> und für den Selbsttest <code>acme-staging-v02.api.letsencrypt.org</code>). | * Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (<code>acme-v02.api.letsencrypt.org</code> und für den Selbsttest <code>acme-staging-v02.api.letsencrypt.org</code>). | ||
* Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz. | * Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz. | ||
| Zeile 24: | Zeile 24: | ||
! Prüfart !! Funktioniert, wenn !! Aus dem Internet erreichbar sein muss | ! Prüfart !! Funktioniert, wenn !! Aus dem Internet erreichbar sein muss | ||
|- | |- | ||
| http-01 || der Name öffentlich auf diesen Server zeigt und Port 80 von | | http-01 || der Name öffentlich auf diesen Server zeigt und Port 80 von außen auf ihn weitergeleitet ist || Port 80 | ||
|- | |- | ||
| dns-01 || sich der DNS-Eintrag <code>_acme-challenge.<Name></code> über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME || nichts | | dns-01 || sich der DNS-Eintrag <code>_acme-challenge.<Name></code> über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME || nichts | ||
|} | |} | ||
Welche Prüfart zu Ihrer [[OBS/Kostenpflichtige Module/ | Welche Prüfart zu Ihrer [[OBS/Kostenpflichtige Module/REST-Server/Öffentliche Freigabe|öffentlichen Freigabe]] passt: | ||
* '''Direkte Portfreigabe:''' http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen. | * '''Direkte Portfreigabe:''' http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen. | ||
* '''Reverse-Proxy:''' Das öffentliche Zertifikat liegt am Proxy. Der REST-Server braucht trotzdem ein Zertifikat für die Strecke vom Proxy | * '''Reverse-Proxy:''' Das öffentliche Zertifikat liegt am Proxy. Der REST-Server braucht trotzdem ein Zertifikat für die Strecke vom Proxy. Dafür genügt ein selbst signiertes Zertifikat oder eines Ihrer internen Zertifizierungsstelle, sofern der Proxy ihm vertraut. Es wird im Server-Profil hinterlegt und muss vor Ablauf getauscht werden. | ||
* '''VPN:''' dns-01. | * '''VPN:''' dns-01. | ||
| Zeile 56: | Zeile 56: | ||
=== Gemeinsame Einstellungen === | === Gemeinsame Einstellungen === | ||
{{Schritte|1= | {{Schritte|1= | ||
# Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST- | # Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST-Server''' und öffnen Sie in der Liste der Server-Profile das Profil mit {{Return}}. | ||
# Stellen Sie auf der Registerkarte '''4 Zertifikaterneuerung''' das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb''. | # Stellen Sie auf der Registerkarte '''4 Zertifikaterneuerung''' das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb''. | ||
# Tragen Sie im Feld '''Zertifikatsname (FQDN)''' den Namen ein, auf den das Zertifikat lauten soll. | # Tragen Sie im Feld '''Zertifikatsname (FQDN)''' den Namen ein, auf den das Zertifikat lauten soll. | ||
| Zeile 63: | Zeile 63: | ||
# Starten Sie den REST-Dienst neu. | # Starten Sie den REST-Dienst neu. | ||
}} | }} | ||
{{Hinweis|Die Befehle <code>cert test</code> und <code>cert renew</code> geben Sie in der Konsole des REST-Servers ein. Die Konsole gibt es nur, wenn der REST-Server ohne den Parameter <code>/service</code> läuft. Läuft er als Windows-Dienst, starten Sie den Dienst stattdessen neu. Nach dem Start prüft er sofort, außer '''Gesperrt bis''' liegt noch in der Zukunft.}} | |||
=== Prüfart http-01 === | === Prüfart http-01 === | ||
{{Schritte|1= | {{Schritte|1= | ||
# Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen. | # Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen. | ||
# Leiten Sie am Router Port 80 von | # Leiten Sie am Router Port 80 von außen auf den Server des REST-Dienstes weiter. | ||
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''http-01 (Port 80)''. Die übrigen Felder bleiben leer. | # Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''http-01 (Port 80)''. Die übrigen Felder bleiben leer. | ||
# Geben Sie in der Konsole des REST-Servers <code>cert test</code> ein. | # Geben Sie in der Konsole des REST-Servers <code>cert test</code> ein. | ||
}} | }} | ||
Port 80 darf auf dem Server des REST-Dienstes von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und | Port 80 darf auf dem Server des REST-Dienstes von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und schließt ihn danach wieder. | ||
=== Prüfart dns-01 direkt beim DNS-Anbieter === | === Prüfart dns-01 direkt beim DNS-Anbieter === | ||
| Zeile 88: | Zeile 90: | ||
=== Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter === | === Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter === | ||
{{Schritte|1= | {{Schritte|1= | ||
# Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel ''obs | # Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel ''obs.acme.example.net''. Einen Eintrag müssen Sie dort nicht anlegen. | ||
# Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an: <code>_acme-challenge.obs. | # Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an: <code>_acme-challenge.obs.example.com</code> auf ''obs.acme.example.net''. | ||
# Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben. | # Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben. | ||
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den Anbieter dieser Zone. | # Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den Anbieter dieser Zone. | ||
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein. | # Tragen Sie unter '''Schlüssel / API-Token''' das Token ein. | ||
# Tragen Sie unter '''Name des TXT-Eintrags''' das Ziel des CNAME ein, hier ''obs | # Tragen Sie unter '''Name des TXT-Eintrags''' das Ziel des CNAME ein, hier ''obs.acme.example.net''. | ||
# Geben Sie in der Konsole <code>cert test</code> ein. | # Geben Sie in der Konsole <code>cert test</code> ein. | ||
}} | }} | ||
| Zeile 110: | Zeile 112: | ||
=== Erstes Zertifikat holen === | === Erstes Zertifikat holen === | ||
Nach einem Neustart des REST-Dienstes prüft der Dienst sofort. Besteht der Selbsttest, holt er das Zertifikat gleich im Anschluss. Nach einem bestandenen <code>cert test</code> holt er es erst bei der nächsten stündlichen Prüfung. Sofort geht es mit <code>cert renew</code> in der Konsole. Bis das erste Zertifikat da ist, kann sich kein Client mit dem Server-Profil verbinden. | |||
=== Testbetrieb === | === Testbetrieb === | ||
{{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 | {{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 ausschließlich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen. Der Dienst holt dann ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft: bei der nächsten stündlichen Prüfung, nach einem Neustart des Dienstes oder sofort mit <code>cert renew</code>.}} | ||
== Ergebnis == | == Ergebnis == | ||
Nach bestandenem Selbsttest ist auf der Registerkarte '''4 Zertifikaterneuerung''' der Haken '''Selbsttest bestanden''' gesetzt. | Nach bestandenem Selbsttest ist auf der Registerkarte '''4 Zertifikaterneuerung''' der Haken '''Selbsttest bestanden''' gesetzt. Im Protokoll des REST-Servers steht "Selbsttest bestanden - von außen erreichbar" (http-01) bzw. "Selbsttest bestanden - DNS-Eintrag von der CA geprüft" (dns-01). Hat die Zertifizierungsstelle eine noch gültige Autorisierung wiederverwendet, steht dort stattdessen eine Warnung. Die Erreichbarkeit ist dann nicht neu geprüft. | ||
Unter '''Letzte Meldung''' steht nach <code>cert test</code> dieselbe Aussage wie im Protokoll, ergänzt um ", Erneuerung noch nicht fällig" oder ", Erneuerung steht an (cert renew)", z.B. "Selbsttest bestanden - von außen erreichbar, Erneuerung noch nicht fällig". "Erneuerung steht an" erscheint auch, wenn noch gar kein Zertifikat ausgestellt ist. Nach der Ausstellung steht dort "Zertifikat erneuert, gültig bis …", und '''Zertifikat gültig bis''' zeigt das Ablaufdatum. <code>cert</code> in der Konsole zeigt den Stand je Profil. | |||
== Wenn es nicht klappt == | == Wenn es nicht klappt == | ||
| Zeile 145: | Zeile 128: | ||
! Meldung !! Ursache | ! Meldung !! Ursache | ||
|- | |- | ||
| "Port 80 | | "Port 80 lässt sich nicht öffnen - er ist belegt" || Ein anderer Dienst auf dem Server des REST-Dienstes belegt Port 80, häufig IIS. Dienst abschalten oder die Prüfart dns-01 verwenden | ||
|- | |- | ||
| "dns-01 ist eingestellt, aber kein DNS-Anbieter" || Auf der Registerkarte '''5 DNS-Prüfung''' ist kein DNS-Anbieter gewählt | | "dns-01 ist eingestellt, aber kein DNS-Anbieter" || Auf der Registerkarte '''5 DNS-Prüfung''' ist kein DNS-Anbieter gewählt | ||
| Zeile 151: | Zeile 134: | ||
| "kein API-Token" || Das Feld '''Schlüssel / API-Token''' ist leer | | "kein API-Token" || Das Feld '''Schlüssel / API-Token''' ist leer | ||
|- | |- | ||
| "acme-dns: Konto | | "acme-dns: Konto unvollständig" || Von Benutzer, Schlüssel und Name des TXT-Eintrags ist nur ein Teil gefüllt | ||
|- | |- | ||
| "Hetzner: keine Zone zu … im Projekt des Tokens" || Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole | | "Hetzner: keine Zone zu … im Projekt des Tokens" || Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole | ||
| Zeile 157: | Zeile 140: | ||
| "Cloudflare: keine Zone zu …, die das Token sehen darf" || Das Token ist nicht für diese Zone freigegeben | | "Cloudflare: keine Zone zu …, die das Token sehen darf" || Das Token ist nicht für diese Zone freigegeben | ||
|- | |- | ||
| "IONOS: keine Zone zu … im Vertrag des | | "IONOS: keine Zone zu … im Vertrag des Schlüssels" || Der API-Schlüssel gehört zu einem anderen Vertrag | ||
|- | |- | ||
| "… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)" || Das Token ist ungültig oder darf keine DNS-Einträge ändern | | "… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)" || Das Token ist ungültig oder darf keine DNS-Einträge ändern | ||
|- | |- | ||
| "… ist nach 210 Sekunden noch nicht | | "… ist nach 210 Sekunden noch nicht überall sichtbar" || Der Eintrag ist über öffentliche DNS-Server nicht zu sehen. Meist fehlt der CNAME oder zeigt auf ein anderes Ziel als '''Name des TXT-Eintrags'''. Der Dienst löst die Prüfung trotzdem aus | ||
|- | |- | ||
| "kein | | "kein öffentlicher DNS-Server erreichbar" || Ausgehendes DNS (Port 53) ist gesperrt. Der Dienst kann die Sichtbarkeit nicht prüfen und wartet fest 60 Sekunden | ||
|- | |- | ||
| "acme-dns-Konto angelegt - jetzt CNAME … setzen" || Kein Fehler: Legen Sie den genannten CNAME an und geben Sie <code>cert test</code> ein | | "acme-dns-Konto angelegt - jetzt CNAME … setzen" || Kein Fehler: Legen Sie den genannten CNAME an und geben Sie <code>cert test</code> ein | ||
|} | |} | ||
== Automatischer Betrieb == | |||
Nach dem ersten Zertifikat läuft die Erneuerung selbständig: | |||
# '''Prüfung:''' Der Dienst sieht stündlich nach, ob etwas ansteht. | |||
# '''Selbsttest:''' Einmal wöchentlich und nach jeder Änderung von Zertifikatsname, Prüfart, DNS-Anbieter oder Name des TXT-Eintrags prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle. Besteht der Test nicht, beantragt er 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. Anschließend 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 Feld '''Gesperrt bis''' zeigt, bis wann. Nach einem Neustart des Dienstes beginnt die Staffel wieder bei einer Stunde. <code>cert test</code> und <code>cert renew</code> in der Konsole wirken sofort, auch während der Sperre. | |||
Für die Erneuerung gibt es drei Befehle in der Konsole. Alle weiteren Befehle beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche#Konsole|Betrieb und Fehlersuche]]. | |||
{| class="wikitable" | |||
! Befehl !! Wirkung | |||
|- | |||
| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests | |||
|- | |||
| <code>cert test</code> || Prüft sofort den Weg über das Testsystem der Zertifizierungsstelle. Beantragt kein Zertifikat | |||
|- | |||
| <code>cert renew</code> || Stößt die Erneuerung sofort an, auch wenn sie noch nicht fällig ist | |||
|} | |||
Bei dns-01 wartet der Dienst nach dem Schreiben des Eintrags 30 Sekunden und dann bis zu drei Minuten, bis der Eintrag über öffentliche DNS-Server sichtbar ist. Erst dann löst er die Prüfung aus. | |||
== Siehe auch == | == Siehe auch == | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Öffentliche Freigabe|Öffentliche Freigabe]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Registerkarte: 4 Zertifikaterneuerung|Pflege: Felder der Zertifikatserneuerung]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Einrichtung|Einrichtung]] | ||
* [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]] | |||
Aktuelle Version vom 17. November 2026, 11:53 Uhr
Zertifikatserneuerung
Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten.
- Zwei Prüfarten. http-01 prüft über Port 80, dns-01 über einen DNS-Eintrag und braucht keinen offenen Port.
- Selbsttest vorab. Vor dem ersten Zertifikat und danach wöchentlich prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle.
- Erneuerung ab 30 Tagen Restlaufzeit. Das bisherige Zertifikat bleibt als Rückfall erhalten.
- dns-01 braucht nur ausgehende Verbindungen und eignet sich damit für VPN und für Server ohne Portfreigabe.
Voraussetzungen
- Ein Name, auf den das Zertifikat lautet, zum Beispiel obs.example.com. Platzhalter-Zertifikate (*.example.com) werden nicht unterstützt.
- Ein Server-Profil mit TLS, also ohne Haken kein SSL und ohne Haken Eigenes Zertifikat (Pin) - der Pin und die automatische Erneuerung schließen sich aus, weil jede Erneuerung einen neuen Schlüssel und damit einen neuen Pin erzeugt.
- Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (
acme-v02.api.letsencrypt.orgund für den Selbsttestacme-staging-v02.api.letsencrypt.org). - Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz.
Welche Prüfart?
| Prüfart | Funktioniert, wenn | Aus dem Internet erreichbar sein muss |
|---|---|---|
| http-01 | der Name öffentlich auf diesen Server zeigt und Port 80 von außen auf ihn weitergeleitet ist | Port 80 |
| dns-01 | sich der DNS-Eintrag _acme-challenge.<Name> über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME |
nichts |
Welche Prüfart zu Ihrer öffentlichen Freigabe passt:
- Direkte Portfreigabe: http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen.
- Reverse-Proxy: Das öffentliche Zertifikat liegt am Proxy. Der REST-Server braucht trotzdem ein Zertifikat für die Strecke vom Proxy. Dafür genügt ein selbst signiertes Zertifikat oder eines Ihrer internen Zertifizierungsstelle, sofern der Proxy ihm vertraut. Es wird im Server-Profil hinterlegt und muss vor Ablauf getauscht werden.
- VPN: dns-01.
Wege bei dns-01
Bei dns-01 fragt die Zertifizierungsstelle den TXT-Eintrag _acme-challenge.<Name> ab. Der Dienst schreibt ihn vor der Prüfung und löscht ihn danach wieder. Dafür gibt es drei Wege:
| Weg | Wann | Einmalig beim DNS des Namens | Einstellung DNS-Anbieter |
|---|---|---|---|
| Direkt beim Anbieter | Die Zone des Namens liegt bei Hetzner, Cloudflare oder IONOS | nichts, Sie brauchen nur ein API-Token | Hetzner, Cloudflare oder IONOS |
| CNAME auf eine Zone bei einem Anbieter | Die Zone des Namens liegt bei einem anderen Anbieter, oder im REST-Server sollen keine Zugangsdaten zur eigenen Zone liegen | CNAME _acme-challenge.<Name> auf einen Namen in einer Zone bei Hetzner, Cloudflare oder IONOS |
Hetzner, Cloudflare oder IONOS |
| CNAME auf acme-dns | Eine acme-dns-Instanz steht zur Verfügung, im eigenen Betrieb oder bei einem Dienstleister | CNAME _acme-challenge.<Name> auf die fulldomain des acme-dns-Kontos |
acme-dns |
Beim CNAME-Weg genügt beim DNS-Anbieter des Namens ein von Hand angelegter Eintrag, auch bei Anbietern ohne Schnittstelle. Der REST-Server bekommt dann nur Zugang zur Zone, auf die der CNAME zeigt.
Vorgehen
Gemeinsame Einstellungen
- Wählen Sie Stammdaten → Z Weitere Stammdaten → REST-Server und öffnen Sie in der Liste der Server-Profile das Profil mit ↩ Enter.
- Stellen Sie auf der Registerkarte 4 Zertifikaterneuerung das Feld Automatische Erneuerung auf Produktivbetrieb.
- Tragen Sie im Feld Zertifikatsname (FQDN) den Namen ein, auf den das Zertifikat lauten soll.
- Tragen Sie unter Kontakt bei der CA eine E-Mail-Adresse ein. Die Zertifizierungsstelle schickt dorthin Warnungen, wenn ein Zertifikat abzulaufen droht.
- Richten Sie die Registerkarte 5 DNS-Prüfung nach einem der folgenden Abschnitte ein und speichern Sie.
- Starten Sie den REST-Dienst neu.
cert test und cert renew geben Sie in der Konsole des REST-Servers ein. Die Konsole gibt es nur, wenn der REST-Server ohne den Parameter /service läuft. Läuft er als Windows-Dienst, starten Sie den Dienst stattdessen neu. Nach dem Start prüft er sofort, außer Gesperrt bis liegt noch in der Zukunft.Prüfart http-01
- Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen.
- Leiten Sie am Router Port 80 von außen auf den Server des REST-Dienstes weiter.
- Wählen Sie auf der Registerkarte 5 DNS-Prüfung im Feld Prüfart den Eintrag http-01 (Port 80). Die übrigen Felder bleiben leer.
- Geben Sie in der Konsole des REST-Servers
cert testein.
Port 80 darf auf dem Server des REST-Dienstes von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und schließt ihn danach wieder.
Prüfart dns-01 direkt beim DNS-Anbieter
- Erstellen Sie beim Anbieter der Zone ein API-Token:
- Hetzner: ein API-Token des Projekts mit Lese- und Schreibrecht in der Hetzner Console. Zonen in der früheren DNS-Konsole (dns.hetzner.com) werden nicht unterstützt.
- Cloudflare: ein API-Token mit der Berechtigung, DNS zu bearbeiten, beschränkt auf die Zone.
- IONOS: einen API-Schlüssel. Er besteht aus Präfix und Secret.
- Wählen Sie auf der Registerkarte 5 DNS-Prüfung im Feld Prüfart den Eintrag dns-01 (DNS-Eintrag) und im Feld DNS-Anbieter den Anbieter.
- Tragen Sie unter Schlüssel / API-Token das Token ein, bei IONOS in der Form
Präfix.Secret. - Lassen Sie Name des TXT-Eintrags leer.
- Geben Sie in der Konsole
cert testein.
Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter
- Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel obs.acme.example.net. Einen Eintrag müssen Sie dort nicht anlegen.
- Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an:
_acme-challenge.obs.example.comauf obs.acme.example.net. - Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben.
- Wählen Sie auf der Registerkarte 5 DNS-Prüfung die Prüfart dns-01 (DNS-Eintrag) und den Anbieter dieser Zone.
- Tragen Sie unter Schlüssel / API-Token das Token ein.
- Tragen Sie unter Name des TXT-Eintrags das Ziel des CNAME ein, hier obs.acme.example.net.
- Geben Sie in der Konsole
cert testein.
Prüfart dns-01 mit CNAME auf acme-dns
- Wählen Sie auf der Registerkarte 5 DNS-Prüfung die Prüfart dns-01 (DNS-Eintrag) und den DNS-Anbieter acme-dns.
- Tragen Sie unter Adresse (acme-dns) die Adresse der Instanz ein. Sie beginnt mit
https://. - Lassen Sie Benutzer (acme-dns), Schlüssel / API-Token und Name des TXT-Eintrags leer und speichern Sie.
- Geben Sie in der Konsole
cert testein. Der Dienst legt das Konto bei acme-dns an und trägt Benutzer, Schlüssel und Name selbst ein. Unter Letzte Meldung steht danach der CNAME, den Sie anlegen müssen. - Legen Sie beim DNS-Anbieter Ihres Namens diesen CNAME an:
_acme-challenge.<Name>auf die genannte fulldomain. - Geben Sie in der Konsole erneut
cert testein.
Erstes Zertifikat holen
Nach einem Neustart des REST-Dienstes prüft der Dienst sofort. Besteht der Selbsttest, holt er das Zertifikat gleich im Anschluss. Nach einem bestandenen cert test holt er es erst bei der nächsten stündlichen Prüfung. Sofort geht es mit cert renew in der Konsole. Bis das erste Zertifikat da ist, kann sich kein Client mit dem Server-Profil verbinden.
Testbetrieb
cert renew.Ergebnis
Nach bestandenem Selbsttest ist auf der Registerkarte 4 Zertifikaterneuerung der Haken Selbsttest bestanden gesetzt. Im Protokoll des REST-Servers steht "Selbsttest bestanden - von außen erreichbar" (http-01) bzw. "Selbsttest bestanden - DNS-Eintrag von der CA geprüft" (dns-01). Hat die Zertifizierungsstelle eine noch gültige Autorisierung wiederverwendet, steht dort stattdessen eine Warnung. Die Erreichbarkeit ist dann nicht neu geprüft.
Unter Letzte Meldung steht nach cert test dieselbe Aussage wie im Protokoll, ergänzt um ", Erneuerung noch nicht fällig" oder ", Erneuerung steht an (cert renew)", z.B. "Selbsttest bestanden - von außen erreichbar, Erneuerung noch nicht fällig". "Erneuerung steht an" erscheint auch, wenn noch gar kein Zertifikat ausgestellt ist. Nach der Ausstellung steht dort "Zertifikat erneuert, gültig bis …", und Zertifikat gültig bis zeigt das Ablaufdatum. cert in der Konsole zeigt den Stand je Profil.
Wenn es nicht klappt
Die Meldungen stehen unter Letzte Meldung und im Protokoll des REST-Servers.
| Meldung | Ursache |
|---|---|
| "Port 80 lässt sich nicht öffnen - er ist belegt" | Ein anderer Dienst auf dem Server des REST-Dienstes belegt Port 80, häufig IIS. Dienst abschalten oder die Prüfart dns-01 verwenden |
| "dns-01 ist eingestellt, aber kein DNS-Anbieter" | Auf der Registerkarte 5 DNS-Prüfung ist kein DNS-Anbieter gewählt |
| "kein API-Token" | Das Feld Schlüssel / API-Token ist leer |
| "acme-dns: Konto unvollständig" | Von Benutzer, Schlüssel und Name des TXT-Eintrags ist nur ein Teil gefüllt |
| "Hetzner: keine Zone zu … im Projekt des Tokens" | Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole |
| "Cloudflare: keine Zone zu …, die das Token sehen darf" | Das Token ist nicht für diese Zone freigegeben |
| "IONOS: keine Zone zu … im Vertrag des Schlüssels" | Der API-Schlüssel gehört zu einem anderen Vertrag |
| "… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)" | Das Token ist ungültig oder darf keine DNS-Einträge ändern |
| "… ist nach 210 Sekunden noch nicht überall sichtbar" | Der Eintrag ist über öffentliche DNS-Server nicht zu sehen. Meist fehlt der CNAME oder zeigt auf ein anderes Ziel als Name des TXT-Eintrags. Der Dienst löst die Prüfung trotzdem aus |
| "kein öffentlicher DNS-Server erreichbar" | Ausgehendes DNS (Port 53) ist gesperrt. Der Dienst kann die Sichtbarkeit nicht prüfen und wartet fest 60 Sekunden |
| "acme-dns-Konto angelegt - jetzt CNAME … setzen" | Kein Fehler: Legen Sie den genannten CNAME an und geben Sie cert test ein
|
Automatischer Betrieb
Nach dem ersten Zertifikat läuft die Erneuerung selbständig:
- Prüfung: Der Dienst sieht stündlich nach, ob etwas ansteht.
- Selbsttest: Einmal wöchentlich und nach jeder Änderung von Zertifikatsname, Prüfart, DNS-Anbieter oder Name des TXT-Eintrags prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle. Besteht der Test nicht, beantragt er 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. Anschließend 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 Feld Gesperrt bis zeigt, bis wann. Nach einem Neustart des Dienstes beginnt die Staffel wieder bei einer Stunde. cert test und cert renew in der Konsole wirken sofort, auch während der Sperre.
Für die Erneuerung gibt es drei Befehle in der Konsole. Alle weiteren Befehle beschreibt Betrieb und Fehlersuche.
| Befehl | Wirkung |
|---|---|
cert |
Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests |
cert test |
Prüft sofort den Weg über das Testsystem der Zertifizierungsstelle. Beantragt kein Zertifikat |
cert renew |
Stößt die Erneuerung sofort an, auch wenn sie noch nicht fällig ist |
Bei dns-01 wartet der Dienst nach dem Schreiben des Eintrags 30 Sekunden und dann bis zu drei Minuten, bis der Eintrag über öffentliche DNS-Server sichtbar ist. Erst dann löst er die Prüfung aus.