--- title: "DNS-01 ACME Challenges with easyDNS" type: "knowledge" post_id: "5930" slug: "dns-01-acme-challenges-easydns" canonical: "https://kb.easydns.com/knowledge/dns-01-acme-challenges-easydns/" markdown_url: "https://kb.easydns.com/knowledge/dns-01-acme-challenges-easydns.md" json_url: "https://kb.easydns.com/knowledge/dns-01-acme-challenges-easydns.json" txt_url: "https://kb.easydns.com/knowledge/dns-01-acme-challenges-easydns.txt" published: "2026-10-19T20:35:35+00:00" modified: "2026-10-19T20:35:35+00:00" author: "Mark Jeftovic" categories: tags: site_name: "easyDNS Knowledge Base" publisher: "easyDNS Technologies Inc." language: "en-US" generator: "easyPress Markdown" generator_version: "1.0.6" --- **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](https://kb.easydns.com/knowledge/lets-encrypt-dns-01-easydns/). What DNS-01 is -------------- [ACME](https://datatracker.ietf.org/doc/html/rfc8555) (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 "" ``` 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](https://letsencrypt.org/docs/challenge-types/). 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](#credentials) 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 clienteasyDNS DNS-01 supportMethod[Certbot](https://certbot.eff.org/)YesPlugin: [`certbot-dns-easydns`](https://github.com/easydns/certbot-dns-easydns) (maintained by easyDNS; [on PyPI](https://pypi.org/project/certbot-dns-easydns/))[acme.sh](https://github.com/acmesh-official/acme.sh)YesNative: [`dns_easydns`](https://github.com/acmesh-official/acme.sh/wiki/dnsapi2#dns_easydns) provider[lego](https://go-acme.github.io/lego/)YesNative: [`easydns`](https://go-acme.github.io/lego/dns/easydns/) DNS provider[Caddy](https://caddyserver.com/)YesModule: [`caddy-dns/easydns`](https://github.com/caddy-dns/easydns) (built into a custom Caddy binary with xcaddy)[Traefik](https://traefik.io/)YesNative: Traefik uses lego, so `provider: easydns` with the lego environment variables[Nginx Proxy Manager](https://nginxproxymanager.com/)YesBuilt in: “easyDNS” appears in the DNS Provider list and NPM installs `certbot-dns-easydns` for you[LinuxServer SWAG](https://github.com/linuxserver/docker-swag)Via plugin installeasydns is not one of SWAG’s bundled `DNSPLUGIN` values; install `certbot-dns-easydns` with the universal-package-install modAnything 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](https://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.` 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](https://kb.easydns.com/knowledge/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](https://github.com/joohoi/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](https://github.com/easydns/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](https://easydns.com/contact-us/) 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 ---------- - easyDNS REST API documentation: [docs.sandbox.rest.easydns.net](https://docs.sandbox.rest.easydns.net/) - Let’s Encrypt, [Challenge Types](https://letsencrypt.org/docs/challenge-types/) - RFC 8555, [Automatic Certificate Management Environment (ACME) §8.4 DNS Challenge](https://datatracker.ietf.org/doc/html/rfc8555#section-8.4) - Certbot easyDNS plugin: [github.com/easydns/certbot-dns-easydns](https://github.com/easydns/certbot-dns-easydns) / [PyPI](https://pypi.org/project/certbot-dns-easydns/) - acme.sh easyDNS provider: [dnsapi2 wiki – dns\_easydns](https://github.com/acmesh-official/acme.sh/wiki/dnsapi2#dns_easydns) - lego easyDNS provider: [go-acme.github.io/lego/dns/easydns](https://go-acme.github.io/lego/dns/easydns/) - Caddy easyDNS module: [github.com/caddy-dns/easydns](https://github.com/caddy-dns/easydns) - Traefik ACME certificate resolvers and DNS challenge: [doc.traefik.io](https://doc.traefik.io/traefik/reference/install-configuration/tls/certificate-resolvers/acme/) - Nginx Proxy Manager Certbot DNS plugin list: [dns-plugins.json](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/develop/backend/certbot/dns-plugins.json) - LinuxServer SWAG: [github.com/linuxserver/docker-swag](https://github.com/linuxserver/docker-swag) Related easyDNS articles ------------------------ - [How to Use Let’s Encrypt DNS-01 with easyDNS](https://kb.easydns.com/knowledge/lets-encrypt-dns-01-easydns/) (Certbot, acme.sh and lego walkthroughs) - [How To Edit DNS Records](https://kb.easydns.com/knowledge/how-to-make-a-dns-entry/) - [easyDNS Nameservers](https://kb.easydns.com/knowledge/easydns-nameservers/) - [DNSSEC](https://kb.easydns.com/knowledge/dnssec-v3/) - [SSL Certificates](https://kb.easydns.com/knowledge/ssl-certificates/) (commercial certificates sold by easyDNS) - [easyDNS DNS hosting plans](https://easydns.com/dns/)