jarvis
484b2e6272
- Remove AdGuard Home from all service catalogs, deployment phases, persistence tables, and network architecture docs - Update Technitium notes: authoritative .ai.home zone, recursive resolver, DoT forwarder to Cloudflare (tls://1.1.1.1), built-in ad blocking - Resolve open questions #2 (Technitium upstream) and #3 (AdGuard layout) - Add dns-topology.md: complete DNS architecture diagram, zone details, client assignments, Tailscale integration, troubleshooting table, migration history (AdGuard deployed → paused → removed)
153 lines
5.0 KiB
Markdown
153 lines
5.0 KiB
Markdown
# DNS Topology — Iron Legion Homelab
|
|
|
|
**Last updated:** 2026-05-30
|
|
**Canonical source:** `Iron-Legion/documentation/dns-topology.md`
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
All DNS resolution for the fleet is handled by **Technitium DNS Server** on MK7. AdGuard Home has been removed — Technitium's built-in ad blocking (blocklist-based) replaces it entirely.
|
|
|
|
**Single source of truth:** Technitium is both authoritative for the fleet's private zone and recursive for the public internet.
|
|
|
|
---
|
|
|
|
## DNS Architecture
|
|
|
|
```
|
|
Client Devices ──→ Router (primary, Cloudflare upstream)
|
|
│
|
|
└── Windows 11: secondary → MK7:53 (Technitium)
|
|
|
|
MK7 (Technitium DNS, port 53):
|
|
├── Authoritative zone: *.ai.home
|
|
│ └── artemis.ai.home, mk7.ai.home, mk44.ai.home, mk5.ai.home, mk33.ai.home, ...
|
|
├── Recursive resolver (root servers for public domains)
|
|
│ └── OR Cloudflare DoT forwarder: tls://1.1.1.1 (configurable)
|
|
└── Ad blocking: blocklist loaded (StevenBlack / OISD / hBlock — user-configured)
|
|
```
|
|
|
|
---
|
|
|
|
## Service Details
|
|
|
|
| Attribute | Value |
|
|
|-----------|-------|
|
|
| **Service** | Technitium DNS Server |
|
|
| **Image** | `technitium/dns-server:latest` |
|
|
| **Host** | MK7 (`192.168.7.7`, `100.66.70.51` Tailscale) |
|
|
| **Published ports** | `53/tcp`, `53/udp` (DNS), `5380/tcp` (Web UI) |
|
|
| **Traefik host** | `dns.ai.home` |
|
|
| **Compose** | `/opt/iron-legion/docker-swarm/technitium/compose.yml` |
|
|
| **Data volume** | `technitium-config` (Docker volume) |
|
|
|
|
---
|
|
|
|
## Upstream / Forwarder Config
|
|
|
|
| Setting | Value | Notes |
|
|
|---------|-------|-------|
|
|
| **Forwarder protocol** | DNS over TLS (DoT) | Encrypted queries to Cloudflare |
|
|
| **Forwarder address** | `tls://1.1.1.1` | Primary |
|
|
| **Fallback** | `tls://1.0.0.1` | Secondary (if configured) |
|
|
| **Root-server fallback** | Implicit | Technitium falls back to recursive resolution if forwarder fails |
|
|
|
|
**Web UI:** `http://dns.ai.home:5380` or `http://192.168.7.7:5380`
|
|
- Settings → DNS Server → Forwarders → Add `tls://1.1.1.1`
|
|
|
|
---
|
|
|
|
## Ad Blocking
|
|
|
|
Technitium uses a **DNS blocklist** to drop ad/tracker/malware domains at resolution time.
|
|
|
|
| Setting | Value |
|
|
|---------|-------|
|
|
| **Blocklist source** | User-configured (e.g., StevenBlack, OISD, hBlock) |
|
|
| **Update interval** | User-configured (recommend: daily) |
|
|
| **Whitelist** | `.ai.home` internal zone never blocked |
|
|
| **Previous solution** | ~~AdGuard Home~~ — removed |
|
|
|
|
**Blocklist config:** Web UI → Settings → Blocking → Blocklists
|
|
|
|
---
|
|
|
|
## Zone: `ai.home`
|
|
|
|
Technitium is **authoritative** for `.ai.home`. Records are maintained via the web UI or API.
|
|
|
|
| Record Type | Examples |
|
|
|-------------|----------|
|
|
| **A** | `artemis.ai.home → 192.168.15.182` |
|
|
| **A** | `mk7.ai.home → 192.168.7.7` |
|
|
| **A** | `mk44.ai.home → 192.168.x.x` |
|
|
| **CNAME** | `dns.ai.home → mk7.ai.home` |
|
|
|
|
**Zone file location:** `/etc/dns/config/zones/ai.home` (inside container)
|
|
|
|
---
|
|
|
|
## Client DNS Assignment
|
|
|
|
| Client | Primary DNS | Secondary DNS | Notes |
|
|
|--------|-------------|---------------|-------|
|
|
| **Router** | Cloudflare (1.1.1.1) | — | Default for all LAN devices |
|
|
| **Windows 11** | Router | MK7:53 (Technitium) | Ad blocking only on secondary |
|
|
| **Tailscale devices** | 100.100.100.100 (MagicDNS) | — | Split-brain: `.ai.home` → 192.168.7.7 |
|
|
|
|
**Fleet nodes** (MK33, MK34, MK39, MK42) resolve `.ai.home` against MK7:53 via their LAN gateway or static DNS assignment.
|
|
|
|
---
|
|
|
|
## Tailscale Integration
|
|
|
|
Tailscale's **MagicDNS** and **split-brain DNS** handle `*.ai.home` for devices connected to the tailnet.
|
|
|
|
| Setting | Value |
|
|
|---------|-------|
|
|
| **Split DNS domain** | `ai.home` |
|
|
| **Nameserver** | `192.168.7.7` (MK7 LAN IP) |
|
|
| **Override local DNS** | Yes |
|
|
|
|
This means: a laptop on Tailscale resolving `artemis.ai.home` hits Tailscale's DNS, which forwards `ai.home` queries to `192.168.7.7` (Technitium). The laptop does NOT need to point its system DNS at MK7.
|
|
|
|
**Off-Tailscale:** Devices must point DNS at MK7:53 directly to resolve `.ai.home`.
|
|
|
|
---
|
|
|
|
## Migration History
|
|
|
|
| Date | Change |
|
|
|------|--------|
|
|
| 2026-05-25 | AdGuard Home deployed on port 3000/5373 |
|
|
| 2026-05-28 | AdGuard paused (port conflict / redundancy concerns) |
|
|
| 2026-05-30 | **AdGuard removed.** Technitium blocklist configured. DoT to Cloudflare enabled. |
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Cause | Fix |
|
|
|---------|-------|-----|
|
|
| Can't resolve `.ai.home` | Device not using Technitium | Point DNS at MK7:53 or join Tailscale |
|
|
| Ads not blocked | Blocklist not loaded / outdated | Refresh blocklist in Technitium UI |
|
|
| Slow resolution | DoT forwarder failing | Check `tls://1.1.1.1` reachability; fall back to root recursion |
|
|
| Tailscale IPs unreachable | Device not on Tailscale | Connect to tailnet; 100.x IPs are VPN-only |
|
|
|
|
---
|
|
|
|
## Operational Commands
|
|
|
|
```bash
|
|
# Test resolution from any node
|
|
dig @192.168.7.7 artemis.ai.home +short
|
|
dig @192.168.7.7 google.com +short
|
|
|
|
# Check Technitium container logs
|
|
ssh jarvis@mk7.ai.home "docker logs $(docker ps -q -f name=technitium)"
|
|
|
|
# Access web UI
|
|
open http://dns.ai.home:5380
|
|
```
|