Let's Encrypt
certbot, previously known as Let's Encrypt client, is a free, automated, and open certificate authority client.
From the official website: "Anyone who has gone through the trouble of setting up a secure website knows what a hassle getting and maintaining a certificate can be. Let’s Encrypt automates away the pain and lets site operators turn on and manage HTTPS with simple commands."[1]
Preliminary
Point an external IP at HTTP (port 80/TCP) and HTTPS (port 443/TCP) at a web server and setup DNS for it. This is important. You have to prove you own the IP/domain. You could use dynamic DNS if necessary.
Installation
It is helpful to read the official documentation and official installation instructions (select Gentoo from the Operating System dropdown) before proceeding with this article.
certbot
app-crypt/certbot is an easy-to-use automatic client that fetches and deploys SSL/TLS certificates for your web server. Certbot can automatically configure your web server to start serving over HTTPS immediately.
root #emerge --ask app-crypt/certbotcertbot plugins
Certbot also supports numbers of DNS-plugins which automates the process of completing a dns-01 challenge (DNS01) by creating, and subsequently removing, TXT records:
| Name | Package | Description | Documentation | Notes |
|---|---|---|---|---|
| certbot-dns-cloudflare | No | Plugin for Cloudflare API. | doc | Available in GURU repository. |
| certbot-dns-digitalocean | No | Plugin for Digital Ocean API. | doc | |
| certbot-dns-dnsimple | app-crypt/certbot-dns-dnsimple | Plugin for DNSimple API. | doc | |
| certbot-dns-dnsmadeeasy | No | Plugin for DNS Made Easy API. | doc | |
| certbot-dns-gehirn | No | Plugin for Gehirn Infrastructure Service DNS API. | doc | |
| certbot-dns-google | No | Plugin for Google Cloud DNS API. | doc | |
| certbot-dns-linode | No | Plugin for Linode API. | doc | |
| certbot-dns-luadns | No | Plugin for LuaDNS API. | doc | |
| certbot-dns-nsone | app-crypt/certbot-dns-nsone | Plugin for NS1 API. | doc | |
| certbot-dns-ovh | No | Plugin for OVH API. | doc | |
| certbot-dns-rfc2136 | No | Plugin using RFC 2136 Dynamic Updates. | doc | bug #702744. Available in GURU repository. |
| certbot-dns-route53 | No | Plugin for Amazon Web Services Route 53 API. | doc | bug #646298. |
| certbot-dns-sakuracloud | No | Plugin for Sakura Cloud DNS API. | doc |
acme-tiny (optional)
The package is masked by a missing keyword, to unmask it, follow the steps provided here.
app-crypt/acme-tiny is a short, auditable Python script which avoids a lot of the bloat included in the official certbot client:
root #emerge --ask app-crypt/acme-tinyacme.sh (optional)
Another alternative available in Gentoo is the app-crypt/acme-sh client:
root #emerge --ask app-crypt/acme-shConfiguration
certbot
Automatic configuration for existing web server
Run certbot with the corresponding web server plugin and domain. Certbot automatically changes the vhost configuration. For example, for nginx:
root #certbot --nginx -d example.comIn order to use certbot with Apache web server, install the additional plugin:
root #emerge --ask app-crypt/certbot-apacheAutomatic signing with temporary certbox webserver
In this configuration certbot will start a wizard and then initiate up a temporary web server instance in order to generate signed certificates. Choose the second option in the list (2), and follow the wizard. When running an existing web server, first disable the web server before running this mode, then restart the web server when finished (click [Expand] below to see wizard output).
root #rc-service nginx stop
root #certbot certonlySaving debug log to /var/log/letsencrypt/letsencrypt.log How would you like to authenticate with the ACME CA? - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1: Nginx Web Server plugin (nginx) 2: Spin up a temporary webserver (standalone) 3: Place files in webroot directory (webroot) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Select the appropriate number [1-3] then [enter] (press 'c' to cancel): 2 Plugins selected: Authenticator standalone, Installer None Please enter in your domain name(s) (comma and/or space separated) (Enter 'c' to cancel): example.letsencrypt.org Requesting a certificate for example.letsencrypt.org Performing the following challenges: http-01 challenge for example.letsencrypt.org Waiting for verification... Cleaning up challenges IMPORTANT NOTES: - Congratulations! Your certificate and chain have been saved at: /etc/letsencrypt/live/example.letsencrypt.org/fullchain.pem Your key file has been saved at: /etc/letsencrypt/live/example.letsencrypt.org/privkey.pem Your certificate will expire on 2021-07-17. To obtain a new or tweaked version of this certificate in the future, simply run certbot again. To non-interactively renew *all* of your certificates, run "certbot renew" - If you like Certbot, please consider supporting our work by: Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate Donating to EFF: https://eff.org/donate-le
root #rc-service nginx startManual certonly configuration
Run certbot with the corresponding web-server plugin and domain, with the certonly option:
root #certbot --nginx certonly -d example.comConfigure your virtual host. For example, for nginx:
/etc/nginx/vhost.d/example.vhostvhost configurationserver {
listen 80;
server_name example.org;
return 301 https://$host$request_uri;
}
server {
listen 443 default_server ssl;
server_name example.org;
root /var/www/example/htdocs;
ssl_certificate /etc/letsencrypt/live/example.org/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.org/privkey.pem;
location / {
# set nginx configuration
}
}
acme-tiny
The documentation on acme-tiny is the best place to look for the most up to date information, but has been summarized below:
Make a directory for challenges to be created in:
root #mkdir /var/www/localhost/acme-challenge/Add this to the Apache http vhost; IE port 80 vhost:
/etc/apache2/vhosts.d/00_default_vhost.confChallenge alias in ApacheAlias /.well-known/acme-challenge/ /var/www/localhost/acme-challenge/
<Directory /var/www/localhost/acme-challenge/>
AllowOverride None
Require all granted
</Directory>
Set these in the Apache https vhost; IE port 443 vhost:
/etc/apache2/vhosts.d/00_default_ssl_vhost.confSSL certificate settings for ApacheSSLCertificateFile /var/lib/letsencrypt/chained.pem
SSLCertificateKeyFile /var/lib/letsencrypt/domain.key
Make a directory to hold the various files related to LE:
root #mkdir /var/lib/letsencrypt
root #cd /var/lib/letsencrypt
Create an account key, domain key and a CSR (replace www.example.co.uk with your host name):
root #openssl genrsa 4096 > account.key
root #openssl genrsa 4096 > domain.key
root #openssl req -new -sha256 -key domain.key -subj "/CN=www.example.co.uk" > domain.csr
Register and create the certificate file:
acme-tiny may fail its own token availability check [1], even though the token is actually available. If the problem occurs, the check should be disabled using the
--disable-check flag.root #/usr/bin/acme-tiny --account-key ./account.key --csr ./domain.csr --acme-dir /var/www/localhost/acme-challenge/ > ./chained.pem
Reload configs for webserver:
root #service apache2 reloador
root #service nginx reloador
root #service lighttpd reloadSample renewal script:
/usr/bin/local/renew-le-certLetsEncrypt Cert renew script#!/bin/sh
/usr/bin/acme-tiny --account-key /var/lib/letsencrypt/account.key --csr /var/lib/letsencrypt/domain.csr --acme-dir /var/www/localhost/acme-challenge/ > /var/lib/letsencrypt/chained.pem.tmp || exit
mv /var/lib/letsencrypt/chained.pem.tmp /var/lib/letsencrypt/chained.pem
service apache2 reload
Add a monthly cron job:
CRONJOB# Renew Lets Encrypt certificate
0 0 1 * * /usr/local/bin/renew-le-cert.sh 2>> /var/log/acme_tiny.log
Usage
certbot
Invocation
user $certbot --helpletsencrypt [SUBCOMMAND] [options] [-d domain] [-d domain] ...
The Let's Encrypt agent can obtain and install HTTPS/TLS/SSL certificates. By
default, it will attempt to use a webserver both for obtaining and installing
the cert. Major SUBCOMMANDS are:
(default) run Obtain & install a cert in your current webserver
certonly Obtain cert, but do not install it (aka "auth")
install Install a previously obtained cert in a server
revoke Revoke a previously obtained certificate
rollback Rollback server configuration changes made during install
config_changes Show changes made to server config during installation
plugins Display information about installed plugins
Choice of server plugins for obtaining and installing cert:
(the apache plugin is not installed)
--standalone Run a standalone webserver for authentication
(nginx support is experimental, buggy, and not installed by default)
--webroot Place files in a server's webroot folder for authentication
OR use different plugins to obtain (authenticate) the cert and then install it:
--authenticator standalone --installer apache
More detailed help:
-h, --help [topic] print this message, or detailed help on a topic;
the available topics are:
all, automation, paths, security, testing, or any of the subcommands or
plugins (certonly, install, nginx, apache, standalone, webroot, etc)
Renewal
Let's encrypt certificates only last 90 days before expiry, thankfully it is easy to renew certificates: run certbot renew to automatically renew all certbot certificates on the system. It is recommended to run this in a cron command, every 60 days.
To renew just a specific domain, run certbot certonly --force-renew -d example.com.
acmetiny
For those that are not interested in using scripts or want to configure things manually the first time, the author of acme-tiny has provided a webpage that gives step by step instructions along with javascript to help walk you through setting up your certificates. The guide may be found on Get HTTPS for Free website.
See also
- Apache — an efficient, extensible web server. It is one of the most popular web servers used the Internet.
- Nginx — a robust, small, high performance web server and reverse proxy server.
- Lighttpd — a fast and lightweight web server.
External resources
- Manual installation - In the event manual installation is preferred. Note: Portage will not track the installation if the Let's Encrypt is manually installed; this is not recommended by Gentoo developers.