From 1c3985bc173083feaab6cfe13b78da69f3c5cd51 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Thu, 11 Dec 2025 00:31:43 +1100 Subject: [PATCH] Add comprehensive OpenWRT and AdGuard Home configuration guide --- openwrt-adguard-setup.md | 580 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 580 insertions(+) create mode 100644 openwrt-adguard-setup.md diff --git a/openwrt-adguard-setup.md b/openwrt-adguard-setup.md new file mode 100644 index 0000000..b5e2094 --- /dev/null +++ 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/