ACME / auto-TLS

Wildcard certificates (*.example.com) require Let's Encrypt's DNS-01 challenge. PDNS Manager ships its own token system that does exactly what's needed – nothing more.

The security model

An ACME token has the prefix dnsmgr_acme_ and is restricted to exactly these operations:

• Write a TXT record named _acme-challenge.<domain>.
• Delete the same TXT record after successful validation.

It can only act in allowed zones (allowed_zones) and only on records whose name starts with _acme-challenge.. Even if an attacker grabs the token, they can not touch A/MX/NS records, create or delete zones, or change settings.

Create a token

As admin: Settings → ACME tokens → New token:

• Name – e.g. "cert-renewer-vm1".
• Allowed zones – comma list, longest match. example.com covers both example.com and foo.example.com.
• Expiry – optional date.

On save the token is shown once in plain text – copy it straight to where it's needed (e.g. /etc/dnsmgr.env on the cert-renewer host). Only a SHA-256 hash is stored in the DB; lost tokens can not be recovered, only replaced.

Use with certbot

The repo ships scripts/certbot-dns-dnsmanager.sh. Prep on the cert-renewer host:

sudo cp certbot-dns-dnsmanager.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/certbot-dns-dnsmanager.sh

sudo install -m 600 /dev/stdin /etc/dnsmgr.env <<EOF
DNSMGR_URL=https://pdns.example.com
DNSMGR_TOKEN=dnsmgr_acme_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DNSMGR_PROPAGATE_SECONDS=30
EOF

Request a cert:

certbot certonly \
  --manual --preferred-challenges dns \
  --manual-auth-hook   /usr/local/bin/certbot-dns-dnsmanager.sh \
  --manual-cleanup-hook /usr/local/bin/certbot-dns-dnsmanager.sh \
  -d "*.example.com" -d "example.com"

What the hook does: read certbot's CERTBOT_DOMAIN and CERTBOT_VALIDATION env vars, decide between present and cleanup based on CERTBOT_AUTH_OUTPUT, and post the right JSON to /api/v1/acme/present or /api/v1/acme/cleanup.

Automate renewal

Just put certbot renew into a cron or systemd timer. Hooks are stored in the renewal config, so it all runs without intervention.

Audit log

action=ACME_PRESENT  resource=_acme-challenge.example.com  user=acme:cert-renewer-vm1
action=ACME_CLEANUP  resource=_acme-challenge.example.com  user=acme:cert-renewer-vm1

So you immediately spot a stuck renewer or a token used unexpectedly.

Rotating tokens

Delete the old one in the panel, create a new one, set the new value in /etc/dnsmgr.env on the cert host, done. Existing certs stay valid – they're already issued.