ACME DNS-01 with lego

lego is an ACME client written in Go. With its PrimeDNS DNS provider it proves control of your domain through the DNS-01 challenge, including wildcards (*.domain.tld), without exposing port 80/443. Traefik's built-in DNS challenge uses lego, so the same provider is available there, see Traefik. How the challenge works with PrimeDNS is explained in ACME DNS-01 certificates with PrimeDNS.

You need lego 5.6.0 or newer (check with lego --version), a zone in your PrimeDNS account and an API key.

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). The key can only write the _acme-challenge names you list, nothing else in your zones.

2. Try it with the staging CA

The Let's Encrypt staging CA issues certificates that browsers do not trust, but it checks the whole path (key, zone, DNS record, validation) without using the limits of the real CA. Run it once before the real certificate:

export PRIMEDNS_API_KEY="pdns_xxxxxxxxxxxxxxxxxxxx"

lego run --dns primedns --server letsencrypt-staging \
  --path /var/lib/lego --email you@domain.tld --accept-tos \
  -d domain.tld -d '*.domain.tld'

lego writes the certificate and the private key under the --path directory. It adds the validation record, waits until the record is visible, asks the CA to validate and removes the record again. If the check times out, raise the propagation timeout with PRIMEDNS_PROPAGATION_TIMEOUT (in seconds).

3. Issue the real certificate

The same command without --server uses the real Let's Encrypt CA:

lego run --dns primedns --path /var/lib/lego \
  --email you@domain.tld --accept-tos \
  -d domain.tld -d '*.domain.tld'

Keep the key out of your shell history

Instead of exporting the key, put it in a file only you can read and point lego at the file with PRIMEDNS_API_KEY_FILE:

install -d -m 700 /etc/lego
printf '%s' 'pdns_xxxxxxxxxxxxxxxxxxxx' > /etc/lego/primedns-key
chmod 600 /etc/lego/primedns-key

export PRIMEDNS_API_KEY_FILE=/etc/lego/primedns-key

Renewal

Run the same lego run command again later: lego renews the certificate when it is due and does nothing before that. A daily cron job with a deploy hook that reloads your web server keeps the certificate current:

17 3 * * *  PRIMEDNS_API_KEY_FILE=/etc/lego/primedns-key lego run --dns primedns --path /var/lib/lego \
  --email you@domain.tld --accept-tos -d domain.tld -d '*.domain.tld' \
  --deploy-hook "nginx -s reload"

The hook runs after a certificate was issued or renewed. Replace the reload command with the one for your server.

On a systemd host a timer does the same. The service:

# /etc/systemd/system/lego-renew.service
[Unit]
Description=Renew certificates with lego

[Service]
Type=oneshot
Environment=PRIMEDNS_API_KEY_FILE=/etc/lego/primedns-key
ExecStart=/usr/local/bin/lego run --dns primedns --path /var/lib/lego \
  --email you@domain.tld --accept-tos -d domain.tld -d '*.domain.tld' \
  --deploy-hook "systemctl reload nginx"

and the timer that starts it every day at a random minute:

# /etc/systemd/system/lego-renew.timer
[Unit]
Description=Daily lego renewal check

[Timer]
OnCalendar=daily
RandomizedDelaySec=1h
Persistent=true

[Install]
WantedBy=timers.target
systemctl daemon-reload
systemctl enable --now lego-renew.timer

Docker

The official goacme/lego image includes the PrimeDNS provider from version 5.6.0. Keep lego's data (account, certificates) in a directory on the host:

mkdir -p .lego

docker run --rm \
  -e PRIMEDNS_API_KEY="pdns_xxxxxxxxxxxxxxxxxxxx" \
  -v "$PWD/.lego:/.lego" \
  goacme/lego:v5.6.0 run \
  --dns primedns --email you@domain.tld --accept-tos \
  -d domain.tld -d '*.domain.tld'

To keep the key out of the process list, mount the key file read-only and pass its path instead:

docker run --rm \
  -e PRIMEDNS_API_KEY_FILE=/run/secrets/primedns_key \
  -v /etc/lego/primedns-key:/run/secrets/primedns_key:ro \
  -v "$PWD/.lego:/.lego" \
  goacme/lego:v5.6.0 run \
  --dns primedns --email you@domain.tld --accept-tos \
  -d domain.tld -d '*.domain.tld'

The certificate and key are written to .lego/certificates/. Run the same command again to renew, for example from cron.

Traefik

Traefik uses lego for its DNS challenge, so with a Traefik release that includes lego 5.6.0 or newer the provider name is primedns and the credential is the same environment variable:

certificatesResolvers:
  primedns:
    acme:
      email: you@domain.tld
      storage: /letsencrypt/acme.json
      dnsChallenge:
        provider: primedns

Pass PRIMEDNS_API_KEY to the Traefik container as an environment variable.

Caddy

Let lego issue and renew the certificate and point Caddy at the files. The deploy hook reloads Caddy after each renewal (--deploy-hook "systemctl reload caddy"):

domain.tld, *.domain.tld {
  tls /var/lib/lego/certificates/domain.tld.crt /var/lib/lego/certificates/domain.tld.key
  reverse_proxy 127.0.0.1:8080
}

CAA records

If your domain has CAA records, they must allow the CA, otherwise the CA refuses to issue. For Let's Encrypt add these two records (the second one covers wildcard names):

domain.tld.  CAA  0 issue "letsencrypt.org"
domain.tld.  CAA  0 issuewild "letsencrypt.org"

In PrimeDNS create them with type CAA, name @ and the text after CAA as the content. Check what is published with dig CAA domain.tld +short.

Settings

VariableMeaning
PRIMEDNS_API_KEYThe API key. Required, unless you use PRIMEDNS_API_KEY_FILE.
PRIMEDNS_API_KEY_FILEPath of a file that holds the key.
PRIMEDNS_PROPAGATION_TIMEOUTHow long lego waits for the record to become visible, in seconds (default 180).
PRIMEDNS_POLLING_INTERVALSeconds between visibility checks (default 2).
PRIMEDNS_HTTP_TIMEOUTTimeout of a single API request, in seconds (default 30).

CNAME delegation

lego follows a CNAME on _acme-challenge by itself and writes the validation record at the target. Point the CNAME at a name in a zone of your PrimeDNS account and give the key the scope for that target, see CNAME delegation.

Troubleshooting

  • lego does not know the provider primedns: your lego is older than 5.6.0. Update it.
  • some credentials information are missing: PRIMEDNS_API_KEY: the variable is not set in the environment lego runs in (cron jobs and containers do not see your shell's variables), or the key file cannot be read.
  • NAME_NOT_ALLOWED (403): the key is not allowed to write the _acme-challenge name of that hostname. Add the hostname to the key.
  • The CA says CAA forbids issuance: your CAA records do not name the CA, see CAA records.
  • The check times out: raise PRIMEDNS_PROPAGATION_TIMEOUT. Other errors from the API and from the CA are listed in the overview.

Questions

Which lego version do I need? 5.6.0 or newer, that is the first one with the PrimeDNS provider.

Can one certificate cover the domain and its wildcard? Yes. List both, -d domain.tld -d '*.domain.tld', and lego validates them in one run.

Can the key be limited to one hostname? Yes. A certificate key writes only the _acme-challenge names you list, see Create an API key.

My DNS is elsewhere, can I still use PrimeDNS for the challenge? Yes, with a CNAME on _acme-challenge, see CNAME delegation.