Install acme.sh with CF and multidomain

Purpose

This role install the acme.sh project on a Linux server and sets up domain(s) with DNS challenge. You can set DNS provider, however, DNS challenge type is the most preferred method than webserver challenges in automated environments.

Variables

All variables are in the defaults folder, however the most importants are:

All domains are in the list, so the list can contains multiple domain configs. In the example we set only one cert with wildcard domain.

• Domains is a list in list format. You can set root domain and wildcard domain. However it is important that the first element used in the filenames, so avoid to use wildcard in the first position!

Note: When you make any change in the list and rerun the role, it dinamicaly changes it. So if you have a domain and a wildcard and two more wildcards it will be expanded. And reverse, if you remove extra wildcards they will be removed.

• Hooks: Refer acme.sh help or documentation, these are runs in the different stages of issue and renew. Everytime scripts runs in the domain directory so you can use relative command to copy the cert as source.
• acme_sh_issue_env_vars: Following the acme.sh documentation you need to optain three data (two API keys and a zone ID) from Cloudflare and need to set them here.
• acme_sh_user_sudo_commands: Optional, list commands in this array that will be added to the sudoers file of user (so these commands are only allowed as root)

Important: Specify the full path, E.G. /usr/bin/docker or /usr/sbin/something to avoid the sudo missing full path problems.

• acme_sh_user_sudoers_file: Contents of the sudoers file for acme user

Note: Avoid to use the sudoers file and sudo commands together because sudoers file has higher precedence.

• acme_sh_user_sudoers_file: You can specify the name of the sudoers file in /etc/sudoers.d for this user to exec limited amount commands without password.

And again, you need to set these vars for every single cert issue (that can contain multiple subdoms, see CA for more info and limitations).

Most important of global variables are

• acme_sh_email: The e-mail address at acme.sh installation
• acme_sh_user_groups: Add acme user to groups. In this example add to docker so can manage containers and certs related to them.

Example

The example uses the Cloudflare provided DNS API to retrieve certs with DNS challenge. You can use many other providers. Refer to documentation.

In this example the Cloudflare domain and account specific information are in plain text. However these are sensitive so might be a good idea to use Ansible Vault.

acme_sh_domains:
  - domains:
      - "yourdomain.com" # it is the root domain
      - "*.yourdomain.com" # get wildcard
    dns_provider: "dns_cf"
    pre_hook:
    post_hook: |
      #!/bin/sh
      echo "OK" > ~/domtest.txt
      echo "$PWD" >> ~/domtest.txt
    renew_hook:  |
      #!/bin/sh
      echo "OK" > ~/domtest.txt
      echo "$PWD" >> ~/domtest.txt
    acme_sh_issue_env_vars:
      CF_Token: ""
      CF_Zone_ID: ""
      CF_Account_ID: ""
acme_sh_user_groups: ["docker"]
acme_sh_email: ""

Paths

You can look for every variables in the defaults folder and can set up the user, additional groups (e.g. if you want to use this with Docker), paths. It is important that every cert got an own folder and all of files stored here.

Hooks are different shell scripts to make easier to manage or modify them later. The acme.sh by default stores the hooks in base64 format in the config, however it is hard to determine that it is changed and this workaround makes easier to modify or debug it.

Hooks run only when acme.sh issues it, E.G. on a success cert creation or renew. So it is important to create the directory if you move the newly created keys. For example if you use docker-nginx-proxy-with-nginx-gen, make sure that nginx role runs before acme role, as it sets up the directory. And if you copy the certs into the nginx, it is important that the folder exists. An example for this, that copy fullchain.cer as your domain.com.crt and domain.com.key as domain.com.key to the Nginx certs. See more info about nginx-proxy docker-gen SSL handling here.

It is a good practice to create new user with the role for acme.sh. You can add it to Docker group or give limited sudo privileges so a possible attack can make harder to impact your server negative.

todo

• Avoid resetting the default CA on every run
• Set up notification system of acme.sh
• Reconnect after adding acme to groups to avoid possible access denied problems