# 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