certbot-dns-technitium

Certbot DNS Authenticator plugin for Technitium DNS Server.

This plugin allows you to use Certbot with the Technitium DNS Server to automatically obtain SSL/TLS certificates from Let's Encrypt using DNS-01 challenges.

Installation

Standard Installation

pip install certbot-dns-technitium

Debian/Ubuntu (PEP 668)

On newer Debian/Ubuntu systems with externally-managed Python environments, use one of these methods:

Option 1: Virtual Environment (Recommended for all cases)

Use this if you want a clean, isolated installation or if you're installing Certbot yourself:

python3 -m venv /opt/certbot-dns-technitium
source /opt/certbot-dns-technitium/bin/activate
pip install --upgrade pip
pip install certbot certbot-dns-technitium

Then use Certbot from the virtual environment:

/opt/certbot-dns-technitium/bin/certbot certonly \
  --authenticator dns-technitium \
  --dns-technitium-credentials /etc/letsencrypt/technitium.ini \
  -d example.com

Why use this: Keeps all dependencies isolated, avoids system package conflicts, and works reliably across different system configurations.

Option 2: System-wide Installation

Use this only if Certbot is already installed system-wide (via apt install certbot) and you want to add the plugin to the same environment:

pip install certbot-dns-technitium --break-system-packages

Why use this: Quick installation when Certbot is already system-installed. Note: This bypasses system package protection, so use with caution.

Option 3: Install from source

If you prefer to install from source:

git clone https://github.com/pprugger/certbot-dns-technitium.git
cd certbot-dns-technitium
pip install . --break-system-packages

Which to choose?

• New setup or unsure? → Use Option 1 (Virtual Environment)
• Certbot already installed via apt? → Use Option 2 (System-wide)
• Want to modify the code? → Use Option 3 (From source) cd certbot-dns-technitium pip install .

## Prerequisites

- Certbot installed on your system
- Technitium DNS Server running and accessible
- API token configured in Technitium DNS Server

## Configuration

Create a credentials file (e.g., `/etc/letsencrypt/technitium.ini`) with your Technitium DNS Server API credentials:

```ini
dns_technitium_api_url = http://localhost:5380
dns_technitium_api_token = your-api-token-here

Note: The credentials file uses underscores (dns_technitium_api_url) while command-line arguments use hyphens (--dns-technitium-api-url).

Note: You must create the API token in Technitium DNS Server before using this plugin. See the "Getting an API Token" section below.

Security Note: Make sure to set appropriate file permissions on the credentials file:

chmod 600 /etc/letsencrypt/technitium.ini

Usage

Obtaining a Certificate

To obtain a certificate for a domain:

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

Wildcard Certificates

This plugin supports wildcard certificates:

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

Automatic Renewal

Certbot will automatically renew certificates before they expire. The plugin will automatically handle DNS record creation and cleanup during renewal.

To test renewal:

certbot renew --dry-run

How It Works

1. Certbot initiates a DNS-01 challenge for your domain
2. The plugin authenticates with Technitium DNS Server API
3. The plugin finds the appropriate DNS zone for your domain
4. A TXT record is created at _acme-challenge.yourdomain.com with the challenge value
5. Let's Encrypt verifies the TXT record
6. The plugin automatically removes the TXT record after validation

API Configuration

Getting an API Token

1. Log in to your Technitium DNS Server web interface
2. Navigate to Administration → Sessions → Create Token
3. Generate an API token
4. Use this token in your credentials file

API URL

• Default: http://localhost:5380 (for local HTTP connections)
• For remote servers: http://your-server-ip:5380 or https://your-server:53443
• For HTTPS: https://your-server:53443 (recommended for remote servers)

Troubleshooting

Zone Not Found

If you get an error about the zone not being found:

1. Ensure the zone exists in Technitium DNS Server
2. Verify the zone name matches your domain (e.g., for example.com, the zone should be example.com)
3. Check that your API credentials have permission to manage the zone

Authentication Errors

• Verify your API token is correct
• Check that the API URL is accessible from your system
• Ensure the API is enabled in Technitium DNS Server settings
• Make sure the API token was created in Technitium DNS Server before use

DNS Propagation

The plugin waits 10 seconds by default after creating the TXT record to allow for DNS propagation. You can adjust this using the --dns-technitium-propagation-seconds option. If Let's Encrypt cannot verify the record:

• Check that the TXT record appears in Technitium DNS Server
• Verify DNS propagation (may take a few minutes)
• Ensure your Technitium DNS Server is authoritative for the domain
• Consider increasing the propagation seconds if your DNS has slower propagation times

Development

Setting Up Development Environment

git clone https://github.com/pprugger/certbot-dns-technitium.git
cd certbot-dns-technitium
pip install -e ".[dev]"

Testing

Unit Tests

Run the test suite using pytest:

pytest tests/

The test suite includes:

• Credential validation
• Zone finding and matching
• TXT record creation and deletion
• Error handling
• Network error scenarios

Manual API Testing

You can also test the plugin using the provided test_api.py script to verify API connectivity:

python3 test_api.py test_credentials.ini

This script will test:

• API connection
• Zone listing
• TXT record creation and deletion

Integration Testing

For full integration testing, use Certbot's dry-run mode:

certbot certonly \
  --authenticator dns-technitium \
  --dns-technitium-credentials /path/to/credentials.ini \
  -d example.com \
  --dry-run

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Certbot - The ACME client
• Technitium DNS Server - The DNS server

Repository

• GitHub Repository: https://github.com/pprugger/certbot-dns-technitium
• PyPI Package: https://pypi.org/project/certbot-dns-technitium/

Support

For issues and questions:

• GitHub Issues: https://github.com/pprugger/certbot-dns-technitium/issues
• Technitium DNS Server Documentation: https://github.com/TechnitiumSoftware/DnsServer