Key takeaways
- A wildcard certificate from Let's Encrypt needs the DNS-01 challenge: a TXT record under _acme-challenge.
- Give the DNS API token only the right to edit DNS for one zone, because it sits on the server that renews.
- Test with the staging server first; the failed validation limit is 5 per hour and cannot be raised.
- Most failures are a wrong TXT record, slow propagation or a token without rights on the zone.
Most sites do not need a wildcard certificate. If you serve a few known names, one certificate listing them is simpler. A wildcard earns its place when subdomains appear on their own, one per customer or per project, and you do not want to request a certificate each time. This post shows how to get one from Let's Encrypt with the DNS challenge, using certbot or acme.sh. How a panel can do it for you is described in automatic wildcard SSL.
Why wildcards need the DNS challenge
Let's Encrypt offers several ways to prove you control a name. According to its challenge types page (read 30 October 2026), the DNS-01 challenge is the one that can issue certificates with wildcard names. Your client publishes a TXT record under _acme-challenge.<your domain>, and Let's Encrypt looks it up.
The same page lists the costs. It is harder to set up than the HTTP challenge. It only makes sense if your DNS provider has an API, because the record is created and removed by a program. Storing full DNS API credentials on a web server is risky. And propagation delays can mean waiting, sometimes as much as an hour. It also cannot validate IP addresses.
Step 1: make a narrow API token
Create the token at your DNS provider, not a global key. With Cloudflare, acme.sh's documentation asks for a token with the Zone, DNS, Edit permission on the zones you need. Other providers have similar scopes. Rule of thumb: edit DNS records of one zone, nothing about billing, nothing about other zones.
Step 2a: certbot
Certbot has a plugin per DNS provider, installed as a package or with pip, for example python3-certbot-dns-cloudflare on Debian and Ubuntu. Put the token in a file only root can read:
sudo install -m 600 /dev/null /root/.secrets/cloudflare.ini
echo 'dns_cloudflare_api_token = YOUR_TOKEN' | sudo tee /root/.secrets/cloudflare.ini
sudo certbot certonly --dns-cloudflare \
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
-d example.com -d '*.example.com'
Certbot installs a renewal timer. Add a deploy hook so your web server picks up the new files:
sudo certbot renew --deploy-hook "systemctl reload nginx"
Step 2b: acme.sh
The acme.sh project keeps a list of DNS API plugins (read 30 October 2026), including Cloudflare, AWS Route53, DigitalOcean, GoDaddy, Linode and Gandi. For Cloudflare you set the token and the account or zone ID, then issue:
export CF_Token="YOUR_TOKEN"
export CF_Zone_ID="YOUR_ZONE_ID"
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'
acme.sh --install-cert -d example.com \
--key-file /etc/ssl/example.key --fullchain-file /etc/ssl/example.pem \
--reloadcmd "systemctl reload nginx"
acme.sh saves the variables in ~/.acme.sh/account.conf and reuses them at renewal, so protect that file. Some providers need more waiting; the acme.sh page suggests --dnssleep values for GoDaddy and Linode.
Delegating the challenge with a CNAME
If your DNS provider has no API, create a CNAME from _acme-challenge.example.com to a name in a zone that does. Let's Encrypt follows it. Then your client writes the TXT record in the second zone, and the main zone's credentials never touch the server.
Rate limits to know
From the rate limits page (read 30 October 2026): 300 new orders per account every 3 hours, 50 new certificates per registered domain every 7 days, 5 duplicates of the same set of names every 7 days, and 5 failed validations per name per account per hour. The last two cannot be raised, so test with --staging (certbot) or --staging (acme.sh) first. Renewals made through ARI are exempt from these limits.
Common errors and fixes
- "DNS problem: NXDOMAIN looking up TXT": the record was not created or did not propagate. Check it with
dig TXT _acme-challenge.example.com @1.1.1.1and raise the sleep time. - Unauthorized or 403 from the API: the token lacks Edit on that zone, or the zone ID belongs to another zone.
- Old TXT records pile up: a client that crashed did not clean them. Delete stale
_acme-challengerecords. - Wildcard works, bare domain fails: you asked for
*.example.comonly. Add-d example.com. - Renewal fails months later: the token expired or was rotated. Run
certbot renew --dry-runafter any change.
Which route should you pick
Use certbot if you already run it for other sites and your provider has a plugin. Use acme.sh for a provider certbot lacks or a small server. If you run a panel that manages DNS itself, the DNS feature can answer the challenge on its own zone, so no token travels anywhere.
Questions
Do I need a wildcard certificate at all?
Only if you serve many subdomains you cannot list in advance, such as one per customer. For a handful of known names, one certificate with several names and the simpler HTTP challenge is easier.
Does a wildcard cover the bare domain?
No. *.example.com does not cover example.com. Ask for both names in the same certificate, as in the commands below.
Can I issue a wildcard certificate without a DNS API?
You can by hand, but then renewal is manual too, and certificates are renewed every few weeks. Without an API, delegate the challenge name to a zone that has one (see the CNAME section).
Is the DNS token dangerous on the server?
It can change your DNS, so scope it to one zone and nothing else, keep the file readable only by root, and rotate it if the server is ever compromised.
