This package contains a DNS provider module for Caddy. It can be used to solve DNS-01 challenges with ACME-DNS server.
dns.providers.acmedns
To use ACME-DNS for solving DNS-01 challenge and obtaining a certificate, you'll need:
- Caddy version with this plugin built-in. See xcaddy to learn how to build Caddy with plugins.
- A domain name that you control. In this example, we'll assume it's
your-domain.example.com
. You'll need to be able to create a CNAME record with name_acme-challenge.your-domain.example.com
. - An access to ACME-DNS server. For testing purposes, you can you the public server at https://auth.acme-dns.io. However, self-hosting is highly encouraged. To learn how to self-host ACME-DNS server, refer to ACME-DNS documentation.
Then follow these steps:
-
Register an account on ACME-DNS server (see ACME-DNS documentation). In short: make a POST request to
<ACME-DNS server URL>/register
, i.e. run:curl -X POST https://auth.acme-dns.io/register
The response should be a JSON that contains your new credentials, looking similar to this one:
{ "username": "5d26a340-2e1d-4b6b-af1a-4aab569897b7", "password": "_r2gFOVtrF9I82_l6ZXTfPaxCgldqJSWaTmd4BS9", "fulldomain": "37c51280-79ca-435f-af32-c775eb67e2ab.auth.acme-dns.io", "subdomain": "37c51280-79ca-435f-af32-c775eb67e2ab", "allowfrom": [] }
-
Create a DNS CNAME record that points from
_acme-challenge.your-domain.example.com
to thefulldomain
from the registration response. In this case, it would be_acme-challenge.your-domain.example.com. CNAME 37c51280-79ca-435f-af32-c775eb67e2ab.auth.acme-dns.io.
-
Use the credentials obtained in step 1 to configure
acmedns
plugin in Caddy. This is a simple example of a workingCaddyfile
:your-domain.example.com tls { dns acmedns { username <username you obtained in step 1> password <password you obtained in step 1> subdomain <ACME-DNS subdomain you obtained in step 1> server_url <ACME-DNS server API URL> # e.g. https://auth.acme-dns.io } } respond "Hello"
There are two orthogonal choices that you can make about the configuration of acmedns
plugin.
- Whether to put the credentials directly in
Caddyfile
/caddy.json
or to use a separate credentials file. - Whether to use a simple one-account configuration as described in the previous section or to use a multi-account set up.
You can save acmedns
account credentials as a JSON file instead or writing it directly to Caddyfile
/caddy.json
. The credentials file should look like this:
{
"username": "<username>",
"password": "<password>",
"subdomain": "<subdomain>",
"server_url": "<server_url>"
}
And your Caddyfile
:
your-domain.example.com
tls {
dns acmedns /path/to/credentials.json
}
respond "Hello"
Simple configuration showed in the previous section is enough for most use-cases. If you are serving multiple domains, you can use different dns acmedns {...}
directives for different site blocks and thus use different ACME-DNS accounts per domain:
your-domain-1.example.com {
tls {
dns acmedns {
username <username 1>
...
}
}
respond "Hello 1"
}
your-domain-2.example.com {
tls {
dns acmedns {
username <username 2>
...
}
}
respond "Hello 2"
}
However, you can also provide acmedns
plugin with a single configuration which contains domain->account/credentials mapping. The credentials file will look like this:
{
"your-domain-1.example.com": {
"username": "<username>",
"password": "<password>",
"fulldomain": "<full domain from registration response>",
"subdomain": "<subdomain>",
"server_url": "<server URL>"
},
"your-domain-2.example.com": {
...
}
}
Note that this type of configuration requires one more field โ fulldomain
(as returned by the registration endpoint).
You can also embed this into Caddyfile
directly. If you want this configuration to apply to all site-blocks in your Caddyfile
, use acme_dns global option.
{
acme_dns acmedns {
config {
your-domain-1.example.com {
username <username>
password <password>
subdomain <subdomain>
server_url <server url>
# Note that this type of configuration requires one parameter
# more -- the fulldomain value from registration response
fulldomain <full domain>
}
your-domain-2.example.com {
username <username>
... # same fields as above
}
}
}
}
your-domain-1.example.com {
respond "Hello 1"
}
your-domain-2.example.com {
respond "Hello 2"
}
Using multi-account configuration is useful if you want to manage all your configurations with acme-dns-client CLI tool. acme-dns-client
saves obtained credentials in a JSON file at /etc/acmedns/clientstorage.json
. This file is compatible with acmedns
Caddy plugin, so you can point to it with dns acmedns /etc/acmedns/clientstorage.json
directive (though you need to make sure that Caddy has permissions to read that file).
You have all the same options if you use caddy.json
configuration format instead of Caddyfile
. Configure your ACME issuer like so (single-account configuration):
{
"module": "acme",
"challenges": {
"dns": {
"provider": {
"name": "acmedns",
"username": "<username>",
"password": "<password>",
"subdomain": "<subdomain>",
"server_url": "<server_url>"
}
}
}
}
Or like so (multi-account-configuration):
{
"module": "acme",
"challenges": {
"dns": {
"provider": {
"name": "acmedns",
"config": {
"your-domain-1.example.com": {
"username": "<username>",
"password": "<password>",
"fulldomain": "<full domain from registration response>",
"subdomain": "<subdomain>",
"server_url": "<server URL>"
}
}
}
}
}
}
Or like so (credentials file):
{
"module": "acme",
"challenges": {
"dns": {
"provider": {
"name": "acmedns",
"config_file_path": "/file/to/credentials.json"
}
}
}
}
If Caddy hangs while trying to obtain a certificate and then throws a timeout error, make sure that you created a correct CNAME record:
_acme-challenge.your-domain.example.com. CNAME <ACME-DNS account full domain>
You can check this with dig _acme-challenge.your-domain.example.com.
If this record it correct, this error might be caused by DNS resolvers caching behaviour. Using Cloudflare or Google resolvers (1.1.1.1 and 8.8.8.8) might help:
your-domain.example.com
tls {
resolvers 1.1.1.1 8.8.8.8
dns acmedns {
...
}
}
-
A Technical Deep Dive: Securing the Automation of ACME DNS Challenge Validation
-
ACME-DNS provider for
libdns
โ thisacmedns
Caddy plugin depends onlibdns/acmedns
provider.