From 7ae3734e52244006d9e654fcf76355fa92a9fd7b Mon Sep 17 00:00:00 2001 From: Sven Luthi Date: Tue, 27 Oct 2026 12:16:23 +0100 Subject: [PATCH] modified: README.md --- README.md | 126 ++++++++++++++++++++++++++---------------------------- 1 file changed, 61 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 656b731..8ec2dac 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Certbot DNS Netbox +# Certbot DNS NetBox Certbot DNS-01 authenticator plugin that updates the challenge TXT records in [NetBox DNS](https://github.com/sys4/netbox-plugin-dns) (the `netbox-dns` @@ -28,13 +28,68 @@ expects them: | `NETBOX_URL` | Base URL of the NetBox instance | | `NETBOX_BEARER` | NetBox API token (`Authorization: Bearer`) | | `NETBOX_TOKEN` | NetBox API token (`Authorization: Token`) | -| `SEARCH_VIEW` | NETBOX DNS View to search for records in. | +| `SEARCH_VIEW` | NetBox DNS view to search for records in. | | `DEBUG` | Optional: verbose nbapi.py logging | One of `NETBOX_BEARER` / `NETBOX_TOKEN` is required. The token's user needs NetBox object permissions to view and change netbox-dns records only — no zone or view permissions are required. + +## Usage + +``` +export NETBOX_URL=https://netbox.example.com +export NETBOX_BEARER= + +certbot certonly \ + --authenticator dns-netbox \ + --dns-netbox-propagation-seconds 60 \ + -d example.com -d '*.example.com' +``` + +### Options + +| Option | Default | Description | +| ---------------------------------- | -------------- | ------------------------------------ | +| `--dns-netbox-propagation-seconds` | `30` | Seconds to wait for DNS propagation | +| `--dns-netbox-ttl` | keep current | TTL of the challenge TXT record (s) | +| `--dns-netbox-insecure` | off | Skip TLS verification towards NetBox | + +The netbox-dns view to search is configured in code: `search_view` at the top +of `certbot_dns_netbox/dns_netbox.py`. + +### Renewal configuration + +certbot stores the authenticator in the renewal configuration, so renewals +need no extra flags: + +``` +# /etc/letsencrypt/renewal/example.com.conf +[renewalparams] +authenticator = dns-netbox +dns_netbox_ttl = 120 +``` + +When certbot runs unattended (cron or systemd timer), make sure the `NETBOX_*` +environment variables are set, e.g. via a systemd `EnvironmentFile=` or a +wrapper script. + + +## Verification + +``` +certbot plugins --init dns-netbox # plugin is discovered and loads +certbot certonly --dry-run \ + --authenticator dns-netbox \ + -d sub.example.com # end-to-end against the staging ACME API +``` + +Watch the `_acme-challenge` TXT records in the `_default_` view: their values +change to the challenge tokens during the run and remain in place afterwards. +The next renewal updates the same records again. + + ## Tutorial: end-to-end setup This walkthrough sets up certificates for `example.com`, including the @@ -42,10 +97,10 @@ wildcard, from scratch. Adapt domains, names and paths to your environment. ### 1. Create the DNS zone -Create the `example.com` zone in netbox-dns, in the view the plugin searches -(`SEARCH_VIEW` environment variable, default: `_default_`), and note the -numeric **zone ID** of the new zone — it is shown in the web UI URL and can -be looked up with: +Create the `example.com` zone in netbox-dns, in the view the plugin will search +(Set by `SEARCH_VIEW` environment variable, default: `_default_`). Note the +numeric **zone ID** of the new zone — it is shown in the web UI URL and can be +looked up with: ``` GET /api/plugins/netbox-dns/zones/?name=example.com @@ -163,62 +218,3 @@ And a cron entry, e.g. `/etc/cron.d/certbot-netbox`: authenticator flags are needed here. Add a `--deploy-hook` (e.g. restarting the web server) if services need to pick up the renewed certificate. -## Installation - -Install into the same Python environment as certbot: - -``` -pip install certbot-dns-netbox -``` - -## Usage - -``` -export NETBOX_URL=https://netbox.example.com -export NETBOX_BEARER= - -certbot certonly \ - --authenticator dns-netbox \ - --dns-netbox-propagation-seconds 60 \ - -d example.com -d '*.example.com' -``` - -### Options - -| Option | Default | Description | -| ---------------------------------- | -------------- | ------------------------------------ | -| `--dns-netbox-propagation-seconds` | `30` | Seconds to wait for DNS propagation | -| `--dns-netbox-ttl` | keep current | TTL of the challenge TXT record (s) | -| `--dns-netbox-insecure` | off | Skip TLS verification towards NetBox | - -The netbox-dns view to search is configured in code: `search_view` at the top -of `certbot_dns_netbox/dns_netbox.py`. - -### Renewal configuration - -certbot stores the authenticator in the renewal configuration, so renewals -need no extra flags: - -``` -# /etc/letsencrypt/renewal/example.com.conf -[renewalparams] -authenticator = dns-netbox -dns_netbox_ttl = 120 -``` - -When certbot runs unattended (cron or systemd timer), make sure the `NETBOX_*` -environment variables are set, e.g. via a systemd `EnvironmentFile=` or a -wrapper script. - -## Verification - -``` -certbot plugins --init dns-netbox # plugin is discovered and loads -certbot certonly --dry-run \ - --authenticator dns-netbox \ - -d sub.example.com # end-to-end against the staging ACME API -``` - -Watch the `_acme-challenge` TXT records in the `_default_` view: their values -change to the challenge tokens during the run and remain in place afterwards. -The next renewal updates the same records again.