Faruque Ahmed : MCP, MCSA, MCSE, MCTS, MCIT, CCNA, OCA, OCP, GCP
LL
Certbot is a free and open source ACME (Automatic Certificate Management Environment) client created by the Electronic Frontier Foundation; we can use it to talk to Let’s Encrypt to obtain a valid SSL/TLS certificate and secure our website. Certbot is written in Python (source code is available on GitHub), and it is included in the official repositories of many Linux distributions. To install it on Debian and Debian-based systems, we can run:
$ sudo apt install certbot
To perform the installation on Fedora, instead, we use dnf:
$ sudo dnf install certbot
Unfortunately Certbot is not officially available on Red Hat Enterprise Linux and its clones (e.g Rocky Linux). On those systems, however, we can install it (with the same command we used on Fedora), once we add the EPEL repository as a software source.
As an alternative, we can install Certbot directly with pip, the Python package manager. We should avoid running pip as root, therefore we should install the package as an unprivileged user:
$ pip install certbot
The most basic way we can use Certbot, is by invoking it with the certonly subcommand. When this subcommand is used, Certbot just tries to obtain a certificate, without creating any webserver-specific configuration:
$ sudo certbot certonly
Once we run the command, Certbot asks us how we want to authenticate with the Certificate Authority. We can choose to spin-up a temporary web server, or place files created during the authentication process in an existing webroot directory. What we want to use depends on whether we have a web server already up and running. If it is not the case, we want to go for the former option, otherwise for the latter. In this case, for the sake of simplicity, we use option 1:
How would you like to authenticate with the ACME CA?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: Spin up a temporary webserver (standalone)
2: Place files in webroot directory (webroot)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 1
After we select the authentication method, Certbot will ask us to provide the email address where we want to receive renewal and security notices. Just for the sake of this article, I will use a dummy one:
Enter email address (used for urgent renewal and security notices)
(Enter 'c' to cancel): mymail@provider.com
Before we can procede further, we need to read and accept Let’s Encrypt Terms of Services:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.3-September-21-2022.pdf. You must
agree in order to register with the ACME server. Do you agree?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y
We can decide if we want to allow the Electronic Frontier Foundation to send us emails about news, future initiatives and campaigns:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing, once your first certificate is successfully issued, to
share your email address with the Electronic Frontier Foundation, a founding
partner of the Let's Encrypt project and the non-profit organization that
develops Certbot? We'd like to send you email about our work encrypting the web,
EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: n
As a last step, we need to enter the domain we want to obtain a certificate for:
Please enter the domain name(s) you would like on your certificate (comma and/or
space separated) (Enter 'c' to cancel): mydomain.com
Certbot will let us know if it was able to obtain a certificate:
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/mydomain.com/fullchain.pem
Key is saved at: /etc/letsencrypt/live/mydomain.com/privkey.pem
This certificate expires on 2024-06-26.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.
The output includes information about the path where the certificate was saved and its expiry date. Existing certificates are automatically renewed by a task scheduled with a systemd.timer (/usr/lib/sytemd/system/certbot.timer) which runs twice a day. Please notice that it is possibile to perform a limited number of requests to Let’s Encrypt during a specific interval of time, therefore, if you feel like you want to experiment with Certbot, you should use the --dry-run option when possible.
Once we know the location of the certificate and the private key, we can modify our web server configuration accordingly. If we don’t want to perform the configuration manually, however, we can instruct Certbot to do it for us. Let’s see how.
In order to use the certificate we just obtained from Let’s Encrypt, our web server needs to know its location. We can modify the server configuration with the required directives manually, or, if we need to automate the process, we can let Certbot do it for us. Certbot is able to automatically create configurations for Apache and Nginx, thanks to dedicated plugins. To install them on Debian, and Debian-based systems, we run:
$ sudo apt install python3-certbot-apache python3-certbot-nginx
On Fedora-based systems, instead:
$ sudo dnf install python3-certbot-apache python3-certbot-nginx
Once the packages are installed, to let Certbot configure our web server, we can use the --apache or --nginx options. To retrieve a certificate and automatically create an Apache configuration, for, example, we would run:
$ sudo certbot --apache
The Apache configuration, on Debian systems, is stored as /etc/apache2/sites-available/000-default-le-ssl.conf. Among the others, it contains the following directives:
ServerName mydomain.com
SSLCertificateFile /etc/letsencrypt/live/mydomain.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/mydomain.com/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
In the previous examples, we ran Certbot interactively. Sometimes, however, user interaction is not possible, therefore we must run Certbot unattended, providing requested information via the appropriate flags. In the example below, we try to retrieve a certificate for the “mydomain.com” domain, spawning an ad-hoc web server for authentication:
$ sudo certbot certonly \
--non-interactive \
--standalone \
--email mymail@provider.com \
--agree-tos \
--no-eff-email \
--domains mydomain.com
The first option we used is --non-interactive: it instructs Certbot to run without ever asking for the user input, which is exactly what we want to achieve. With the --standalone option we specified we want to launch a web server and use it for authentication.
We provided the email address we want to use as argument to the --email option, and we used --agree-tos to agree to Let’s Encrypt terms and conditions. Furthermore, we specified we don’t want to share our address with the EFF via the --no-eff-mail option. Finally, we passed the domain we want to retrieve the certificate for, as argument to --domains.
What if we want to make Certbot additionally create an Apache configuration? All we need to do is to add the --installer option and pass the name of the plugin which should be used, as argument:
$ sudo certbot \
--non-interactive \
--standalone \
--email mymail@provider.com \
--agree-tos \
--no-eff-email \
--domains mydomain.com \
--installer apache
To display information about the certificates we obtained with certbot, we can use the certificates command:
$ sudo certbot certificates
If a certificate has almost reached its expiry date, and we want to renew it immediately, without relying on the scheduled task, we can use the renew command. All the certificates we previously obtained with Certbot will be renewed:
$ sudo certbot renew
To revoke a certificate, instead, we can use the revoke command. A certificate can be referenced by name or by path, with the --cert-name and --cert-path options, respectively. In the example below we revoke the certificate named “mydomain.com”:
$ sudo certbot revoke --cert-name mydomain.com
Finally, to delete a certificate we use the delete command:
$ sudo certbot delete --cert-name mydomain.com
We can use Certbot to manage our ACME account. To display information about an account, we use the show_account command:
$ sudo certbot show_account
The command returns information like the account URL and associated email:
Account details for server https://acme-v02.api.letsencrypt.org/directory:
Account URL: https://acme-v02.api.letsencrypt.org/acme/acct/0000000000
Email contact: mymail@provider.com
To unregister an account, we can use the unregister command:
$ sudo certbot unregister
We will be prompted to confirm we want to deactivate our account:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Are you sure you would like to irrevocably deactivate your account?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(D)eactivate/(A)bort:
Finally, to register a new account, we use the register command, and provide required information, either interactively or via dedicated options, e.g:
$ sudo certbot register --email mymail@provider.com --agree-tos --no-eff-email
Registering an account explicitly is usually not needed, since it is created on the fly the first time we use Certbot, as we saw in previous examples.
LL