Add AdGuard DNS setup with automatic failover documentation
- docs/16-ADGUARD-VLAN-PLAN.md: Implementation plan for AdGuard on VLANs - docs/17-DNS-ADGUARD-FAILOVER.md: Complete DNS architecture with: - Dual AdGuard setup (MikroTik primary, Unraid secondary) - Automatic failover via Netwatch monitoring - NAT redirect rules for all VLANs - Sync configuration between instances - docs/wip/CONSOLE-PORT-ETHER5.md: WIP plan for dedicated console port Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Kaloyan Danchev
521
docs/16-ADGUARD-VLAN-PLAN.md
Normal file
521
docs/16-ADGUARD-VLAN-PLAN.md
Normal file
@@ -0,0 +1,521 @@
|
||||
# AdGuard Configuration Plan for VLAN Structure
|
||||
|
||||
**Created:** 2026-01-31
|
||||
**Status:** IMPLEMENTED
|
||||
**Prerequisites:** VLAN setup complete (doc 15)
|
||||
**See Also:** [17-DNS-ADGUARD-FAILOVER.md](17-DNS-ADGUARD-FAILOVER.md) - Complete implementation with failover
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Configure AdGuard DNS filtering for the new VLAN-segmented network with:
|
||||
- MikroTik container as primary DNS (172.17.0.2)
|
||||
- Unraid AdGuard as secondary DNS (192.168.10.10)
|
||||
- DNS redirect for all VLANs
|
||||
- Different filtering policies per VLAN (Kids stricter)
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
| Component | IP | Status |
|
||||
|-----------|-----|--------|
|
||||
| AdGuard (Unraid) | 192.168.10.10 | Running |
|
||||
| AdGuard (MikroTik) | 172.17.0.2 | Not installed |
|
||||
| adguardhome-sync | 172.18.0.27 | Running |
|
||||
|
||||
---
|
||||
|
||||
## Network Architecture (VLAN-Aware)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ INTERNET │
|
||||
│ │
|
||||
│ Mobile/Remote ──► dns.xtrm-lab.org ──► WAN:853 (DoT) │
|
||||
│ ──► WAN:8443 (DoH) │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ MikroTik hAP ax³ │
|
||||
│ 192.168.10.1 │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────────────┐ │
|
||||
│ │ AdGuard Container │ │
|
||||
│ │ 172.17.0.2 (primary) │ │
|
||||
│ │ │ │
|
||||
│ │ Ports: 53 (DNS), 80 (HTTP), 443 (HTTPS), 853 (DoT) │ │
|
||||
│ └───────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────────────────┴────────────────────────────────┐ │
|
||||
│ │ DNS Redirect Rules │ │
|
||||
│ │ │ │
|
||||
│ │ VLAN 10 (192.168.10.0/24) ─► 172.17.0.2:53 Management │ │
|
||||
│ │ VLAN 20 (192.168.20.0/24) ─► 172.17.0.2:53 Trusted │ │
|
||||
│ │ VLAN 25 (192.168.25.0/24) ─► 172.17.0.2:53 Kids │ │
|
||||
│ │ VLAN 30 (192.168.30.0/24) ─► 172.17.0.2:53 IoT │ │
|
||||
│ │ VLAN 40 (192.168.1.0/24) ─► 172.17.0.2:53 Catch-All │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Unraid (VLAN 10) │
|
||||
│ 192.168.10.20 │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────────────┐ │
|
||||
│ │ AdGuard Container (secondary) │ │
|
||||
│ │ 192.168.10.10 │ │
|
||||
│ │ │ │
|
||||
│ │ Upstream: MikroTik AdGuard (172.17.0.2) │ │
|
||||
│ │ Failover: Quad9 DoH │ │
|
||||
│ └───────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────────────┐ │
|
||||
│ │ adguardhome-sync │ │
|
||||
│ │ 172.18.0.27 │ │
|
||||
│ │ │ │
|
||||
│ │ Syncs: MikroTik ◄─► Unraid (filters, rewrites, clients) │ │
|
||||
│ └───────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: MikroTik Container Setup
|
||||
|
||||
### 1.1 Create Container Infrastructure
|
||||
|
||||
```routeros
|
||||
# Container mode (if not already enabled)
|
||||
/system/device-mode/update container=yes
|
||||
|
||||
# Create veth interface
|
||||
/interface veth add address=172.17.0.2/24 gateway=172.17.0.1 name=veth-adguard
|
||||
|
||||
# Add to bridge
|
||||
/interface bridge port add bridge=bridge interface=veth-adguard
|
||||
|
||||
# Gateway IP for container network
|
||||
/ip address add address=172.17.0.1/24 interface=veth-adguard
|
||||
```
|
||||
|
||||
### 1.2 Create Container Mounts
|
||||
|
||||
```routeros
|
||||
# Create USB directory structure first
|
||||
/file print # verify usb1 exists
|
||||
|
||||
# Create mounts
|
||||
/container mounts add name=agh-config src=usb1/adguard/conf dst=/opt/adguardhome/conf
|
||||
/container mounts add name=agh-work src=usb1/adguard/work dst=/opt/adguardhome/work
|
||||
```
|
||||
|
||||
### 1.3 Pull and Create Container
|
||||
|
||||
```routeros
|
||||
# Environment variables
|
||||
/container envs add name=agh-env key=TZ value="Europe/Sofia"
|
||||
|
||||
# Pull image and create container
|
||||
/container add remote-image=adguard/adguardhome:latest \
|
||||
interface=veth-adguard \
|
||||
root-dir=usb1/adguard/root \
|
||||
mounts=agh-config,agh-work \
|
||||
envlist=agh-env \
|
||||
dns=8.8.8.8 \
|
||||
logging=yes \
|
||||
start-on-boot=yes \
|
||||
name=adguardhome
|
||||
|
||||
# Wait for extraction (check status)
|
||||
/container print
|
||||
|
||||
# Start when status shows "stopped" (not "extracting")
|
||||
/container start [find name=adguardhome]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: NAT Rules for All VLANs
|
||||
|
||||
### 2.1 Exception Rules (MUST BE FIRST)
|
||||
|
||||
```routeros
|
||||
# Allow AdGuard containers' own DNS queries (prevent loops)
|
||||
/ip firewall nat add chain=dstnat action=accept protocol=udp \
|
||||
src-address=172.17.0.0/24 dst-port=53 \
|
||||
comment="[DNS] Allow MikroTik AdGuard outbound" place-before=0
|
||||
|
||||
/ip firewall nat add chain=dstnat action=accept protocol=udp \
|
||||
src-address=192.168.10.10 dst-port=53 \
|
||||
comment="[DNS] Allow Unraid AdGuard outbound" place-before=1
|
||||
|
||||
/ip firewall nat add chain=dstnat action=accept protocol=tcp \
|
||||
src-address=192.168.10.10 dst-port=53 \
|
||||
comment="[DNS] Allow Unraid AdGuard outbound TCP" place-before=2
|
||||
```
|
||||
|
||||
### 2.2 VLAN DNS Redirect Rules
|
||||
|
||||
```routeros
|
||||
# VLAN 10 - Management (192.168.10.0/24)
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=udp src-address=192.168.10.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN10 Mgmt redirect"
|
||||
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=tcp src-address=192.168.10.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN10 Mgmt redirect TCP"
|
||||
|
||||
# VLAN 20 - Trusted (192.168.20.0/24)
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=udp src-address=192.168.20.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN20 Trusted redirect"
|
||||
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=tcp src-address=192.168.20.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN20 Trusted redirect TCP"
|
||||
|
||||
# VLAN 25 - Kids (192.168.25.0/24)
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=udp src-address=192.168.25.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN25 Kids redirect"
|
||||
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=tcp src-address=192.168.25.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN25 Kids redirect TCP"
|
||||
|
||||
# VLAN 30 - IoT (192.168.30.0/24)
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=udp src-address=192.168.30.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN30 IoT redirect"
|
||||
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=tcp src-address=192.168.30.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN30 IoT redirect TCP"
|
||||
|
||||
# VLAN 40 - Catch-All (192.168.1.0/24)
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=udp src-address=192.168.1.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN40 CatchAll redirect"
|
||||
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=53 \
|
||||
protocol=tcp src-address=192.168.1.0/24 dst-port=53 \
|
||||
comment="[DNS] VLAN40 CatchAll redirect TCP"
|
||||
```
|
||||
|
||||
### 2.3 Masquerade Rules for Return Traffic
|
||||
|
||||
```routeros
|
||||
# Masquerade for all VLAN subnets to AdGuard
|
||||
/ip firewall nat add chain=srcnat action=masquerade protocol=udp \
|
||||
src-address=192.168.10.0/24 dst-address=172.17.0.2 dst-port=53 \
|
||||
comment="[DNS] VLAN10 masquerade"
|
||||
|
||||
/ip firewall nat add chain=srcnat action=masquerade protocol=udp \
|
||||
src-address=192.168.20.0/24 dst-address=172.17.0.2 dst-port=53 \
|
||||
comment="[DNS] VLAN20 masquerade"
|
||||
|
||||
/ip firewall nat add chain=srcnat action=masquerade protocol=udp \
|
||||
src-address=192.168.25.0/24 dst-address=172.17.0.2 dst-port=53 \
|
||||
comment="[DNS] VLAN25 masquerade"
|
||||
|
||||
/ip firewall nat add chain=srcnat action=masquerade protocol=udp \
|
||||
src-address=192.168.30.0/24 dst-address=172.17.0.2 dst-port=53 \
|
||||
comment="[DNS] VLAN30 masquerade"
|
||||
|
||||
/ip firewall nat add chain=srcnat action=masquerade protocol=udp \
|
||||
src-address=192.168.1.0/24 dst-address=172.17.0.2 dst-port=53 \
|
||||
comment="[DNS] VLAN40 masquerade"
|
||||
```
|
||||
|
||||
### 2.4 External Access (DoT/DoH)
|
||||
|
||||
```routeros
|
||||
# DoT (DNS over TLS) - port 853
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=853 \
|
||||
protocol=tcp in-interface=ether1 dst-port=853 \
|
||||
comment="[DNS] DoT external"
|
||||
|
||||
# DoH (DNS over HTTPS) - port 8443 → 443
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=443 \
|
||||
protocol=tcp in-interface=ether1 dst-port=8443 \
|
||||
comment="[DNS] DoH external"
|
||||
```
|
||||
|
||||
### 2.5 Web UI Access
|
||||
|
||||
```routeros
|
||||
# AdGuard Web UI on port 3000 from Management VLAN
|
||||
/ip firewall nat add chain=dstnat action=dst-nat to-addresses=172.17.0.2 to-ports=80 \
|
||||
protocol=tcp dst-address=192.168.10.1 dst-port=3000 \
|
||||
comment="[DNS] AdGuard Web UI"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Firewall Filter Rules
|
||||
|
||||
```routeros
|
||||
# Allow traffic to container network
|
||||
/ip firewall filter add chain=input action=accept dst-address=172.17.0.0/24 \
|
||||
comment="[Container] Allow to container network" place-before=0
|
||||
|
||||
/ip firewall filter add chain=input action=accept src-address=172.17.0.0/24 \
|
||||
comment="[Container] Allow from container network" place-before=1
|
||||
|
||||
/ip firewall filter add chain=forward action=accept dst-address=172.17.0.0/24 \
|
||||
comment="[Container] Forward to container network"
|
||||
|
||||
/ip firewall filter add chain=forward action=accept src-address=172.17.0.0/24 \
|
||||
comment="[Container] Forward from container network"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: MikroTik DNS Settings
|
||||
|
||||
```routeros
|
||||
# Point MikroTik's own DNS resolver to AdGuard container
|
||||
/ip dns set servers=172.17.0.2 allow-remote-requests=yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: AdGuard Initial Configuration
|
||||
|
||||
### 5.1 Access Web UI
|
||||
|
||||
After container starts, access: `http://192.168.10.1:3000`
|
||||
|
||||
### 5.2 Initial Setup Wizard
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| Admin Interface | All interfaces, port 80 |
|
||||
| DNS Server | All interfaces, port 53 |
|
||||
| Username | admin |
|
||||
| Password | (set secure password) |
|
||||
|
||||
### 5.3 Upstream DNS
|
||||
|
||||
```
|
||||
# Primary (encrypted)
|
||||
https://dns.quad9.net/dns-query
|
||||
|
||||
# Fallback to Unraid AdGuard
|
||||
192.168.10.10
|
||||
```
|
||||
|
||||
### 5.4 Bootstrap DNS
|
||||
|
||||
```
|
||||
9.9.9.9
|
||||
149.112.112.112
|
||||
```
|
||||
|
||||
### 5.5 TLS Configuration (for DoT/DoH)
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| Server Name | dns.xtrm-lab.org |
|
||||
| Certificate Path | /opt/adguardhome/conf/fullchain.pem |
|
||||
| Key Path | /opt/adguardhome/conf/privkey.pem |
|
||||
|
||||
**Certificate upload:**
|
||||
```bash
|
||||
# From Mac - copy certificates to MikroTik USB
|
||||
scp -P 2222 /path/to/fullchain.pem xtrm@192.168.10.1:usb1/adguard/conf/
|
||||
scp -P 2222 /path/to/privkey.pem xtrm@192.168.10.1:usb1/adguard/conf/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Client Configuration per VLAN
|
||||
|
||||
### 6.1 DHCP Network Settings
|
||||
|
||||
Update each VLAN's DHCP to advertise AdGuard as DNS:
|
||||
|
||||
```routeros
|
||||
/ip dhcp-server network
|
||||
set [find address=192.168.10.0/24] dns-server=192.168.10.10
|
||||
set [find address=192.168.20.0/24] dns-server=192.168.10.10
|
||||
set [find address=192.168.25.0/24] dns-server=192.168.10.10
|
||||
set [find address=192.168.30.0/24] dns-server=192.168.10.10
|
||||
set [find address=192.168.1.0/24] dns-server=192.168.10.10
|
||||
```
|
||||
|
||||
**Note:** We use 192.168.10.10 (Unraid AdGuard) as the advertised DNS because:
|
||||
1. Clients can reach it directly on VLAN 10
|
||||
2. The NAT redirect still captures all DNS traffic to 172.17.0.2
|
||||
3. If redirect fails, clients fall back to Unraid AdGuard
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: AdGuard Sync Configuration
|
||||
|
||||
### 7.1 Update adguardhome-sync on Unraid
|
||||
|
||||
Edit `/mnt/user/appdata/adguardhome-sync/adguardhome-sync.yaml`:
|
||||
|
||||
```yaml
|
||||
origin:
|
||||
url: http://172.17.0.2 # MikroTik AdGuard (via router internal)
|
||||
username: admin
|
||||
password: YOUR_PASSWORD
|
||||
|
||||
replicas:
|
||||
- url: http://192.168.10.10 # Unraid AdGuard
|
||||
username: admin
|
||||
password: YOUR_PASSWORD
|
||||
|
||||
cron: "0 */30 * * * *" # Every 30 minutes
|
||||
|
||||
api:
|
||||
port: 8080
|
||||
|
||||
features:
|
||||
dns:
|
||||
rewrites: true
|
||||
filters: true
|
||||
clients: true
|
||||
services: true
|
||||
```
|
||||
|
||||
### 7.2 Restart Sync Container
|
||||
|
||||
```bash
|
||||
docker restart adguardhome-sync
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Kids VLAN Special Configuration (Optional)
|
||||
|
||||
For stricter filtering on VLAN 25 (Kids), you can:
|
||||
|
||||
### Option A: Separate AdGuard Client Profile
|
||||
|
||||
In AdGuard → Settings → Client Settings, add clients for Kids VLAN:
|
||||
- Identifier: 192.168.25.0/24
|
||||
- Name: Kids Devices
|
||||
- Enable: SafeSearch, Block Adult Sites
|
||||
- Custom filters: stricter blocklists
|
||||
|
||||
### Option B: Redirect to Different DNS (More Complex)
|
||||
|
||||
Create separate DNS redirect for VLAN 25 to a different filtering service.
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After implementation, verify:
|
||||
|
||||
- [ ] Container running: `/container print` shows "running"
|
||||
- [ ] DNS resolution: `:resolve google.com server=172.17.0.2`
|
||||
- [ ] VLAN 10 DNS: `nslookup google.com` from Unraid
|
||||
- [ ] VLAN 20 DNS: Test from trusted device
|
||||
- [ ] VLAN 25 DNS: Test from kids device
|
||||
- [ ] VLAN 30 DNS: Test from IoT device
|
||||
- [ ] VLAN 40 DNS: Test from catch-all device
|
||||
- [ ] DoT external: `kdig @dns.xtrm-lab.org +tls google.com`
|
||||
- [ ] DoH external: `curl https://dns.xtrm-lab.org:8443/dns-query?name=google.com`
|
||||
- [ ] Web UI accessible: `http://192.168.10.1:3000`
|
||||
- [ ] Sync working: Check adguardhome-sync logs
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container won't start
|
||||
|
||||
```routeros
|
||||
# Check container status
|
||||
/container print detail
|
||||
|
||||
# Check logs
|
||||
:log print where topics~"container"
|
||||
|
||||
# Common fix: recreate container
|
||||
/container remove [find name=adguardhome]
|
||||
# Then repeat Phase 1.3
|
||||
```
|
||||
|
||||
### DNS not redirecting
|
||||
|
||||
```routeros
|
||||
# Check NAT rules are active
|
||||
/ip firewall nat print where comment~"DNS"
|
||||
|
||||
# Test packet flow
|
||||
/tool sniffer quick port=53
|
||||
```
|
||||
|
||||
### Sync not working
|
||||
|
||||
```bash
|
||||
# On Unraid, check sync logs
|
||||
docker logs adguardhome-sync
|
||||
|
||||
# Verify connectivity
|
||||
curl -u admin:password http://172.17.0.2/control/status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
```routeros
|
||||
# Check AdGuard container
|
||||
/container print where name=adguardhome
|
||||
|
||||
# Restart AdGuard
|
||||
/container stop [find name=adguardhome]
|
||||
/container start [find name=adguardhome]
|
||||
|
||||
# Test DNS
|
||||
:resolve google.com server=172.17.0.2
|
||||
|
||||
# Check DNS NAT rules
|
||||
/ip firewall nat print where comment~"DNS"
|
||||
|
||||
# Backup before changes
|
||||
/system backup save name=pre-adguard-$(date)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files Location
|
||||
|
||||
| Item | Location |
|
||||
|------|----------|
|
||||
| MikroTik AdGuard Config | usb1/adguard/conf/AdGuardHome.yaml |
|
||||
| MikroTik AdGuard Work | usb1/adguard/work/ |
|
||||
| MikroTik TLS Certs | usb1/adguard/conf/*.pem |
|
||||
| Unraid AdGuard Config | /mnt/user/appdata/adguardhome/ |
|
||||
| Sync Config | /mnt/user/appdata/adguardhome-sync/ |
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order
|
||||
|
||||
1. **Backup MikroTik** - `/system backup save name=pre-adguard`
|
||||
2. **Phase 1** - Container setup (requires device mode update + reboot)
|
||||
3. **Phase 2** - NAT rules (careful with order!)
|
||||
4. **Phase 3** - Firewall filters
|
||||
5. **Phase 4** - MikroTik DNS settings
|
||||
6. **Test** - Verify DNS works
|
||||
7. **Phase 5** - AdGuard web configuration
|
||||
8. **Phase 6** - DHCP updates
|
||||
9. **Phase 7** - Sync setup
|
||||
10. **Phase 8** - Kids filtering (optional)
|
||||
|
||||
---
|
||||
|
||||
**Document Version:** 1.0
|
||||
**Last Updated:** 2026-01-31
|
||||
Reference in New Issue
Block a user