Standalone DNS Authenticator plugin for Certbot

This is a Certbot 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.

Installation

pip

# pip3 install certbot certbot-dns-standalone

snap

# 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

Debian

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

Docker

See below.

Usage

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

Next, the _acme-challenge records need to be pointed to $domain.acme.example.com using CNAME records, e.g. for example.net:

_acme-challenge  IN  CNAME  example.net.acme.example.com.

Finally, you need to point *.acme.example.com 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.example.com:

acme     IN  NS  ns.acme.example.com.
ns.acme  IN  A   1.2.3.4

where 1.2.3.4 is the IP of the server where certbot will be run. This configuration directs any requests to *.acme.example.com to 1.2.3.4 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 [email protected] certonly \
  --authenticator dns-standalone \
  --dns-standalone-address=1.2.3.4 \
  -d example.net -d '*.example.net'

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

With Knot DNS you can use mod-dnsproxy:

remote:
  - id: certbot
    address: 127.0.0.1@5555

mod-dnsproxy:
  - id: certbot
    remote: certbot
    fallback: off

zone:
  - domain: acme.example.com
    module: mod-dnsproxy/certbot

Using this configuration all requests to *.acme.example.com are directed to 127.0.0.1 port 5555.

You can then run certbot as follows:

certbot --non-interactive --agree-tos --email [email protected] certonly \
  --authenticator dns-standalone \
  --dns-standalone-address=127.0.0.1 \
  --dns-standalone-port=5555 \
  -d example.net -d '*.example.net'

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

In order to use the latest image published in Docker Hub, run:

docker run -it --rm --name certbot-dns-standalone \
  -v "/etc/letsencrypt:/etc/letsencrypt" \
  -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
  -p 8080:80 -p 1.2.3.4:53:53/tcp -p 1.2.3.4:53:53/udp \
  laurik/certbot-dns-standalone:latest certonly

where 1.2.3.4 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.

Alternatively, you may also build the plugin image locally by running:

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

and then:

docker run -it --rm \
  -v "/etc/letsencrypt:/etc/letsencrypt" \
  -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
  -p 8080:80 -p 1.2.3.4:53:53/tcp -p 1.2.3.4:53:53/udp \
  certbot-dns-standalone-local certonly

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 0.0.0.0
• 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:

• CertCache