Wildcard-Zertifikat mit Let's Encrypt über die DNS-Abfrage

Ein Wildcard-Zertifikat deckt alle Namen einer Ebene ab: shop.MeineDomain.de, mail.MeineDomain.de, kunde-4711.MeineDomain.de, auch solche, die es heute noch gar nicht gibt. Genau das ist der Grund, warum der bekannte Weg über den Webserver hier nicht mehr funktioniert. Diese Anleitung zeigt beide gangbaren Wege, den manuellen und den automatischen, und geht besonders auf die Stellen ein, an denen es in der Praxis schiefgeht.

Alles Folgende ist auf Debian 13, Debian 12, Ubuntu 24.04 LTS und Ubuntu 22.04 LTS geprüft. Die vier Systeme unterscheiden sich bei Certbot deutlicher, als die meisten Anleitungen zugeben, deshalb steht weiter unten eine Tabelle dazu.

Warum ein Wildcard-Zertifikat nur über DNS geht

Let's Encrypt kennt drei Prüfverfahren. Zwei davon scheiden für Wildcards aus:

• HTTP-01 legt eine Datei unter http://name/.well-known/acme-challenge/token ab. Für *.MeineDomain.de gibt es aber keinen einzelnen Namen, unter dem diese Datei liegen könnte. Die Zertifizierungsstelle müsste unendlich viele Hostnamen abfragen.
• TLS-ALPN-01 hat dasselbe Problem, es prüft ebenfalls einen konkreten Host auf Port 443.
• DNS-01 prüft einen TXT-Eintrag unter _acme-challenge.MeineDomain.de. Wer diesen Eintrag setzen kann, kontrolliert die Zone und damit auch jeden beliebigen Namen darunter. Das ist der einzige Nachweis, der zu einem Stern passt.

Praktisch heißt das: --apache, --nginx, --webroot und --standalone sind für Wildcards nicht verwendbar. Wer es trotzdem versucht, bekommt diese Meldung:

Client with the currently selected authenticator does not support any
combination of challenges that will satisfy the CA. You may need to use an
authenticator plugin that can do challenges over DNS.

Das ist kein Fehler in Ihrer Konfiguration, sondern die korrekte Antwort auf eine unmögliche Anfrage. Für den normalen Fall mit ein paar festen Namen ist der Webserver-Weg weiterhin richtig, den beschreiben wir im Beitrag zum kostenlosen SSL-Zertifikat mit Certbot.

Ein zweiter Punkt, den fast alle Anleitungen unterschlagen: Ein Wildcard-Zertifikat deckt nur die Namen eine Ebene tiefer ab. *.MeineDomain.de gilt für shop.MeineDomain.de, aber weder für MeineDomain.de selbst noch für a.b.MeineDomain.de. Die nackte Domain müssen Sie zusätzlich anfordern, und das hat Folgen für den TXT-Eintrag, siehe unten.

Voraussetzungen und die Paketlage je Distribution

Sie brauchen Root-Zugriff per SSH, eine Domain, deren Zone Sie verwalten, und Certbot. Ein laufender Webserver ist für die Ausstellung nicht nötig, Port 80 muss nicht offen sein. Das ist ein angenehmer Nebeneffekt: Sie können ein Zertifikat auch für einen Dienst ausstellen, der überhaupt nicht am Internet hängt.

Installieren Sie Certbot und die DNS-Werkzeuge:

apt update
apt install -y certbot bind9-dnsutils

Das Paket bind9-dnsutils liefert dig. Der alte Name dnsutils ist auf allen vier Systemen nur noch ein Platzhalter, der auf bind9-dnsutils zeigt. Prüfen Sie, welche Certbot-Version Sie bekommen haben:

certbot --version

Die Unterschiede sind erheblich, und sie entscheiden darüber, welcher Weg für Sie überhaupt offensteht:

Das ist die Überraschung: Debian 13 hat die meisten DNS-Erweiterungen aus dem Archiv geworfen. Wer unter Debian 12 mit python3-certbot-dns-ovh oder python3-certbot-dns-linode gearbeitet hat und auf Debian 13 aktualisiert, findet das Paket dort schlicht nicht mehr. Ein apt upgrade über die Distributionsgrenze hinweg entfernt es, und die Erneuerung bricht ab, ohne dass jemand hinschaut. Prüfen Sie das vor einem Distributionswechsel.

Welche Erweiterungen auf Ihrem System tatsächlich geladen werden, zeigt:

certbot plugins

Der manuelle Weg mit TXT-Eintrag

Der manuelle Weg braucht keinen API-Zugang und funktioniert bei jedem DNS-Anbieter. Er eignet sich zum Ausprobieren und für Zonen, die Sie ohnehin selten anfassen. Er hat einen gravierenden Nachteil, auf den wir gleich kommen.

Setzen Sie die TTL des künftigen TXT-Eintrags in Ihrer Zone vorher niedrig, 60 bis 300 Sekunden. Das kostet nichts und spart Ihnen später Wartezeit. Dann:

certbot certonly --manual --preferred-challenges dns \
  --cert-name meinedomain.de \
  -d "*.MeineDomain.de" -d MeineDomain.de

Die Anführungszeichen um "*.MeineDomain.de" sind Pflicht. Ohne sie ersetzt die Shell den Stern durch Dateinamen aus dem aktuellen Verzeichnis, und Certbot beantragt Zertifikate für Ihre Dateien. --cert-name ist ebenfalls dringend zu empfehlen: Certbot leitet den Namen der Zertifikatsablage sonst aus dem ersten Namen ab, und ein Verzeichnis mit einem Stern im Namen will niemand suchen müssen.

Certbot hält an und zeigt so etwas:

Please deploy a DNS TXT record under the name:
_acme-challenge.MeineDomain.de.

with the following value:

gfj9Xq...Rg85nM

Jetzt kommt der Punkt, an dem die meisten Versuche scheitern. Sie haben zwei Namen angefordert, den Stern und die nackte Domain. Das sind zwei getrennte Prüfungen, und beide landen auf demselben Eintragsnamen _acme-challenge.MeineDomain.de, mit zwei verschiedenen Werten. Certbot sagt das auch:

This must be set up in addition to the previous challenges; do not remove, replace, or undo the previous challenge tasks yet. Note that you might be asked to create multiple distinct TXT records with the same name. This is permitted by DNS standards.

Viele DNS-Oberflächen bieten für denselben Namen aber nur ein Eingabefeld und ersetzen den ersten Wert durch den zweiten. Dann steht am Ende nur ein Wert in der Zone, eine der beiden Prüfungen schlägt fehl, und die Fehlermeldung nennt trotzdem nur einen Namen. Wenn Ihre Oberfläche keine zwei TXT-Einträge mit gleichem Namen zulässt, ist das ein Ausschlusskriterium für den manuellen Weg. Nutzen Sie dann die Delegierung per CNAME, weiter unten.

Erst prüfen, dann Enter drücken

Certbot wartet auf Ihre Bestätigung. Drücken Sie nicht sofort Enter. Öffnen Sie eine zweite SSH-Sitzung und prüfen Sie zuerst am autoritativen Nameserver, nicht am lokalen Resolver:

dig +short NS MeineDomain.de
dig +short TXT _acme-challenge.MeineDomain.de @ns1.anbieter.example
dig +short TXT _acme-challenge.MeineDomain.de @1.1.1.1
dig +short TXT _acme-challenge.MeineDomain.de @8.8.8.8

Erst wenn beide Werte in einer Abfrage erscheinen, und zwar bei mehreren voneinander unabhängigen Resolvern, drücken Sie Enter. Eine leere Ausgabe bedeutet: Der Eintrag ist noch nicht da. So sieht das bei einer Domain ohne Eintrag aus, die Ausgabe bleibt leer:

dig +short TXT _acme-challenge.example.com @1.1.1.1

Warum der Umweg über den autoritativen Server? Wenn Sie _acme-challenge abfragen, bevor Sie den Eintrag angelegt haben, merkt sich Ihr Resolver die Nichtexistenz für die Dauer der negativen TTL aus dem SOA-Eintrag, oft eine Stunde. Sie sehen dann noch lange nichts, obwohl der Eintrag längst steht, und suchen den Fehler an der falschen Stelle. Der autoritative Server hat diesen Zwischenspeicher nicht.

Der Haken am manuellen Weg

Ein Zertifikat, das mit --manual und ohne Skript ausgestellt wurde, erneuert sich nie von selbst. Beim nächsten automatischen Lauf steht im Protokoll:

An authentication script must be provided with --manual-auth-hook when using
the manual plugin non-interactively.

Certbot überspringt dieses Zertifikat und macht mit den anderen weiter, der Rückgabewert bleibt oft unauffällig. Sie merken es, wenn der Browser meckert. Rechnen Sie also fest damit, alle 60 bis 90 Tage von Hand dieselbe Prozedur zu wiederholen, oder wechseln Sie auf einen der automatischen Wege.

Der automatische Weg über eine Anbieter-Erweiterung

Hat Ihr DNS-Anbieter eine Schnittstelle und gibt es dafür eine Certbot-Erweiterung, setzt Certbot den TXT-Eintrag selbst, wartet, lässt prüfen und räumt ihn wieder weg. Das ist der Weg, den Sie für produktive Systeme wollen. Am Beispiel Cloudflare:

apt install -y python3-certbot-dns-cloudflare

Legen Sie die Zugangsdaten außerhalb des Webverzeichnisses ab und schützen Sie sie sofort:

mkdir -p /root/.secrets/certbot
chmod 700 /root/.secrets/certbot

In /root/.secrets/certbot/cloudflare.ini gehört genau eine Zeile:

dns_cloudflare_api_token = IhrTokenHier

Danach unbedingt:

chmod 600 /root/.secrets/certbot/cloudflare.ini

Certbot warnt sonst bei jedem Lauf über zu weite Rechte. Nutzen Sie ein eingeschränktes Token mit Schreibrecht auf DNS-Einträge, nicht den globalen Kontoschlüssel. Der globale Schlüssel funktioniert zwar noch, kann aber alles in Ihrem Konto, und er liegt danach im Klartext auf dem Server. Ein Token lässt sich auf eine einzige Zone begrenzen und im Schadensfall einzeln zurückziehen.

Die Ausstellung:

certbot certonly --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/certbot/cloudflare.ini \
  --dns-cloudflare-propagation-seconds 60 \
  --cert-name meinedomain.de \
  -d "*.MeineDomain.de" -d MeineDomain.de

Der Wert für --propagation-seconds ist die Wartezeit zwischen Setzen des Eintrags und Prüfanfrage. Die Voreinstellung liegt bei 10 Sekunden und ist für viele Zonen zu knapp. 60 Sekunden sind ein guter Startwert, bei trägen Anbietern auch 120. Diese eine Zahl erklärt einen Großteil der sporadisch fehlschlagenden Erneuerungen, die sonst niemand reproduzieren kann.

Für andere Anbieter heißt das Paket python3-certbot-dns-<anbieter>, die Parameter folgen demselben Muster. Achten Sie auf die Tabelle oben, ob Ihr Anbieter auf Ihrer Distribution überhaupt dabei ist.

Wenn das passende Paket fehlt

Der naheliegende Reflex ist pip install certbot-dns-irgendwas. Auf Debian 12, Debian 13 und Ubuntu 24.04 endet das so:

error: externally-managed-environment

× This environment is externally managed

Das ist Absicht und kein Defekt. Auf Ubuntu 22.04 läuft derselbe Befehl noch durch, mischt dann aber pip-Pakete unter die Systempakete, und beim nächsten apt upgrade passen die Versionen von Certbot und Erweiterung nicht mehr zusammen. Erzwingen Sie das nicht mit --break-system-packages.

Der saubere Ausweg ist die Snap-Fassung von Certbot, die Erweiterungen mitbringt und sich selbst aktuell hält. Entfernen Sie vorher das Distributionspaket, damit nicht zwei Certbots dasselbe Verzeichnis verwalten:

apt remove -y certbot
snap install --classic certbot
ln -s /snap/bin/certbot /usr/bin/certbot
snap set certbot trust-plugin-with-root=ok
snap install certbot-dns-cloudflare

Wichtig: Die bestehenden Daten unter /etc/letsencrypt/ bleiben erhalten, das Snap übernimmt sie. Aber der systemd-Timer heißt danach snap.certbot.renew.timer und nicht mehr certbot.timer. Wer das übersieht, hat zwei Timer oder keinen.

Ohne Anbieter-Erweiterung: rfc2136 und CNAME-Delegierung

Zwei Verfahren funktionieren unabhängig davon, wen Sie als DNS-Anbieter haben.

rfc2136 ist der Standardweg für dynamische DNS-Aktualisierung mit TSIG-Schlüssel. Er funktioniert mit BIND, Knot und PowerDNS und ist auf allen vier Systemen als Paket vorhanden:

apt install -y python3-certbot-dns-rfc2136

Wenn Sie Ihren DNS selbst betreiben, ist das die robusteste Lösung, weil sie keinen fremden Dienst und keine HTTP-Schnittstelle braucht.

Die CNAME-Delegierung ist die elegantere Antwort auf zwei Probleme gleichzeitig. Sie legen in Ihrer Hauptzone einmalig einen unveränderlichen Eintrag an:

_acme-challenge.MeineDomain.de.  CNAME  MeineDomain.de.acme.eine-andere-zone.de.

Let's Encrypt folgt CNAME-Ketten bei der Suche nach dem TXT-Eintrag. Der TXT-Eintrag entsteht also in der Zielzone, und nur dort braucht der Server Schreibrechte. Das löst gleich mehrere Punkte:

• Die Zugangsdaten auf dem Webserver können nicht Ihre Hauptzone verändern. Ein kompromittierter Webserver kann keine MX-Einträge umbiegen.
• Die Zielzone darf mehrere TXT-Werte gleichzeitig führen, auch wenn die Oberfläche Ihres Hauptanbieters das nicht kann.
• Die Zielzone kann eine sehr niedrige TTL haben, ohne dass die Hauptzone darunter leidet.

Der CNAME selbst wird nie wieder angefasst, er darf eine hohe TTL haben. Prüfen lässt er sich mit:

dig +short CNAME _acme-challenge.MeineDomain.de @1.1.1.1

Die Erneuerung automatisieren

Certbot bringt aus dem Paket bereits einen Timer mit, der zweimal täglich läuft. Ein Zertifikat wird dabei nur erneuert, wenn es nötig ist:

systemctl list-timers certbot.timer

Falls er nicht läuft:

systemctl enable --now certbot.timer

Das Paket bringt auf allen vier Systemen zwei Auslöser mit: /lib/systemd/system/certbot.timer und zusätzlich /etc/cron.d/certbot. Die Cron-Datei prüft zu Beginn selbst, ob der Timer aktiv ist, und tut dann nichts, doppelt erneuert wird also nicht. Einen eigenen Renew-Cronjob brauchen Sie deshalb nicht, er wäre der dritte Auslöser für dieselbe Aufgabe.

Hier gibt es einen Unterschied zwischen den Distributionen, den man kennen sollte. Certbot bis Version 3 erneuert, wenn weniger als 30 Tage Restlaufzeit bleiben. Certbot 4.0, also die Fassung in Debian 13, erneuert stattdessen, wenn ein Drittel der Laufzeit übrig ist. Bei den heute üblichen 90 Tagen ergibt beides denselben Zeitpunkt. Sobald Let's Encrypt kürzer laufende Zertifikate ausgibt, verhalten sich die beiden Fassungen unterschiedlich, und nur die neue passt sich automatisch an.

Testen Sie den Ablauf im Trockenlauf. Dabei wird nichts ausgestellt und kein Limit verbraucht:

certbot renew --dry-run

Ein Wildcard-Zertifikat wird von Certbot nicht in die Webserver-Konfiguration eingetragen, das müssen Sie einmalig selbst tun. Damit der Webserver nach jeder Erneuerung das neue Zertifikat auch wirklich lädt, legen Sie einen Deploy-Hook an. Schreiben Sie ihn als Datei, nicht als Parameter:

mkdir -p /etc/letsencrypt/renewal-hooks/deploy

Der Inhalt von /etc/letsencrypt/renewal-hooks/deploy/reload-webserver.sh:

#!/bin/sh
systemctl reload nginx

Danach ausführbar machen:

chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-webserver.sh

Skripte in diesem Verzeichnis laufen für jedes erneuerte Zertifikat. Der Parameter --deploy-hook dagegen wird nur in die Erneuerungsdatei genau der Zertifikate geschrieben, die in diesem Moment behandelt wurden. Später hinzugekommene Zertifikate haben ihn dann nicht, und das fällt erst Monate danach auf.

Eine Warnung zu den API-Zugangsdaten: Wird das Token beim Anbieter zurückgezogen oder läuft es ab, schlägt die Erneuerung fehl, ohne dass irgendetwas offensichtlich kaputt ist. Das Zertifikat gilt ja noch. Erst 30 Tage später steht der Dienst. Prüfen Sie deshalb ab und zu, dass Zertifikate tatsächlich frischer werden, und verlassen Sie sich nicht auf Ablaufwarnungen per Mail.

Woran Sie erkennen, dass es wirklich geklappt hat

Dass der Befehl ohne Fehler durchlief, ist kein Nachweis. Diese drei Prüfungen sind einer. Erstens die Übersicht:

certbot certificates

Unter Domains müssen beide Namen stehen, *.MeineDomain.de und MeineDomain.de. Fehlt der Stern, haben Sie ein gewöhnliches Zertifikat bekommen und es nur nicht gemerkt.

Zweitens der Blick in die Datei selbst:

openssl x509 -noout -text -in /etc/letsencrypt/live/meinedomain.de/fullchain.pem | grep -A1 "Subject Alternative Name"

Dort muss DNS:*.MeineDomain.de auftauchen. Der Feldname Subject Alternative Name ist maßgeblich, nicht der Common Name, den moderne Browser gar nicht mehr auswerten.

Drittens, und das ist der eigentliche Beweis, fragen Sie einen Namen ab, den Sie sich gerade ausgedacht haben:

echo | openssl s_client -servername test-1234.MeineDomain.de -connect MeineDomain.de:443 2>/dev/null | openssl x509 -noout -subject -dates

Liefert das ein gültiges Zertifikat und keine Warnung, greift die Wildcard tatsächlich. Erst dann sind Sie fertig.

Häufige Fehler im Wortlaut

• "DNS problem: NXDOMAIN looking up TXT for _acme-challenge.MeineDomain.de": Der Eintrag existiert nicht, ist noch nicht verbreitet, oder Sie haben ihn beim falschen Anbieter angelegt. Der häufigste Fall: Die Domain ist zwar bei Anbieter A registriert, die Nameserver zeigen aber auf Anbieter B, und der Eintrag liegt bei A. Maßgeblich ist ausschließlich, was dig +short NS MeineDomain.de ausgibt.
• "Incorrect TXT record ... found at _acme-challenge.MeineDomain.de": Es steht ein Wert da, aber der falsche. Typisch nach einem Abbruch, wenn der alte Wert noch in der Zone liegt, oder wenn die Oberfläche den zweiten Wert über den ersten geschrieben hat. Alte _acme-challenge-Einträge löschen und neu beginnen.
• "DNS problem: SERVFAIL looking up TXT ... the domain's nameservers may be malfunctioning": Fast immer eine defekte DNSSEC-Signatur, etwa nach einem Anbieterwechsel, bei dem der alte DS-Eintrag bei der Registry stehen blieb. Vorher reparieren, sonst schlägt jede Ausstellung fehl.
• "CAA record for MeineDomain.de prevents issuance": Der oft übersehene Stolperstein. Für Wildcards wertet die Zertifizierungsstelle zuerst issuewild aus. Wer issue "letsencrypt.org" gesetzt hat, aber daneben ein issuewild ";" stehen hat, bekommt gewöhnliche Zertifikate und Wildcards nicht. Prüfen mit dig +short CAA MeineDomain.de.
• "too many certificates (5) already issued for this exact set of identifiers": Für dieselbe Namenskombination sind fünf Zertifikate in sieben Tagen erlaubt. Testen Sie deshalb mit --dry-run oder gegen die Testumgebung per --test-cert. Die Sperre läuft von selbst ab, aufheben lässt sie sich nicht.
• Die Oberfläche zeigt den TXT-Eintrag, dig aber nicht: Manche Anbieter verlangen, dass Änderungen an der Zone ausdrücklich veröffentlicht werden. Ein gespeicherter Eintrag ist nicht automatisch ein aktiver Eintrag.
• Der Eintragsname wird doppelt: Einige Oberflächen hängen die Domain automatisch an. Tragen Sie dort nur _acme-challenge ein, sonst entsteht _acme-challenge.MeineDomain.de.MeineDomain.de. Ein dig auf den vollständigen Namen deckt das sofort auf.

Ausblick: DNS-PERSIST-01

Let's Encrypt arbeitet an einem neuen Prüfverfahren namens DNS-PERSIST-01. Statt bei jeder Erneuerung einen frischen Token zu veröffentlichen, hinterlegen Sie einmalig einen dauerhaften Eintrag, der ein bestimmtes ACME-Konto zur Ausstellung berechtigt. Danach braucht der Server für die Erneuerung überhaupt keinen Schreibzugriff mehr auf das DNS. Für Wildcards wäre das ein deutlicher Gewinn an Sicherheit.

Nach dem Fahrplan von Let's Encrypt war die Testumgebung für Ende des ersten Quartals 2026 vorgesehen, der Produktivbetrieb für das zweite Quartal. Ob Certbot das Verfahren unterstützt, ist derzeit nicht angekündigt. Planen Sie also noch nicht damit, aber behalten Sie es im Blick, wenn Sie gerade eine Zertifikatsverwaltung neu aufbauen.

Zusammenfassung

Ein Wildcard-Zertifikat geht ausschließlich über die DNS-Abfrage, weil ein Stern sich nicht über einen einzelnen Webserver nachweisen lässt. Der manuelle Weg über einen TXT-Eintrag funktioniert überall, erneuert sich aber nie von selbst. Der Weg über eine Anbieter-Erweiterung ist der einzige, den Sie unbeaufsichtigt laufen lassen können, und er scheitert in der Praxis meist an zu kurzer Wartezeit oder an Zugangsdaten, die still ungültig geworden sind. Wenn Sie sich nur eine Sache merken: Prüfen Sie den TXT-Eintrag am autoritativen Nameserver, bevor Sie Certbot weiterlaufen lassen, und rechnen Sie bei Stern plus nackter Domain fest mit zwei Einträgen unter demselben Namen.