Wie SSL in smoxy funktioniert

SSL/TLS-Zertifikate sind entscheidend, um den Datenverkehr zwischen deinen Besuchern und smoxy sowie zwischen smoxy und deinen Origin-Servern abzusichern. smoxy bietet einen vollständig integrierten Zertifikats-Lebenszyklus — von der automatischen Generierung über Let's Encrypt bis hin zum manuellen Upload eigener Zertifikate.

Diese Anleitung erklärt, wie SSL in smoxy funktioniert, welche Zertifikatstypen verfügbar sind und wie smoxy Zertifikate für dich verwaltet.

---

SSL-Zertifikatstypen

smoxy unterstützt zwei Arten von SSL-Zertifikaten:

Typ	Erstellt von	Erneuert von	Geeignet für
Automatisch verwaltet (Empfohlen)	smoxy über Let's Encrypt	smoxy (automatisch)	Die meisten Nutzer — kein Wartungsaufwand
Selbst verwaltet	Du	Du (manuell)	Enterprise-Zertifikate, EV-Zertifikate, spezielle Compliance-Anforderungen

Automatisch verwaltete Zertifikate (Empfohlen)

Wenn du eine Domain in smoxy hinzufügst, wird automatisch ein Wildcard-SSL-Zertifikat erstellt. Dieses Zertifikat deckt ab:

• deinedomain.com

• *.deinedomain.com (alle Subdomains)

Das Zertifikat wird über Let's Encrypt mittels DNS-basierter Validierung (ACME-Protokoll) ausgestellt. smoxy übernimmt den gesamten Lebenszyklus:

1. Zertifikatsanforderung

2. DNS-Challenge-Verifizierung

3. Zertifikatsausstellung

4. Automatische Erneuerung (30 Tage vor Ablauf)

Selbst verwaltete Zertifikate

Wenn du ein eigenes Zertifikat verwenden musst (z. B. Extended Validation, organisationsspezifische Anforderungen), kannst du es manuell hochladen.

Anforderungen:

• Zertifikatsdatei im PEM-Format

• Private-Key-Datei im PEM-Format

• Der Private Key muss zum Zertifikat passen

• Das Zertifikat darf nicht abgelaufen sein

• Das Zertifikat muss die Domain(s) abdecken, die du verwenden möchtest

Wichtig: smoxy kann manuell hochgeladene Zertifikate nicht automatisch erneuern. Du bist dafür verantwortlich, ein neues Zertifikat hochzuladen, bevor das aktuelle abläuft.

---

Wie die Zertifikatsgenerierung funktioniert

Schritt 1: DNS-Verifizierung

Für jeden Subject Alternative Name (SAN) auf dem Zertifikat benötigt smoxy einen CNAME-Eintrag, der auf die ACME-Verifizierungsinfrastruktur von smoxy zeigt:

_acme-challenge.deinedomain.com  →  deine-org.acme.smoxy.eu

Dieser CNAME-Eintrag ermöglicht es smoxy, die ACME DNS-01 Challenge durchzuführen, die von Let's Encrypt benötigt wird.

Wichtig: Wenn du Cloudflare verwendest, muss der Cloudflare-Proxy für den _acme-challenge CNAME-Eintrag deaktiviert sein. Weitere Informationen findest du unter Cloudflare Setup.

Schritt 2: Zertifikatsausstellung

Sobald alle DNS-Einträge verifiziert sind, führt smoxy automatisch folgende Schritte aus:

1. Anforderung eines Zertifikats bei Let's Encrypt

2. Abschluss der ACME-Challenge

3. Download und Installation des Zertifikats

4. Aktivierung des Zertifikats für deine Hostnamen

Schritt 3: Automatische Erneuerung

smoxy überwacht den Ablauf von Zertifikaten und startet den Erneuerungsprozess 30 Tage vor Ablauf. Die Erneuerung folgt dem gleichen Verifizierungsablauf. Wenn die DNS-Einträge noch vorhanden sind, erfolgt die Erneuerung vollständig automatisch.

---

Subject Alternative Names (SANs)

Ein Subject Alternative Name (SAN) ist ein einzelner Domainname, der von einem SSL-Zertifikat abgedeckt wird. Wenn du eine neue Domain in smoxy erstellst, werden zwei Standard-SANs hinzugefügt:

• deinedomain.com — die Root-Domain

• *.deinedomain.com — Wildcard für alle Subdomains

Zusätzliche SANs hinzufügen

Wenn du zusätzliche spezifische Subdomains abdecken musst (z. B. spezifisch.sub.deinedomain.com, die nicht vom Wildcard abgedeckt wird), kann smoxy zusätzliche SANs zu deinem Zertifikat hinzufügen. Jeder SAN benötigt seinen eigenen _acme-challenge CNAME-Eintrag zur DNS-Verifizierung.

SAN-Status

Jeder SAN hat zwei unabhängige Status:

Status	Werte	Bedeutung
DNS-Status	Valid / Missing	Ob der _acme-challenge CNAME-Eintrag korrekt konfiguriert ist
SSL-Status	Covered / Not covered	Ob das aktuelle Zertifikat diese Domain tatsächlich enthält

smoxy überprüft regelmäßig die DNS-Einträge:

• Alle 12 Stunden für gültige Einträge (um eine Entfernung zu erkennen)

• Jede 1 Stunde für fehlende Einträge (um zu erkennen, wenn du sie hinzugefügt hast)

Wenn neue SANs hinzugefügt und deren DNS verifiziert wurde, löst smoxy automatisch eine Zertifikatserneuerung aus, um die neuen Domains einzuschließen.

---

Zertifikatsstatus

Dein SSL-Zertifikat in smoxy kann sich in einem der folgenden Zustände befinden:

Status	Bedeutung	Handlungsbedarf
Active	Zertifikat ist gültig und funktioniert	Keiner
Pending	Zertifikatsgenerierung wurde gestartet, ist aber noch nicht abgeschlossen	Warte auf den Abschluss der Generierung
DNS Missing	Der _acme-challenge CNAME-Eintrag existiert nicht	Füge den erforderlichen CNAME-Eintrag bei deinem DNS-Anbieter hinzu
DNS Wrong	Der CNAME-Eintrag existiert, zeigt aber auf das falsche Ziel	Aktualisiere den CNAME auf das korrekte smoxy-Ziel
DNS Duplicate	Ein TXT-Eintrag existiert für _acme-challenge anstelle des erforderlichen CNAME	Entferne den TXT-Eintrag und erstelle stattdessen einen CNAME-Eintrag

Hinweis: Mehrere DNS-Probleme können gleichzeitig auftreten (z. B. können einige SANs fehlende Einträge haben, während andere auf falsche Ziele zeigen).

---

Workflow der Zertifikatsgenerierung

Im Hintergrund verfolgt smoxy die Zertifikatsgenerierung durch einen detaillierten Workflow:

Phase	Was passiert
Pending	Generierungsanfrage ist in der Warteschlange
Starting	Worker nimmt die Anfrage auf
CNAME Check	Verifizierung der DNS-Einträge für alle SANs
Ordering	Anforderung des Zertifikats bei Let's Encrypt
Validating	ACME-Challenge-Validierung läuft
Completed	Zertifikat erfolgreich ausgestellt und installiert

Wenn ein Fehler während der Generierung auftritt, versucht smoxy es automatisch mit exponentiellem Backoff erneut. Häufige Fehler sind:

Fehler	Ursache	Lösung
CNAME not found	DNS-Eintrag fehlt für einen oder mehrere SANs	Füge den/die fehlenden CNAME-Eintrag/Einträge hinzu
TXT record exists	Ein TXT-Eintrag für _acme-challenge kollidiert mit dem CNAME	Entferne den TXT-Eintrag, behalte nur den CNAME
Rate limit	Zu viele Zertifikatsanfragen bei Let's Encrypt	Automatisch — smoxy wartet und versucht es nach 1 Stunde erneut
Validation failed	ACME-Challenge konnte nicht verifiziert werden	Überprüfe die DNS-Propagierung; smoxy versucht es automatisch erneut
Cloudflare error	Cloudflare-Proxy stört die DNS-Verifizierung	Deaktiviere den Cloudflare-Proxy für den _acme-challenge Eintrag

---

Selbst verwaltetes Zertifikat hochladen

Um ein eigenes SSL-Zertifikat hochzuladen:

1. Navigiere zu Domains & DNS und wähle deine Domain aus

2. Gehe zum SSL-Tab

3. Klicke auf Eigenes SSL-Zertifikat hochladen

4. Stelle bereit:

   • Zertifikat (PEM-Format): Die vollständige Zertifikatskette, einschließlich Zwischenzertifikate

   • Private Key (PEM-Format): Der passende private Schlüssel

Validierung

Beim Upload validiert smoxy:

• Das Zertifikat ist parsebar und im gültigen PEM-Format

• Der Private Key passt zum Zertifikat

• Das Zertifikat ist nicht abgelaufen

• Die SANs im Zertifikat decken deine Domain ab

Wenn sich die SANs im neuen Zertifikat von den aktuellen unterscheiden, zeigt smoxy dir die Unterschiede an und bittet um Bestätigung, bevor fortgefahren wird.

Nach dem Upload

• Das vorherige Zertifikat wird zu Audit-Zwecken archiviert

• Das neue Zertifikat wird sofort aktiviert

• Da selbst verwaltete Zertifikate nicht automatisch erneuert werden, musst du vor Ablauf ein Ersatzzertifikat hochladen

---

Wildcard-Zertifikate

smoxy erstellt standardmäßig Wildcard-Zertifikate. Ein Wildcard-Zertifikat für *.deinedomain.com deckt ab:

• www.deinedomain.com

• shop.deinedomain.com

• api.deinedomain.com

• Jede andere einstufige Subdomain

Was Wildcards NICHT abdecken:

• Die Root-Domain selbst (deinedomain.com) — diese wird als separater SAN hinzugefügt

• Mehrstufige Subdomains (sub.sub.deinedomain.com) — diese benötigen zusätzliche SANs

Wenn du einen Hostnamen wie shop.deinedomain.com zu einer Site hinzufügst, prüft smoxy, ob das vorhandene Wildcard-Zertifikat ihn bereits abdeckt. Falls ja, ist keine zusätzliche Zertifikatsarbeit erforderlich.

---

Zertifikate herunterladen

Du kannst dein SSL-Zertifikat und den Private Key zur Verwendung in externen Tools herunterladen:

1. Navigiere zu Domains & DNS und wähle deine Domain aus

2. Gehe zum SSL-Tab

3. Klicke auf den Download-Button für das Zertifikat oder den Schlüssel

Erforderliche Rolle: Owner oder Maintainer

---

Subdomain-Wiederverwendung

Wenn du die Hauptdomain (z. B. deinedomain.com) erstellst und ein Wildcard-Zertifikat generiert wird, können alle Subdomains dieses Zertifikat wiederverwenden. Beim Hinzufügen von Subdomains als Hostnamen zu Sites:

• Es ist keine zusätzliche DNS-Verifizierung für die Subdomain erforderlich

• Das vorhandene Wildcard-Zertifikat deckt die Subdomain automatisch ab

• Dies beschleunigt die Einrichtung zusätzlicher Hostnamen erheblich

Empfehlung: Erstelle immer zuerst deine Hauptdomain und füge dann die Subdomains hinzu. So stellst du sicher, dass das Wildcard-Zertifikat vorhanden ist und Subdomains ohne zusätzliche SSL-Schritte konfiguriert werden können.

---

Fehlerbehebung

Zertifikat bleibt im Status "Pending"

• Überprüfe, ob alle erforderlichen _acme-challenge CNAME-Einträge bei deinem DNS-Anbieter gesetzt sind

• Die DNS-Propagierung kann bis zu 48 Stunden dauern (normalerweise aber deutlich schneller)

• Wenn du Cloudflare verwendest, stelle sicher, dass der Proxy für Challenge-Einträge deaktiviert ist

Status "DNS Missing"

Der _acme-challenge CNAME-Eintrag wurde nicht gefunden. Überprüfe:

• Der Eintrag existiert bei deinem DNS-Anbieter

• Er zeigt auf das korrekte Ziel (in smoxy angezeigt)

• Der DNS hatte genug Zeit zur Propagierung

Status "DNS Wrong"

Der CNAME-Eintrag existiert, zeigt aber auf ein falsches Ziel. Aktualisiere den Eintrag auf das in smoxy angezeigte Ziel.

Status "DNS Duplicate"

Ein TXT-Eintrag für _acme-challenge existiert neben oder anstelle des erforderlichen CNAME. Entferne den TXT-Eintrag und stelle sicher, dass nur der CNAME-Eintrag existiert.

Zertifikat erneuert sich nicht

• Automatisch verwaltete Zertifikate erneuern sich automatisch 30 Tage vor Ablauf

• Stelle sicher, dass die _acme-challenge CNAME-Einträge noch vorhanden sind

• Selbst verwaltete Zertifikate werden niemals automatisch erneuert — du musst ein Ersatzzertifikat hochladen

SAN-Änderungen werden nicht übernommen

Nach dem Hinzufügen neuer SANs muss smoxy das Zertifikat neu generieren. Dies geschieht automatisch, sobald die DNS-Verifizierung für den neuen SAN bestanden ist. Überprüfe den DNS-Status des SANs im SSL-Tab.