📋 Prerequisites

  • An active domain on OnlyDNS.
  • A TSIG Key generated in the OnlyDNS Portal or via CLI (onlydns tsig create --algo hmac-sha256).
  • Caddy v2.x with the RFC 2136 plugin or Docker.
1

Obtain Caddy with the RFC 2136 Plugin

Caddy requires the caddy-dns/rfc2136 module to execute DNS-01 challenges. You can build it locally with xcaddy, download it from the Caddy website, or use a multi-stage Docker build:

Method A: Build with xcaddy (Binary) 
# Install xcaddy and build custom Caddy binary
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
xcaddy build --with github.com/caddy-dns/rfc2136
sudo mv caddy /usr/bin/caddy
Method B: Multi-Stage Dockerfile 
FROM caddy:2-builder AS builder
RUN xcaddy build --with github.com/caddy-dns/rfc2136

FROM caddy:2
COPY --from=builder /usr/bin/caddy /usr/bin/caddy
2

Configure your Caddyfile

In your Caddyfile, specify your wildcard and apex domains with the tls directive and dns rfc2136 block:

/etc/caddy/Caddyfile 
# Wildcard + Apex domain with automated TSIG DNS-01 verification
*.example.com, example.com {
    tls {
        dns rfc2136 {
            server ns1.onlydns.com:53
            key_name "your-tsig-key-name"
            key_alg "hmac-sha256"
            key "YOUR_BASE64_TSIG_SECRET_KEY"
        }
    }

    # Reverse proxy backend or serve static files
    reverse_proxy localhost:8080
}
💡 Environment Variables: You can replace hardcoded secrets with environment variables: key {env.ONLYDNS_TSIG_SECRET}.
🔒 Least-Privilege Security Tip: In the OnlyDNS Portal or REST API, restrict this TSIG key to only update the _acme_challenge subdomain so Caddy cannot modify other zone records.
3

Start Caddy & Verify TLS

Start or reload Caddy. Caddy will detect that a wildcard domain is requested, dynamically post the ACME DNS-01 challenge TXT records to OnlyDNS, obtain the certificate, and maintain automated renewals in the background: 

# Validate Caddyfile and reload service
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Message Sent

Thanks for contacting OnlyDNS. We received your message and will follow up shortly.