Domain 2Networking & RoutingFOUNDATIONAL

VLAN Architecture on Proxmox: Linux VLAN-Aware Bridges (vmbr0) & Trunking

Architecture guide and configuration deep dive for implementing 802.1q VLAN-aware Linux bridges on Proxmox VE to segment management, compute, Kubernetes, and isolated security testbeds.

Domain: Domain 2: Networking & Routing•Updated: 2026-09-28
#Networking#VLAN#Proxmox#Linux Bridge#Trunking#802.1q#OPNsense

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

  1. VLAN-Aware vs Multiple Bridges: A single VLAN-aware vmbr0 drastically simplifies hypervisor configuration, reduces kernel overhead, and allows dynamic VLAN assignment without restarting VMs.
  2. Management Isolation: Binding the hypervisor management IP to a tagged sub-interface (vmbr0.10) keeps Proxmox management traffic completely separated from guest VM traffic.
  3. Next Chapter: 02-virtual-router-firewall-setup.md — Virtualizing the Edge with OPNsense firewall rules and multi-zone inter-VLAN routing.