diff --git a/docs/16-ADGUARD-VLAN-PLAN.md b/docs/16-ADGUARD-VLAN-PLAN.md new file mode 100644 index 0000000..e15099d --- /dev/null +++ b/docs/16-ADGUARD-VLAN-PLAN.md @@ -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 diff --git a/docs/17-DNS-ADGUARD-FAILOVER.md b/docs/17-DNS-ADGUARD-FAILOVER.md new file mode 100644 index 0000000..e760a46 --- /dev/null +++ b/docs/17-DNS-ADGUARD-FAILOVER.md @@ -0,0 +1,358 @@ +# DNS Architecture with AdGuard Failover + +**Created:** 2026-01-31 +**Status:** Implemented +**Backup:** `adguard-failover-complete-2026-01-31.backup` + +--- + +## Overview + +Dual AdGuard DNS setup with automatic failover. All DNS queries are filtered through AdGuard for ad-blocking, and if the primary (MikroTik) fails, traffic automatically switches to secondary (Unraid). + +--- + +## Architecture + +``` + ┌─────────────────────────────────────┐ + │ INTERNET │ + │ │ + │ External clients (DoT/DoH) │ + │ dns.xtrm-lab.org:853 (DoT) │ + │ dns.xtrm-lab.org:8443 (DoH) │ + └──────────────┬──────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────────────────────────┐ +│ MikroTik hAP ax³ (192.168.10.1) │ +│ │ +│ ┌────────────────────────────────────────────────────────────────────────┐ │ +│ │ AdGuard Home (PRIMARY) │ │ +│ │ Container: 172.17.0.2 │ │ +│ │ Web UI: http://192.168.10.1:3000 │ │ +│ │ │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ +│ │ │ Filters │ │ Blocklists │ │ Clients │ │ │ +│ │ │ (synced) │ │ 143K rules │ │ (synced) │ │ │ +│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ +│ └────────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ Netwatch monitors every 10s │ +│ │ │ +│ ┌─────────┴─────────┐ │ +│ │ │ │ +│ Container UP Container DOWN │ +│ │ │ │ +│ ▼ ▼ │ +│ NAT → 172.17.0.2 NAT → 192.168.10.10 │ +│ (MikroTik) (Unraid Failover) │ +└──────────────────────────────────────────────────────────────────────────────┘ + ▲ ▲ ▲ + │ │ │ + NAT Redirect NAT Redirect NAT Redirect + │ │ │ +┌───────┴───────┐ ┌────────┴────────┐ ┌────────┴────────┐ +│ VLAN 10 │ │ VLAN 20/25 │ │ VLAN 30/40 │ +│ Management │ │ Trusted/Kids │ │ IoT/CatchAll │ +│ 192.168.10.x │ │ 192.168.20.x │ │ 192.168.30.x │ +│ │ │ 192.168.25.x │ │ 192.168.1.x │ +└───────────────┘ └─────────────────┘ └─────────────────┘ +``` + +--- + +## AdGuard Instances + +| Instance | Role | IP | Port | Web UI | +|----------|------|-----|------|--------| +| MikroTik | Primary | 172.17.0.2 | 53 | http://192.168.10.1:3000 | +| Unraid | Secondary/Failover | 192.168.10.10 | 3000 | http://192.168.10.10:3000 | + +### Credentials (Same for Both) + +| Username | Password | +|----------|----------| +| jazzymc | 7RqWElENNbZnPW | + +--- + +## DNS Redirect Rules + +All DNS queries (port 53) from any VLAN are intercepted and redirected: + +| VLAN | Subnet | Redirected To | +|------|--------|---------------| +| 10 | 192.168.10.0/24 | 172.17.0.2:53 | +| 20 | 192.168.20.0/24 | 172.17.0.2:53 | +| 25 | 192.168.25.0/24 | 172.17.0.2:53 | +| 30 | 192.168.30.0/24 | 172.17.0.2:53 | +| 40 | 192.168.1.0/24 | 172.17.0.2:53 | + +**Note:** Clients don't need any DNS configuration - even if they use 8.8.8.8, traffic is intercepted by NAT. + +### NAT Rules on MikroTik + +```routeros +# Exception rules (prevent loops) - MUST BE FIRST +/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" +add chain=dstnat action=accept protocol=udp src-address=192.168.10.10 dst-port=53 comment="[DNS] Allow Unraid AdGuard outbound" + +# VLAN redirect rules +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" +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" +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" +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" +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" + +# Masquerade for return traffic +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" +# ... (similar for other VLANs) +``` + +--- + +## Automatic Failover + +### How It Works + +1. **Netwatch** monitors 172.17.0.2 (container IP) every 10 seconds +2. If ping fails for 3 seconds → status changes to "down" +3. **dns-failover-down** script runs → NAT rules switch to Unraid +4. When ping succeeds again → status changes to "up" +5. **dns-failover-up** script runs → NAT rules switch back to MikroTik + +### Failover Timeline + +| Event | Detection Time | Total Switchover | +|-------|----------------|------------------| +| Container stops | ~10-13 seconds | ~13-16 seconds | +| Container recovers | ~10-13 seconds | ~13-16 seconds | + +### Failover Scripts + +```routeros +# dns-failover-down (runs when container is unreachable) +/system script add name=dns-failover-down dont-require-permissions=yes source={ + :log warning "DNS Failover: Switching to Unraid" + /ip firewall nat set [find where comment~"VLAN" and comment~"redirect"] to-addresses=192.168.10.10 to-ports=3000 +} + +# dns-failover-up (runs when container is back) +/system script add name=dns-failover-up dont-require-permissions=yes source={ + :log info "DNS Failover: Switching back to MikroTik" + /ip firewall nat set [find where comment~"VLAN" and comment~"redirect"] to-addresses=172.17.0.2 to-ports=53 +} +``` + +### Netwatch Configuration + +```routeros +/tool netwatch add host=172.17.0.2 interval=10s timeout=3s \ + up-script=dns-failover-up \ + down-script=dns-failover-down \ + comment="AdGuard failover monitor" +``` + +--- + +## Sync Configuration + +Settings are synced from Unraid (source of truth) to MikroTik every 30 minutes. + +### What Syncs + +| Feature | Synced | +|---------|--------| +| Filter lists (blocklists) | ✅ | +| User rules (custom blocks/allows) | ✅ | +| Client settings (per-device rules) | ✅ | +| Services (blocked services) | ✅ | +| Rewrites (custom DNS entries) | ✅ | +| DNS server config | ❌ | +| DHCP settings | ❌ | +| Query logs/stats | ❌ | + +### Sync Container + +```yaml +# /mnt/user/appdata/adguard-sync/adguardhome-sync.yaml +cron: "*/30 * * * *" +runOnStart: true + +origin: + url: http://192.168.10.10:3000 + username: jazzymc + password: 7RqWElENNbZnPW + +replicas: + - url: http://192.168.10.1:3000 + username: jazzymc + password: 7RqWElENNbZnPW + +features: + dns: + serverConfig: false + accessLists: true + rewrites: true + filters: true + clientSettings: true + services: true +``` + +**Note:** The sync container must be connected to both `dockerproxy` and `br0` networks to reach both AdGuard instances. + +--- + +## Container Configuration (MikroTik) + +### Container Details + +| Setting | Value | +|---------|-------| +| Image | adguard/adguardhome:latest | +| Interface | veth-adguard | +| IP | 172.17.0.2/24 | +| Gateway | 172.17.0.1 | +| Root dir | usb1/adguard/root | +| Config mount | usb1/adguard/conf → /opt/adguardhome/conf | +| Work mount | usb1/adguard/work → /opt/adguardhome/work | +| Start on boot | Yes | + +### Container Commands + +```routeros +# Check status +/container print + +# Start container +/container start 0 + +# Stop container +/container stop 0 + +# View logs +/log print where topics~"container" +``` + +--- + +## Upstream DNS + +Both AdGuard instances use the same upstream: + +| Upstream | Type | +|----------|------| +| https://dns.quad9.net/dns-query | Primary (DoH) | +| 9.9.9.9 | Bootstrap | +| 149.112.112.112 | Bootstrap secondary | + +--- + +## Management + +| Task | Where to Do It | +|------|----------------| +| Change blocklists | Unraid AdGuard (syncs to MikroTik) | +| Add custom rules | Unraid AdGuard | +| Add client settings | Unraid AdGuard | +| View query logs | MikroTik AdGuard (real-time) | +| Check failover status | MikroTik `/tool netwatch print` | + +--- + +## Troubleshooting + +### Check Failover Status + +```routeros +/tool netwatch print +# STATUS should be "up" normally +``` + +### Check Current DNS Target + +```routeros +/ip firewall nat print where comment~"VLAN10 Mgmt redirect" +# to-addresses should be 172.17.0.2 (normal) or 192.168.10.10 (failover) +``` + +### View Failover Logs + +```routeros +/log print where message~"Failover" +``` + +### Manual Failover Test + +```routeros +# Stop container (triggers failover) +/container stop 0 + +# Wait 15 seconds, check NAT rules switched to 192.168.10.10 + +# Start container (triggers recovery) +/container start 0 + +# Wait 15 seconds, check NAT rules switched back to 172.17.0.2 +``` + +### DNS Not Working + +1. Check container is running: `/container print` +2. Check netwatch status: `/tool netwatch print` +3. Test DNS directly: `:resolve google.com server=172.17.0.2` +4. Check NAT rules: `/ip firewall nat print where comment~"DNS"` + +### Sync Not Working + +```bash +# On Unraid +docker logs adguardhome-sync --tail 20 + +# Check connectivity +docker exec adguardhome-sync ping -c 2 192.168.10.10 +docker exec adguardhome-sync ping -c 2 192.168.10.1 +``` + +--- + +## Backups + +| Backup | Description | +|--------|-------------| +| `pre-adguard-2026-01-31` | Before AdGuard setup | +| `adguard-container-running-2026-01-31` | Container working, before NAT | +| `adguard-synced-2026-01-31` | After sync configured | +| `adguard-failover-complete-2026-01-31` | Final with failover | + +### Restore Command + +```routeros +/system backup load name=adguard-failover-complete-2026-01-31 +``` + +--- + +## Quick Reference + +### Normal Operation +- DNS queries → MikroTik AdGuard (172.17.0.2) +- Ad blocking active +- ~143,000 filter rules + +### During Failover +- DNS queries → Unraid AdGuard (192.168.10.10) +- Ad blocking still active (same rules synced) +- Automatic, no manual intervention needed + +### Recovery +- Automatic when container comes back up +- NAT rules switch back to MikroTik +- No DNS interruption for clients + +--- + +**Document Version:** 1.0 +**Last Updated:** 2026-01-31 diff --git a/docs/wip/CONSOLE-PORT-ETHER5.md b/docs/wip/CONSOLE-PORT-ETHER5.md new file mode 100644 index 0000000..1423e36 --- /dev/null +++ b/docs/wip/CONSOLE-PORT-ETHER5.md @@ -0,0 +1,110 @@ +# WIP: Dedicated Console Port on ether5 + +**Status:** Pending consideration +**Created:** 2026-01-31 +**Purpose:** Emergency management access independent of VLAN configuration + +--- + +## Rationale + +If VLAN or bridge configuration breaks, having a dedicated port with static IP provides guaranteed router access without relying on the main network setup. + +--- + +## Current State + +| Port | Current Use | PVID | +|------|-------------|------| +| ether5 | Unraid eth2 (bond member) | 10 | + +--- + +## Proposed Configuration + +### Remove ether5 from Bridge + +```routeros +# Backup first +/system backup save name=pre-console-port + +# Remove from bridge +/interface bridge port remove [find interface=ether5] +``` + +### Assign Static IP + +```routeros +# Isolated subnet - not used by any VLAN +/ip address add address=192.168.99.1/24 interface=ether5 comment="Console Port - Emergency Access" +``` + +### Firewall Rule + +```routeros +# Allow all management traffic from console port +/ip firewall filter add chain=input action=accept in-interface=ether5 \ + comment="Console Port - Allow All" place-before=0 +``` + +--- + +## Access Instructions + +1. Connect laptop directly to **ether5** (rightmost port on hAP ax³) +2. Configure laptop with static IP: + - IP: `192.168.99.2` + - Netmask: `255.255.255.0` + - Gateway: `192.168.99.1` +3. Access router: + - **WinBox:** 192.168.99.1:8291 + - **SSH:** `ssh -p 2222 xtrm@192.168.99.1` + - **WebFig:** http://192.168.99.1 + +--- + +## Impact Assessment + +### Pros +- Always-available management access +- Independent of bridge/VLAN state +- Works even if filtering misconfigured + +### Cons +- Loses one port from bridge (ether5) +- Unraid bonding reduced to single link (ether4 only) +- Physical security concern (anyone plugging in gets router access) + +--- + +## Alternatives + +### Option A: Use ether5 (Current Proposal) +- Simple, dedicated port +- Sacrifices Unraid bond member + +### Option B: Use ether2 (CAP XL ac port) +- CAP currently on ether2 +- Would need to move CAP to switch port +- More complex but preserves Unraid bond + +### Option C: Separate VLAN for Management +- Keep ether5 in bridge +- Create untagged management VLAN on ether5 +- More complex but keeps port in bridge + +--- + +## Decision + +- [ ] Implement Option A (ether5 dedicated) +- [ ] Implement Option B (move CAP) +- [ ] Implement Option C (management VLAN) +- [ ] Defer - not needed + +--- + +**Notes:** +- Consider physical labeling of port if implemented +- Document in network map +- Keep emergency access instructions printed/offline