Certbot wildcard certificate: DNS-01 setup wey dey work

Why wildcard certificate need DNS-01

Wildcard certificate dey cover every first-level subdomain for one domain: *.example.com match app.example.com, blog.example.com, and any other name wey dey one label deep. Let's Encrypt dey issue wildcard certificates only through DNS-01 challenge, so Certbot must prove control of the domain DNS by publishing TXT record for _acme-challenge.example.com. HTTP-01 challenge no fit qualify, because serving token file only proves control of one hostname, na the hostname wey validation server fetch the file from. Wildcard na claim about every possible name under the domain, and DNS na the only public record wey fit represent the whole namespace.

That one requirement dey decide everything else for this page. To pass DNS-01, you must fit create TXT records for the domain zone, either by hand or through your DNS provider API (application programming interface). The by-hand method go work once, then e go fail during renewal, for the clear reason wey we show below. The API method, through Certbot DNS plugin, renews without anybody intervention, and na this setup you suppose finish with.

This na the wildcard chapter for our Certbot guides. Ordinary single-hostname certificates, web server configuration, and port 80 rules dey covered for Certbot with nginx on Ubuntu 24.04 and Certbot with Apache on Ubuntu 24.04.

How the _acme-challenge TXT record dey work

When Certbot requests *.example.com, Let's Encrypt go answer with random token. Certbot go join that token with your ACME (automatic certificate management environment) account key, hash the result with SHA-256, then produce short text value. That value must show as TXT record for _acme-challenge.example.com. Let's Encrypt go then query your domain authoritative name servers from its own infrastructure. If the record wey e read match the value wey e expect, you don prove say you control the zone. Control of the zone dey count as control of every name under am.

Two details dey cause most failures:

• Requesting example.com and *.example.com for the same certificate means two separate challenges, and both TXT records dey for the same name, _acme-challenge.example.com. Both must exist for the same time. Adding the second record correct; replacing the first one with the second go make the first challenge fail.
• Validation dey read your authoritative servers, but provider control panels fit need one minute or more to push new record go those servers. Check from outside before you allow validation run:

dig +short TXT _acme-challenge.example.com @1.1.1.1

When that command print the value wey Certbot ask for, validation fit succeed. When e print nothing, wait and run am again.

See say e work once: manual mode

Manual mode make you edit DNS by yourself. Na na better way to understand how the mechanism work before you automate am:

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

The quotes around the wildcard stop your shell from treating * as filename pattern. Certbot go pause and show you instructions:

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

Create that TXT record for your DNS provider panel. Confirm say e dey visible with the dig command wey dey above. Only then press Enter. Because this run dey ask for the bare domain and the wildcard, Certbot go prompt you two times. Leave both records in place until issuance finish. Success go end with these familiar lines:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem

Why manual mode no fit renew itself

Every renewal na fresh challenge with fresh token, so the TXT value dey change every time. The record wey you paste today no go useful after 60 days. The renewal timer dey run Certbot unattended two times every day, and nobody dey for keyboard to paste the new value. So certificate wey you issue manually go fail renewal with this exact error:

Failed to renew certificate example.com with error: The manual plugin is not
working; there may be problems with your existing configuration.
The error was: PluginError('An authentication script must be provided with
--manual-auth-hook when using the manual plugin non-interactively.')

You fit satisfy this requirement by writing --manual-auth-hook scripts wey dey call your DNS provider API, but for that point you dey rebuild DNS plugin by hand. Use manual mode to learn how the process dey work, or for genuine one-off on domain wey you never fit automate the DNS for yet. Set reminder well before day 90, because Let's Encrypt no dey send expiry emails again. For everything else, use plugin.

The plugin route: certbot-dns-cloudflare for Ubuntu 24.04

DNS plugin dey hold API credential for your DNS provider and e dey handle the whole TXT record process by itself, when e dey issue certificate and again for every renewal. Cloudflare na the working example here because na the provider plugin wey plenty people need, and Ubuntu package am.

Our Certbot guides recommend apt packages for Ubuntu 24.04, and the same advice apply to Cloudflare:

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

Make we talk true about versions. The 24.04 archive get this plugin for version 2.0.0 together with Certbot 2.9.0; apt policy python3-certbot-dns-cloudflare go show your own version. This difference no cause problem, and scoped API tokens dey work because the underlying python3-cloudflare library for 24.04 na 2.11.1. E pass 2.3.1, wey the plugin need for token support. For older Ubuntu releases, that library too old for tokens. Na from there the online warnings come say apt plugin dey force Global API Key. For 24.04, those warnings no longer apply.

For Cloudflare dashboard, create scoped API token, no be the Global API Key: go My Profile, then API Tokens, then Create Token. Use only the permission Zone / DNS / Edit, and limit am to the one zone wey you dey issue certificate for. Put am for file wey only root fit read:

sudo mkdir -p /root/.secrets
sudo tee /root/.secrets/cloudflare.ini > /dev/null <<'EOF'
dns_cloudflare_api_token = paste_your_scoped_token_here
EOF
sudo chmod 600 /root/.secrets/cloudflare.ini

Certbot dey check the file mode and warn about Unsafe permissions on credentials configuration file if other users fit read the file. Now issue certificate:

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

The plugin go create TXT records through API, wait small for propagation, allow validation run, then delete the records again. If your zone name servers slow to pick changes, increase the wait with --dns-cloudflare-propagation-seconds 60. The certificate go enter /etc/letsencrypt/live/example.com/. Point nginx or Apache to fullchain.pem and privkey.pem exactly as the base guides show, including deploy hook.

If provider plugin no dey inside apt

The 24.04 archive only package plugins for small number of providers. Cloudflare, Route 53, DigitalOcean and the general RFC 2136 interface dey among dem. Run apt search certbot-dns to see the list. If your provider no dey there, na for this one place our apt-first advice dey change: install Certbot and the plugin from snap instead, then remove the apt Certbot first so two renewal timers no go fight over /etc/letsencrypt:

sudo apt remove certbot python3-certbot-dns-cloudflare
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-dns-yourprovider

snap plugin fit connect only to snap Certbot. E no fit extend the apt one. Na why the two installations must not coexist. And if your DNS host no offer any API, your realistic options na to move the domain DNS go provider wey get one, or run your own name server and point the rfc2136 plugin to am.

Renewal: prove am now, no be after 60 days

Certbot dey record how dem issue each certificate for /etc/letsencrypt/renewal/example.com.conf, including authenticator = dns-cloudflare and the credentials path, so the normal timer wey dey run two times every day go renew am without your help. Test the whole process against the staging environment:

sudo certbot renew --dry-run

If e pass, e mean say the credential dey work and validation complete from start to finish; the real renewal for 60 days go follow the same process. Do these two things today. First, when renewed certificate change for disk, nothing go happen until web server reload am. So configure the deploy hook wey nginx and Apache guides describe. Second, handle the credentials file carefully: anybody wey fit read am fit edit your DNS zone. That one fit redirect your mail or let dem pass their own DNS-01 challenges. Keep the file at mode 600 under /root, limit the token to one zone, and rotate am if you ever suspect say e leak.

When wildcard no dey necessary

Wildcard na correct tool for plenty subdomains, or for subdomains wey you no fit predict. But e no suppose be default for every other case.

• One subdomain, or small number of known ones: normal SAN (subject alternative name) certificate dey simpler. certbot --nginx -d example.com -d www.example.com -d app.example.com fit cover up to 100 names through plain HTTP-01, and no DNS API credential ever dey on the server.
• Wildcard dey match exactly one label. *.example.com no cover the bare example.com, na why the commands above request both, and e no cover a.b.example.com too; that one go need *.b.example.com.
• Na one private key dey behind every subdomain. If machine wey hold am get breached, every name wey the wildcard cover go dey affected at once.
• If Traefik dey terminate TLS (transport layer security) for your containers, you no need Certbot at all: Traefik dey request wildcard certificates by itself through DNS-01, using the same kind provider token.

Where wildcard really dey useful na for per-customer or per-app subdomains wey dem dey create faster than you want reissue certificates, and internal hosts wey no get public port 80, like services wey you fit reach only through WireGuard VPN. DNS-01 no ever connect to the host wey dem dey certify, so even fully private machine fit hold publicly trusted certificate.

FAQ

Certbot fit issue wildcard certificate with HTTP-01?

No. HTTP-01 dey prove control of one hostname, because validation server go fetch token file from that exact name. Wildcard dey cover every name under the domain, so Let's Encrypt require DNS-01 challenge for am, and the --nginx, --apache, --webroot and --standalone authenticators all dey use HTTP. The only way na TXT record for _acme-challenge.example.com, wey you fit add manually or through DNS plugin.

Wildcard certificate fit cover root domain?

No. Wildcard dey match exactly one label, so *.example.com cover www.example.com but e no cover bare example.com, and e no cover a.b.example.com too. Request both names for one certificate with -d example.com -d '*.example.com'. That one go create two challenges, and both TXT records go dey for the same _acme-challenge.example.com name, so add the second record without deleting the first one.

Why my wildcard certificate no renew automatically?

Because dem issue am with --manual. Every renewal need brand-new TXT value, and unattended timer no get way to paste am, so renewal go stop with error An authentication script must be provided with --manual-auth-hook when using the manual plugin non-interactively. Issue the certificate again with DNS plugin like certbot-dns-cloudflare, or provide --manual-auth-hook and --manual-cleanup-hook scripts wey go edit the record through your provider's API.

How long e dey take before _acme-challenge TXT record show?

E depend on your DNS provider: e fit take from seconds reach several minutes. Validation dey read your zone authoritative servers, so check with dig +short TXT _acme-challenge.example.com @1.1.1.1 and wait until the expected value show before you continue manual run. With plugin, increase the built-in wait through the plugin's propagation option, for example --dns-cloudflare-propagation-seconds 60, if validation report say e no find the record.

Wildcard certificate less secure than normal certificate?

The cryptography dey identical. The difference na for operations: one private key dey cover every subdomain, so breach fit reach more places, and the DNS API credential wey automation need na sensitive secret wey dey stored for the server. If na only few known subdomains you dey run, SAN certificate go avoid both problems. Na exactly for this situation this guide recommend say make you skip wildcard.