Certbot i Let's Encrypt: wildcard, odnowienia i typowe błędy

Zwykły certyfikat dla example.pl i www.example.pl certbot zdobędzie przez wyzwanie HTTP-01 – wystarczy otwarty port 80 i jedna komenda. Certyfikat wildcard (*.example.pl) wymaga wyzwania DNS-01, czyli automatycznego dodawania rekordu TXT w DNS, najlepiej przez API dostawcy DNS. W obu przypadkach odnowienia robi za Ciebie timer systemowy; Ty sprawdzasz je raz komendą certbot renew --dry-run i dodajesz hook, który przeładuje serwer WWW.

Opis opiera się na dokumentacji Let’s Encrypt i certbota sprawdzonej 11.11.2026. Przykłady używają domeny example.pl i nginx.

Zwykły certyfikat: HTTP-01

Let’s Encrypt sprawdza, czy kontrolujesz domenę, pobierając plik z adresu http://example.pl/.well-known/acme-challenge/…. Według dokumentacji wyzwań to wyzwanie działa wyłącznie na porcie 80 – nie da się wskazać innego portu. Nie obsługuje też certyfikatów wildcard.

Najprostsza droga przy nginx:

sudo certbot --nginx -d example.pl -d www.example.pl

Certbot sam doda konfigurację SSL do bloku server. Jeśli wolisz zarządzać konfiguracją ręcznie, użyj trybu webroot:

sudo certbot certonly --webroot -w /var/www/example.pl -d example.pl -d www.example.pl

Wtedy w nginx wskazujesz pliki z katalogu /etc/letsencrypt/live/example.pl/ (fullchain.pem i privkey.pem).

Wildcard: DNS-01

Certyfikat *.example.pl obejmuje wszystkie subdomeny pierwszego poziomu, ale nie samą domenę example.pl – tę dodajesz osobno. Jedyną metodą weryfikacji dla wildcarda jest DNS-01: certbot tworzy rekord TXT _acme-challenge.example.pl z jednorazową wartością, a Let’s Encrypt go odczytuje.

Dokumentacja Let’s Encrypt wymienia zalety i wady DNS-01. Zalety: wildcardy, wiele serwerów WWW, serwery niewidoczne z internetu. Wady: dane dostępowe do API DNS leżą na serwerze, a nie każdy dostawca DNS ma API lub informuje, kiedy zmiana się rozeszła.

Z wtyczką dostawcy DNS

Certbot ma wtyczki dla wielu dostawców DNS, m.in. Cloudflare, Route 53, Google Cloud DNS i DigitalOcean. Nie są instalowane domyślnie – doinstalowujesz je z menedżera pakietów, jako snap albo w obrazie Docker (dokumentacja certbota). Wtyczkę instalujesz tak samo jak certbota – nie mieszaj pakietu z repozytorium z instalacją przez snap. Przykład dla Cloudflare.

Certbot z pakietu Ubuntu albo Debiana (jak w poradniku od zera):

sudo apt -y install python3-certbot-dns-cloudflare

Certbot ze snapa:

sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-dns-cloudflare

Plik z tokenem API – według dokumentacji wtyczki token potrzebuje uprawnienia Zone:DNS:Edit tylko dla stref, dla których wystawiasz certyfikaty:

sudo install -d -m 700 /root/.secrets
sudo install -m 600 /dev/null /root/.secrets/cloudflare.ini
echo 'dns_cloudflare_api_token = WKLEJ-TOKEN' | sudo tee /root/.secrets/cloudflare.ini >/dev/null
sudo ls -l /root/.secrets/cloudflare.ini

Potem wystaw certyfikat:

sudo certbot certonly --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
  -d example.pl -d "*.example.pl"

Plik z tokenem ma prawa 600 od chwili utworzenia, więc token ani przez moment nie jest czytelny dla innych użytkowników (certbot ostrzega, gdy plik jest dostępny szerzej). tee nadpisuje zawartość, ale zachowuje te prawa.

Z własnymi skryptami (manual + hooki)

Jeśli dla Twojego DNS-u nie ma wtyczki, użyj trybu --manual ze skryptami --manual-auth-hook (ustawia TXT) i --manual-cleanup-hook (usuwa go). Bez skryptu auth certyfikat z trybu manual nie odnowi się automatycznie – dokumentacja certbota mówi wprost, że takiej komendy nie da się wtedy zautomatyzować.

sudo certbot certonly --manual --preferred-challenges dns \
  --manual-auth-hook /usr/local/bin/dns-auth.sh \
  --manual-cleanup-hook /usr/local/bin/dns-cleanup.sh \
  -d "*.example.pl" --cert-name example-wildcard

Pułapki przy DNS-01

Niektórzy darmowi dostawcy DNS przechowują w API tylko jedną wartość TXT dla nazwy. Certyfikat obejmujący jednocześnie example.pl i *.example.pl wymaga dwóch wartości TXT naraz pod tym samym _acme-challenge, więc tam się nie da. Rozwiązanie: dwa osobne certyfikaty, każdy z jedną nazwą (--cert-name odróżnia je w konfiguracji).

Druga pułapka to propagacja. Skrypt auth czeka, aż serwery autorytatywne zwrócą nową wartość, a potem jeszcze dodatkowo ok. półtorej minuty. Bez tej przerwy test odnowienia wildcarda kończył się błędem „Incorrect TXT record”, gdy oba certyfikaty odnawiały się jeden po drugim – walidatory Let’s Encrypt sprawdzają DNS z kilku miejsc i część z nich miała jeszcze poprzednią wartość. Let’s Encrypt w dokumentacji radzi, by przy dostawcy bez informacji o propagacji ustawić oczekiwanie nawet do godziny.

Jeśli Twój DNS nie ma API, możesz delegować samo _acme-challenge rekordem CNAME do strefy u dostawcy, który API ma – Let’s Encrypt podąża za CNAME.

Automatyczne odnowienia

Pakiety certbota instalują zadanie, które uruchamia certbot renew zwykle dwa razy dziennie – jako timer systemd albo wpis cron. Sprawdzisz to komendą:

systemctl list-timers | grep certbot

Od wersji 4.0 certbot odnawia certyfikat, gdy zostaje mniej niż 1/3 jego ważności, a przy certyfikatach ważnych 10 dni lub krócej – połowa (wcześniej: sztywno 30 dni przed wygaśnięciem). Tak opisuje to dokumentacja certbota, sprawdzona 11.11.2026. Zawsze przetestuj cały proces:

sudo certbot renew --dry-run

Odnowiony certyfikat trzeba jeszcze załadować do serwera WWW. Przy certbot --nginx robi to sam certbot, ale przy certonly (webroot, DNS-01) już nie. Najprościej dodać skrypt do katalogu /etc/letsencrypt/renewal-hooks/deploy/ – certbot uruchamia z niego tylko pliki wykonywalne i tylko po udanym odnowieniu:

sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh >/dev/null <<'EOF'
#!/bin/sh
systemctl reload nginx
EOF
sudo chmod 755 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
sudo ls -l /etc/letsencrypt/renewal-hooks/deploy/

Bez chmod certbot pominie plik bez żadnego błędu. Hooki z tego katalogu uruchamiają się w kolejności alfabetycznej nazw plików.

Listę certyfikatów z datami wygaśnięcia pokaże sudo certbot certificates.

Krótsze certyfikaty od 2027 roku

Let’s Encrypt zapowiedział skracanie ważności certyfikatów: od 13 maja 2026 opcjonalny profil tlsserver wydaje certyfikaty 45-dniowe, od 10 lutego 2027 domyślny profil przejdzie na 64 dni, a od 16 lutego 2028 na 45 dni. Odnawianie co sztywne 60 dni przestanie wystarczać. Jeśli masz własne skrypty lub crony z twardym terminem, przejdź na certbot renew z domyślną logiką albo na klienta obsługującego ARI (informacje o odnowieniu od samego Let’s Encrypt).

Typowe błędy i naprawa

„Incorrect TXT record” przy DNS-01. Rekord nie zdążył się rozejść albo walidator widzi starą wartość. Wydłuż oczekiwanie w skrypcie auth lub parametr propagacji wtyczki, obniż TTL rekordu.

Timeout lub „Connection refused” przy HTTP-01. Port 80 jest zablokowany na zaporze (ufw, firewall dostawcy) albo domena wskazuje na inny adres IP. Sprawdź rekordy A i AAAA – jeśli masz AAAA, serwer musi odpowiadać także po IPv6.

404 na ścieżce /.well-known/acme-challenge/. Zły katalog -w w trybie webroot albo reguła nginx przekierowuje lub blokuje tę ścieżkę.

„too many certificates” (limit). Według limitów Let’s Encrypt możesz wystawić 5 certyfikatów na dokładnie ten sam zestaw nazw w ciągu 7 dni i 50 nowych certyfikatów na zarejestrowaną domenę w 7 dni. Do tego 5 nieudanych autoryzacji na nazwę na godzinę. Testuj z --dry-run albo --staging, które korzystają ze środowiska testowego z wyższymi limitami.

Certyfikat odnowiony, a przeglądarka pokazuje stary. Serwer WWW nie został przeładowany. Dodaj hook deploy opisany wyżej.

Certyfikat z trybu manual nie odnawia się. Został wystawiony bez --manual-auth-hook. Wystaw go ponownie z hookami – parametry zapiszą się w pliku odnowienia.

Rekord CAA blokuje wydanie. Jeśli w DNS masz rekord CAA, musi on zezwalać na Let’s Encrypt.

Monitoring wygaśnięcia

Automat zawodzi po cichu: zmiana DNS, wygasły token API, zapora. Dlatego niezależnie od certbota sprawdzaj datę wygaśnięcia z zewnątrz:

echo | openssl s_client -connect example.pl:443 -servername example.pl 2>/dev/null \
  | openssl x509 -noout -enddate

Ustaw alert, gdy któryś certyfikat wygasa w ciągu 14 dni – skrypt jest w poradniku o monitoringu, a możesz też użyć narzędzia do monitoringu stron, jak w poradniku Uptime Kuma na VPS. Cały serwer z nginx, Dockerem i certbotem krok po kroku znajdziesz w poradniku Tani VPS od zera, a porównanie małych serwerów w rankingu VPS.

Lista kontrolna

• Zwykły certyfikat: port 80 otwarty, rekordy A/AAAA poprawne.
• Wildcard: wtyczka DNS albo skrypty auth i cleanup; token z minimalnymi uprawnieniami, plik 600.
• Domena główna jest w certyfikacie obok *.example.pl albo ma osobny certyfikat.
• sudo certbot renew --dry-run kończy się sukcesem.
• Hook deploy w renewal-hooks/deploy/ jest wykonywalny i przeładowuje serwer WWW.
• Brak sztywnego odnawiania co 60 dni w Twoich skryptach.
• Zewnętrzny alert na 14 dni przed wygaśnięciem.