jazzymc/infrastructure
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: AdGuard Home migration - MikroTik persistence fix, Unraid replaces Pi-hole
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
Details

Browse Source 
- Fixed MikroTik AdGuard container persistence (disk1 root + usb1 mount)
- Deployed AdGuard Home on Unraid at 192.168.31.4 (replacing Pi-hole)
- Synced configuration: 6 clients, Quad9 DoH, TLS certs, filtering rules
- Added Mermaid diagrams for network topology and DNS architecture
This commit is contained in:
XTRM-Unraid
2026-01-22 15:38:14 +02:00
parent 4cd8caa27e
commit 9226e1494b
2 changed files with 229 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

359
docs/00-CURRENT-STATE.md
View File

@@ -1,15 +1,84 @@
# Infrastructure Upgrade Proposal: xtrm-lab.org (v2)
# Infrastructure Current State: xtrm-lab.org
## Current Infrastructure State
**Document Updated:** 2026-01-22
**Target Domain:** xtrm-lab.org
## Document Updated: 2026-01-22
## Target Domain: xtrm-lab.org
---
## Network Topology
## Network Topology Diagram
### MikroTik hAP ax³ Router (192.168.31.1)
```mermaid
graph TB
subgraph Internet
WAN["WAN: 62.73.120.142"]
DNS_EXT["dns.xtrm-lab.org<br/>DoH/DoT/DoQ"]
end
subgraph MikroTik["MikroTik hAP ax³ (192.168.31.1)"]
ROUTER["RouterOS 7.20.6"]
subgraph MK_Containers["Docker Containers"]
AGH_MK["AdGuard Home<br/>172.17.0.5:5355<br/>PRIMARY DNS"]
TS["Tailscale<br/>172.17.0.4"]
end
end
subgraph Switch["CSS326-24G-2S+ (192.168.31.9)"]
SW["24-Port Managed Switch"]
end
subgraph AP["cAP ac (192.168.31.6)"]
WIFI["CAPsMAN AP"]
end
subgraph Unraid["Unraid Server (192.168.31.2)"]
subgraph Core["Core Services"]
TRAEFIK["Traefik<br/>172.18.0.3"]
HOMARR["Homarr<br/>172.18.0.4"]
end
subgraph Security["Security"]
AUTH["Authentik<br/>172.18.0.11"]
VAULT["Vaultwarden<br/>172.18.0.15"]
end
subgraph DNS_Unraid["DNS Services"]
AGH_UR["AdGuard Home<br/>192.168.31.4:53<br/>SECONDARY DNS"]
UNBOUND["Unbound<br/>192.168.31.5"]
end
subgraph DevOps["DevOps"]
GITEA["Gitea<br/>172.18.0.31"]
WOODPECKER["Woodpecker CI<br/>172.18.0.32"]
end
subgraph Monitoring["Monitoring"]
UPTIME["Uptime Kuma<br/>172.18.0.20"]
NETBOX["NetBox<br/>172.24.0.5"]
end
subgraph Media["Media"]
PLEX["Plex"]
NEXTCLOUD["Nextcloud<br/>172.18.0.24"]
end
end
subgraph LAN["LAN Devices (192.168.31.x)"]
CLIENTS["Clients"]
end
WAN --> ROUTER
DNS_EXT --> ROUTER
ROUTER --> AGH_MK
ROUTER --> TS
ROUTER --> SW
SW --> Unraid
SW --> AP
AP --> CLIENTS
SW --> CLIENTS
AGH_MK -.->|"Upstream DoH"| QUAD9["Quad9 DNS"]
AGH_UR -.->|"Upstream DoH"| QUAD9
CLIENTS -->|"DNS Queries"| AGH_MK
CLIENTS -.->|"Failover"| AGH_UR
```
---
## MikroTik hAP ax³ Router (192.168.31.1)
| Parameter | Value |
|-----------|-------|
@@ -17,11 +86,7 @@
| WAN IP (Static) | 62.73.120.142 |
| LAN Subnet | 192.168.31.0/24 |
| Docker Bridge | 172.17.0.0/24 |
| SSH Access | `ssh -i /root/.ssh/mikrotik_key -p 2222 unraid@192.168.31.1` |
**SSH Users:**
- `xtrm` - Primary admin user (key auth issues)
- `unraid` - Secondary admin user (key-based from Unraid) ✓ Working
| SSH Access | Port 2222, user: jazzymc |
**Interfaces:**
- `ether1` - WAN (62.73.120.142/23)
@@ -29,54 +94,46 @@
- `docker-bridge` - Container network (172.17.0.1/24)
- `back-to-home-vpn` - WireGuard VPN (192.168.216.1/24)
**Running Containers on MikroTik:**
### Running Containers on MikroTik
| Container | IP | Storage | Purpose |
|-----------|-----|---------|---------|
| tailscale:latest | 172.17.0.4 | usb1/tailscale/root | Tailscale VPN client |
| adguardhome:latest | 172.17.0.5 | usb1/agh2 | DNS sinkhole with DoH/DoT/DoQ |
| tailscale | 172.17.0.4 | usb1/tailscale/root | Tailscale VPN client |
| adguardhome | 172.17.0.5 | disk1/agh-root + usb1 mount | DNS with DoH/DoT/DoQ |
**Stopped Containers:**
| Container | Issue |
|-----------|-------|
| unbound:latest | exited with status 1 |
### AdGuard Home (MikroTik) - PRIMARY DNS
**AdGuard Home Configuration (172.17.0.5):**
| Service | Port | Protocol | Status |
|---------|------|----------|--------|
| DNS | 5355 | UDP/TCP | Active (NAT from 53) |
| DNS | 5355 (NAT from 53) | UDP/TCP | Active |
| Web UI | 80 | HTTP | Active |
| DoH (DNS-over-HTTPS) | 443 | HTTPS | Active (TLS) |
| DoT (DNS-over-TLS) | 853 | TCP | Active (TLS) |
| DoQ (DNS-over-QUIC) | 8853 | UDP | Active (TLS) |
| DoH | 443 | HTTPS | Active |
| DoT | 853 | TCP | Active |
| DoQ | 8853 | UDP | Active |
**AdGuard Home Blocklists:**
- StevenBlack Hosts
- Hagezi Pro
- Hagezi NSFW
**Configuration:**
- Upstream: Quad9 DoH (https://dns10.quad9.net/dns-query)
- TLS Certificate: Let's Encrypt wildcard (\*.xtrm-lab.org)
- Server Name: dns.xtrm-lab.org
- Certificate Expiry: 2026-04-02
- Credentials: jazzymc / 7RqWElENNbZnPW
**AdGuard Home Custom Rules:**
- ||dv-eu-prod.sentinelone.net^
- ||euce1-soc360.sentinelone.net^
- ||ampeco.jamfcloud.com^
- ||*.jamfcloud.com^
**Persistence:** root-dir on disk1 + data mount on usb1 (survives container restart)
**TLS Certificate:** Let's Encrypt wildcard cert for `*.xtrm-lab.org`
**Server Name:** `dns.xtrm-lab.org`
**Certificate Expiry:** 2026-04-02
---
**⚠️ IMPORTANT:** Do NOT stop/restart the AdGuard Home container - MikroTik has a bug where the root directory disappears when container stops.
### MikroTik CSS326-24G-2S+ Switch (192.168.31.9)
## MikroTik CSS326-24G-2S+ Switch (192.168.31.9)
| Parameter | Value |
|-----------|-------|
| Role | Managed Layer 2 Switch |
| Model | CSS326-24G-2S+ |
| Ports | 24x Gigabit + 2x SFP |
| OS | SwOS (MikroTik Switch OS) |
| Web UI | http://192.168.31.9/index.html |
| OS | SwOS |
| Web UI | http://192.168.31.9 |
### MikroTik cAP ac (192.168.31.6)
---
## MikroTik cAP ac (192.168.31.6)
| Parameter | Value |
|-----------|-------|
@@ -95,152 +152,144 @@
| Network | Subnet | Purpose |
|---------|--------|---------|
| br0 | 192.168.31.0/24 | LAN macvlan (AdGuard Home) |
| dockerproxy | 172.18.0.0/16 | Traefik-accessible services |
| netbox | 172.24.0.0/16 | NetBox stack |
| slurpit_slurpit-network | Auto | Slurp'it stack |
| br0 | 192.168.31.0/24 | LAN macvlan |
| bridge | 172.17.0.0/16 | Default Docker bridge |
| host | - | Host network stack |
### Key Services
| Service | Container | Static IP | External URL |
|---------|-----------|-----------|--------------|
| **Core Infrastructure** |
| Service | Container | IP | External URL |
|---------|-----------|---|--------------|
| **Core** ||||
| Reverse Proxy | traefik | 172.18.0.3 | traefik.xtrm-lab.org |
| Docker Socket | dockersocket | 172.18.0.2 | - |
| Dashboard | homarr | 172.18.0.4 | xtrm-lab.org |
| **Security** |
| **Security** ||||
| Identity Provider | authentik | 172.18.0.11 | auth.xtrm-lab.org |
| Authentik Worker | authentik-worker | 172.18.0.12 | - |
| Password Manager | vaultwarden | 172.18.0.15 | vault.xtrm-lab.org |
| **Databases** |
| PostgreSQL | postgresql17 | 172.18.0.13 | - |
| Redis | Redis | 172.18.0.14 | - |
| **DNS (Unraid - Secondary)** |
| Pi-hole (Unraid) | binhex-official-pihole | 192.168.31.4 | ph1.xtrm-lab.org |
| Unbound (Unraid) | unbound | 192.168.31.5 | - |
| DoH Server | DoH-Server | 172.18.0.22 | doh.xtrm-lab.org |
| nebula-sync | nebula-sync | - | ⚠️ Crash-looping (incompatible with AdGuard) |
| **DevOps** |
| **DNS** ||||
| AdGuard Home | adguardhome | 192.168.31.4 | - |
| Unbound | unbound | 192.168.31.5 | - |
| **DevOps** ||||
| Git Server | gitea | 172.18.0.31 | git.xtrm-lab.org |
| CI/CD Server | woodpecker-server | 172.18.0.32 | ci.xtrm-lab.org |
| CI/CD Agent | woodpecker-agent | 172.18.0.33 | - |
| **Network Management** |
| NetBox | netbox | 172.24.0.5 | netbox.xtrm-lab.org |
| NetDisco Web | netdisco-web | 172.18.0.41 | netdisco.xtrm-lab.org |
| Unimus | unimus | host | unimus.xtrm-lab.org |
| **Monitoring** |
| **Monitoring** ||||
| Uptime Kuma | UptimeKuma | 172.18.0.20 | uptime.xtrm-lab.org |
| NetAlertX | NetAlertX | host | netalert.xtrm-lab.org |
| Speedtest Tracker | speedtest-tracker | 172.18.0.21 | speedtest.xtrm-lab.org |
| **Media & Storage** |
| NetBox | netbox | 172.24.0.5 | netbox.xtrm-lab.org |
| **Media** ||||
| Plex | plex | host | plex.xtrm-lab.org |
| Nextcloud | Nextcloud | 172.18.0.24 | nextcloud.xtrm-lab.org |
| **Remote Access** |
| RustDesk ID | rustdesk-hbbs | bridge | rustdesk.xtrm-lab.org |
| RustDesk Relay | rustdesk-hbbr | bridge | - |
| **Remote Access** ||||
| RustDesk | rustdesk-hbbs/hbbr | bridge | rustdesk.xtrm-lab.org |
### AdGuard Home (Unraid) - SECONDARY DNS
| Setting | Value |
|---------|-------|
| IP Address | 192.168.31.4 |
| Network | br0 (macvlan) |
| Web UI | http://192.168.31.4:3000 |
| DNS | 192.168.31.4:53 |
| DoT | 192.168.31.4:853 |
| Credentials | jazzymc / 7RqWElENNbZnPW |
**Configuration (synced with MikroTik):**
- Upstream: Quad9 DoH
- TLS Certificate: Let's Encrypt wildcard
- 6 Clients configured
- Custom filtering rules (SentinelOne, Jamf)
**Data Location:** /mnt/user/appdata/adguardhome/
**Stopped Services:**
- binhex-official-pihole (replaced by AdGuard Home)
- nebula-sync (incompatible with AdGuard Home)
---
## DNS Architecture
```
┌─────────────────────────────────────┐
│ Internet │
│ (DoH/DoT/DoQ: dns.xtrm-lab.org) │
└───────────────┬─────────────────────┘
│
┌───────────────▼─────────────────────┐
│ MikroTik hAP ax³ (192.168.31.1) │
│ Ports: 443(DoH), 853(DoT), │
│ 8853(DoQ), 53→5355(DNS) │
└───────────────┬─────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ AdGuard Home │ │ Unraid Server │ │ LAN Devices │
│ 172.17.0.5:5355 │ │ 192.168.31.2 │ │ 192.168.31.x │
│ PRIMARY DNS │ │ │ │ │
│ DoH/DoT/DoQ Server │ └────────┬─────────┘ └──────────────────┘
└──────────────────────┘ │
▼
┌──────────────────┐
│ Pi-hole (Unraid) │
│ 192.168.31.4 │
│ SECONDARY DNS │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Unbound (Unraid) │
│ 192.168.31.5 │
│ Recursive DNS │
└──────────────────┘
```mermaid
flowchart TB
subgraph External["External Access"]
DOH["DoH: https://dns.xtrm-lab.org/dns-query"]
DOT["DoT: tls://dns.xtrm-lab.org:853"]
DOQ["DoQ: quic://dns.xtrm-lab.org:8853"]
end
subgraph MikroTik["MikroTik Router"]
NAT["NAT: 53 → 5355"]
AGH1["AdGuard Home<br/>172.17.0.5:5355<br/>PRIMARY"]
end
subgraph Unraid["Unraid Server"]
AGH2["AdGuard Home<br/>192.168.31.4:53<br/>SECONDARY"]
end
subgraph Upstream["Upstream DNS"]
Q9["Quad9 DoH<br/>dns10.quad9.net"]
end
subgraph Clients["LAN Clients"]
C1["IPhone Dancho"]
C2["IPhone Kimi"]
C3["Laptop Dari"]
C4["Laptop Kimi"]
C5["PC Dancho"]
C6["ROG Ally Teodor"]
end
External --> MikroTik
Clients -->|"Primary"| NAT
NAT --> AGH1
Clients -.->|"Failover"| AGH2
AGH1 --> Q9
AGH2 --> Q9
```
**Encrypted DNS Endpoints (MikroTik AdGuard Home):**
- **DoH:** `https://dns.xtrm-lab.org/dns-query`
- **DoT:** `tls://dns.xtrm-lab.org:853`
- **DoQ:** `quic://dns.xtrm-lab.org:8853`
---
**Note:** Pi-hole on Unraid serves as secondary/backup. nebula-sync is disabled (incompatible with AdGuard Home).
## Configured Clients (Both AdGuard Instances)
| Client | MAC Address | Tags |
|--------|-------------|------|
| IPhone (Dancho) | f2:b8:14:61:c8:27 | - |
| IPhone (Kimi) | 2a:2b:ba:86:d4:af | user_child |
| Laptop (Dari) | 34:f6:4b:b3:14:83 | user_child |
| Laptop (Kimi) | 90:91:64:70:0d:86 | user_child |
| PC (Dancho) | 70:85:c2:75:64:e5 | - |
| ROG Ally (Teodor) | cc:5e:f8:d3:37:d3 | user_child |
---
## Current NAT/Port Forwarding (MikroTik)
## Custom Filtering Rules
| Rule | Protocol | Src/Dst Port | Destination | Purpose |
|------|----------|--------------|-------------|---------|
| Forward HTTP | TCP | 80 | 192.168.31.2:8001 | Traefik HTTP |
| Forward HTTPS | TCP | 443 | 192.168.31.2:44301 | Traefik HTTPS |
| Force DNS to AdGuard | UDP | 53→5355 | 172.17.0.5 | LAN DNS redirect |
| Force DNS TCP | TCP | 53→5355 | 172.17.0.5 | LAN DNS redirect |
| AdGuard Web UI | TCP | 80 | 172.17.0.5:80 | Internal web access |
| DoT | TCP | 853 | 172.17.0.5:853 | DNS over TLS |
| DoH (internal) | TCP | 443 | 172.17.0.5:443 | DNS over HTTPS |
| Plex | TCP | 32400 | 192.168.31.2:32400 | Plex Media Server |
| RustDesk | TCP/UDP | 21115-21119 | 192.168.31.2 | RustDesk Server |
```
||dv-eu-prod.sentinelone.net^
||euce1-soc360.sentinelone.net^
||ampeco.jamfcloud.com^
||*.jamfcloud.com^
```
---
## Traefik Configuration
## NAT/Port Forwarding (MikroTik)
**Entry Points:**
- HTTP (:80) → Redirects to HTTPS
- HTTPS (:443)
**Certificate Resolver:** Cloudflare DNS Challenge
**TLS Certificates Location:** `/mnt/user/appdata/traefik/certs/`
- `xtrm-lab.org.crt` - Wildcard certificate chain
- `xtrm-lab.org.key` - Private key
---
## Migration Data
**AdGuard Migration Config:** `/mnt/user/appdata/adguard-migration.json`
Contains blocklists, custom rules, and client configurations for applying to new AdGuard Home instances.
---
## Backup & Cloud Sync
### Flash Backup Script
- **Script Path:** /boot/config/plugins/user.scripts/scripts/flash-backup/script
- **Schedule:** 0 3 * * * (Daily at 3:00 AM)
- **Retention:** 7 days
- **Cloud Sync:** drive:Backups/unraid-flash
| Rule | Protocol | Port | Destination | Purpose |
|------|----------|------|-------------|---------|
| HTTP | TCP | 80 | 192.168.31.2:8001 | Traefik |
| HTTPS | TCP | 443 | 192.168.31.2:44301 | Traefik |
| DNS UDP | UDP | 53→5355 | 172.17.0.5 | AdGuard Home |
| DNS TCP | TCP | 53→5355 | 172.17.0.5 | AdGuard Home |
| DoT | TCP | 853 | 172.17.0.5 | DNS over TLS |
| DoQ | UDP | 8853 | 172.17.0.5 | DNS over QUIC |
| Plex | TCP | 32400 | 192.168.31.2 | Plex Media |
| RustDesk | TCP/UDP | 21115-21119 | 192.168.31.2 | RustDesk |
---
## Reference Documents
- [Phase 1: Global DNS Portability](./01-PHASE1-DNS-PORTABILITY.md)
- [Phase 1: DNS Portability](./01-PHASE1-DNS-PORTABILITY.md)
- [Phase 7: Gitea GitOps](./08-PHASE7-GITEA-GITOPS.md)
- [Container IP Assignments](./13-CONTAINER-IP-ASSIGNMENTS.md)
- [Changelog](./06-CHANGELOG.md)

25
docs/06-CHANGELOG.md
View File

@@ -3,6 +3,31 @@
### Pi-hole Removal from MikroTik
- [CONTAINER] Removed Pi-hole container from MikroTik
- [STORAGE] Freed internal flash storage
## 2026-01-22 - AdGuard Home Migration Complete
### MikroTik AdGuard Home - Persistence Fix
- [CONTAINER] Fixed container persistence issue (root-dir on disk1, data on usb1)
- [CONFIG] Container now survives stop/start cycles
- [MOUNT] agh-work mount: usb1/adguard-home/work → /opt/adguardhome/work
### Unraid AdGuard Home - Replaces Pi-hole
- [CONTAINER] Deployed AdGuard Home on br0 macvlan network
- [IP] 192.168.31.4 (same IP as Pi-hole was using)
- [STOPPED] binhex-official-pihole container stopped (not removed)
- [CONFIG] Same credentials and rules as MikroTik instance
### Configuration Sync (Both Instances)
- [DNS] Upstream: Quad9 DoH (dns10.quad9.net)
- [TLS] Let's Encrypt wildcard cert for *.xtrm-lab.org
- [CLIENTS] 6 clients configured with MAC addresses
- [RULES] Custom filtering rules for SentinelOne, Jamf
### Documentation
- [DOCS] Updated 00-CURRENT-STATE.md with Mermaid diagrams
- [DIAGRAM] Added network topology and DNS architecture diagrams
---
- [CLEANUP] Removed Pi-hole mounts, envs, and data
### AdGuard Home Installation (Multiple Attempts)