Certbot wildcard certificate DNS-01 TXT record paano

Bakit kailangan ng DNS-01 ang wildcard certificate

Sinasaklaw ng wildcard certificate ang bawat first-level subdomain ng isang domain: tumutugma ang *.example.com sa app.example.com, blog.example.com, at anumang pangalan na isang label ang lalim. Nag-iisyu ang Let's Encrypt ng wildcard certificate sa pamamagitan lamang ng DNS-01 challenge, kaya kailangang patunayan ng Certbot ang kontrol sa DNS ng domain sa pamamagitan ng pag-publish ng TXT record sa _acme-challenge.example.com. Hindi puwede ang HTTP-01 challenge, dahil ang pag-serve ng token file ay nagpapatunay lang ng kontrol sa iisang hostname — 'yung hostname kung saan kinuha ng validation server ang file. Ang wildcard ay claim tungkol sa bawat posibleng pangalan sa ilalim ng domain, at ang tanging public record na nagsasalita para sa buong namespace ay ang DNS mismo.

Ang requirement na 'yan ang nagdidikta ng lahat ng iba pa sa page na ito. Para makapasa sa DNS-01, kailangan mong makagawa ng TXT records sa zone ng domain, mano-mano man o sa pamamagitan ng API (application programming interface) ng iyong DNS provider. Ang mano-manong paraan ay gagana nang isang beses at pagkatapos ay babagsak sa renewal, dahil sa konkretong dahilan na ipapakita sa ibaba. Ang API route, sa pamamagitan ng Certbot DNS plugin, ay nagre-renew nang unattended, at ito ang setup na dapat mong kahantungan.

Ito ang wildcard chapter ng aming mga gabay sa Certbot. Ang ordinaryong single-hostname certificates, ang web server configuration, at ang port 80 rules ay tinalakay sa Certbot with nginx on Ubuntu 24.04 at Certbot with Apache on Ubuntu 24.04.

Paano gumagana ang _acme-challenge TXT record

Kapag humiling ang Certbot ng *.example.com, tumutugon ang Let's Encrypt gamit ang random token. Pinagsasama ng Certbot ang token na iyon sa iyong ACME (automatic certificate management environment) account key, ini-hash ang resulta gamit ang SHA-256, at gumagawa ng maikling text value. Dapat lumabas ang value na iyon bilang TXT record sa _acme-challenge.example.com. Kwe-query-in ng Let's Encrypt ang authoritative name servers ng iyong domain mula sa sarili nitong infrastructure. Kung tumugma ang record na nabasa nito sa value na inaasahan nito, napatunayan mong kontrolado mo ang zone, at ang kontrol sa zone ay tinatanggap bilang kontrol sa bawat pangalan sa ilalim nito.

Dalawang detalye ang sanhi ng karamihan ng pagkabigo:

• Ang pag-request ng example.com at *.example.com sa iisang certificate ay nangangahulugan ng dalawang magkahiwalay na challenge, at parehong TXT record ay nasa iisang pangalan, _acme-challenge.example.com. Dapat parehong umiral nang sabay. Tama ang pagdagdag ng pangalawang record; ang pagpalit sa una gamit ang pangalawa ay magpapabigo sa unang challenge.
• Binabasa ng validation ang iyong authoritative servers, pero maaaring abutin ng isang minuto o higit pa ang provider control panels bago maitulak palabas ang bagong record sa mga ito. Suriin mula sa labas bago mo hayaang tumakbo ang validation:

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

Kapag na-print niyan ang value na hiniling ng Certbot, maaaring magtagumpay ang validation. Kapag wala itong na-print, maghintay at patakbuhin itong muli.

Makita itong gumana nang isang beses: manual mode

Sa manual mode, ikaw mismo ang gagawa ng DNS edit, na siyang pinakamahusay na paraan para maintindihan ang mekanismo bago mo ito i-automate:

sudo certbot certonly --manual --preferred-challenges dns -d example.com -d '*.example.com'

Pinipigilan ng mga panipi sa paligid ng wildcard ang iyong shell na ituring ang * bilang filename pattern. Hihinto ang Certbot na may mga tagubilin:

Please deploy a DNS TXT record under the name:
_acme-challenge.example.com.
with the following value:
Jx9mQ2wLr8vTn5cKp0aYdG3hB7fZs4eN1oiRuXqMk6E

Gawin ang TXT record na iyon sa panel ng iyong DNS provider, kumpirmahing nakikita ito gamit ang dig command sa itaas, at saka lang pindutin ang Enter. Dahil humihingi ang run na ito ng bare domain at ng wildcard, dalawang beses magpo-prompt ang Certbot; panatilihing nakalagay ang parehong record hanggang matapos ang issuance. Nagtatapos ang tagumpay sa mga pamilyar na linya:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem

Bakit hindi kayang i-renew ng manual mode ang sarili nito

Bawat renewal ay bagong challenge na may bagong token, kaya nagbabago ang TXT value sa tuwing magre-renew. Walang silbi ang record na pinaste mo ngayon pagkalipas ng 60 araw. Ang renewal timer ay nagpapatakbo ng Certbot nang unattended dalawang beses kada araw, at walang tao sa keyboard para i-paste ang bagong value, kaya ang manually issued certificate ay bumabagsak sa renewal nito na may ganitong eksaktong error:

Failed to renew certificate example.com with error: The manual plugin is not
working; there may be problems with your existing configuration.
The error was: PluginError('An authentication script must be provided with
--manual-auth-hook when using the manual plugin non-interactively.')

Puwede mong matugunan ang requirement na iyon sa pamamagitan ng pagsulat ng --manual-auth-hook scripts na tumatawag sa API ng iyong DNS provider, pero sa puntong iyon, mano-mano mong nire-rebuild ang isang DNS plugin. Gamitin ang manual mode para matutunan ang daloy, o para sa tunay na one-off sa isang domain na ang DNS ay hindi mo pa kayang i-automate, at mag-set ng reminder bago mag-day 90, dahil hindi na nagpapadala ng expiry emails ang Let's Encrypt. Para sa lahat ng iba pa, gumamit ng plugin.

Ang plugin route: certbot-dns-cloudflare sa Ubuntu 24.04

Ang isang DNS plugin ay may hawak na API credential para sa iyong DNS provider at siya mismo ang gumagawa ng buong TXT record dance, sa issuance at muli sa bawat renewal. Cloudflare ang ginamit na halimbawa dito dahil ito ang provider plugin na kailangan ng karamihan, at ito ay naka-package sa Ubuntu.

Ang aming mga gabay sa Certbot ay nagrerekomenda ng apt packages sa Ubuntu 24.04, at ang paninindigang iyon ay nananatili para sa Cloudflare:

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

Isang tapat na tala tungkol sa mga bersyon. Ang 24.04 archive ay naghahatid ng plugin na ito sa bersyon 2.0.0 kasama ang Certbot 2.9.0; ipinapakita ng apt policy python3-certbot-dns-cloudflare ang sa iyo. Ang mismatch ay hindi nakakasama, at gumagana ang scoped API tokens, dahil ang pinagbabatayang python3-cloudflare library sa 24.04 ay 2.11.1, mas mataas sa 2.3.1 na kailangan ng plugin para sa token support. Sa mas lumang mga release ng Ubuntu, ang library na iyon ay masyadong luma para sa mga token, kung saan nagmumula ang mga babala na maaari mong makita online tungkol sa apt plugin na pumipilit sa Global API Key. Sa 24.04, hindi na ito applicable.

Sa Cloudflare dashboard, gumawa ng scoped API token, hindi ang Global API Key: My Profile, pagkatapos ay API Tokens, pagkatapos ay Create Token, na may iisang pahintulot na Zone / DNS / Edit, na limitado sa isang zone kung saan ka nag-i-issue. Ilagay ito sa isang file na tanging root lang ang makakabasa:

sudo mkdir -p /root/.secrets
sudo tee /root/.secrets/cloudflare.ini > /dev/null <<'EOF'
dns_cloudflare_api_token = paste_your_scoped_token_here
EOF
sudo chmod 600 /root/.secrets/cloudflare.ini

Sinusuri ng Certbot ang mode at nagbababala tungkol sa Unsafe permissions on credentials configuration file kung ang file ay nababasa ng iba. Ngayon, mag-issue:

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

Ang plugin ay gumagawa ng TXT records sa pamamagitan ng API, naghihintay ng maikling propagation delay, hinahayaang tumakbo ang validation, at pagkatapos ay binubura muli ang mga record. Kung ang mga name server ng iyong zone ay mabagal pumick-up ng mga pagbabago, taasan ang paghihintay gamit ang --dns-cloudflare-propagation-seconds 60. Ang certificate ay mapupunta sa /etc/letsencrypt/live/example.com/, at ituturo mo ang nginx o Apache sa fullchain.pem at privkey.pem eksakto tulad ng ipinapakita ng mga base guide, kasama ang deploy hook.

Kung wala sa apt ang plugin ng provider mo

Ang 24.04 archive ay nagpa-package lang ng plugins para sa ilang provider, kabilang ang Cloudflare, Route 53, DigitalOcean, at ang generic na RFC 2136 interface. I-run ang apt search certbot-dns para makita ang listahan. Kung wala ang provider mo, ito ang tanging pagkakataon na babaguhin natin ang payong unahin ang apt: i-install ang Certbot at ang plugin mula sa snap sa halip, at alisin muna ang apt na Certbot para hindi magsabayan ang dalawang renewal timer sa /etc/letsencrypt:

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

Ang isang snap plugin ay kumokonekta lang sa snap na Certbot; hindi nito kayang i-extend ang apt na bersyon, kaya hindi dapat magkasabay ang dalawang install. At kung walang API ang DNS host mo, ang praktikal na opsyon ay ilipat ang DNS ng domain sa provider na mayroon nito, o magpatakbo ng sariling name server at ituro dito ang rfc2136 plugin.

Renewal: patunayan ngayon, hindi sa loob ng 60 araw

Nire-record ng Certbot kung paano na-issue ang bawat certificate sa /etc/letsencrypt/renewal/example.com.conf, kasama ang authenticator = dns-cloudflare at ang credentials path, kaya nire-renew ito ng standard twice-daily timer nang walang tulong mula sa iyo. I-rehearse ang buong proseso laban sa staging environment:

sudo certbot renew --dry-run

Kapag pumasa, ibig sabihin gumagana ang credential at kumpleto ang validation end to end; susundan ng totoong renewal sa loob ng 60 araw ang parehong path. Dalawang follow-up ang dapat gawin ngayon. Una, walang nababago sa disk ang na-renew na certificate hangga't hindi ito nire-reload ng web server, kaya i-wire ang deploy hook na inilalarawan sa nginx at Apache guides. Pangalawa, ingatan ang credentials file: sinumang makakabasa nito ay puwedeng mag-edit ng iyong DNS zone, sapat na para i-redirect ang iyong mail o pumasa ng DNS-01 challenges nang mag-isa. Panatilihin ito sa mode 600 sa ilalim ng /root, i-scope ang token sa isang zone, at i-rotate ito kung sakaling may hinala kang leak.

Kapag hindi mo kailangan ng wildcard

Ang wildcard ay tamang tool para sa maraming subdomain, o para sa mga subdomain na hindi mo mahuhulaan. Ito ang maling default para sa lahat ng iba pa.

• Isang subdomain, o ilang alam na: mas simple ang normal na SAN (subject alternative name) certificate. Sinasaklaw ng certbot --nginx -d example.com -d www.example.com -d app.example.com ang hanggang 100 pangalan sa plain HTTP-01, at walang DNS API credential na naka-store sa server.
• Eksaktong isang label lang ang tinatapatan ng wildcard. Hindi sinasaklaw ng *.example.com ang bare na example.com, kaya hinihiling ng mga command sa itaas ang pareho, at hindi rin nito sinasaklaw ang a.b.example.com; kakailanganin nito ang *.b.example.com.
• Isang private key ang nasa likod ng bawat subdomain. Kapag na-compromise ang machine na may hawak nito, apektado agad ang bawat pangalan na sinasaklaw ng wildcard.
• Kung si Traefik ang nagte-terminate ng TLS (transport layer security) para sa iyong mga container, hindi mo na kailangan si Certbot sa eksena: si Traefik mismo ang humihiling ng wildcard certificates sa pamamagitan ng DNS-01, gamit ang parehong uri ng provider token.

Kung saan talaga sulit ang wildcard: mga per-customer o per-app na subdomain na mas mabilis malikha kaysa sa gusto mong pag-reissue ng certificates, at mga internal host na walang public port 80, tulad ng mga serbisyong maaabot lang sa pamamagitan ng isang WireGuard VPN. Hindi kailanman kumokonekta ang DNS-01 sa host na sine-certify, kaya kahit isang fully private na machine ay puwedeng magkaroon ng publicly trusted certificate.

FAQ

Pwede bang mag-issue ang Certbot ng wildcard certificate gamit ang HTTP-01?

Hindi. Pinapatunayan lang ng HTTP-01 ang kontrol sa isang hostname, dahil kumukuha ang validation server ng token file mula sa eksaktong pangalan na iyon. Sakop ng wildcard ang bawat pangalan sa ilalim ng domain, kaya hinihingi ng Let's Encrypt ang DNS-01 challenge para rito, at ang mga authenticator na --nginx, --apache, --webroot at --standalone ay pawang HTTP-based. Ang tanging paraan ay isang TXT record sa _acme-challenge.example.com, na inilalagay nang manual o sa pamamagitan ng DNS plugin.

Sakop ba ng wildcard certificate ang root domain?

Hindi. Eksaktong isang label ang tinutugma ng wildcard, kaya sinasaklaw ng *.example.com ang www.example.com pero hindi ang bare na example.com, at hindi rin ang a.b.example.com. Humiling ng parehong pangalan sa iisang certificate gamit ang -d example.com -d '*.example.com'. Lumilikha iyon ng dalawang challenge, at parehong nasa iisang _acme-challenge.example.com na pangalan ang mga TXT record, kaya idagdag ang pangalawang record nang hindi binubura ang una.

Bakit hindi awtomatikong nagre-renew ang wildcard certificate ko?

Dahil na-issue ito gamit ang --manual. Kailangan ng bawat renewal ng bagong TXT value, at walang paraan ang unattended timer para i-paste ito, kaya humihinto ang renewal na may error na An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. I-reissue ang certificate gamit ang DNS plugin tulad ng certbot-dns-cloudflare, o magbigay ng --manual-auth-hook at --manual-cleanup-hook na mga script na nag-e-edit ng record sa pamamagitan ng API ng provider mo.

Gaano katagal bago lumabas ang _acme-challenge TXT record?

Depende ito sa DNS provider mo: maaaring ilang segundo hanggang ilang minuto. Binabasa ng validation ang mga authoritative server ng zone mo, kaya suriin gamit ang dig +short TXT _acme-challenge.example.com @1.1.1.1 at hintaying lumabas ang inaasahang value bago ipagpatuloy ang manual run. Kapag may plugin, taasan ang built-in na paghihintay sa pamamagitan ng propagation option ng plugin, halimbawa --dns-cloudflare-propagation-seconds 60, kung nag-ulat ang validation na hindi nakita ang record.

Hindi ba gaanong secure ang wildcard certificate kumpara sa normal na certificate?

Magkapareho ang cryptography. Ang mga pagkakaiba ay operational: isang private key ang sumasaklaw sa bawat subdomain, kaya mas malawak ang aabutin ng kompromiso, at ang DNS API credential na kailangan ng automation ay isa mismong sensitibong sikretong nakaimbak sa server. Kung kaunting kilalang subdomain lang ang pinapatakbo mo, iniiwasan ng SAN certificate ang parehong alalahanin, na siyang eksaktong pagkakataon kung kailan inirerekomenda ng gabay na ito na laktawan ang wildcard.