Let’s Encrypt
Let’s Encrypt is a free, automated, and open certificate authority utilizing the ACME protocol.
The official client is called Certbot, which allows to request valid X.509 certificates straight from the command line. A minimal client with manual CSR creation is available at acme-tinyAUR. More integrated clients suitable for scripts are e.g. simp_le-gitAUR and letsencrypt-cliAUR.
Contents
Certbot
Certbot, previously called the Let’s Encrypt client, is the official reference client. It is written in Python and provides a command-line tool to obtain certificates.
Installation
Plugins are available for automated configuration and installation of the issued certificates in web servers:
- The experimental plugin for Nginx is provided with the certbot-nginx package.
- Although a package certbot-apache exists, automated installation using the Apache HTTP Server is currently only supported on Debian and derivatives.
Configuration
Please consult the Certbot documentation on how to create and install certificates.
Manual
If there is no plugin for your web server, use the following command:
# certbot certonly --manual
This will automatically verify your domain and create a private key and certificate pair. These are placed in /etc/letsencrypt/live/your.domain/
.
You can then manually configure your web server to use the key and certificate in that directory.
Webroot
The webroot method lets the client place a challenge response at yourdomain.tld/.well-known/acme-challenge/
.
You can use it to get/renew certificates with a running webserver.
# certbot certonly --email email@example.com --webroot -w /path/to/html/ -d your.domain
Make sure the server configuration for the certificates points to /etc/letsencrypt/live/your.domain/
.
Multiple domains
If you use more than one domain or subdomains, the webroot has to be given for every domain. If no new webroot is given, the previous is taken.
Management of this can be made much easier, if you map all http requests for /.well-known/acme-challenge/
to a single folder, e.g. /var/lib/letsencrypt
.
For nginx you can achieve this by creating a file containing this location block then including it in server blocks of sites you want to request certificates for:
/etc/nginx/letsencrypt.conf
location ^~ /.well-known/acme-challenge { alias /var/lib/letsencrypt/.well-known/acme-challenge; default_type "text/plain"; try_files $uri =404; }
Then within the server block:
/etc/nginx/servers/example.com.conf
server { ... include letsencrypt.conf; }
For Apache you can achieve this by creating the file httpd-acme.conf
:
/etc/httpd/conf/extra/httpd-acme.conf
Alias /.well-known/acme-challenge/ "/var/lib/letsencrypt/.well-known/acme-challenge/" <Directory "/var/lib/letsencrypt/"> AllowOverride None Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec Require method GET POST OPTIONS </Directory>
and including it in httpd.conf
:
/etc/httpd/conf/httpd.conf
Include conf/extra/httpd-acme.conf
The chosen path has then to be writable for the chosen letsencrypt client. It also has to be readable by the web server; you can achieve this thereby : chgrp http /var/lib/letsencrypt && chmod g+s /var/lib/letsencrypt
.
Automatic renewal
When running certbot certonly
, Certbot stores the domains and webroot directories in /etc/letsencrypt/renewal
, so the certificates can be renewed later automatically by running certbot renew
.
Service
You can fully automate this by creating a systemd service
/etc/systemd/system/certbot.service
[Unit] Description=Let's Encrypt renewal [Service] Type=oneshot ExecStart=/usr/bin/certbot renew --quiet --agree-tos
Standonly service
When using the standalone method you'll want to stop your webserver before executing the renew request and start your webserver when certbot is finished, luckily certbot provides some hooks that do just that.
Nginx
/etc/systemd/system/certbot.service
[Unit] Description=Let's Encrypt renewal [Service] Type=oneshot ExecStart=/usr/bin/certbot renew --pre-hook "/usr/bin/systemctl stop nginx.service" --post-hook "/usr/bin/systemctl start nginx.service" --quiet --agree-tos
Apache
/etc/systemd/system/certbot.service
[Unit] Description=Let's Encrypt renewal [Service] Type=oneshot ExecStart=/usr/bin/certbot renew --pre-hook "/usr/bin/systemctl stop httpd.service" --post-hook "/usr/bin/systemctl start httpd.service" --quiet --agree-tos
Automatic renewal timer
Before adding a timer, check that the service is working correctly and is not trying to prompt anything. Then, you can add a timer to renew the certificates daily. Include a randomized delay so that everyone's requests for renewal will be evenly spread over the day to lighten the Let's Encrypt server load.
/etc/systemd/system/certbot.timer
[Unit] Description=Daily renewal of Let's Encrypt's certificates [Timer] OnCalendar=daily RandomizedDelaySec=1day Persistent=true [Install] WantedBy=timers.target
Enable and start certbot.timer
.
You'll probably want your web server to reload the certificates after each time they're renewed. You can realize that by adding one of these lines to the certbot.service
file:
- Apache:
ExecStartPost=/bin/systemctl reload httpd.service
- nginx:
ExecStartPost=/bin/systemctl reload nginx.service