wireguard-lab-overlay/OPENWRT_CHANGELOG.md

OpenWrt Integration - Change Log

What's New

OpenWrt Gateway Support

This version adds complete support for OpenWrt routers as lab network gateways, making them fully interoperable with Linux VMs and MikroTik routers.

New Ansible Roles

1. openwrt-common - System preparation and package installation
2. openwrt-wireguard - UCI-based WireGuard configuration
3. openwrt-vxlan - VXLAN interface setup with FDB management
4. openwrt-bridge - Bridge configuration via UCI
5. openwrt-dhcp - dnsmasq DHCP server configuration
6. openwrt-firewall - Automatic firewall zone creation and isolation
7. openwrt-monitoring - Lightweight shell-based Prometheus exporter

Key Features

• UCI Configuration: All settings managed via OpenWrt's UCI system
• Auto Package Installation: Automatic installation of required packages:
  • wireguard-tools
  • kmod-wireguard
  • kmod-vxlan
  • ip-full
  • tcpdump
• Firewall Isolation: Each lab network gets isolated firewall zone
• Metrics Export: Lightweight shell script exporter on port 9586
• Full Mesh Support: OpenWrt gateways mesh with Linux and MikroTik
• DHCP Modes: Support for both simple (split range) and failover simulation

Architecture Support

• x86_64: PC Engines APU, Protectli Vault, generic x86
• ARM: GL.iNet, Turris Omnia, Raspberry Pi
• MIPS: Various TP-Link, Ubiquiti models (device-dependent)

Updated Files

Terraform:

• terraform/outputs.tf - Added openwrt_gateways inventory group
• terraform/terraform.tfvars.example - Added OpenWrt gateway examples

Ansible:

• ansible/playbooks/site.yml - Added OpenWrt configuration block
• ansible/inventory/hosts.yml - Added openwrt_gateways group
• ansible/inventory/group_vars/openwrt_gateways.yml - OpenWrt-specific vars

Documentation:

• docs/openwrt-setup.md - Complete OpenWrt setup guide
• docs/gateway-comparison.md - Comparison of all three gateway types
• README.md - Updated with OpenWrt references

Compatibility

• OpenWrt Version: 23.05 or later (stable releases)
• Minimum Hardware: 128MB RAM, 128MB flash (256MB+ recommended)
• Tested Platforms: x86_64, ARM (Cortex-A series)
• Interoperability: Fully compatible with Linux and MikroTik gateways

Usage Example

# 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-linux1"
        type      = "linux"
        mgmt_ip   = "192.168.1.11"
        api_port  = 22
        lab_if    = "eth1"
        dhcp_role = "primary"
      },
      {
        hostname  = "lab100-openwrt1"
        type      = "openwrt"      # ← OpenWrt gateway
        mgmt_ip   = "192.168.1.14"
        api_port  = 22
        lab_if    = "eth1"         # Adjust to your OpenWrt interface
        dhcp_role = "secondary"
      }
    ]
  }
}

Deploy:

./deploy.sh

Testing Checklist

After deploying an OpenWrt gateway:

• WireGuard tunnel established: wg show
• VXLAN interface up: ip -d link show vxlan100
• Bridge operational: bridge link show
• DHCP serving: cat /tmp/dhcp.leases
• Firewall zone created: uci show firewall | grep lab100
• Metrics exported: curl http://<openwrt-ip>:9586/metrics/
• Can ping peer WireGuard IPs
• Lab devices getting DHCP addresses

Known Limitations

1. DHCP Failover: OpenWrt uses simulated failover (split ranges), not true ISC DHCP failover protocol
2. Resource Constraints: Performance varies significantly based on hardware
3. Package Availability: Some older/exotic architectures may lack VXLAN support
4. Web UI: No LuCI integration (CLI/Ansible only)

Migration Notes

If upgrading from a version without OpenWrt support:

1. Update Terraform: terraform init -upgrade
2. Run Terraform plan to see new inventory structure
3. No changes needed for existing Linux/MikroTik gateways
4. Add OpenWrt gateways incrementally

Performance Expectations

Hardware Class	WireGuard Throughput	Concurrent Devices
x86_64 (modern)	500 Mbps - 2 Gbps	50-100+
ARM (Cortex-A)	100-300 Mbps	20-50
MIPS (consumer)	50-150 Mbps	10-20

Support

See:

• docs/openwrt-setup.md for detailed setup instructions
• docs/gateway-comparison.md for choosing gateway types
• docs/operations.md for troubleshooting

Breaking Changes

None - fully backward compatible with existing deployments.

Next Features (Future)

• LuCI web UI integration (optional)
• Support for OpenWrt snapshot builds
• WiFi AP mode integration for wireless lab devices
• Advanced QoS policies for lab networks