dehydrated/README.maintainer

==========================================
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 use the following snippet:

  server.modules += ("mod_alias")
  alias.url += (
     "/.well-known/acme-challenge/" => "/var/lib/acme-challenge/",
  )

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.

NOTE: The dehydrated-lighttpd package has been removed. Please use the
snippet above.

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.

Upgrade Notes
=============

If you are upgrading from letsencrypt.sh, note that you need to move
/etc/letsencrypt.sh to /etc/dehydrated and chown it to the "dehydrated"
user.

Links
=====

[1] https://mozilla.github.io/server-side-tls/ssl-config-generator/