Acme.sh Setup

Debian / Ubuntu

Overview

Setup acme.sh for automated certificate deployment.

Assumptions

• Logged in as administrative user.

Create System User

Add a new acmesh system user and map the home directory to /opt/acmesh.

sudo useradd --system --user-group --create-home --home /opt/acmesh --shell /sbin/nologin acmesh

Execute commands as the user using su.

sudo su -s /bin/bash acmesh -c "COMMAND_TO_RUN"

Alternatively, switch to the user with su.

sudo su -s /bin/bash - acmesh

Install acme.sh

As the acmesh user, download the installation script from the project domain.

wget -O /opt/acmesh/acmesh-install.sh https://get.acme.sh

Review the installation script and run it.

sh /opt/acmesh/acmesh-install.sh email=[email protected]

Verify a cron job was successfully created for acme.sh.

crontab -e

There should be an entry resembling the following at the end of the file.

0 2 * * * "/opt/acmesh/.acme.sh"/acme.sh --cron --home "/opt/acmesh/.acme.sh" > /dev/null

Configure acme.sh

Configure acme.sh from the directory it was installed to, /opt/acmesh/.acme.sh in this guide.

Select Certificate Authority

Select a certificate authority for acme.sh to use for generating certificates. Refer to the acme.sh CA documentation for an updated list of supported certificate authorities.

This guide will assume Let’s Encrypt is being used.

/opt/acmesh/.acme.sh/acme.sh --set-default-ca --server letsencrypt

Configure DNS Provider

Provide acme.sh API credentials for your DNS provider. These will be used for DNS-based ACME validation when generating new certificates.

Start by modifying the permissions for the account.conf file so no other system users can view your API credentials.

chmod 640 /opt/acmesh/.acme.sh/account.conf

Open the acme.sh account.conf configuration file.

nano /opt/acmesh/.acme.sh/account.conf

Enter the API information required by your specific provider. Refer to the acme.sh DNS API documentation and find your provider in the list.

This guide will assume the Cloudflare API is being used. Generate a new Cloudflare API token from your profile, and note the Zone ID on the relevant domain overview page.

CF_TOKEN='YourCloudflareAPIToken'
CF_ZONE_ID='CertificateDomainZoneID'

Deploy Certificate

With acme.sh configured, a certificate can now be easily deployed.

Issue Certificate

Issue a new certificate for a domain of choice, or wildcard, with the following command. Consider using the --staging flag while testing to prevent being rate-limited by Let’s Encrypt. Replace the Cloudflare DNS definition --dns dns_cf with the flag for your specific DNS provider; this flag instructs acme.sh to use the DNS challenge.

/opt/acmesh/.acme.sh/acme.sh --issue -d example.com -d www.example.com --dns dns_cf

Install Certificate

Install the generated certificate files to the directory required by your application. The following demonstrates deploying the certificates to the Apache ssl directory.

Start by modifying the directory so the acmesh user can write files to it.

sudo chown -R acmesh:root /etc/apache2/ssl && \
sudo chmod -R go= /etc/apache2/ssl

Run the acme.sh certificate installation tool, specifying the locations to install certificates.

/opt/acmesh/.acme.sh/acme.sh --installcert -d example.com \
--certpath /etc/apache2/ssl/example-cr.pem \
--keypath /etc/apache2/ssl/example-cr.key \
--capath  /etc/apache2/ssl/example-ca.pem

You may also add the --reloadcmd flag to issue a command after the certificates are installed, this would require the acmesh user to have the proper permissions to run the command. For example, to restart Apache after a new certificate has been installed, add the following flag.

--reloadcmd  "systemctl restart apache2"

References

^{1 2 3 4}