Let's Encrypt DNS-01 Challenges with DNScale

Let's Encrypt supports three ACME challenge types: HTTP-01, TLS-ALPN-01, and DNS-01. For most public websites, HTTP-01 is the default because it's simple — a file on port 80 proves you control the domain. But when HTTP-01 doesn't fit, DNS-01 is the escape hatch: instead of proving control via HTTP, you prove it by placing a TXT record in DNS.

DNScale's API lets any ACME client automate DNS-01 challenges against your zones. This guide covers when to use DNS-01, and how to set it up with the four most common Let's Encrypt clients.

When to use DNS-01

HTTP-01 breaks in four common situations:

• Wildcard certificates (*.example.com). Let's Encrypt does not support HTTP-01 for wildcards — DNS-01 is the only option.
• Servers behind edge proxies or CDNs. If your origin sits behind a proxy (DNScale's Postscale edge network, Cloudflare, an ADC, etc.) the origin can't receive HTTP-01 validation traffic. DNS-01 bypasses the data plane entirely.
• No port 80 exposed. Firewalled origins, internal services, mail servers, and hosts behind strict NATs often have no public HTTP listener. DNS-01 needs no HTTP endpoint.
• Private or internal hostnames that still resolve publicly (split-horizon DNS, lab environments). HTTP-01 can't reach them; DNS-01 only needs DNS reachability for the ACME validator.

If none of those apply, HTTP-01 is usually simpler — fewer moving parts, no API token to manage. DNS-01 is worth the extra setup only when you need it.

Tip: DNS-01 plays nicely with CAA records. Set 0 issue "letsencrypt.org" on your zone, and Let's Encrypt will be the only CA that can issue for it regardless of challenge type.

How DNS-01 works

For each domain on a certificate request, Let's Encrypt asks the client to publish a TXT record at _acme-challenge.<domain> containing a specific value. The ACME validator then queries public DNS for that record. If the value matches, the challenge passes.

Your ACME client drives three steps on each issuance or renewal:

1. Add — create the TXT record via the DNScale API
2. Wait — give the record time to propagate across DNScale's authoritative nameservers
3. Clean up — delete the TXT record after validation completes

All four clients covered below automate this flow end-to-end.

API token setup

Before any client can use DNS-01, create a DNScale API token:

1. Sign in at dnscale.eu.
2. Go to Dashboard → API Keys and create a new key.
3. Grant the minimum scopes: zones:read, records:read, records:write.
4. Scope the key to specific zones if you can — e.g. only example.com if that's the only domain the client will renew.

Store the token as you would any other secret: a file with mode 600, a secret manager, or an environment variable in your CI/CD pipeline. Never check it into a public repository.

Tip: Separate tokens per client. If certbot and cert-manager both issue certs on different hosts, use two tokens so you can rotate one without disrupting the other.

Client: certbot

The certbot-dns-dnscale plugin is published on PyPI.

pip install certbot-dns-dnscale

Create the credentials file:

# /etc/letsencrypt/dnscale.ini
dns_dnscale_api_token = <your-token>

chmod 600 /etc/letsencrypt/dnscale.ini

Issue a certificate:

certbot certonly \
  --authenticator dns-dnscale \
  --dns-dnscale-credentials /etc/letsencrypt/dnscale.ini \
  --dns-dnscale-propagation-seconds 60 \
  -d example.com \
  -d "*.example.com"

Subsequent renewals (certbot renew) automatically use the same authenticator — certbot stores the choice in /etc/letsencrypt/renewal/<name>.conf.

To convert an existing certificate from HTTP-01 to DNS-01, edit its renewal config:

[renewalparams]
authenticator = dns-dnscale
dns_dnscale_credentials = /etc/letsencrypt/dnscale.ini
dns_dnscale_propagation_seconds = 60

Remove any webroot_path, standalone, or [[webroot_map]] leftover from the old authenticator.

Client: lego v5+

lego is the Go ACME client and library behind many DNS-01 integrations. DNScale is available in lego v5+ as provider code dnscale.

For a dedicated walkthrough with systemd, Docker, and external Caddy/Traefik certificate-file examples, see lego DNS-01 with the DNScale DNS Provider.

lego CLI:

export DNSCALE_API_TOKEN="<your-token>"
 
lego \
  --accept-tos \
  --email you@example.com \
  --dns dnscale \
  --domains example.com \
  --domains "*.example.com" \
  run

Use the Let's Encrypt staging directory before the first production run:

DNSCALE_API_TOKEN="<your-token>" lego \
  --server https://acme-staging-v02.api.letsencrypt.org/directory \
  --accept-tos \
  --email you@example.com \
  --dns dnscale \
  --domains example.com \
  --domains "*.example.com" \
  run

Secret-file form:

sudo install -d -m 700 /etc/lego
printf '%s' '<your-token>' | sudo tee /etc/lego/dnscale-token >/dev/null
sudo chmod 600 /etc/lego/dnscale-token
 
DNSCALE_API_TOKEN_FILE=/etc/lego/dnscale-token lego \
  --accept-tos \
  --email you@example.com \
  --dns dnscale \
  --domains example.com \
  --domains "*.example.com" \
  run

Docker:

docker run --rm \
  -e DNSCALE_API_TOKEN="<your-token>" \
  -v "$PWD/.lego:/root/.lego" \
  goacme/lego:v5.2.0 \
  --accept-tos \
  --email you@example.com \
  --dns dnscale \
  --domains example.com \
  --domains "*.example.com" \
  run

Useful DNScale-specific lego environment variables:

lego stores issued certificates under .lego/certificates/ by default. For unattended renewals, run the same command with renew instead of run from a systemd timer, cron job, or CI job that can read the token secret.

Client: acme.sh

The DNScale API plugin ships with acme.sh.

export DNSCALE_Token=<your-token>
acme.sh --issue --dns dns_dnscale -d example.com -d "*.example.com"

acme.sh saves the token to ~/.acme.sh/account.conf on first use, so subsequent renewals don't need the env var. To rotate, edit that file or pass --renew-with-dnsapi dns_dnscale on the next renewal.

Client: cert-manager (Kubernetes)

For Kubernetes workloads, DNScale's cert-manager webhook plugs into cert-manager's external webhook interface.

1. Install the webhook via Helm:

   Copy

   helm install cert-manager-webhook-dnscale \
     oci://ghcr.io/dnscaleou/charts/cert-manager-webhook-dnscale \
     --namespace cert-manager

2. Store the token as a Kubernetes secret:

   Copy

   apiVersion: v1
   kind: Secret
   metadata:
     name: dnscale-api-token
     namespace: cert-manager
   stringData:
     api-token: <your-token>

3. Define a ClusterIssuer referencing the webhook:

   Copy

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: letsencrypt-dnscale
   spec:
     acme:
       email: you@example.com
       server: https://acme-v02.api.letsencrypt.org/directory
       privateKeySecretRef:
         name: letsencrypt-dnscale-account-key
       solvers:
         - dns01:
             webhook:
               groupName: acme.dnscale.eu
               solverName: dnscale
               config:
                 apiTokenSecretRef:
                   name: dnscale-api-token
                   key: api-token

4. Request a certificate as usual — cert-manager will drive DNS-01 through the webhook.

Common pitfalls

Propagation too short

ACME validators cache DNS. If your client's propagation wait is shorter than the TTL of negative caches and nearby resolvers, validation will fail. Start at 60 seconds. If you see intermittent failures, raise to 120.

With lego, tune the DNScale provider rather than adding an unrelated global delay:

DNSCALE_PROPAGATION_TIMEOUT=120 \
DNSCALE_POLLING_INTERVAL=5 \
DNSCALE_TTL=120 \
DNSCALE_API_TOKEN="<your-token>" \
lego --accept-tos --email you@example.com --dns dnscale \
  -d example.com -d "*.example.com" run

lego says the provider is unknown

If lego returns an error such as unrecognized DNS provider: dnscale, the binary is too old. DNScale support starts with lego v5. Check the version:

lego --version

Upgrade the standalone CLI, or wait for the product embedding lego to ship a build based on lego v5 or newer. This matters for Traefik and other Go products that vendor lego internally: their supported provider list is the provider list in the embedded lego version, not the list on your workstation.

Missing or unreadable token

The lego provider expects DNSCALE_API_TOKEN or DNSCALE_API_TOKEN_FILE. The _FILE value must point to a file containing only the token value:

sudo install -d -m 700 /etc/lego
printf '%s' '<your-token>' | sudo tee /etc/lego/dnscale-token >/dev/null
sudo chmod 600 /etc/lego/dnscale-token
 
DNSCALE_API_TOKEN_FILE=/etc/lego/dnscale-token lego \
  --accept-tos --email you@example.com --dns dnscale \
  -d example.com -d "*.example.com" run

CNAME delegation

If _acme-challenge.example.com is a CNAME to another name (a common pattern for delegating DNS-01 to a separate zone), the ACME validator follows the CNAME — but your ACME client must publish the TXT at the target of the CNAME, not at _acme-challenge.example.com itself. All four clients above handle this automatically if configured with the correct zone.

CAA blocking Let's Encrypt

If your zone has a 0 issue "other-ca.com" CAA record and no entry for letsencrypt.org, Let's Encrypt will refuse to issue. Before moving a domain to DNS-01, confirm CAA allows the CA you're using:

dig CAA example.com +short

Orphan _acme-challenge.* TXT records

If cleanup fails silently (API error, plugin bug, client crash) the challenge TXT record may linger on your zone. These don't affect future issuance (every renewal uses a fresh random value), but they can clutter the zone over time. Periodically delete any _acme-challenge.* TXT records older than a few hours.

For lego renewals, orphan records usually mean the challenge process was interrupted after validation but before cleanup. Confirm the token has record delete permission and rerun the command once; if cleanup still fails, inspect the DNScale API response in lego's debug output:

DNSCALE_API_TOKEN="<your-token>" lego \
  --debug \
  --accept-tos --email you@example.com --dns dnscale \
  -d example.com -d "*.example.com" renew

Rate limits

Let's Encrypt limits 50 certificates per registered domain per week and 5 duplicate certs per week. DNS-01 doesn't change these limits — but if your client is stuck in a retry loop (e.g. a misconfigured propagation wait causing repeated failures) you can burn through the duplicate cert limit quickly. Always run --dry-run first when changing client or zone setup.

Which client should you pick?

• Standalone host with a single cert — certbot. Familiar, well-documented, ships in every distro.
• Go-stack or standalone certificate runner — use lego v5+. It is a single binary and now has DNScale built in.
• Traefik already in your stack — use Traefik's DNS challenge once your Traefik version embeds lego v5 or newer; older builds do not know provider dnscale.
• Caddy already in your stack — keep Caddy serving certificates from disk or use another ACME client until a native DNScale Caddy DNS module exists.
• Minimal, shell-only host — acme.sh. No Python, no compiled binary, just bash.
• Kubernetes — cert-manager with the DNScale webhook.

For production today, choose a client that already has a DNScale integration in the version you run. Pick by where the rest of your infrastructure already sits.