Configuring acme.sh

This is the ways I have configured acme.sh on my setup. I currently only run it on my HAProxy container and use a deployhook for postfix. The lxc instance I am running acme.sh on is using a Debian Trixie image.

Install

I follow the git install, which means you will need to have git installed on the server. It is recommended to install as root. It shouldn’t matter if you install it any other way.

First I create a user for managing certificates.

adduser --system --disabled-password --disabled-login --home /var/lib/acme --quiet --force-badname --group acme

Then you add that user to the haproxy group

adduser acme haproxy

Create the directory that acme.sh will be installed to.

mkdir /usr/local/share/acme.sh

Install acme.sh to the directory created above.

git clone https://github.com/acmesh-official/acme.sh.git
cd acme.sh
.acme.sh --install --no-cron --no-profile --home /usr/local/share/acme.sh
ln -s /usr/local/share/acme.sh/acme.sh /usr/local/bin
sudo chmod 755 /usr/local/share/acme.sh/

Generate ACME Account

Use sudo to enter a shell for the acme user and then register an account.

sudo -u acme -s
cd
acme.sh --register-account -m [email protected]

Configure DNS Mode

I use dns mode to create the certificate as I am lazy and use a wildcard certificate. The instructions here are for Cloudflare.

Cloudflare API Token

1. Log into your Cloudflare account dashboard.
2. Click on the person icon at top right.
3. Select Profile.
4. Select API Tokens from the left column.
5. Click the + Create Token button.
6. Use the Edit zone DNS template.
   • You can modify options here as needed. I set the Zone Resources to a specific zone and use the IPv6 address of my HAProxy container under the Client IP Address Filtering.
7. Once filled out, click on Continue to summary
8. Click Create Token
9. You will be presented with the token. Make sure you note this down.
10. Return to the dashboard. You can get your Account ID from the URL of you dash between dash.cloudflare.com and /home/overview

Now that you have a token and your account ID, you can add them as variables.

export CF_Token="randomstuff"
export CF_Account_ID="otherrandomstuff"

Create Certificate

In this example it will create a certficate with example.com as the CN and both example.com and *.example.com as DNS entries under Subject Alternative Name.

acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'

Deploy Certificate to HAProxy

Set the environment variables that acme.sh will use. You can find where the socket is located in your haproxy.cfg.

export DEPLOY_HAPROXY_HOT_UPDATE="yes"
export DEPLOY_HAPROXY_STATS_SOCKET="/var/run/haproxy/admin.sock"
export DEPLOY_HAPROXY_PEM_PATH="/etc/haproxy/certificates"

Run acme.sh with the built-in haproxy deployhook.

acme.sh --deploy -d example.com -d '*.example.com' --deploy-hook haproxy

This copies the certificates to the directory /etc/haproxy/certificates and loads them live into haproxy. No restart required.

Deploy Certificates to Remote Server

This example is deploying the certificates to a Postfix server and reloading Postfix.

You need to make sure you can ssh using an ssh key to the remote server. There are lots of guides around for doing that.

You then need to add environment variables. I am deploying to an LXC instance running postfix on my Incus host name smtp.incus. I am using the root user on that container.

export DEPLOY_SSH_USER="root"
export DEPLOY_SSH_SERVER="smtp.incus"
export DEPLOY_SSH_KEYFILE="/etc/ssl/mail/example.com.key"
export DEPLOY_SSH_FULLCHAIN="/etc/ssl/mail/example.com.pem"
export DEPLOY_SSH_REMOTE_CMD="postfix reload"

Run acme.sh with the built-in ssh deployhook

acme.sh --deploy -d example.com -d '*.example.com' --deploy-hook ssh

Schedule Update

Add a cronjob that periodically updates the certificate with the following command.

acme.sh --install-cronjob