Writing a Plugin: DNS Provider

Join the Caddy Community Forum to chat with other Caddy developers!

Caddy magically obtains TLS certificates for your site in 3 ways: HTTP, TLS-SNI, and DNS. The first two are used by default and can be completed without intervention by you. The third is more versatile in some environments where you cannot start a listener that can be accessed by external networks, etc. The problem is that doing it the DNS way requires custom code to interact with the DNS provider whom your domain's nameservers are pointed to.

Caddy uses xenolf/lego to implement the ACME protocol and solve the domain challenges (lego was originally written for use in Caddy). It supports pluggable DNS providers, but to use them in Caddy they have to be adapted. It only requires a few lines of code.

If you want to add a new DNS provider, it must be built to work with lego (see that repository for instructions and documentation). Once that is working, you can adapt it for Caddy very easily:

package myprovider

import (
	"errors"

	"github.com/mholt/caddy/caddytls"
	"github.com/xenolf/lego/acme"
	"github.com/xenolf/lego/providers/dns/myprovider"
)

func init() {
	caddytls.RegisterDNSProvider("myprovider", NewDNSProvider)
}

// NewDNSProvider returns a new MyProvider DNS challenge provider.
// The credentials are interpreted as follows:
//
// len(0): use credentials from environment
// len(2): credentials[0] = API user
//         credentials[1] = API key
func NewDNSProvider(credentials ...string) (acme.ChallengeProvider, error) {
	switch len(credentials) {
	case 0:
		return myprovider.NewDNSProvider()
	case 2:
		return myprovider.NewDNSProviderCredentials(credentials[0], credentials[1])
	default:
		return nil, errors.New("invalid credentials length")
	}
}

Note that we do not plug the DNS provider directly into the caddy package; we plug it into caddytls.

You can see all of the officially-supported adapters at caddyserver/dnsproviders. If you've written a DNS provider, please feel free to submit a pull request to adapt it for use with Caddy!

Once your provider is plugged in, you can use it in the Caddyfile:

tls {
    dns myprovider
}

And that's all there is to it.