wireguard-lab-overlay/docs/openwrt-setup.md

OpenWrt Gateway Setup Guide

Prerequisites

OpenWrt Version

• Minimum: OpenWrt 23.05 (stable)
• Recommended: Latest stable release
• Architectures: x86_64, ARM, MIPS supported

Hardware Requirements

• Flash: Minimum 128MB (256MB+ recommended)
• RAM: Minimum 128MB (256MB+ recommended)
• Network Interfaces: At least 2 (one for management, one for lab devices)

Initial OpenWrt Preparation

1. Fresh OpenWrt Installation

Ensure you have a clean OpenWrt installation with network access.

# From your management workstation
ssh root@<openwrt-ip>

2. Configure Management Network

Ensure the router is reachable from your management server:

# On OpenWrt router
uci set network.lan.ipaddr='192.168.1.21'
uci set network.lan.netmask='255.255.255.0'
uci commit network
/etc/init.d/network restart

3. Install Required Packages

The Ansible playbook will auto-install these, but you can pre-install:

opkg update
opkg install wireguard-tools kmod-wireguard kmod-vxlan ip-full tcpdump

4. Enable SSH Access

Ensure SSH is accessible:

# Set root password if not already set
passwd

# Enable SSH
/etc/init.d/dropbear enable
/etc/init.d/dropbear start

5. Configure SSH Keys (Recommended)

From your management server:

ssh-copy-id root@192.168.1.21

Network Interface Configuration

Identifying Interfaces

List available interfaces:

# On OpenWrt
ip link show

Common interface names:

• x86_64: eth0, eth1, eth2
• ARM/embedded: lan1, lan2, wan
• VLAN-aware: eth0.1, eth0.2

Recommended Setup

┌──────────────────┐
│  OpenWrt Router  │
│                  │
│  eth0  ───────────┼──→ Corporate Network (Management)
│  eth1  ───────────┼──→ Lab Devices (Physical Connection)
│                  │
│  wg_lab100 ──────┼──→ WireGuard Overlay
│  vxlan100 ───────┼──→ VXLAN over WireGuard
│  br_lab100 ──────┼──→ Bridge (eth1 + vxlan100)
└──────────────────┘

Deployment via Ansible

1. Update Terraform Configuration

Edit terraform/terraform.tfvars:

lab_networks = {
  lab100 = {
    vni           = 100
    subnet        = "10.100.0.0/24"
    wireguard_net = "172.16.100.0/24"
    dhcp_mode     = "simple"
    road_warrior  = false
    gateways = [
      {
        hostname  = "lab100-openwrt1"
        type      = "openwrt"           # Important: set to 'openwrt'
        mgmt_ip   = "192.168.1.21"
        api_port  = 22
        lab_if    = "eth1"              # Interface facing lab devices
        dhcp_role = "primary"
      }
    ]
  }
}

2. Deploy

# From project root
./deploy.sh

Or manually:

cd terraform
terraform apply
cd ../ansible
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

Verification

1. Check WireGuard Status

# On OpenWrt router
wg show

Expected output:

interface: wg_lab100
  public key: <key>
  private key: (hidden)
  listening port: 51920

peer: <peer-public-key>
  endpoint: 192.168.1.11:51920
  allowed ips: 172.16.100.1/32
  latest handshake: 30 seconds ago
  transfer: 5.2 KiB received, 4.8 KiB sent

2. Check VXLAN Interface

ip -d link show vxlan100

Expected output:

vxlan100@wg_lab100: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1450
    link/ether ... brd ff:ff:ff:ff:ff:ff
    vxlan id 100 dev wg_lab100 dstport 4789 ...

3. Check Bridge

bridge link show | grep br_lab100

Expected output:

3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> master br_lab100
4: vxlan100: <BROADCAST,MULTICAST,UP,LOWER_UP> master br_lab100

4. Check DHCP

# Show DHCP configuration
uci show dhcp.lab100

# Check active leases
cat /tmp/dhcp.leases

5. Check Firewall

# Show firewall zones
uci show firewall | grep lab100

# Check iptables rules
iptables -L -n -v | grep lab100

6. Test Connectivity

# Ping peer WireGuard IP
ping 172.16.100.1

# Test DHCP by connecting a lab device to eth1
# The device should get an IP in 10.100.0.0/24

Monitoring

Access Metrics

The OpenWrt gateway exposes Prometheus metrics on port 9586:

# From management server
curl http://192.168.1.21:9586/metrics/

Sample output:

# HELP wireguard_tunnel_up WireGuard tunnel status
# TYPE wireguard_tunnel_up gauge
wireguard_tunnel_up{lab="lab100",interface="wg_lab100",peer="abcd1234"} 1
...

View Logs

# On OpenWrt
logread | grep -E 'wireguard|vxlan|lab100'

# Follow logs in real-time
logread -f | grep -E 'wireguard|vxlan|lab100'

Troubleshooting

WireGuard Not Starting

# Check kernel modules
lsmod | grep wireguard

# Reload network
/etc/init.d/network reload

# Check logs
logread | grep wireguard

VXLAN Not Working

# Manually recreate VXLAN
/etc/init.d/vxlan-lab100 restart

# Check if WireGuard is up first
ip link show wg_lab100

DHCP Not Assigning IPs

# Restart dnsmasq
/etc/init.d/dnsmasq restart

# Check configuration
uci show dhcp.lab100

# Test with static IP first
ip addr add 10.100.0.50/24 dev br_lab100

Firewall Blocking Traffic

# Temporarily disable firewall for testing
/etc/init.d/firewall stop

# Check rules
iptables -L -n -v

# Re-enable
/etc/init.d/firewall start

Package Installation Failures

# Update package lists
opkg update

# Check available space
df -h

# Free up space if needed
opkg remove <unnecessary-packages>

Performance Tuning

For High-Throughput Labs

# Increase network buffers
sysctl -w net.core.rmem_max=16777216
sysctl -w net.core.wmem_max=16777216

# Make permanent
echo "net.core.rmem_max=16777216" >> /etc/sysctl.conf
echo "net.core.wmem_max=16777216" >> /etc/sysctl.conf

For Low-Resource Devices

# Reduce WireGuard keepalive
uci set network.wg_lab100_peer0.persistent_keepalive='60'
uci commit network

# Limit DHCP lease time
uci set dhcp.lab100.leasetime='1h'
uci commit dhcp

Backup and Recovery

Create Backup

# Full configuration backup
sysupgrade -b /tmp/backup-$(date +%Y%m%d).tar.gz

# Download backup
scp root@192.168.1.21:/tmp/backup-*.tar.gz ./

Restore Backup

# Upload backup
scp backup-20250130.tar.gz root@192.168.1.21:/tmp/

# Restore
sysupgrade -r /tmp/backup-20250130.tar.gz

Integration with Multi-Vendor Labs

OpenWrt gateways are fully compatible with Linux and MikroTik gateways in the same lab network:

# Example mixed gateway lab
lab_networks = {
  lab100 = {
    gateways = [
      { hostname = "gw1", type = "linux" },
      { hostname = "rt1", type = "mikrotik" },
      { hostname = "ap1", type = "openwrt" }  # All three work together!
    ]
  }
}

All three gateway types:

• ✅ Form full mesh WireGuard tunnels with each other
• ✅ Participate in VXLAN overlay
• ✅ Provide DHCP services (with split ranges or failover)
• ✅ Export metrics to centralized Prometheus
• ✅ Can be managed from same Ansible playbooks

Next Steps

• Enable road warrior access: Edit terraform.tfvars and set road_warrior = true
• Add monitoring dashboards in Grafana
• Configure alerting for tunnel failures
• Set up automated backups via cron

Support

For OpenWrt-specific issues:

• OpenWrt documentation: https://openwrt.org/docs
• Check /var/log/messages for system logs
• Use logread -f for real-time debugging
• Run health check: ansible-playbook playbooks/health-check.yml