ACME DNS-01 with acme.sh

2 min read Updated

Contents

acme.sh issues and renews Let's Encrypt certificates from a shell script. With the PrimeDNS DNS API plugin it proves control of your domain through the DNS-01 challenge, including wildcards (*.domain.tld), without exposing port 80/443. How the challenge works with PrimeDNS is explained in ACME DNS-01 certificates with PrimeDNS.

1. Create an API key

In Account → API Keys choose Certificate key and list each hostname you will issue a certificate for (details: Create an API key). You'll set the key as PRIMEDNS_API_KEY below.

2. Install the plugin

Drop the PrimeDNS plugin into acme.sh's dnsapi directory:

curl -o ~/.acme.sh/dnsapi/dns_primedns.sh \
  https://primedns.net/media/com_primedns/acme-sh/dns_primedns.sh

3. Issue the certificate

Set your API key and issue the certificate:

export PRIMEDNS_API_KEY="pdns_xxxxxxxxxxxxxxxxxxxx"

acme.sh --issue --dns dns_primedns \
  -d domain.tld -d '*.domain.tld'
Tip: acme.sh defaults to ZeroSSL as CA. If issuance hangs at the finalize step, pin Let's Encrypt instead: acme.sh --issue --server letsencrypt --dns dns_primedns -d domain.tld, or set it permanently with acme.sh --set-default-ca --server letsencrypt.

acme.sh installs a cron job on first --issue and renews automatically, so no further action is needed.

CNAME delegation

For a domain whose DNS is hosted elsewhere, use acme.sh's alias mode. Add the CNAME at the other provider and tell acme.sh where it leads. With _acme-challenge.shop.example.com pointing to _acme-challenge.validation.example.net (a zone in your PrimeDNS account):

export PRIMEDNS_API_KEY="pdns_xxxxxxxxxxxxxxxxxxxx"

acme.sh --issue --dns dns_primedns \
  -d shop.example.com --challenge-alias validation.example.net

If the CNAME points to validation.example.net without the _acme-challenge. prefix, use --domain-alias validation.example.net instead. The key scopes for both forms and the full explanation are in CNAME delegation.

Troubleshooting

Errors from the API (DOMAIN_NOT_FOUND, 403, NXDOMAIN reported by the CA) and their fixes are listed in the overview. Run acme.sh with --debug to see the API request and answer.