Certbot DNS Multi-provider Plugin

4.33.0 · active · verified Sun Apr 12

Certbot DNS plugin supporting multiple DNS providers by integrating with the `go-acme/lego` ACME client, which currently supports over 117 different DNS providers. It simplifies obtaining wildcard certificates and automating DNS-01 challenges for Certbot users. The current version is 4.33.0, and it appears to be actively maintained with regular updates.

Warnings

gotcha Installing via `pip` on certain Linux x86_64 / amd64 distributions for Python versions earlier than 3.11, or on other platforms, may require Go 1.24+ to be installed on your server for the plugin to compile successfully.
Fix: Ensure Go 1.24 or newer is installed if `pip install` fails to find a pre-compiled wheel for your system, or use the `snap` installation method if available.
gotcha The plugin is controlled via a credentials file (`.ini`). The specific environment variable names for DNS provider API keys/tokens (e.g., `CLOUDFLARE_API_TOKEN`) are dictated by the underlying `go-acme/lego` library, not `certbot-dns-multi`.
Fix: Always consult the official `lego` documentation (https://go-acme.github.io/lego/dns/) for the correct credential names for your specific DNS provider.
gotcha The credentials file containing API keys/tokens must be secured with strict permissions.
Fix: Run `chmod 0600 /etc/letsencrypt/dns-multi.ini` (or the path to your credentials file) immediately after creation to prevent unauthorized access.
gotcha This library is a Certbot plugin and is designed to be used via the `certbot` command-line interface. It does not expose a direct Python API for programmatic interaction.
Fix: Interact with `certbot-dns-multi` exclusively through `certbot` commands, specifying `-a dns-multi` and `--dns-multi-credentials`.

Install

pip install certbot-dns-multi Standard pip installation
sudo /opt/certbot/bin/pip install certbot-dns-multi For Certbot installed via official pip instructions
sudo snap install certbot-dns-multi sudo snap set certbot trust-plugin-with-root=ok sudo snap connect certbot:plugin certbot-dns-multi For Certbot installed via Snap

Quickstart

To use `certbot-dns-multi`, create a credentials file specifying your DNS provider and API credentials. Secure this file, then invoke Certbot with the `dns-multi` authenticator and point to your credentials file. This example uses Cloudflare, but you must refer to the `go-acme/lego` documentation for the specific environment variables required by your chosen DNS provider.

# Create a credentials file (e.g., /etc/letsencrypt/dns-multi.ini)
# Replace 'cloudflare' with your DNS provider, and add required API tokens/keys.
# Consult https://go-acme.github.io/lego/dns/ for provider-specific environment variables.
# Example for Cloudflare:
# dns_multi_provider = cloudflare
# CLOUDFLARE_API_TOKEN="${CLOUDFLARE_API_TOKEN}"

# Secure the credentials file
sudo chmod 0600 /etc/letsencrypt/dns-multi.ini

# Issue a wildcard certificate using dns-multi plugin (example with Cloudflare)
# Replace 'example.com' with your domain and ensure CLOUDFLARE_API_TOKEN is set as an environment variable or hardcoded in the ini for testing.
certbot certonly \
  -a dns-multi \
  --dns-multi-credentials /etc/letsencrypt/dns-multi.ini \
  -d "*.example.com" \
  --dry-run

view raw JSON →