ansible-ffibk/roles/service-dehydrated/README.md
prisma01 7611fb9d76
add dehydrated role with pdns-api.sh support (#25)
* add dehydrated role with pdns-api.sh support

* Minor changes to Readme

* Remove Meta

* move dehydrated to linse

* Remove Zuckerwatte from PR (nothing to do with dehydrated)

* Add other domains to dehydrated config, added hook_chain

* Add authorized keys for cert user, add structures in /home/cert/ for checking out certs

* Send dehydrated ouput to /dev/null

* user authorized_keys module, add kumpir key

* Fix typo. Use \\n for each ssh-key

* remove unnecessary .ssh creation (done by authorized_key module)

* Added wrapper script to execute two hooks: pdns_api.sh + deploy certificates

* Remove challengetype variable, as only dns-01 is supported anyway.

* Add freifunk-mainz.de domain

* fix cert deploy script.
2019-09-08 20:44:26 +02:00

5.2 KiB

service-dehydrated

Install, configure and run dehydrated Let's Encrypt client using powerdns api hook

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_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_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_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/lukas2511/dehydrated.git
pdns_api_repo_url Specify URL to git repository of pdns_api.sh https://github.com/silkeh/pdns_api.sh
pdns_api_update Update pdns_api.sh sources on ansible run yes
pdns_api_version Powerdns api version (v>=4 ? 1 : 0) 1

Using dns-01 challenges

Due to simplicity only dns-01 is supported. See Example Playbooks

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)
   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 dns-01 with powerdns (only supported use case)

- hosts: servers
  vars:
    dehydrated_accept_letsencrypt_terms: yes
    dehydrated_contactemail: hostmaster@example.com
    dehydrated_domains: example.com
    pdns_host: https://powerdns-api.url.com:port

    dehydrated_deploycert: |
      service nginx reload      
  roles:
    - service-dehydrated

License

MIT License

Author Information

Alexander Zielke - mail@alexander.zielke.name

Sebastian Schmachtel - prisma_freifunk@oimel.net