A compatibility script between Lego and Certbot, to allow Lego to use Certbot authenticator plugins to perform DNS-01 challenges.
Designed to be run using the exec provider in default mode.
The latest version of lego-certbot can be directly installed using pip.
$ python3 -m pip install lego-certbot
If you'd prefer to clone the lego-certbot repository directly, you can install it as a local package in a virtual environment.
$ git clone https://github.com/Callum027/lego-certbot.git
$ cd lego-certbot
$ python3 -m venv .venv
$ source .venv/bin/activate
$ python3 -m pip install -r requirements.txt .
lego-certbot uses Poetry, so it is recommended to setup a development environment using poetry install.
$ git clone https://github.com/Callum027/lego-certbot.git
$ cd lego-certbot
$ poetry install [--with=dev]
Configuration of the Lego exec provider is done via environment variables.
Base configuration:
EXEC_PATH- Path to the script (e.g./usr/local/bin/lego-certbot)
EXEC_MODE must be undefined, or otherwise not set to RAW mode.
Additional configuration used by the script:
EXEC_POLLING_INTERVAL- Time between DNS propagation checks, in seconds.
Default:5EXEC_PROPAGATION_TIMEOUT- Maximum waiting time for DNS propagation, in seconds. Used to setpropagation_secondsin the Certbot authenticator plugin.
Default: (plugin default)
As Lego's exec provider enforces a standard interface for the script itself, lego-certbot configuration cannot be done via the command line.
$ lego-certbot --help
usage: lego-certbot [-h] {present,cleanup,timeout} [name] [value]
A compatibility script between Lego and Certbot, to allow Lego to use Certbot authenticator plugins to perform DNS-01 challenges.
Designed to be run using the 'exec' provider in 'default' mode.
positional arguments:
{present,cleanup,timeout}
ACME challenge command type
name ACME challenge TXT record name (e.g. _acme-challenge.example.com)
value ACME challenge TXT record value
optional arguments:
-h, --help show this help message and exit
-v, --version show program's version number and exit
Instead, lego-certbot itself is configured using the following environment variables:
LEGOCERTBOT_DOMAIN- The root domain name of the (sub)domain for which the ACME challenge will take place.
Example:example.comLEGOCERTBOT_AUTHENTICATOR_TYPE- The DNS authenticator plugin to use.
Example:dns-metanameLEGOCERTBOT_AUTHENTICATOR_CONFIG- Parameters to pass to the authenticator, in JSON format.
Example:{"endpoint":"https://metaname.net/api/1.1","credentials":"/etc/traefik/metaname.ini"}
Below are some examples of how to integrate lego-certbot into your Lego workflow, using the Metaname DNS authenticator as the Certbot authenticator.
A complete invocation of Lego to generate a wildcard certificate would look something like this.
EXEC_PATH="/usr/local/bin/lego-certbot" \
EXEC_POLLING_INTERVAL=5 \
EXEC_PROPAGATION_TIMEOUT=120 \
LEGOCERTBOT_DOMAIN="example.com" \
LEGOCERTBOT_AUTHENTICATOR_TYPE="dns-metaname" \
LEGOCERTBOT_AUTHENTICATOR_CONFIG='{"endpoint":"https://metaname.net/api/1.1","credentials":"/etc/traefik/metaname.ini"}' \
lego --email you@example.com --dns exec --domains example.com --domains *.example.com --dns.resolvers 49.50.242.204:53 --dns.resolvers 103.11.126.252:53 --dns.resolvers 103.11.126.244:53 runThis example shows how lego-certbot can be used with Traefik to generate wildcard certificates for all services under a root domain.
Static configuration (traefik.yml):
# Reverse proxy entrypoints.
# (Not relevant to the example)
entryPoints:
# HTTP entrypoint.
# Automatically redirect HTTP to HTTPS.
web:
address: ":80"
http:
redirections:
entryPoint:
to: websecure
# HTTPS entrypoint.
websecure:
address: ":443"
# Certificate resolvers, used to generate TLS certificates for routers.
# In this case, we're using Let's Encrypt to generate certificates via the DNS-01 challenge.
certificatesResolvers:
letsencrypt:
acme:
# Email address to send to Let's Encrypt.
email: you@example.com
# Path to save ACME certification files to.
# (Paths are resolved relative to the pwd of the Traefik process.)
storage: acme.json
# DNS-01 challenge configuration.
dnsChallenge:
# Lego DNS provider to use.
provider: exec
# Authoritative nameservers for the DNS provider to check against.
# In this example, these are Metaname's servers.
resolvers:
- "49.50.242.204:53"
- "103.11.126.252:53"
- "103.11.126.244:53"
# During development, uncomment the following line to use the Let's Encrypt staging server.
# Necessary to avoid hitting the rate limits on the production servers.
caServer: https://acme-staging-v02.api.letsencrypt.org/directoryDynamic configuration (file provider):
# Example router/service which receives a wildcard certificate
# from the Let's Encrypt certificate resolver.
http:
routers:
whoami:
rule: "Host(`whoami.example.com`)"
service: whoami
entryPoints:
- websecure
tls:
certResolver: letsencrypt
domains:
- main: "example.com"
sans: "*.example.com"
services:
whoami:
loadBalancer:
servers:
- url: "http://192.0.2.1:8080/"Since version 4.9.0, recursive traversal of ACME challenge CNAME records was enabled by default in Lego. Previously, this was enabled by defining the LEGO_EXPERIMENTAL_CNAME_SUPPORT environment variable.
DNS configurations where the _acme-challenge subdomain resolves to a wildcard CNAME record for the root domain may not work properly with this change.
To fix the problem, you could add a explicit CNAME record for the _acme-challenge subdomain to an A record subdomain designated for ACME challenges (e.g. acme.example.com). TXT records will then be created with this subdomain.
To restore the old behaviour, define the LEGO_DISABLE_CNAME_SUPPORT environment variable.