Caddy DNS Challenge Provider

With the Caddy DNS plugin for Servercow, Caddy can manage DNS records through the Servercow DNS API. This is especially useful when you want to issue TLS certificates via the ACME DNS-01 challenge, for example for wildcard certificates like *.example.com.

Prerequisites¶

Before you can use the plugin, you need:

a domain managed in Servercow DNS
DNS API access (see this guide)
a Caddy server where you can include plugins or build your own Caddy binary

Important

When installed via repository, Caddy is always shipped without any plugins. This means you must either build your own Caddy binary with the Servercow plugin or download a custom build binary from the Caddy website to use this plugin (see below).

Module name¶

The Caddy plugin registers under the following module name:

dns.providers.servercow

Deploy Caddy with the plugin¶

There are two common ways to use Caddy with the Servercow DNS plugin.

Option 1: Build your own Caddy binary with xcaddy¶

Recommended for technical users and developers

This option requires a local Go toolchain and is better suited for advanced users who already have experience building Caddy binaries. For a detailed explanation of how xcaddy works, see the official Caddy documentation.

The plugin is added to a custom Caddy binary via xcaddy.

xcaddy build --with github.com/caddy-dns/servercow

If you already use an existing build pipeline for Caddy, you can add the plugin there in the same way.

Option 2: Download a custom build directly from the Caddy website¶

Recommended by us

This option is especially easy and does not require a local Go installation. You can directly download a ready-to-use Caddy binary with the Servercow plugin included.

If you do not want to use xcaddy on the server, you can create and download a custom build binary with included modules directly from the official Caddy website.

To do this, select a Custom Build on the Caddy download page and add the module:

github.com/caddy-dns/servercow

After that, you can download the built binary for your operating system and install it like a normal Caddy version.

Configuration with Caddyfile¶

Global ACME DNS configuration¶

If you want to set the DNS challenge globally for Caddy, you can configure it like this:

{
    acme_dns servercow <username> <password>
}

TLS configuration per host¶

Alternatively, you can define the DNS challenge directly per site:

tls {
    dns servercow <username> <password>
}

Recommended option using environment variables¶

To avoid storing credentials directly in the Caddyfile, you should use environment variables:

tls {
    dns servercow {
        username {env.SERVERCOW_USERNAME}
        password {env.SERVERCOW_PASSWORD}
    }
}

Example for a complete site¶

example.com, *.example.com {
    tls {
        dns servercow {
            username {env.SERVERCOW_USERNAME}
            password {env.SERVERCOW_PASSWORD}
        }
    }

    respond "Hello from Caddy with Servercow DNS"
}

This setup is especially useful if you need a wildcard certificate for your domain.

JSON configuration¶

If you configure Caddy via JSON, the ACME issuer can look like this:

{
  "module": "acme",
  "challenges": {
    "dns": {
      "provider": {
        "name": "servercow",
        "username": "YOUR_SERVERCOW_USERNAME",
        "password": "YOUR_SERVERCOW_PASSWORD"
      }
    }
  }
}

Security notes¶

We recommend that you do not store API credentials directly in the Caddyfile, but provide them exclusively through environment variables.

Example:

export SERVERCOW_USERNAME="dein-benutzername"
export SERVERCOW_PASSWORD="dein-passwort"

Then Caddy can use the values via {env.SERVERCOW_USERNAME} and {env.SERVERCOW_PASSWORD}.

Typical use cases¶

This plugin is suitable for, among other things:

automatic certificate issuance with Let's Encrypt
wildcard certificates for subdomains
setups without open port 80 validation
internal or segmented infrastructures where DNS validation is preferred

Troubleshooting¶

If certificate issuance fails, please check:

Are the Servercow DNS API credentials correct?
Is the domain actually managed via Servercow DNS?
Was Caddy built with the github.com/caddy-dns/servercow plugin or downloaded as a custom build with this module?
Are the environment variables set correctly on the system?
Can Caddy reach the API over outbound network access?