proxmox-infra/docs/NETWORK-UPGRADE-PLAN.md

# Network Upgrade Plan

> **Status**: Planning
> **Created**: 2025-12-18
> **Goal**: Replace Asus mesh with UniFi APs + 10G backhaul + VLAN segmentation

## Overview

Upgrade from consumer Asus mesh WiFi to enterprise-grade UniFi APs with proper VLAN segmentation, 10G backhaul between floors, and OPNsense for routing/firewall.

## Hardware Purchase List

| Item | Qty | Unit Price | Total |
|------|-----|------------|-------|
| GiGaPlus 6-Port 10G PoE Switch | 2 | $101 | $202 |
| UniFi U7 Pro AP | 2 | $189 | $378 |
| USB 2.5G NIC (for OPNsense WAN) | 1 | ~$25 | $25 |
| **Total** | | | **~$605** |

### USB 2.5G NIC Options
- Plugable USBC-E2500 (~$30)
- Cable Matters 2.5G USB-C (~$25)
- UGREEN 2.5G USB-C (~$20)

### GiGaPlus Switch Specs
- 4× 2.5G Base-T PoE ports
- 2× 10G RJ45 ports
- 60Gbps switching capacity
- Unmanaged with VLAN mode

### UniFi U7 Pro Specs
- WiFi 7, tri-band + 6GHz
- 2.5G PoE uplink
- 1,500 ft² coverage
- Multiple SSIDs per VLAN

## Existing Hardware (Keep)

| Item | Location | Purpose |
|------|----------|---------|
| UniFi U6 Enterprise AP | Server closet | Upstairs WiFi |
| Netgear GS308EP | Server closet | Cameras (managed, VLAN capable) |
| Cat 6 cable (floors) | Basement ↔ Server closet | 10G backhaul |

## Physical Topology

```
                          AT&T Modem
                               │
                               │ 2.5G (ethernet)
                               ▼
┌──────────────────────────────────────────────────────────┐
│ pm4 (Server Closet) - OPNsense Host                      │
│                                                          │
│   [USB 3.1 2.5G NIC] ◄── AT&T Modem (WAN)               │
│   [Intel I226-V 2.5G] ──► GiGaPlus switch (LAN)         │
│                                                          │
│   OPNsense VM:                                           │
│   - vtnet0 (WAN) ← USB NIC                               │
│   - vtnet1 (LAN) ← Intel NIC, VLAN trunk                │
└──────────────────────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────┐
│ SERVER CLOSET - GiGaPlus 10G PoE                         │
│                                                          │
│  [10G RJ45] ─────────── Cat6 to basement                 │
│  [10G RJ45] spare                                        │
│  [2.5G PoE] pm4 (OPNsense LAN)                           │
│  [2.5G PoE] U6 Enterprise AP (upstairs coverage)         │
│  [2.5G PoE] spare                                        │
│  [2.5G PoE] spare                                        │
│                                                          │
│  Netgear GS308EP ◄── cameras via attic runs              │
│  Unmanaged switches ◄── wired PCs                        │
└──────────────────────────────────────────────────────────┘
              │
              │ 10G Cat6 backhaul
              ▼
┌──────────────────────────────────────────────────────────┐
│ BASEMENT - GiGaPlus 10G PoE                              │
│                                                          │
│  [10G RJ45] ◄── from server closet                       │
│  [10G RJ45] spare (future Elantris 10G NIC)              │
│  [2.5G PoE] U7 Pro AP (basement coverage)                │
│  [2.5G PoE] U7 Pro AP (main floor - long run)            │
│  [2.5G PoE] Elantris (Proxmox node)                      │
│  [2.5G PoE] KavNas (Synology)                            │
└──────────────────────────────────────────────────────────┘
```

## WiFi Coverage

| Floor | AP | Model |
|-------|-----|-------|
| Upstairs (3rd) | Server closet | U6 Enterprise (existing) |
| Main (2nd) | Long run from basement | U7 Pro |
| Basement (1st) | Local | U7 Pro |

## VLAN Architecture

### VLAN Assignments

| VLAN | Name | Subnet | Purpose |
|------|------|--------|---------|
| 1 | Default | 10.4.2.0/24 | Management, trusted PCs, Proxmox hosts |
| 10 | Servers | 10.4.10.0/24 | Server containers, NAS |
| 20 | IoT | 10.4.20.0/24 | Cameras, smart home, Home Assistant |
| 30 | Guest | 10.4.30.0/24 | Guest WiFi, isolated |

### WiFi SSIDs

| SSID | VLAN | Purpose |
|------|------|---------|
| KavCorp | 1 | Trusted devices (phones, laptops, PCs) |
| KavCorp-IoT | 20 | Smart home WiFi devices |
| KavCorp-Guest | 30 | Guest access (rate limited, internet only) |

### Device VLAN Assignments

| Device Type | VLAN | How Tagged |
|-------------|------|------------|
| WiFi - trusted | 1 | UniFi AP (SSID) |
| WiFi - IoT | 20 | UniFi AP (SSID) |
| WiFi - guest | 30 | UniFi AP (SSID) |
| Cameras | 20 | GS308EP (port-based) |
| Wired PCs | 1 | Untagged (unmanaged switches) |
| Proxmox containers | varies | Proxmox VLAN tag |

## Proxmox VLAN Configuration

### Enable VLAN-aware bridge on Elantris

```bash
# /etc/network/interfaces
auto vmbr0
iface vmbr0 inet static
    address 10.4.2.14/24
    gateway 10.4.2.254
    bridge-ports eno1
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes
```

### Container VLAN Assignments

| Container | VLAN | Subnet | Reason |
|-----------|------|--------|--------|
| OPNsense | trunk | all | Router - needs all VLANs |
| Traefik | 1 | 10.4.2.x | Reverse proxy - reaches all |
| Pi-hole | 1 | 10.4.2.x | DNS for all VLANs |
| Sonarr/Radarr/*arr | 10 | 10.4.10.x | Server VLAN |
| Jellyfin | 10 | 10.4.10.x | Server VLAN |
| Frigate | 20 | 10.4.20.x | Needs camera access |
| Home Assistant | 20 | 10.4.20.x | IoT control |
| UniFi Controller | 1 | 10.4.2.x | AP management |

### LXC VLAN Tag Example

```bash
# Per container in Proxmox GUI or CLI:
pct set <vmid> -net0 name=eth0,bridge=vmbr0,tag=10

# Or in /etc/pve/lxc/<vmid>.conf:
net0: name=eth0,bridge=vmbr0,tag=10,type=veth
```

## OPNsense VM Setup

### Location
- **Host**: pm4 (server closet, next to AT&T modem)
- **Resources**: 2 vCPU, 2-4GB RAM
- **Why pm4**: Proximity to AT&T modem, avoids routing WAN over backhaul

### Network Interfaces

| Physical | Device | Purpose |
|----------|--------|---------|
| USB 2.5G NIC | enxXXXXXX | WAN (AT&T modem) |
| Intel I226-V | eno1/vmbr0 | LAN (to GiGaPlus switch) |

### OPNsense Interface Config

| Interface | VLAN | IP | Role |
|-----------|------|-----|------|
| vtnet0 (USB) | - | DHCP from AT&T | WAN |
| vtnet1.1 | 1 | 10.4.2.1 | LAN - Management |
| vtnet1.10 | 10 | 10.4.10.1 | LAN - Servers |
| vtnet1.20 | 20 | 10.4.20.1 | LAN - IoT |
| vtnet1.30 | 30 | 10.4.30.1 | LAN - Guest |

### Proxmox Setup on pm4

**Important**: NICs are NOT passed through directly. They use bridges so other LXCs can share.

```
USB 2.5G NIC ──► vmbr1 (WAN bridge) ──► OPNsense WAN only

Intel I226-V ──► vmbr0 (LAN bridge) ──► OPNsense LAN
                       │
                       ├──► Pi-hole (LXC 103)
                       ├──► Vaultwarden (LXC 125)
                       ├──► Immich (LXC 126)
                       ├──► Gitea (LXC 127)
                       └──► GiGaPlus switch (physical uplink)
```

1. Create WAN bridge for USB NIC:
   ```bash
   # /etc/network/interfaces on pm4

   # Existing LAN bridge (Intel NIC) - shared by all LXCs
   auto vmbr0
   iface vmbr0 inet manual
       bridge-ports eno1
       bridge-stp off
       bridge-fd 0
       bridge-vlan-aware yes

   # New WAN bridge (USB NIC) - OPNsense only
   auto vmbr1
   iface vmbr1 inet manual
       bridge-ports enxXXXXXX  # USB NIC device name (check with `ip link`)
       bridge-stp off
       bridge-fd 0
   ```

2. OPNsense VM network config:
   - net0: bridge=vmbr1 (WAN - USB NIC)
   - net1: bridge=vmbr0 (LAN - shared Intel NIC, VLAN-aware)

3. Other LXCs on pm4 stay on vmbr0:
   - No changes needed to LXC network config
   - Just update gateway from Asus router IP → OPNsense (10.4.2.1)

### Firewall Rules (High Level)

| From | To | Action |
|------|-----|--------|
| Trusted (1) | Any | Allow |
| Servers (10) | Internet | Allow |
| Servers (10) | Trusted (1) | Allow (for access) |
| IoT (20) | Internet | Allow |
| IoT (20) | Servers (10) | Block (except Frigate, HA) |
| IoT (20) | Trusted (1) | Block |
| Guest (30) | Internet | Allow (rate limit) |
| Guest (30) | Any internal | Block |

## UniFi Controller

### Deployment Options

1. **LXC on Proxmox** (recommended) - Free, uses existing hardware
2. **Cloud Gateway** - Extra cost, dedicated hardware

### LXC Setup (via helper script)

```bash
# On Proxmox node:
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/unifi.sh)"
```

## Implementation Steps

### Phase 1: Hardware
- [ ] Order 2× GiGaPlus 10G PoE switches
- [ ] Order 2× UniFi U7 Pro APs
- [ ] Test Cat6 cable for 10G capability

### Phase 2: Switches
- [ ] Install GiGaPlus switch in server closet
- [ ] Install GiGaPlus switch in basement
- [ ] Connect 10G backhaul
- [ ] Verify 10G link speed

### Phase 3: OPNsense
- [ ] Create OPNsense VM on Elantris
- [ ] Configure WAN (AT&T modem)
- [ ] Configure VLAN interfaces
- [ ] Set up basic firewall rules
- [ ] Test internet connectivity

### Phase 4: UniFi
- [ ] Deploy UniFi Controller LXC
- [ ] Adopt U6 Enterprise
- [ ] Install U7 Pro APs
- [ ] Adopt U7 Pro APs
- [ ] Configure SSIDs with VLAN tags

### Phase 5: VLAN Migration
- [ ] Configure GS308EP camera ports for VLAN 20
- [ ] Update Proxmox bridge to VLAN-aware
- [ ] Migrate containers to appropriate VLANs
- [ ] Test inter-VLAN routing
- [ ] Verify firewall rules

### Phase 6: Cleanup
- [ ] Remove Asus mesh routers
- [ ] Update documentation
- [ ] Test all services

## Rollback Plan

Keep Asus mesh routers available during migration. If issues arise:
1. Disconnect GiGaPlus switches
2. Reconnect Asus routers
3. Restore original network config

## Notes

- GiGaPlus switches are unmanaged - VLAN tagging happens at endpoints (APs, GS308EP, Proxmox)
- Wired PCs on unmanaged switches will stay on VLAN 1 (trusted)
- Pi-hole should remain accessible from all VLANs for DNS
- Consider adding 10G NIC to Elantris later for direct 10G connection