Proxmox Networking: Bridges, VLANs, and Bonding
A practical guide to how Proxmox VE wires guests to the physical network using Linux bridges, VLAN-aware bridging, and NIC bonding, with verified /etc/network/interfaces syntax for a redundant, segmented setup.
/etc/network/interfaces, with no proprietary virtual switch underneath.
A Linux bridge acting as a virtual switch inside the host, connecting physical NICs to guest network devices.
Turns a single bridge into an 802.1Q trunk, so each guest’s VLAN tag is set per virtual NIC instead of per bridge.
A Linux bonding interface that aggregates two or more physical NICs for redundancy or throughput.
What Is Proxmox Networking?
Proxmox VE does not ship its own virtual switch. It configures the same Linux networking stack any Debian server uses — bridges, VLAN interfaces, and bonds — through /etc/network/interfaces, and exposes that configuration through the web GUI so most changes never require hand-editing the file directly.
Think of a Linux bridge as a small physical switch that lives inside the hypervisor host itself. A physical NIC plugs into one port of that switch, and every VM or container network device plugs into another port. Frames arriving on the physical NIC get forwarded to whichever guest port their destination MAC address is learned on, exactly like an unmanaged switch on a desk.
The default bridge is named vmbr0, following the vmbr[N] naming convention Proxmox uses for bridges (any alphanumeric name up to 10 characters is technically valid, but the installer and most guides stick to vmbr0, vmbr1, and so on). Physical interface names follow systemd’s predictable naming scheme on current installs — eno1 for the first on-board NIC, enp3s0f1 for a NIC on PCI bus 3 — rather than the older eth0-style names still seen on older systems.
/etc/network/interfaces.new first. Running ifreload -a applies them live with no reboot, courtesy of ifupdown2, which has been the default network stack since Proxmox VE 7.0. A reboot applies the same staged file through the pvenetcommit systemd service if you never run ifreload yourself.
Why VLAN-Aware Bridges Instead of One Bridge per VLAN?
Before VLAN-aware bridges, isolating guest traffic by VLAN meant creating a separate tagged sub-interface and bridge pair for every VLAN — vmbr0.10, vmbr0.20, and so on — each with its own bridge device. That works, but it means every new VLAN is a host-level networking change.
A VLAN-aware bridge collapses all of that into one bridge acting as an 802.1Q trunk. The bridge itself carries every tagged VLAN on the wire, and the VLAN tag is assigned per guest, in the VM or container’s network device settings, using the VLAN Tag field. Adding a guest to a new VLAN becomes a per-VM setting instead of a host reconfiguration.
A single vmbr0 carries the full VLAN range instead of one bridge device per VLAN.
Set the VLAN once per VM network device in the GUI — no host-side interface changes to add a guest to a VLAN.
No per-VLAN sub-interface to create, no extra bridge-fd/bridge-stp settings to repeat for each one.
Host-level tagged sub-interfaces still have a place: if the host itself needs an IP address on a specific VLAN — a dedicated storage or management VLAN, for example — a vmbr0.20-style interface addressed directly is still the documented pattern for that one case. VLAN-aware bridging is specifically about how guest traffic gets tagged, not host traffic.
Why Redundancy Matters — Bonding NICs
A Proxmox node with a single physical NIC has a single point of failure for everything that node does: guest network traffic, storage traffic if using NFS or iSCSI, and cluster communication if the node is part of a cluster. bond0 aggregates two or more physical NICs into one logical interface so the loss of a cable, switch port, or NIC does not take the node off the network.
This matters more on a clustered node than a standalone one. Corosync, the cluster membership and quorum engine covered in the Proxmox Cluster Setup post, expects low-latency connectivity between nodes to keep quorum. A flapping or dead link on an unbonded NIC can knock a node out of quorum even though the node itself is healthy — bonding turns a single link failure into a non-event instead of an outage.
Configuration
The example below combines a bonded pair of NICs with a VLAN-aware bridge on top — the two patterns from the sections above used together. It configures bond0 from two physical NICs in active-backup mode, then bridges bond0 as a VLAN-aware trunk.
# /etc/network/interfaces
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-miimon 100
bond-mode active-backup
auto vmbr0
iface vmbr0 inet static
address 10.10.10.5/24
gateway 10.10.10.1
bridge-ports bond0
bridge-stp off
bridge-fd 0
bridge-vlan-aware yes
bridge-vids 2-4094| Line | Purpose |
|---|---|
iface eno1/eno2 inet manual |
Declares the physical NICs without their own IP addresses, since they only exist to be bond slaves. |
bond-slaves eno1 eno2 |
Lists the physical NICs to aggregate into bond0. |
bond-miimon 100 |
Polls link state every 100ms so a dead NIC is detected and failed over quickly. |
bond-mode active-backup |
Only one slave carries traffic at a time; the standby takes over on failure. Needs no switch-side configuration. |
bridge-ports bond0 |
Attaches the bond, not an individual NIC, as the bridge’s uplink. |
bridge-stp off / bridge-fd 0 |
Disables Spanning Tree Protocol and zeroes the forwarding delay — standard on a Proxmox bridge with no downstream switch loop to guard against. |
bridge-vlan-aware yes |
Turns vmbr0 into an 802.1Q trunk so it can carry multiple tagged VLANs. |
bridge-vids 2-4094 |
Allows VLAN IDs 2 through 4094 to pass through the bridge (VLAN 1 and the reserved 4095 are excluded). |
eno1 and eno2 support LACP (802.3ad) and are configured as a matching link-aggregation group, bond-mode 802.3ad gives active/active throughput instead of active/passive failover. Without switch-side LACP configuration, 802.3ad will not come up correctly — active-backup is the safe default when in doubt.
Scripts / Commands
Use the commands below to apply staged network changes, inspect bond and bridge state, and confirm which VLANs are actually passing traffic.
# Apply changes staged in /etc/network/interfaces.new, live, no reboot
ifreload -a
# Compare the interfaces file against the currently running config
ifquery -c vmbr0
# Show bond0's mode, active slave, and per-NIC link state
cat /proc/net/bonding/bond0
# Show link state for the first physical NIC in the bond
ip link show eno1
# Show link state for the second physical NIC in the bond
ip link show eno2
# List every port attached to vmbr0
bridge link show
# List which VLAN IDs are currently active per bridge port
bridge vlan show
# Confirm bond0 is attached as vmbr0's uplink
ip link show bond0
# Show a VM's network device config, including its VLAN tag
qm config 101 | grep net
# Watch kernel link-state messages while testing a NIC pull
journalctl -k -fbond-mode active-backup, unplugging the active slave’s cable should show the standby take over within roughly one bond-miimon interval in cat /proc/net/bonding/bond0, with no interruption to guest traffic beyond that brief window.
Bonding Modes Cheat Sheet
Linux supports seven bonding modes. Proxmox VE exposes all of them through bond-mode; which one is right depends entirely on what the upstream switch supports.
| Mode | Keyword | Switch Support Needed |
|---|---|---|
| Round-robin | balance-rr | Not required |
| Active-backup | active-backup | Not required |
| XOR | balance-xor | Not required |
| Broadcast | broadcast | Not required |
| IEEE 802.3ad (LACP) | 802.3ad | Required — switch-side LACP/LAG group |
| Adaptive transmit load balancing | balance-tlb | Not required |
| Adaptive load balancing | balance-alb | Not required |
802.3ad for active/active throughput and faster failure detection. If it does not — or you are not sure — use active-backup. It is the only mode that behaves correctly against plain unconfigured switch ports with zero switch-side setup.
Troubleshooting Cheat Sheet
| Symptom | Likely Cause | Fix |
|---|---|---|
| Node drops off the network after a bond change | bond-mode 802.3ad set without a matching LACP group configured on the switch. |
Reconfigure the switch ports as an LACP group, or fall back to bond-mode active-backup, which needs no switch-side config. |
| Guest VLAN tag has no effect | The bridge is not VLAN-aware, so tags set on the VM’s network device are silently dropped. | Add bridge-vlan-aware yes and bridge-vids 2-4094 to the bridge, then ifreload -a. |
cat /proc/net/bonding/bond0 shows only one interface |
bond-slaves lists a NIC that failed to enumerate at boot, or a typo in the interface name. |
Check ip link show for the NIC’s actual name and correct bond-slaves to match. |
| Failover takes several seconds instead of near-instant | bond-miimon interval is high, or missing entirely (defaults to no monitoring). |
Set bond-miimon 100 explicitly for sub-second link-failure detection. |
| VM traffic reaches the bridge but never leaves the host | bridge-ports still points at a physical NIC instead of the bond, so the bonded NICs are unused. |
Change bridge-ports to the bond interface name (bond0), not an individual NIC. |
| Changes in the GUI don’t seem to apply | Changes are staged in /etc/network/interfaces.new until reloaded. |
Run ifreload -a, or use the GUI’s “Apply Configuration” button, then confirm with ifquery -c vmbr0. |
Final Thoughts
Proxmox networking is deliberately unglamorous: bridges, bonds, and VLAN tags, all sitting on top of the same Linux primitives that have run production networks for decades. That is a feature, not a limitation — anything documented for Linux bonding or 802.1Q bridging elsewhere applies here without translation.
Get the bond right before the VLANs. A misconfigured VLAN tag affects one guest; a misconfigured bond mode against a switch that does not expect it can take a whole node off the network, cluster traffic included.
vmbr0 with bridge-vids 2-4094 so VLANs are tagged per guest, and back it with a bond using active-backup unless the switch is explicitly configured for LACP — then 802.3ad is the better default.
Next, we can look at Proxmox’s Software-Defined Networking (SDN) zones, which build VXLAN and EVPN overlays on top of the bridges and bonds set up here.