Proxmox Networking: vmbr0, VLAN-Aware Bridges, and Bonds
The configuration model rather than a click path. What the bridge is, which VLAN strategy to pick, whether Open vSwitch earns its place, and what the switch has to agree to before a bond works.
By William Bradshaw | August 20, 2026 | 11 min read
Most Proxmox networking guides walk you through the web interface, field by field. That works right up until something does not behave the way the form implied, and then you are looking at a configuration file you have never read, trying to work out which of the two things you are looking at is actually in effect.
This article goes the other way. Proxmox VE networking is Debian networking with a naming convention on top. Once the model is clear, the interface is obvious and the failure modes stop being mysterious. Everything below is organized around a decision you are actually making rather than a screen you are looking at.
If you are coming to this from a migration rather than a new build, the companion pieces are our VMware ESXi to Proxmox migration guide and the Proxmox VE 9.2 release notes, which cover what changed in the SDN stack. For the command-line side of diagnosing a network that is already broken, see our Linux networking troubleshooting reference.
What vmbr0 Actually Is
vmbr0 is a Linux bridge. Not a Proxmox invention, not a virtual switch product, just the kernel's software bridge with a name Proxmox picked. The vmbr prefix is a convention the Proxmox tooling recognizes, and the number distinguishes one bridge from another.
The part that trips people up is what happens to the physical NIC. Before the bridge exists, your host has an address on eno1. After the installer builds vmbr0, eno1 becomes a port on the bridge and carries no IP address at all. The management address moves onto the bridge. That is why the file looks the way it does:
auto lo
iface lo inet loopback
iface eno1 inet manual
auto vmbr0
iface vmbr0 inet static
address 192.168.10.20/24
gateway 192.168.10.1
bridge-ports eno1
bridge-stp off
bridge-fd 0
iface eno1 inet manual means bring the interface up but do not assign it an address. bridge-stp off and bridge-fd 0 disable spanning tree and set the forwarding delay to zero, which is the Proxmox default and is correct for a host with a single uplink. If you ever build a topology where two bridges could form a loop, that default is the first thing to revisit.
When a VM starts, Proxmox creates a tap interface and adds it to the bridge as another port. A container gets a veth pair instead. Either way the bridge behaves like an unmanaged switch inside the host: ports learn MAC addresses, frames get forwarded, and nothing filters anything unless you tell it to. That last clause is where the VLAN decision comes in.
Decision One: VLAN-Aware Bridge or One Bridge Per VLAN
There are two ways to get VLANs onto guests, and the Proxmox web interface will let you build either without commenting on the choice.
The traditional approach: one bridge per VLAN
Create a VLAN sub-interface on the physical NIC, then bridge it. Each VLAN gets its own bridge, and a guest picks its VLAN by picking which bridge to attach to.
auto vmbr10
iface vmbr10 inet manual
bridge-ports eno1.10
bridge-stp off
bridge-fd 0
auto vmbr20
iface vmbr20 inet manual
bridge-ports eno1.20
bridge-stp off
bridge-fd 0This works, and it is easy to reason about because each bridge carries exactly one VLAN. The cost shows up over time: every new VLAN is a host network change on every node in the cluster, and the interfaces file grows a stanza pair per VLAN per node.
The VLAN-aware approach: one bridge, tags on guests
Turn on VLAN filtering on a single bridge and declare which VLAN IDs it will carry. Guests then set a VLAN tag on their own interface.
auto vmbr0
iface vmbr0 inet static
address 192.168.10.20/24
gateway 192.168.10.1
bridge-ports eno1
bridge-stp off
bridge-fd 0
bridge-vlan-aware yes
bridge-vids 2-4094
Now a guest on VLAN 20 is a property of the guest, set as the VLAN Tag field on its network device or as tag=20 in the VM configuration. Adding VLAN 30 next month requires no host change at all, on any node.
Pick the VLAN-aware bridge unless you have a specific reason not to. It is fewer moving parts, it scales without touching the host, and it keeps a cluster's nodes identical, which matters because a guest that migrates to a node missing vmbr20 simply fails to start. The reasons to stay with per-VLAN bridges are narrow: you need different bridge-level settings per VLAN, or you have hit a driver or appliance that behaves badly behind a VLAN-filtering bridge.
The switch side is half the configuration
Neither approach works if the switch port feeding the host is an access port. Tagged frames arriving on an access port are typically dropped. The port needs to be a trunk (Cisco and Arista terminology) or to carry the VLANs tagged (HPE, Juniper and MikroTik terminology), and the VLAN the host's own management address lives on is usually the untagged or native VLAN on that port. Getting this half wrong produces the single most common Proxmox networking symptom: the host is reachable, and every tagged guest is not.
Decision Two: Linux Bridge or Open vSwitch
Open vSwitch is available on Proxmox after installing openvswitch-switch, and it introduces its own stanza types: OVSBridge, OVSBond, OVSIntPort and OVSPort.
The honest recommendation for most deployments is to stay on the Linux bridge. It is the default, it requires no additional package, it is maintained in the kernel, and it is what the Proxmox documentation and the overwhelming majority of community answers assume. When something breaks at two in the morning, the amount of directly applicable material available to you is not a trivial consideration.
Open vSwitch earns its place when you need something the Linux bridge does not do:
- OpenFlow control, because a controller is programming your forwarding rules.
- Per-port traffic shaping and QoS with more granularity than
tcapplied by hand. - Port mirroring to a remote collector via RSPAN or ERSPAN, which the Linux bridge cannot do natively.
- Overlay tunnels managed by the switch layer, where you want VXLAN or GRE endpoints handled as ports rather than as separate interfaces.
Note what is absent from that list: VLANs. The Linux bridge does VLANs perfectly well. Choosing Open vSwitch to get VLAN support is choosing a second networking model, an extra package in the boot path, and a different troubleshooting vocabulary, in exchange for a capability you already had.
Decision Three: Bonding, and What the Switch Has to Agree To
A bond combines two or more NICs into one logical interface. The critical point, and the one most often skipped, is that a bond is a negotiated arrangement. Some modes require the switch to be configured to match. Choosing a mode the switch does not share does not produce a clean failure. It produces intermittent packet loss, MAC addresses flapping between ports, and a switch log full of complaints, which reads like a cable fault and gets diagnosed as one.
802.3ad (LACP), when you control the switch
Mode 802.3ad negotiates a link aggregation group with the switch using LACP. Both ends must agree. The switch ports must be configured as an aggregation group, and on most platforms LACP must be active on at least one side.
auto bond0
iface bond0 inet manual
bond-slaves eno1 eno2
bond-mode 802.3ad
bond-miimon 100
bond-lacp-rate fast
bond-xmit-hash-policy layer3+4
auto vmbr0
iface vmbr0 inet static
address 192.168.10.20/24
gateway 192.168.10.1
bridge-ports bond0
bridge-stp off
bridge-fd 0
bridge-vlan-aware yes
bridge-vids 2-4094
bond-xmit-hash-policy deserves a moment, because it is the setting that determines whether aggregation delivers anything. A bond does not split a single conversation across links. It hashes each flow to one link. With the default layer2 policy the hash uses MAC addresses only, so all traffic between the host and one gateway lands on a single link no matter how many you bonded. layer2+3 adds IP addresses and layer3+4 adds ports, which spreads flows far better in a virtualization host serving many guests. Two 1 Gbps links do not produce a 2 Gbps transfer either way, but they do let two transfers run at 1 Gbps each.
active-backup, when you do not
Mode active-backup uses one link and holds the other in reserve. It requires nothing from the switch, which makes it the right answer in three common situations: the switch is unmanaged, the switch is managed by someone who is not you, or the two uplinks deliberately land on two unrelated switches for redundancy.
auto bond0
iface bond0 inet manual
bond-slaves eno1 eno2
bond-mode active-backup
bond-primary eno1
bond-miimon 100You give up aggregate throughput and you keep the failover. For a great many small deployments that is the correct trade, and it is considerably better than an LACP bond misconfigured against a switch that was never set up for it.
The stacked-switch case is worth naming separately. If your two switches present themselves as one logical device through MLAG, a stack, or a vendor equivalent, then 802.3ad across both switches is both possible and excellent: you get aggregation and survive losing an entire switch. If they are two independent switches, LACP across them will not work and active-backup is the design.
Applying Changes Without Locking Yourself Out
Here is the place where the web interface and the underlying file genuinely disagree, and knowing about it saves a support call.
When you edit networking in the Proxmox web interface, your changes are not written to /etc/network/interfaces. They are staged in /etc/network/interfaces.new. The running configuration is untouched until you press Apply Configuration. This is a safety feature, and it is also why a colleague can swear they made a change while ip a insists otherwise. If you want to see what is pending, read the .new file:
diff -u /etc/network/interfaces /etc/network/interfaces.new
From a shell, the equivalent of Apply Configuration is ifreload -a, provided by ifupdown2, which reloads the configuration in place and changes only what differs. That is a meaningful improvement on the old cycle of taking interfaces down and bringing them back up, but it is not a guarantee: if the change you are applying breaks the management interface, you lose the session at the moment it succeeds.
Before you apply anything on a remote host
- Have out-of-band access confirmed working first: IPMI, iDRAC, iLO, or physical console. Confirmed, not assumed.
- Keep a copy:
cp /etc/network/interfaces /root/interfaces.$(date +%F) - Change one thing at a time. A bond change and a VLAN change applied together give you two candidates when it breaks.
- On a cluster, apply to one node and verify before touching the second. Identical breakage across every node at once is a much longer evening.
The verification commands worth knowing, in the order you will want them:
# Which VLANs is the bridge actually filtering, per port
bridge vlan show
# Bridge ports and their state
bridge link show
# Bond status, mode, and per-slave link state
cat /proc/net/bonding/bond0
# Addresses and link state
ip -br addr show
bridge vlan show is the one to reach for first when a tagged guest cannot reach anything. It tells you what the bridge believes, which is frequently not what the web interface implied.
A Worked Configuration
Putting the three decisions together for a typical small cluster node: two NICs bonded with LACP to a managed switch, one VLAN-aware bridge, management on VLAN 10 as the native VLAN, and guests tagging their own VLANs.
auto lo
iface lo inet loopback
iface eno1 inet manual
iface eno2 inet manual
auto bond0
iface bond0 inet manual
bond-slaves eno1 eno2
bond-mode 802.3ad
bond-miimon 100
bond-lacp-rate fast
bond-xmit-hash-policy layer3+4
auto vmbr0
iface vmbr0 inet static
address 192.168.10.20/24
gateway 192.168.10.1
bridge-ports bond0
bridge-stp off
bridge-fd 0
bridge-vlan-aware yes
bridge-vids 2-4094
A guest on VLAN 20 needs no host-side change. Its network device carries tag=20 and attaches to vmbr0, which in the VM configuration file reads like this:
net0: virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=20On the switch, the two ports form one aggregation group, VLAN 10 is untagged or native on that group, and VLANs 20 and 30 are carried tagged. Those two sentences are as much a part of this configuration as the file above, and they are the half that lives in someone else's system.
One note on MTU if you are running Ceph or any storage replication across this bond: the MTU has to be consistent end to end, on the bond, on the bridge, on the guest interfaces, and on every switch port in the path. A jumbo-frame path with one 1500-byte hop in it fails in a way that looks intermittent, because small packets succeed and large ones do not. Set it deliberately or leave it at the default everywhere.
When to Reach for the SDN Stack Instead
Everything above is per-node configuration. Proxmox VE also ships an SDN layer that defines zones and virtual networks at the datacenter level and pushes the resulting configuration to every node, which is a different model rather than a nicer interface over the same one.
The per-node approach described here is the right starting point for a single node or a small cluster on a flat or VLAN-segmented network. Reach for SDN when you need overlay networks spanning nodes that do not share a layer 2 domain, when you want tenant isolation defined centrally rather than reproduced by hand on each node, or when the number of nodes makes keeping the interfaces files identical a real risk. The 9.2 release notes cover the recent additions to that stack.
The mistake worth avoiding is adopting SDN to solve a VLAN problem on a three-node cluster. A VLAN-aware bridge and a correctly configured trunk port solve that completely, and the resulting configuration is one file you can read.
Planning a Proxmox Network Design or Untangling One?
Bullium designs and operates Proxmox environments for SMB, township and fire-district clients, including the switch-side configuration that the host-side file depends on. We will review your current layout, work through the bridge, VLAN and bonding decisions against your actual switching, and hand back a configuration you can apply and understand. No commitment to engage further.
Related Reading
Proxmox VE 9.2 Release Notes
What changed in the release, including the additions to the SDN stack that sit above the per-node configuration described here.
Linux Networking Commands Reference
The diagnostic side, ordered by symptom: is the link up, can it route, why will it not resolve, where is the packet being dropped.
VMware ESXi to Proxmox Migration Guide
Where most people meet these decisions for the first time: translating a vSwitch and port group layout into bridges and VLAN tags.
Proxmox Hardening for SMB Production
Once the network is right, the rest of the host build: access control, updates, backups, and the firewall layer.
Network Topology Visualization
Documenting what you built, so the switch-side half of the configuration is written down somewhere other than one person's memory.
Proxmox VE Against VMware vSphere
The platform comparison, for readers still deciding rather than configuring.
Related Services
Network Design
VLAN scheme, switching layout, and the trunk configuration the virtualization hosts depend on.
Virtualization
Proxmox cluster design, migration from VMware, and ongoing operation.
Managed IT Services
For organizations that would rather the bridge, bond and trunk configuration were somebody else's pager.
IT Project Management
Cutover planning for network changes that touch every guest on a cluster at once.