Skip to main content

Standalone DNS Authenticator plugin for Certbot

Project description

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 certmaster@example.com 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 certmaster@example.com 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:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

certbot_dns_standalone-1.2.1.tar.gz (13.3 kB view details)

Uploaded Source

Built Distribution

certbot_dns_standalone-1.2.1-py2.py3-none-any.whl (10.5 kB view details)

Uploaded Python 2Python 3

File details

Details for the file certbot_dns_standalone-1.2.1.tar.gz.

File metadata

  • Download URL: certbot_dns_standalone-1.2.1.tar.gz
  • Upload date:
  • Size: 13.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.2

File hashes

Hashes for certbot_dns_standalone-1.2.1.tar.gz
Algorithm Hash digest
SHA256 1f708ef5f351d0ea6e3b6dadea2886a6d0db98d45d62756b456c9f423fc5388a
MD5 e29700148ff68311de0251de3c6bc55b
BLAKE2b-256 a1a344b4c4129a6526202b1a3b29389749c2284fdf1ceded3b826e8528bed33f

See more details on using hashes here.

File details

Details for the file certbot_dns_standalone-1.2.1-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for certbot_dns_standalone-1.2.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 e7af1d392588acd329e127354ce6db015942bad16d24ad17643ba4129700d722
MD5 64a76c9ff3fb3106498548c71238c88f
BLAKE2b-256 80bb2f8dbd23d70eb04aa1e3d29c58c989cfb07b002a93fd68c18edafc704f66

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page