Skip to main content
Mapagam

Working with Let's Encrypt

1. Installing Certbot

Operating System Installation Method Command
Ubuntu/Debian Package Manager sudo apt update && sudo apt install certbot python3-certbot-nginx
CentOS/RHEL/Fedora Package Manager sudo dnf install certbot python3-certbot-nginx
Amazon Linux 2 Package Manager sudo yum install certbot python3-certbot-nginx
Manual Installation Direct Download sudo wget https://dl.eff.org/certbot.tar.gz && tar xzf certbot.tar.gz && cd certbot && sudo python3 -m pip install --editable .

Example: Install Certbot on Ubuntu

sudo apt update
sudo apt install certbot python3-certbot-nginx
Note: Ensure that your firewall allows traffic on port 80 and 443 for the certificate validation process.

2. Generating Certificates

Example: Requesting a certificate using certbot

sudo certbot --nginx -d example.com -d www.example.com
Option Values Description
--nginx true Use the Nginx plugin to automatically configure the server
-d domain.com Domain(s) to request a certificate for
--dry-run true Test the process without actually requesting a certificate
--agree-tos true Agree to the Let's Encrypt Terms of Service
--email admin@example.com Email address for renewal notifications
Note: Certbot will automatically configure Nginx to redirect HTTP traffic to HTTPS.
Warning: Ensure your DNS records are correctly set up before running the command to avoid validation issues.

Summary of Certificate Generation Steps

  • Install Certbot with the Nginx plugin
  • Run the command to request a certificate for your domain(s)
  • Confirm that Nginx is configured to use the certificate
  • Set up automatic renewal using cron or systemd timers

3. Using Webroot Authentication

Directive Description Values Notes
auth_http Specifies the HTTP endpoint for authentication http://localhost:8080/auth Used by nginx to validate requests
auth_timeout Timeout for authentication requests 60s Default is 60 seconds

Example: Webroot Authentication Setup

server {
    listen 80;
    server_name example.com;

    location /.well-known/acme-challenge/ {
        alias /var/www/certs/;
        try_files $uri =404;
    }

    location / {
        auth_request /auth;
        proxy_pass http://backend;
    }

    location = /auth {
        internal;
        proxy_pass http://auth-service/auth;
        proxy_method GET;
        proxy_set_header Host $host;
    }
}
Note: The auth_request module must be enabled in your Nginx build.
Warning: Ensure that /var/www/certs/ is writable by the Nginx user.

4. Using Standalone Mode

Standalone mode is a method for obtaining SSL certificates from Let's Encrypt using the acme.sh client, which runs as a standalone process without requiring a web server to handle the ACME challenges.

Option Values Description
--standalone true Enables standalone mode for certificate issuance.
--keylength 2048, 4096 Specifies the key length for the certificate (2048 or 4096 bits).
--accountkey /path/to/account.key Path to the ACME account key used for authentication.
--domain example.com Domain(s) to issue the certificate for (can be multiple).

Example: Issuing a certificate in standalone mode

acme.sh --issue --standalone -d example.com
Note: In standalone mode, acme.sh starts a temporary HTTP server on port 80 to handle the ACME challenge. Ensure that port 80 is not in use by another service.
Warning: If your server is behind a firewall or NAT, make sure that port 80 is accessible from the internet for the ACME challenge to succeed.

5. Configuring Auto-renewal

Example: Setting up Auto-Renewal with Certbot

sudo crontab -e
Note: Add the following line to your crontab to run renewal twice daily: 
0 12 * * * /usr/bin/certbot renew --quiet
Option Description Default Value
--renew-by-default Renew all certificates that are due false
--quiet Suppress output during renewal false
--dry-run Test renewal without actually renewing false
Warning: Ensure that the renewal command does not conflict with existing cron jobs or systemd timers.

Auto-Renewal Best Practices

  • Set up a daily cron job to check for expiring certificates.
  • Use --dry-run before enabling auto-renewal to test the process.
  • Monitor logs for renewal failures using /var/log/letsencrypt/.

6. Setting Renewal Hooks

Let's Encrypt certificates are valid for 90 days, so renewal is essential. Nginx does not directly handle certificate renewal; it relies on external tools like certbot to manage the process and trigger hooks when renewal occurs.

Hook Type Description Usage
renewal-hook Command to run after a successful renewal certbot renew --renew-hook "/bin/systemctl reload nginx"
deploy-hook Command to run after a certificate is deployed or renewed certbot certonly --deploy-hook "systemctl reload nginx"

Example: Renewal Hook for Nginx Reload

certbot renew --renew-hook "/bin/systemctl reload nginx"
Note: Ensure the hook command has appropriate permissions to execute and reload Nginx without errors.
Warning: If the renewal hook fails, Certbot will still consider the renewal successful but may not update the certificate in Nginx.

7. Managing Multiple Domains

Example: Nginx Configuration for Multiple Domains

# /etc/nginx/sites-available/example.com

server {
    listen 80;
    server_name example.com www.example.com;

    location / {
        root /var/www/example.com;
        index index.html;
    }

    # Redirect HTTP to HTTPS
    location /.well-known/acme-challenge/ {
        alias /var/www/challenges/;
    }
}

server {
    listen 443 ssl http2;
    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;

    location / {
        root /var/www/example.com;
        index index.html;
    }
}
Domain SSL Certificate Path Nginx Server Block Status
example.com /etc/letsencrypt/live/example.com/fullchain.pem server { listen 443 ssl; ... } Active
www.example.com /etc/letsencrypt/live/example.com/fullchain.pem server { listen 443 ssl; ... } Active

Workflow: Adding New Domain to Let's Encrypt

  1. Update DNS records for new domain to point to server IP
  2. Create new Nginx server block with listen 80 and server_name
  3. Run certbot --nginx -d newdomain.com to obtain certificate
  4. Verify SSL config with nginx -t
  5. Reload Nginx: systemctl reload nginx

Summary: Multiple Domains with Let's Encrypt

  • Each domain requires its own server_name in Nginx config
  • Certificates can be shared across domains using certbot --nginx -d domain1.com,domain2.com
  • Use ssl_certificate and ssl_certificate_key to reference certificate files
  • Ensure all domains are accessible via HTTP for ACME challenge validation

8. Using DNS Challenge

Field Description Example
dns_resolver Resolver to use for DNS queries 8.8.8.8
dns_timeout Timeout for DNS queries 30s

Example: DNS Challenge Configuration

server {
    listen 80;
    server_name example.com;

    location /.well-known/acme-challenge/ {
        alias /var/www/challenges/;
        try_files $uri =404;
    }

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

server {
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location /.well-known/acme-challenge/ {
        alias /var/www/challenges/;
        try_files $uri =404;
    }
}
Note: Ensure that your DNS provider supports the required API for DNS challenge automation.
Warning: The dns_resolver must be set to a valid DNS server for the challenge to work correctly.

9. Configuring Certificate Paths

Property Value Description
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem Path to the certificate file for the domain
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem Path to the private key file for the domain
ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem Path to the intermediate certificate file (optional)

Example: Basic SSL Configuration

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    # Optional: Include intermediate certificate
    ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;

    # Other SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
}
Note: Ensure that the paths to the certificate files are correct and accessible by the Nginx process. Let's Encrypt certificates are typically renewed automatically, so paths may change over time.

10. Testing Certificate Renewal

Example: Simulate renewal with certbot

# Test renewal process without actually renewing
sudo certbot renew --dry-run

# Output shows what would happen
# "Renewing" and "reinstalling" are simulated
Option Values Description
--dry-run true Simulates renewal without making changes
--force-renewal false Forces renewal even if not due
--renew-by-default false Renew all certs that are due
Note: The --dry-run flag is essential for testing renewal without affecting production certificates.
Warning: Certificates are only renewed if they are within 30 days of expiration.

Testing Renewal Process

  1. Run certbot renew --dry-run
  2. Verify no errors in output
  3. Check that renewal would proceed normally
  4. Confirm certificate expiration dates remain valid

11. Using Wildcard Certificates

Property Description Notes
*.example.com Wildcard certificate for all subdomains of example.com Must be validated with DNS-01 challenge
certbot --server https://acme-v02.api.letsencrypt.org/directory --agree-tos --authenticator dns-cloudflare --dns-cloudflare-credentials /path/to/cloudflare/credentials.ini --domain '*.example.com' Command to request wildcard certificate Requires DNS provider integration (e.g., Cloudflare)

Example: Requesting Wildcard Certificate

certbot --server https://acme-v02.api.letsencrypt.org/directory \
  --agree-tos \
  --authenticator dns-cloudflare \
  --dns-cloudflare-credentials /path/to/cloudflare/credentials.ini \
  --domain '*.example.com'
Note: DNS-01 challenge required for wildcard certificates.
Warning: Wildcard certificates must be renewed before expiration to avoid service disruption.

12. Revoking Certificates

Command Description Notes
certbot revoke Revoke a certificate issued by Let's Encrypt Must be run on the machine where the certificate was originally obtained

Example: Revoking a Certificate

certbot revoke --cert-path /etc/letsencrypt/live/example.com/fullchain.pem
Note: Revocation is not immediate and may take several hours to propagate.
Warning: Once revoked, a certificate cannot be reissued for the same domain within 90 days.

Was this article helpful?

Related Cheat Sheets