Skip to main content

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 set propagation_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


Download files

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

Source Distribution

lego_certbot-1.0.0.tar.gz (6.3 kB view details)

Uploaded Source

Built Distribution

lego_certbot-1.0.0-py3-none-any.whl (7.0 kB view details)

Uploaded Python 3

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

Hashes for lego_certbot-1.0.0.tar.gz
Algorithm Hash digest
SHA256 d218522d3f418dfd5a0c616a0f421ad44ac009e4454f29674dbaca88361eec31
MD5 0e24ea14d7a683b1d1368b5a5cd83e81
BLAKE2b-256 54b5c9492ffb4414b844fc4c08f711ba0dfad4643e17a7736149dddbb6780117

See more details on using hashes here.

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

Hashes for lego_certbot-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 1bf7adc61b3cb88e2ebd55d6e7477ba6aac4f72e9ced32e38c7c1ed72ae69341
MD5 bfa345cca6b88dd595ae437a193f1e5a
BLAKE2b-256 f4c6b1886f7da0f5d83bfe252d0f1362b432e7603a219c3cfa53d6df1c575777

See more details on using hashes here.

Supported by

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