Add comprehensive OpenWRT and AdGuard Home configuration guide

2025-12-11 00:31:43 +11:00
parent 617f5659f9
commit 1c3985bc17
1 changed files with 580 additions and 0 deletions
--- a/openwrt-adguard-setup.md
+++ b/openwrt-adguard-setup.md
@@ -0,0 +1,580 @@
+# OpenWRT and AdGuard Home Configuration Guide
+
+## Network Overview
+
+**Current Setup:**
+- Router: 10.0.0.254 (TPLink)
+- DNS: 10.0.0.55 (HomeAssistant/AdGuard)
+
+**New Setup:**
+- OpenWRT Router: 10.0.0.246
+- New AdGuard: 10.0.0.245
+- DHCP Range: 10.0.0.1 - 10.0.0.200
+
+---
+
+## Part 1: Initial OpenWRT Setup
+
+### 1.1 First Login and Basic Configuration
+
+1. **Connect to OpenWRT:**
+   - Connect via Ethernet to LAN port
+   - Default IP is usually `192.168.1.1`
+   - Access via browser: `http://192.168.1.1`
+   - Default login: `root` (no password initially)
+
+2. **Set Root Password:**
+   ```
+   System → Administration → Router Password
+   ```
+   Set a strong password immediately.
+
+### 1.2 Configure LAN Interface
+
+1. **Navigate to Network → Interfaces**
+
+2. **Edit LAN interface:**
+   - Protocol: `Static address`
+   - IPv4 address: `10.0.0.246`
+   - IPv4 netmask: `255.255.255.0`
+   - IPv4 gateway: `10.0.0.254` (your main TPLink router)
+   - Use custom DNS servers: `10.0.0.245` (your new AdGuard)
+   - Click "Save" then "Save & Apply"
+
+3. **Reconnect:**
+   - Your OpenWRT will now be at `http://10.0.0.246`
+   - You may need to manually set your PC to 10.0.0.x network temporarily
+
+---
+
+## Part 2: DHCP Server Configuration
+
+### 2.1 Basic DHCP Settings
+
+1. **Navigate to Network → DHCP and DNS**
+
+2. **Server Settings (General Settings tab):**
+   - Check "Authoritative" if this will be the only DHCP server on this network
+   - DNS forwardings: `10.0.0.245`
+   - Click "Save"
+
+3. **DHCP Pool Settings:**
+   - Navigate to Network → Interfaces → LAN → Edit → DHCP Server tab
+   - Check "Enable this DHCP server"
+   - Start: `1`
+   - Limit: `200`
+   - Lease time: `12h` (or your preference)
+
+### 2.2 Static Leases Configuration
+
+1. **Navigate to Network → DHCP and DNS → Static Leases tab**
+
+2. **Add Static Leases:**
+   - Click "Add"
+   - Hostname: Device name (e.g., "homeassistant")
+   - MAC Address: Device MAC
+   - IPv4 Address: Desired IP (e.g., 10.0.0.55)
+   - Lease time: Leave empty for infinite
+   - Click "Save" then "Save & Apply"
+
+Example static leases you might want:
+```
+10.0.0.55  - HomeAssistant/Current AdGuard
+10.0.0.245 - New AdGuard
+10.0.0.246 - OpenWRT itself
+10.0.0.254 - TPLink Router
+```
+
+### 2.3 DHCP Options for Custom DNS per Client
+
+To set different DNS servers for specific clients, you'll need to use DHCP options.
+
+**Option 1: Via LuCI (GUI)**
+1. Navigate to Network → DHCP and DNS → Static Leases
+2. When adding/editing a static lease, you can add DHCP options
+3. Add option `6` with comma-separated DNS IPs: `8.8.8.8,8.8.4.4`
+
+**Option 2: Via Config File (more flexible)**
+
+SSH into OpenWRT and edit `/etc/config/dhcp`:
+
+```bash
+vi /etc/config/dhcp
+```
+
+Add configuration like this:
+
+```
+config host
+    option name 'special-device'
+    option mac 'AA:BB:CC:DD:EE:FF'
+    option ip '10.0.0.100'
+    option dns '8.8.8.8 8.8.4.4'
+
+config host
+    option name 'standard-device'
+    option mac '11:22:33:44:55:66'
+    option ip '10.0.0.101'
+    # Uses default DNS (AdGuard at 10.0.0.245)
+```
+
+Then restart dnsmasq:
+```bash
+/etc/init.d/dnsmasq restart
+```
+
+---
+
+## Part 3: Access Control Configuration
+
+### 3.1 Install Required Packages
+
+SSH into your OpenWRT router and install firewall management tools:
+
+```bash
+opkg update
+opkg install luci-app-firewall
+opkg install iptables-mod-extra
+```
+
+### 3.2 Method 1: MAC Address Filtering (Simple Block)
+
+**Via LuCI:**
+1. Navigate to Network → Wireless (if WiFi) or DHCP
+2. For each device you want to block:
+   - Add to static lease with specific IP
+   - Then create firewall rule to block that IP
+
+**Create Firewall Rule:**
+1. Network → Firewall → Traffic Rules
+2. Add new rule:
+   - Name: `Block Device Name`
+   - Source zone: `lan`
+   - Source MAC or IP: `10.0.0.XX` or `AA:BB:CC:DD:EE:FF`
+   - Destination zone: `wan`
+   - Action: `reject`
+
+### 3.3 Method 2: IP Sets for Group Management (Advanced)
+
+This allows you to easily manage groups of blocked devices.
+
+**SSH Configuration:**
+
+Create custom firewall rules in `/etc/firewall.user`:
+
+```bash
+vi /etc/firewall.user
+```
+
+Add:
+```bash
+# Create IP set for blocked devices
+ipset create blocked_devices hash:ip -exist
+
+# Add devices to blocked list (can be managed dynamically)
+ipset add blocked_devices 10.0.0.100 -exist
+ipset add blocked_devices 10.0.0.101 -exist
+
+# Block internet access for devices in the set
+iptables -I FORWARD -m set --match-set blocked_devices src -o eth1 -j REJECT
+```
+
+Apply:
+```bash
+/etc/init.d/firewall restart
+```
+
+**To add/remove devices from block list:**
+```bash
+# Block a device
+ipset add blocked_devices 10.0.0.150
+
+# Unblock a device
+ipset del blocked_devices 10.0.0.150
+
+# List blocked devices
+ipset list blocked_devices
+```
+
+### 3.4 Method 3: Parental Controls Package (Easiest GUI)
+
+Install parental controls:
+```bash
+opkg update
+opkg install luci-app-advanced-reboot
+opkg install luci-app-simple-adblock  # Optional, if not using AdGuard
+```
+
+For better device management, install:
+```bash
+opkg install luci-app-nlbwmon  # Network bandwidth monitoring
+```
+
+This gives you per-device traffic monitoring and easier access control.
+
+---
+
+## Part 4: AdGuard Home Setup (10.0.0.245)
+
+### 4.1 Installation Options
+
+**Option A: Docker (Recommended if you have Docker)**
+```bash
+docker run -d \
+  --name adguardhome \
+  --restart unless-stopped \
+  -v /path/to/adguard/work:/opt/adguardhome/work \
+  -v /path/to/adguard/conf:/opt/adguardhome/conf \
+  -p 10.0.0.245:53:53/tcp \
+  -p 10.0.0.245:53:53/udp \
+  -p 10.0.0.245:3000:3000/tcp \
+  adguard/adguardhome
+```
+
+**Option B: Native Linux Install**
+```bash
+curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
+```
+
+**Option C: Windows**
+Download from: https://github.com/AdguardTeam/AdGuardHome/releases
+
+### 4.2 Initial AdGuard Configuration
+
+1. **Access Setup:** `http://10.0.0.245:3000`
+
+2. **Setup Wizard:**
+   - Admin Web Interface: Port `3000` (or your choice)
+   - DNS Server: Port `53`
+   - Admin credentials: Set username and password
+
+3. **Configure Upstream DNS:**
+   - Navigate to Settings → DNS settings
+   - Add upstream DNS servers:
+     ```
+     https://dns.cloudflare.com/dns-query
+     https://dns.google/dns-query
+     1.1.1.1
+     8.8.8.8
+     ```
+   - Enable parallel queries for better performance
+   - Set rate limit: 20 (adjust based on needs)
+
+4. **Configure Private Reverse DNS:**
+   - Add your local network: `10.0.0.0/24`
+   - Enable "Use private reverse DNS resolvers"
+
+5. **Enable Query Logging:**
+   - Settings → General settings
+   - Query logs retention: 7 days (or your preference)
+   - Statistics retention: 90 days
+
+### 4.3 Blocklists Configuration
+
+Add recommended blocklists:
+
+1. Navigate to Filters → DNS blocklists
+2. Add these lists:
+
+```
+# OISD Big List (comprehensive)
+https://big.oisd.nl/
+
+# AdGuard DNS filter
+https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt
+
+# Steven Black's Unified Hosts
+https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
+
+# Hagezi's Pro DNS Blocklist
+https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro-onlydomains.txt
+```
+
+3. Click "Save" and "Apply"
+
+### 4.4 Custom Filtering Rules
+
+For local network DNS resolution, add custom rules:
+
+1. Navigate to Filters → DNS rewrites
+2. Add entries:
+   ```
+   openwrt.local → 10.0.0.246
+   adguard.local → 10.0.0.245
+   homeassistant.local → 10.0.0.55
+   router.local → 10.0.0.254
+   ```
+
+---
+
+## Part 5: Integration and Testing
+
+### 5.1 Point OpenWRT to AdGuard
+
+Ensure OpenWRT is configured to use AdGuard:
+
+1. Network → Interfaces → LAN → Edit
+2. Advanced Settings tab:
+   - Use custom DNS servers: `10.0.0.245`
+3. Network → DHCP and DNS:
+   - DNS forwardings: `10.0.0.245`
+
+### 5.2 Testing DHCP
+
+1. **Connect a test device** to the OpenWRT network
+2. **Check IP assignment:**
+   ```bash
+   # On Windows
+   ipconfig /all
+   
+   # On Linux
+   ip addr show
+   ```
+3. **Verify you receive:**
+   - IP in range 10.0.0.1-200
+   - DNS server: 10.0.0.245
+   - Gateway: 10.0.0.246 or 10.0.0.254
+
+### 5.3 Testing DNS Resolution
+
+```bash
+# On Windows
+nslookup google.com 10.0.0.245
+
+# On Linux
+dig @10.0.0.245 google.com
+```
+
+### 5.4 Testing Access Control
+
+1. Add a device to block list
+2. Try to access internet from that device
+3. Verify connection is blocked
+4. Check OpenWRT firewall logs: Status → Firewall
+
+### 5.5 Monitor AdGuard
+
+1. Access AdGuard dashboard: `http://10.0.0.245:3000`
+2. Check:
+   - Query log shows requests
+   - Blocked requests are being filtered
+   - All devices are showing up
+
+---
+
+## Part 6: Advanced Configuration
+
+### 6.1 Create Easy Device Management Script
+
+Save this script on OpenWRT as `/root/device-control.sh`:
+
+```bash
+#!/bin/sh
+
+# Device Access Control Script for OpenWRT
+
+ACTION=$1
+DEVICE_IP=$2
+DEVICE_NAME=$3
+
+case $ACTION in
+  block)
+    ipset add blocked_devices $DEVICE_IP -exist
+    echo "Blocked: $DEVICE_NAME ($DEVICE_IP)"
+    ;;
+  unblock)
+    ipset del blocked_devices $DEVICE_IP
+    echo "Unblocked: $DEVICE_NAME ($DEVICE_IP)"
+    ;;
+  list)
+    echo "Currently blocked devices:"
+    ipset list blocked_devices
+    ;;
+  status)
+    ipset test blocked_devices $DEVICE_IP && echo "$DEVICE_IP is BLOCKED" || echo "$DEVICE_IP is ALLOWED"
+    ;;
+  *)
+    echo "Usage: $0 {block|unblock|list|status} [IP] [NAME]"
+    exit 1
+    ;;
+esac
+```
+
+Make executable:
+```bash
+chmod +x /root/device-control.sh
+```
+
+Usage:
+```bash
+# Block a device
+./device-control.sh block 10.0.0.100 "Kids Tablet"
+
+# Unblock
+./device-control.sh unblock 10.0.0.100 "Kids Tablet"
+
+# List all blocked
+./device-control.sh list
+
+# Check status
+./device-control.sh status 10.0.0.100
+```
+
+### 6.2 Setup Scheduled Device Controls (Optional)
+
+To block devices at specific times (e.g., bedtime):
+
+```bash
+# Edit crontab
+crontab -e
+```
+
+Add entries:
+```cron
+# Block kids devices at 9 PM
+0 21 * * * /root/device-control.sh block 10.0.0.100 "Kids Tablet"
+
+# Unblock at 7 AM
+0 7 * * * /root/device-control.sh unblock 10.0.0.100 "Kids Tablet"
+```
+
+### 6.3 Backup Configurations
+
+**OpenWRT Backup:**
+1. System → Backup / Flash Firmware
+2. Click "Generate archive"
+3. Save the `.tar.gz` file
+
+**AdGuard Backup:**
+1. Settings → General settings
+2. Scroll to "Export settings"
+3. Click "Download" to save YAML config
+
+---
+
+## Part 7: Network Topology Options
+
+### Option A: OpenWRT as Router (Full Gateway)
+```
+Internet → TPLink (10.0.0.254) → OpenWRT (10.0.0.246) → Devices
+                                      ↓
+                                 AdGuard (10.0.0.245)
+```
+- Requires routing configuration
+- More complex but more control
+
+### Option B: OpenWRT as DHCP/Access Point (Recommended for your setup)
+```
+Internet → TPLink (10.0.0.254) ← Gateway for all
+              ↓
+         OpenWRT (10.0.0.246) - DHCP Server + Access Control
+              ↓
+         AdGuard (10.0.0.245) - DNS Filtering
+              ↓
+         Devices (10.0.0.1-200)
+```
+- OpenWRT provides DHCP and access control
+- TPLink remains gateway
+- AdGuard handles DNS
+- Simpler setup, which I've documented above
+
+---
+
+## Troubleshooting
+
+### DHCP not working
+```bash
+# Check DHCP status
+/etc/init.d/dnsmasq status
+
+# Restart DHCP
+/etc/init.d/dnsmasq restart
+
+# Check logs
+logread | grep -i dhcp
+```
+
+### DNS not resolving
+```bash
+# Test DNS on OpenWRT itself
+nslookup google.com 10.0.0.245
+
+# Check if AdGuard is running
+# On AdGuard server
+netstat -tulpn | grep :53
+```
+
+### Access control not working
+```bash
+# Check firewall rules
+iptables -L FORWARD -v -n
+
+# Check ipset
+ipset list blocked_devices
+
+# Reload firewall
+/etc/init.d/firewall restart
+```
+
+### Can't access OpenWRT web interface
+```bash
+# SSH in and check
+netstat -tulpn | grep :80
+
+# Restart web interface
+/etc/init.d/uhttpd restart
+```
+
+---
+
+## Quick Reference Commands
+
+```bash
+# OpenWRT
+/etc/init.d/network restart    # Restart network
+/etc/init.d/dnsmasq restart    # Restart DHCP/DNS
+/etc/init.d/firewall restart   # Restart firewall
+logread                         # View system logs
+
+# View DHCP leases
+cat /tmp/dhcp.leases
+
+# View current connections
+cat /proc/net/nf_conntrack
+
+# Monitor traffic
+tcpdump -i br-lan port 53      # Monitor DNS traffic
+```
+
+---
+
+## Next Steps
+
+1. **Set up OpenWRT first** with static IP 10.0.0.246
+2. **Configure DHCP** with your range and static leases
+3. **Install and configure AdGuard** on 10.0.0.245
+4. **Point OpenWRT DNS** to AdGuard
+5. **Set up access control** using one of the methods above
+6. **Test thoroughly** with various devices
+7. **Create backups** of both configurations
+
+---
+
+## Security Recommendations
+
+1. **Change default passwords** on both OpenWRT and AdGuard
+2. **Enable HTTPS** for OpenWRT web interface (System → Administration → HTTP(S) Access)
+3. **Disable SSH password authentication**, use keys instead
+4. **Keep OpenWRT updated**: System → Software → Update lists
+5. **Enable AdGuard statistics** to monitor unusual activity
+6. **Set up firewall rules** to prevent LAN → LAN attacks if needed
+7. **Regular backups** of both configurations
+
+---
+
+## Additional Resources
+
+- OpenWRT Documentation: https://openwrt.org/docs/start
+- AdGuard Home Documentation: https://github.com/AdguardTeam/AdGuardHome/wiki
+- OpenWRT Forum: https://forum.openwrt.org/
+- AdGuard Forum: https://forum.adguard.com/