Jinsi ya kupata wildcard certificate kwa Certbot

Kwa nini cheti cha wildcard kinahitaji DNS-01

Cheti cha wildcard kinahusu kila subdomain ya kiwango cha kwanza ya domain: *.example.com inafanana na app.example.com, blog.example.com, na majina mengine yoyote yenye lebo moja. Let's Encrypt hutoa vyeti vya wildcard kupitia njia ya DNS-01 pekee, hivyo Certbot lazima ithibitishe udhibiti wa DNS ya domain kwa kuweka rekodi ya TXT kwenye _acme-challenge.example.com. Njia ya HTTP-01 haiwezi kutumika, kwa sababu kutoa faili ya token inathibitisha udhibiti wa hostname moja tu, ile ambayo seva ya uhakiki ilichukua faili hiyo. Wildcard ni dai kuhusu kila jina linalowezekana chini ya domain, na rekodi pekee ya umma inayozungumzia nafasi yote ya majina (namespace) ni DNS yenyewe.

Hitaji hilo moja linaamua mambo mengine yote kwenye ukurasa huu. Ili upate DNS-01, lazima uweze kutengeneza rekodi za TXT kwenye zone ya domain, kwa mkono au kupitia API ya mtoa huduma wako wa DNS. Njia ya mkono hufanya kazi mara moja lakini itashindwa wakati wa kuhuisha (renewal), kwa sababu maalum iliyoonyeshwa hapa chini. Njia ya API, kupitia plugin ya DNS ya Certbot, inajihuisha bila usimamizi, na hiyo ndiyo mipangilio unayopaswa kuimaliza.

Hii ni sehemu ya wildcard katika mwongozo wetu wa Certbot. Vyeti vya kawaida vya hostname moja, usanidi wa seva ya web, na sheria za port 80 vimeelezwa kwenye Certbot na nginx kwenye Ubuntu 24.04 na Certbot na Apache kwenye Ubuntu 24.04.

Jinsi rekodi ya _acme-challenge TXT inavyofanya kazi

Certbot inapotaka *.example.com, Let's Encrypt hujibu kwa tokeni ya nasibu. Certbot inachanganya tokeni hiyo na funguo ya akaunti yako ya ACME (automatic certificate management environment), inafanya hash ya matokeo hayo kwa kutumia SHA-256, na kutoa thamani fupi ya maandishi. Thamani hiyo lazima ionekane kama rekodi ya TXT kwenye _acme-challenge.example.com. Kisha Let's Encrypt huuliza seva za majina (authoritative name servers) za domini yako kutoka kwenye miundombinu yake. Ikiwa rekodi inayosomwa inafanana na thamani inayotarajiwa, umethibitisha kuwa unadhibiti zone, na udhibiti wa zone unakubalika kama udhibiti wa kila jina chini yake.

Mambo mawili husababisha kushindwa kwa nyingi:

• Kuomba example.com na *.example.com kwenye cheti kimoja inamaanisha changamoto mbili tofauti, na rekodi zote za TXT zipo kwenye jina moja, _acme-challenge.example.com. Zote lazima ziwepo kwa wakati mmoja. Kuongeza rekodi ya pili ni sahihi; kubadilisha rekodi ya kwanza kwa ya pili husababisha changamoto ya kwanza kushindwa.
• Uhakiki husoma seva zako za mamlaka, lakini paneli za udhibiti za mtoa huduma zinaweza kuchukua dakika moja au zaidi kusambaza rekodi mpya kwazo. Hakiki kutoka nje kabla ya kuruhusu uhakiki uanze:

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

Thamani inayotokea wakati hiyo inachapisha kile Certbot kilichoomba, uhakiki unaweza kufanikiwa. Ikiwa haichapishi kitu, subiri na uendeshe tena.

Ione jinsi inavyofanya kazi mara moja: manual mode

Manual mode inakulazimisha ufanye uhariri wa DNS mwenyewe. Hii ndiyo njia bora ya kuelewa mfumo kabla ya kuuweka kwenye automation:

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

Alama za nukuu kwenye wildcard huzuia shell isichukulie * kama mfumo wa faili. Certbot itasimama na kutoa maelekezo:

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

Tengeneza rekodi hiyo ya TXT kwenye panel ya mtoa huduma wako wa DNS. Hakikisha inaonekana kwa kutumia amri ya dig iliyo juu, kisha bonyeza Enter. Kwa sababu hatua hii inaomba bare domain na wildcard, Certbot itauliza mara mbili; weka rekodi zote mbili mahali pake hadi utoaji unapoisha. Mafanikio huisha na mistari inayofahamika:

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

Kwa nini hali ya manual haiwezi kujifanya upya (renew)

Kila uthibitisho mpya ni changamoto mpya yenye token mpya, hivyo thamani ya TXT hubadilika kila wakati. Rekodi uliyoweka leo haitafanya kazi baada ya siku 60. Certbot hukimbiza muda wa uthibitisho bila usimamizi mara mbili kwa siku, na hakuna mtu kwenye kibodi kuweka thamani mpya, hivyo cheti kilichotolewa kwa njia ya manual hushindwa kujifanya upya kwa kosa hili:

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.')

Unaweza kutimiza hitaji hilo kwa kuandika skripti za --manual-auth-hook zinazotumia API ya mtoa huduma wako wa DNS, lakini hapo utakuwa unajenga plugin ya DNS kwa mkono. Tumia hali ya manual kujifunza mtiririko, au kwa matumizi ya mara moja kwenye domain ambayo DNS yake haiwezi kutumika kwa njia ya kiotomatiki bado, na weka ukumbusho kabla ya siku 90, kwa sababu Let's Encrypt haitumi tena barua pepe za mwisho wa muda. Kwa mambo mengine yote, tumia plugin.

Njia ya plugin: certbot-dns-cloudflare kwenye Ubuntu 24.04

Plugin ya DNS inahifadhi sifa za API (API credentials) za mtoa huduma wako wa DNS na inafanya mchakato mzima wa rekodi za TXT yenyewe, wakati wa utoaji na wakati wa kila utengenezaji upya. Cloudflare imetumika kama mfano hapa kwa sababu ndiyo plugin ya mtoa huduma inayohitajika zaidi, na imepakiwa kwenye Ubuntu.

Mwongozo wetu wa Certbot unapendekeza kutumia vifurushi vya apt kwenye Ubuntu 24.04, na msimamo huo unabaki kwa Cloudflare:

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

Zingatia kuhusu matoleo (versions). Kumbukumbu ya 24.04 inatoa plugin hii katika toleo la 2.0.0 pamoja na Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare inaonyesha toleo lako. Kutofautiana huku hakuna madhara, na API tokens zenye ukomwengu (scoped tokens) zinafanya kazi, kwa sababu maktaba ya python3-cloudflare kwenye 24.04 ni 2.11.1, ambayo ni juu ya 2.3.1 inayohitajika na plugin kwa ajili ya kuunga mkono tokens. Kwenye matoleo ya zamani ya Ubuntu, maktaba hiyo ilikuwa ya zamani mno kwa tokens, na hapo ndipo maonyo unayoweza kuyapata mtandaoni kuhusu plugin ya apt kulazimisha Global API Key yanapotokea. Kwenye 24.04, maonyo hayo hayafanyi kazi tena.

Kwenye dashboard ya Cloudflare, tengeneza scoped API token, siyo Global API Key: My Profile, kisha API Tokens, kisha Create Token, ukiwa na ruhusa moja ya Zone / DNS / Edit, iliyowekwa kwa zone moja unayotaka kutoa cheti. Iweke kwenye faili ambalo ni root pekee anayeweza kusoma:

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

Certbot hukagua hali ya faili na kutoa onyo kuhusu Unsafe permissions on credentials configuration file ikiwa faili inaweza kusomwa na wengine. Sasa toa cheti:

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

Plugin hutengeneza rekodi za TXT kupitia API, husubiri muda mfupi wa kusambazwa (propagation), huruhusu uhakiki (validation) ufanyike, kisha hufuta rekodi hizo tena. Ikiwa seva za majina (name servers) za zone yako zina ucheleweshaji wa kuchukua mabadiliko, ongeza muda wa kusubiri kwa kutumia --dns-cloudflare-propagation-seconds 60. Cheti hutunza kwenye /etc/letsencrypt/live/example.com/, na unaelekeza nginx au Apache kwenye fullchain.pem na privkey.pem kama mwongozo wa msingi unavyoonyesha, ikiwa ni pamoja na deploy hook.

Ikiwa plugin ya mtoa huduma wako haipo kwenye apt

Paketi za nyaraka za 24.04 zinatoa plugin kwa mtoa huduma wachache tu, ikiwemo Cloudflare, Route 53, DigitalOcean na interface ya RFC 2136. Tumia apt search certbot-dns kuona orodha hiyo. Ikiwa mtoa huduma wako hayupo, hapa ndipo ushauri wetu wa kutumia apt unabadilika: badala yake, pakua Certbot na plugin kutoka snap, na uondoe Certbot wa apt kwanza ili timer mbili za kurenew wakati zisigombane juu ya /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

Plugin ya snap inaunganishwa na snap Certbot pekee; haiwezi kuongeza uwezo wa ile ya apt, ndiyo maana usakinishaji huo miwili haupaswi kuwepo kwa pamoja. Na ikiwa mwenyeji wako wa DNS hana API kabisa, chaguo zako ni kuhamisha DNS ya domain kwenda kwa mtoa huduma mwenye API, au kuendesha name server yako mwenyewe na kuelekeza plugin ya rfc2136 kwake.

Uingizaji upya: thibitisha sasa, si baada ya siku 60

Certbot huhifadhi rekodi ya jinsi kila cheti kilivyotolewa katika /etc/letsencrypt/renewal/example.com.conf, ikiwa ni pamoja na authenticator = dns-cloudflare na njia ya sifa za uingizaji (credentials path), hivyo timer ya kawaida ya mara mbili kwa siku inajifanyia uingizaji upya bila msaada wako. Fanya mazoezi ya mchakato mzima dhidi ya mazingira ya staging:

sudo certbot renew --dry-run

Kufanikiwa kunamaanisha kuwa sifa za uingizaji (credentials) zinafanya kazi na uthibitisho unakamilika kuanzia mwanzo hadi mwisho; uingizaji upya halisi baada ya siku 60 utafuata njia hiyo hiyo. Hatua mbili za ziada ni muhimu kufanya leo. Kwanza, cheti kilichofanyiwa uingizaji upya kwenye diski hakibadilishi chochote mpaka seva ya wavuti iipakue upya (reload), hivyo weka deploy hook iliyoelezwa kwenye mwongozo wa nginx na Apache. Pili, chukulia faili la sifa za uingizaji kwa uangalifu: mtu yeyote anayeweza kusoma faili hilo anaweza kuhariri eneo lako la DNS, jambo ambalo linatosha kuelekeza barua pepe zako au kufanya changamoto za DNS-01 zao. Liweke katika mode 600 chini ya /root, weka token katika eneo moja tu, na ubadilishe (rotate) ikiwa utahisi imevuja.

Unapozihitaji wildcard

Wildcard ni chombo sahihi kwa subdomain nyingi, au kwa subdomain ambazo huwezi kutabiri. Sio chaguo sahihi kwa mambo mengine yote.

• Subdomain moja, au chache zinazojulikana: cheti cha kawaida cha SAN (subject alternative name) ni rahisi zaidi. certbot --nginx -d example.com -d www.example.com -d app.example.com inashughulikia majina hadi 100 kupitia HTTP-01, na hakuna ujedwali wa DNS API unaobaki kwenye seva.
• Wildcard inalingana na label moja tu. *.example.com haikui example.com, ndiyo maana amri za juu zinaomba zote mbili, na haikui a.b.example.com pia; hiyo ingehitaji *.b.example.com.
• Funguo ya siri (private key) moja inasimamia kila subdomain. Ikiwa mashine inayoshikilia funguo hiyo imevamiwa, kila jina ambalo wildcard inalikiwa huathirika kwa wakati mmoja.
• Ikiwa Traefik inafanya TLS (transport layer security) termination kwa container zako, hauhitaji Certbot kabisa: Traefik inajihusisha na kuomba vyeti vya wildcard kupitia DNS-01, ikitumia aina ile ile ya token ya mtoa huduma.

Mahali ambapo wildcard inafaa kweli: subdomain za kila mteja au kila app zinazoundwa kwa kasi zaidi kuliko unavyotaka kutoa vyeti upya, na host za ndani ambazo hazina port 80 ya umma, kama vile huduma zinazofikiwa tu kupitia WireGuard VPN. DNS-01 haijawahi kuunganishwa na host inayotolewa cheti, hivyo hata mashine ya siri kabisa inaweza kuwa na cheti kinachotambulika hadharani.

FAQ

Je, Certbot inaweza kutoa cheti cha wildcard kwa kutumia HTTP-01?

Hapana. HTTP-01 inathibitisha udhibiti wa jina moja tu la hostname, kwa sababu seva ya uthibitishaji hupata faili ya token kutoka kwenye jina hilo mahususi. Wildcard inafunika kila jina chini ya domain, hivyo Let's Encrypt inahitaji changamoto ya DNS-01 kwa ajili yake, na authenticators za --nginx, --apache, --webroot na --standalone zote zinategemea HTTP. Njia pekee ni rekodi ya TXT kwenye _acme-challenge.example.com, inayowekwa kwa mkono au kwa kutumia plugin ya DNS.

Je, cheti cha wildcard kinafunika root domain?

Hapana. Wildcard inalinganisha label moja tu, hivyo *.example.com inafunika www.example.com lakini si example.com tupu, na si a.b.example.com. Omba majina yote mawili kwenye cheti kimoja kwa kutumia -d example.com -d '*.example.com'. Hii inatengeneza changamoto mbili, na rekodi zote za TXT zinakaa kwenye _acme-challenge.example.com moja, hivyo ongeza rekodi ya pili bila kufuta ya kwanza.

Kwa nini cheti changu cha wildcard hakifanyiwe marekebisho (renew) kiotomatiki?

Kwa sababu kilitolewa kwa kutumia --manual. Kila marekebisho yanahitaji thamani mpya ya TXT, na timer ya kiotomatiki haina uwezo wa kuweka thamani hiyo, hivyo mchakato wa marekebisho unasimama kwa kosa la An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Toa cheti upya kwa kutumia plugin ya DNS kama vile certbot-dns-cloudflare, au toa skripti za --manual-auth-hook na --manual-cleanup-hook zinazofanya marekebisho ya rekodi kupitia API ya mtoa huduma wako.

Inachukua muda gani ili rekodi ya _acme-challenge TXT ionekane?

Inategemea mtoa huduma wako wa DNS: kuanzia sekunde chache hadi dakika kadhaa. Uthibitishaji husoma seva za mamlaka za zone yako, hivyo kagua kwa dig +short TXT _acme-challenge.example.com @1.1.1.1 na usubiri thamani inayotarajiwa ionekane kabla ya kuendelea na mchakato wa mkono. Ukitumia plugin, ongeza muda wa kusubiri kupitia chaguo la propagation la plugin hiyo, kwa mfano --dns-cloudflare-propagation-seconds 60, ikiwa uthibitishaji utaripoti kuwa rekodi haijapatikana.

Je, cheti cha wildcard ni salama kiasi kidogo kuliko cheti cha kawaida?

Usimbuaji (cryptography) ni sawa. Tofauti ni za kiutendaji: fungi moja ya siri (private key) inafunika kila subdomain, hivyo uvamizi unaweza kuenea zaidi, na siri ya API ya DNS inayohitajika kwa utendaji wa kiotomatiki ni siri nyeti inayohifadhiwa kwenye seva. Ikiwa unatumia subdomain chache zinazojulikana, cheti cha SAN kinuepuka hofu zote hizi, na ndipo mwongozo huu unapopendekeza kuacha kutumia wildcard.