docs: Add Reverse MWAN WireGuard design specification
Design spec for WireGuard mesh peers as backup uplinks: - Architecture for multi-WAN failover over WireGuard tunnels - mwan3 integration plan for automatic failover - Uplink capability advertisement via gossip - CLI commands (wgctl uplink) and RPCD methods - 4-phase implementation plan Implementation planned for v2 release. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
b542ac7d3c
commit
ecf0ccb9fb
245
DOCS/REVERSE-MWAN-WIREGUARD.md
Normal file
245
DOCS/REVERSE-MWAN-WIREGUARD.md
Normal file
@ -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 <peer_id>
|
||||||
|
|
||||||
|
# Remove peer uplink
|
||||||
|
wgctl uplink remove <peer_id>
|
||||||
|
|
||||||
|
# Show uplink status
|
||||||
|
wgctl uplink status
|
||||||
|
|
||||||
|
# Enable/disable mwan3 failover
|
||||||
|
wgctl uplink failover enable
|
||||||
|
wgctl uplink failover disable
|
||||||
|
|
||||||
|
# Test uplink connectivity
|
||||||
|
wgctl uplink test <peer_id>
|
||||||
|
|
||||||
|
# Set priority (lower = less preferred)
|
||||||
|
wgctl uplink priority <peer_id> <weight>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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)
|
||||||
Loading…
Reference in New Issue
Block a user