DNS providers
How Beamd issues wildcard certs over DNS-01, the providers it ships with, and how to add another.
Beamd needs DNS API access for two jobs: writing the A/AAAA records that
point tunnels at your edge, and answering the DNS-01 ACME challenge that
issues your wildcard certificate. Both use the same provider credential.
How DNS-01 issuance works
To get a *.YOUR_DOMAIN certificate from Let's Encrypt, Beamd proves it
controls the domain by writing a temporary TXT record. Because it issues a
wildcard, a brand-new <name>.YOUR_DOMAIN is already covered — no per-tunnel
issuance latency, no HTTP challenge that would require the name to be live
first. That's why the edge needs a DNS token with write access, not just read.
Certificates and ACME account state are cached in data_dir
(/var/lib/beamd by default) so they survive restarts, and certmagic renews
them automatically before they expire.
Supported providers
The cert layer uses libdns under the hood. The OSS binary compiles in:
| Provider | dns_provider | Use |
|---|---|---|
| Cloudflare | cloudflare | The supported production provider. Needs a Zone:DNS:Edit API token. |
| Stub | stub | In-memory, for local dev and tests — issues nothing real. |
For Cloudflare, create the token from the "Edit zone DNS" template scoped to
your zone, and set it via BEAMD_DNS_PROVIDER_CREDS (see
Configuration).
Zone auto-detection
Leave dns_zone blank and Beamd auto-detects the registered zone that owns your
base_domain. This is what lets base_domain be a subdomain of your zone —
base_domain: tunnel.example.com resolves to zone example.com automatically.
Set dns_zone explicitly only to skip the lookup.
Adding a provider
More providers (Route53, DigitalOcean DNS, Hetzner, Gandi, …) are a small
addition — one import plus one switch case in internal/dns/dns.go, since libdns
gives them all the same interface. PRs are welcome on the
repo.