openwrt-adguard-setup/openwrt-adguard-setup.md

# OpenWRT Gateway & AdGuard Home - Complete Configuration Guide

## Network Overview

**New Network Topology:**
```
Cable Modem → OpenWRT (Main Gateway) → TP-Link Archer AX72 Pro (AP Mode) → Devices
                          ↓
                    AdGuard Home (10.0.0.245) - DNS Filtering
```

**IP Configuration:**
- OpenWRT WAN: DHCP from Cable Modem (Public IP)
- OpenWRT LAN: **10.0.0.254** (Main Gateway)
- AdGuard Home: **10.0.0.245** (DNS Server)
- TP-Link Archer AX72 Pro: **10.0.0.246** (AP Mode, no routing/DHCP)
- DHCP Range: **10.0.0.1 - 10.0.0.200**
- Subnet: **10.0.0.0/24**

**Roles:**
- **OpenWRT**: Main router, gateway, firewall, NAT, DHCP server, access control
- **AdGuard**: DNS filtering, ad blocking, phishing protection, parental controls
- **TP-Link AX72 Pro**: WiFi 6 access point + Ethernet switch only (no routing/DHCP)

---

## Part 1: OpenWRT Initial Setup as Main Gateway

### 1.1 Physical Connection Setup

**Connection Order:**
1. **DO NOT connect cable modem yet**
2. Connect computer to OpenWRT LAN port via Ethernet
3. Power on OpenWRT
4. Configure OpenWRT completely first
5. Then connect to cable modem

### 1.2 First Login and Basic Configuration

1. **Connect to OpenWRT:**
   - Connect via Ethernet to any LAN port
   - Default IP: `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 (e.g., 16+ characters with numbers/symbols).

3. **Set Timezone:**
   ```
   System → System → General Settings
   Timezone: Australia/Melbourne
   ```

### 1.3 Configure WAN Interface (Internet Connection)

**This connects OpenWRT to your cable modem.**

1. **Navigate to Network → Interfaces**

2. **Edit WAN interface:**
   - Protocol: `DHCP client` (most cable modems use DHCP)
   - Leave everything default initially
   - Advanced Settings:
     - ✓ Use DNS servers advertised by peer (we'll change this later)
     - Firewall Settings:
       - Create/Assign to firewall zone: `wan`
     - Click "Save"

3. **If your ISP requires specific settings:**
   - Some ISPs bind to your old router's MAC address
     - Advanced → Override MAC address (use your old router's MAC)
   - VLAN tagging
   - PPPoE (username/password)
   - Check with your ISP if connection fails

### 1.4 Configure LAN Interface

1. **Navigate to Network → Interfaces → LAN → Edit**

2. **Edit LAN interface:**
   - Protocol: `Static address`
   - IPv4 address: `10.0.0.254`
   - IPv4 netmask: `255.255.255.0`
   - IPv4 gateway: (leave empty - this IS the gateway)
   - Use custom DNS servers: `10.0.0.245`
   - Click "Save"

3. **Wait 30 seconds**, then reconnect to: `http://10.0.0.254`

### 1.5 Configure Firewall & NAT

1. **Network → Firewall → General Settings tab:**
   - ✓ Authoritative (OpenWRT is now the only DHCP server)
   - DNS forwardings: `10.0.0.245`
   - DNS server port: `53`
   - Local server: `/lan/`
   - Local domain: `lan` (or your preference like `home.local`)
   - Use custom DNS servers: `10.0.0.245`
   - Click "Save"

2. **Zone: WAN**
   - Input: `reject`
   - Output: `accept`
   - Forward: `reject`
   - ✓ Masquerading (NAT)
   - ✓ MSS clamping
   - Covered networks: `wan` `wan6`

3. **Zone: LAN**
   - Input: `accept`
   - Output: `accept`
   - Forward: `accept`
   - Masquerading: unchecked
   - Covered networks: `lan`

4. **Forwarding Rules:**
   - Add: LAN → WAN (Allow) - should exist by default
   - Verify this rule exists

5. **Advanced Settings:**
   - Enable SYN-flood protection: ✓
   - Drop invalid packets: ✓
   
6. **Save & Apply**

### 1.6 Test Internet Connection

**Now connect the cable modem:**
1. Connect cable modem to OpenWRT WAN port
2. Wait 60 seconds for modem to assign IP
3. Check connection:
   ```
   Network → Interfaces → WAN
   ```
   - Should show public IP addresses
   - Should show "Connected" status

4. **Test from OpenWRT:**
   - Go to Network → Diagnostics
   - Ping test: `8.8.8.8` (should work)
   - Ping test: `google.com` (should work)

5. **If connection fails:**
   - Check cable modem is online (lights stable)
   - Try rebooting cable modem (unplug 30 seconds)
   - Check WAN interface settings
   - Some ISPs require MAC cloning (see Section 1.9)

### 1.7 Update OpenWRT

**Before continuing, update packages:**

SSH into OpenWRT:
```bash
ssh root@10.0.0.254
```

Update package lists:
```bash
opkg update
opkg list-upgradable
opkg upgrade [package-name]
```

Or update all (be careful, test first):
```bash
opkg update
opkg list-upgradable | cut -d ' ' -f 1 | xargs opkg upgrade
```

### 1.8 Install Essential Packages

```bash
# Firewall and network tools
opkg install luci-app-firewall
opkg install iptables-mod-extra

# HTTPS for web interface (recommended)
opkg install luci-ssl-openssl

# Monitoring tools
opkg install luci-app-nlbwmon    # Bandwidth monitoring
opkg install luci-app-statistics # System stats

# Additional useful tools
opkg install tcpdump              # Network debugging
opkg install iperf3               # Speed testing
```

### 1.9 MAC Address Cloning (If Required)

Some ISPs bind to your old router's MAC address.

1. **Find your old router's WAN MAC address**
   - Usually on a sticker on TP-Link
   - Or from TP-Link admin interface

2. **Clone MAC in OpenWRT:**
   ```
   Network → Interfaces → WAN → Edit
   Advanced Settings:
     Override MAC address: [ENTER OLD ROUTER'S MAC]
   Save & Apply
   ```

3. **Reboot cable modem and OpenWRT:**

---

## Part 2: DHCP Server Configuration

### 2.1 Basic DHCP Settings

1. **Navigate to Network → DHCP and DNS**

2. **General Setup tab:**
   - ✓ Authoritative (CRITICAL - ensures OpenWRT is the only DHCP server)
   - DNS forwardings: `10.0.0.245`
   - DNS server port: `53`
   - Local server: `/lan/`
   - Local domain: `lan` (or your preference like `home.local`)
   - Use custom DNS servers: `10.0.0.245`
   - Click "Save"

3. **Advanced Settings:**
   - Rebind protection: ✓
   - Domain whitelist: (leave empty unless needed)
   - Strict order: ✓ (uses DNS servers in order)

### 2.2 DHCP Pool Configuration

1. **Navigate to Network → Interfaces → LAN → Edit → DHCP Server**

2. **General Setup:**
   - ✓ Enable DHCP server
   - Ignore interface: Unchecked (Enable DHCP)
   - Start: `1`
   - Limit: `200`
   - Lease time: `12h` (or `24h` for stability)

### 2.3 Advanced DHCP Options - Comprehensive Guide

**Understanding DHCP Options:**
DHCP options allow you to configure various network parameters automatically for clients. OpenWRT uses dnsmasq for DHCP, which supports extensive option configuration.

#### 2.3.1 DNS Configuration (Multiple DNS Servers)

**Dual DNS Setup: Filtered + Unfiltered**

To provide both filtered DNS (AdGuard) and unfiltered DNS (OpenWRT bypass), we configure DHCP option 6:

1. **Navigate to Network → DHCP and DNS → Advanced**

2. **Add DHCP Option for Dual DNS:**
   ```
   DHCP Options:
   6,10.0.0.245,10.0.0.254
   ```

**Explanation:**
- Option 6 = DNS servers
- `10.0.0.245` = AdGuard (filtered DNS, first priority)
- `10.0.0.254` = OpenWRT (unfiltered DNS, fallback)

**Client Behavior:**
- Most devices will use the first DNS (AdGuard) by default
- If AdGuard is down, devices fall back to OpenWRT direct DNS
- Users can manually configure devices to use only 10.0.0.254 for unfiltered access

#### 2.3.2 Boot Options (TFTP, PXE Network Boot)

**For network booting computers (useful for IT labs, diskless workstations):**

```
DHCP Options:
66,10.0.0.100
67,pxeboot/bootfile.efi
```

**Explanation:**
- Option 66 = TFTP server IP address
- Option 67 = Boot filename path
- Replace `10.0.0.100` with your TFTP server IP
- Replace `bootfile.efi` with your boot file

**Complete PXE Boot Setup:**
```
# TFTP Server
66,10.0.0.100

# Boot filename
67,pxelinux.0

# Alternative: UEFI boot
67,bootx64.efi
```

#### 2.3.3 Common DHCP Options Reference

**Network Time Protocol (NTP) Servers:**
```
42,10.0.0.254
```
- Option 42 = NTP server
- Provides time synchronization to all network devices

**Windows WINS Server:**
```
44,10.0.0.254
46,8
```
- Option 44 = WINS (NetBIOS) server
- Option 46 = NetBIOS node type (8 = h-node)

**Domain Name:**
```
15,home.local
```
- Option 15 = Domain name
- Used for hostname resolution

**Static Routes:**
```
121,24,10,0,1,10,0,0,254
```
- Option 121 = Classless static routes
- Format: prefix_length,network_bytes,gateway_bytes
- Example routes traffic for 10.0.1.0/24 via 10.0.0.254

**MTU Configuration:**
```
26,1500
```
- Option 26 = Interface MTU
- Adjust if you have jumbo frames or specific network requirements

**Vendor-Specific Options:**
```
43,hex:01:04:192:168:1:100
```
- Option 43 = Vendor-specific information
- Used for IP phones, wireless controllers, etc.

#### 2.3.4 Complete DHCP Options Configuration Example

**In OpenWRT, add to Network → DHCP and DNS → Advanced:**

```
DHCP Options:
6,10.0.0.245,10.0.0.254
15,home.local
42,10.0.0.254
```

**This provides:**
- Primary DNS: 10.0.0.245 (AdGuard filtered)
- Secondary DNS: 10.0.0.254 (OpenWRT unfiltered)
- Domain: home.local
- NTP Server: 10.0.0.254

#### 2.3.5 Testing DHCP Options

**On Windows:**
```cmd
ipconfig /all
```
Look for:
- DNS Servers: Should show both 10.0.0.245 and 10.0.0.254
- DHCP Server: Should show 10.0.0.254
- Connection-specific DNS Suffix: home.local

**On Linux:**
```bash
nmcli device show
```

**On macOS:**
```bash
scutil --dns
```

### 2.4 Static Leases Configuration

**Critical Static Leases:**

```
Hostname: adguard
MAC Address: [AdGuard server MAC]
IPv4 address: 10.0.0.245
Lease time: infinite
```

```
Hostname: tplink-ap
MAC Address: [TP-Link WAN/LAN MAC]
IPv4 address: 10.0.0.246
Lease time: infinite
```

```
Hostname: homeassistant (if applicable)
MAC Address: [HA MAC]
IPv4 address: 10.0.0.55
Lease time: infinite
```

**Other servers/devices:**
```
NAS: 10.0.0.60
Printer: 10.0.0.70
Desktop: 10.0.0.101
Laptop: 10.0.0.102
```

### 2.5 Per-Device DNS Configuration (For Parental Controls)

**Method: Via Config File**

SSH into OpenWRT and edit `/etc/config/dhcp`:

```bash
vi /etc/config/dhcp
```

Add host configuration:
```
# Standard adult device - uses AdGuard with full filtering
config host
    option name 'laptop'
    option mac '11:22:33:44:55:66'
    option ip '10.0.0.100'
    option dns '10.0.0.245'
    option tag 'kids'

# Kids tablet - uses AdGuard with parental controls
config host
    option name 'kids-tablet'
    option mac 'AA:BB:CC:DD:EE:FF'
    option ip '10.0.0.100'
    option dns '10.0.0.245'
    option tag 'kids'

# Work/unfiltered device - bypasses AdGuard
config host
    option name 'work-laptop'
    option mac '77:88:99:AA:BB:CC'
    option ip '10.0.0.150'
    option dns '1.1.1.1 8.8.8.8'
```

Restart dnsmasq:
```bash
/etc/init.d/dnsmasq restart
```

**Note:** We'll configure AdGuard to handle different filtering levels for kids vs adults in Part 5.

---

## Part 3: Access Control & Device Blocking

### 3.1 Create Device Blocking System

This allows you to block internet access for specific devices.

**Install the script:**

```bash
# SSH into OpenWRT
ssh root@10.0.0.254

# Create the script (use the existing device-control.sh in your repository)

# Make executable
chmod +x /root/device-control.sh

# Initialize the system
/root/device-control.sh init
```

### 3.2 Make Blocking Persistent

Add to `/etc/firewall.user` to survive reboots:

```bash
vi /etc/firewall.user
```

Add these lines:
```bash
ipset create blocked_devices hash:ip timeout 0 comment -exist
iptables -I FORWARD -m set --match-set blocked_devices src -j REJECT
```

Restart firewall:
```bash
/etc/init.d/firewall restart
```

### 3.3 Usage Examples

```bash
# Block kids tablet at bedtime
/root/device-control.sh block 10.0.0.100 "Kids Tablet"

# Unblock in the morning
/root/device-control.sh unblock 10.0.0.100

# Check if device is blocked
/root/device-control.sh status 10.0.0.100

# List all currently blocked devices
/root/device-control.sh list

# View action log
/root/device-control.sh log

# Clear all blocks (with confirmation)
/root/device-control.sh clear
```

### 3.4 Scheduled Access Control (Automatic Blocking)

For automatic blocking/unblocking via cron:

```bash
crontab -e
```

Add entries:
```bash
# Block kids devices at 9 PM every day
0 21 * * * /root/device-control.sh block 10.0.0.100 "Kids Tablet"
0 21 * * * /root/device-control.sh block 10.0.0.110 "Gaming Console"

# Unblock kids devices at 7 AM every day
0 7 * * * /root/device-control.sh unblock 10.0.0.100
0 7 * * * /root/device-control.sh unblock 10.0.0.110

# Block gaming console during school hours (Mon-Fri 8 AM - 3 PM)
0 8 * * 1-5 /root/device-control.sh block 10.0.0.110 "Gaming Console"
0 15 * * 1-5 /root/device-control.sh unblock 10.0.0.110

# Weekend gaming limits (noon-8pm only on Sat/Sun)
0 20 * * 6,0 /root/device-control.sh block 10.0.0.110 "Gaming Console"
0 12 * * 6,0 /root/device-control.sh unblock 10.0.0.110
```

---

## Part 4: TP-Link Archer AX72 Pro Configuration (AP Mode)

### 4.1 Important: Reconfigure TP-Link as Access Point

The TP-Link Archer AX72 Pro is a WiFi 6 router with significant advantages over older WiFi 5 (802.11ac) devices:

**Benefits:**
- Faster speeds: Up to 2402 Mbps on 5GHz, 574 Mbps on 2.4GHz
- Better efficiency: OFDMA allows multiple devices to share channels efficiently
- Reduced interference: BSS Coloring helps distinguish your network from neighbors
- Battery savings: Target Wake Time (TWT) for IoT devices
- More devices: Handles simultaneous connections more efficiently
- Beamforming: Improves range and speed

**Compatibility Notes:**
- Fully backward compatible with WiFi 5, WiFi 4 devices
- Older devices will use their native standard
- WPA2/WPA3 Mixed mode ensures older devices can connect
- All your existing devices will work, but WiFi 6 devices get the benefits

### 4.2 Connect to TP-Link

1. **Connect computer directly to TP-Link LAN port**
2. Access: `http://192.168.0.1` or `http://tplinwifi.net`
3. Default login: `admin/admin` (or on sticker)

### 4.3 Change Operation Mode

1. **Advanced → System Tools → Operation Mode**
2. Select: "Access Point Mode"
3. Click "Save"

### 4.4 Set Static IP

```
Advanced → Network → LAN
IP address: 10.0.0.246
Subnet Mask: 255.255.255.0
Gateway: 10.0.0.254
Primary DNS: 10.0.0.245
Secondary DNS: 10.0.0.254
Save
```

### 4.5 Reconnect after reboot

- New address: `http://10.0.0.246`

### 4.6 WiFi 6 Settings (2.4GHz WiFi)

```
Wireless → Wireless Settings (2.4GHz)
SSID: YourNetworkName
Channel: 1, 6, or 11 (check local regulations)
Channel Width: 20MHz or 40MHz (20MHz recommended for compatibility)
Mode: 802.11ax(WiFi 6)
Max Tx Rate: 574 Mbps
Enable Wireless: ✓
Enable SSID Broadcast: ✓
Enable OFDMA: ✓
Enable MU-MIMO: ✓
Enable BSS Coloring: ✓
Enable Target Wake Time: ✓ (good for IoT devices)
Enable Beamforming: ✓
```

### 4.7 WiFi 6 Settings (5GHz WiFi)

```
Wireless → Wireless Settings (5GHz)
SSID: YourNetworkName-5G (or same as 2.4GHz for seamless roaming)
Channel: 36, 40, 44, 48, 149, 153, 157, 161 (check local regulations)
Channel Width: 80MHz (or 160MHz if supported and no interference)
Mode: 802.11ax (WiFi 6)
Max Tx Rate: 2402 Mbps (with 80MHz) or 4804 Mbps (with 160MHz)
Enable Wireless: ✓
Enable SSID Broadcast: ✓
Enable OFDMA: ✓
Enable MU-MIMO: ✓
Enable BSS Coloring: ✓
Enable Target Wake Time: ✓
Enable Smart Connect: ✗ (disable unless needed)
```

**WiFi 6 Channel Width Recommendations:**
- **2.4GHz**: 20MHz for better efficiency and less interference
- **5GHz**: 80MHz for balance of speed and compatibility
- **5GHz**: 160MHz only if you have clear channels and WiFi 6 devices

### 4.8 WiFi Security (both bands):

```
Wireless → Wireless Security
Version: WPA3-Personal or WPA2/WPA3-Mixed (recommended)
Encryption: AES
Wireless Password: [Strong password 12+ characters]
Group Key Update Period: 3600 seconds
```

**WPA3 benefits but WPA2/WPA3 Mixed ensures older devices work.**

### 4.9 Optimization Settings

```
Advanced → Wireless → Advanced
Transmit Power: High (adjust if needed)
Smart Connect: Disabled (let devices choose band based on their SSID setup)
Fast Roaming: ✓ (if multiple APs)
```

### 4.10 Verify After Reconfiguration

- Access: `http://10.0.0.246`

---

## Part 5: AdGuard Home Setup

### 5.1 Install AdGuard

Choose your installation method:
- **Option A**: Docker installation on __________
- **Option B**: Native Linux installation on __________
- **Option C**: Windows installation on __________

### 5.2 Initial Configuration
- Access: http://10.0.0.245:3000
- Complete setup wizard
- Admin interface port: `3000`
- DNS server port: `53`
- Set admin username: _________________
- Set admin password: _________________
- Save credentials in password manager

### 5.3 Configure Upstream DNS
- Settings → DNS settings
- Add upstream servers:
  - `https://dns.cloudflare.com/dns-query`
  - `https://dns.google/dns-query`
  - `1.1.1.1`
  - `8.8.8.8`
- Enable parallel queries
- Save

### 5.4 Add Blocklists
- Filters → DNS blocklists
- Add OISD Big List: `https://big.oisd.nl/`
- Add AdGuard DNS: `https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt`
- Add Steven Black: `https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts`
- Save and Apply

### 5.5 Local DNS Entries
- Filters → DNS rewrites
- Add: `openwrt.local` → `10.0.0.254`
- Add: `adguard.local` → `10.0.0.245`
- Add: `homeassistant.local` → `10.0.0.55`
- Add: `tplink.local` → `10.0.0.246`

---

## Testing & Verification

### Test DHCP
- Connect test device to network
- Verify IP received in range 10.0.0.1-200
- Verify DNS servers shows 10.0.0.245 and 10.0.0.254
- Verify gateway is 10.0.0.254

### Test DNS Resolution
From test device:
```bash
nslookup google.com 10.0.0.245
```
- DNS query successful
- Response received

### Test AdGuard Filtering
- Access http://10.0.0.245:3000
- Dashboard → Query Log
- Browse to a website from test device
- Verify queries appear in log
- Try accessing known ad domain
- Verify ads are blocked

### Test Dual DNS Configuration
```bash
# Test filtered DNS (AdGuard)
nslookup doubleclick.net 10.0.0.245
# Should be blocked

# Test unfiltered DNS (OpenWRT)
nslookup doubleclick.net 10.0.0.254
# Should resolve normally
```

### Test Access Control
- Get test device IP: _________________
- Run: `/root/device-control.sh block [IP] "Test Device"`
- Verify internet access is blocked
- Run: `/root/device-control.sh unblock [IP]`
- Verify internet access restored

### Verify Static Leases
- Check each static device is getting correct IP
- HomeAssistant: 10.0.0.55 ✓
- AdGuard: 10.0.0.245 ✓
- TP-Link AP: 10.0.0.246 ✓

---

## Backup & Documentation

### Create Backups
- OpenWRT: System → Backup/Flash → Generate Archive
- Save backup file: openwrt-backup-[DATE].tar.gz
- AdGuard: Settings → General → Export Settings
- Save backup file: adguard-backup-[DATE].yaml

### Document Your Setup
Create a file with:
- OpenWRT admin password
- AdGuard admin credentials
- List of static IP assignments
- List of blocked devices (if any)
- Any custom firewall rules
- Backup file locations

---

## Troubleshooting

### Can't access OpenWRT web interface
```bash
/etc/init.d/uhttpd restart
netstat -tulpn | grep :80
```

### DHCP not giving out addresses
```bash
/etc/init.d/dnsmasq restart
logread | grep -i dhcp
```

### DNS not resolving
```bash
nslookup google.com 10.0.0.245
ping 10.0.0.245
```

### Device blocking not working
```bash
ipset list blocked_devices
iptables -L FORWARD -v -n
/etc/init.d/firewall restart
```

---

## Maintenance Schedule

### Weekly
- Check AdGuard query logs for anomalies
- Review blocked devices list
- Check OpenWRT system log for errors

### Monthly
- Update AdGuard blocklists
- Review and update static leases
- Check for OpenWRT updates: System → Software
- Create fresh backups

### Quarterly
- Review all firewall rules
- Audit device access permissions
- Update OpenWRT firmware if available
- Test backup restoration procedure

---

## Emergency Contacts & Resources

### Reset Instructions
**OpenWRT Hard Reset:**
- Press and hold reset button for 10 seconds
- Default IP will be 192.168.1.1

**AdGuard Reset:**
- Stop AdGuard service
- Delete config files
- Restart and run setup wizard

### Support Resources
- OpenWRT Forum: https://forum.openwrt.org/
- AdGuard Forum: https://forum.adguard.com/
- This documentation folder: _________________

---

## Completion

Setup completed by: _________________
Date: _________________
Time taken: ________ minutes

All phases completed successfully: ☐ YES ☐ NO

Notes/Issues encountered:
_____________________________________________
_____________________________________________
_____________________________________________

Next review date: _________________