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

141 lines
5.2 KiB
Markdown

# service-dehydrated
Install, configure and run dehydrated Let's Encrypt client using powerdns api hook
- Based upon clutterbox.dehydrated (https://github.com/clutterbox/ansible-dehydrated) by Alexander Zielke
- Stripped down for simplicity: removed http-01 challenge, hooks
- Added pdns_api.sh (https://github.com/silkeh/pdns_api.sh) for powerdns api handling
- [service-dehydrated](#clutterboxdehydrated)
* [Role Variables](#role-variables)
* [Using dns-01 challenges](#using-dns-01-challenges)
* [using systemd timers](#using-systemd-timers)
* [Overriding per certificate config](#overriding-per-certificate-config)
* [dehydrated_deploycert](#dehydrated-deploycert)
+ [Variables](#variables)
* [Example Playbooks](#example-playbooks)
+ [Using dns-01 with cloudflare](#using-dns-01-with-cloudflare)
+ [Using dehydrated_deploycert with multiple certificates](#using-dehydrated-deploycert-with-multiple-certificates)
* [License](#license)
* [Author Information](#author-information)
## 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](#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.
```yaml
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:
```yaml
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.
```yaml
dehydrated_deploycert: |
service nginx reload
```
In this example, for ever certificate obtained, nginx will be reloaded
```yaml
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)
```yaml
- 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