martin-v.letsencryptsh

Dehydrated

Dehydrated is a tool for managing SSL/TLS certificates. Here’s how to install and set it up, including user permissions and automatic certificate renewals.

Be cautious! Dehydrated works with your private keys, so make sure to review the code from this Ansible role and the Dehydrated script.

For an example setup using NGINX as an HTTPS proxy, check out the Ansible role martin-v/ansible-nginx_https_only.

Requirements

This role needs to install the following packages on your server:

openssl
curl
sed
grep
mktemp
git

You’ll also need a web server that serves files from the directory specified in dehydrated_challengesdir (default: /var/www/dehydrated/) at the URL http://<your-domain>/.well-known/acme-challenge/ for all the domains you are obtaining certificates for.

Role Variables

Required Variables:

dehydrated_contactemail: The email used for the Let's Encrypt account. It's primarily for notifications about certificate expirations.
```
dehydrated_contactemail: certmaster@example.com
```

dehydrated_letsencrypt_agreed_terms: Set this to the URL of Let's Encrypt’s terms of service.

dehydrated_letsencrypt_agreed_terms: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf

dehydrated_domains: List the domains for which you want to request certificates. Each line creates a certificate in /etc/dehydrated/certs/.
```
dehydrated_domains: |
  example.com
  example.org www.example.org blog.example.org
```

dehydrated_deploy_cert: This variable contains a bash script that runs after certificates are created. It handles copying certificates to the correct locations, changing permissions, and restarting services.

Example script:

dehydrated_deploy_cert: |
  mkdir -p /etc/nginx/ssl/${DOMAIN}
  cp "${KEYFILE}" "${CERTFILE}" "${FULLCHAINFILE}" "${CHAINFILE}" /etc/nginx/ssl/${DOMAIN}
  chown root:root /etc/nginx/ssl/${DOMAIN}/*
  chmod 600 /etc/nginx/ssl/${DOMAIN}/*
  systemctl restart nginx.service

dehydrated_run_cron_on_every_ansible_run: This variable controls whether the cron job runs every time Ansible executes. To disable it, set it to false.
```
dehydrated_run_cron_on_every_ansible_run: false
```

Optional Variables:

dehydrated_challengesdir: This is the directory for storing your acme-challenge files. It should be publicly accessible from http://<your-domain>/.well-known/acme-challenge/.
```
dehydrated_challengesdir: /var/www/dehydrated/
```

There are more advanced variables listed in defaults/main.yml for those who want more control.

Dependencies

There are no additional dependencies.

Example Playbook

Here’s an example of a basic playbook:

- hosts: all
  remote_user: root
  vars_files:
    - dehydrated_vars.yml
  roles:
    - martin-v.dehydrated

Example Variables File

dehydrated_contactemail: certmaster@example.com
dehydrated_letsencrypt_agreed_terms: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
dehydrated_domains: |
  example.com
  example.org www.example.org blog.example.org
dehydrated_deploy_cert: |
  mkdir -p /etc/nginx/ssl/${DOMAIN}
  cp "${KEYFILE}" "${CERTFILE}" "${FULLCHAINFILE}" "${CHAINFILE}" /etc/nginx/ssl/${DOMAIN}
  chown root:root /etc/nginx/ssl/${DOMAIN}/*
  chmod 600 /etc/nginx/ssl/${DOMAIN}/*
  systemctl restart nginx.service