How to manage Let's Encrypt SSL/TLS certificates with certbot
Let's Encrypt is an automated and open certificate authority (CA) operated by the Internet Security Research Group (ISRG) and founded by the Electronic Frontier Foundation (EFF), the Mozilla Foundation, and others. It provides free SSL/TLS certificates which are commonly used to encrypt communications for security and privacy purposes, the most notable use case being HTTPS. Let's Encrypt relies on the ACME (Automatic Certificate Management Environment) protocol to issue, revoke and renew certificates. Certbot is a free and open-source utility mainly used for managing SSL/TLS certificates from the Let's Encrypt certificate authority. It is available for most UNIX and UNIX-like operating systems, including GNU/Linux, FreeBSD, OpenBSD and OS X. This guide will provide a platform-agnostic introduction to the usage of certbot.
NOTE: As certbot is a work in progress, some features or behaviors described in this guide might differ in older or future releases.
Requirements
- A registered domain name with an A record pointing to your IPv4 address. `www.example.com` will be used as an example.
- Access to a privileged shell.
General Concepts
Operation Modes
Using certbot to enable HTTPS can be divided in two parts: Authentication and Installation. The first requires solving a challenge and saving the certificate and other files. The installation step involves configuring and securing the web server. Certbot can automatically perform both, with the run subcommand. The certonly and install subcommands are for the authentication and installation steps respectively.
Certbot also includes certificate renewal and revocation features.
Challenges
Obtaining a Let's Encrypt certificate involves solving a domain validation challenge issued by an ACME (Automatic Certificate Management Environment) server. This challenge verifies your ownership of the domain(s) you're trying to obtain a certificate for. Different challenge types exist, the most commonly used being HTTP-01. As its name suggests, it uses the HTTP protocol. While HTTP servers can be configured to use any TCP port, this challenge will only work on port 80 due to security measures. DNS-01 is another, less popular challenge type based on DNS resolution. Note that wildcard certificates are not obtainable through the HTTP-01 challenge. This guide will initially focus on HTTP-01.
Plugins
Certbot relies on plugins to perform authentication and installation. Plugins such as webroot and standalone only perform authentication, while others such as the Apache and Nginx plugins are designed to automatically obtain and install certificates (i.e. web server configuration). Other plugins include several vendor-specific DNS plugins for DNS-01 authentication. Most certbot plugins are installed separately, except the webroot and standalone plugins which are built-in.
Installing Certbot
Most Linux distributions provide certbot in their official repositories. Below are installation instructions for widely-used platforms.
Debian and Ubuntu:
apt update
apt install -y certbot
CentOS 7:
yum install -y certbot
Fedora and CentOS 8:
dnf install -y certbot
Arch Linux:
pacman -Sy certbot
FreeBSD:
pkg install py36-certbot
OpenBSD 6.0 and later:
pkg_add certbot
MacOS (homebrew required):
brew install letsencrypt
Other:
If a certbot package is not available for your platform, you can use the official certbot-auto wrapper script to install certbot automatically on your system. It can be downloaded here.
Using Certbot
Listing Certificates
To display a list of the certificates managed by certbot on your server, issue the command:
certbot certificates
Obtaining A Certificate For Manual Configuration
If you choose to manually configure your web server, obtaining a certificate can be done in two ways. Either by giving certbot access to the web root directory of your server (i.e the webroot plugin), or by deploying a temporary standalone web server on port 80 (i.e. the standalone plugin). The latter plugin is useful in cases where integration with your existing web server is impossible or not desired. For convenience and simpler renewals, be consistent with the plugin used.
Using an existing web server
To use your existing web server, make sure it is running and listening on port 80 before executing the following command
certbot certonly --webroot
You will be prompted to enter, among other information, your domain name(s) and the path to your webroot, which is `/var/www/html/` by default on most Linux systems. Alternatively, you may specify the required information as command arguments. For example:
certbot certonly --webroot --webroot-path /var/www/html --agree-tos -m [email protected] -d www.example.com
Using the standalone web server
In order to use the standalone server, first ensure the availability of port 80. You can check for any processes binding to that port using:
ss -lntp 'sport = 80'
If needed, stop the offending service/process before proceeding. Then, issue the command:
certbot certonly --standalone
Once the certificate is issued, you will need to configure your web server manually. The relevant files can be found in /etc/letsencrypt/live/your_domain.
Interactive HTTPS Installation
As mentioned previously, certbot can automate the whole HTTPS setup process, including web server configuration. Plugins are available for both Apache and Nginx, and may need to be installed as a separate package. Install the certbot plugin specific to your web server, then execute `certbot run --PLUGIN_NAME`. We'll demonstrate the whole process for Apache on a Debian 10 system. The process for Nginx is similar.
apt install -y python-certbot-apache certbot run --apache
Assuming your web server is already configured for your domain name(s), certbot will parse the existing configuration and prompt you to choose which domain name(s) HTTPS should be activated for. If your web server is not configured, or if certbot fails to detect your domain name(s), simply enter your domain name(s) manually when prompted. For example:
Which names would you like to activate HTTPS for?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: www.example.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate numbers separated by commas and/or spaces, or leave input
blank to select all options shown (Enter 'c' to cancel): 1
Certbot will create a new Apache configuration file for your new HTTPS virtual host, and will ask whether HTTP traffic should be redirected to HTTPS. Unless you have strong reasons not to, you should enable redirection to HTTPS.
Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1: No redirect - Make no further changes to the webserver configuration. 2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for new sites, or if you're confident your site works on HTTPS. You can undo this change by editing your web server's configuration. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2 Enabled Apache rewrite module Redirecting vhost in /etc/apache2/sites-enabled/www.example.com.conf to ssl vhost in /etc/apache2/sites-available/www.example.com-le-ssl.conf - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Congratulations! You have successfully enabled https://www.example.com
Renewing certificates
Manual Renewal
To renew your certificates with certbot, you can use the renew subcommand. During renewal, certbot will use the same plugins and options used for the original issuance. Certificates are only renewed if they expire in less than 30 days, so this subcommand can be used as frequently as desired, as it will take no action if the certificates aren't near their expiry date. The command is simply:
certbot renew
If the standalone plugin was used to issue a certificate, you will need to stop your web server in order for renewal to succeed. You can accomplish that using hooks. For example, if the system runs Apache, the command would be:
certbot renew --pre-hook "systemctl stop apache2.service" --post-hook "systemctl start apache2.service"
Automatic Renewal
Many distributions have enabled automatic renewals by default, either via systemd timers or cron jobs. You can check for systemd timers with:
systemctl list-timers
And for cron jobs using:
ls /etc/cron*
If the webroot plugin was used for issuance, automated renewals should succeed as long as your web server is running. With the standalone plugin, however, the default automated renewal command will fail in case a web server is running, as certbot will not be able to bind to port 80. Modifying it with the addition of hooks, as shown above, is hence required.
Revoking Certificates
Revoking a certificate can be achieved by specifying the certificate path or name:
certbot revoke --cert-name cert_name (OR) certbot revoke --cert-path /path/to/cert.pem
For example:
certbot revoke --cert-name www.example.net
After running the revoke subcommand, certbot will ask whether certificate files should be deleted. If you choose not to delete them, the revoked certificate will be renewed during the next renewal occurrence. Several self-explanatory options can be passed to the revoke subcommand:
- --delete-after-revoke (prompts for user choice by default)
- --no-delete-after-revoke (prompts for user choice by default)
- --reason [unspecified,keycompromise,affiliationchanged,superseded,cessationofoperation] (Default: unspecified)
Wildcard Certificates
A single wildcard certificate can be used to identify multiple subdomains, as an alternative to separate regular certificates. To obtain a wildcard certificate, the DNS-01 challenge must be used. While several vendor-specific plugins that automate the ACME authentication process are available, we will explain the manual, vendor-neutral process. Access to the nameservers for your domain is needed.
Use the following command to request a wildcard certificate:
certbot certonly --manual --preferred-challenges dns-01 -d *.example.net
Certbot will display a value which should be deployed in a DNS TXT record. This TXT record serves as the necessary ownership validation.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Please deploy a DNS TXT record under the name _acme-challenge.example.net with the following value: y77OkxXi89sJLjUgYu-HReYrcVlxt_bfG8yVOVKngBOcU Before continuing, verify the record is deployed. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Press Enter to Continue
You will need to create the specified record in your DNS control panel before proceeding. Once the record is created, wait a few minutes before pressing Enter, which triggers the ACME server to verify it. In some cases, a longer wait time might be required for the new record to properly propagate and be accessible. Upon success, the certificate, chain and private key will be saved under /etc/letsencrypt/live/example.com/.
