Lego DNS-01 exec provider script for Certbot authenticator plugins
Project description
lego-certbot
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.
Installation
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
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:5
EXEC_PROPAGATION_TIMEOUT
- Maximum waiting time for DNS propagation, in seconds. Used to setpropagation_seconds
in 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.com
LEGOCERTBOT_AUTHENTICATOR_TYPE
- The DNS authenticator plugin to use.
Example:dns-metaname
LEGOCERTBOT_AUTHENTICATOR_CONFIG
- Parameters to pass to the authenticator, in JSON format.
Example:{"endpoint":"https://metaname.net/api/1.1","credentials":"/etc/traefik/metaname.ini"}
Usage
Below are some examples of how to integrate lego-certbot
into your Lego workflow, using the Metaname DNS authenticator as the Certbot authenticator.
Lego
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 run
Traefik
This 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/directory
Dynamic 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/"
Tips and Tricks
Lego CNAME traversal
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file lego_certbot-1.0.0.tar.gz
.
File metadata
- Download URL: lego_certbot-1.0.0.tar.gz
- Upload date:
- Size: 6.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.4.0 CPython/3.8.3 Windows/10
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | d218522d3f418dfd5a0c616a0f421ad44ac009e4454f29674dbaca88361eec31 |
|
MD5 | 0e24ea14d7a683b1d1368b5a5cd83e81 |
|
BLAKE2b-256 | 54b5c9492ffb4414b844fc4c08f711ba0dfad4643e17a7736149dddbb6780117 |
File details
Details for the file lego_certbot-1.0.0-py3-none-any.whl
.
File metadata
- Download URL: lego_certbot-1.0.0-py3-none-any.whl
- Upload date:
- Size: 7.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.4.0 CPython/3.8.3 Windows/10
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1bf7adc61b3cb88e2ebd55d6e7477ba6aac4f72e9ced32e38c7c1ed72ae69341 |
|
MD5 | bfa345cca6b88dd595ae437a193f1e5a |
|
BLAKE2b-256 | f4c6b1886f7da0f5d83bfe252d0f1362b432e7603a219c3cfa53d6df1c575777 |