========================================== Acquiring TLS Certificates with Dehydrated ========================================== The dehydrated package has been designed to make acquiring TLS certificates (aka SSL Certificates) as simple as possible, while still being useful in a broad amount of use cases. Please consult the dehydrated man page, then continue reading here. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! IMPORTANT: On systemd-based systems, you need to enable the update timer, which has obsoleted the cron job. This is independent on which method you chose from below! # systemctl enable dehydrated.timer Also note that with the systemd timer, failures will not be mailed to the system administrator, but are being logged to the systemd journal, as per systemd's design philosophy. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Acquisition through HTTP (http-01) =================================== This is the primary method of acquiring certifictes. The Certificate Authority will provide a challenge that the requestor needs to provide via HTTP on port 80/TCP, in /.well-known/acme-challenge/. Setting up the acme-challenge auto-responder -------------------------------------------- Apache (easiest) ~~~~~~~~~~~~~~~~ If you are using Apache, just install dehydrated-apache2 and reload Apache. This will take care of setting up the acme-challenge auto-responder. nginx ~~~~~ (not part of SLE, use openSUSE backports) For nginx, you will need to install dehydrated-nginx. Unfortunately, nginx does not support directory mappings across vhosts, so in addition you will need to include "/etc/nginx/acmechallenge" in all vhost configurations like this: server { listen 80; listen [::]:80; server_name <hostname>; include "acmechallenge"; location / { return 301 https://$host$request_uri; } } lighttpd ~~~~~~~~ (not part of SLE, use openSUSE backports) Lighttpd users can simply install dehydrated-lighttpd and reload lighttpd to set up the acme-challenge auto-responder NOTE: Never set up the SSL vhosts until you have initially acquired the first host. Specifying an SSL vhost without certificates constitutes an error for web servers. Machines without a webserver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ On machines that are not running any web server, e.g. mail relays, you can run apache2 with dehydrated-apache2. If you do not want to run any web server on a system with systemd permnently, you can use dehydrated-acmeresponder. This is a small socket activated server. Once installed, it will automatically listen on port 80 whenever the dehydrated cron job seeks renewal, assuming no other server is currently occupying the port. It will also shut down once the timer has finished execution. Acquisition of initial certificate ---------------------------------- How set up an account as described in the man page (as root): # dehydrated --register --accept-terms (the current version of the LetsEncrypt Terms & Conditions are referenced in /etc/dehydrated/config) Next, fill in domains.txt and acquire the initial certificates (again, as root): # echo "myhost.example.com myalias.example.com" >> domains.txt # dehydrated --cron adds myhost.example.com to the list of host names we want to request a certificate for. The certificate will hold a Subject Alternative Name of "myalias.example.com". LetsEncrypt will check both host names. NOTE: As of 2017, LetsEncrypt certificates are only valid for three months, and the validity period may be further reduced in the future. It is therefore vital to ensure that the certificates are being automatically renewed. On systems without systemd, a cron job is automatically set up to take care of this. On systemd-enabled systems, a timer is provided which needs to be activated manually: # systemctl enable dehydrated.timer Aqcuisition through DNS (dns-01) ================================ This is mostly useful under these conditions 1. Your hosts are not directly exposed to the internet 2. Your host names are part of a public DNS zone visible on the internet. 3. You are comfortable with the service adding and removing records in your domain. Usually, the scenario you want this is a central host which picks up certificates for all other hosts on a network, and then deploys them to the actual target host, using plain scp or configuration management tools like Ansible or Salt. For details, please refer to dns-verification.md. For openSUSE, the python-dns-lexicon package provides hooks into many DNS providers and DNS servers. Proceeding after initial certificate aquisition =============================================== Setting up the SSL host ----------------------- As recommended parameters shift, please refer to Mozillas excellent SSL Configuration Generator [1] for details on how to configure your web server. Replace the example paths with the following: Key: /etc/dehydrated/certs/<domainname>/privkey.pem Certificate: /etc/dehydrated/certs/<domainname>/cert.pem Intermediate Chain: /etc/dehydrated/certs/<domainname>/chain.pem Certificate + Intermediate: /etc/dehydrated/certs/<domainname>/fullchain.pem where <domainname> should be the name of the first column in domains.txt Limitations & Ceveats ===================== * It is currently not possible to aqcuire Wildcard certificates * No EV- or OV-validated certificates * Certificates expire within weeks, not years. This is by design. Ensure that certificate renewal works and that daemons get reloaded frequently to pick up certificate updates. Apache will work due to log rotation SIGHUP'ing the process frequently. However, any other actions, such as service reloads need to be provided as a script in /etc/dehydrated/postrun-hooks.d, which will be executed by the cron script / systemd timer *after* an update run has been performed. Links ===== [1] https://mozilla.github.io/server-side-tls/ssl-config-generator/