Let & # 39; s Encrypt is an automated and open certificate authority (CA) run by the Internet Security Research Group (ISRG) and founded by the Electronic Frontier Foundation (EFF), 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 case being HTTPS. Let's encrypt relies on the Automatic Certificate Management Environment (ACME) protocol to issue, revoke, and renew certificates. Certbot is a free and open source tool that is mainly used to manage SSL / TLS certificates from the certificate authority Let & # 39; s Encrypt . 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 use of certbot.
NOTE: As certbot is an ongoing work, some features or behaviors described in this guide may vary in older or future editions.
- 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.
Using certbot to enable HTTPS can be divided into two parts: Authentication and Installation. The first requires that you solve a challenge and save the certificate and other files. The installation step involves configuring and securing the web server. Certbot can automatically execute both with the sub command . The subcommands certonly and are for the authentication and installation steps.
Certbot also includes certificate prevention and recall features.
Obtaining an Let & # 39; s Encrypt certificate involves solving a domain validation challenge issued by an Automatic Certificate Management Environment (ACME) server. This challenge verifies your ownership of the domain (s) you are trying to get a certificate for. Various types of challenges exist, the most commonly used being HTTP-01
Certbot relies on plugins to perform authentication and installation. Plugins like webroot and standalone perform only authentication, while others like Apache and Nginx plugins are designed to automatically obtain and install certificates (ie, web server configuration). Other plugins include several vendor-specific DNS plugins for DNS-01 authentication. Most certbot plugins are installed separately, except for webroot and standalone plugins that are built-in.
Most Linux distributions contain certbot in their official repositories. Below are installation instructions for commonly used platforms.
Debian and Ubuntu:
apt install -y certbot
yum install -y certbot
Fedora and CentOS 8:
dnf install -y certbot
pacman -Sy certbot
pkg install py36-certbot
OpenBSD 6.0 and later:
MacOS (homebrew required) :
brew install letsencrypt
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.
To view a list of certificates managed by certbot on your server, issue the command:
Obtaining a certificate for manual configuration
If you If you choose to manually configure your web server, you can get a certificate in two ways. Either by granting certbot access to the web directory of your server (ie the webbrot plugin), or by distributing a temporary standalone web server on port 80 (ie the standalone plugin). The latter plugin is useful in cases where integration with your existing web server is impossible or not desired. For simplicity and simplified renewals, follow 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 running the following command
certbot certonly --webroot
You will be asked 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 can enter the desired information as a command argument. For example:
certbot certonly --webroot --webroot-path / var / www / html --agree-tos -m [email protected] -d www.example.com
Using the standalone web server
To use the standalone server, you must first make sure port 80 is available. You can check if processes that are binding for that port use:
ss - lntp & # 39; sport = 80 & # 39;
Stop the offending service / process if needed before proceeding. Then issue the command:
certbot certonly - standalone
Once the certificate has been issued, you must configure your web server manually. The relevant files can be found in / etc / letsencrypt / live / your_domain .
Interactive HTTPS Installation
As previously mentioned, certbot can automate the entire HTTPS installation 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 and then run "certbot run –PLUGIN_NAME". We demonstrate the entire process for Apache on a Debian 10 system. The process for Nginx is similar.
apt install -y python-certbot-apache certbot run --apache
Provided that your web server is already configured for your domain names, certbot will analyze the existing configuration and prompt you to choose which domain name HTTPS should be enabled for. If your web server is not configured or if certbot fails to detect your domain names, you only enter your domain name manually when prompted to do so. For example:
What names do you want to enable HTTPS for?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: www.example. com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select appropriate numbers separated by comma and / or space, or leave input
blank to select all displayed options (enter & # 39; c & # 39; to cancel): 1
Certbot creates a new Apache configuration file for your new virtual HTTPS hosts and asks if HTTP traffic should be redirected to HTTPS. If you do not have strong reasons for this, you should enable redirection to HTTPS.
Please select whether you want to redirect HTTP traffic to HTTPS or remove HTTP access. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1: No Redirect - Make no further changes to the web server configuration. 2: Redirect - Makes all requests redirect to secure HTTPS access. Select this for new websites, or if you are sure your site is working on HTTPS. You can undo this change by editing your web server configuration. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Select the appropriate number [1-2] and then [enter] (press & # 39; c & # 39; to cancel): 2 Activated module for rewriting Apache Redirect 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 enabled https://www.example.com
To renew your certificates with certbot, you can use the sub-command renew . During renewal, certbot will use the same plugins and options used for the original issue. Certificates are renewed only if they expire in less than 30 days, so this subcommand can be used as often as desired, as no action will be taken if the certificates are not close to their expiration date. The command is simply:
If the standalone plugin was used to issue a certificate, you must stop your web server for renewal to succeed. You can achieve it with hooks. For example, if the system is running Apache, the command would be:
certbot renew - pre-hook "systemctl stop apache2.service" --post-hook "systemctl start apache2.service"
Many distributions have enabled automatic renewals by default, either via systemd timers or cron jobs. You can search for systemd timers with:
And for cron jobs with:
ls / etc / cron *
If the webroot plugin was used for issuing, automated renewals should succeed as long as your web server is running. However, with the standalone plugin, the automatic renewal command will default if a web server is run, as certbot will not be able to bind to port 80. It is therefore necessary to change it with the addition of hooks.
Revocation of a certificate can be obtained by specifying the certificate path or name:
revoke certificate - certificate name cert_name (OR) revoke certbot - cert-path /path/to/cert.pem
certbot revoke - cert-name www.example.net
After running the subcommand revoke certbot will ask if certificate files should be removed. If you choose not to delete them, the revoked certificate will be renewed during the next renewal process. Several self-explanatory options can be forwarded to the recall subcommand:
- – delete-after-revoke (user selection prompts by default)
- – no-delete-after-revoke (user selection prompts by default)
- – reason [unspecified,keycompromise,affiliationchanged,superseded,cessationofoperation] (Default: unspecified)
A single wildcard certificate can be used to identify multiple subdomains, as an option to separate common certificates. To obtain a wildcard certificate, the challenge DNS-01 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 name servers for your domain is needed.
Use the following command to request a wildcard certificate:
certbot certonly - manual - lecture-challenges dns-01 -d * .example.net
Certbot displays a value that should be distributed in a DNS TXT record. This TXT record serves as necessary owner validation.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Distribute a DNS TXT record under the name _acme-challenge.example.net with the following value: y77OkxXi89sJLjUgYu-HReYrcVlxt_bfG8yVOVKngBOcU Before proceeding, make sure the record is placed. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Press Enter to continue
You must create the specified entry 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, longer waiting times may be required for the new item to be distributed and available. After success, the certificate, chain and private key will be saved under /etc/letsencrypt/live/example.com /.
References and Additional Information