Paano gumawa ng wildcard certificate sa Certbot DNS-01

Bakit kailangan ng wildcard certificate ang DNS-01

Sinasaklaw ng wildcard certificate ang bawat first-level subdomain ng isang domain: tumutugma ang *.example.com sa app.example.com, blog.example.com, at sa anumang ibang pangalan na may isang label ang lalim. Nagbibigay ang Let's Encrypt ng wildcard certificates lamang sa pamamagitan ng DNS-01 challenge, kaya kailangang patunayan ng Certbot ang kontrol nito sa DNS ng domain sa pamamagitan ng paglalathala ng TXT record sa _acme-challenge.example.com. Hindi kwalipikado ang HTTP-01 challenge dahil ang pagsilbi ng token file ay nagpapatunay lamang ng kontrol sa isang hostname — iyong hostname na kinuhanan ng validation server ng file. Ang wildcard ay isang claim tungkol sa bawat posibleng pangalan sa ilalim ng domain, at ang tanging pampublikong record na sumasagot para sa buong namespace ay ang DNS mismo.

Ang iisang requirement na ito ang nagtatakda sa lahat ng iba pa sa pahinang ito. Para makapasa sa DNS-01, kailangan mong makagawa ng TXT records sa zone ng domain, maging sa pamamagitan ng manual na paraan o sa API (application programming interface) ng iyong DNS provider. Gumagana ang manual na paraan nang isang beses pero nabibigo sa susunod na renewal, dahil sa isang tiyak na dahilan na ipinapakita sa ibaba. Ang paraang gamit ang API, sa pamamagitan ng Certbot DNS plugin, ay awtomatikong nagre-renew nang walang interbensyon ng tao, at ito ang setup na dapat mong puntahan sa huli.

Ito ang kabanata tungkol sa wildcard sa aming mga gabay sa Certbot. Sakop sa Certbot gamit ang nginx sa Ubuntu 24.04 at Certbot gamit ang Apache sa Ubuntu 24.04 ang mga ordinaryong single-hostname certificate, ang configuration ng web server, at ang mga tuntunin para sa port 80.

Paano Gumagana ang TXT Record ng _acme-challenge

Kapag humiling ang Certbot ng *.example.com, sumasagot ang Let's Encrypt gamit ang random token. Pinagsasama ng Certbot ang token na iyon sa iyong ACME (automatic certificate management environment) account key, hina-hash ang resulta gamit ang SHA-256, at gumagawa ng maikling text value. Kailangang lumitaw ang value na iyon bilang TXT record sa _acme-challenge.example.com. Pagkatapos, nag-q-query ang Let's Encrypt sa authoritative name servers ng iyong domain mula mismo sa sarili nitong infrastructure. Kung tumutugma 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.

May dalawang detalye na sanhi ng karamihan sa mga kabiguan:

• Kapag humiling ka ng example.com at *.example.com sa iisang certificate, nangangahulugan ito ng dalawang magkahiwalay na challenge, at parehong nasa iisang pangalan matatagpuan ang dalawang TXT record, ang _acme-challenge.example.com. Kailangang magkasabay silang umiral. Tama ang pagdaragdag ng ikalawang record; ang pagpapalit sa una gamit ang ikalawa ay magpapabigo sa unang challenge.
• Binabasa ng validation ang iyong authoritative servers, ngunit maaaring umabot ng isang minuto o higit pa bago maipadala ng control panel ng provider ang bagong record papunta 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 nito ang value na hiningi ng Certbot, puwede nang magtagumpay ang validation. Kapag walang na-print, maghintay at patakbuhin itong muli.

Tingnan muna kung paano ito gumagana: manual mode

Sa manual mode, ikaw mismo ang mag-e-edit ng DNS, at ito ang pinakamagandang paraan para maunawaan ang mekanismo bago ito i-automate:

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

Pinipigilan ng quotes sa paligid ng wildcard na ituring ng shell mo ang * bilang filename pattern. Humihinto si Certbot at nagbibigay ng mga instruction:

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

Gumawa ng TXT record na iyon sa panel ng DNS provider mo, kumpirmahin na visible ito gamit ang dig command sa itaas, at saka ka lang pumindot ng Enter. Dahil hinihingi ng run na ito ang bare domain at ang wildcard, doble ang prompt ni Certbot; panatilihin ang dalawang record hanggang matapos ang pag-isyu ng certificate. Nagtatapos ang matagumpay na proseso 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 isang bagong challenge na may bagong token, kaya nagbabago ang TXT value sa tuwing magre-renew. Sa loob ng 60 araw, mawawalan na ng silbi ang record na na-paste mo ngayon. Pinapatakbo ng renewal timer ang Certbot nang walang nag-aasikaso, dalawang beses kada araw, at walang taong nasa keyboard para i-paste ang bagong value, kaya nabibigo ang renewal ng certificate na na-isyu nang manual sa eksaktong error na ito:

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 mga --manual-auth-hook script na tumatawag sa API ng DNS provider mo, pero sa puntong iyon, ginagawa mo na nang manual ang sarili mong bersyon ng DNS plugin. Gamitin ang manual mode para matutunan ang flow, o para sa totoong one-off na kaso sa isang domain na hindi mo pa ma-automate ang DNS nito, at mag-set ng paalala bago pa dumating ang ika-90 araw, dahil hindi na nagpapadala ang Let's Encrypt ng mga expiry email. Para sa lahat ng iba pang kaso, gumamit ng plugin.

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

Ang isang DNS plugin ang naghahawak ng API credential para sa DNS provider mo at ang buong TXT record na proseso mismo ang gumagawa nito, kapag nag-isyu at muli sa bawat pag-renew. Cloudflare ang worked example dito dahil ito ang provider plugin na pinaka-kailangan ng karamihan, at naka-package na ito sa Ubuntu.

Inirerekomenda ng aming mga Certbot guide ang mga apt package sa Ubuntu 24.04, at nananatiling totoo ang tindig na iyon para sa Cloudflare:

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

Isang tapat na paalala tungkol sa mga bersyon. Ang 24.04 archive ay nagshi-ship ng plugin na ito sa bersyong 2.0.0 kasabay ng Certbot 2.9.0; ipinapakita ng apt policy python3-certbot-dns-cloudflare ang sa iyo. Hindi mapanganib ang hindi pagtutugma, at gumagana ang mga scoped API token, dahil ang python3-cloudflare library sa ilalim nito sa 24.04 ay 2.11.1, mas mataas kaysa sa 2.3.1 na kailangan ng plugin para sa suporta sa token. Sa mga mas lumang Ubuntu release, masyadong luma ang library na iyon para sa mga token, at doon nanggagaling ang mga babala na makikita mo online tungkol sa apt plugin na pumipilit gumamit ng Global API Key. Sa 24.04, hindi na ito aplikable.

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

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 nababasa ang file ng iba. Ngayon, mag-isyu:

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

Ginagawa ng plugin ang mga TXT record sa pamamagitan ng API, naghihintay ng maikling propagation delay, hinahayaang tumakbo ang validation, pagkatapos ay binubura ulit ang mga record. Kung mabagal kumuha ng mga pagbabago ang name server ng zone mo, taasan ang paghihintay gamit ang --dns-cloudflare-propagation-seconds 60. Napupunta ang certificate sa /etc/letsencrypt/live/example.com/, at itinuturo mo ang nginx o Apache sa fullchain.pem at privkey.pem eksaktong gaya ng ipinapakita ng mga base guide, kasama na ang deploy hook.

Kung Wala sa apt ang Plugin ng Provider Mo

Kaunti lang na provider ang may naka-package na plugin sa 24.04 archive, kabilang na rito ang Cloudflare, Route 53, DigitalOcean, at ang generic RFC 2136 interface. I-run ang apt search certbot-dns para makita ang listahan. Kung wala rito ang provider mo, dito lang bumabaluktot ang apt-first na payo namin: sa halip, i-install ang Certbot at ang plugin mula sa snap, at alisin muna ang apt Certbot para hindi mag-agawan ang dalawang renewal timer para 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

Kumokonekta lang ang snap plugin sa snap Certbot; hindi nito ma-e-extend ang apt na installation, kaya hindi dapat magkasabay ang dalawang install na ito. At kung wala talagang API ang DNS host mo, ang praktikal mong mga opsyon ay ilipat ang DNS ng domain sa isang provider na may API, o magpatakbo ng sarili mong name server at ituro dito ang rfc2136 plugin.

Pag-renew: patunayan ngayon, hindi sa loob ng 60 araw

Itinatala 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 ni-renew ito ng standard na timer na tumatakbo dalawang beses kada araw, nang walang kailangang gawin mula sa iyo. Subukan muna ang buong proseso gamit ang staging environment:

sudo certbot renew --dry-run

Kapag pumasa ito, nangangahulugan na gumagana ang credential at kumpleto ang validation mula umpisa hanggang dulo; susunod ang parehong path ang gagamitin ng aktwal na renewal pagkalipas ng 60 araw. May dalawang dapat gawin ngayon din. Una, walang mababago sa renewed certificate na naka-disk hangga't hindi ito nire-reload ng web server, kaya i-wire ang deploy hook na inilarawan sa mga gabay para sa nginx at Apache. Pangalawa, pahalagahan ang credentials file: sinumang makakabasa nito ay makakapag-edit ng iyong DNS zone, at sapat na iyon para i-redirect ang iyong mail o para pumasa sa sarili nilang DNS-01 challenges. Panatilihin ito sa mode 600 sa ilalim ng /root, i-scope ang token sa isang zone lamang, at i-rotate ito kung sakaling maghinala kang na-leak ito.

Kailan Hindi Mo Kailangan ang Wildcard

Ang wildcard ang tamang tool kapag maraming subdomain, o kapag hindi mo mahuhulaan ang mga subdomain. Mali itong gawing default para sa lahat ng iba pa.

• Isang subdomain lang, o kaunti at kilala 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 wala pang DNS API credential na naka-store sa server.
• Isang label lang ang tinutugma ng wildcard. Hindi saklaw ng *.example.com ang bare example.com, kaya hiniling ng mga command sa itaas ang pareho, at hindi rin nito saklaw ang a.b.example.com; kakailanganin niyan ang *.b.example.com.
• Iisang private key ang nasa likod ng bawat subdomain. Kapag na-breach ang machine na may hawak nito, apektado agad ang lahat ng pangalang saklaw ng wildcard.
• Kung si Traefik ang nagta-terminate ng TLS (transport layer security) para sa mga container mo, hindi mo na kailangan ang Certbot: humihiling mismo si Traefik ng wildcard certificate sa pamamagitan ng DNS-01, gamit ang parehong uri ng provider token.

Dito talaga kapaki-pakinabang ang wildcard: mga subdomain na per-customer o per-app na ginagawa nang mas mabilis kaysa gusto mong mag-reissue ng certificate, at mga internal host na walang public port 80, tulad ng mga serbisyong maa-access lang sa loob ng isang WireGuard VPN. Hindi kailanman kumokonekta ang DNS-01 sa host na sini-certify, kaya kahit ang isang ganap na private na machine ay maaaring magkaroon ng publicly trusted na certificate.

FAQ

Kaya bang mag-isyu ng wildcard certificate ang Certbot gamit ang HTTP-01?

Hindi. Pinapatunayan ng HTTP-01 ang kontrol sa isang hostname lang, dahil kinukuha ng validation server ang isang token file mula sa eksaktong pangalang iyon. Sinasaklaw ng wildcard ang bawat pangalan sa ilalim ng domain, kaya kinakailangan ng Let's Encrypt ang DNS-01 challenge para dito, at HTTP-based lahat ang mga authenticator na --nginx, --apache, --webroot at --standalone. Ang tanging paraan ay isang TXT record sa _acme-challenge.example.com, na ilalagay nang manu-mano o sa pamamagitan ng isang DNS plugin.

Sinasaklaw ba ng wildcard certificate ang root domain?

Hindi. Isang label lang ang tinutugma ng wildcard, kaya sinasaklaw ng *.example.com ang www.example.com pero hindi ang plain na example.com, at hindi rin ang a.b.example.com. Hilingin ang parehong pangalan sa isang certificate gamit ang -d example.com -d '*.example.com'. Lumilikha ito ng dalawang challenge, at parehong nasa iisang _acme-challenge.example.com name ang dalawang TXT record, kaya idagdag ang pangalawang record nang hindi binubura ang una.

Bakit hindi awtomatikong nire-renew ang wildcard certificate ko?

Dahil in-isyu ito gamit ang --manual. Kailangan ng bawat renewal ng bagong-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-isyu muli ang certificate gamit ang isang DNS plugin tulad ng certbot-dns-cloudflare, o magbigay ng mga script na --manual-auth-hook at --manual-cleanup-hook na nag-eedit ng record sa pamamagitan ng API ng provider mo.

Gaano katagal bago lumitaw ang _acme-challenge TXT record?

Depende ito sa DNS provider mo: maaaring segundo lang o ilang minuto. Binabasa ng validation ang authoritative servers ng zone mo, kaya i-check gamit ang dig +short TXT _acme-challenge.example.com @1.1.1.1 at hintayin na lumitaw ang inaasahang value bago ituloy ang isang manual run. Kapag gumagamit ng plugin, taasan ang built-in na waiting time sa pamamagitan ng propagation option ng plugin, halimbawa --dns-cloudflare-propagation-seconds 60, kung sinasabi ng validation na hindi mahanap ang record.

Hindi ba ligtas ang wildcard certificate kumpara sa normal na certificate?

Magkapareho ang cryptography. Nasa operational aspect ang mga pagkakaiba: iisang private key ang sumasaklaw sa lahat ng subdomain, kaya mas malawak ang maaabot ng isang breach, at ang DNS API credential na kailangan ng automation ay isa ring sensitibong sikreto na naka-imbak sa server. Kung ilang known subdomain lang ang pinapatakbo mo, iiwasan ng SAN certificate ang dalawang alalahanin na ito, at dito mismo inirerekomenda ng gabay na ito na laktawan na lang ang wildcard.