Ansible Role acme_sh

This role installs acme.sh and enables issuing certificates with Let’s Encrypt. Issued certificates are copied from /etc/acme.sh to the appropriate subfolders of /etc/pki/.

After running this role, configure Apache HTTPd as follows:

SSLEngine on
SSLCertificateFile      /etc/pki/tls/certs/www.example.com.crt
SSLCertificateKeyFile   /etc/pki/tls/private/www.example.com.key
SSLCertificateChainFile /etc/pki/tls/certs/www.example.com-chain.crt

Mandatory Requirements

  • Install openssl. This can be done using the linuxfabrik.lfops.apps role.

  • Install tar. This can be done using the linuxfabrik.lfops.apps role.

  • Have a configured web server. If you are using LFOps to manage an Apache reverse proxy, a virtual host working for acme might be defined like this:

apache_httpd__vhosts__host_var:
  - conf_server_name: 'other.example.com'
    enabled: true
    state: 'present'
    template: 'redirect'
    virtualhost_port: 80

If you use the acme.sh Playbook, this is automatically done for you (except configuring the webserver).

Tags

Tag

What it does

acme_sh

Installs acme.sh and issues certificates

acme_sh:certificates

Issues certificates

acme_sh:state

Manages the state of the weekly acme.sh timer

Mandatory Role Variables

Variable

Description

acme_sh__account_email

Email address for the Let’s encrypt account. This address will receive expiry emails.

acme_sh__certificates

List of certificates that should be issued. Subkeys:

  • name: Mandatory, string. Domain of the certificate.
  • alternative_names: Optional, list. Subject Alternative Names (SAN) for the certificate. Defaults to unset.
  • reload_cmd: Optional, string. Command to execute after issue/renew to reload the server. Defaults to systemctl reload httpd.

Example:

# mandatory
acme_sh__account_email: 'info@example.com'
acme_sh__certificates:
  - name: 'other.example.com'
  - name: 'test.example.com'
    alternative_names:
      - 'linuxfabrik.example.com'
    reload_cmd: '/usr/local/sbin/custom_reload_script'

Optional Role Variables

Variable

Description

Default Value

acme_sh__deploy_to_host

The host which the issued certificates should be deployed to.

unset

acme_sh__deploy_to_host_hook

The deployment hook which should be used to deploy the certificates to the deploy host.

ssh

acme_sh__deploy_to_host_reload_cmd

The reload command which should be executed after the certificates were deployed to the deploy host.

reload_cmd subkey of the acme_sh__certificates item, or systemctl reload httpd

acme_sh__deploy_to_host_user

The remote user account which should be used to deploy the certificates to the deploy host.

root

acme_sh__key_length

Key length in bits of the certificates to issue.

4096

acme_sh__timer_enabled

Enables or disables the weekly acme.sh timer, analogous to systemctl enable/disable --now.

true

Example:

# optional
acme_sh__deploy_to_host: 'proxy02.example.com'
acme_sh__deploy_to_host_hook: 'ssh'
acme_sh__deploy_to_host_reload_cmd: 'systemctl reload nginx'
acme_sh__deploy_to_host_user: 'root'
acme_sh__key_length: 4096
acme_sh__timer_enabled: true

Troubleshooting

Request failed: <urlopen error timed out>': Check if your Reverse Proxy is available over the Internet (Ports on Provider- and Host-Firewall, DNS set correctly, DNAT configured), and check if it is hosting the requested domain on Port 80.

Replace an issued certificate:

# on the control node:
ansible MYHOST --inventory=$INV --module-name=shell --args "acme.sh --remove --domain www.example.com; rm -rf /etc/acme.sh/certs/www.example.com/"
ansible-playbook --inventory=$INV linuxfabrik.lfops.acme_sh

License

The Unlicense

Author Information

Linuxfabrik GmbH, Zurich