Let’s Encrypt

Stand-alone signed SSL certificate for use on personal systems using Let’s Encrypt and ACME protocol with DNS-01 verification.

Ansible Role: acme

This is for personal use only, and doesn’t account for specific nation-state attacks, which could include MITM or a compromise of Let’s Encrypt servers or the ACME protocol. Don’t consider this secure. It is better than having people accepting self-signed certificates, and it enables use of verifed SSL for things like mail and web services.

  • Automatically adds a _acme_challenge TXT record to your DNS server, confirming you own the domain, and download the signed certificates. No exposed ports are required.

  • Automatically pulls new certificates if none are found in acme_cert. Renewal requests automatically happen every 12 hours. Be sure to restart if changes are made.

  • Lexicon is used to modify your domains, but requires specific authentication for each differ provider. See Lexicon Providers for specific options for each supported DNS provider.

  • Use the Configuration Reference and the example config to setup for your specifc DNS providers.

None

Role Details: Updated: 2022-10-09 service docs Reference PRIVATE

Defaults

---
###############################################################################
# ACME (let's encrypt) Role Configuration
###############################################################################
# Note: If certs fail to renew, check cert/logs/letsencrypt.log
#
# 'certbot.errors.CertStorageError: expected .../cert.pem to be a symlink`
#
# Means the certificate location changed, likely due to cert path change:
# * Confirm full path for acme/cert/live/{DOMAIN}/*.pem
# * Update related configuration files in acme/cert/renewal/*.conf
# * Ensure local path matches configuration path in cert/config

# User that roundcube will run under. Assumes externally managed.
acme_user:  'acme'
acme_group: 'acme'

# Create 'acme' user if not detected? See: vars/main.yml.
acme_create_user: false

# Install and working directory for ACME certificates. Default: '/etc/acme'
# (user home directory).
acme_base: '{{ acme_default_user.home }}'

# ACME certifcate storage location. Default: '{{ acme_base }}/cert'
acme_cert: '{{ acme_base }}/cert'

###############################################################################
# dnsrobocert config.yml (acme section)
###############################################################################
#
# Reference:
# * https://dnsrobocert.readthedocs.io/en/latest/user_guide.html#configuring-acme-section

acme_config_acme:
  email_account: 'user@example.com'
  staging:       true
  api_version:   2
  certs_permissions:
    user:       '{{ acme_user }}'
    group:      '{{ acme_group }}'
    dirs_mode:  '0750'
    files_mode: '0640'

###############################################################################
# dnsrobocert config.yml (profiles section)
###############################################################################
# sleep_time is the delay in seconds to validate DNS after making auth
# challenge change to the domain. Set to ``150`` as Google Cloud DNS guarantees
# updates in 120 seconds.
#
# staging will run requests against the staging server, allowing the ability
# to test setup.
#
# Reference:
# * https://dnsrobocert.readthedocs.io/en/latest/user_guide.html#configuring-profiles-section

acme_config_profiles:
  - name: 'googleclouddns'
    provider:   'googleclouddns'
    sleep_time: 150
    provider_options:
      # base64 encoded password. Use vault.
      auth_service_account_info: 'base64::...'

###############################################################################
# dnsrobocert config.yml (certificates section)
###############################################################################
#
# Reference:
# * https://dnsrobocert.readthedocs.io/en/latest/user_guide.html#configuring-certificates-section

acme_config_certificates:
  - name:    'example.com'
    domains:
      -      '*.example.com'
      -      'example.com'
    profile: 'googleclouddns'
  - name:    'mail.example.com'
    domains:
      -      'mail.example.com'
    profile: 'googleclouddns'
  - name:    'example2.com'
    domains:
      -      '*.example2.com'
      -      'example2.com'
    profile: 'googleclouddns'
  - name:    'mail.example2.com'
    domains:
      -      'mail.example2.com'
    profile: 'googleclouddns'

Example Config:

acme:
  api_version: 2
  certs_permissions:
    group: root
    user: root
    dirs_mode: '0750'
    files_mode: '0640'
  email_account: {EMAIL}
  staging: false
certificates:
- domains:
  - '*.example.com'
  - example.com
  name: example.com
  profile: googleclouddns
- domains:
  - mail.example2.com
  name: mail.example2.com
  profile: googleclouddns
profiles:
- name: googleclouddns
  provider: googleclouddns
  provider_options:
    auth_service_account_info: >-
      base64::asdfJDFDx99dsafd ...
  sleep_time: 150