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 hashes)

Uploaded Source

Built Distribution

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

Uploaded Python 3

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