Certbot: گرفتن و تمدید گواهی‌های Let's Encrypt به روش درست

certbot چیست، و واقعاً چه‌کار می‌کند

Certbot یک ACME client رایگان و open-source است که توسط Electronic Frontier Foundation نگهداری می‌شود. ACME همان پروتکلی است که Let's Encrypt (و تعداد رو‌به‌رشدی از CAهای دیگر) برای صدور گواهی بدون دخالت انسان استفاده می‌کند. Certbot آن را به‌جای شما صحبت می‌کند: یک account key می‌سازد، از CA گواهی می‌خواهد، ثابت می‌کند مالک دامنه‌اید، گواهی و کلید را روی دیسک ذخیره می‌کند، و اگر اجازه بدهید، تنظیمات وب‌سرور شما را ویرایش می‌کند و همه‌چیز را قبل از انقضا تمدید می‌کند.

اثبات مالکیت یک challenge است، و certbot از دو نوع آن پشتیبانی می‌کند. HTTP-01: CA یک token تصادفی روی http://example.com/.well-known/acme-challenge/<token> روی پورت 80 می‌خواهد، و certbot مطمئن می‌شود آن فایل سرو می‌شود. DNS-01: CA یک رکورد TXT روی _acme-challenge.example.com جستجو می‌کند، و certbot (یا خودتان) آن را منتشر می‌کنید. HTTP-01 پیش‌فرض ساده است؛ DNS-01 تنها راه گرفتن یک wildcard و راه صدور برای سروری است که از اینترنت قابل‌دسترس نیست.

اینکه چه کسی چه‌کاری انجام می‌دهد با دو نوع پلاگین تعیین می‌شود. یک authenticator به challenge پاسخ می‌دهد (--nginx، --apache، --webroot، --standalone، --manual، یا یک پلاگین DNS مثل --dns-cloudflare). یک installer گواهی را در تنظیمات سرور می‌گذارد (nginx یا apache). certbot --nginx هر دو کار را می‌کند؛ certbot certonly ... فقط گواهی را می‌گیرد و تنظیمات را به خودتان می‌سپارد.

همه‌چیز زیر /etc/letsencrypt فرود می‌آید. فایل‌هایی که سرور را به آن‌ها اشاره می‌دهید در /etc/letsencrypt/live/<cert-name>/ هستند: fullchain.pem (گواهی شما به‌همراه intermediate) و privkey.pem. این‌ها symlinkهایی به archive/ هستند، پس مسیرها بعد از هر تمدید تغییر نمی‌کنند. اگر می‌خواهید بدانید یک گواهی چیست و چرا رایگان است، گواهی‌های SSL رایگان را بخوانید؛ این راهنما دربارهٔ ابزار است.

نصب certbot: اول snap، بعد پکیج‌های distro

پروژهٔ certbot روی لینوکس پکیج snap را پیشنهاد می‌کند. این نسخهٔ جاری را دنبال می‌کند (5.x در 2026)، Python خودش را bundle می‌کند، و یک systemd timer برای تمدید نصب می‌کند. اول هر نسخهٔ distro را حذف کنید تا دو certbot روی /etc/letsencrypt با هم درگیر نشوند: sudo apt remove certbot، sudo dnf remove certbot یا sudo yum remove certbot.

پکیج‌های distro کار می‌کنند و چیزی هستند که بسیاری از سرورها از قبل دارند: sudo apt install certbot python3-certbot-nginx (یا python3-certbot-apache) در Debian و Ubuntu، و همان نام پکیج‌ها از EPEL در RHEL، Rocky و Alma. trade-off آن قدمت است: یک توزیع LTS می‌تواند certbotای چند نسخهٔ اصلی عقب‌تر ارسال کند، که حالا که Let's Encrypt طول عمر گواهی‌ها را کوتاه‌تر می‌کند اهمیت دارد (بخش تمدید را ببینید). Certbot روی PyPI و به‌شکل image داکر (certbot/certbot و یک image به‌ازای هر پلاگین DNS) هم منتشر می‌شود اگر آن‌ها را ترجیح می‌دهید.

بعد از نصب، certbot --version به شما می‌گوید چه چیزی گرفتید، و sudo certbot certificates هر گواهی‌ای که مدیریت می‌کند را با دامنه‌ها، تاریخ انقضا و مسیر فایل‌هایش فهرست می‌کند.

نصب پیشنهادی روی لینوکس (snap)

# remove an OS-packaged certbot first, if present
sudo apt remove certbot

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot

certbot --version
sudo certbot certificates

صدور گواهی برای nginx و Apache

پلاگین‌های nginx و Apache کوتاه‌ترین مسیرند. sudo certbot --nginx -d example.com -d www.example.com بلاک serverای را پیدا می‌کند که server_name آن مطابقت دارد، HTTP-01 را از طریق آن پاسخ می‌دهد، ssl_certificate و ssl_certificate_key را در آن بلاک می‌نویسد و nginx را reload می‌کند. نسخه‌های اخیر به‌طور پیش‌فرض ریدایرکت HTTP به HTTPS را هم اضافه می‌کنند؛ --no-redirect آن را خاموش می‌کند. --apache همین کار را با virtual hostها می‌کند. هر دو به یک server_name / ServerName که با دامنه مطابقت دارد نیاز دارند، وگرنه certbot نمی‌تواند بگوید کدام بلاک را ویرایش کند. تازه‌کار با خودِ سرور هستید؟ از nginx چیست شروع کنید.

Webroot انتخابی است وقتی می‌خواهید certbot دستش را از تنظیمات شما دور نگه دارد: فایل challenge را در دایرکتوری‌ای می‌نویسد که سرور در حال اجرای شما از قبل سرو می‌کند. certonly یعنی شما خودتان دو خط ssl_ را یک‌بار اضافه می‌کنید؛ تمدیدها بعد از آن فقط فایل‌ها را پشت همان مسیرها جایگزین می‌کنند.

Standalone یک وب‌سرور کوچک مخصوص خودش روی پورت 80 شروع می‌کند. برای ماشین‌هایی است که هیچ وب‌سروری ندارند، یا وب‌سروری دارند که nginx یا Apache نیست. پورت 80 باید در زمان صدور و هر تمدید آزاد باشد، پس سرور دیگر را در یک hook متوقف کنید: --pre-hook "systemctl stop haproxy" --post-hook "systemctl start haproxy".

هر -d یک نام به همان گواهی اضافه می‌کند، و اولی نام گواهی می‌شود. برای اضافه‌کردن یک نام بعداً، دستور را دوباره با فهرست کامل به‌همراه --cert-name example.com اجرا کنید؛ certbot گواهی قدیمی را جایگزین می‌کند نه یک دومی می‌سازد.

چهار روش رایج صدور (یکی را انتخاب کنید)

# nginx: issue and install
sudo certbot --nginx -d example.com -d www.example.com

# Apache: issue and install
sudo certbot --apache -d example.com -d www.example.com

# webroot: issue only; your server keeps serving /.well-known/acme-challenge/
sudo certbot certonly --webroot -w /var/www/example -d example.com -d www.example.com

# standalone: certbot listens on :80 itself
sudo certbot certonly --standalone -d example.com

# then, in nginx, for the webroot/standalone case:
#   ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
#   ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

گواهی‌های wildcard با DNS-01

Let's Encrypt *.example.com را فقط از طریق DNS-01 صادر می‌کند. یک wildcard یک سطح را پوشش می‌دهد (shop.example.com، نه a.shop.example.com) و دامنهٔ خالی را پوشش نمی‌دهد، پس هر دو را درخواست کنید: -d example.com -d '*.example.com'. ستاره را quote کنید تا shell آن را expand نکند.

با یک پلاگین DNS certbot رکوردهای TXT را از طریق API provider DNS شما می‌سازد و حذف می‌کند، که همان چیزی است که تمدید را خودکار می‌کند. پلاگین‌های رسمی برای Cloudflare، Route 53، Google Cloud DNS، DigitalOcean، Linode، OVH، سرورهای RFC 2136 و دیگران هست، و پلاگین‌های third-party برای خیلی بیشتر. با snap اول اجازه می‌دهید پلاگین‌ها به‌عنوان root اجرا شوند (sudo snap set certbot trust-plugin-with-root=ok) و بعد snap پلاگین را نصب می‌کنید. فایل credentials را در مود 600 نگه دارید، و به token API کمترین scopeای که provider شما ارائه می‌دهد را بدهید (برای Cloudflare، *Zone: DNS: Edit* روی همان یک zone).

با --manual، certbot مقدار TXT را چاپ می‌کند و منتظر می‌ماند تا خودتان آن را دستی اضافه کنید. درخواست example.com و *.example.com با هم دو مقدار TXT زیر همان نام _acme-challenge.example.com می‌خواهد؛ هر دو را به‌شکل رکوردهای جدا منتشر کنید. قبل از فشردن Enter با dig +short TXT _acme-challenge.example.com بررسی کنید. نکتهٔ مهم: یک گواهی دستی به‌طور خودکار تمدید نمی‌شود مگر اینکه اسکریپت‌های --manual-auth-hook و --manual-cleanup-hook را که کار DNS را انجام می‌دهند بدهید، پس برای هر چیز بلندمدتی از یک پلاگین استفاده کنید.

اگر provider DNS شما API ندارد، می‌توانید _acme-challenge.example.com را با یک رکورد CNAME به zoneای که خودتان کنترل می‌کنید اشاره دهید؛ CA آن CNAME را دنبال می‌کند و رکورد TXT را آنجا می‌خواند.

Wildcard به‌همراه apex از طریق پلاگین DNS Cloudflare (snap)

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

# /root/.secrets/cloudflare.ini  (chmod 600)
#   dns_cloudflare_api_token = <token with Zone:DNS:Edit>

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

# by hand (no automatic renewal without hooks)
sudo certbot certonly --manual --preferred-challenges dns \
  -d example.com -d '*.example.com'

تمدید خودکار: timerها، hookها و --dry-run

برای certbot یک cron job نمی‌نویسید؛ پکیج از قبل این کار را کرده. snap یک systemd timer به نام snap.certbot.renew.timer نصب می‌کند، پکیج‌های Debian و Ubuntu certbot.timer را نصب می‌کنند، و بعضی پکیج‌ها یک فایل در /etc/cron.d/ استفاده می‌کنند. این job روزی دو بار certbot renew را اجرا می‌کند، که فقط گواهی‌هایی را که موعدشان رسیده تمدید می‌کند و در غیر این صورت ساکت خارج می‌شود. آن را با systemctl list-timers | grep certbot ببینید.

یک گواهی کِی موعدش می‌رسد؟ از certbot 4.0 به این سو، وقتی کمتر از یک‌سوم طول عمرش باقی مانده (نیم، برای گواهی‌های 10 روز یا کمتر)، و certbot همچنین نشانه‌های ACME Renewal Info (ARI) از CA را دنبال می‌کند. این مهم است چون Let's Encrypt طول عمر گواهی‌ها را کوتاه‌تر می‌کند: پروفایل پیش‌فرض از 90 به 64 روز در 10 فوریهٔ 2027 و به 45 روز در فوریهٔ 2028 می‌رود. یک راه‌اندازی که از یک خط cron ثابت «هر 60 روز» تمدید می‌کند خراب می‌شود؛ یکی که روزانه certbot renew را اجرا می‌کند خراب نمی‌شود. Let's Encrypt همچنین در 2025 فرستادن ایمیل‌های یادآوری انقضا را متوقف کرد، پس هیچ‌کس اگر تمدید بی‌صدا شکست بخورد به شما هشدار نمی‌دهد: خودتان تاریخ انقضای گواهی را رصد کنید.

سرور را بعد از تمدید reload کنید. installerهای nginx و Apache به‌جای شما reload می‌کنند. با webroot، standalone یا یک پلاگین DNS، یک deploy hook اضافه کنید، که فقط وقتی یک گواهی واقعاً تمدید شده اجرا می‌شود. آن را در دستور زمان صدور بگذارید (--deploy-hook، که در /etc/letsencrypt/renewal/<name>.conf ذخیره می‌شود) یا یک اسکریپت اجراشدنی در /etc/letsencrypt/renewal-hooks/deploy/ بگذارید.

همیشه تست کنید با sudo certbot renew --dry-run. این کل فرآیند تمدید را در برابر محیط staging لت‌س انکریپت اجرا می‌کند، با challengeهای واقعی، بدون دست‌زدن به گواهی‌های زنده‌تان یا استفاده از rate limitهای production.

timer را بررسی کنید، تمدید را تست کنید، nginx را بعد از هر تمدید reload کنید

systemctl list-timers | grep certbot

sudo certbot renew --dry-run

# reload nginx whenever any certificate is renewed
sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh >/dev/null <<'EOF'
#!/bin/sh
systemctl reload nginx
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

# when does each certificate expire?
sudo certbot certificates

rate limitهایی از Let's Encrypt که واقعاً به آن‌ها می‌خورید

محدودیت‌های Let's Encrypt برای استفادهٔ معمولی سخاوتمندند و در یک جلسهٔ دیباگ دردآورند. آن‌هایی که گیر می‌کنند:

5 گواهی به‌ازای هر مجموعهٔ دقیق نام در هر 7 روز. صدور example.com + www.example.com پنج بار در یک هفته، مثلاً با اجرای دوباره یک اسکریپت provisioning یا پاک‌کردن /etc/letsencrypt در هر شروع container، همان مجموعهٔ دقیق را برای چند روز قفل می‌کند. خطا می‌گوید *too many certificates already issued for this exact set of identifiers* و یک زمان retry می‌دهد. برای این یکی override وجود ندارد. تغییر مجموعهٔ نام‌ها (اضافه‌کردن یک نام دیگر) یک محدودیت جدید می‌گیرد، اما راه‌حل واقعی نگه‌داشتن /etc/letsencrypt روی storage دائمی است.

5 اعتبارسنجی ناموفق به‌ازای هر hostname به‌ازای هر حساب در هر ساعت. یک رکورد DNS غلط به‌همراه یک حلقهٔ retry این را در چند دقیقه می‌سوزاند.

50 گواهی به‌ازای هر دامنهٔ ثبت‌شده در هر 7 روز، که در سراسر همهٔ زیردامنه‌های example.com شمارش می‌شود، و 300 سفارش جدید به‌ازای هر حساب در هر 3 ساعت. پلتفرم‌های میزبانی با زیردامنهٔ زیاد اول به این‌ها می‌خورند.

تمدیدها با ملایمت رفتار می‌شوند: تمدیدی که از ARI استفاده می‌کند، همان‌طور که certbot فعلی می‌کند، از همهٔ محدودیت‌ها معاف است، و یک تمدید معمولی همان مجموعهٔ نام‌ها از محدودیت‌های per-domain و per-order معاف است.

قانون برای آزمایش‌ها: --test-cert (مستعار --staging) اضافه کنید یا از --dry-run استفاده کنید. staging محدودیت‌های بسیار بالاتری دارد و گواهی‌هایی صادر می‌کند که مرورگرها به آن‌ها اعتماد ندارند، که دقیقاً همان چیزی است که تا وقتی challenge را درست کنید می‌خواهید.

خطاهای رایج certbot و چطور رفعشان کنیم

Timeout during connect / connection refused روی پورت 80. HTTP-01 همیشه روی پورت 80 شروع می‌شود، حتی اگر سایت شما فقط HTTPS سرو کند. پورت 80 را در firewall و security group ابری باز کنید؛ ریدایرکت‌کردنش به HTTPS مشکلی ندارد، چون CA ریدایرکت‌ها را دنبال می‌کند. اگر پورت 80 نمی‌تواند باز شود، به DNS-01 سوئیچ کنید.

Invalid response / 404 روی /.well-known/acme-challenge/. درخواست به یک سرور رسیده، اما نه سرور درست یا نه دایرکتوری درست. دلایل رایج: رکورد A هنوز به یک host قدیمی اشاره می‌کند، یک load balancer درخواست را به یک node دیگر می‌فرستد، یک بلاک location یا rewrite مسیر را می‌گیرد، یا -w به webroot غلط اشاره می‌کند. خودتان تست کنید: یک فایل زیر .well-known/acme-challenge/ بسازید و از بیرون با HTTP معمولی آن را curl کنید.

یک رکورد AAAA که جای دیگری اشاره می‌کند. اگر آن نام یک آدرس IPv6 دارد، Let's Encrypt اول از طریق IPv6 اعتبارسنجی می‌کند. یک رکورد AAAA کهنه که از سرور دیگری پاسخ می‌دهد باعث شکست اعتبارسنجی می‌شود حتی اگر IPv4 درست باشد. رکورد AAAA را درست کنید یا حذف کنید؛ dig AAAA example.com آن را نشان می‌دهد.

DNS problem: NXDOMAIN / no valid A records. آن نام هنوز resolve نمی‌شود. برای propagation صبر کنید، و رکورد را از یک resolver بیرونی بررسی کنید، نه فقط ماشین خودتان.

CAA record prevents issuance. یک رکورد CAA روی دامنه (یا والدش) فهرست می‌کند کدام CAها اجازهٔ صدور دارند، و Let's Encrypt روی آن نیست. example.com. CAA 0 issue "letsencrypt.org" را اضافه کنید، و اگر برای wildcardها یکی تنظیم کرده‌اید issuewild را هم. پس‌زمینه در DNS چیست.

Incorrect TXT record / no TXT record found. DNS-01 قبل از propagate شدن رکورد بررسی شد، یا فقط یکی از دو مقدار wildcard منتشر شده بود. --dns-<provider>-propagation-seconds پلاگین را بالا ببرید یا در مود دستی بیشتر صبر کنید.

Could not automatically find a matching server block. پلاگین nginx به یک server_name نیاز دارد که برابر نام درخواستی باشد. آن را اضافه کنید، nginx -t را اجرا کنید، و دوباره تلاش کنید.

Too many certificates already issued. همان محدودیت تکراری بالا. از گواهی‌ای که از قبل دارید استفاده کنید (certbot certificates)، و از این به بعد با --staging تست کنید.

Certbot روی ویندوز: از یک ACME client بومی ویندوز استفاده کنید

Certbot پشتیبانی ویندوز را متوقف کرده است. آخرین installer ویندوز با certbot 2.9.0 در فوریهٔ 2024 ارسال شد، و سایت certbot حالا کاربران ویندوز را به جایگزین‌هایی که community فهرست کرده هدایت می‌کند. installerهای قدیمی که هنوز روی سایت‌های دانلود پیدا می‌شوند سال‌ها عقب‌اند و تغییرات تمدیدی که Let's Encrypt در حال رول‌اوت است را نمی‌گیرند، پس روی آن‌ها نسازید.

به‌جایش چه استفاده کنید به سرور بستگی دارد:

IIS یا هر سرور ویندوزی: win-acme انتخاب معمول بوده: یک ابزار command-line که گواهی را در IIS bind می‌کند، آن را در certificate store ویندوز یا فایل‌های PEM/PFX می‌نویسد، و یک scheduled task برای تمدید می‌سازد. نگهدارنده‌اش حالا simple-acme را توسعه می‌دهد، که به‌عنوان جایگزین drop-in و backwards-compatible توصیف شده، پس قبل از یک deployment جدید آن پروژه را بررسی کنید.

اتوماسیون PowerShell: Posh-ACME یک ماژول PowerShell با مجموعهٔ بزرگی از پلاگین‌های DNS برای wildcardها است.

یک GUI ترجیح می‌دهید: Certify The Web یک client گرافیکی برای IIS است.

واقعاً certbot می‌خواهید: آن را داخل WSL 2 برای صدور اجرا کنید، بعد فایل‌ها را به ویندوز export کنید. این برای گواهی‌های DNS-01ای که جای دیگری کپی می‌کنید عملی است، کمتر برای یک سایت IIS که به bind خودکار نیاز دارد.

هیچ‌کدام از این‌ها تایید نیست: همه پروژه‌های third-party هستند، پس قبل از اتکا به آن‌ها مستندات فعلی‌شان را بخوانید.

لغو و حذف گواهی‌ها

لغو کنید وقتی کلید خصوصی ممکن است لیک شده باشد، یا وقتی دیگر دامنه را کنترل نمی‌کنید. Certbot به نام گواهی یا فایل گواهی نیاز دارد، و یک دلیل: keycompromise، superseded، cessationofoperation، affiliationchanged یا unspecified (پیش‌فرض). بعد از لغو، certbot پیشنهاد می‌دهد فایل‌های محلی را حذف کند؛ بله بگویید، وگرنه همچنان سعی می‌کند گواهی لغوشده را تمدید کند. اگر کلید لیک شده، جایگزین را با یک کلید تازه صادر کنید، که certbot به‌طور پیش‌فرض این کار را می‌کند.

حذف کنید بدون لغو وقتی فقط دیگر از یک گواهی استفاده نمی‌کنید، مثلاً بعد از انتقال یک سایت: certbot delete --cert-name example.com آن را از /etc/letsencrypt و از تمدید حذف می‌کند. اول خط‌های ssl_ متناظر را از تنظیمات سرور حذف کنید، وگرنه nginx در reload بعدی start نمی‌شود.

Let's Encrypt اجرای OCSP را متوقف کرده؛ مرورگرها لغوها را از طریق CRLها می‌فهمند، پس یک لغو همه‌جا فوراً قابل‌مشاهده نیست. این یک دلیل دیگر برای نگه‌داشتن کلیدهای خصوصی فقط قابل‌خواندن برای root است.

لغو یک گواهی به‌خطرافتاده، یا حذف یکی که دیگر لازم ندارید

sudo certbot revoke --cert-name example.com --reason keycompromise

sudo certbot delete --cert-name example.com

پشت یک CDN: گواهی دست کیست

وقتی یک سایت پشت یک CDN یا یک reverse proxy دیگر می‌نشیند، بازدیدکنندگان دیگر گواهی origin شما را نمی‌بینند. edge با گواهی خودش TLS را terminate می‌کند، و اتصال از edge به origin شما یک handshake جدا است. می‌توانید certbot را روی origin نگه دارید تا آن hop دوم را امن کند، اما گواهی‌ای که مرورگر بررسی می‌کند متعلق به edge است.

در CDN.com.tr، گواهی edge توسط Auto SSL مدیریت می‌شود: هر گواهی یک گواهی domain-validated از Let's Encrypt بدون هزینهٔ جدا است. یک hostname را با CNAME به edge اشاره دهید و آن نام گواهی خودش را می‌گیرد، که از طریق HTTP تایید می‌شود. DNS خودتان را به CDN.com.tr delegate کنید و دامنهٔ ریشه یک wildcard می‌گیرد که ریشه و هر زیردامنهٔ سطح اول را پوشش می‌دهد، که با یک رکورد DNS تایید می‌شود. یک گواهی به‌محض تایید دامنه و اشاره‌کردن DNS آن به ما درخواست می‌شود، و 30 روز قبل از انقضا به‌طور خودکار تمدید می‌شود، پس هیچ timer certbotای برای رصد نیست.

دارید یک سایت زنده را منتقل می‌کنید؟ ویزارد zero-downtime wildcard را از طریق یک رکورد TXT در provider DNS فعلی‌تان قبل از سوئیچ صادر می‌کند، خیلی شبیه یک اجرای certbot --manual DNS-01، و مثل آن اجرا، تا وقتی DNS بیرون از CDN.com.tr بماند به‌طور خودکار تمدید نمی‌شود. و اگر یک گواهی OV یا EV از یک CA دیگر دارید، می‌توانید آن را آپلود و به یک hostname وصل کنید؛ همان سیاست TLS گواهی خودکار را می‌گیرد. راهنمای TLS توضیح می‌دهد edge چه چیزی را negotiate می‌کند، و HSTS قدم بعدی است وقتی HTTPS پایدار شد.