Let’s Encrypt
Let’s Encrypt is a free, automated, and open certificate authority utilizing the ACME protocol.
It is recommended to start with the certbot client, which allows to request valid X.509 certificates straight from the command line.
If you would like to try other clients, a minimal client with manual certificate signing request (CSR) creation is available at acme-tinyAUR. Clients suitable for scripts are simp_le-gitAUR and letsencrypt-cliAUR.
Contents
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.
- Automated installation using the Apache HTTP Server is enabled via the certbot-apache package.
Configuration
Consult the Certbot documentation for more information about creation and usage of certificates.
Plugins
Nginx
The plugin certbot-nginx provides an automatic configuration for nginx server-blocks:
# certbot --nginx
To renew certificates:
# certbot renew
To change certificates without modifying nginx config files:
# certbot --nginx certonly
See Nginx on Arch Linux for more information and #Automatic renewal to keep installed certificates valid.
Managing server blocks
The following example may be used in each server-blocks when managing these files manually:
/etc/nginx/sites-available/example
server { listen 443 ssl http2; listen [::]:443 ssl http2; # Listen on IPv6 ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem; # managed by Certbot ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem; # managed by Certbot include /etc/letsencrypt/options-ssl-nginx.conf; ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; .. }
See nginx#TLS/SSL for more information.
It's also possible to create a separated config file and include it in each server block:
/etc/nginx/conf/001-cerbot.conf
ssl_certificate /etc/letsencrypt/live/domain/fullchain.pem; # managed by Certbot ssl_certificate_key /etc/letsencrypt/live/domain/privkey.pem; # managed by Certbot include /etc/letsencrypt/options-ssl-nginx.conf; ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
/etc/nginx/sites-available/example
server { listen 443 ssl http2; listen [::]:443 ssl http2; # Listen on IPv6 include conf/001-certbot.conf; .. }
Webroot
- The Webroot method requires HTTP on port 80 for Certbot to validate.
- The Server Name must match that of it's corresponding DNS.
- Permissions may need to be altered on the host to allow read-access to
http://domain.tld/.well-known
.
When using the webroot method the Certbot client places a challenge response inside /path/to/domain.tld/html/.well-known/acme-challenge/
which is used for validation.
The use of this method is recommend over a manual install; it offers automatic renewal and easier certificate management. However the usage of #Plugins may be the preferred since it allows automatic configuration and installation.
Mapping ACME-challenge requests
Management of can be made easier by mapping all HTTP-requests for .well-known/acme-challenge
to a single folder, e.g. /var/lib/letsencrypt
.
The path has then to be writable for Cerbot and the web server (e.g. nginx or Apache running as user http):
# mkdir -p /var/lib/letsencrypt/.well-known # chgrp http /var/lib/letsencrypt # chmod g+s /var/lib/letsencrypt
nginx
Create a file containing the location block and include this inside a server block:
/etc/nginx/conf.d/letsencrypt.conf
location ^~ /.well-known/acme-challenge/ { allow all; root /var/lib/letsencrypt/; default_type "text/plain"; try_files $uri =404; }
Example of a server configuration:
/etc/nginx/servers-available/domain.conf
server { server_name domain.tld .. include conf.d/letsencrypt.conf; }
Apache
Create the file /etc/httpd/conf/extra/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>
Including this in /etc/httpd/conf/httpd.conf
:
/etc/httpd/conf/httpd.conf
Include conf/extra/httpd-acme.conf
Obtain certificate(s)
Request a certificate for domain.tld
using /var/lib/letsencrypt/
as public accessible path:
# certbot certonly --email email@example.com --webroot -w /var/lib/letsencrypt/ -d domain.tld
To add a (sub)domain, include all registered domains used on the current setup:
# certbot certonly --email email@example.com --webroot -w /var/lib/letsencrypt/ -d domain.tld,sub.domain.tld
To renew (all) the current certificate(s):
# certbot renew
See #Automatic renewal as alternative approach.
Manual
If there is no plugin for your web server, use the following command:
# certbot certonly --manual
When preferring to use DNS challenge (TXT record) use:
# certbot certonly --manual --preferred-challenges dns
This will automatically verify your domain and create a private key and certificate pair. These are placed in /etc/letsencrypt/archive/your.domain/
and symlinked from /etc/letsencrypt/live/your.domain/
.
You can then manually configure your web server to reference the private key, certificate and full certificate chain in the symlinked directory.
/etc/letsencrypt/archive/your.domain/
. Certbot automatically updates the symlinks in /etc/letsencrypt/live/your.domain/
to point to the latest instances of files so there is no need to update your webserver to point to the new key material.Advanced Configuration
Automatic renewal
systemd
Create a systemd certbot.service
:
/etc/systemd/system/certbot.service
[Unit] Description=Let's Encrypt renewal [Service] Type=oneshot ExecStart=/usr/bin/certbot renew --quiet --agree-tos
If you do not use a plugin to manage the web server configuration automatically, the web server has to be reloaded manually to reload the certificates each time they are renewed. This can be done by adding --deploy-hook "systemctl reload nginx.service"
to the ExecStart
command [1]. Of course use httpd.service
instead of nginx.service
if appropriate.
Add a timer to check for certificate renewal twice a day and include a randomized delay so that everyone's requests for renewal will be spread over the day to lighten the Let's Encrypt server load [2]:
/etc/systemd/system/certbot.timer
[Unit] Description=Twice daily renewal of Let's Encrypt's certificates [Timer] OnCalendar=0/12:00:00 RandomizedDelaySec=1h Persistent=true [Install] WantedBy=timers.target
Enable and start certbot.timer
.