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