--- title: "How to Use Let’s Encrypt DNS-01 with easyDNS" type: "knowledge" post_id: "5931" slug: "lets-encrypt-dns-01-easydns" canonical: "https://kb.easydns.com/knowledge/lets-encrypt-dns-01-easydns/" markdown_url: "https://kb.easydns.com/knowledge/lets-encrypt-dns-01-easydns.md" json_url: "https://kb.easydns.com/knowledge/lets-encrypt-dns-01-easydns.json" txt_url: "https://kb.easydns.com/knowledge/lets-encrypt-dns-01-easydns.txt" published: "2026-10-19T20:36:32+00:00" modified: "2026-10-19T20:36:32+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" --- **easyDNS customers can automate Let’s Encrypt certificate issuance and renewal using ACME DNS-01 validation.** The easyDNS REST API allows supported ACME clients to create and remove the required `_acme-challenge` TXT records automatically, including for wildcard certificates. This article is the hands-on companion to [DNS-01 ACME Challenges with easyDNS](https://kb.easydns.com/knowledge/dns-01-acme-challenges-easydns/), which explains how the challenge works and which software supports it. Here we configure the three most widely used ACME clients: - [Certbot](#certbot), with the `certbot-dns-easydns` plugin - [acme.sh](#acmesh), with its native `dns_easydns` provider - [lego](#lego), with its native `easydns` provider All examples use `example.com`; substitute your own domain. None of the credential values shown are real. Before you begin ---------------- You need: - A domain whose authoritative DNS is hosted at easyDNS. Check with `dig NS example.com +short`; the answer should be easyDNS nameservers (see [easyDNS Nameservers](https://kb.easydns.com/knowledge/easydns-nameservers/)). - easyDNS REST API credentials: a **user token** and an **API key**. These are issued from the easyDNS control panel under **User → Security → easyDNS REST API**. Refer to the [easyDNS API documentation](https://docs.sandbox.rest.easydns.net/) for the current signup and access process. - An ACME client (one of the three below) installed on a host that can reach both the Let’s Encrypt API and `https://rest.easydns.net`. - The credentials must belong to the easyDNS account that holds the zone, so that they have permission to modify its records. The API endpoint for live zones is `https://rest.easydns.net`. Each client below needs that value plus the token and key. Method 1: Certbot with certbot-dns-easydns ------------------------------------------ [certbot-dns-easydns](https://github.com/easydns/certbot-dns-easydns) is the DNS authenticator plugin for Certbot, maintained by easyDNS and published on [PyPI](https://pypi.org/project/certbot-dns-easydns/). ### Install Install the plugin into the same Python environment as Certbot. If Certbot itself was installed with pip: ``` pip install certbot certbot-dns-easydns ``` If Certbot was installed via snap, the plugin must be installed as a snap too, or Certbot will not see it. Where no easydns snap is available, install Certbot with pip (in a virtualenv) instead of snap. Confirm the plugin is visible with: ``` certbot plugins ``` The output should list `dns-easydns`. ### Create the credentials file Create an INI file readable only by root, for example `/etc/letsencrypt/.secrets/easydns.ini`: ``` dns_easydns_usertoken = your-easydns-user-token dns_easydns_userkey = your-easydns-api-key dns_easydns_endpoint = https://rest.easydns.net ``` ``` sudo mkdir -p /etc/letsencrypt/.secrets sudo chown root:root /etc/letsencrypt/.secrets /etc/letsencrypt/.secrets/easydns.ini sudo chmod 700 /etc/letsencrypt/.secrets sudo chmod 600 /etc/letsencrypt/.secrets/easydns.ini ``` Certbot will warn (and in some versions refuse to run) if the credentials file is readable by other users. ### Request a certificate ``` sudo certbot certonly \ --authenticator dns-easydns \ --dns-easydns-credentials /etc/letsencrypt/.secrets/easydns.ini \ --dns-easydns-propagation-seconds 120 \ -d example.com \ -d www.example.com ``` `--dns-easydns-propagation-seconds` is how long Certbot waits after creating the TXT record before asking Let’s Encrypt to validate. The plugin’s default is 120 seconds; if validation intermittently fails with “no TXT record found”, raise it (the plugin README suggests 600 or more for safety) rather than changing anything else. Add `--dry-run` to test against the Let’s Encrypt staging environment first; it exercises the full DNS flow without consuming production rate limits. ### Wildcard certificate ``` sudo certbot certonly \ --authenticator dns-easydns \ --dns-easydns-credentials /etc/letsencrypt/.secrets/easydns.ini \ --dns-easydns-propagation-seconds 120 \ -d example.com \ -d '*.example.com' ``` Quote the wildcard so the shell does not expand it. This order validates two identifiers at `_acme-challenge.example.com`, so the plugin creates two TXT values there during issuance. ### Renewal Certbot records the authenticator and credentials path in the renewal configuration under `/etc/letsencrypt/renewal/example.com.conf`. The standard `certbot renew` (run by the systemd timer or cron job installed with Certbot) will repeat the DNS-01 flow automatically. Test it with: ``` sudo certbot renew --dry-run ``` Use `--deploy-hook` to reload the service that uses the certificate after a successful renewal, for example `--deploy-hook "systemctl reload nginx"`. Method 2: acme.sh ----------------- [acme.sh](https://github.com/acmesh-official/acme.sh) ships with a native easyDNS provider, [`dns_easydns`](https://github.com/acmesh-official/acme.sh/wiki/dnsapi2#dns_easydns), so nothing extra needs to be installed. ### Credentials Export the token and key in the shell that runs acme.sh. On first use, acme.sh saves them to `~/.acme.sh/account.conf` and reuses them for renewals, so the variables only need to be set once: ``` export EASYDNS_Token="your-easydns-user-token" export EASYDNS_Key="your-easydns-api-key" ``` Note the mixed-case variable names; acme.sh is case-sensitive about them. ### Request a certificate ``` acme.sh --issue --dns dns_easydns -d example.com -d www.example.com ``` acme.sh waits for the TXT record to be visible and then asks the CA to validate. If you need a longer wait, add `--dnssleep 120` (seconds) to the command. ### Wildcard certificate ``` acme.sh --issue --dns dns_easydns -d example.com -d '*.example.com' ``` ### Install and renew acme.sh keeps certificates under `~/.acme.sh/` and installs a cron job that renews them automatically; renewals reuse the saved easyDNS credentials. Copy the certificate into place for your server with `--install-cert` so that renewals are deployed too: ``` acme.sh --install-cert -d example.com \ --key-file /etc/ssl/private/example.com.key \ --fullchain-file /etc/ssl/certs/example.com.fullchain.pem \ --reloadcmd "systemctl reload nginx" ``` By default, current acme.sh versions use ZeroSSL as the CA. To use Let’s Encrypt, add `--server letsencrypt` to the `--issue` command, or set it as the default with `acme.sh --set-default-ca --server letsencrypt`. Method 3: lego -------------- [lego](https://go-acme.github.io/lego/) is a Go ACME client and library with a native [`easydns`](https://go-acme.github.io/lego/dns/easydns/) provider. Because Traefik and a number of other tools embed lego, the same environment variables apply to them. ### Credentials ``` export EASYDNS_TOKEN="your-easydns-user-token" export EASYDNS_KEY="your-easydns-api-key" ``` Both variables are upper-case in lego (unlike acme.sh). Optional tuning variables, with their defaults: VariablePurposeDefault`EASYDNS_ENDPOINT`API server URL; set to `https://sandbox.rest.easydns.net` to test against the sandboxlive endpoint`EASYDNS_TTL`TTL of the challenge TXT record120`EASYDNS_POLLING_INTERVAL`Seconds between DNS checks2`EASYDNS_PROPAGATION_TIMEOUT`Maximum seconds to wait for the record to be visible60`EASYDNS_SEQUENCE_INTERVAL`Seconds between sequential record operations60`EASYDNS_HTTP_TIMEOUT`API request timeout in seconds30### Request a certificate ``` lego --email you@example.com --dns easydns -d example.com -d www.example.com run ``` ### Wildcard certificate ``` lego --email you@example.com --dns easydns -d '*.example.com' -d example.com run ``` ### Renewal lego does not install a scheduler; run `lego ... renew` from cron or a systemd timer. It only renews when the certificate is within the `--days` threshold (default 30), so a daily run is safe: ``` lego --email you@example.com --dns easydns -d '*.example.com' -d example.com renew ``` Add `--renew-hook "systemctl reload nginx"` (or the equivalent for your service) to deploy the renewed certificate. Verifying the challenge record yourself --------------------------------------- While an issuance is in progress (or after one has failed), you can confirm what the CA sees. First check through your normal resolver: ``` dig TXT _acme-challenge.example.com +short ``` Then query one of the domain’s authoritative easyDNS nameservers directly, which is the view that matters for validation: ``` dig NS example.com +short dig @ TXT _acme-challenge.example.com +short ``` A successful lookup returns one or more quoted strings, each a 43-character base64url token, for example: ``` "gfj9Xq...example-token-value...Rg85nM" ``` The exact value is generated by the CA for each challenge and changes on every issuance. If the record is present on the authoritative servers but the CA still reports failure, see the [troubleshooting section](https://kb.easydns.com/knowledge/dns-01-acme-challenges-easydns/#troubleshooting) of the DNS-01 overview. An empty answer from the authoritative server means the record was never created or has not been published yet; increase the client’s propagation wait and check the API credentials. Automatic renewal ----------------- The point of ACME is that certificates renew without intervention. Once one of the methods above has worked once, the client should, on each renewal: 1. request renewal from the CA; 2. create the `_acme-challenge` TXT record via the easyDNS API; 3. wait for the record to be visible from authoritative DNS; 4. complete validation; 5. obtain the renewed certificate; 6. remove the temporary challenge record. You should not need to create TXT records by hand for renewals. If you find yourself doing so, the saved credentials are missing or the renewal job is running in an environment where the environment variables or credentials file are not available (a common cause with cron, which runs with a minimal environment: use the credentials file approach, or set the variables inside the cron script). Wildcard certificates with easyDNS ---------------------------------- A wildcard certificate covers every single-label subdomain of a name: `*.example.com` matches `www.example.com` and `api.example.com` but not `example.com` itself, nor `a.b.example.com`. To cover the apex as well, request both names in the same certificate. Let’s Encrypt issues wildcard names only through DNS-01, which is why the easyDNS API integration is required. All three clients covered here handle the two-TXT-value RRset that a combined apex + wildcard order produces: ``` # Certbot sudo certbot certonly --authenticator dns-easydns \ --dns-easydns-credentials /etc/letsencrypt/.secrets/easydns.ini \ -d example.com -d '*.example.com' # acme.sh acme.sh --issue --dns dns_easydns -d example.com -d '*.example.com' # lego lego --email you@example.com --dns easydns -d example.com -d '*.example.com' run ``` Related easyDNS resources ------------------------- - [DNS-01 ACME Challenges with easyDNS](https://kb.easydns.com/knowledge/dns-01-acme-challenges-easydns/) (overview, compatibility table, troubleshooting) - [easyDNS REST API documentation](https://docs.sandbox.rest.easydns.net/) - [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/) (a broken DNSSEC chain will cause DNS-01 validation to fail) - [easyDNS DNS hosting](https://easydns.com/dns/)