How to use DNS provider modules in Caddy 2

Caddy 2 uses a new and improved DNS provider interface for solving the ACME DNS challenge.

All you have to do is plug the service provider(s) you need into your build, then add the DNS challenge to your configuration!

Getting a DNS provider plugin

How you choose to get a custom Caddy build is up to you; we’ll describe two common methods here.

Method 1:

  1. Go to the Caddy download page.
  2. Find your DNS provider in the list of modules (dns.providers.*) and select it.
  3. Download your custom Caddy build.

Method 2:

  1. Find your DNS provider in the caddy-dns repositories.
  2. Build caddy with your DNS provider plugged in. This is a single xcaddy command:
    xcaddy build --with

If you do not find your DNS provider:

If you do not find a module for your DNS provider, that means nobody has implemented it yet. You have two options: either…

  1. implement your DNS provider (recommended), or
  2. use lego-deprecated which supports all of lego’s 75+ DNS providers, but without certain advantages.

Enabling the DNS challenge

Once you have a custom Caddy binary with your DNS provider module plugged in, you simply have to enable the DNS challenge in your config. Do this one of the following ways:


Global option (use DNS challenge for all sites)

For a globally-recognized DNS challenge configuration, use the acme_dns global option at the top of your Caddyfile:

    acme_dns <provider> ...

For example:

    acme_dns cloudflare 1484053787dJQB8vP1q0yc5ZEBnH6JGS4d3mBmvIeMrnnxFi3WtJdF

Per-site configuration

Or, to enable the DNS challenge for a specific site only, use a tls directive in its site block:

tls {
    dns <provider> ...

for example:

tls {
    dns cloudflare 1484053787dJQB8vP1q0yc5ZEBnH6JGS4d3mBmvIeMrnnxFi3WtJdF

(You might also use a {env.*) placeholder if your credentials are in the environment.) Each provider may have a slightly different syntax; check module docs to be sure.


Or, if you use JSON, configure an automation policy with an acme issuer that sets the DNS challenge, for example:

	"module": "acme",
	"challenges": {
        "dns": {
            "provider": {
                "name": "cloudflare",
                "api_token": "YOUR_CLOUDFLARE_API_TOKEN"
Anybody using wildcard SSL with Namecheap on Caddy?
Caddy v2 Cloudflare plugin install
How can I use DNS challenge in Caddy2?
Caddy version 1 end of life date
"The page isn’t redirecting properly" when runn
Rate limited by LetsEncrypt - how to resolve?
Enabling wildcard and on_demand certificates
Generic question about DNS providers & Caddy
Wildcard certificates, building from scratch and what Caddy is all about
How to get Cloudflare API token env variable?
Apple Pay TLS Cipher Suite Issues
Caddy2 Cloudflare-DNS Implimentation Windows Native
Can't figure out how to get started w/ wildcard cert w/Route53 and Letsencrypt
Caddy docker rootless problem with Certificate
Erorr With Dockerization On Unraid
Caddy not requesting wildcard domain
How to migrate from NGINX Ubuntu 20
PowerDNS plugin
Error obtaining certificate after Caddy restart
Configuring Caddy with Cloudflare DNS - The page isn’t redirecting properly
Client TLS Setup (iOS, macOS)
Could my Caddyfile be improved?
HTTPS in Backend, Caddy as Proxy ends in Errror 502
Tls interal still yields ERR_SSL_PROTOCOL_ERROR
Can't obtain certificate on custom port http-01
SabNZBd Reserse Proxy V3.0.1 Docker - rss feeds
Reverse Proxy Local Clients Directly to Local Server Using Same Domain as External Clients
Cant get my DNS-Provider-Module for DNS-Challenge working
DNS-01 Challenge failing with Netcup DNS-Plugin
New DNS provider module
Acme-dns support in caddy v2 as a dns provider
Caddy as "acme forward proxy"?
Serving tens of thousands of domains over HTTPS with Caddy
Enabling wildcard and on_demand certificates
Install a new module in Caddy 2
Caddy server SSL installed but not working
Caddy with UFW and autodrop of rules
Caddy as reverse proxy with duckdns package
Cannot connect to website https nor http

A post was split to a new topic: How to get Cloudflare API token?

A post was split to a new topic: Advantages of libdns?

The global option is only in 2.4.0-beta.1, which should be pointed out.
Just spent 2 hours finding out that it wasn’t available on previous versions.

1 Like

That’s not exactly true, it existed for a long time before, but it was broken/non-functional until this commit: caddyfile: Refactor unmarshaling of module tokens · caddyserver/caddy@f021696 · GitHub

A post was split to a new topic: Split up ACME challenges

A post was split to a new topic: DNS challenge troubles

I am using 2.4.0-Beta.1 now. But even before that I was able to do the following

(cloudflare) {
      tls {
        dns cloudflare YOUR_API_KEY
} {
      import cloudflare

It’s easier now that we can define it globally and not have to import it in every site configuration.


the doc link

seems outdate. (empty content)

maybe this link?

Fixed, thanks.

FYI, anyone can edit Wiki posts if you find a problem.

A post was split to a new topic: New DNS provider module