Metadata-Version: 2.4
Name: certbot-dns-technitium
Version: 0.1.0
Summary: Certbot plugin for obtaining SSL/TLS certificates using Technitium DNS Server DNS-01 challenges
Author: certbot-dns-technitium contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/pprugger/certbot-dns-technitium
Project-URL: Documentation, https://github.com/pprugger/certbot-dns-technitium#readme
Project-URL: Repository, https://github.com/pprugger/certbot-dns-technitium
Project-URL: Issues, https://github.com/pprugger/certbot-dns-technitium/issues
Keywords: certbot,dns,technitium,letsencrypt,acme,certificate
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Networking
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certbot>=1.0.0
Requires-Dist: acme>=1.0.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# 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

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

Or install from source:

```bash
git clone https://github.com/pprugger/certbot-dns-technitium.git
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:

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

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

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

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

```bash
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](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/yourusername/certbot-dns-technitium/issues
- Technitium DNS Server Documentation: https://github.com/TechnitiumSoftware/DnsServer
