Certbot Commands

Install

Snap is what Certbot's own docs recommend, because it always carries the current release. Distro packages lag behind but update with the rest of the system. The plugin for your web server is a separate package either way.

Without snap, a virtualenv keeps Certbot off the system Python:

sudo python3 -m venv /opt/certbot
sudo /opt/certbot/bin/pip install certbot certbot-nginx
sudo ln -s /opt/certbot/bin/certbot /usr/bin/certbot

A pip or virtualenv install schedules nothing, so add the renewal cron entry yourself. Snap and distro packages both bring their own timer.

nginx

The nginx plugin is the usual route: it proves control of the domain, fetches the certificate, and edits the matching server block in one go. It needs an existing block whose server_name matches, which the nginx config generator can produce.

Confirm the result from outside with the SSL checker.

Apache

Same idea with the Apache plugin. On Debian and Ubuntu the service is apache2; on RHEL and friends it is httpd.

certonly

certonly obtains or renews a certificate without touching any web server config; you point the server at the files yourself. Pick one authenticator per run.

The files land in /etc/letsencrypt/live/<name>/ as fullchain.pem and privkey.pem. Inspect what you got with the certificate decoder or openssl x509 -text from the OpenSSL cheat sheet.

Standalone

Standalone binds its own listener on port 80, so it works on machines with no web server at all: mail servers, database hosts, brokers. Whatever already holds port 80 must stop first.

If a web server owns port 80, stop it around the run and restart it after:

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

Certbot remembers the hooks and reuses them at renewal, so the stop-start happens automatically from then on.

Webroot

Webroot never takes the site down: certbot writes the challenge into .well-known/acme-challenge/ under the directory you name, and Let's Encrypt fetches it over plain HTTP.

One certificate for several sites, each with its own root:

sudo certbot certonly --webroot \
  -w /var/www/html -d example.com -d www.example.com \
  -w /var/www/blog -d blog.example.com

The path must be served over HTTP without a redirect to somewhere the challenge is not. A 404 on /.well-known/acme-challenge/... during the run means -w points at the wrong directory.

DNS Challenge

The dns-01 challenge proves control with a TXT record, so it needs no open port at all, works behind a CDN, and is the only challenge that can issue wildcards.

Manual, for a one-off certificate:

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

Certbot prints the TXT value, you add it at your DNS host, wait for it to propagate, and press Enter. A manual certificate cannot renew unattended unless you also supply --manual-auth-hook.

Automated, with a provider plugin and an API credentials file (chmod 600):

sudo certbot certonly --dns-cloudflare \
  --dns-cloudflare-credentials ~/.secrets/cloudflare.ini \
  -d example.com

Slow DNS host? Add --dns-cloudflare-propagation-seconds 60 (each plugin has its own version of the flag).

Every plugin follows the same three-part pattern: a package, a --dns-<provider> flag, and a credentials file.

Registrars with no official plugin, GoDaddy, Namecheap and Porkbun among them, have community plugins on PyPI, or you can delegate _acme-challenge with a CNAME to a provider that does have one.

Wildcard Certificates

Wildcards come only from the DNS challenge above.

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

• Quote *.example.com so the shell does not try to expand it.
• Include the bare domain: *.example.com does not cover example.com.
• A wildcard covers one level only: app.example.com yes, a.b.example.com no.
• For automatic renewal, use a DNS plugin instead of --manual.

Renewal

Packaged installs (snap, apt, dnf) add a systemd timer or cron job that runs certbot renew twice a day. Each certificate renews once it is within 30 days of expiry, reusing the exact options it was created with, so you never repeat --nginx or -w.

The timer is a normal systemd unit, so the systemctl cheat sheet applies if it is missing or dead.

Add and Remove Domains

There is no "add domain" subcommand. You reissue the certificate with the full list of names you want and pin --cert-name so it replaces the existing one instead of creating a second certificate under a new directory.

Get the current name list before you edit it, since leaving a domain out of the reissue removes it:

sudo certbot certificates --cert-name example.com

The live directory keeps its original name, so /etc/letsencrypt/live/example.com/ stays correct in nginx or Apache no matter which domains you add.

List and Delete

delete does not touch your web server config. Remove the ssl_certificate lines that point at the deleted files first, or nginx refuses to start on the next reload.

Deploy Hooks

Nginx and Apache load certificate files at startup and never look again, so a renewed file on disk changes nothing until a reload. A deploy hook runs after each successful issue or renewal, which is exactly the moment for it.

Add a hook to an existing certificate without reissuing it:

sudo certbot reconfigure --cert-name example.com \
  --deploy-hook "systemctl reload nginx"

Files and Logs

Everything Certbot owns lives under /etc/letsencrypt/, and every run appends to one log file. That log carries the real ACME error text, which is usually far more specific than what the terminal printed.

Back up /etc/letsencrypt/ as a whole, with symlinks preserved (tar -czphf), or the restored copy points nowhere. See the tar cheat sheet.

Windows

Certbot no longer ships a native Windows build; EFF stopped producing the Windows installer during the 2.x series, and the old beta .exe downloads are unsupported. Three options remain.

IIS wants a .pfx, not the .pem pair, so convert with openssl pkcs12 -export -out cert.pfx -inkey privkey.pem -in fullchain.pem from the OpenSSL cheat sheet.

Account and Version

Docker

The official image is certbot/certbot, and its entrypoint is certbot itself, so everything after the image name is a normal certbot command. Mount /etc/letsencrypt or the certificates die with the container.

docker run -it --rm -p 80:80 \
  -v /etc/letsencrypt:/etc/letsencrypt \
  certbot/certbot certonly --standalone -d example.com

Renewal is the same image with renew; there is no timer inside a container, so schedule it yourself from host cron:

docker run --rm -p 80:80 \
  -v /etc/letsencrypt:/etc/letsencrypt \
  certbot/certbot renew

For webroot next to an nginx container, mount the same volume in both containers as the challenge directory. Docker basics are on the Docker cheat sheet.

Command Line Options

Gotchas

• Let's Encrypt rate limits are real: five identical certificates per week. Test with --dry-run or --staging, and never put --force-renewal in cron.
• After a certonly renewal your server still serves the old certificate until it reloads. If the SSL checker shows an expired certificate but certbot certificates shows a fresh one, the missing piece is a deploy hook.
• Everything in /etc/letsencrypt/live/ is a symlink. Point your config there and never copy the files out; copies stop updating.
• The HTTP challenge needs port 80 reachable from the internet. A closed firewall gives "Timeout during connect"; open it with ufw allow 80/tcp (UFW cheat sheet) and confirm from outside with the port checker. Behind Cloudflare or another CDN, use the DNS challenge instead.
• Failed validations have their own limit, five per account, hostname and hour. Retrying a broken challenge in a loop earns "too many failed authorizations recently" and an hour of lockout, so read /var/log/letsencrypt/letsencrypt.log and fix the cause between attempts.
• certbot-auto and letsencrypt-auto are long dead. Install from your package manager or snap (sudo snap install --classic certbot).