WireGuard VPN Integration for EQ Gateway

Overview

This implementation replaces ZeroTier with WireGuard for managed gateway VPN connectivity. WireGuard provides a simpler, more reliable VPN solution with better performance and fewer routing conflicts.

Note: For corporate VPN infrastructure details (network architecture, IP scheme, peer management), see eq-systems/infrastructure/wireguard. This document focuses on gateway deployment to the VPN.

Implementation Details

1. Configuration Generation

• Location: /etc/wireguard/eq-vpn.conf
• Naming: Uses “eq-vpn” prefix for clear identification vs other WG networks
• Dynamic IP Assignment: Gateway IP calculated from device serial (EQG-0001 → 172.20.1.2/32)
• Address Scope: Uses /32 to prevent subnet ownership conflicts

2. Key Management

• Private Key: /etc/wireguard/eq-vpn.key (0600 permissions)
• Public Key: /etc/wireguard/eq-vpn.pub (0644 permissions)
• Generation: Automatic during post-installation if keys don’t exist
• Security: Keys generated using WireGuard’s native tools

3. Service Integration

• Service Name: wg-quick@eq-vpn
• Auto-start: Enabled during installation
• Status Check: Verified during setup with clear logging

4. Network Architecture

Corporate LAN (172.16.0.0/23)
     ↕
Router (WireGuard Server)
     ↕
VPN Network (172.20.0.0/23)
     ↕
Gateways (172.20.1.x/32)

5. IP Assignment Scheme

The VPN IP is derived from the device model and serial number:

Examples:

Note: RPi serials are decimal (1-127), EQG serials are hex (0000-FFFF).

Fixed Routing Issues

Problem Solved

The original issue was asymmetric routing when gateways had both local LAN and WireGuard connectivity:

1. Packet arrives: Corporate LAN → eth0 (172.16.1.50)
2. Reply attempts: WireGuard interface (wg0) due to subnet ownership
3. Result: Connection failure

Solution: /32 Address Assignment

Using /32 instead of /23 prevents WireGuard from claiming subnet ownership:

# Before (problematic):
Address = 172.20.1.2/23  # Claims entire 172.20.0.0/23 subnet

# After (correct):
Address = 172.20.1.2/32  # Claims only single IP

Installation Flow

1. Package Installation

sudo dpkg -i eq-gateway_0.3.0~rc3_all.deb

2. Post-Installation Configuration

The system automatically:

1. Detects device serial from setup.yml
2. Calculates appropriate VPN IP
3. Generates WireGuard key pair
4. Creates configuration file
5. Enables and starts service
6. Displays public key for server configuration

3. Manual Steps

On router: Add the displayed public key to WireGuard server configuration.

Configuration Files

Gateway WireGuard Config (/etc/wireguard/eq-vpn.conf)

[Interface]
PrivateKey = <generated_private_key>
Address = 172.20.1.2/32

[Peer]
PublicKey = 9NEiqfcLdEX5HoyfmNgfjgNfJ5CjxGM6SYR3/ll6x20=
Endpoint = vpn.eq.systems:51820
AllowedIPs = 172.20.0.0/24
PersistentKeepalive = 25

Router Static Route

Target: 172.16.0.0/23 Interface: WG_VPN Purpose: Bridge VPN users to corporate LAN

Deployment Scenarios

Corporate LAN Testing

• Local Access: 172.16.1.50 (direct corporate network)
• VPN Access: 172.20.1.2 (via WireGuard tunnel)
• Both work simultaneously without routing conflicts

Field Deployment

• Only VPN Access: 172.20.1.2
• No corporate LAN: Clean, simple configuration
• Remote management: Full access via VPN tunnel

Dependencies

Package Dependencies

wireguard          # WireGuard kernel module and tools

System Requirements

• Linux kernel with WireGuard support
• wg command-line tools
• systemd for service management

Testing

Verify Installation

# Check service status
sudo systemctl status wg-quick@eq-vpn

# Check interface status
sudo wg show

# Test connectivity
ping 172.20.0.1  # Router

Key Files to Check

ls -la /etc/wireguard/eq-vpn.*
# Should show:
# -rw------- eq-vpn.conf
# -rw------- eq-vpn.key
# -rw-r--r-- eq-vpn.pub

Advantages Over ZeroTier

1. Simpler Routing: Point-to-point, no broadcast/ARP complexity
2. Better Performance: Kernel-level vs userspace
3. Fewer Conflicts: Minimal protocol, predictable behavior
4. Easier Debugging: Standard networking tools work
5. Corporate Friendly: No “shitstorm of ARP” issues

Troubleshooting

Common Issues

1. Keys not generated: Check wireguard package installation
2. Service fails: Check configuration syntax with wg-quick up eq-vpn
3. No connectivity: Verify router has matching public key
4. Routing loops: Ensure /32 address assignment

Log Locations

# Service logs
journalctl -u wg-quick@eq-vpn

# Installation logs
journalctl -u eq-gateway.postinst

# WireGuard status
sudo wg show

This implementation provides a clean, maintainable WireGuard VPN solution that works reliably in both corporate and field environments.