SSL-Fehlerbehebung

Diese Anleitung behandelt häufige SSL-Probleme in smoxy und deren Behebung.

---

SSL-Status verstehen

Der Zertifikatsstatus und der DNS-Status jedes SANs sind auf der Seite SSL-Zertifikate sichtbar - ein Zertifikat öffnen, um dessen SANs-Tab zu sehen. Folgende Zustände weisen auf ein Problem hin:

Die SAN-Tabelle in der Zertifikatsansicht: DNS- und SSL-Status je Name sowie der erforderliche CNAME-Eintrag.

Pending

Bedeutung: Die Zertifikatsgenerierung wurde gestartet, ist aber noch nicht abgeschlossen.

Was zu tun ist:

• Prüfen, ob alle _acme-challenge CNAME-Einträge beim DNS-Anbieter konfiguriert sind
• Auf die DNS-Propagierung warten (normalerweise wenige Minuten, kann aber bis zu 48 Stunden dauern)
• smoxy nimmt die Generierung automatisch auf, sobald die DNS-Einträge verifiziert sind

Wenn der Status länger als 1 Stunde bestehen bleibt:

• Den DNS-Status jedes SANs im SANs-Tab des Zertifikats prüfen
• Nach SANs mit dem DNS-Status „Missing" suchen und diese Einträge korrigieren
• smoxy versucht es automatisch in zunehmenden Abständen erneut

DNS-Status: Missing

Bedeutung: Der erforderliche _acme-challenge CNAME-Eintrag wurde für einen oder mehrere SANs nicht gefunden. Ein Eintrag, der auf das falsche Ziel zeigt, oder ein kollidierender TXT-Eintrag führen ebenfalls zum Status Missing - siehe die Ursachen unten.

Lösung:

1. Den erwarteten CNAME-Eintrag prüfen, der im SANs-Tab des Zertifikats angezeigt wird

2. Den Eintrag beim DNS-Anbieter hinzufügen:

   Typ:    CNAME
   Name:   _acme-challenge
   Ziel:   example.com.acme.smoxy.eu.  (den exakten Wert aus dem SANs-Tab verwenden)

3. Auf die DNS-Propagierung warten

4. smoxy überprüft fehlende Einträge jede 1 Stunde und erkennt die Änderung automatisch

Ursache: CNAME zeigt auf das falsche Ziel

Bedeutung: Ein CNAME-Eintrag für _acme-challenge existiert, zeigt aber auf das falsche Ziel, sodass der SAN im DNS-Status Missing verbleibt.

Lösung:

1. Beim DNS-Anbieter anmelden
2. Den _acme-challenge CNAME auf das exakte Ziel aktualisieren, das im SANs-Tab des Zertifikats angezeigt wird
3. smoxy verifiziert den aktualisierten Eintrag bei der nächsten Prüfung

Ursache: kollidierender TXT-Eintrag

Bedeutung: Ein TXT-Eintrag für _acme-challenge existiert, der mit dem erforderlichen CNAME-Eintrag kollidiert und den SAN im DNS-Status Missing hält.

Warum das passiert: Einige DNS-Anbieter oder frühere Konfigurationen haben möglicherweise einen TXT-Eintrag für ACME-Challenges erstellt. smoxy benötigt stattdessen einen CNAME-Eintrag.

Lösung:

1. Den TXT-Eintrag für _acme-challenge beim DNS-Anbieter entfernen
2. Sicherstellen, dass nur der CNAME-Eintrag existiert
3. smoxy erkennt die Änderung bei der nächsten Prüfung

---

Häufige Szenarien

Cloudflare-Nutzer

Bei Nutzung von Cloudflare als DNS-Anbieter:

1. Cloudflare-Proxy deaktivieren (orangene Wolke) für den _acme-challenge CNAME-Eintrag
2. Der Eintrag muss Nur DNS (graue Wolke) sein, damit die ACME-Verifizierung funktioniert
3. Reguläre Traffic-Einträge können weiterhin den Cloudflare-Proxy verwenden

Detaillierte Anweisungen unter Cloudflare Setup.

Zertifikat erneuert sich nicht automatisch

Automatisch generierte Zertifikate erneuern sich innerhalb des empfohlenen Erneuerungsfensters der CA (ersatzweise etwa zwei Wochen vor Ablauf). Wenn die Erneuerung nicht stattfindet:

1. DNS-Einträge prüfen - Die _acme-challenge CNAME-Einträge müssen noch vorhanden sein
2. SAN-DNS-Status prüfen - Im SANs-Tab des Zertifikats prüfen, ob alle SANs den DNS-Status „Valid" anzeigen
3. Rate Limits - Wenn smoxy die Let's Encrypt Rate Limits erreicht hat, wartet es vor dem nächsten Versuch

INFO

Hinweis: Selbst verwaltete Zertifikate werden niemals automatisch erneuert. Ein Ersatzzertifikat muss manuell hochgeladen werden.

Mehrere Subdomains nicht abgedeckt

Der Standard-Wildcard (*.example.com) deckt einstufige Subdomains ab. Er deckt nicht ab:

• Mehrstufige Subdomains wie sub.shop.example.com
• Andere Top-Level-Domains

Für diese Fälle kann smoxy zusätzliche SANs hinzufügen. Jeder zusätzliche SAN benötigt seinen eigenen _acme-challenge CNAME-Eintrag.

Zertifikat wird als abgelaufen angezeigt

Wenn das Zertifikat abgelaufen ist:

• Automatisch verwaltet: Prüfen, ob die _acme-challenge DNS-Einträge noch vorhanden sind. Wenn ja, versucht smoxy eine Erneuerung. Wenn sie entfernt wurden, müssen sie wieder hinzugefügt werden.
• Selbst verwaltet: Ein neues Zertifikat hochladen. smoxy kann Zertifikate, die es nicht generiert hat, nicht erneuern.

SSL-Generierung schlägt wiederholt fehl

Bei wiederholten Fehlern im SSL-Generierungsprozess:

Fehler	Ursache	Lösung
CNAME record missing	Der _acme-challenge CNAME-Eintrag fehlt für einen oder mehrere SANs	Den/die erforderlichen CNAME-Eintrag/Einträge hinzufügen
CNAME record invalid	Der CNAME-Eintrag existiert, zeigt aber auf das falsche Ziel	Auf das exakte Ziel aktualisieren, das im SANs-Tab angezeigt wird
DNS provisioning failed	smoxy konnte den DNS-01-Challenge-Eintrag nicht anlegen	Vorübergehend - smoxy versucht es automatisch erneut
ACME error	Die Zertifizierungsstelle hat einen Fehler gemeldet	DNS-Propagierung prüfen; smoxy versucht es automatisch erneut
Rate limit	Zu viele Zertifikatsanfragen bei Let's Encrypt	Automatisch - smoxy wartet und versucht es später erneut
Internal error	Ein unerwarteter Fehler ist aufgetreten	smoxy versucht es erneut; bei anhaltendem Fehler den Support kontaktieren

smoxy verwendet exponentielles Backoff bei Wiederholungsversuchen und erhöht die Wartezeit zwischen den Versuchen, um externe Dienste nicht zu überlasten.

Der Tab „Versuche“: jeder Generierungs- und Erneuerungsversuch, aufklappbar in die einzelnen Schritte und Fehler.

---

Zertifikatsverifizierung

Um unabhängig zu prüfen, ob das SSL-Zertifikat funktioniert:

Im Browser

1. Die Domain mit https:// aufrufen
2. Auf das Schloss-Symbol in der Adressleiste klicken
3. Die Zertifikatsdetails prüfen:
   • Ausgestellt für die korrekte Domain
   • Gültiger Zeitraum
   • Ausgestellt von der erwarteten CA (Let's Encrypt bei automatisch verwalteten Zertifikaten)

Per Kommandozeile

# Zertifikatsdetails anzeigen
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null | openssl x509 -text -noout

# Ablaufdatum des Zertifikats prüfen
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -dates

---

Hilfe erhalten

Wenn die Fehlerbehebungsschritte befolgt wurden und das SSL-Problem weiterhin besteht:

1. Die genauen Statusmeldungen notieren, die in smoxy angezeigt werden
2. Das Aktivitätsprotokoll (unter Team-Einstellungen) auf SSL-bezogene Ereignisse prüfen
3. Den smoxy-Support mit Domainnamen und Fehlerdetails kontaktieren