ACME DNS-01 with acme.sh / certbot

← Docs

The DNS-01 challenge lets you issue Let's Encrypt certificates — including wildcards (*.domain.tld) — without exposing port 80/443. Your ACME client asks PrimeDNS to create a _acme-challenge TXT record, Let's Encrypt verifies it over DNS, and the client removes it again.

1. Create an API key

Go to Account → API Keys and create a key with the dns:write scope. You'll set it as PRIMEDNS_API_KEY below.

Create new API key form with dns:write scope checked

Option A: acme.sh

Drop the PrimeDNS hook 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

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 — no further action needed.

Option B: certbot (manual hooks)

Download the auth and cleanup hooks and make them executable:

curl -o /usr/local/bin/primedns-auth.sh \
  https://primedns.net/media/com_primedns/acme-sh/primedns-auth.sh
curl -o /usr/local/bin/primedns-cleanup.sh \
  https://primedns.net/media/com_primedns/acme-sh/primedns-cleanup.sh
chmod +x /usr/local/bin/primedns-auth.sh /usr/local/bin/primedns-cleanup.sh

Set your API key and run certbot:

export PRIMEDNS_API_KEY="pdns_xxxxxxxxxxxxxxxxxxxx"

certbot certonly \
  --manual --preferred-challenges dns \
  --manual-auth-hook    /usr/local/bin/primedns-auth.sh \
  --manual-cleanup-hook /usr/local/bin/primedns-cleanup.sh \
  -d domain.tld -d '*.domain.tld'

certbot does not auto-renew manual-hook certificates by default. Add a cron job that re-runs the same command (with PRIMEDNS_API_KEY exported) and passes --non-interactive, or use the renewal config hooks certbot writes under /etc/letsencrypt/renewal/.

Troubleshooting

  • DOMAIN_NOT_FOUND — the domain in -d isn't in your PrimeDNS account, or the API key belongs to a different account/team.
  • 403 — the API key is missing the dns:write scope.
  • 422 — domain or value missing from the request; check the hook is passing certbot/acme.sh's environment variables through correctly.