Configuration: DNS providers

DNS providers are used by the tls-acme module to solve the DNS-01 ACME challenge — the only challenge type that supports wildcard certificates. You configure a provider inside the dns { } block nested within a tls { } block, selecting it by name with the provider directive.

*.example.com:443 {
    tls {
        provider "acme"
        challenge dns-01
        contact "admin@example.com"
        dns {
            provider "<provider-name>"
            # provider-specific directives …
        }
    }
}

All DNS provider implementations are part of the dns-stalwart module.

Providers

Bunny

Provider name: bunny

Configuration example:

dns {
    provider "bunny"
    api_key "YOUR_BUNNY_API_KEY"
}

Cloudflare

Provider name: cloudflare

Configuration example:

# Scoped API token (recommended)
dns {
    provider "cloudflare"
    api_key "YOUR_CLOUDFLARE_API_TOKEN"
}

# Global API key
dns {
    provider "cloudflare"
    api_key "YOUR_GLOBAL_API_KEY"
    email "admin@example.com"
}

deSEC

Provider name: desec

Configuration example:

dns {
    provider "desec"
    api_token "YOUR_DESEC_API_TOKEN"
}

DigitalOcean

Provider name: digitalocean

Configuration example:

dns {
    provider "digitalocean"
    oauth_token "YOUR_DO_OAUTH_TOKEN"
}

DNSimple

Provider name: dnsimple

Configuration example:

dns {
    provider "dnsimple"
    oauth_token "YOUR_DNSIMPLE_TOKEN"
    account_id "12345"
}

Google Cloud DNS

Provider name: googlecloud

Configuration example:

dns {
    provider "googlecloud"
    service_account_json "{\"type\":\"service_account\", ...}"
    project_id "my-gcp-project"
    managed_zone "example-com"
}

OVH

Provider name: ovh

Configuration example:

dns {
    provider "ovh"
    application_key "YOUR_APP_KEY"
    application_secret "YOUR_APP_SECRET"
    consumer_key "YOUR_CONSUMER_KEY"
    endpoint "ovh-eu"
}

Porkbun

Provider name: porkbun

Configuration example:

dns {
    provider "porkbun"
    api_key "YOUR_PORKBUN_API_KEY"
    secret_key "YOUR_PORKBUN_SECRET_KEY"
}

RFC 2136 (TSIG)

Provider name: rfc2136

Updates DNS records on any authoritative server that supports dynamic updates (RFC 2136) authenticated with TSIG.

Configuration example:

dns {
    provider "rfc2136"
    server "udp://ns1.example.com:53"
    key_name "ferron-acme."
    key_secret "BASE64_ENCODED_TSIG_SECRET"
    key_algorithm "HMAC-SHA256"
}

Route 53

Provider name: route53

Configuration example:

dns {
    provider "route53"
    access_key_id "AKIAIOSFODNN7EXAMPLE"
    secret_access_key "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    region "us-east-1"
    hosted_zone_id "Z1D633PJN98FT9"
}

Spaceship

Provider name: spaceship

Configuration example:

dns {
    provider "spaceship"
    api_key "YOUR_SPACESHIP_API_KEY"
    api_secret "YOUR_SPACESHIP_API_SECRET"
}

Notes and troubleshooting

Using environment variables for credentials

All string directives support environment variable interpolation. This avoids storing secrets directly in your configuration file:

dns {
    provider "cloudflare"
    api_key $env(CF_API_TOKEN)
}

DNS propagation delays

After Ferron creates the _acme-challenge TXT record, the ACME CA must be able to resolve it. Propagation time varies by provider:

If certificate issuance fails with a DNS validation error, verify that the TXT record is resolvable from the public internet before retrying.

RFC 2136 TSIG key format

The key_secret value must be the raw TSIG key bytes encoded as standard Base64 (with padding). Most DNS management tools (BIND tsig-keygen, dnssec-keygen) output the key in this format already.

OVH endpoint selection

Choose the endpoint that matches where your domain is registered:

See also

• ACME automatic TLS — full ACME configuration reference
• Automatic TLS use case — guided walkthrough