How to use DNS provider modules in Caddy 2

[matt (Matt Holt)]

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

Introducing libdns: A collaborative effort for unified DNS provider APIs

libdns is a collection of free-range DNS provider client implementations written in Go. With libdns packages, your Go program can manage DNS records across any supported providers. Caddy previously used go-acme/lego for DNS providers (75+ of them!) but those packages can only set and delete TXT records for ACME challenges. Other libraries like StackExchange/dnscontrol are useful if you need to control the whole zone, but not if you need incremental changes to a zone. libdns APIs have methods…

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 github.com/caddy-dns/REPOSITORY
   

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. Your DNS provider must be implemented, either by you or someone else kind enough to do it. We can do it for your business for free with a Business+ sponsorship or higher.

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:

Caddyfile

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.

JSON

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"
            }
        }
    }
}

[std4453]

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.

[francislavoie]

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

[inxsible]

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
      }
}
nas.myfancydomain.com {
      reverse_proxy http://192.168.1.51
      import cloudflare
}

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

[yurenchen]

the doc link

JSON Config Structure - Caddy Documentation

seems outdate. (empty content)

maybe this link?

JSON Config Structure - Caddy Documentation

[francislavoie]

Fixed, thanks.

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