ClouDNS Module for Caddy

This package provides a DNS provider module for Caddy. It allows you to manage DNS records with ClouDNS for automated TLS certificate issuance via the ACME DNS challenge.

Caddy Module Name

dns.providers.cloudns

Installation

To use this module, build Caddy with it included. The simplest way is to use xcaddy:

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

Configuration

Credentials

The module authenticates with the ClouDNS HTTP API using an API user or API sub-user (created in the ClouDNS control panel under API & Resellers):

• auth_id — ClouDNS API user ID (required if sub_auth_id is not provided)
• sub_auth_id — ClouDNS API sub-user ID (required if auth_id is not provided)
• auth_password — ClouDNS API password (required)

Each credential is resolved in this order:

1. The value set in the Caddy configuration (JSON or Caddyfile), after placeholder resolution, so {env.CLOUDNS_AUTH_ID}-style values work.
2. If unset, the corresponding environment variable is used as a fallback: CLOUDNS_AUTH_ID, CLOUDNS_SUB_AUTH_ID, CLOUDNS_AUTH_PASSWORD.

If no usable credentials are found by either path, provisioning fails with an error that names the missing setting.

Note: ClouDNS lets you restrict an API user by allowed IP addresses and zones; make sure the API user you configure is allowed to manage the zones Caddy serves, from the host Caddy runs on.

Retry behavior (optional)

All DNS operations retry transient API failures with exponential backoff. The defaults (5 attempts, 1s initial backoff, 30s max backoff) work well; they can be tuned if needed:

• operation_retries — maximum attempts per API call
• initial_backoff — delay before the first retry (doubles each attempt)
• max_backoff — upper bound for the retry delay

Configuration Examples

Caddyfile, credentials from environment variables

With CLOUDNS_AUTH_ID (or CLOUDNS_SUB_AUTH_ID) and CLOUDNS_AUTH_PASSWORD set in Caddy's environment, no block is needed at all:

example.com {
  tls {
    dns cloudns
  }
}

Caddyfile, global configuration

{
  acme_dns cloudns {
    auth_id "<auth_id>"
    auth_password "<auth_password>"
  }
}

Caddyfile, per-site configuration

example.com {
  tls {
    dns cloudns {
      sub_auth_id "<sub_auth_id>"
      auth_password "<auth_password>"
      operation_retries 5
      initial_backoff 1s
      max_backoff 30s
    }
  }
}

JSON configuration

Placeholders are resolved when the provider is provisioned, so secrets can be kept out of the config file:

{
  "apps": {
    "tls": {
      "automation": {
        "policies": [
          {
            "issuers": [
              {
                "module": "acme",
                "challenges": {
                  "dns": {
                    "provider": {
                      "name": "cloudns",
                      "auth_id": "{env.CLOUDNS_AUTH_ID}",
                      "auth_password": "{env.CLOUDNS_AUTH_PASSWORD}"
                    }
                  }
                }
              }
            ]
          }
        ]
      }
    }
  }
}

Environment Variables

The following environment variables are used as fallbacks for any credential not specified in the Caddy configuration:

• CLOUDNS_AUTH_ID — ClouDNS API user ID
• CLOUDNS_SUB_AUTH_ID — ClouDNS API sub-user ID
• CLOUDNS_AUTH_PASSWORD — ClouDNS API password

Testing

go test ./...

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgements

This module is based on the libdns/cloudns package and the Caddy project.