Ansible Role for Getting Let's Encrypt SSL Certificates

This role helps you request SSL certificates from Let's Encrypt. You can use either the HTTP or DNS methods to validate your domain.

Features:

• Installs and sets up certbot and a DNS helper script.
• Supports both HTTP and DNS challenges.
  • For the HTTP challenge, it supports apache, nginx, standalone, and webroot plugins.
• Uses a dedicated zone for DNS challenge tokens, improving security.
• Restarts services after certificate renewal using hooks or custom commands.
• Controls certificate permissions with a special system group.

Supported Operating Systems:

• Debian 11 (Bullseye)
• Debian 12 (Bookworm)

Tested On:

• Debian 11 (Bullseye)
• Debian 12 (Bookworm)
• CentOS 7
• Ubuntu 22.04 (Jammy Jellyfish)

What It Does:

If letsencrypt_setup is set to True (default), the role will:

• Install certbot.
• Create an account with Let's Encrypt.
• Prepare necessary files for the DNS challenge.
• Make a system group called 'letsencrypt'.

When you provide the letsencrypt_cert variable, it will:

• Request an SSL certificate from Let's Encrypt using your chosen method.
• Optionally set a hook to restart services when renewing certificates.
• Optionally add users to the 'letsencrypt' system group for access to the SSL certificates.

Examples of How to Use It:

• Install certbot:

  ansible-playbook site.yml -l localhost -t letsencrypt
  

• Create a certificate using HTTP challenge and webroot (restarting apache2 afterward):

  ansible-playbook site.yml -l localhost -t letsencrypt -e '{"letsencrypt_cert":{"name":"sub.example.org","domains":["sub.example.org"],"challenge":"http","http_auth":"webroot","webroot_path":"/var/www/sub.example.org","services":["apache2"]}}'
  

• Create a certificate using DNS challenge (granting Debian-exim read access to the certificates, restarting exim4 and dovecot afterward):

  ansible-playbook site.yml -l localhost -t letsencrypt -e '{"letsencrypt_cert":{"name":"sub2","domains":["sub2.example.org","sub2.another.example.org"],"challenge":"dns","services":["dovecot","exim4"],"users":["Debian-exim"]}}'
  

• Using HTTP challenge with standalone authenticator (re-using the key and running a custom post-hook):

  ansible-playbook site.yml -l localhost -t letsencrypt -e '{"letsencrypt_cert":{"name":"sub3","domains":["sub3.example.org"],"challenge":"http","http_auth":"standalone","reuse_key":True,"post_hook":"/usr/local/bin/cert-post-hook.sh"}}'
  

Expected Structure of letsencrypt_cert

The letsencrypt_cert variable should be a dictionary with the following structure:

letsencrypt_cert:
  name: sub.example.org                       # Certificate name (optional)
  domains:                                     # List of domains (required)
    - sub.example.org
  challenge: http                             # 'http' or 'dns' (required)
  http_auth: webroot                          # Authenticator for HTTP (optional)
  webroot_path: /var/www/sub.example.org      # Path for webroot (optional)
  services:                                   # Services to restart (optional)
    - apache2

General Info

This role will handle the installation of certbot and the request for SSL certificates through either the HTTP or DNS methods. However, it does not install or set up Apache or DNS servers.

HTTP Challenge Requirements:

• The domain for the certificate must point to your system.
• For apache, Apache2 must be installed and configured.
• For nginx, NGINX must be installed and configured.

DNS Challenge Requirements:

• You need a DNS server with a zone dedicated for the ACME DNS challenge.
• Specific CNAME records must be configured in that zone.
• You need to provide the DNS update keys in Ansible variables.

Ansible Variable Defaults:

letsencrypt_setup: True                     # Enable setup
letsencrypt_account: ""                      # Existing account data
letsencrypt_account_email: ""                # Email for Let's Encrypt account
letsencrypt_http_auth: webroot               # Default HTTP authenticator
letsencrypt_webroot_path: /var/www           # Default webroot path
letsencrypt_dns_challenge: yes                # Enable DNS challenge
letsencrypt_group: yes                       # Create system group 'letsencrypt'
letsencrypt_reuse_key: False                  # Reuse key on renewal?
letsencrypt_opts_extra: ""                    # Extra commandline options
letsencrypt_directory: /etc/letsencrypt      # Path for Let's Encrypt files

Testing

You can test this role with Let's Encrypt's test servers by setting letsencrypt_test to True. For local testing, you can run:

molecule test

License

This role is licensed under the GNU GPLv3.

Author

Copyright 2017-2019 systemli.org (https://www.systemli.org/)