Free HTTPS with Let’s Encrypt and certbot

Let’s Encrypt is a free certificate authority. certbot is the client the Electronic Frontier Foundation maintains for it: it proves to Let’s Encrypt that you control the domain, downloads the certificate, and installs a timer that renews it before it expires. Done right, you set it up once and never think about it again.

Before you start

• A domain whose A (and, if you have IPv6, AAAA) record points at this server: dig +short www.example.com must show the server’s public address.
• Port 80 reachable from the internet: Let’s Encrypt connects to it to verify the domain, even if you will only serve HTTPS afterwards. Open it in the host firewall and any cloud security group, and port 443 as well.
• nginx or Apache already answering on port 80 for that name, if you want certbot to configure the web server for you.

1. Install certbot

The project recommends the snap package, which is the same on every distribution and updates itself. Remove any distribution package first so the two do not fight:

sudo apt remove certbot        # Debian / Ubuntu, if an old package is installed
sudo dnf remove certbot        # RHEL family

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

On Debian and Ubuntu, snapd is usually present; on RHEL family install it from EPEL and enable snapd.socket following the snapcraft instructions linked below. If you cannot use snap, the certbot site lists pip-based instructions and the distribution packages, which work the same way but may be older.

2. Get and install the certificate

# nginx: obtain the certificate and edit the nginx config to use it
sudo certbot --nginx -d example.com -d www.example.com

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

certbot asks for an email address for expiry warnings, the terms of service, and whether to redirect HTTP to HTTPS (say yes unless you have a reason not to). It finds the server block or virtual host for the names you listed, adds the ssl_certificate lines and reloads the server. Open https://www.example.com and look at the padlock.

To get only the files and configure the web server, proxy or application yourself:

# the web server keeps running; certbot drops a file into its document root for validation
sudo certbot certonly --webroot -w /var/www/html -d example.com -d www.example.com

# nothing is listening on port 80 yet: certbot runs its own temporary web server
sudo certbot certonly --standalone -d example.com

The files land in /etc/letsencrypt/live/example.com/: fullchain.pem (certificate plus intermediates, what servers should send) and privkey.pem. They are symlinks to the newest version, so point your configuration at these paths and never copy the files elsewhere. The directory is readable by root only; a service running as another user needs either a group permission on /etc/letsencrypt/live and archive, or a deploy hook that copies the files with the right owner.

3. Check that renewal works

The snap installs a systemd timer that runs certbot renew twice a day; it renews anything within 30 days of expiry. Test the whole path without touching the real certificate:

sudo certbot renew --dry-run
systemctl list-timers | grep certbot
sudo certbot certificates          # every certificate, its names and expiry date

When certbot configured nginx or Apache itself, it also reloads them after renewal. For the certonly variants, tell it what to do once a new certificate arrives:

sudo certbot renew --dry-run --deploy-hook "systemctl reload haproxy"

A --deploy-hook passed once is remembered in the certificate’s renewal configuration under /etc/letsencrypt/renewal/, so later automatic renewals run it too. For --standalone renewals the port must be free at renewal time, which is why --webroot is the better choice as soon as a web server exists.

Wildcards and servers without port 80

A wildcard certificate (*.example.com), or a server that cannot expose port 80, needs DNS validation: certbot creates a TXT record at _acme-challenge.example.com through your DNS provider’s API. Install the matching plugin (for example certbot-dns-cloudflare, certbot-dns-route53) as a snap, put the API credentials in a root-only file, and run certbot certonly --dns-cloudflare --dns-cloudflare-credentials /root/.secrets/cloudflare.ini -d '*.example.com' -d example.com. The certbot site has per-provider instructions.

Rate limits and mistakes

• Let’s Encrypt limits how many certificates you can issue for the same names per week. While experimenting add --test-cert (or --dry-run) to use the staging environment, whose certificates are not trusted but do not count.
• Challenge failed with a timeout means port 80 is not reachable from the internet, or DNS still points elsewhere. Fix that, not certbot.
• Moving to a new server: copy the whole /etc/letsencrypt directory, including accounts and renewal, or simply issue fresh certificates there.
• Removing a certificate you no longer need: sudo certbot delete --cert-name example.com, after removing it from the web server configuration.

Official documentation

• certbot: installation instructions per web server and OS
• certbot user guide
• Let’s Encrypt rate limits