forked from pool/dehydrated
Marcus Rueckert
3a1b390a5c
- No longer require nginx or lighttpd for SLE
- Never go as far as to require acmeresponder, it might not be available
- Drop -update from dehydrated-update.{timer,socket} for consistency
- Add distro specific README.SUSE / README.Fedora
- Ran spec-cleaner
OBS-URL: https://build.opensuse.org/request/show/528993
OBS-URL: https://build.opensuse.org/package/show/security:dehydrated/dehydrated?expand=0&rev=12
141 lines
5.0 KiB
Plaintext
141 lines
5.0 KiB
Plaintext
==========================================
|
|
Acquiring TLS Certificates with Dehydrated
|
|
==========================================
|
|
|
|
The SUSE 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.
|
|
|
|
Aqcuisition through HTTP (http-01)
|
|
===================================
|
|
|
|
This is the primary method of acquiring certifictes.
|
|
|
|
Setting up the acme-challenge auto-responder
|
|
--------------------------------------------
|
|
|
|
Apache
|
|
~~~~~~
|
|
|
|
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, you can use dehydrated-acmeresponder, 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)
|
|
================================
|
|
|
|
Tnis 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 (This is currently not automated on the dehydrated end,
|
|
however Apache will reload every night due to log rotation).
|
|
|
|
Links
|
|
=====
|
|
|
|
[1] https://mozilla.github.io/server-side-tls/ssl-config-generator/
|