Bobay Stack

Ops & troubleshooting / 2026-08-05

Nginx + acme.sh: Automating Certificates with DNS-01

HTTP-01 needs port 80 and public reachability; DNS-01 doesn't. The price is an API token that can edit DNS.

4 MIN READ BY BOBAY.TOP Updated 2026-08-11 ↖ All notes
Nginx + acme.sh: Automating Certificates with DNS-01

The most fragile part of certificate automation isn't issuance — it's that the service isn't reloaded after renewal. The advantage of DNS-01 is that it moves "proving you own the domain" from port 80 to a DNS record, so machines on the internal network or behind a reverse proxy can still get certificates.

Why DNS-01

  • The machine isn't on the public internet; port 80 can't reach it
  • You want a wildcard certificate (*.example.com), which HTTP-01 can't do
  • You don't want to open port 80 temporarily just for renewal

The trade-off: you need an API token that can modify DNS, and that token has to work long term (or be rotated regularly).

The Cloudflare way

export CF_Token="<Token with only Zone.DNS edit permission>"
acme.sh --issue --dns dns_cf -d example.com -d www.example.com --keylength ec-256

Least privilege matters: this token only needs DNS edit permission — don't give it full Zone rights, and definitely not account-level permissions.

Installing into Nginx and reloading

acme.sh --install-cert -d example.com --ecc \
  --key-file       /etc/nginx/certs/example.com.key \
  --fullchain-file /etc/nginx/certs/example.com.fullchain.pem \
  --reloadcmd      "nginx -t && systemctl reload nginx"

Putting nginx -t inside --reloadcmd is a good habit: if the config is broken, no reload happens and production keeps running the old config, so the site doesn't go down.

Minimal Nginx-side config

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
add_header Strict-Transport-Security "max-age=31536000" always;

Once HSTS is served, rolling it back is a pain (browsers remember it for a year). Run it on a test domain for a while before going to production.

Verifying renewal

acme.sh --list
acme.sh --renew -d example.com --force

Force a renewal once and check whether the certificate file timestamp changed, whether Nginx reloaded, and whether the browser received the new certificate. Only when all three pass is it actually automated.

Why not HTTP-01

HTTP-01 requires port 80 to be reachable, requires temporarily writing /.well-known/acme-challenge/, and requires making sure redirects don't swallow it. As soon as a site has forced HTTPS or CDN origin rewriting, the validation failure rate goes up immediately. DNS-01 writes a single TXT record and is fully decoupled from site routing, redirects, and firewalls.

The trade-off: you must have an API credential that can modify DNS. Cloudflare token scope should be narrowed to Zone:DNS:Edit on a single zone; don't use a global key.

A complete run-through

# 1. Run it manually once first to confirm the TXT record can be published
acme.sh --issue --dns dns_cf -d bobay.top -d '*.bobay.top' --staging

# 2. Remove --staging for the real issuance
acme.sh --issue --dns dns_cf -d bobay.top -d '*.bobay.top'

# 3. Install into the nginx directory and configure reload
acme.sh --install-cert -d bobay.top \
  --key-file /etc/nginx/ssl/bobay.key \
  --fullchain-file /etc/nginx/ssl/bobay.crt \
  --reloadcmd "nginx -s reload"

The --staging step matters: production has rate limits (5 per domain per week), so get it working against staging during debugging instead of spending production quota on troubleshooting.

Renewal and verification

After installation acme.sh writes a cron entry that checks daily and renews 30 days before expiry. What you actually need to verify isn't "is there a cron entry" but whether nginx picks up the new certificate after renewal:

openssl x509 -in /etc/nginx/ssl/bobay.crt -noout -dates
echo | openssl s_client -connect bobay.top:443 -servername bobay.top 2>/dev/null | openssl x509 -noout -dates

The notAfter from both commands must match. If they don't, the reload didn't take effect, or nginx is reading a different file.

Two pitfalls I've hit

  • Wildcard and root domain must be issued separately: *.bobay.top does not cover bobay.top, so you have to write -d bobay.top -d '*.bobay.top'.
  • With the CF proxy enabled, validation "looks successful": curl hits the Cloudflare edge certificate, not the one on your origin. To verify the origin you must connect directly to the IP with --resolve.

One more note: renewal failures are often not a certificate problem but an expired DNS token. CF tokens have no expiry date, but manually deleting one invalidates it immediately — add an "alert if the TXT write fails" check to the renewal script, rather than finding out when the certificate expires.

Nginxacme.shTLSDNS-01

References

acme.sh DNS mode ↗ Nginx SSL configuration ↗