Let's Encrypt mit DNS-01-Challenge¶

Einführung¶

Was ist die DNS-01-Challenge?¶

DNS-01 ist eine alternative ACME (Automated Certificate Management Environment) Validierungsmethode, die den Domainbesitz durch DNS-TXT-Records anstelle von HTTP-Anfragen nachweist. Bei der Anforderung eines Zertifikats mit DNS-01:

Der ACME-Server (Let's Encrypt) stellt einen einzigartigen Token bereit
Ihr mailcow-Server erstellt automatisch einen DNS-TXT-Record _acme-challenge.ihredomain.de mit diesem Token
Let's Encrypt fragt DNS ab, um zu überprüfen, ob der Record existiert
Nach erfolgreicher Prüfung wird Ihr Zertifikat ausgestellt

mailcow nutzt acme.sh für die DNS-01-Validierung und unterstützt über 150 DNS-Provider über deren APIs.

Wann die DNS-Challenge verwenden?¶

Erwägen Sie die Verwendung der DNS-01-Challenge, wenn Sie Folgendes benötigen:

Wildcard-Zertifikate (*.example.de) - HTTP-01 kann keine Wildcard-Zertifikate ausstellen
Server hinter Firewall - Port 80 (HTTP) ist blockiert oder nicht öffentlich erreichbar
Komplexe Reverse-Proxy-Setups - HTTP-Validierung würde den falschen Server erreichen
Mehrere Server, die sich eine Domain teilen - HTTP-Challenge könnte einen anderen Server erreichen
Reduzierte externe Exposition - Kein Port 80 muss ins Internet exponiert werden

Wann NICHT die DNS-Challenge verwenden?¶

Bleiben Sie bei der Standard-HTTP-01-Challenge, wenn:

Sie ein einfaches Single-Server-Setup mit öffentlichem HTTP-Zugang haben (einfacher zu konfigurieren)
Ihr DNS-Provider keinen API-Zugang bietet oder von acme.sh nicht unterstützt wird
Sie den DNS-API-Zugang aufgrund organisatorischer Einschränkungen nicht automatisieren können
Sie keine Wildcard-Zertifikate benötigen

Standard-Methode

mailcow verwendet standardmäßig die HTTP-01-Challenge, die für die meisten Installationen gut funktioniert. Wechseln Sie nur zu DNS-01, wenn Sie einen spezifischen Bedarf dafür haben.

Voraussetzungen¶

Bevor Sie die DNS-01-Challenge aktivieren, stellen Sie sicher, dass Sie Folgendes haben:

mailcow Version 2026-03 oder neuer
Einen unterstützten DNS-Provider mit API-Zugang (siehe Unterstützte DNS-Provider)
API-Zugangsdaten von Ihrem DNS-Provider mit Berechtigung zum Bearbeiten von DNS-Records
Verständnis Ihrer DNS-Zonenstruktur (welche Domains/Subdomains Zertifikate benötigen)

Konfiguration¶

Schritt 1: DNS-Challenge in mailcow.conf aktivieren¶

Bearbeiten Sie /opt/mailcow-dockerized/mailcow.conf und fügen Sie folgende Parameter hinzu oder ändern Sie sie:

# DNS-01-Challenge aktivieren (statt HTTP-01)
ACME_DNS_CHALLENGE=y

# DNS-Provider-Plugin angeben (siehe Provider-Liste unten)
# Beispiel: dns_servercow für Servercow, dns_cf für CloudFlare, dns_aws für AWS Route53
ACME_DNS_PROVIDER=dns_servercow

# E-Mail-Adresse für ACME-Account-Registrierung
ACME_ACCOUNT_EMAIL=admin@example.de

Wichtige Einstellungen

Wenn ACME_DNS_CHALLENGE=y gesetzt ist, ignoriert mailcow SKIP_HTTP_VERIFICATION (es ist impliziert)
Port 80 wird für DNS-Challenge nicht benötigt
Alle Domains in Ihrer mailcow-Installation verwenden DNS-01 (HTTP-01 und DNS-01 können nicht gemischt werden)

Schritt 2: DNS-Provider-Zugangsdaten konfigurieren¶

Erstellen oder bearbeiten Sie /opt/mailcow-dockerized/data/conf/acme/dns-01.conf:

# Servercow Beispiel
SERVERCOW_API_Username="servercow-api-username"
SERVERCOW_API_Password="servercow-api-password"

Das Dateiformat sind einfache key=value Paare. Jeder DNS-Provider benötigt unterschiedliche Variablen - siehe Konfigurations-Beispiele für Ihren spezifischen Provider.

Schritt 3: Konfiguration anwenden¶

Starten Sie den acme-mailcow-Container neu, um die Änderungen anzuwenden:

docker compose (Plugin)docker-compose (Standalone)

cd /opt/mailcow-dockerized
docker compose up -d

cd /opt/mailcow-dockerized
docker-compose up -d

Schritt 4: Zertifikatsanforderung überwachen¶

Beobachten Sie die Logs, um zu überprüfen, ob die DNS-Challenge funktioniert:

docker compose (Plugin)docker-compose (Standalone)

docker compose logs -f acme-mailcow

docker-compose logs -f acme-mailcow

Unterstützte DNS-Provider¶

mailcow nutzt acme.sh DNS-API-Plugins. Über 150 Provider werden unterstützt.

Tier 1: Vollständig getestet & empfohlen¶

Provider	Plugin-Name	Benötigte Zugangsdaten	Dokumentation
Servercow	`dns_servercow`	`SERVERCOW_API_Username`, `SERVERCOW_API_Password`	Servercow API
CloudFlare	`dns_cf`	`CF_Token`, `CF_Account_ID`	CloudFlare DNS API
AWS Route53	`dns_aws`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	Route53 API
Azure DNS	`dns_azure`	`AZUREDNS_SUBSCRIPTIONID`, `AZUREDNS_TENANTID`, `AZUREDNS_APPID`, `AZUREDNS_CLIENTSECRET`	Azure API
Google Cloud DNS	`dns_gcloud`	`CLOUDSDK_ACTIVE_CONFIG_NAME`	GCloud API
DigitalOcean	`dns_dgon`	`DO_API_KEY`	DigitalOcean API

Tier 2: Community-getestet¶

Provider	Plugin-Name	Hinweise
Hetzner	`dns_hetzner`	Beliebt in Deutschland/Europa
IONOS	`dns_ionos`	Deutscher Provider (früher 1&1)
Strato	`dns_strato`	Deutscher Hosting-Provider
OVH	`dns_ovh`	Europäischer Provider
Namecheap	`dns_namecheap`	Benötigt DDNS-Passwort, nicht Standard-API
GoDaddy	`dns_gd`	API-Key + API-Secret erforderlich
Linode	`dns_linode`	API-Token

Vollständige Provider-Liste: acme.sh DNS API Dokumentation (150+ Provider)

Provider nicht aufgeführt?

Wenn Ihr Provider DNS-API unterstützt und in der acme.sh-Dokumentation aufgeführt ist, sollte er mit mailcow funktionieren. Prüfen Sie das acme.sh Wiki für Konfigurationsdetails.

Wildcard-Zertifikate¶

Die DNS-01-Challenge ist die einzige Möglichkeit, Wildcard-Zertifikate von Let's Encrypt zu erhalten.

Konfigurations-Beispiel¶

Bearbeiten Sie mailcow.conf:

MAILCOW_HOSTNAME=mail.example.de
ADDITIONAL_SAN=*.example.de,example.de
ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_servercow

Wildcard-Einschränkungen

*.example.de deckt mail.example.de, webmail.example.de, smtp.example.de, etc. ab
*.example.de deckt NICHT example.de (die Apex/Root-Domain) ab
Sie müssen beides explizit hinzufügen: ADDITIONAL_SAN=*.example.de,example.de

Konfigurations-Beispiele¶

Beispiel 1: Servercow mit Wildcard¶

Szenario: mailcow bei Servercow gehostet, einzelne Domain mit Wildcard-Zertifikat

mailcow.conf:

MAILCOW_HOSTNAME=mail.example.de
ADDITIONAL_SAN=*.example.de,example.de

# DNS-01-Challenge-Konfiguration
ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_servercow
ACME_ACCOUNT_EMAIL=admin@example.de

data/conf/acme/dns-01.conf:

# Servercow API-Zugangsdaten
# Abrufen unter: https://cp.servercow.de
# API > API-Benutzer > Neuen Benutzer erstellen oder existierenden verwenden
SERVERCOW_API_Username="ihr-servercow-api-benutzername"
SERVERCOW_API_Password="ihr-servercow-api-passwort"

Servercow API-Benutzer erstellen:

Einloggen im Servercow Control Panel
Navigation zu API > API-Benutzer
Klick auf API-Benutzer erstellen oder existierenden API-Benutzer verwenden
Benutzername und Passwort notieren
Sicherstellen, dass der API-Benutzer DNS-Verwaltungsrechte hat

Beispiel 2: CloudFlare mit Wildcard¶

Szenario: Kleines Unternehmen, einzelne Domain, Wildcard-Zertifikat für alle Subdomains gewünscht

mailcow.conf:

MAILCOW_HOSTNAME=mail.example.de
ADDITIONAL_SAN=*.example.de,example.de

# DNS-01-Challenge-Konfiguration
ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_cf
ACME_ACCOUNT_EMAIL=admin@example.de

data/conf/acme/dns-01.conf:

# CloudFlare API-Token (NICHT Global API Key!)
# Erstellen unter: https://dash.cloudflare.com/profile/api-tokens
# Berechtigungen: Zone > DNS > Edit für Zone 'example.de'
CF_Token="ihr_cloudflare_api_token_hier"
CF_Account_ID="ihre_cloudflare_account_id"

CloudFlare API-Token erstellen:

Gehen Sie zum CloudFlare Dashboard
Klicken Sie auf "Token erstellen"
Verwenden Sie die Vorlage "Zone-DNS bearbeiten" oder erstellen Sie einen benutzerdefinierten Token mit:
Berechtigungen: Zone > DNS > Bearbeiten
Zonenressourcen: Einschließen > Bestimmte Zone > example.de
Kopieren Sie den Token (wird nur einmal angezeigt!)

Beispiel 3: Hetzner (Deutschland)¶

Szenario: Deutscher Hosting-Provider, beliebt in Europa

mailcow.conf:

MAILCOW_HOSTNAME=mail.example.de
ADDITIONAL_SAN=*.example.de

ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_hetzner
ACME_ACCOUNT_EMAIL=admin@example.de

data/conf/acme/dns-01.conf:

# Hetzner DNS API-Token
# Erstellen unter: https://dns.hetzner.com/settings/api-token
HETZNER_Token="ihr-hetzner-api-token-hier"

Beispiel 4: IONOS (Deutschland)¶

Szenario: IONOS (früher 1&1), deutscher Provider

mailcow.conf:

MAILCOW_HOSTNAME=mail.example.de
ADDITIONAL_SAN=*.example.de

ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_ionos
ACME_ACCOUNT_EMAIL=admin@example.de

data/conf/acme/dns-01.conf:

# IONOS API-Key
# Abrufen im IONOS-Kundenbereich unter Developer Tools
IONOS_API_KEY="ihr-ionos-api-key"

Beispiel 5: AWS Route53 (Multi-Domain)¶

Szenario: Mehrere Domains auf AWS gehostet, Unternehmenssetup

mailcow.conf:

MAILCOW_HOSTNAME=mail.firma.de
ADDITIONAL_SAN=smtp.firma.de,mail.abteilung.de

ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_aws
ACME_ACCOUNT_EMAIL=admin@firma.de

data/conf/acme/dns-01.conf:

# AWS IAM User Zugangsdaten
# IAM User: mailcow-acme-dns
# Policy: Angehängte benutzerdefinierte Richtlinie (siehe unten)
AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Empfohlene IAM-Richtlinie (minimale Rechte):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "route53:GetChange",
        "route53:ListHostedZones"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": "arn:aws:route53:::hostedzone/Z1234567890ABC"
    }
  ]
}

Ersetzen Sie Z1234567890ABC durch Ihre tatsächliche Hosted-Zone-ID.

Zusätzliche Ressourcen¶

acme.sh DNS API Dokumentation - Vollständige Liste von 150+ unterstützten DNS-Providern mit Konfigurationsbeispielen
Let's Encrypt Challenge-Typen - Offizielle Dokumentation zu HTTP-01 vs DNS-01
Let's Encrypt Rate Limits - Limits für Zertifikatsausstellung
mailcow SSL Dokumentation (HTTP-01) - Standard HTTP-basierte Zertifikatsausstellung
mailcow Reverse Proxy Setup - mailcow hinter Reverse Proxies verwenden
mailcow DNS Voraussetzungen - Für Mail-Betrieb erforderliche DNS-Records