Install an SSL certificate with ACME and acme.sh

Install acme.sh

The script installs acme.sh in /root/.acme.sh, adds the acme.sh alias and a renewal cron job. The last command prints the installed version.

curl https://get.acme.sh | sh -s email=admin@mydomain.tld
source ~/.bashrc
acme.sh --version

See an example result

Review the existing installation

Update acme.sh and list the certificates it already manages. The rest of the tutorial does not change them.

acme.sh --upgrade
acme.sh --list

Each HTTPCS order has its own ACME account, while acme.sh keeps only one account per server URL. Check whether an account already exists for the URL of this certificate:

ls /root/.acme.sh/ca/SERVER_URL/account.key

No such file or directory: no account, keep the shared configuration. The account.key file is listed: another certificate already uses this URL, choose the separate configuration, otherwise acme.sh would reuse the old account and the ACME server would reject this domain.

grep -o '^SAVED_[A-Za-z_]*' /root/.acme.sh/account.conf

Register the ACME account

This command links acme.sh to your HTTPCS ACME account with the EAB (External Account Binding) credentials. Run it only once per server.

This step is still required with an existing acme.sh: the EAB credentials belong to this HTTPCS order.

Separate configuration: --config-home keeps this certificate in its own folder (ACME account, DNS credentials, renewal settings). Keep this option in every following command, it is already added.

mkdir -p /root/.acme.sh-httpcs-mydomain.tld && touch /root/.acme.sh-httpcs-mydomain.tld/account.conf
acme.sh --register-account \
  --config-home /root/.acme.sh-httpcs-mydomain.tld \
  --server SERVER_URL \
  --eab-kid YOUR_KID \
  --eab-hmac-key YOUR_HMAC \
  -m admin@mydomain.tld

Expected result: Registered then ACCOUNT_THUMBPRINT=….

Test the website folder

To prove control of the domain, acme.sh places a file in the .well-known/acme-challenge folder of the website. This test reproduces the operation before the real request. For a multi-domain certificate, repeat the curl line with each domain.

mkdir -p /var/www/html/.well-known/acme-challenge
echo ok > /var/www/html/.well-known/acme-challenge/httpcs-test
curl -i http://mydomain.tld/.well-known/acme-challenge/httpcs-test
rm /var/www/html/.well-known/acme-challenge/httpcs-test

Expected result: HTTP/1.1 200 OK, then ok at the end of the response.

Provide DNS API access

acme.sh creates the validation TXT record itself through your DNS provider API. Export the credentials in the session: acme.sh saves them in /root/.acme.sh/account.conf during the first request and reuses them at every renewal. If possible, restrict the token to editing this zone.

acme.sh already installed: if these variables are already listed in the “Review” step for the same account, no need to export them again, acme.sh reads them back. Credentials saved for another provider stay untouched.

export CF_Token="TO_FILL_IN"
export CF_Zone_ID="TO_FILL_IN"

export OVH_END_POINT="TO_FILL_IN"
export OVH_AK="TO_FILL_IN"
export OVH_AS="TO_FILL_IN"
export OVH_CK="TO_FILL_IN"

export GANDI_LIVEDNS_TOKEN="TO_FILL_IN"

export INFOMANIAK_API_TOKEN="TO_FILL_IN"

export IONOS_PREFIX="TO_FILL_IN"
export IONOS_SECRET="TO_FILL_IN"

export SCALEWAY_API_TOKEN="TO_FILL_IN"

export AWS_ACCESS_KEY_ID="TO_FILL_IN"
export AWS_SECRET_ACCESS_KEY="TO_FILL_IN"

Export the variables listed for your provider in the acme.sh documentation, as export NAME="value".

Check that the zone is managed by this provider: the name servers shown must belong to it.

dig +short NS mydomain.tld

Get the certificate

acme.sh requests the certificate from the HTTPCS ACME server, performs the chosen validation and downloads the certificate to /root/.acme.sh/.

Keep the single quotes around '*.mydomain.tld': without them, the shell replaces * with the files of the current folder.

acme.sh --issue \
  --config-home /root/.acme.sh-httpcs-mydomain.tld \
  --server SERVER_URL \
  -d mydomain.tld \
  -w /var/www/html

acme.sh --issue \
  --config-home /root/.acme.sh-httpcs-mydomain.tld \
  --server SERVER_URL \
  -d mydomain.tld \
  --dns dns_xxx

acme.sh --issue \
  --config-home /root/.acme.sh-httpcs-mydomain.tld \
  --server SERVER_URL \
  -d mydomain.tld \
  --dns \
  --yes-I-know-dns-manual-mode-enough-go-ahead-please

Expected result: Cert success., followed by the certificate and key paths.

Expected result: acme.sh stops on purpose and prints, for each name, a Domain: '_acme-challenge.mydomain.tld' line and a TXT value: '…' line. Keep these values for the next step.

Organization certificate: the domain was already checked during the organization validation. acme.sh may then print Already verified, skip and go straight to issuance. This is expected.

Add the TXT records

In your DNS provider interface, create one TXT record for each value printed by acme.sh, on the _acme-challenge name. Most interfaces append the domain automatically: then enter only _acme-challenge, not the full name.

Wildcard: acme.sh prints two values for the same _acme-challenge.mydomain.tld name, one for the bare domain and one for *.mydomain.tld. Create two separate TXT records; do not replace the first one with the second.

Wait for propagation, then check that every value is visible:

dig +short TXT _acme-challenge.mydomain.tld @1.1.1.1

Once every value appears, complete the request:

acme.sh --renew \
  --config-home /root/.acme.sh-httpcs-mydomain.tld \
  -d mydomain.tld \
  --yes-I-know-dns-manual-mode-enough-go-ahead-please

Manual DNS mode does not renew by itself. ACME certificates are short-lived, a few months: you will have to repeat these steps before each expiry (notAfter date of the certificate). To automate, switch to automatic DNS as soon as possible.

Install the certificate

Copy the key and the full certificate (fullchain) to /etc/ssl. acme.sh remembers these paths and the reload command, and reuses them at every renewal. Never point the web server directly to the files in /root/.acme.sh/.

acme.sh --install-cert -d mydomain.tld \
  --config-home /root/.acme.sh-httpcs-mydomain.tld \
  --key-file /etc/ssl/private/mydomain.tld-acme.key \
  --fullchain-file /etc/ssl/certs/mydomain.tld-acme.crt \
  --reloadcmd "RELOAD_COMMAND"

Check that both files exist:

ls -l /etc/ssl/private/mydomain.tld-acme.key /etc/ssl/certs/mydomain.tld-acme.crt

Check that acme.sh remembered this installation. Without these settings, a renewal would not copy the files again nor reload the web server.

grep -o '^Le_\(RealKeyPath\|RealFullChainPath\|ReloadCmd\)' /root/.acme.sh/mydomain.tld_ecc/mydomain.tld.conf

Expected result: Le_RealKeyPath, Le_RealFullChainPath and Le_ReloadCmd.

See an example result

Configure the web server

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name mydomain.tld;

    ssl_certificate     /etc/ssl/certs/mydomain.tld-acme.crt;
    ssl_certificate_key /etc/ssl/private/mydomain.tld-acme.key;

    # rest of your existing configuration
}

nginx -t && systemctl reload nginx

<VirtualHost *:443>
    ServerName mydomain.tld
    ServerAlias *.mydomain.tld

    SSLEngine on
    SSLCertificateFile    /etc/ssl/certs/mydomain.tld-acme.crt
    SSLCertificateKeyFile /etc/ssl/private/mydomain.tld-acme.key

    # rest of your existing configuration
</VirtualHost>

a2enmod ssl
apachectl configtest && systemctl reload apache2

/etc/ssl/private/mydomain.tld-acme.key
/etc/ssl/certs/mydomain.tld-acme.crt

Check the certificate

Query the website the way a browser does:

openssl s_client -connect mydomain.tld:443 -servername mydomain.tld </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

Expected result: issuer mentions Sectigo or TrustSign, notAfter gives the expiry date and the X509v3 Subject Alternative Name line lists all your domains.

Wildcard: the list must contain DNS:*.mydomain.tld and DNS:mydomain.tld. To test a subdomain, replace the -servername value with this subdomain.

Then open the website in a browser and click the padlock: the certificate must be valid and issued by Sectigo or TrustSign.

See an example result

Check automatic renewal

acme.sh checks its certificates every day through cron. It renews this one before it expires, installs it again and runs the reload command, with no action from you.

(crontab -l; echo '0 4 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" --config-home "/root/.acme.sh-httpcs-mydomain.tld" > /dev/null') | crontab -

Manual DNS: no automatic renewal. Note the date in the Renew column and repeat the DNS steps before that date, or switch to automatic DNS.

crontab -l | grep acme.sh
acme.sh --list --config-home /root/.acme.sh-httpcs-mydomain.tld

Expected result: a cron line containing acme.sh --cron, and your domain in acme.sh --list with the next renewal date (Renew column).

Separate configuration: two acme.sh --cron lines, one of them with --config-home.

Check the duration of the installed certificate:

openssl x509 -noout -dates -in /etc/ssl/certs/mydomain.tld-acme.crt

Expected result: notAfter gives the expiry date. The date in the Renew column of acme.sh --list must come earlier: acme.sh renews well before expiry.

See an example result