diff --git a/DOCS/REVERSE-MWAN-WIREGUARD.md b/DOCS/REVERSE-MWAN-WIREGUARD.md new file mode 100644 index 00000000..08192604 --- /dev/null +++ b/DOCS/REVERSE-MWAN-WIREGUARD.md @@ -0,0 +1,245 @@ +# Reverse MWAN WireGuard Design Specification + +**Status:** Design +**Version:** 0.1.0 +**Last Updated:** 2026-02-28 + +## Overview + +Allow WireGuard mesh peers to act as backup uplinks for multi-WAN failover. When the primary WAN connection fails, traffic routes through a WireGuard tunnel to a peer that has internet connectivity. + +## Use Cases + +1. **Remote Site Backup:** Office router loses WAN, fails over to home user's WireGuard peer +2. **Mobile Failover:** Fixed router fails over to mobile hotspot connected via WireGuard +3. **Mesh Redundancy:** Any mesh node can provide emergency uplink to others + +## Architecture + +``` + ┌─────────────────────────────────────────┐ + │ MESH NETWORK │ + │ │ + ┌────────────────┤ ├────────────────┐ + │ │ WireGuard Tunnels (always up) │ │ + │ │ │ │ +┌──▼──┐ ┌──▼──┐ ┌──▼──┐ ┌──▼──┐ +│Node │◄─────────►Node │ │Node │◄─────────►Node │ +│ A │ wg0 │ B │ │ C │ wg0 │ D │ +└──┬──┘ └──┬──┘ └──┬──┘ └──┬──┘ + │WAN1 │WAN1 │WAN1 │WAN1 + │(Primary) │(Primary) │(Primary) │(Primary) + ▼ ▼ ▼ ▼ + 🌐 🌐 ❌ 🌐 + (UP) (UP) (DOWN) (UP) + + ┌─────────────────────┐ + │ Node C Failover │ + │ │ + │ WAN1 → DOWN │ + │ wg0 (Node A) → UP │ + │ wg0 (Node B) → UP │ + │ wg0 (Node D) → UP │ + │ │ + │ mwan3 policy: │ + │ Use wg_nodeA │ + └─────────────────────┘ +``` + +## Components + +### 1. WireGuard Uplink Interface + +New interface type in WireGuard dashboard: `uplink` + +```uci +config interface 'wg_uplink_nodeA' + option proto 'wireguard' + option private_key '...' + list addresses '10.0.0.100/24' + # Mark as uplink-capable + option secubox_uplink '1' + option secubox_peer_id 'nodeA' + +config wireguard_wg_uplink_nodeA + option public_key '...' + option endpoint_host 'nodeA.example.com' + option endpoint_port '51820' + # Full tunnel for uplink mode + list allowed_ips '0.0.0.0/0' + list allowed_ips '::/0' + option persistent_keepalive '25' +``` + +### 2. mwan3 Integration + +```uci +# /etc/config/mwan3 + +config interface 'wan' + option enabled '1' + option family 'ipv4' + option reliability '2' + option track_method 'ping' + list track_ip '8.8.8.8' + list track_ip '1.1.1.1' + +config interface 'wg_uplink_nodeA' + option enabled '1' + option family 'ipv4' + option reliability '1' + option track_method 'ping' + # Track through tunnel + list track_ip '10.0.0.1' + # Lower weight = backup + option weight '10' + +config member 'wan_primary' + option interface 'wan' + option weight '100' + option metric '1' + +config member 'wg_uplink_nodeA_backup' + option interface 'wg_uplink_nodeA' + option weight '10' + option metric '10' + +config policy 'balanced' + list use_member 'wan_primary' + list use_member 'wg_uplink_nodeA_backup' +``` + +### 3. Uplink Capability Advertisement + +Peers advertise uplink capability via gossip: + +```json +{ + "type": "uplink_offer", + "peer_id": "nodeA", + "timestamp": "2026-02-28T12:00:00Z", + "capabilities": { + "bandwidth_mbps": 100, + "latency_ms": 20, + "wan_type": "fiber", + "available": true + }, + "endpoint": { + "host": "nodeA.example.com", + "port": 51820, + "public_key": "..." + } +} +``` + +### 4. CLI Commands + +```bash +# List available uplinks from mesh peers +wgctl uplink list + +# Add peer as uplink +wgctl uplink add + +# Remove peer uplink +wgctl uplink remove + +# Show uplink status +wgctl uplink status + +# Enable/disable mwan3 failover +wgctl uplink failover enable +wgctl uplink failover disable + +# Test uplink connectivity +wgctl uplink test + +# Set priority (lower = less preferred) +wgctl uplink priority +``` + +### 5. RPCD Methods + +``` +luci.wireguard-dashboard.uplink_list +luci.wireguard-dashboard.uplink_add { peer_id } +luci.wireguard-dashboard.uplink_remove { peer_id } +luci.wireguard-dashboard.uplink_status +luci.wireguard-dashboard.uplink_test { peer_id } +luci.wireguard-dashboard.uplink_set_priority { peer_id, weight } +``` + +## Implementation Plan + +### Phase 1: Core Infrastructure + +1. Add `secubox_uplink` option to WireGuard interface config +2. Create `wgctl uplink` command set +3. Implement uplink advertisement via gossip + +### Phase 2: mwan3 Integration + +1. Auto-generate mwan3 config for uplink interfaces +2. Implement connectivity tracking +3. Add failover policy generation + +### Phase 3: LuCI Dashboard + +1. Add "Uplink" column to peers view +2. Create uplink configuration modal +3. Add failover status indicator + +### Phase 4: Advanced Features + +1. Bandwidth-aware peer selection +2. Latency-based routing +3. Cost/metering awareness + +## Configuration + +### UCI Options + +```uci +config wireguard-uplink 'uplink' + option enabled '1' + # Auto-failover when primary WAN down + option auto_failover '1' + # Minimum uplinks to maintain + option min_uplinks '2' + # Health check interval (seconds) + option check_interval '30' + # Failover timeout (seconds) + option failover_timeout '10' + # Prefer peers with lowest latency + option prefer_latency '1' +``` + +## Security Considerations + +1. **Trust:** Only mesh peers with valid master-link trust can be uplinks +2. **Traffic Inspection:** Uplink peers can see outbound traffic +3. **Bandwidth:** Uplinks should set rate limits to prevent abuse +4. **DNS:** DNS requests should also route through uplink tunnel + +## Dependencies + +- `mwan3` - Multi-WAN failover +- `wireguard-tools` - WireGuard management +- `secubox-p2p` - Gossip protocol for uplink discovery +- `secubox-master-link` - Peer trust verification + +## Files + +| File | Purpose | +|------|---------| +| `/usr/lib/wireguard-dashboard/uplink.sh` | Uplink management library | +| `/etc/config/wireguard-uplink` | UCI configuration | +| `/etc/mwan3.d/wireguard-uplinks.conf` | Generated mwan3 config | +| `/var/run/wireguard-uplinks.json` | Runtime uplink state | + +## See Also + +- [WireGuard Dashboard](../package/secubox/luci-app-wireguard-dashboard/README.md) +- [Master Link Trust](../package/secubox/secubox-master-link/README.md) +- [P2P Gossip Protocol](../package/secubox/secubox-p2p/README.md) +- [OpenWrt mwan3 Documentation](https://openwrt.org/docs/guide-user/network/wan/multiwan/mwan3)