certbot-dns-xynta 0.1.0

Xynta DNS Authenticator plugin for Certbot

xynta-certbot-plugin

Xynta DNS Authenticator plugin for Certbot.

This plugin automates the process of completing a dns-01 challenge by creating, and subsequently removing, TXT records in your Xynta DNS zone using the Xynta HostFact API.

It enables you to obtain wildcard certificates (e.g. *.example.com) via Let's Encrypt without any manual DNS interaction.

---

Requirements

Requirement	Version
Python	≥ 3.10
certbot	≥ 2.0.0
requests	≥ 2.32.0

---

Installation

pip install certbot-dns-xynta

If certbot is installed system-wide and you want to add the plugin to that environment, either use sudo pip install certbot-dns-xynta or install both certbot and the plugin together in a virtual environment:

python3 -m venv certbot-env
source certbot-env/bin/activate
pip install certbot certbot-dns-xynta

---

Xynta API credentials

You need the UserID and IP Hash from your Xynta HostFact account. These are found in the Xynta control panel under your API settings.

---

Usage

1. Create a credentials file

Create a file (e.g. /etc/letsencrypt/xynta.ini) with the following content:

dns_xynta_api_url     = https://api.xynta.com/
dns_xynta_api_user_id = YOUR_USER_ID
dns_xynta_api_ip_hash = YOUR_IP_HASH

2. Secure the credentials file

chmod 600 /etc/letsencrypt/xynta.ini

3. Run certbot

Single domain:

certbot certonly \
  --authenticator dns-xynta \
  --dns-xynta-credentials /etc/letsencrypt/xynta.ini \
  -d example.com

Wildcard certificate:

certbot certonly \
  --authenticator dns-xynta \
  --dns-xynta-credentials /etc/letsencrypt/xynta.ini \
  -d example.com \
  -d "*.example.com"

Custom DNS propagation wait (in seconds):

certbot certonly \
  --authenticator dns-xynta \
  --dns-xynta-credentials /etc/letsencrypt/xynta.ini \
  --dns-xynta-propagation-seconds 300 \
  -d example.com \
  -d "*.example.com"

---

Arguments

Argument	Description
--dns-xynta-credentials	Path to the credentials INI file (required)
--dns-xynta-propagation-seconds	Seconds to wait for DNS propagation (default: 120)

---

Docker

Pre-built images are published to the GitHub Container Registry on every push:

ghcr.io/mbchristoff/xynta-certbot-plugin:latest   # latest build from main
ghcr.io/mbchristoff/xynta-certbot-plugin:main     # current main branch build
ghcr.io/mbchristoff/xynta-certbot-plugin:<branch> # sanitized branch-name build

Pull the latest image:

docker pull ghcr.io/mbchristoff/xynta-certbot-plugin:latest

Environment variables

Configure the container entirely through environment variables — no credentials file needs to be created on the host.

Variable	Required	Default	Description
XYNTA_API_USER_ID	✅	—	Xynta HostFact API User ID
XYNTA_API_IP_HASH	✅	—	Xynta HostFact API IP Hash
CERTBOT_EMAIL	✅	—	Email address for Let's Encrypt account / recovery
CERTBOT_DOMAINS	✅	—	Comma-separated list of domains (e.g. example.com,*.example.com)
XYNTA_API_URL	❌	https://api.xynta.com/	Xynta API base URL
CERTBOT_PROPAGATION_SECONDS	❌	120	Seconds to wait for DNS propagation
CERTBOT_STAGING	❌	false	Set to true to use the Let's Encrypt staging environment (avoids rate limits during testing)

Using a .env file (recommended)

Copy .env.example to .env, fill in your values, and pass it to docker run:

cp .env.example .env
# edit .env with your credentials and domains
docker run --rm \
  --env-file .env \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  ghcr.io/mbchristoff/xynta-certbot-plugin:latest

Volumes

Host path	Container path	Purpose
/etc/letsencrypt	/etc/letsencrypt	Issued certificates and certbot config
/var/lib/letsencrypt	/var/lib/letsencrypt	Certbot working directory (locks, accounts)

Run the container

Single domain:

docker run --rm \
  -e XYNTA_API_USER_ID=your-user-id \
  -e XYNTA_API_IP_HASH=your-ip-hash \
  -e CERTBOT_EMAIL=[e-mail] \
  -e CERTBOT_DOMAINS=example.com \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  ghcr.io/mbchristoff/xynta-certbot-plugin:latest

Wildcard certificate:

docker run --rm \
  -e XYNTA_API_USER_ID=your-user-id \
  -e XYNTA_API_IP_HASH=your-ip-hash \
  -e CERTBOT_EMAIL=[e-mail] \
  -e "CERTBOT_DOMAINS=example.com,*.example.com" \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  ghcr.io/mbchristoff/xynta-certbot-plugin:latest

With custom propagation time:

docker run --rm \
  -e XYNTA_API_USER_ID=your-user-id \
  -e XYNTA_API_IP_HASH=your-ip-hash \
  -e CERTBOT_EMAIL=[e-mail] \
  -e "CERTBOT_DOMAINS=example.com,*.example.com" \
  -e CERTBOT_PROPAGATION_SECONDS=300 \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  ghcr.io/mbchristoff/xynta-certbot-plugin:latest

After a successful run the certificates are stored on the host at /etc/letsencrypt/live/<domain>/.

Renewing certificates

Pass renew as the command to run certbot renew instead of certbot certonly. Only the API credentials (XYNTA_API_USER_ID, XYNTA_API_IP_HASH) are required — CERTBOT_EMAIL and CERTBOT_DOMAINS are not needed because certbot reads those from the stored renewal configuration.

docker run --rm \
  --env-file .env \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  ghcr.io/mbchristoff/xynta-certbot-plugin:latest renew

Cron example

Add this line to your crontab (crontab -e) to attempt renewal every day at 03:00:

0 3 * * * docker run --rm --env-file /path/to/.env -v /etc/letsencrypt:/etc/letsencrypt -v /var/lib/letsencrypt:/var/lib/letsencrypt ghcr.io/mbchristoff/xynta-certbot-plugin:latest renew >> /var/log/certbot-renew.log 2>&1

Certbot only renews certificates that expire within 30 days, so running daily is safe.

Build the image locally

docker build -t xynta-certbot-plugin .

---

Development

Install dev dependencies:

pip install -e ".[dev]"

Run tests:

pytest certbot_dns_xynta/

Run linter:

ruff check certbot_dns_xynta/

---

Troubleshooting

Plugin not found by certbot

If certbot plugins doesn't list dns-xynta, make sure both certbot and the plugin are installed in the same Python environment:

# Check the active certbot
which certbot

# If using system certbot but plugin installed in a venv, install both together:
pip install certbot certbot-dns-xynta

API errors

• Verify the api_url is correct (default: https://api.xynta.com/).
• Check that your api_user_id and api_ip_hash match the values in the Xynta control panel.
• Ensure the domain you are trying to certify is managed by your Xynta account.

---

License

Apache License 2.0