clutterbox.dehydrated

Install, configure and run dehydrated Let's Encrypt client

• clutterbox.dehydrated
  • Role Variables
  • Using dns-01 challenges
  • using systemd timers
  • Overriding per certificate config
  • dehydrated_deploycert
    • Variables
  • Example Playbooks
    • Using http-01 .well-known/acme-challenge
    • Using dns-01 with cloudflare
    • Using dehydrated_deploycert with multiple certificates
  • Additinal hook scripts
    • Writing shell fragments for single hooks
    • deploying complete hook script files
  • License
  • Author Information

Table of contents generated with markdown-toc

Role Variables

Variable	Function	Default
dehydrated_accept_letsencrypt_terms	Set to yes to automatically register and accept Let's Encrypt terms	no
dehydrated_contactemail	E-Mail address (required)
dehydrated_domains	List of domains to request SSL certificates for
dehydrated_deploycert	Script to run to deploy a certificate (see below)
dehydrated_wellknown	Directory where to deploy http-01 challenges
dehydrated_install_root	Where to install dehydrated	/opt/dehydrated
dehydrated_update	Update dehydrated sources on ansible run	yes
dehydrated_version	Which version to check out from github	HEAD
dehydrated_challengetype	Challenge to use (http-01, dns-01)	http-01
dehydrated_use_lexicon	Enable the use of lexicon	yes if dehydrated_challengetype == dns-01 else no
dehydrated_lexicon_dns	Options for running lexicon	{}
dehydrated_hooks	Dict with hook-names for which to add scripts
dehydrated_hook_scripts	Add additional scripts to hooks-Directory	[]
dehydrated_key_algo	Keytype to generate (rsa, prime256v1, secp384r1)	rsa
dehydrated_keysize	Size of Key (only for rsa Keys)	4096
dehydrated_ca	CA to use	https://acme-v02.api.letsencrypt.org/directory
dehydrated_cronjob	Install cronjob for certificate renewals	yes
dehydrated_systemd_timer	Use systemd timer for certificate renewals	no
dehydrated_config_extra	Add arbitrary text to config
dehydrated_run_on_changes	If dehydrated should run if the list of domains changed	yes
dehydrated_systemd_timer_onfailure	If set, an OnFailure-Directive will be added to the systemd unit
dehydrated_cert_config	Override configuration for certificates	[]
dehydrated_repo_url	Specify URL to git repository of dehydrated	https://github.com/dehydrated-io/dehydrated.git
dehydrated_install_pip	Whether pip will be installed when using lexicon	yes
dehydrated_pip_package	Name of pip package	python3-pip if ansible is running on python3, otherwise python-pip
dehydrated_pip_executable	Name of pip executable to use	autodetected by pip module

Using dns-01 challenges

When dehydrated_challengetype is set to dns-01, this role will automatically install lexicon from python pip to be able to set and remove the necessary DNS-Records needed to obtain an SSL certificate.

lexicon uses environment variables for username and password.

using systemd timers

It is possible to use a systemd-timer instead of a cronjob to renew certificates.

Note: Enabling the systemd timer does not disable the cronjob. This might change in the future.

dehydrated_systemd_timer: yes
dehydrated_cronjob: no

Overriding per certificate config

The Configration for single certificates can be overridden using dehydrated_cert_config.

dehydrated_cert_config must be a list of dicts. Only the elemenent name: is mandatory ans must match a certificate name. The certificate name is either the first domain listed in domains.txt or the certificate alias, if defined.

Format is as follows:

dehydrated_cert_config:
 - name: # certificate name or alias (mandatory)
   state: present # present or absent (optional)
   challengetype: # override CHALLENGE (optional)
   wellknown: # override WELLKNOWN (optional)
   key_algo: # override KEY_ALGO (optional)
   keysize: # override KEYSIZE (optional)

dehydrated_deploycert

The variable dehydrated_deploycert contains a shellscript fragment to be executed when a certificate has successfully been optained. This variable can either be a multiline string or a hash of multiline strings.

dehydrated_deploycert: |
  service nginx reload

In this example, for ever certificate obtained, nginx will be reloaded

dehydrated_deploycert:
  example.com: |
    service nginx reload
  service.example.com: |
    cat ${FULLCHAINFILE} ${KEYFILE} > /etc/somewhere/ssl/full.pem
    service someservice reload

Here, for certificates with the primary domain example.com, nginx will be reloaded and for service.example.com the certificate, intermediate and key will be written to another file and someservice is reloaded.

Variables

Variable	Function
DOMAIN	(Primary) Domain of the certificate
KEYFILE	Full path to the keyfile
CERTFILE	Full path to certificate file
FULLCHAINFILE	Full path to file containing both certificate and intermediate
CHAINFILE	Full path to intermediate certificate file
TIMESTAMP	Timestamp when the certificate was created.

Example Playbooks

Using http-01 .well-known/acme-challenge

- hosts: servers
  vars:
    dehydrated_accept_letsencrypt_terms: yes
    dehydrated_contactemail: [email protected]
    dehydrated_wellknown: /var/www/example.com/.well-known/acme-challenge
    dehydrated_domains: |
      example.com
    dehydrated_deploycert: |
      service nginx reload
  roles:
    - clutterbox.dehydrated

Using dns-01 with cloudflare

- hosts: servers
  vars:
    dehydrated_accept_letsencrypt_terms: yes
    dehydrated_contactemail: [email protected]
    dehydrated_challengetype: dns-01
    dehydrated_lexicon_dns:
      LEXICON_CLOUDFLARE_USERNAME: [email protected]
      LEXICON_CLOUDFLARE_TOKEN: f7e7e...
    dehydrated_domains: |
      example.com
    dehydrated_deploycert: |
      service nginx reload
  roles:
    - clutterbox.dehydrated

Using dehydrated_deploycert with multiple certificates

- hosts: servers
  vars:
    # [...]
    dehydrated_domains: |
      example.com www.example.com
      sub.example.com
      service.example.com
    dehydrated_deploycert:
      example.com: |
        service nginx reload
      sub.example.com
        cat ${FULLCHAINFILE} ${KEYFILE} > /etc/somewhere/ssl/full.pem
        service someservice reload
      service.example.com:
        rsync -rl $(dirname ${KEYFILE})/ [email protected]:/etc/ssl/${DOMAIN}/
        ssh [email protected] sudo service someservice reload
  roles:
    - clutterbox.dehydrated

Additinal hook scripts

This role offers two different ways to deploy additional hooks:

• Using shell fragments
• by deploying complete hook scripts

For Information on how to use these hooks see https://github.com/lukas2511/dehydrated/blob/master/docs/examples/hook.sh

This role follows the example hook script as close as possible.

Writing shell fragments for single hooks

Single hooks can be written using the dehydrated_hooks variable. The variable is a dict where the key is the name of a hook and the value is the shell fragment.

dehydrated_hooks:
  exit_hook: |
    echo "simple cleanup"
  deploy_ocsp: |
    cp "${OCSPFILE}" /etc/nginx/ssl/
    nginx -s reload

For every known hook, well-know variables are set according to the example hook script (see link above).

deploying complete hook script files

Additional hooks can be deployed using dehydrated_hook_scripts or can be put in the /etc/dehydrated/hooks.d directory manually.

The syntax for dehydrated_hook_scripts is as follows:

dehydrated_hook_scripts:
  - src: # source filename
    name: # optional filename inside hooks.d. defaults to filename in src
    state: # state present or absent. defaults to present

If you have a hook-script called myhook in your playbook-directory, it can be deployed like:

dehydrated_hook_scripts:
  - src: "{{ playbook_dir }}/myhook"

If you decide, that you don't need the hook anymore, you can add state: absent and it will be deleted.

Note: Filenames must match ^[a-zA-Z0-9_-]+$ - otherwise they won't be executed!

Testing

This role is automatically tested using Travis CI. Local testing can be done using Vagrant. Both run molecule/setup.sh script to setup the testing environment.

Multiple services are started in the environment to test both http-01 and dns-01.

Service	Usage
boulder (using docker)	Let's Encrypt CA for validations
nginx	webserver for http-01
powerdns	Used as a nameserver for dns-01. lexicon as a plugin to manipulate records.

License

MIT License

Author Information

Alexander Zielke - [email protected]