Certbot DNS plugin (certbot-dns-gigahost)

certbot-dns-gigahost is a Certbot plugin that completes Let's Encrypt DNS-01 challenges through the Gigahost DNS API, so you can get wildcard certificates (*.example.com) for zones hosted at Gigahost. It adds a TXT record at _acme-challenge.<domain>, waits for it to propagate and removes it after validation.

Source / package: pypi.org/project/certbot-dns-gigahost

Install

pip install certbot-dns-gigahost

Credentials file

The plugin authenticates with an API key. Create one under API Keys with read and write access to DNS for the zones you want certificates for, then create ~/.secrets/certbot/gigahost.ini:

dns_gigahost_api_token = flux_live_xxxxxxxxxxxxxxxxxxxxxxxx

Anyone who can read the file can use the key, so lock it down. Certbot warns on every run while other users can read it:

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

Plugin arguments

Argument	Required	Default	Description
--dns-gigahost-credentials	yes	none	Path to the .ini file.
--dns-gigahost-propagation-seconds	no	120	How long to wait for DNS to propagate before asking Let's Encrypt to validate.

Issue a normal certificate

certbot certonly \
  --authenticator dns-gigahost \
  --dns-gigahost-credentials ~/.secrets/certbot/gigahost.ini \
  -d example.com \
  -d www.example.com

Issue a wildcard certificate

certbot certonly \
  --authenticator dns-gigahost \
  --dns-gigahost-credentials ~/.secrets/certbot/gigahost.ini \
  -d example.com \
  -d "*.example.com"

Docker

docker run --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  -v $(pwd)/secrets:/secrets:ro \
  certbot/certbot:latest \
  certonly \
  --non-interactive --agree-tos --email [email protected] \
  --authenticator dns-gigahost \
  --dns-gigahost-credentials /secrets/gigahost.ini \
  -d example.com \
  -d "*.example.com"

Certbot's official image does not include the plugin. Install it in the container with pip install certbot-dns-gigahost, or use an image that has it.

Renewals

Renewal needs no flags; Certbot stores the plugin choice in /etc/letsencrypt/renewal/<domain>.conf:

certbot renew

Add a test run before scheduling:

certbot renew --dry-run

Troubleshooting

• Unable to determine zone for...: make sure the parent zone exists in your account (GET /dns/zones).
• Validation times out: bump --dns-gigahost-propagation-seconds to 300 or 600 if your resolvers are slow to pick up the new TXT record.
• 401 Unauthorized: the API key in the credentials file is wrong or has been deleted. Older versions of the plugin logged in with email and password, which the API no longer accepts; upgrade with pip install -U certbot-dns-gigahost and switch the file to dns_gigahost_api_token.
• 403 Forbidden: the API key does not have write access to DNS for this zone.