certbot-dns-technitium 0.1.2
Certbot plugin for obtaining SSL/TLS certificates using Technitium DNS Server DNS-01 challenges
License: Apache-2.0
Requires Python: >=3.7
Keywords: certbot, dns, technitium, letsencrypt, acme, certificate

# certbot-dns-technitium

Certbot DNS Authenticator plugin for Technitium DNS Server.

This plugin allows you to use [Certbot](https://certbot.eff.org/) with the [Technitium DNS Server](https://technitium.com/dns/) to automatically obtain SSL/TLS certificates from Let's Encrypt using DNS-01 challenges.

## Installation

### Standard Installation

```bash
pip install certbot-dns-technitium
```

### Debian/Ubuntu (PEP 668)

On newer Debian/Ubuntu systems, Python environments are protected to prevent conflicts with system packages. Choose the installation method based on how Certbot is installed:

**Option 1: Virtual Environment (Recommended for all cases)**

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

```bash
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:

```bash
/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:

```bash
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.

**Which to choose?**

- **New setup or unsure?** → Use Option 1 (Virtual Environment)
- **Certbot already installed via apt?** → Use Option 2 (System-wide)

## 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:

```bash
chmod 600 /etc/letsencrypt/technitium.ini
```

## Usage

### Obtaining a Certificate

To obtain a certificate for a domain:

```bash
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:

```bash
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:

```bash
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

## Repository

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

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request on [GitHub](https://github.com/pprugger/certbot-dns-technitium).

## License

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

## Acknowledgments

- [Certbot](https://certbot.eff.org/) - The ACME client
- [Technitium DNS Server](https://technitium.com/dns/) - The DNS server

## Support

For issues and questions:

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