Ken Schiano
a36ffe0b68
- config.yaml: add ports for DoT, DoH (tcp+udp), HTTPS console with descriptions - add TLS cert options schema (enable_https, pfx path/password) mapped to HA ssl dir - Dockerfile: set HTTPS env defaults, fix symlink to -sf - README: document DoT/DoH setup using HA ACME certs via openssl pfx export - bump version to 1.1.0
73 lines
3.0 KiB
Markdown
73 lines
3.0 KiB
Markdown
# Technitium DNS - Home Assistant Add-on
|
|
|
|
Runs the [Technitium DNS Server](https://technitium.com/dns/) inside Home Assistant as a supervised add-on.
|
|
|
|
## Features
|
|
- Ad-blocking DNS server with web console on port 5380
|
|
- Local DNS records, conditional forwarding, DNS-over-TLS/HTTPS
|
|
- DNS-over-TLS (853/tcp), DNS-over-HTTPS (443/tcp + 443/udp), HTTPS web console (53443/tcp)
|
|
- Persists config to the add-on config volume
|
|
- Designed to act as **secondary** to a primary Technitium instance via DNS Replication
|
|
|
|
## Installation
|
|
|
|
1. Add this repository in Home Assistant:
|
|
**Settings → Add-ons → Add-on Store → ⋮ → Repositories**
|
|
```
|
|
https://git.kenschiano.net/kschiano/Hassio_Addons.git
|
|
```
|
|
2. Refresh the add-on store, then install **Technitium DNS**.
|
|
3. Set `admin_password` and `timezone` in the add-on config.
|
|
4. (Optional) For DoT/DoH/HTTPS console, set `enable_https: true` and provide a TLS `.pfx` cert path + password (see below).
|
|
5. Start the add-on and open the web UI at `http://homeassistant.local:5380`.
|
|
|
|
## TLS / DNS-over-TLS / DNS-over-HTTPS
|
|
|
|
Technitium can serve DoT (853/tcp), DoH (443/tcp + 443/udp, HTTP/1.1, HTTP/2, HTTP/3), and an HTTPS web console (53443/tcp). All three share one TLS certificate.
|
|
|
|
### Using the HA `ssl` map (recommended)
|
|
The add-on maps the HA `ssl` directory, so certs issued by the HA ACME add-on are available.
|
|
|
|
1. Convert your cert to `.pfx` (Technitium requires PFX):
|
|
```bash
|
|
openssl pkcs12 -export -out /ssl/technitium.pfx \
|
|
-inkey /ssl/privkey.pem -in /ssl/fullchain.pem \
|
|
-password pass:YOUR_PASSWORD
|
|
```
|
|
2. In the add-on config:
|
|
```yaml
|
|
enable_https: true
|
|
tls_cert_pfx_path: /ssl/technitium.pfx
|
|
tls_cert_pfx_password: YOUR_PASSWORD
|
|
```
|
|
3. Restart the add-on. Technitium will use the cert for DoT, DoH, and the HTTPS web console.
|
|
|
|
### Verifying
|
|
```bash
|
|
# DoT
|
|
kdig @homeassistant.local +tls example.com
|
|
# DoH
|
|
kdig @homeassistant.local +https example.com
|
|
# HTTPS console
|
|
https://homeassistant.local:53443/
|
|
```
|
|
|
|
> **Note:** Technitium reads the cert path from its internal config. The first time you enable HTTPS, do it in the web console under **Settings → Options → Web Service** so the path is saved, then it will persist across restarts via replication.
|
|
|
|
## Failover / Replication setup
|
|
|
|
This add-on is intended to run as a **secondary** to a primary Technitium instance deployed to Kubernetes. See the repository root README for the full primary/secondary replication plan.
|
|
|
|
Quick steps:
|
|
1. On the **Primary** (k8s): Settings → Replication → generate API key, add this host as secondary (`https://homeassistant.local:5380`).
|
|
2. On this add-on: Settings → Replication → set the same API key, enable secondary mode.
|
|
|
|
## Updating the add-on
|
|
|
|
The add-on pulls `technitium/dns-server:latest` upstream. To update:
|
|
1. Rebuild the add-on image: **Settings → Add-ons → Technitium DNS → Rebuild**
|
|
2. Or restart the add-on after bumping `version` in `config.yaml`.
|
|
|
|
## Repository
|
|
|
|
Source: https://git.kenschiano.net/kschiano/Hassio_Addons |