certbot-dns-nicmanager 1.1.0

nicmanager AnycastDNS Authenticator plugin for Certbot

certbot-dns-nicmanager

Status: stable (1.0). Running in production — wildcard issuance + automatic renewal against the live nicmanager AnycastDNS API.

A Certbot DNS authenticator plugin for nicmanager AnycastDNS. It automates the dns-01 ACME challenge by creating, and then removing, the _acme-challenge TXT record through the nicmanager API — which makes it possible to issue wildcard certificates for domains hosted on nicmanager.

There was no Certbot plugin for the nicmanager API, and the lego-based multi-provider plugins do not yet support nicmanager's current API. This plugin fills that gap with a small, dependency-light, well-tested implementation.

Why DNS-01 (and not HTTP-01)?

dns-01 is the only ACME challenge type that can issue wildcard certificates, and it does not require any inbound HTTP reachability. It also keeps your individual service hostnames out of the public Certificate Transparency logs that a per-host http-01 certificate would expose.

Installation

pip install certbot-dns-nicmanager

Install the plugin into the same Python environment as Certbot. If you installed Certbot via snap, install the plugin with snap install certbot-dns-nicmanager once it is published there, or run Certbot from a pip environment that contains both packages.

Verify it is registered:

certbot plugins
# ... should list:  * dns-nicmanager

Credentials

This plugin authenticates against the nicmanager API with HTTP Basic auth. The strongly recommended setup is a dedicated API-ACME account, which nicmanager restricts to managing only the _acme-challenge.<zone> TXT record:

Module	Rights
Webfrontend	–
Account settings	–
Domains	–
Nameserver	View, Manage (create, edit, delete)
Domainsecurity	–
Other modules	–

Because such an account can touch nothing but the challenge record, a leaked credential cannot be used to hijack other records, transfer domains, or read account data.

Two-factor authentication (TOTP) is supported. If the account has 2FA enabled, the API requires a rotating code in the X-Auth-Token header on every request. Provide the account's base32 TOTP secret as dns_nicmanager_totp_secret and the plugin generates the code per request. Leave it unset for accounts without 2FA. The host clock must be accurate (NTP): a skewed clock yields an invalid code, and repeated invalid codes get the account throttled.

Create an INI file, e.g. ~/.secrets/certbot/nicmanager.ini:

# nicmanager API credentials used by Certbot
dns_nicmanager_username = mylogin.acmeuser
# Quote the password if it contains '#' — an unquoted '#' starts an INI comment.
dns_nicmanager_password = "0123456789abcdef0123456789abcdef"

# Optional. Base32 TOTP secret — required only if the account has 2FA enabled.
# dns_nicmanager_totp_secret = JBSWY3DPEHPK3PXP

# Optional. Defaults to https://api.nicmanager.com/v1
# dns_nicmanager_endpoint = https://api.nicmanager.com/v1

# Optional. Skip zone detection and always use this zone.
# dns_nicmanager_zone = example.com

The username is login.username (or the account email). Zone detection works without any read access, so dns_nicmanager_zone is only needed in unusual multi-zone-suffix setups.

The username is either login.username or the account email address, as configured in nicmanager.

Protect this file:

chmod 600 ~/.secrets/certbot/nicmanager.ini

Usage

# A single hostname
certbot certonly \
  --authenticator dns-nicmanager \
  --dns-nicmanager-credentials ~/.secrets/certbot/nicmanager.ini \
  -d example.com

# A wildcard (and the apex)
certbot certonly \
  --authenticator dns-nicmanager \
  --dns-nicmanager-credentials ~/.secrets/certbot/nicmanager.ini \
  -d 'example.com' -d '*.example.com'

Command-line arguments

Argument	Description	Default
--dns-nicmanager-credentials	Path to the nicmanager credentials INI file. (required)	–
--dns-nicmanager-propagation-seconds	Seconds to wait for DNS propagation before the ACME server checks the record.	60

How it works

1. Certbot asks the plugin to create _acme-challenge.<domain> with the validation token.
2. The plugin determines the owning AnycastDNS zone without reading it — a restricted API-ACME account cannot read zones. It tries POST /v1/anycast/<candidate>/records against each candidate zone (most-specific first); a 403/404 skips to the next candidate, the first 2xx wins. An explicit dns_nicmanager_zone short-circuits this. A 401 (genuine auth failure) is surfaced immediately.
3. nicmanager returns the new record's numeric id, which the plugin remembers.
4. After validation, the plugin removes the record via DELETE /v1/anycast/<zone>/records/<id>.

TTL is fixed at the API minimum of 900 seconds.

Heads-up: the API blocks the IP after too many failed logins. Make sure the password is correct (and any # in it is quoted in the INI, see below) before running at scale.

Troubleshooting

Common failures, decoded (full details in docs/TROUBLESHOOTING.md):

Response	Meaning	Fix
401 Authentication error	Wrong username form or password	Match the username to the account's auth method: email for "E-Mail + Passwort" accounts, login.username otherwise.
401 Missing 2FA token header (X-Auth-Token)	Account has 2FA but no secret configured	Set dns_nicmanager_totp_secret to the account's base32 TOTP secret.
403 API usage not allowed	Auth OK — API access not enabled	Ask nicmanager support to enable API access for the account.
401 Too many invalid attempts / no response (000)	IP rate-limited / firewall-blocked after failed logins	Stop and wait. Never loop over credential variants — it locks the IP. Check the host clock (NTP) if using 2FA — skew makes every code invalid.

Key gotchas: the username form depends on the account's active authentication method (email vs login.username); 2FA is supported via dns_nicmanager_totp_secret (needs an accurate clock); a # in the password must be quoted in the INI; and the restricted API-ACME account cannot read zones (this plugin resolves the zone by create-attempt instead).

Development

git clone https://github.com/jp1337/certbot-dns-nicmanager
cd certbot-dns-nicmanager
python -m venv .venv && . .venv/bin/activate
pip install -e '.[test,dev]'

pytest          # run the test suite
ruff check .    # lint
mypy certbot_dns_nicmanager

For the design and the reasoning behind it, see docs/ARCHITECTURE.md and the Architecture Decision Records in docs/decisions/ (DNS-01-only, zone resolution without zone reads, and the basic-auth username / cleanup-by-id decisions).

License

Apache License 2.0

This is an independent, community-maintained plugin and is not affiliated with or endorsed by InterNexum GmbH / nicmanager or the EFF / Certbot project.