DNS-01 ACME Challenges with easyDNS

Yes. easyDNS supports ACME DNS-01 certificate validation through the easyDNS REST API. This allows ACME clients such as Certbot, acme.sh and lego to automatically create and remove the _acme-challenge TXT records required by certificate authorities such as Let’s Encrypt. DNS-01 can also be used to obtain wildcard certificates.

This article explains how DNS-01 works with easyDNS, which ACME clients and reverse proxies support it, and how to troubleshoot validation. For step-by-step configuration of Certbot, acme.sh and lego, see How to Use Let’s Encrypt DNS-01 with easyDNS.

What DNS-01 is

ACME (Automatic Certificate Management Environment) is the protocol certificate authorities such as Let’s Encrypt use to automate certificate issuance and renewal. Before issuing a certificate, the CA must verify that the requester controls the domain names in it. ACME defines several “challenge” types for this; DNS-01 is the one that proves control through DNS.

During a DNS-01 challenge the ACME client places a temporary TXT record beneath the _acme-challenge label of the name being validated:

_acme-challenge.example.com.   300   IN   TXT   "<challenge-token>"

The CA queries DNS for that TXT record. If the expected token is present in the authoritative answer, validation succeeds and the certificate is issued. The ACME client then removes the temporary record.

easyDNS exposes zone and record management through its REST API, which is what allows an ACME client to create and delete the _acme-challenge TXT record without anyone logging into the control panel.

DNS-01 compared with HTTP-01

HTTP-01, the other common challenge type, proves control by serving a token file at http://example.com/.well-known/acme-challenge/. It is simple, but it requires the validated hostname to resolve to a server that is reachable from the public internet on port 80, and it cannot be used to issue wildcard certificates.

DNS-01 does not require the validated host to expose a public HTTP server at all. That makes it the right choice for:

  • wildcard certificates (*.example.com)
  • internal services and hostnames that only resolve on a private network
  • NAS devices and homelabs behind NAT
  • reverse proxies that terminate TLS for many backends
  • firewalled services where port 80 cannot or should not be opened
  • hosts with multiple web servers behind a load balancer

The trade-off is that the ACME client needs API credentials that can modify the DNS zone. See Credentials and security below.

Wildcard certificates

DNS-01 is the ACME validation method used to obtain wildcard certificates such as *.example.com. Let’s Encrypt and other ACME CAs only issue wildcard names via DNS-01; HTTP-01 and TLS-ALPN-01 cannot be used for them.

A certificate that covers both the apex and the wildcard:

example.com
*.example.com

requires a separate ACME validation for each identifier, and both validations use the same DNS name: _acme-challenge.example.com. The client will therefore create two TXT records at that name, one per challenge token, and the RRset must contain both values for the CA to validate both identifiers. The easyDNS integrations listed below handle this correctly; if you are writing your own integration, do not replace the RRset when adding the second value.

Supported ACME clients and reverse proxies

The following software can complete DNS-01 challenges against easyDNS zones. “Native” means the easyDNS provider ships with the software; “plugin” means an additional package must be installed first.

Software / ACME client easyDNS DNS-01 support Method
Certbot Yes Plugin: certbot-dns-easydns (maintained by easyDNS; on PyPI)
acme.sh Yes Native: dns_easydns provider
lego Yes Native: easydns DNS provider
Caddy Yes Module: caddy-dns/easydns (built into a custom Caddy binary with xcaddy)
Traefik Yes Native: Traefik uses lego, so provider: easydns with the lego environment variables
Nginx Proxy Manager Yes Built in: “easyDNS” appears in the DNS Provider list and NPM installs certbot-dns-easydns for you
LinuxServer SWAG Via plugin install easydns is not one of SWAG’s bundled DNSPLUGIN values; install certbot-dns-easydns with the universal-package-install mod

Anything else that embeds lego (for example many Go-based proxies and Kubernetes tooling) or that can call an external Certbot plugin can generally use the same integrations. Dedicated guides for Caddy, Traefik, Nginx Proxy Manager, SWAG, Synology and cert-manager are planned as companion articles to this one.

Credentials and security

Automated DNS-01 requires easyDNS API credentials with permission to modify the zone that contains the name being validated. The easyDNS REST API uses a user token and an API key; all of the integrations above accept those two values (plus the endpoint https://rest.easydns.net).

Because these credentials can change live DNS records, treat them like any other production secret:

  • Do not put credentials directly in scripts or configuration files that are committed to source control.
  • Use environment variables, a credentials file with restricted permissions (chmod 600), container or orchestrator secrets, or your CI system’s secret store, as appropriate for the environment.
  • Scope credentials as narrowly as the easyDNS API permits: use a dedicated API identity for certificate automation rather than reusing one that is also used for other tooling.
  • Rotate (regenerate) the API key immediately if it is accidentally exposed, for example by being pasted into a public issue tracker or committed to a repository.

API credentials are issued from the easyDNS control panel under User → Security → easyDNS REST API. The canonical API reference, including the request/response format for zone records, is at docs.sandbox.rest.easydns.net.

How automated validation works

The sequence for a DNS-01 issuance against an easyDNS zone is:

  1. The ACME client requests a certificate from the CA for one or more names.
  2. The CA returns a DNS-01 challenge token for each name.
  3. The easyDNS integration in the ACME client calls the easyDNS REST API.
  4. A TXT record is created at _acme-challenge.<name> containing the challenge value.
  5. The record becomes visible on the easyDNS authoritative nameservers.
  6. The CA queries DNS, finds the expected value, and marks the challenge valid.
  7. The CA issues the certificate and the client stores it.
  8. The integration deletes the temporary _acme-challenge TXT record.

On renewal the same sequence runs again automatically. Correctly configured, no one needs to create TXT records by hand.

Authoritative DNS and record visibility

The validation TXT record must ultimately be visible from the authoritative nameservers for the domain, which for an easyDNS-hosted zone are the easyDNS nameservers assigned to that domain (see easyDNS Nameservers).

This is not the same thing as general “DNS propagation”. A record created through the API is written to the easyDNS zone and published to the easyDNS authoritative nameservers; what matters for validation is the short interval between the API call and the moment all authoritative servers answer with the new RRset. Recursive resolver caches are mostly irrelevant, because the CA performs its own lookup from authoritative data (and because the _acme-challenge name usually has nothing cached for it).

The ACME clients handle this with a wait-and-check loop: lego’s easyDNS provider defaults to polling every 2 seconds for up to 60 seconds; certbot-dns-easydns waits a fixed --dns-easydns-propagation-seconds (default 120). If validation intermittently fails with “no TXT record found”, increase that wait before suspecting anything else.

One caveat: if the domain’s registrar-level NS delegation points somewhere other than easyDNS, creating the record in the easyDNS zone has no effect. Confirm the delegation with dig NS example.com before troubleshooting the integration.

Troubleshooting

The TXT record never appears

Check, in order: that the API token and key are correct and have not been regenerated; that the credentials belong to the account that owns the zone; that the zone in question is actually hosted on easyDNS; and that the integration is targeting the exact record name (_acme-challenge.example.com, not _acme-challenge.example.com.example.com). API error responses from the easyDNS endpoint usually say which of these it is.

The TXT record exists but validation fails

Query the authoritative nameservers directly rather than your local resolver:

# 1. find the authoritative nameservers for the zone
dig NS example.com +short

# 2. ask one of them directly (substitute a hostname from step 1)
dig @rush.easydns.com TXT _acme-challenge.example.com +short

easyDNS assigns different nameserver sets per service level, so always use the hostnames returned in step 1 rather than assuming. The expected token should appear in quotes. If it does not, the record has not reached the authoritative servers yet or was created under a different name. If it does, and the CA still reports failure, check that the CA’s own resolvers are not being blocked and that DNSSEC validation for the zone is intact (a broken DNSSEC chain will cause validating resolvers to return SERVFAIL for every name in the zone, including _acme-challenge).

Old _acme-challenge records remain

Leftover TXT records usually mean the ACME client’s cleanup step did not run, typically because the client was interrupted or the issuance failed before cleanup. They are harmless to leave in place but untidy; delete them in the easyDNS control panel or via the API. If they accumulate on every run, check whether the client is being killed before it finishes (for example by a short container or cron timeout).

Multiple TXT records at the same name

Do not assume that _acme-challenge.example.com should contain exactly one value. Validating example.com and *.example.com in a single order, or running two ACME clients for the same domain, legitimately produces an RRset with more than one TXT value. The CA only needs its own token to be among them. Integrations that “fix” this by deleting the other values will break concurrent validations.

CNAME delegation of _acme-challenge

ACME CAs follow CNAMEs when looking up _acme-challenge. Some deployments use this to delegate the challenge name to a separate zone or provider (for example a dedicated validation zone, or acme-dns), so that the production zone’s API credentials never leave a secure host. That is a different architecture from the direct API integration described in this article: with delegation, the ACME client updates the target of the CNAME, and the easyDNS zone only holds a static CNAME record. If you use delegation, troubleshoot the record at the CNAME target, not in the easyDNS zone.

Testing and interoperability

easyDNS maintains the certbot-dns-easydns plugin and is developing automated interoperability tests for its DNS-01 integrations against the Let’s Encrypt staging environment. When that test harness is public, this section will list the last successful run, the ACME client versions exercised, the CA environment used, and a link to the test repository.

If you find a DNS-01 integration that fails against an easyDNS zone, please open an issue on the relevant upstream repository and copy easyDNS support so it can be reproduced.

Frequently asked questions

Does easyDNS support DNS-01?

Yes. easyDNS supports ACME DNS-01 validation through its REST API, which ACME clients use to create and remove _acme-challenge TXT records automatically.

Can I use Let’s Encrypt with easyDNS?

Yes. Any Let’s Encrypt client that supports the DNS-01 challenge with an easyDNS provider (Certbot with the easyDNS plugin, acme.sh, lego, Caddy, Traefik, Nginx Proxy Manager) can obtain and renew Let’s Encrypt certificates for domains whose DNS is hosted at easyDNS.

Can easyDNS automate wildcard certificates?

Yes. Wildcard certificates such as *.example.com require DNS-01 validation, and easyDNS’s API support for DNS-01 makes that automation possible with any supported ACME client.

Does Certbot support easyDNS?

Yes, through the certbot-dns-easydns authenticator plugin published by easyDNS on PyPI. Install it alongside Certbot and run Certbot with --authenticator dns-easydns.

Does acme.sh support easyDNS?

Yes. acme.sh includes a native dns_easydns provider; set EASYDNS_Token and EASYDNS_Key and issue with --dns dns_easydns.

Does lego support easyDNS?

Yes. lego includes a native easydns DNS provider configured with the EASYDNS_TOKEN and EASYDNS_KEY environment variables. Software built on lego, including Traefik, inherits this support.

Does Caddy support easyDNS DNS-01?

Yes, through the caddy-dns/easydns DNS provider module, which is compiled into Caddy with xcaddy and configured with your easyDNS API token and key.

References

Related easyDNS articles

Related Articles

Leave a Reply