Certyfikat wildcard Let's Encrypt przez weryfikację DNS

Certyfikat wildcard obejmuje wszystkie nazwy na jednym poziomie: shop.MojaDomena.pl, mail.MojaDomena.pl, klient-4711.MojaDomena.pl, także te, których dzisiaj jeszcze w ogóle nie ma. Właśnie dlatego znana droga przez serwer WWW przestaje tutaj działać. Ten poradnik pokazuje obie możliwe drogi, ręczną i automatyczną, i zwraca szczególną uwagę na te punkty, w których w praktyce coś się sypie.

Wszystko, co następuje, zostało sprawdzone na Debianie 13, Debianie 12, Ubuntu 24.04 LTS oraz Ubuntu 22.04 LTS. Te cztery systemy różnią się pod względem Certbota wyraźniej, niż przyznaje większość poradników, dlatego niżej znajdziesz osobną tabelę.

Dlaczego certyfikat wildcard działa wyłącznie przez DNS

Let's Encrypt zna trzy metody weryfikacji. Dwie z nich odpadają przy certyfikatach wildcard:

• HTTP-01 odkłada plik pod adresem http://name/.well-known/acme-challenge/token. Dla *.MojaDomena.pl nie istnieje jednak żadna pojedyncza nazwa, pod którą ten plik mógłby leżeć. Urząd certyfikacji musiałby odpytać nieskończenie wiele nazw hostów.
• TLS-ALPN-01 ma ten sam problem, bo również sprawdza konkretny host na porcie 443.
• DNS-01 sprawdza rekord TXT pod nazwą _acme-challenge.MojaDomena.pl. Kto potrafi utworzyć ten rekord, ten kontroluje strefę, a więc również dowolną nazwę pod nią. To jedyny dowód, który pasuje do gwiazdki.

W praktyce oznacza to, że --apache, --nginx, --webroot i --standalone nie nadają się do certyfikatów wildcard. Kto mimo wszystko spróbuje, dostanie taki komunikat:

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.

To nie jest błąd w twojej konfiguracji, tylko poprawna odpowiedź na niemożliwe żądanie. W zwykłym przypadku, z kilkoma stałymi nazwami, droga przez serwer WWW pozostaje właściwa, a opisujemy ją we wpisie o darmowym certyfikacie SSL z Certbotem.

Drugi punkt, który pomija niemal każdy poradnik: certyfikat wildcard obejmuje wyłącznie nazwy o jeden poziom niżej. *.MojaDomena.pl obowiązuje dla shop.MojaDomena.pl, ale ani dla samej MojaDomena.pl, ani dla a.b.MojaDomena.pl. Domenę główną musisz zamówić dodatkowo, a to ma konsekwencje dla rekordu TXT, o czym niżej.

Wymagania i sytuacja pakietowa w poszczególnych dystrybucjach

Potrzebujesz dostępu roota przez SSH, domeny, której strefą sam zarządzasz, oraz Certbota. Do wystawienia certyfikatu nie jest potrzebny działający serwer WWW, port 80 nie musi być otwarty. To przyjemny efekt uboczny: certyfikat możesz wystawić także dla usługi, która w ogóle nie wisi w internecie.

Zainstaluj Certbota i narzędzia DNS:

apt update
apt install -y certbot bind9-dnsutils

Pakiet bind9-dnsutils dostarcza dig. Stara nazwa dnsutils jest na wszystkich czterech systemach już tylko pakietem przejściowym, który wskazuje na bind9-dnsutils. Sprawdź, jaka wersja Certbota ci się trafiła:

certbot --version

Różnice są znaczne i to one decydują, która droga w ogóle stoi przed tobą otworem:

I tu niespodzianka: Debian 13 wyrzucił z archiwum większość wtyczek DNS. Kto pod Debianem 12 pracował z python3-certbot-dns-ovh albo python3-certbot-dns-linode i zaktualizuje system do Debiana 13, po prostu nie znajdzie tam już tego pakietu. apt upgrade przez granicę dystrybucji go usuwa, a odnawianie przerywa się, choć nikt na to nie patrzy. Sprawdź to przed zmianą dystrybucji.

Które wtyczki faktycznie ładują się w twoim systemie, pokaże:

certbot plugins

Droga ręczna z rekordem TXT

Droga ręczna nie wymaga dostępu do API i działa u każdego dostawcy DNS. Nadaje się do wypróbowania rozwiązania oraz do stref, w których i tak rzadko cokolwiek zmieniasz. Ma jedną poważną wadę, do której zaraz przejdziemy.

Wcześniej obniż w swojej strefie TTL przyszłego rekordu TXT, na wartość od 60 do 300 sekund. Nic to nie kosztuje, a później oszczędza czas oczekiwania. Następnie:

certbot certonly --manual --preferred-challenges dns \
  --cert-name mojadomena.pl \
  -d "*.MojaDomena.pl" -d MojaDomena.pl

Cudzysłowy wokół "*.MojaDomena.pl" są obowiązkowe. Bez nich shell podmieni gwiazdkę na nazwy plików z bieżącego katalogu, a Certbot poprosi o certyfikaty dla twoich plików. --cert-name również gorąco polecamy: w przeciwnym razie Certbot wyprowadzi nazwę katalogu z certyfikatem od pierwszej nazwy, a katalogu z gwiazdką w nazwie nikt nie chce szukać.

Certbot zatrzymuje się i pokazuje coś takiego:

Please deploy a DNS TXT record under the name:
_acme-challenge.MojaDomena.pl.

with the following value:

gfj9Xq...Rg85nM

Teraz dochodzimy do punktu, na którym rozbija się większość prób. Zamówiłeś dwie nazwy, gwiazdkę i domenę główną. To dwie osobne weryfikacje i obie lądują pod tą samą nazwą rekordu _acme-challenge.MojaDomena.pl, z dwiema różnymi wartościami. Certbot zresztą sam to mówi:

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.

Wiele paneli DNS oferuje jednak dla tej samej nazwy tylko jedno pole i zastępuje pierwszą wartość drugą. W strefie zostaje wtedy tylko jedna wartość, jedna z dwóch weryfikacji się nie udaje, a komunikat błędu i tak wymienia tylko jedną nazwę. Jeśli twój panel nie dopuszcza dwóch rekordów TXT o tej samej nazwie, droga ręczna odpada. Skorzystaj wtedy z delegowania przez CNAME, opisanego niżej.

Najpierw sprawdź, dopiero potem naciśnij Enter

Certbot czeka na twoje potwierdzenie. Nie naciskaj Entera od razu. Otwórz drugą sesję SSH i odpytaj najpierw autorytatywny serwer nazw, a nie lokalny resolver:

dig +short NS MojaDomena.pl
dig +short TXT _acme-challenge.MojaDomena.pl @ns1.dostawca.example
dig +short TXT _acme-challenge.MojaDomena.pl @1.1.1.1
dig +short TXT _acme-challenge.MojaDomena.pl @8.8.8.8

Enter naciśnij dopiero wtedy, gdy w jednym zapytaniu pojawią się obie wartości, i to u kilku niezależnych od siebie resolverów. Pusty wynik oznacza, że rekordu jeszcze nie ma. Tak wygląda to przy domenie bez rekordu, wynik pozostaje pusty:

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

Po co ten objazd przez serwer autorytatywny? Jeśli odpytasz _acme-challenge, zanim założysz rekord, twój resolver zapamięta jego nieistnienie na czas negatywnego TTL z rekordu SOA, często na całą godzinę. Wtedy jeszcze długo niczego nie zobaczysz, choć rekord dawno już stoi, i będziesz szukać błędu w złym miejscu. Serwer autorytatywny tego cache'u nie ma.

Haczyk drogi ręcznej

Certyfikat wystawiony przez --manual i bez skryptu nigdy nie odnawia się sam. Przy następnym automatycznym przebiegu w logu pojawia się:

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

Certbot pomija ten certyfikat i idzie dalej z pozostałymi, a kod wyjścia zwykle niczego nie zdradza. Zorientujesz się dopiero, gdy przeglądarka zacznie protestować. Licz się więc na pewno z tym, że co 60 do 90 dni powtórzysz ręcznie tę samą procedurę, albo przejdź na jedną z dróg automatycznych.

Droga automatyczna przez wtyczkę dostawcy

Jeśli twój dostawca DNS ma API, a do tego istnieje odpowiednia wtyczka Certbota, to Certbot sam zakłada rekord TXT, czeka, pozwala go zweryfikować i na koniec sam go sprząta. To droga, której chcesz dla systemów produkcyjnych. Na przykładzie Cloudflare:

apt install -y python3-certbot-dns-cloudflare

Odłóż dane dostępowe poza katalogiem WWW i od razu je zabezpiecz:

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

W pliku /root/.secrets/certbot/cloudflare.ini ma się znaleźć dokładnie jeden wiersz:

dns_cloudflare_api_token = TwojTokenTutaj

Potem koniecznie:

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

Inaczej Certbot przy każdym przebiegu ostrzega o zbyt szerokich uprawnieniach. Używaj ograniczonego tokenu z prawem zapisu do rekordów DNS, a nie globalnego klucza konta. Globalny klucz wprawdzie nadal działa, ale potrafi w twoim koncie wszystko, a potem leży na serwerze w postaci jawnej. Token da się ograniczyć do jednej strefy i w razie wpadki unieważnić osobno.

Wystawienie certyfikatu:

certbot certonly --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/certbot/cloudflare.ini \
  --dns-cloudflare-propagation-seconds 60 \
  --cert-name mojadomena.pl \
  -d "*.MojaDomena.pl" -d MojaDomena.pl

Wartość --propagation-seconds to czas oczekiwania między założeniem rekordu a zapytaniem weryfikacyjnym. Domyślnie wynosi 10 sekund i dla wielu stref jest zbyt krótki. 60 sekund to dobry punkt wyjścia, u ospałych dostawców nawet 120. Ta jedna liczba tłumaczy sporą część sporadycznie nieudanych odnowień, których poza tym nikt nie potrafi odtworzyć.

U innych dostawców pakiet nazywa się python3-certbot-dns-<dostawca>, a parametry trzymają się tego samego wzorca. Zerknij do tabeli powyżej, czy twój dostawca w ogóle jest obecny w twojej dystrybucji.

Gdy brakuje pasującego pakietu

Odruch nasuwa się sam: pip install certbot-dns-cokolwiek. Na Debianie 12, Debianie 13 i Ubuntu 24.04 kończy się to tak:

error: externally-managed-environment

× This environment is externally managed

To zamierzone działanie, a nie usterka. Na Ubuntu 22.04 to samo polecenie jeszcze przechodzi, ale miesza pakiety z pipa z pakietami systemowymi, a przy następnym apt upgrade wersje Certbota i wtyczki przestają do siebie pasować. Nie wymuszaj tego przez --break-system-packages.

Czystym wyjściem jest wersja snap Certbota, która przynosi wtyczki ze sobą i sama utrzymuje się w aktualnym stanie. Wcześniej usuń pakiet z dystrybucji, żeby dwa Certboty nie zarządzały tym samym katalogiem:

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

Ważne: istniejące dane w /etc/letsencrypt/ zostają na miejscu, snap je przejmuje. Ale timer systemd nazywa się potem snap.certbot.renew.timer, a już nie certbot.timer. Kto to przeoczy, ma dwa timery albo żadnego.

Bez wtyczki dostawcy: rfc2136 i delegowanie CNAME

Dwie metody działają niezależnie od tego, kogo masz jako dostawcę DNS.

rfc2136 to standardowa droga dynamicznej aktualizacji DNS z kluczem TSIG. Działa z BIND, Knot i PowerDNS, a na wszystkich czterech systemach jest dostępna jako pakiet:

apt install -y python3-certbot-dns-rfc2136

Jeśli prowadzisz własny DNS, to najodporniejsze rozwiązanie, bo nie potrzebuje żadnej obcej usługi ani żadnego API HTTP.

Delegowanie przez CNAME to bardziej eleganckie rozwiązanie dwóch problemów naraz. W swojej strefie głównej zakładasz jednorazowo niezmienny rekord:

_acme-challenge.MojaDomena.pl.  CNAME  MojaDomena.pl.acme.inna-strefa.pl.

Let's Encrypt podąża za łańcuchami CNAME, gdy szuka rekordu TXT. Rekord TXT powstaje więc w strefie docelowej i tylko tam serwer potrzebuje prawa zapisu. To rozwiązuje od razu kilka spraw:

• Dane dostępowe na serwerze WWW nie mogą zmienić twojej strefy głównej. Przejęty serwer WWW nie przestawi rekordów MX.
• Strefa docelowa może prowadzić kilka wartości TXT jednocześnie, nawet jeśli panel twojego głównego dostawcy tego nie potrafi.
• Strefa docelowa może mieć bardzo niski TTL, a strefa główna na tym nie ucierpi.

Samego CNAME już nigdy nie ruszasz, więc może mieć wysoki TTL. Sprawdzisz go przez:

dig +short CNAME _acme-challenge.MojaDomena.pl @1.1.1.1

Automatyzacja odnawiania

Certbot przynosi już z pakietu timer, który uruchamia się dwa razy dziennie. Certyfikat zostaje przy tym odnowiony tylko wtedy, gdy jest to potrzebne:

systemctl list-timers certbot.timer

Jeśli nie działa:

systemctl enable --now certbot.timer

Na wszystkich czterech systemach pakiet przynosi dwa wyzwalacze: /lib/systemd/system/certbot.timer oraz dodatkowo /etc/cron.d/certbot. Plik crona sam na początku sprawdza, czy timer jest aktywny, i wtedy nic nie robi, więc do podwójnego odnowienia nie dochodzi. Własnego cronjoba do odnawiania nie potrzebujesz, byłby trzecim wyzwalaczem tego samego zadania.

Jest tu różnica między dystrybucjami, którą warto znać. Certbot do wersji 3 odnawia certyfikat, gdy zostaje mniej niż 30 dni ważności. Certbot 4.0, czyli wersja z Debiana 13, odnawia go zamiast tego wtedy, gdy została jedna trzecia okresu ważności. Przy dzisiejszych 90 dniach obie reguły dają ten sam moment. Gdy tylko Let's Encrypt zacznie wydawać certyfikaty o krótszej ważności, obie wersje zaczną zachowywać się inaczej, a tylko ta nowa dostosuje się automatycznie.

Przetestuj cały przebieg na sucho. Nic wtedy nie zostaje wystawione i żaden limit się nie zużywa:

certbot renew --dry-run

Certyfikatu wildcard Certbot nie wpisuje do konfiguracji serwera WWW, to musisz zrobić jednorazowo sam. Żeby serwer WWW po każdym odnowieniu naprawdę ładował nowy certyfikat, załóż deploy hook. Zapisz go jako plik, nie jako parametr:

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

Zawartość pliku /etc/letsencrypt/renewal-hooks/deploy/reload-webserver.sh:

#!/bin/sh
systemctl reload nginx

Potem nadaj mu prawo wykonywania:

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

Skrypty w tym katalogu uruchamiają się dla każdego odnowionego certyfikatu. Parametr --deploy-hook trafia natomiast tylko do pliku odnowienia dokładnie tych certyfikatów, które akurat w tej chwili były obsługiwane. Certyfikaty dodane później już go nie mają, a wychodzi to na jaw dopiero po miesiącach.

Jedno ostrzeżenie co do danych dostępowych do API: jeśli token zostanie u dostawcy unieważniony albo wygaśnie, odnowienie się nie powiedzie, a na pierwszy rzut oka nic nie będzie zepsute. Certyfikat przecież nadal obowiązuje. Dopiero 30 dni później usługa staje. Sprawdzaj więc od czasu do czasu, czy certyfikaty faktycznie robią się świeższe, i nie polegaj na ostrzeżeniach o wygaśnięciu wysyłanych e-mailem.

Po czym poznasz, że naprawdę się udało

To, że polecenie przeszło bez błędu, niczego nie dowodzi. Dowodzą dopiero te trzy sprawdzenia. Po pierwsze, przegląd:

certbot certificates

Pod Domains muszą stać obie nazwy, *.MojaDomena.pl oraz MojaDomena.pl. Jeśli brakuje gwiazdki, dostałeś zwykły certyfikat i tylko tego nie zauważyłeś.

Po drugie, zajrzyj do samego pliku:

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

Musi się tam pojawić DNS:*.MojaDomena.pl. Decydujące jest pole Subject Alternative Name, a nie Common Name, którego nowoczesne przeglądarki w ogóle już nie analizują.

Po trzecie, i to jest właściwy dowód, odpytaj nazwę, którą przed chwilą wymyśliłeś:

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

Jeśli dostaniesz ważny certyfikat i żadnego ostrzeżenia, wildcard naprawdę działa. Dopiero wtedy jesteś gotowy.

Częste błędy w oryginalnym brzmieniu

• „DNS problem: NXDOMAIN looking up TXT for _acme-challenge.MojaDomena.pl”: rekord nie istnieje, jeszcze się nie rozpropagował albo założyłeś go u niewłaściwego dostawcy. Najczęstszy przypadek: domena jest zarejestrowana u dostawcy A, ale serwery nazw wskazują na dostawcę B, a rekord leży u A. Decyduje wyłącznie to, co wypisze dig +short NS MojaDomena.pl.
• „Incorrect TXT record ... found at _acme-challenge.MojaDomena.pl”: jakaś wartość tam stoi, ale niewłaściwa. Typowe po przerwanym przebiegu, gdy stara wartość nadal leży w strefie, albo gdy panel nadpisał pierwszą wartość drugą. Usuń stare rekordy _acme-challenge i zacznij od nowa.
• „DNS problem: SERVFAIL looking up TXT ... the domain's nameservers may be malfunctioning”: prawie zawsze uszkodzony podpis DNSSEC, na przykład po zmianie dostawcy, przy której stary rekord DS został w rejestrze. Napraw to najpierw, bo inaczej każde wystawienie certyfikatu się nie powiedzie.
• „CAA record for MojaDomena.pl prevents issuance”: często przeoczana pułapka. Przy certyfikatach wildcard urząd certyfikacji ocenia najpierw issuewild. Kto ustawił issue "letsencrypt.org", ale obok ma issuewild ";", dostanie zwykłe certyfikaty, ale wildcard już nie. Sprawdzisz to przez dig +short CAA MojaDomena.pl.
• „too many certificates (5) already issued for this exact set of identifiers”: dla tej samej kombinacji nazw dozwolonych jest pięć certyfikatów w ciągu siedmiu dni. Testuj więc z --dry-run albo w środowisku testowym przez --test-cert. Blokada wygasa sama, zdjąć się jej nie da.
• Panel pokazuje rekord TXT, a dig już nie: niektórzy dostawcy wymagają, żeby zmiany w strefie zostały wyraźnie opublikowane. Zapisany rekord nie jest automatycznie rekordem aktywnym.
• Nazwa rekordu podwaja się: niektóre panele dopisują domenę automatycznie. Wpisuj tam samo _acme-challenge, bo inaczej powstanie _acme-challenge.MojaDomena.pl.MojaDomena.pl. dig na pełną nazwę odsłania to natychmiast.

Perspektywy: DNS-PERSIST-01

Let's Encrypt pracuje nad nową metodą weryfikacji o nazwie DNS-PERSIST-01. Zamiast publikować przy każdym odnowieniu świeży token, składasz jednorazowo trwały rekord, który upoważnia określone konto ACME do wystawiania certyfikatów. Od tej pory serwer nie potrzebuje już do odnowienia żadnego prawa zapisu w DNS. Dla certyfikatów wildcard byłby to wyraźny zysk w bezpieczeństwie.

Zgodnie z harmonogramem Let's Encrypt środowisko testowe było przewidziane na koniec pierwszego kwartału 2026, a praca produkcyjna na drugi kwartał. Czy Certbot obsłuży tę metodę, na razie nie zostało zapowiedziane. Jeszcze więc na to nie licz, ale miej to na oku, jeśli akurat budujesz zarządzanie certyfikatami od podstaw.

Podsumowanie

Certyfikat wildcard da się uzyskać wyłącznie przez weryfikację DNS, bo gwiazdki nie sposób udowodnić za pomocą pojedynczego serwera WWW. Droga ręczna przez rekord TXT działa wszędzie, ale nigdy nie odnawia się sama. Droga przez wtyczkę dostawcy jest jedyną, którą możesz zostawić bez nadzoru, a w praktyce rozbija się najczęściej o zbyt krótki czas oczekiwania albo o dane dostępowe, które po cichu straciły ważność. Jeśli masz zapamiętać tylko jedno: sprawdź rekord TXT na autorytatywnym serwerze nazw, zanim pozwolisz Certbotowi iść dalej, a przy gwiazdce plus domenie głównej licz się na pewno z dwoma rekordami pod tą samą nazwą.