Wildcard SSL with Let's Encrypt: DNS-01 Setup Guide

One certificate, every subdomain covered — that's the promise of a wildcard SSL. But the moment you try to actually issue one with Let's Encrypt, the usual HTTP-01 method fails with a cryptic error and no obvious fix. Here's why, and how to get a *.yourdomain.com certificate issued properly using DNS validation.

Symptom: Wildcard Requests Keep Failing

You add a new subdomain every few weeks — app.example.com, staging.example.com, api.example.com — and you're tired of running Certbot separately for each one. So you try the obvious thing:

sudo certbot certonly --nginx -d example.com -d *.example.com

And you get something like:

Certbot failed to authenticate some domains (authenticator: nginx)
Domain: *.example.com
Type:   unauthorized
Detail: Invalid response ... during HTTP validation

Or Certbot just refuses outright with "The manual plugin is not working with --https-port or --http-01-port" style noise. Either way, the certificate never gets issued, and you're stuck re-running the same command with the same result.

Cause: Wildcards Can't Use HTTP-01 Validation

This isn't a bug — it's how the ACME protocol is designed. Let's Encrypt supports two ways to prove you own a domain before it hands you a certificate:

• HTTP-01: it puts a token at http://yourdomain.com/.well-known/acme-challenge/<token> and checks that your server serves it back. This only proves you control that one exact hostname.
• DNS-01: it asks you to create a TXT record at _acme-challenge.yourdomain.com with a specific value. Because DNS control implies control over every subdomain under it, this is the only method Let's Encrypt accepts for wildcard names.

So *.example.com will never validate over HTTP-01, no matter how correctly your webroot or Nginx config is set up. You have to switch to DNS-01, which means giving your ACME client a way to create TXT records — either through your DNS provider's API, or by hand.

Fix: Issue the Wildcard Cert with DNS-01

Option 1 — Certbot with a DNS plugin (fastest if supported)

If your DNS is hosted somewhere Certbot has a plugin for (Cloudflare, Route 53, DigitalOcean, Google Cloud DNS, and a few others), this is the least fussy route. Example for Cloudflare:

sudo apt install python3-certbot-dns-cloudflare -y

# API token needs Zone:DNS:Edit permission, scoped to the zone
sudo mkdir -p /root/.secrets
sudo nano /root/.secrets/cloudflare.ini

# /root/.secrets/cloudflare.ini
dns_cloudflare_api_token = your_token_here

sudo chmod 600 /root/.secrets/cloudflare.ini

sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
  -d example.com -d '*.example.com'

Certbot creates the TXT record itself via the API, waits for propagation, validates, and tears the record down. No manual steps, and renewal later is fully automatic since the credentials file is already in place.

Option 2 — acme.sh, if your DNS provider has no Certbot plugin

acme.sh supports well over a hundred DNS APIs, so it's worth trying when Certbot comes up short. Example with Cloudflare again (works the same shape for most providers, just different env vars):

curl https://get.acme.sh | sh -s email=you@example.com

export CF_Token="your_cloudflare_api_token"
export CF_Account_ID="your_account_id"

~/.acme.sh/acme.sh --issue --dns dns_cf \
  -d example.com -d '*.example.com'

Check acme.sh's DNS API wiki page for your specific registrar or DNS host — the env var names change per provider but the pattern is identical.

Option 3 — Manual DNS-01 (no API access, one-time issue)

If your DNS provider has no API at all, or you just want a one-off cert without handing anyone credentials, Certbot's manual mode works, but you'll repeat this by hand every 90 days:

sudo certbot certonly --manual --preferred-challenges dns \
  -d example.com -d '*.example.com'

Certbot pauses and prints something like:

Please deploy a DNS TXT record under the name:
_acme-challenge.example.com

with the following value:
gfj9Xq...Rg85nM

Log into your DNS zone editor, add that exact TXT record, wait a couple of minutes for it to be queryable (check with dig TXT _acme-challenge.example.com), then hit Enter in the terminal to continue. This is fine for a rare, single wildcard issuance, but it's a bad long-term plan — automated renewal needs the API route above.

Installing the Certificate

Once issued, the cert and key land in /etc/letsencrypt/live/example.com/. Point Nginx at them:

server {
    listen 443 ssl;
    server_name example.com *.example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    ...
}

Reload once the config's in place:

sudo nginx -t && sudo systemctl reload nginx

Any subdomain you point at this server — present or future — is now covered by the same certificate, with no separate issuance needed as long as it resolves to this box.

Renewal: Why It's Different for Wildcards

A normal HTTP-01 cert renews silently through the standard certbot renew cron job or systemd timer, because the webroot check needs nothing from you. A wildcard cert renews the same way only if you used the DNS API route (Option 1 or 2) — Certbot or acme.sh will call the API again automatically and rotate the TXT record without asking.

If you went the manual route (Option 3), certbot renew will just pause again and wait for you to update the TXT record by hand, every 90 days, forever. That's the real reason to invest the ten minutes to get an API token working: it turns a wildcard cert from a recurring chore into something you never think about again.

Confirm auto-renewal is actually wired up:

sudo certbot renew --dry-run

A clean dry run with no manual prompt means you're set.

A Note for cPanel Users

AutoSSL in cPanel/WHM does not issue wildcard certificates for individual cPanel accounts — it only covers explicit hostnames and their www. counterpart. If you need *.example.com on a cPanel server, you'll either need to generate the wildcard cert externally (using the acme.sh or Certbot steps above on a machine with DNS API access) and upload it under SSL/TLS > Install an SSL Certificate on your website, or ask your host to enable a DNS-based wildcard workflow at the WHM level. It's not something the cPanel UI does out of the box.

Prevention: Keep Wildcard Renewals Boring

• Always issue wildcards through a DNS API plugin, not manual mode — manual renewal is the single biggest cause of wildcard cert expiry.
• Scope the DNS API token to Zone:DNS:Edit only, not full account access, and store it outside the web root with chmod 600.
• Set a calendar reminder to run certbot renew --dry-run a few days after any DNS provider migration — moving registrars or nameservers is the most common way an otherwise-working auto-renewal quietly breaks.
• Monitor certificate expiry separately (uptime tools like UptimeRobot support this) so a silent renewal failure doesn't surprise you three months later.

Wildcard certs are genuinely useful once every subdomain under a domain is covered by one file — you stop juggling per-host certs and stop remembering to reissue one every time marketing spins up a new landing subdomain. The one-time setup cost of a DNS API token is what buys that convenience.