From e0a64b1b9233d6718012511eacf492ce7b740365 Mon Sep 17 00:00:00 2001 From: kavren Date: Sun, 21 Dec 2025 19:20:07 -0500 Subject: [PATCH] docs: Add DHCP-based network isolation strategy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document OPNsense WAN configuration (pm4 vmbr1 with USB NIC) - Add DHCP-based isolation workaround for unmanaged Gigabyte switches - Plan subnet scheme: LAN (10.4.2.0/24), IoT (10.4.10.0/24), Guest (10.4.20.0/24) - Document planned OPNsense firewall rules for isolation - Update tasks with OPNsense migration and isolation steps - Fix Claude Code hooks settings (remove matcher from Stop hook) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .claude/settings.json | 1 - docs/CHANGELOG.md | 34 +++++++++++++++++++ docs/DECISIONS.md | 77 ++++++++++++++++++++++++++++++++---------- docs/INFRASTRUCTURE.md | 33 ++++++++++++++---- docs/README.md | 2 +- docs/TASKS.md | 43 +++++++++++++++++------ 6 files changed, 154 insertions(+), 36 deletions(-) diff --git a/.claude/settings.json b/.claude/settings.json index 8fcee56..59d3341 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -2,7 +2,6 @@ "hooks": { "Stop": [ { - "matcher": {}, "hooks": [ { "type": "command", diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 416346b..a883418 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -2,6 +2,40 @@ > **Purpose**: Historical record of all significant infrastructure changes +## 2025-12-21 + +### OPNsense WAN Configuration +- **pm4 vmbr1**: Created new bridge for OPNsense WAN interface + - Physical NIC: enx6c1ff76e4d47 (USB 2.5G adapter) + - Added to `/etc/network/interfaces` on pm4 + - Bridge is UP and connected to switch + +- **OPNsense VM 130**: Added second network interface + - net0: vmbr0 (LAN - 10.4.2.0/24) + - net1: vmbr1 (WAN - to AT&T modem) + - Ready for WAN cutover when AT&T modem is connected + +### Network Isolation Strategy +- **Decision**: Use DHCP-based isolation instead of VLANs + - Constraint: Gigabyte 10G switches are unmanaged (no VLAN support) + - Workaround: Assign different subnets via DHCP, use OPNsense firewall rules + +- **Planned Subnets**: + - Main LAN: 10.4.2.0/24 (existing) + - IoT (KavCorp-IOT): 10.4.10.0/24 + - Guest (KavCorp-Guest): 10.4.20.0/24 + +- **Planned Firewall Rules**: + - Block IoT/Guest → LAN + - Block Guest → IoT + - Allow Smart Home VMs → IoT + - Allow IoT/Guest → Internet + +- **Documentation Updated**: + - DECISIONS.md: Network isolation strategy and constraints + - INFRASTRUCTURE.md: pm4 bridges and subnet plan + - TASKS.md: OPNsense migration and isolation tasks + ## 2025-12-19 ### Network Upgrade Progress diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 3c7a1f2..cb115f9 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -41,37 +41,78 @@ ## Network Architecture -### VLAN Strategy (Planned) +### Network Isolation Strategy -**Decision**: Segment network into 4 VLANs -**See**: [NETWORK-UPGRADE-PLAN.md](NETWORK-UPGRADE-PLAN.md) +**Goal**: Isolate IoT (KavCorp-IOT) and Guest (KavCorp-Guest) WiFi networks from the main LAN, while allowing Smart Home VMs to access IoT devices. + +#### Constraint: Unmanaged Gigabyte Switches + +The Gigabyte 10G switches provide 10G backhaul and 2.5G PoE to UniFi APs, but they are **unmanaged** and don't support VLAN tagging. This means VLAN tags from UniFi APs are stripped when traffic passes through. + +**Workaround**: DHCP-based isolation (L3 firewall rules instead of L2 VLANs) + +#### IP Subnet Scheme + +| Subnet | Range | Purpose | DHCP Source | +|--------|-------|---------|-------------| +| Main LAN | 10.4.2.0/24 | Trusted devices, Proxmox hosts, services | OPNsense | +| IoT | 10.4.10.0/24 | KavCorp-IOT SSID devices | OPNsense or UniFi | +| Guest | 10.4.20.0/24 | KavCorp-Guest SSID devices | OPNsense or UniFi | + +#### OPNsense Firewall Rules (Planned) + +| Source | Destination | Action | Notes | +|--------|-------------|--------|-------| +| 10.4.10.0/24 (IoT) | 10.4.2.0/24 (LAN) | **Block** | Isolate IoT from LAN | +| 10.4.20.0/24 (Guest) | 10.4.2.0/24 (LAN) | **Block** | Isolate Guest from LAN | +| 10.4.20.0/24 (Guest) | 10.4.10.0/24 (IoT) | **Block** | Isolate Guest from IoT | +| Smart Home VMs | 10.4.10.0/24 (IoT) | **Allow** | Home Assistant → IoT devices | +| 10.4.10.0/24 (IoT) | Internet | **Allow** | IoT internet access | +| 10.4.20.0/24 (Guest) | Internet | **Allow** | Guest internet access | + +#### Limitations of DHCP Workaround + +- **Not true L2 isolation**: All traffic on same broadcast domain +- **IP spoofing possible**: Malicious device could use LAN IP range +- **Sufficient for**: IoT devices and guests (low threat actors) +- **Future upgrade**: Replace Gigabyte switches with managed 2.5G PoE switches for proper VLANs + +#### VLAN IDs (For Future Reference) | 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 | +| 10 | IoT | 10.4.10.0/24 | IoT devices, cameras, smart home | +| 20 | Guest | 10.4.20.0/24 | Guest WiFi, isolated | -**VLAN Tagging Methods**: -- WiFi: UniFi APs (SSID → VLAN mapping) -- Cameras: GS308EP (port-based VLAN) -- Containers: Proxmox (bridge VLAN tag) -- Wired PCs: Untagged (VLAN 1 via unmanaged switches) +### Router/Firewall -### Router/Firewall (Planned) +**Decision**: OPNsense VM 130 on pm4 (server closet) +**Status**: Deployed, pending WAN cutover -**Decision**: OPNsense VM on pm4 (server closet) **Reason**: - Free, full-featured firewall/router -- VLAN routing and inter-VLAN firewall rules +- Inter-subnet firewall rules for IoT/Guest isolation - IDS/IPS capability - pm4 is in server closet next to AT&T modem (avoids routing WAN over backhaul) -- pm4 has Intel I226-V (2.5G) + USB 3.1 for second NIC -**Network Interfaces**: -- WAN: USB 2.5G NIC (~$25) → AT&T modem -- LAN: Intel I226-V → GiGaPlus switch (VLAN trunk) +**Network Interfaces (VM 130)**: +| Interface | Bridge | Purpose | Status | +|-----------|--------|---------|--------| +| net0 | vmbr0 | LAN (10.4.2.0/24) | Configured | +| net1 | vmbr1 | WAN (to AT&T modem) | Configured | + +**pm4 Bridge Configuration**: +| Bridge | Physical NIC | Purpose | +|--------|--------------|---------| +| vmbr0 | eno1 (Intel I226-V) | LAN - all VMs/LXCs | +| vmbr1 | enx6c1ff76e4d47 (USB 2.5G) | WAN - OPNsense only | + +**HA/Failover Consideration**: +- Current: Single OPNsense on pm4 (SPOF) +- Future options: + 1. OPNsense HA with CARP (requires second USB NIC on another node) + 2. Keep current router as cold standby (swap cables if pm4 fails) **Alternative Considered**: Ubiquiti Dream Machine - Rejected due to cost and ecosystem lock-in diff --git a/docs/INFRASTRUCTURE.md b/docs/INFRASTRUCTURE.md index bb62160..be0ee94 100644 --- a/docs/INFRASTRUCTURE.md +++ b/docs/INFRASTRUCTURE.md @@ -45,7 +45,7 @@ | **Gitea** | 10.4.2.7:3000 | LXC 127 (pm4) | git.kavcorp.com | Built-in | | **Pi-hole** | 10.4.2.129 | LXC 103 (pm4) | pihole.kavcorp.com | Built-in | | **UniFi Controller** | 10.4.2.242:8443 | LXC 111 (pm4) | - | Built-in | -| **OPNsense (KavSense)** | 10.4.2.1 | VM 130 (pm4) | - | Built-in | +| **OPNsense (KavSense)** | 10.4.2.1 | VM 130 (pm4) | - | Built-in (net0: vmbr0/LAN, net1: vmbr1/WAN) | | **KavNas** | 10.4.2.13 | Synology NAS | - | NAS auth | ## Storage Architecture @@ -90,12 +90,33 @@ All `*.kavcorp.com` subdomains route through Traefik reverse proxy (10.4.2.10) for SSL termination and routing. -### Standard Bridge +### Bridges -**Bridge**: vmbr0 -**Physical Interface**: eno1 -**CIDR**: 10.4.2.0/24 -**Gateway**: 10.4.2.254 +#### All Nodes (vmbr0) +| Setting | Value | +|---------|-------| +| Bridge | vmbr0 | +| Physical Interface | eno1 | +| CIDR | 10.4.2.0/24 | +| Gateway | 10.4.2.254 | + +#### pm4 Only (vmbr1 - WAN for OPNsense) +| Setting | Value | +|---------|-------| +| Bridge | vmbr1 | +| Physical Interface | enx6c1ff76e4d47 (USB 2.5G NIC) | +| Purpose | WAN uplink to AT&T modem | +| Used by | VM 130 (OPNsense) net1 | + +### Planned Subnets (DHCP-based Isolation) + +| Subnet | Range | Purpose | Gateway | +|--------|-------|---------|---------| +| Main LAN | 10.4.2.0/24 | Trusted devices, Proxmox, services | 10.4.2.1 (OPNsense) | +| IoT | 10.4.10.0/24 | KavCorp-IOT WiFi devices | 10.4.10.1 (OPNsense) | +| Guest | 10.4.20.0/24 | KavCorp-Guest WiFi devices | 10.4.20.1 (OPNsense) | + +*Note: Using DHCP-based isolation due to unmanaged Gigabyte switches (no VLAN support). See DECISIONS.md for details.* ## Access & Credentials diff --git a/docs/README.md b/docs/README.md index b1799cb..cd71c2b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Documentation Index -> **Last Updated**: 2025-11-17 (Added Frigate and Foundry VTT to Traefik) +> **Last Updated**: 2025-12-21 (OPNsense WAN config, DHCP isolation strategy) > **IMPORTANT**: Update this index whenever you modify documentation files ## Quick Reference diff --git a/docs/TASKS.md b/docs/TASKS.md index d328e16..eb69755 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -1,6 +1,6 @@ # Current Tasks -> **Last Updated**: 2025-12-18 +> **Last Updated**: 2025-12-21 ## In Progress @@ -8,16 +8,35 @@ None currently. ## Pending -### Network Upgrade (Priority) -See [NETWORK-UPGRADE-PLAN.md](NETWORK-UPGRADE-PLAN.md) for full details. +### OPNsense Migration (Priority) +OPNsense VM 130 deployed on pm4 with vmbr1 (USB NIC) for WAN. -- [ ] Order hardware (2× GiGaPlus 10G PoE, 2× U7 Pro) -- [ ] Test Cat6 cable for 10G capability -- [ ] Install switches and verify 10G backhaul -- [ ] Deploy OPNsense VM on Elantris -- [ ] Deploy UniFi Controller LXC -- [ ] Configure VLANs and migrate services -- [ ] Remove Asus mesh routers +**Pending:** +- [ ] Connect USB NIC to AT&T modem (WAN cutover) +- [ ] Configure OPNsense WAN interface (DHCP or PPPoE from AT&T) +- [ ] Configure OPNsense as DHCP server for LAN (10.4.2.0/24) +- [ ] Test internet connectivity through OPNsense +- [ ] Update gateway on all devices from 10.4.2.254 → 10.4.2.1 + +### Network Isolation (DHCP Workaround) +Using DHCP-based isolation due to unmanaged Gigabyte switches. See DECISIONS.md. + +**Pending:** +- [ ] Configure OPNsense DHCP scope for IoT (10.4.10.0/24) +- [ ] Configure OPNsense DHCP scope for Guest (10.4.20.0/24) +- [ ] Configure UniFi to assign IoT/Guest clients to correct subnets (via DHCP options or UniFi DHCP) +- [ ] Create OPNsense firewall rules: + - Block IoT → LAN + - Block Guest → LAN + - Block Guest → IoT + - Allow Smart Home VMs → IoT +- [ ] Test isolation (IoT device cannot ping LAN device) +- [ ] Test Smart Home access (Home Assistant can reach IoT) + +### Future Network Upgrades +- [ ] Order hardware (2× GiGaPlus 10G PoE, 2× U7 Pro) for 10G backhaul +- [ ] Consider managed 2.5G PoE switches for proper VLAN support +- [ ] Consider OPNsense HA (CARP) with second USB NIC on another node ### Media Organization - [ ] Verify Jellyfin can see all imported media @@ -35,6 +54,10 @@ See [NETWORK-UPGRADE-PLAN.md](NETWORK-UPGRADE-PLAN.md) for full details. ## Completed (Recent) +- [x] Configured pm4 vmbr1 bridge with USB 2.5G NIC for OPNsense WAN +- [x] Added net1 (vmbr1) to OPNsense VM 130 +- [x] Documented DHCP-based network isolation strategy +- [x] Deployed UniFi Controller LXC 111 on pm4 - [x] Fixed SSH access between cluster nodes (pm2 can access all nodes) - [x] Fixed NZBGet permissions (UMask=0000 for 777 files) - [x] Fixed Sonarr permissions (chmod 777 on imports)