Jinsi ya kusakinisha Certbot kwenye Ubuntu 24.04

Sakinisha Certbot: apt au snap

Kwenye Ubuntu 24.04, sudo apt install certbot python3-certbot-nginx inakupa Certbot inayofanya kazi na inayotoa vyeti halisi vya Let's Encrypt vilivyothibitishwa hadharani. Nyaraka rasmi za Certbot zinakuelekeza kwenye snap; tofauti ni ndogo — snap hufuatilia matoleo mapya ya upstream, wakati kifurushi cha archive hufuatilia kile kilichokuja na LTS na kupata marekebisho ya usalama.

Chagua moja. Nakala mbili za Certbot zinamaanisha saa mbili za usajili (renewal timers) zinazolenga mti mmoja wa /etc/letsencrypt, na ile uliyoisahau ndiyo itakayokushtua.

Njia ya apt:

sudo apt update
sudo apt install certbot python3-certbot-nginx

Hii inasakinisha /usr/bin/certbot, plugin ya nginx, jozi ya certbot.service + certbot.timer, na ingizo ya /etc/cron.d/certbot ambayo haifanyi kazi chini ya systemd.

Njia ya snap:

sudo apt remove certbot python3-certbot-nginx
sudo snap install core && sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

Snap inakuja na saa yake yenyewe, snap.certbot.renew.timer. Ondoa kifurushi cha apt kabla ya kusakinisha snap.

Baada ya hapo, usakinishaji zote mbili zinafanya kazi sawa. Certbot 2.x hutumia ECDSA (P-256) kama chaguo la kawaida — tumia --key-type rsa tu kwa mteja asiyeweza kutumia ECDSA. Hali zote zinahifadhiwa chini ya /etc/letsencrypt: archive/ inashikilia mafaili halisi ya funguo na cheti, live/ ni symlinks kwenda kwenye mafaili ya sasa, renewal/ ni faili moja la usanidi kwa kila cheti, na accounts/ ni funguo yako ya akaunti ya ACME.

Kile HTTP-01 kinachofanya, na kwa nini port 80 si ya hiari

Changamoto ya HTTP-01 ni mrejesho (callback). Unaiomba Let's Encrypt cheti kinachohusu example.com; inatafuta jina hilo kwenye DNS ya umma, inafungua muunganisho kwenye port 80 kwenye anwani inayopatikana, na kuomba http://example.com/.well-known/acme-challenge/<token>. Seva yako inajibu kwa maudhui sahihi ya token ambayo Certbot imeandika kwenye diski. Huu ndio utaratibu mzima. Matokeo matatu yanatokea kutokana na hili, na ndiyo sababu kuu za kushindwa kwa utoaji wa cheti.

• Port 80 lazima ifikike kutoka kwenye mtandao wa umma, siyo tu kutoka kwenye laptop yako. Sheria ya ufw, kikundi cha usalama cha mtoa huduma wa wingu (cloud-provider security group), au firewall ya VPS-console inayofungua 443 pekee itasababisha kushindwa kwa utoaji wa cheti na kila utafutaji mpya wa cheti (renewal) baada ya hapo.
• DNS lazima iwe imeelekeza kwenye seva hii. Seva ya uthibitishaji hufanya utafutaji wake wenyewe kutoka nje; rekodi zako za /etc/hosts na kumbukumbu ya kivinjari (browser cache) hazina maana kwake.
• Ikiwa umeweka rekodi ya AAAA, IPv6 itajaribiwa kwanza. Let's Encrypt hujaribu tena kupitia IPv4 ikiwa muunganisho wa IPv6 unashindwa kabisa — lakini rekodi ya AAAA iliyopitwa na wakati inayoelekeza kwenye host inayokubali muunganisho lakini inatoa kitu kingine itasababisha kushindwa kabisa.

Mrejesho (redirects) unaruhusiwa: uthibitishaji hufuata HTTP redirect kwenda HTTPS na haijalali kama cheti upande wa pili kinakosekana, kimeisha muda wake, au kimesainiwa wenyewe (self-signed). Hata hivyo, haitafanya utafutaji mahali popote isipokuwa kwenye port 80. Certbot haina utekelezaji wa TLS-ALPN-01, hivyo "tumia tu 443" siyo suluhisho.

Kuchagua authenticator: --nginx, --webroot, --standalone

--nginx ni chaguo sahihi la msingi ikiwa nginx tayari inafanya kazi na inatoa domain tayari. Certbot inasoma config yako, inaweka mahali kwa muda kwa ajili ya challenge, inafanya reload nginx, inathibitisha, kisha inaandika TLS directives kwenye server block yako. Hakuna muda wa kutokuwa online (no downtime).

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

Kwa kutumia script, kwa seva mpya:

sudo certbot --nginx \
  -d example.com -d www.example.com \
  --agree-tos -m ops@example.com --no-eff-email \
  --redirect --non-interactive

--webroot ni sahihi unapotaka Certbot isiguse kabisa config ya nginx — mfano unayotengeneza kutokana na template, unayohifadhi kwenye git, au unayotuma kwa Ansible. Certbot inaandika faili ya challenge pekee, kwenye directory ambayo tayari unaitoa.

sudo certbot certonly --webroot -w /var/www/example.com \
  -d example.com -d www.example.com \
  --deploy-hook "systemctl reload nginx"

--standalone ni sahihi wakati hakuna kitu kinachosikiliza kwenye port 80: mail server, API inayotumia 443 pekee, au script ya kwanza kabisa inayojiendesha kabla nginx haipo. Certbot inachukua port 80 yenyewe kwa sekunde chache. Ikiwa nginx inaendelea kufanya kazi, hii itafeli — izime kabla ya kuanza:

sudo certbot certonly --standalone -d mail.example.com \
  --pre-hook "systemctl stop nginx" \
  --post-hook "systemctl start nginx"

Hooks hizo zinahifadhiwa kwenye config ya marejesho (renewal) ya cheti, hivyo kitendo hicho cha kusitisha/kuwasha kinafanyika chenyewe wakati wa marejesho.

Block ya server inayofanya kazi kabla na baada ya cheti kuwepo

Tatizo la mzunguko: nginx inakataa kuanza ikiwa ssl_certificate inaelekeza kwenye faili ambayo haipo, na Certbot haiwezi kuthibitisha wakati nginx imezimwa. Washa tovuti kwenye port 80 kwanza.

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

    root /var/www/example.com;
    index index.html;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/example.com;
        default_type "text/plain";
        try_files $uri =404;
    }

    location / {
        try_files $uri $uri/ =404;
    }
}

Run sudo nginx -t && sudo systemctl reload nginx, thibitisha majibu ya curl -I http://example.com/ kutoka nje ya mfumo, kisha toa cheti. Baada ya hapo:

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/example.com;
        default_type "text/plain";
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name example.com www.example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    root /var/www/example.com;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Kiambishi awali cha ^~ kwenye eneo la ACME ni muhimu: kinazuia block ya return 301 isimeze ombi la uthibitisho. Kuacha eneo hilo kwenye port 80 kunahakikisha usajili mpya unaendelea kufanya kazi baada ya tovuti nyingine kuwa HTTPS-only.

Sintaksi ya HTTP/2 inategemea toleo lako la nginx, na kuchanganya aina hizo mbili husababisha hitilafu wakati wa kuanza. Ubuntu 24.04 inakuja na nginx 1.24, ambayo inahitaji iandikwe ndani — listen 443 ssl http2;. Debian 13 inakuja na nginx mpya zaidi, ambayo inahitaji amri ya http2 on; iliyotenganishwa. Angalia nginx -v kwanza.

Elekeza nginx kwenye live/, usielekeze kwenye archive/. Symlinks za live/ hufanyiwa marekebisho kila wakati wa usajili mpya; kutumia njia ya moja kwa moja (hard path) kwenye archive/ kutakuunganisha kwenye cheti kitakachokwisha muda wake.

Wildcards inamaanisha DNS-01, na DNS-01 inamaanisha plugin

Cheti cha wildcard (*.example.com) hakiwezi kuthibitishwa kupitia HTTP-01 — hakuna jina moja la host linaloweza kutumika kupata faili. DNS-01 ndiyo njia pekee: unathibitisha udhibiti kwa kuchapisha rekodi ya _acme-challenge.example.com TXT. Certbot inahitaji sifa za API za mtoa huduma wako wa DNS ili kufanya hivyo bila usimamizi, ndiyo maana plugin za mtoa huduma zinatumiwa. Mwongozo kamili wa cheti cha wildcard unaelezea utendaji wa rekodi ya TXT na changamoto ya kuhifadhi (renewal trap) katika hali ya manual; toleo fupi la Cloudflare linafuata.

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

Kwenye njia ya apt, ni sudo apt install python3-certbot-dns-cloudflare badala yake. Sifa huwekwa kwenye faili ambalo linatumiwa na root pekee:

# /root/.secrets/cloudflare.ini
# then: sudo chmod 600 /root/.secrets/cloudflare.ini
dns_cloudflare_api_token = your_scoped_token_here

Weka ukomo wa token kwenye haki za DNS-edit kwenye zone hiyo moja tu. Ni funguo ya DNS yako; itumie kama funguo.

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

Weka alama za nukuu kwenye wildcard ili shell yako isichanganye alama hizo. DNS-01 pia hutatua changamoto ambazo HTTP-01 haiwezi: vyeti kwa host ambazo hazina port 80 ya umma — huduma ya ndani, kifaa kinachofikiwa kupitia self-hosted WireGuard VPN kwenye VPS, au jopo la admin kwenye interface ya ndani.

Ufanyaji upya: siku 90, muda, na deploy hook

Cheti za Let's Encrypt zina ukomo wa siku 90. Certbot hufanya ufanyaji upya wakati siku chini ya 30 zimebaki. Hii inakupa dirisha la siku 30 ambapo hitilafu ya ufanyaji upya ni tatizo linaloweza kurekebishwa badala ya kukatika kwa huduma. Let's Encrypt haitumi tena barua pepe za tahadhari ya ukomo — hakuna atakayekujulisha, hivyo usimamizi ni wako sasa.

Angalia muda uliopangwa wakati wa usakinishaji:

systemctl list-timers 'certbot*' 'snap.certbot*'
sudo certbot certificates

certbot renew hukagua kila usanidi katika /etc/letsencrypt/renewal/, huruka chochote kilicho nje ya dirisha la siku 30, na hufanya ufanyaji upya kwa mengine akitumia bendera (flags) zilezile za run ya awali. Ndiyo maana run ya kwanza ni muhimu: ndiyo inayorekodiwa.

Kufanya upya faili kwenye diski hakubadilishi chochote peke yake — nginx itaendelea kutoa cheti cha zamani kutoka kwenye memory mpaka kitu kitakachoiambia kirejee (reload). Unganisha deploy hook mara moja:

sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh >/dev/null <<'EOF'
#!/bin/sh
set -e
nginx -t && systemctl reload nginx
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

Chochote kinachoweza kutekelezwa (executable) katika renewal-hooks/deploy/ hufanya kazi baada ya ufanyaji upya wowote wenye mafanikio. Bendera ya --deploy-hook hufanya kazi hiyo hiyo kwa cheti kimoja, ikihifadhi renew_hook = ... katika usanidi wake wa ufanyaji upya. certbot --nginx hufanya reload kwa ajili yako; mipangilio ya --webroot na --standalone haifanyi hivyo. Kukosekana kwa hook ndiyo sababu inayofanya tovuti itoe cheti kilichopita muda wakati certbot certificates ikiripoti cheti kipya. Chochote kingine kinachosoma cheti wakati wa kuanza kinahitaji hook hiyo hiyo — programu iliyowekwa kwenye container kama Nextcloud VPS install with Docker, TLS and backups inahitaji hatua yake ya kuanza upya au reload iliyounganishwa hapa pia.

Kujaribu uingizaji upya (renewal) kwa vitendo

sudo certbot renew --dry-run

Hii inafanya jaribio kamili dhidi ya mazingira ya staging ya Let's Encrypt: njia ya kodi ni sawa, firewall ni sawa, DNS ni sawa, haina gharama ya kikomo cha idadi ya maombi (rate-limit), na hakuna kitu kinachoandikwa kwenye diski. Ikiwa inafanikiwa leo, uingizaji upya wa kiotomatiki baada ya siku 60 utafanikiwa pia, ikiwa hakuna kitu kinachobadilika kwenye mfumo.

Dry run haithibitishi kuwa reload hook yako inafanya kazi — tabia hiyo inatofautiana kulingana na toleo la Certbot. Jaribu sehemu hiyo kwa mkono: endesha script ya hook moja kwa moja, thibitisha kuwa systemctl reload nginx imefanikiwa, na kagua sudo grep renew_hook /etc/letsencrypt/renewal/example.com.conf.

Makosa utakayokutana nayo

Could not bind to IPv4 or IPv6. — --standalone kwa sababu nginx tayari inatumia port 80. Tumia --nginx au --webroot, au simamisha nginx kabla ya kuanza. Hakiki programu inayotumia port hiyo kwa kutumia sudo ss -lntp | grep ':80'.

Timeout during connect (likely firewall problem) — Let's Encrypt imeshindwa kufikia port 80. Angalia hatua hizi: sudo ufw status (ifungue kwa kutumia sudo ufw allow 'Nginx Full'), kisha firewall ya mtoa huduma wa VPS, kisha DNS. Jaribu kutoka sehemu nyingine isiyo server yako: curl -sSv http://example.com/.well-known/acme-challenge/test. Rekodi ya AAAA iliyopitwa na wakati pia hutoa ujumbe huu.

unauthorized :: Invalid response from http://example.com/.well-known/acme-challenge/xyz: 404 — port 80 inaweza kufikiwa, lakini token haitolewi. Ombi limefikia server block tofauti (angalia ni ipi inayomiliki default_server), au directory iliyowekwa kwenye -w si ile inayotolewa na nginx. Weka faili kwenye /var/www/example.com/.well-known/acme-challenge/test na uifuate kwa nje; ikiwa inatoa 404, basi cheti kilikuwa si tatizo.

DNS problem: NXDOMAIN looking up A for example.com — jina halitambuliki hadharani. Rekodi mpya ambazo hazijasambaa, au rekodi kwenye zone ambayo msajili wako haitoi.

too many certificates already issued for: example.com — kikomo cha idadi ya maombi (rate limit), na hiki hutokea wakati wa kufanya debugging mara nyingi. Let's Encrypt inazuia vyeti vinavyojirudia — seti sawa ya majina — mara tano kwa wiki, na pia inaruhusu vyeti vipya 50 kwa kila domain iliyosajiliwa kwa wiki; hakuna kinachoweza kuondoa vikwazo hivi isipokuwa muda. Fanya debugging kwenye staging kwa kutumia --dry-run.

nginx: [emerg] cannot load certificate "/etc/letsencrypt/live/example.com/fullchain.pem": No such file or directory — nginx imesanidiwa kwa cheti ambacho hakijatolewa kamwe, au kimoja kilichofutwa kwa kutumia certbot delete. Zima (comment out) TLS server block, washa nginx, toa cheti, kisha rudisha block hiyo.

open() "/etc/letsencrypt/options-ssl-nginx.conf" failed — faili hiyo huja pamoja na kifurushi cha nginx plugin. Kwenye mfumo wa certonly usio na python3-certbot-nginx, ongeza plugin au badilisha mstari wa include na mipangilio yako ya ssl_protocols na ssl_ciphers.

Kumiliki hii kwa kiwango kikubwa

Cheti kimoja kinaweza kubeba majina hadi 100, na certbot --nginx -d a.example.com -d b.example.com ... moja ni inayovutia — hadi rekodi moja ya DNS iliyopitwa na wakati inaposhindwa uthibitisho na kusababisha majina mengine yote kwenye cheti hicho kushindwa. Vyeti vilivyotenganishwa kwa kila tovuti hufeli kwa njia huru, jambo ambalo ni muhimu kwenye seva inayohosti vitu vingi. Unapozidi tovuti chache, msimamizi wa mlangoni (front door) anayeofahamu ACME anafaa: Traefik reverse proxy inayojiendesha na programu nyingi chini ya Docker Compose huomba na kuhuisha vyeti yenyewe, na Certbot haihitajiki tena.

Nakili /etc/letsencrypt nzima — sudo tar -czf letsencrypt-$(date +%F).tar.gz -C /etc letsencrypt — ikiwa na symlinks kama zilivyo. Mfumo huo una accounts/, ufunguo wa akaunti yako ya ACME, ambao hauwezi kutengenezwa upya kwa namna ile ile. Kuhamia kwenye VPS mpya kunapungua hadi: rsync mfumo huo kwa kutumia -a, install Certbot, badilisha DNS, na kimbiza certbot renew --dry-run kabla ya kuanza kutumia mfumo mpya.

Ukifuta mfumo au ukihamia kwenye LTS mpya, muda wa kuhuisha (renewal timer) hautafuatana nawe. Baada ya uhamiaji wowote, urejesho wa snapshot, au sasisho la distro, kimbiza systemctl list-timers 'certbot*' na --dry-run moja. Kuruka hatua hiyo ndiyo husababisha tovuti kuzimika baada ya siku 89, saa 3 usiku, kwenye cheti ambacho kila mtu alidhani kinajihuisha chenyewe.

Hii yote inafanya kazi ikiwa unamiliki mashine yenye IP ya umma na port 80 iliyo wazi kwa ulimwengu — kwa maneno mengine, VPS. Hatua hizi ni sawa kwenye yoyote kati ya hizo.

Hatua zilezile za cheti zinatumika kwenye Apache badala ya nginx, na wakati cheti cha umma kisipokuwa chaguo, cheti cha kujitengeneza (self-signed) kwenye Ubuntu hufunika huduma za ndani.

FAQ

Je, nahitaji kufungua port 80 ikiwa tovuti yangu inatumia HTTPS pekee?

Ndiyo, kwa ajili ya HTTP-01 challenge. Let's Encrypt huanza ombi lake la uthibitisho kwenye port 80, na Certbot haina utekelezaji wa TLS-ALPN-01. Hivyo, ukuta wa moto (firewall) unaofungua port 443 pekee utazuia utoaji wa kwanza na kila utengenezaji mpya (renewal) usioofuatiliwa. Kuhamisha trafiki (redirect) kutoka port 80 kwenda HTTPS ni sawa — uthibitisho utafuata mwelekeo huo. Njia pekee ya kuacha port 80 kabisa ni kutumia DNS-01 kupitia plugin ya mtoa huduma.

apt au snap — ni Certbot ipi nifunge kwa nginx kwenye Ubuntu 24.04?

Tumia apt. sudo apt install certbot python3-certbot-nginx inakupa Certbot 2.9.0 kwenye Ubuntu 24.04, ambayo ni ya kisasa vya kutosha kwa kila kitu kwenye mwongozo huu, inapata maboresho ya usalama kupitia unattended-upgrades, na haihitaji snapd. Chagua snap ikiwa unahitaji toleo jipya zaidi mara moja au plugin ya DNS inayotolewa pekee kama snap. Vyovyote vile, chagua moja tu: usakinishaji wa mifumo miwili inamaanisha kuwa na timer mbili za utengenezaji zinazoelekea kwenye /etc/letsencrypt moja, na inayosahaulika ndiyo itakayokusumbua.

Je, Certbot inaweza kutoa cheti cha wildcard kwa nginx?

Ni kupitia DNS-01 pekee. Wildcard kama *.example.com haina jina moja la host (hostname) la kupata faili la uthibitisho, hivyo --nginx, --webroot na --standalone vyote haviwezekani. Sakinisha plugin ya mtoa huduma wako wa DNS, weka API token kwenye faili la siri la root pekee, kisha endesha certbot certonly --dns-cloudflare -d example.com -d '*.example.com', ukiweka alama za nukuu kwenye wildcard ili kuzuia shell globbing.

Kwa nini nginx bado inaonyesha cheti cha zamani baada ya utengenezaji kufanikiwa?

nginx huweka cheti kwenye kumbukumbu (memory) na haitambui faili mpya iliyo kwenye diski mpaka iwe imereload. certbot --nginx inafanya reload kwa ajili yako, lakini --webroot na --standalone hazifanyi hivyo, hivyo utengenezaji unaweza kufanikiwa wakati kivinjari (browser) bado kinaona cheti kinachokoma muda. Weka script inayoweza kutekelezwa kwenye /etc/letsencrypt/renewal-hooks/deploy/ inayorun nginx -t && systemctl reload nginx, na itafanya kazi baada ya kila utengenezaji uliofanikiwa.

Je, certbot renew --dry-run inathibitisha kuwa utengenezaji utafanya kazi?

Kwa kiasi kikubwa. Inafanya uthibitisho halisi dhidi ya mazingira ya staging — firewall sawa, DNS sawa, na njia ya kodi sawa — bila gharama ya kikomo cha ombi (rate-limit) na bila kuandika kitu kwenye diski, hivyo kufanikiwa kunamaanisha sehemu ya mtandao iko sawa. Hata hivyo, haithibitishi kwa uhakika kuwa deploy hook yako inafanya kazi. Jaribu hilo kando: endesha script ya hook kwa mkono na ukague sudo grep renew_hook /etc/letsencrypt/renewal/example.com.conf.