VLAN Architecture on Proxmox: Linux VLAN-Aware Bridges (vmbr0) & Trunking
Executive Summary
Running multiple workload classes (management, general compute, Kubernetes clusters, and vulnerable test ranges) on a single flat subnet (/24) creates significant security risks and broadcast domain bloat.
Rather than creating dozens of separate physical network interfaces or disjointed virtual bridge devices (vmbr1, vmbr2, vmbr3), Proxmox VE natively supports 802.1q VLAN-aware Linux bridges. A single master bridge (vmbr0) acts as a virtual managed switch, allowing VMs to tag ingress/egress packets dynamically using virtual network interface (vNIC) VLAN tags.
This article details the architecture, /etc/network/interfaces configuration, trunking mechanics, and guest VM tag assignment for segmenting a homelab into 5 secure, isolated zones.
1. Architectural Overview & Network Topology
+----------------------------------------------------------------------------------------------------+
| PROXMOX 802.1Q VLAN-AWARE TOPOLOGY |
+----------------------------------------------------------------------------------------------------+
| Physical NIC: `enp5s0` |
| | |
| [ Linux Bridge: `vmbr0` (bridge-vlan-aware yes) ] |
| | |
| +-------------------+------------------+------------------+-------------------+ |
| | Tag: 10 | Tag: 20 | Tag: 30 | Tag: 40 | Tag: 50 |
| [ VLAN 10: MGMT ] [ VLAN 20: ROUTER ] [ VLAN 30: FLEET ] [ VLAN 40: K8S ] [ VLAN 50: LABS ] |
| 10.0.10.0/24 10.0.20.0/24 10.0.30.0/24 10.0.40.0/24 10.0.50.0/24 |
| - Proxmox Web/SSH - OPNsense / WAN - RHEL 9 Golden - K8s Control - Metasploitable3 |
| - IPMI / Switch - DNS / Kea DHCP - Ubuntu 24.04 - K8s Worker 1-3 - AD Range Lab |
+----------------------------------------------------------------------------------------------------+
Homelab Subnet Allocation Plan
| VLAN ID | Subnet CIDR | Zone / Purpose | Gateway / Router Interface | Egress Policy |
|---|---|---|---|---|
| VLAN 10 | 10.0.10.0/24 |
Management (MGMT) | 10.0.10.1 |
Restricted SSH / Proxmox Web UI (:8006) |
| VLAN 20 | 10.0.20.0/24 |
Core Network & Edge (NET) | 10.0.20.1 |
Edge Routing, DNS (AdGuard), Ingress |
| VLAN 30 | 10.0.30.0/24 |
Linux Systems & Fleet (FLEET) | 10.0.30.1 |
General outbound internet, NTP, Repos |
| VLAN 40 | 10.0.40.0/24 |
Kubernetes Workloads (K8S) | 10.0.40.1 |
Intra-cluster pod CIDRs, eBPF CNI |
| VLAN 50 | 10.0.50.0/24 |
Isolated Target Lab (LABS) | 10.0.50.1 (Optional) |
Host-only quarantine / Zero internet |
2. Step-by-Step Implementation
Step 1: Configuring /etc/network/interfaces on Proxmox Host
Edit /etc/network/interfaces on the Proxmox host to declare vmbr0 as bridge-vlan-aware yes:
auto lo
iface lo inet loopback
iface enp5s0 inet manual
# Physical uplink interface attached to bridge
auto vmbr0
iface vmbr0 inet manual
bridge-ports enp5s0
bridge-stp off
bridge-fd 0
bridge-vlan-aware yes
bridge-vids 2-4094
# VLAN-aware bridge acting as virtual switch
# Host Management Interface bound strictly to VLAN 10
auto vmbr0.10
iface vmbr0.10 inet static
address 10.0.10.250/24
gateway 10.0.10.1
dns-nameservers 10.0.20.53 1.1.1.1
comment "Proxmox Host Management IP"
Apply the network configuration without rebooting the host:
# Reload network interfaces safely
ifreload -a
Step 2: Assigning VLAN Tags to Guest VMs via Proxmox CLI
When creating or modifying VMs, assign the target VLAN tag directly to the virtual network adapter:
# 1. Assign Ubuntu Compute VM (VM 200) to VLAN 30 (Systems Fleet)
qm set 200 --net0 virtio,bridge=vmbr0,tag=30,firewall=1
# 2. Assign K8s Worker Node (VM 301) to VLAN 40 (Kubernetes)
qm set 301 --net0 virtio,bridge=vmbr0,tag=40,firewall=1
# 3. Assign Metasploitable 3 (VM 104) to VLAN 50 (Isolated Range)
qm set 104 --net0 virtio,bridge=vmbr0,tag=50,firewall=0
3. Deep Dive & Troubleshooting Analysis
+-----------------------------------------------------------------------------------+
| TROUBLESHOOTING MATRIX |
+-------------------------------------+---------------------------------------------+
| Symptom / Error | Root Cause & Resolution |
+-------------------------------------+---------------------------------------------+
| 1. Guest VM receives no DHCP lease | Tag mismatch on `vmbr0` or router trunking |
| on tagged VLAN interface | interface missing `bridge-vids` inclusion. |
+-------------------------------------+---------------------------------------------+
| 2. Inter-VLAN routing failure | Host bridge forwarding enabled, but router |
| | firewall rules drop cross-VLAN packets. |
+-------------------------------------+---------------------------------------------+
| 3. Packet leakage across VLANs | Ensure `bridge-vlan-aware yes` is set; |
| | otherwise tags are stripped or ignored. |
+-------------------------------------+---------------------------------------------+
4. Verification & Health Checks
Verify that the bridge VLAN filtering tables and guest port memberships are active:
# Display bridge VLAN filter table on Proxmox host
bridge vlan show
# Expected output snippet:
# port vlan-id
# enp5s0 1-4094
# vmbr0 10 PVID Egress Untagged
# tap200i0 30 PVID Egress Untagged
# tap301i0 40 PVID Egress Untagged
# tap104i0 50 PVID Egress Untagged
5. Key Technical Lessons & Next Steps
- VLAN-Aware vs Multiple Bridges: A single VLAN-aware
vmbr0drastically simplifies hypervisor configuration, reduces kernel overhead, and allows dynamic VLAN assignment without restarting VMs. - Management Isolation: Binding the hypervisor management IP to a tagged sub-interface (
vmbr0.10) keeps Proxmox management traffic completely separated from guest VM traffic. - Next Chapter:
02-virtual-router-firewall-setup.md— Virtualizing the Edge with OPNsense firewall rules and multi-zone inter-VLAN routing.