Certbot Lets Encrypt

Certbot cheatsheet — obtain and renew Let's Encrypt SSL certificates. certbot --nginx, certbot certonly, certbot renew --dry-run. Free HTTPS for any domain.

7 min read

What it is

Certbot is an automated client for Let’s Encrypt, a free, automated, and open certificate authority, that can obtain, install, and renew TLS/SSL certificates for your web server.

Installation

Debian/Ubuntu

sudo apt update
sudo apt install certbot python3-certbot-apache
# or for Nginx
sudo apt install certbot python3-certbot-nginx

Fedora

sudo dnf install certbot python3-certbot-apache
# or for Nginx
sudo dnf install certbot python3-certbot-nginx

CentOS/RHEL

sudo yum install epel-release
sudo yum install certbot python3-certbot-apache
# or for Nginx
sudo yum install certbot python3-certbot-nginx

macOS

Using Homebrew:

brew install certbot

Windows

Download the Windows executable from the Certbot website: https://certbot.eff.org/instructions

Core Concepts

  • Let’s Encrypt: A free, automated, and open certificate authority. It issues short-lived certificates (90 days).
  • ACME Protocol: The protocol used by Certbot to communicate with Let’s Encrypt servers to obtain and manage certificates.
  • Challenges (HTTP-01, DNS-01): Methods Let’s Encrypt uses to verify that you control the domain for which you are requesting a certificate.
    • HTTP-01: Certbot places a file on your web server that Let’s Encrypt’s servers then fetch to verify ownership. This requires your web server to be running and accessible from the internet on port 80.
    • DNS-01: You are asked to create a specific TXT record in your domain’s DNS zone. This is useful if you don’t have a public web server or want to automate certificate issuance without web server interaction.
  • Plugins: Certbot uses plugins to interact with your web server (e.g., apache, nginx) or to handle DNS challenges (dns_cloudflare, dns_route53).

Commands / Usage

Obtaining Certificates

For Apache (automatic installation):

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

Obtains and installs a certificate for example.com and www.example.com using the Apache plugin. Certbot will attempt to modify your Apache configuration.

For Nginx (automatic installation):

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

Obtains and installs a certificate for example.com and www.example.com using the Nginx plugin. Certbot will attempt to modify your Nginx configuration.

Standalone (temporary web server):

sudo certbot certonly --standalone -d example.com

Obtains a certificate for example.com using the standalone plugin (which temporarily runs its own web server on port 80). The certificate files will be placed in /etc/letsencrypt/live/example.com/. You’ll need to configure your web server manually.

Webroot (using existing web server):

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

Obtains a certificate for example.com and www.example.com using the webroot plugin. It uses your existing web server and places challenge files in the specified webroot directory (/var/www/html).

DNS Challenge (e.g., with Cloudflare):

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini \
  -d example.com -d www.example.com

Obtains a certificate using the DNS-01 challenge with Cloudflare. You’ll need to create a cloudflare.ini file with your API credentials.

Managing Certificates

List all certificates:

sudo certbot certificates

Shows information about all certificates managed by Certbot, including expiry dates and paths to certificate files.

Renew certificates:

sudo certbot renew

Checks all certificates and renews any that are close to expiring (typically within 30 days of expiry). This command is often run automatically by a cron job or systemd timer.

Dry run for renewal:

sudo certbot renew --dry-run

Tests the renewal process without actually renewing any certificates. Useful for troubleshooting.

Revoke a certificate:

sudo certbot revoke --cert-path /etc/letsencrypt/live/example.com/cert.pem

Revokes the specified certificate with Let’s Encrypt.

Advanced Options

Specify email for notifications:

sudo certbot --apache -d example.com --email admin@example.com

Provides an email address for important renewal and security notices.

Agree to terms of service (non-interactive):

sudo certbot --apache -d example.com --agree-tos

Skips the interactive prompt to agree to the Let’s Encrypt Terms of Service. Use with caution.

Specify authentication domain (useful for multiple domains on one IP):

sudo certbot --apache -d example.com -d www.example.com --apache-server-root /etc/apache2

Specifies the Apache server root directory. Useful if running multiple Apache instances or non-standard configurations.

Request a specific challenge type:

sudo certbot certonly --webroot -w /var/www/html -d example.com --preferred-challenges http

Explicitly requests the HTTP-01 challenge. You can also use dns.

Set certificate validity period (for testing, not recommended for production):

sudo certbot certonly --standalone -d example.com --test-cert

Requests a certificate from the Let’s Encrypt staging environment, which issues short-lived test certificates. This is useful for testing your setup without consuming Let’s Encrypt rate limits.

Reinstalling certificates (e.g., after web server upgrade):

sudo certbot reinstall --cert-path /etc/letsencrypt/live/example.com/cert.pem --apache

Reinstalls the specified certificate using the Apache plugin. Useful if your web server configuration has changed significantly.

Delete a certificate:

sudo certbot delete --cert-path /etc/letsencrypt/live/example.com/cert.pem

Removes certificate files and associated configurations from Certbot’s management.

Common Patterns

Automated Renewal Setup (Systemd): Most Linux distributions install a systemd timer or cron job automatically. You can check its status:

sudo systemctl status certbot.timer
# or
sudo systemctl list-timers | grep certbot

If it’s not set up, you can create a systemd timer unit file (e.g., /etc/systemd/system/certbot-renew.timer) and enable it:

[Unit]
Description=Run certbot renew weekly

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target

Then enable and start:

sudo systemctl enable certbot-renew.timer
sudo systemctl start certbot-renew.timer

Securing a new domain with Nginx:

  1. Create an Nginx server block for your domain.
  2. Obtain the certificate:
    sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
  3. Certbot will likely ask if you want to redirect HTTP traffic to HTTPS. Choose '2' for redirection.

Using DNS challenge with AWS Route 53:

  1. Install the Route 53 plugin: pip install certbot-dns-route53 (or use your distro’s package manager).
  2. Create AWS credentials file (~/.aws/credentials or /etc/letsencrypt/route53.ini):
    [default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY
  3. Run Certbot:
    sudo certbot certonly \
  --dns-route53 \
  --dns-route53-credentials /etc/letsencrypt/route53.ini \
  -d example.com -d www.example.com

Getting a certificate without modifying web server config:

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

This obtains the certificate and places it in /etc/letsencrypt/live/example.com/. You’ll then manually configure your web server (Apache, Nginx, Caddy, etc.) to use these certificate files.

Gotchas

  • Rate Limits: Let’s Encrypt has rate limits on certificate issuance. Using --test-cert or --dry-run is crucial for testing to avoid hitting these limits.
  • Port 80/443: The HTTP-01 challenge requires your web server to be accessible on port 80 (or port 443 if using TLS-ALPN-01). If another process is using it, or if a firewall blocks it, challenges will fail.
  • Webroot Path: Ensure the -w path for the --webroot plugin points to the actual document root of your web server where it serves files for the domain. If it’s incorrect, the challenge file won’t be found.
  • Reloading Web Server: After Certbot automatically installs certificates (using --apache or --nginx), it usually reloads your web server. If this fails, you might need to manually reload it (e.g., sudo systemctl reload apache2).
  • Wildcard Certificates: Wildcard certificates (*.example.com) can only be obtained using the DNS-01 challenge. The HTTP-01 challenge is not supported for wildcards.
  • Certificate Expiry: Certificates are valid for only 90 days. Ensure your certbot renew cron job or systemd timer is correctly set up and running. Check logs in /var/log/letsencrypt/.
  • Plugin Dependencies: Some DNS plugins might require additional installation steps (e.g., pip install certbot-dns-cloudflare).
  • Permissions: Certbot needs read/write access to /etc/letsencrypt and potentially your web server’s configuration files and document roots. Run commands with sudo.
  • Multiple Domains on One IP: When obtaining certificates for multiple domains hosted on the same IP address, ensure your web server is configured to respond correctly for each domain before running Certbot with the --apache or --nginx plugins, or use the --webroot plugin with appropriate -w flags for each domain.