Skip to content


Repository files navigation

Standalone DNS Authenticator plugin for Certbot

This is a plugin that uses an integrated DNS server to respond to the _acme-challenge records, so the domain's records do not have to be modified.



# pip3 install certbot certbot-dns-standalone


# snap install certbot certbot-dns-standalone
# snap set certbot trust-plugin-with-root=ok
# snap connect certbot:plugin certbot-dns-standalone
# snap connect certbot-dns-standalone:certbot-metadata certbot:certbot-metadata


# apt-get install certbot python3-certbot-dns-standalone


First, you need to pick a central address for certbot, e.g.

Next, the _acme-challenge records need to be pointed to $ using CNAME records, e.g. for

_acme-challenge  IN  CNAME

Finally, you need to point * to certbot. There are two options for that.

Firstly, if you have an IP address with port 53 available, you could configure it as the nameserver for

acme     IN  NS
ns.acme  IN  A

where is the IP of the server where certbot will be run. This configuration directs any requests to * to where the plugin will respond with the relevant challenge.

Any server can be used as long as port 53 is available which means that a DNS server cannot be run at that particular IP at the same time.

You can then run certbot as follows:

certbot --non-interactive --agree-tos --email certonly \
  --authenticator dns-standalone \
  --dns-standalone-address= \
  -d -d '*'

Secondly, if you already run a DNS server you could configure it to forward all requests to * to another IP/port instead where you would run certbot.

With Knot DNS you can use mod-dnsproxy:

  - id: certbot

  - id: certbot
    remote: certbot
    fallback: off

  - domain:
    module: mod-dnsproxy/certbot

Using this configuration all requests to * are directed to port 5555.

You can then run certbot as follows:

certbot --non-interactive --agree-tos --email certonly \
  --authenticator dns-standalone \
  --dns-standalone-address= \
  --dns-standalone-port=5555 \
  -d -d '*'

By default the plugin binds to all available interfaces. The validation usually takes less than a second.

To renew the certificates add certbot renew to crontab.

Usage with Docker

First, build the certbot image:

docker build -t certbot /path/to/certbot-dns-standalone/

Next, the certificate:

docker run -it --rm --name certbot \
  -v "/etc/letsencrypt:/etc/letsencrypt" \
  -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
  -p 8080:80 -p -p \
  certbot certonly

where is the IP address to use for responding the challenges. HTTP challenges should be directed to port 8080.

/etc/letsencrypt and /var/lib/letsencrypt need to be mapped to permanent storage.

Supported parameters

Parameters can be specified as --dns-standalone-PARAMETER=VALUE. For older certbot versions it should be --certbot-dns-standalone:dns-standalone-PARAMETER=VALUE.

Supported parameters are:

  • address -- IPv4 address to bind to, defaults to
  • ipv6-address -- IPv6 address to bind to, defaults to ::
  • port -- port to use, defaults to 53

The relevant parameters in /etc/letsencrypt/renewal/*.conf are dns_standalone_address, dns_standalone_port and dns_standalone_ipv6_address.

Third party projects

Third party projects integrating certbot-dns-standalone: