# lego-certbot
A compatibility script between [Lego](https://go-acme.github.io/lego) and [Certbot](https://certbot.eff.org), to allow Lego to use Certbot authenticator plugins to perform `DNS-01` challenges.
Designed to be run using the [`exec`](https://go-acme.github.io/lego/dns/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](https://go-acme.github.io/lego/dns/exec/#base-configuration).
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](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins) 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](https://github.com/Callum027/certbot-dns-metaname) as the Certbot authenticator.
### Lego
A complete invocation of Lego to generate a wildcard certificate would look something like this.
```bash
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](https://doc.traefik.io/traefik/getting-started/configuration-overview/#the-static-configuration) (`traefik.yml`):
```yaml
# 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](https://doc.traefik.io/traefik/getting-started/configuration-overview/#the-dynamic-configuration) (`file` provider):
```yaml
# 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](https://github.com/go-acme/lego/pull/1718) 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/Callum027/lego-certbot",
"name": "lego-certbot",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0.0",
"maintainer_email": "",
"keywords": "certbot,lego,letsencrypt,dns-01",
"author": "Callum Dickinson",
"author_email": "callum.dickinson.nz@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/54/b5/c9492ffb4414b844fc4c08f711ba0dfad4643e17a7736149dddbb6780117/lego_certbot-1.0.0.tar.gz",
"platform": null,
"description": "# lego-certbot\n\nA compatibility script between [Lego](https://go-acme.github.io/lego) and [Certbot](https://certbot.eff.org), to allow Lego to use Certbot authenticator plugins to perform `DNS-01` challenges.\n\nDesigned to be run using the [`exec`](https://go-acme.github.io/lego/dns/exec) provider in `default` mode.\n\n## Installation\n\nThe latest version of `lego-certbot` can be directly installed using `pip`.\n\n```\n$ python3 -m pip install lego-certbot\n```\n\nIf you'd prefer to clone the `lego-certbot` repository directly, you can install it as a local package in a virtual environment.\n\n```\n$ git clone https://github.com/Callum027/lego-certbot.git\n$ cd lego-certbot\n$ python3 -m venv .venv\n$ source .venv/bin/activate\n$ python3 -m pip install -r requirements.txt .\n```\n\n`lego-certbot` uses Poetry, so it is recommended to setup a development environment using `poetry install`.\n\n```\n$ git clone https://github.com/Callum027/lego-certbot.git\n$ cd lego-certbot\n$ poetry install [--with=dev]\n```\n\n## Configuration\n\nConfiguration of the Lego `exec` provider is done via [environment variables](https://go-acme.github.io/lego/dns/exec/#base-configuration).\n\nBase configuration:\n\n* `EXEC_PATH` - Path to the script (e.g. `/usr/local/bin/lego-certbot`)\n\n`EXEC_MODE` must be undefined, or otherwise not set to `RAW` mode.\n\nAdditional configuration used by the script:\n\n* `EXEC_POLLING_INTERVAL` - Time between DNS propagation checks, in seconds.\\\n Default: `5`\n* `EXEC_PROPAGATION_TIMEOUT` - Maximum waiting time for DNS propagation, in seconds. Used to set `propagation_seconds` in the Certbot authenticator plugin.\\\n Default: (plugin default)\n\nAs Lego's `exec` provider enforces a standard interface for the script itself, `lego-certbot` configuration cannot be done via the command line.\n\n```\n$ lego-certbot --help\nusage: lego-certbot [-h] {present,cleanup,timeout} [name] [value]\n\nA compatibility script between Lego and Certbot, to allow Lego to use Certbot authenticator plugins to perform DNS-01 challenges.\nDesigned to be run using the 'exec' provider in 'default' mode.\n\npositional arguments:\n {present,cleanup,timeout}\n ACME challenge command type\n name ACME challenge TXT record name (e.g. _acme-challenge.example.com)\n value ACME challenge TXT record value\n\noptional arguments:\n -h, --help show this help message and exit\n -v, --version show program's version number and exit\n```\n\nInstead, `lego-certbot` itself is configured using the following environment variables:\n\n* `LEGOCERTBOT_DOMAIN` - The root domain name of the (sub)domain for which the ACME challenge will take place.\\\n Example: `example.com`\n* `LEGOCERTBOT_AUTHENTICATOR_TYPE` - The [DNS authenticator plugin](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins) to use.\\\n Example: `dns-metaname`\n* `LEGOCERTBOT_AUTHENTICATOR_CONFIG` - Parameters to pass to the authenticator, in JSON format.\\\n Example: `{\"endpoint\":\"https://metaname.net/api/1.1\",\"credentials\":\"/etc/traefik/metaname.ini\"}`\n\n## Usage\n\nBelow are some examples of how to integrate `lego-certbot` into your Lego workflow, using [the Metaname DNS authenticator](https://github.com/Callum027/certbot-dns-metaname) as the Certbot authenticator.\n\n### Lego\n\nA complete invocation of Lego to generate a wildcard certificate would look something like this.\n\n```bash\nEXEC_PATH=\"/usr/local/bin/lego-certbot\" \\\nEXEC_POLLING_INTERVAL=5 \\\nEXEC_PROPAGATION_TIMEOUT=120 \\\nLEGOCERTBOT_DOMAIN=\"example.com\" \\\nLEGOCERTBOT_AUTHENTICATOR_TYPE=\"dns-metaname\" \\\nLEGOCERTBOT_AUTHENTICATOR_CONFIG='{\"endpoint\":\"https://metaname.net/api/1.1\",\"credentials\":\"/etc/traefik/metaname.ini\"}' \\\nlego --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\n```\n\n### Traefik\n\nThis example shows how `lego-certbot` can be used with Traefik to generate wildcard certificates for all services under a root domain.\n\n[Static configuration](https://doc.traefik.io/traefik/getting-started/configuration-overview/#the-static-configuration) (`traefik.yml`):\n```yaml\n# Reverse proxy entrypoints.\n# (Not relevant to the example)\nentryPoints:\n # HTTP entrypoint.\n # Automatically redirect HTTP to HTTPS.\n web:\n address: \":80\"\n http:\n redirections:\n entryPoint:\n to: websecure\n # HTTPS entrypoint.\n websecure:\n address: \":443\"\n\n# Certificate resolvers, used to generate TLS certificates for routers.\n# In this case, we're using Let's Encrypt to generate certificates via the DNS-01 challenge.\ncertificatesResolvers:\n letsencrypt:\n acme:\n # Email address to send to Let's Encrypt.\n email: you@example.com\n # Path to save ACME certification files to.\n # (Paths are resolved relative to the pwd of the Traefik process.)\n storage: acme.json\n # DNS-01 challenge configuration.\n dnsChallenge:\n # Lego DNS provider to use.\n provider: exec\n # Authoritative nameservers for the DNS provider to check against.\n # In this example, these are Metaname's servers.\n resolvers:\n - \"49.50.242.204:53\"\n - \"103.11.126.252:53\"\n - \"103.11.126.244:53\"\n # During development, uncomment the following line to use the Let's Encrypt staging server.\n # Necessary to avoid hitting the rate limits on the production servers.\n caServer: https://acme-staging-v02.api.letsencrypt.org/directory\n```\n\n[Dynamic configuration](https://doc.traefik.io/traefik/getting-started/configuration-overview/#the-dynamic-configuration) (`file` provider):\n```yaml\n# Example router/service which receives a wildcard certificate\n# from the Let's Encrypt certificate resolver.\nhttp:\n routers:\n whoami:\n rule: \"Host(`whoami.example.com`)\"\n service: whoami\n entryPoints:\n - websecure\n tls:\n certResolver: letsencrypt\n domains:\n - main: \"example.com\"\n sans: \"*.example.com\"\n services:\n whoami:\n loadBalancer:\n servers:\n - url: \"http://192.0.2.1:8080/\"\n```\n\n## Tips and Tricks\n\n### Lego CNAME traversal\n\nSince version 4.9.0, [recursive traversal of ACME challenge CNAME records](https://github.com/go-acme/lego/pull/1718) was enabled by default in Lego. Previously, this was enabled by defining the `LEGO_EXPERIMENTAL_CNAME_SUPPORT` environment variable.\n\nDNS configurations where the `_acme-challenge` subdomain resolves to a wildcard `CNAME` record for the root domain may not work properly with this change.\n\nTo 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.\n\nTo restore the old behaviour, define the `LEGO_DISABLE_CNAME_SUPPORT` environment variable.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lego DNS-01 exec provider script for Certbot authenticator plugins",
"version": "1.0.0",
"split_keywords": [
"certbot",
"lego",
"letsencrypt",
"dns-01"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4c6b1886f7da0f5d83bfe252d0f1362b432e7603a219c3cfa53d6df1c575777",
"md5": "bfa345cca6b88dd595ae437a193f1e5a",
"sha256": "1bf7adc61b3cb88e2ebd55d6e7477ba6aac4f72e9ced32e38c7c1ed72ae69341"
},
"downloads": -1,
"filename": "lego_certbot-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bfa345cca6b88dd595ae437a193f1e5a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0.0",
"size": 7012,
"upload_time": "2023-03-11T21:01:20",
"upload_time_iso_8601": "2023-03-11T21:01:20.972740Z",
"url": "https://files.pythonhosted.org/packages/f4/c6/b1886f7da0f5d83bfe252d0f1362b432e7603a219c3cfa53d6df1c575777/lego_certbot-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "54b5c9492ffb4414b844fc4c08f711ba0dfad4643e17a7736149dddbb6780117",
"md5": "0e24ea14d7a683b1d1368b5a5cd83e81",
"sha256": "d218522d3f418dfd5a0c616a0f421ad44ac009e4454f29674dbaca88361eec31"
},
"downloads": -1,
"filename": "lego_certbot-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "0e24ea14d7a683b1d1368b5a5cd83e81",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0.0",
"size": 6298,
"upload_time": "2023-03-11T21:01:22",
"upload_time_iso_8601": "2023-03-11T21:01:22.814166Z",
"url": "https://files.pythonhosted.org/packages/54/b5/c9492ffb4414b844fc4c08f711ba0dfad4643e17a7736149dddbb6780117/lego_certbot-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-11 21:01:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Callum027",
"github_project": "lego-certbot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "lego-certbot"
}
JSON
