From e93030ba9b16e166ff6303869eb47e79066c04aa Mon Sep 17 00:00:00 2001 From: kavren Date: Sun, 21 Dec 2025 20:52:38 -0500 Subject: [PATCH] docs: Complete OPNsense VLAN and firewall configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Updated CHANGELOG with implemented VLAN config (VLANs 10, 20, 30) - Updated DECISIONS with complete VLAN architecture and firewall rules - Updated INFRASTRUCTURE with VLANs/subnets table and bridge configs - Updated TASKS to mark VLAN/firewall work complete, add UniFi VLAN tasks - Updated README last updated date đŸ¤– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/CHANGELOG.md | 40 ++++++++++++++++---------- docs/DECISIONS.md | 65 +++++++++++++++++++++++------------------- docs/INFRASTRUCTURE.md | 15 +++++----- docs/README.md | 2 +- docs/TASKS.md | 30 +++++++++---------- 5 files changed, 84 insertions(+), 68 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 5800d67..6938a90 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -28,26 +28,36 @@ - 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 +### OPNsense VLAN Configuration (Implemented) +- **VLANs Created** on vtnet0 (LAN interface): + - VLAN 10 (vlan01): Trusted network - 10.4.10.0/24 + - VLAN 20 (vlan02): IoT network - 10.4.20.0/24 + - VLAN 30 (vlan03): Guest network - 10.4.30.0/24 -- **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 +- **VLAN Interfaces Configured**: + - vlan01: 10.4.10.1/24 (gateway for Trusted) + - vlan02: 10.4.20.1/24 (gateway for IoT) + - vlan03: 10.4.30.1/24 (gateway for Guest) -- **Planned Firewall Rules**: - - Block IoT/Guest → LAN - - Block Guest → IoT - - Allow Smart Home VMs → IoT +- **DHCP Configured** on all interfaces: + - LAN: 10.4.2.100-200, DNS: 10.4.2.129 (Pi-hole) + - Trusted: 10.4.10.100-200 + - IoT: 10.4.20.100-200 + - Guest: 10.4.30.100-200 + +- **Firewall Rules Implemented**: + - Allow DNS: IoT/Guest → 10.4.2.129:53 (Pi-hole) + - Block IoT → LAN: 10.4.20.0/24 → 10.4.2.0/24 + - Block Guest → LAN: 10.4.30.0/24 → 10.4.2.0/24 + - Block Guest → IoT: 10.4.30.0/24 → 10.4.20.0/24 + - Allow Home Assistant → IoT: 10.4.2.62 → 10.4.20.0/24 - Allow IoT/Guest → Internet +- **Note**: Unmanaged Gigabyte switches pass VLAN tags through (they just don't understand them). UniFi APs tag traffic per SSID, OPNsense receives tagged traffic on VLAN interfaces. + - **Documentation Updated**: - - DECISIONS.md: Network isolation strategy and constraints - - INFRASTRUCTURE.md: pm4 bridges and subnet plan - - TASKS.md: OPNsense migration and isolation tasks + - DECISIONS.md: Complete VLAN architecture and firewall rules + - INFRASTRUCTURE.md: VLANs and subnets table, pm4 bridges ## 2025-12-19 diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index cb115f9..67caea7 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -45,45 +45,52 @@ **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 +**Status**: Implemented via OPNsense VLANs and firewall rules. -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. +#### VLAN Architecture -**Workaround**: DHCP-based isolation (L3 firewall rules instead of L2 VLANs) +Unmanaged Gigabyte switches pass VLAN tags through (they just don't understand them). UniFi APs tag traffic per SSID, OPNsense receives tagged traffic on VLAN interfaces. -#### IP Subnet Scheme +| VLAN | Interface | Subnet | Gateway | Purpose | +|------|-----------|--------|---------|---------| +| - | vtnet0 (LAN) | 10.4.2.0/24 | 10.4.2.1 | Infrastructure (Proxmox, core services) | +| 10 | vlan01 | 10.4.10.0/24 | 10.4.10.1 | Trusted (user devices) | +| 20 | vlan02 | 10.4.20.0/24 | 10.4.20.1 | IoT (KavCorp-IOT SSID) | +| 30 | vlan03 | 10.4.30.0/24 | 10.4.30.1 | Guest (KavCorp-Guest SSID) | -| 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 | +#### DHCP Configuration -#### OPNsense Firewall Rules (Planned) +All DHCP served by OPNsense: +- LAN: 10.4.2.100-200, DNS: 10.4.2.129 (Pi-hole) +- Trusted: 10.4.10.100-200, DNS: 10.4.2.129 +- IoT: 10.4.20.100-200, DNS: 10.4.2.129 +- Guest: 10.4.30.100-200, DNS: 10.4.2.129 -| 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 | +#### OPNsense Firewall Rules (Implemented) -#### Limitations of DHCP Workaround +| Rule | Source | Destination | Action | +|------|--------|-------------|--------| +| Allow DNS | IoT/Guest | 10.4.2.129:53 | Pass | +| Block IoT→LAN | 10.4.20.0/24 | 10.4.2.0/24 | Block | +| Block Guest→LAN | 10.4.30.0/24 | 10.4.2.0/24 | Block | +| Block Guest→IoT | 10.4.30.0/24 | 10.4.20.0/24 | Block | +| Allow Home Assistant→IoT | 10.4.2.62 | 10.4.20.0/24 | Pass | +| Allow IoT Internet | 10.4.20.0/24 | any | Pass | +| Allow Guest Internet | 10.4.30.0/24 | any | Pass | -- **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 +#### Network Segmentation Philosophy -#### VLAN IDs (For Future Reference) +| Network | Contains | Access Level | +|---------|----------|--------------| +| 10.4.2.0/24 (LAN) | Proxmox hosts, OPNsense, Pi-hole, Traefik, NAS | Full infrastructure access | +| 10.4.10.0/24 (Trusted) | User PCs, laptops | Full access to LAN and services | +| 10.4.20.0/24 (IoT) | Smart devices, cameras | Internet + DNS only, no LAN access | +| 10.4.30.0/24 (Guest) | Guest WiFi | Internet + DNS only, no local access | -| VLAN | Name | Subnet | Purpose | -|------|------|--------|---------| -| 1 | Default | 10.4.2.0/24 | Management, trusted PCs, Proxmox hosts | -| 10 | IoT | 10.4.10.0/24 | IoT devices, cameras, smart home | -| 20 | Guest | 10.4.20.0/24 | Guest WiFi, isolated | +#### Future Considerations + +- Consider adding a **Servers VLAN** to isolate services (media stack, Bitwarden) from infrastructure +- Consider OPNsense HA (CARP) with second USB NIC on another node for failover ### Router/Firewall diff --git a/docs/INFRASTRUCTURE.md b/docs/INFRASTRUCTURE.md index 9e88c34..abd95b5 100644 --- a/docs/INFRASTRUCTURE.md +++ b/docs/INFRASTRUCTURE.md @@ -108,15 +108,16 @@ All `*.kavcorp.com` subdomains route through Traefik reverse proxy (10.4.2.10) f | Purpose | WAN uplink to AT&T modem | | Used by | VM 130 (OPNsense) net1 | -### Planned Subnets (DHCP-based Isolation) +### VLANs and Subnets -| 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) | +| VLAN | Subnet | Gateway | DHCP Range | Purpose | +|------|--------|---------|------------|---------| +| - | 10.4.2.0/24 | 10.4.2.1 | .100-.200 | Infrastructure (Proxmox, core services) | +| 10 | 10.4.10.0/24 | 10.4.10.1 | .100-.200 | Trusted (user devices) | +| 20 | 10.4.20.0/24 | 10.4.20.1 | .100-.200 | IoT (KavCorp-IOT SSID) | +| 30 | 10.4.30.0/24 | 10.4.30.1 | .100-.200 | Guest (KavCorp-Guest SSID) | -*Note: Using DHCP-based isolation due to unmanaged Gigabyte switches (no VLAN support). See DECISIONS.md for details.* +*VLANs configured on OPNsense. UniFi APs tag traffic per SSID. See DECISIONS.md for firewall rules.* ## Access & Credentials diff --git a/docs/README.md b/docs/README.md index cd71c2b..38f268d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Documentation Index -> **Last Updated**: 2025-12-21 (OPNsense WAN config, DHCP isolation strategy) +> **Last Updated**: 2025-12-21 (OPNsense VLANs, firewall rules, network isolation) > **IMPORTANT**: Update this index whenever you modify documentation files ## Quick Reference diff --git a/docs/TASKS.md b/docs/TASKS.md index eb69755..5c14c3d 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -8,30 +8,23 @@ None currently. ## Pending -### OPNsense Migration (Priority) -OPNsense VM 130 deployed on pm4 with vmbr1 (USB NIC) for WAN. +### OPNsense WAN Cutover (Priority) +OPNsense VM 130 configured with VLANs and firewall rules. Ready for WAN cutover. **Pending:** -- [ ] Connect USB NIC to AT&T modem (WAN cutover) +- [ ] Connect USB NIC (vmbr1) to AT&T modem - [ ] 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. +### UniFi VLAN Configuration +VLANs configured on OPNsense. Need to configure UniFi APs to tag traffic. **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 +- [ ] Configure KavCorp-IOT SSID with VLAN 20 tag +- [ ] Configure KavCorp-Guest SSID with VLAN 30 tag - [ ] Test isolation (IoT device cannot ping LAN device) -- [ ] Test Smart Home access (Home Assistant can reach IoT) +- [ ] Test Smart Home access (Home Assistant can reach IoT devices) ### Future Network Upgrades - [ ] Order hardware (2Ă— GiGaPlus 10G PoE, 2Ă— U7 Pro) for 10G backhaul @@ -54,9 +47,14 @@ Using DHCP-based isolation due to unmanaged Gigabyte switches. See DECISIONS.md. ## Completed (Recent) +- [x] Configured OPNsense VLANs (10, 20, 30) on vtnet0 +- [x] Configured VLAN interfaces with IPs (10.4.10.1, 10.4.20.1, 10.4.30.1) +- [x] Configured DHCP on all VLAN interfaces +- [x] Implemented firewall rules for IoT/Guest isolation +- [x] Added Traefik routes for UniFi Controller and OPNsense +- [x] Resized Traefik LXC 104 rootfs from 2GB to 4GB - [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)