# SSL-Fehlerbehebung

Diese Anleitung behandelt häufige SSL-Probleme in smoxy und wie du sie beheben kannst.

***

### SSL-Status verstehen

Der SSL-Status deiner Domain ist auf dem **SSL-Tab** unter **Domains & DNS** sichtbar. Folgende Status weisen auf ein Problem hin:

#### Pending

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

**Was zu tun ist:**

* Überprüfe, ob alle `_acme-challenge` CNAME-Einträge bei deinem DNS-Anbieter konfiguriert sind
* Warte auf die DNS-Propagierung (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:**

* Überprüfe den DNS-Status jedes SANs im SSL-Tab
* Suche nach SANs mit dem DNS-Status „Missing" und korrigiere diese Einträge
* smoxy versucht es automatisch in zunehmenden Abständen erneut

#### DNS Missing

**Bedeutung:** Der erforderliche `_acme-challenge` CNAME-Eintrag wurde für einen oder mehrere SANs nicht gefunden.

**Lösung:**

1. Überprüfe den erwarteten CNAME-Eintrag, der in smoxy angezeigt wird
2. Füge den Eintrag bei deinem DNS-Anbieter hinzu:

   ```
   Typ:    CNAME
   Name:   _acme-challenge
   Ziel:   deine-org.acme.smoxy.eu  (wie in smoxy angezeigt)
   ```
3. Warte auf die DNS-Propagierung
4. smoxy überprüft fehlende Einträge jede **1 Stunde** und erkennt die Änderung automatisch

#### DNS Wrong

**Bedeutung:** Ein CNAME-Eintrag für `_acme-challenge` existiert, zeigt aber auf das falsche Ziel.

**Lösung:**

1. Gehe zu deinem DNS-Anbieter
2. Aktualisiere den `_acme-challenge` CNAME, sodass er auf das in smoxy angezeigte Ziel zeigt
3. smoxy wird den aktualisierten Eintrag bei der nächsten Prüfung verifizieren

#### DNS Duplicate

**Bedeutung:** Ein TXT-Eintrag für `_acme-challenge` existiert, der mit dem erforderlichen CNAME-Eintrag kollidiert.

**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. Entferne den TXT-Eintrag für `_acme-challenge` bei deinem DNS-Anbieter
2. Stelle sicher, dass nur der CNAME-Eintrag existiert
3. smoxy erkennt die Änderung bei der nächsten Prüfung

***

### Häufige Szenarien

#### Cloudflare-Nutzer

Wenn du Cloudflare als DNS-Anbieter verwendest:

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

Detaillierte Anweisungen findest du unter Cloudflare Setup.

#### Zertifikat erneuert sich nicht automatisch

Automatisch verwaltete Zertifikate erneuern sich 30 Tage 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** — Gehe zum SSL-Tab und überprüfe, ob alle SANs den DNS-Status „Valid" anzeigen
3. **Rate Limits** — Wenn smoxy die Let's Encrypt Rate Limits erreicht hat, wartet es 1 Stunde vor dem nächsten Versuch

{% hint style="info" %}
**Hinweis:** Selbst verwaltete Zertifikate werden **niemals** automatisch erneuert. Du musst selbst ein Ersatzzertifikat hochladen.
{% endhint %}

#### Mehrere Subdomains nicht abgedeckt

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

* Mehrstufige Subdomains wie `sub.shop.deinedomain.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 dein Zertifikat abgelaufen ist:

* **Automatisch verwaltet:** Überprüfe, ob die `_acme-challenge` DNS-Einträge noch vorhanden sind. Wenn ja, versucht smoxy eine Erneuerung. Wenn sie entfernt wurden, füge sie wieder hinzu.
* **Selbst verwaltet:** Lade ein neues Zertifikat hoch. smoxy kann Zertifikate, die es nicht generiert hat, nicht erneuern.

#### SSL-Generierung schlägt wiederholt fehl

Wenn du wiederholte Fehler im SSL-Generierungsprozess siehst:

| Fehler                    | Ursache                                      | Lösung                                                             |
| ------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
| CNAME not found           | DNS-Eintrag fehlt                            | Füge den erforderlichen CNAME-Eintrag hinzu                        |
| TXT ACME challenge exists | Kollidierender TXT-Eintrag                   | Entferne den TXT-Eintrag, behalte nur den CNAME                    |
| Rate limit                | Zu viele Let's Encrypt-Anfragen              | Automatisch — smoxy versucht es nach 1 Stunde erneut               |
| Validation failed         | DNS-Propagierung nicht abgeschlossen         | Warte auf die Propagierung, smoxy versucht es automatisch erneut   |
| Fetch DNS error           | DNS-Anbieter nicht erreichbar                | Vorübergehend — smoxy versucht es automatisch erneut               |
| No SAN error              | Keine Subject Alternative Names konfiguriert | Kontaktiere den Support — SANs sollten automatisch erstellt werden |

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

***

### Zertifikatsverifizierung

Um unabhängig zu überprüfen, ob dein SSL-Zertifikat funktioniert:

#### Im Browser

1. Besuche deine Domain mit `https://`
2. Klicke auf das Schloss-Symbol in der Adressleiste
3. Überprüfe die Zertifikatsdetails:
   * Ausgestellt für die korrekte Domain
   * Gültiger Zeitraum
   * Ausgestellt von der erwarteten CA (Let's Encrypt bei automatisch verwalteten Zertifikaten)

#### Per Kommandozeile

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

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

***

### Hilfe erhalten

Wenn du die Fehlerbehebungsschritte befolgt hast und dein SSL-Problem weiterhin besteht:

1. Notiere die genauen Statusmeldungen, die in smoxy angezeigt werden
2. Überprüfe das **Aktivitätsprotokoll** (unter Team-Einstellungen) auf SSL-bezogene Ereignisse
3. Kontaktiere den smoxy-Support mit deinem Domainnamen und den Fehlerdetails