Proxmox Network Bridges and VLANs: vmbr0, Tags, and OVS

For almost every Proxmox VE host, the correct network design is:

• A single Linux bridge, vmbr0, with VLAN awareness enabled. Open vSwitch is for people who can name the OVS feature they need.
• Tag per guest, not per bridge. One VLAN-aware bridge plus a tag= on each VM or container NIC beats a pile of vmbr10, vmbr20, vmbr30.
• Give the host its own VLAN interface such as vmbr0.10, rather than leaving management on whatever the switch happens to treat as untagged.
• Get out-of-band access before you touch anything. IPMI, iDRAC, iLO, or a keyboard in front of the machine.
• Schedule the rollback before you press Apply. A one-line at job that restores your backup is the difference between a bad ten minutes and a drive to the rack.

Proxmox networking is plain Debian underneath. The web UI is a thin editor over /etc/network/interfaces, and ifupdown2 brings the interfaces up. That is good news, because it is all text you can back up and restore. It is also the trap, because the GUI makes a change that severs your own SSH session look exactly like one that works.

What the installer gives you and why it is right

A fresh install creates one Linux bridge, vmbr0, with your physical NIC as its only bridge port, and puts the management IP on the bridge rather than on the NIC. Guests get a tap (VMs) or veth (containers) interface plugged into the same bridge.

The consequence is that guests sit on your physical LAN as first-class devices with their own MAC addresses. There is no NAT and no routing on the host by default. Your DHCP server hands them leases and your switch sees their MACs, exactly like any other machine on the wire. That is the behavior most people want, and it is why the Proxmox VE install does not ask you to design a network first. Everything below is a variation on that one bridge.

Linux bridge or Open vSwitch

Proxmox supports both. The GUI offers Linux Bridge, Linux Bond, and Linux VLAN, plus OVS Bridge, OVS Bond, and OVS IntPort once openvswitch-switch is installed.

Pick the Linux bridge unless you have a specific reason not to. It is in-kernel, needs no extra daemon, is what the installer configures, and is what the documentation and forum threads assume. VLAN handling used to be the reason people reached for OVS; VLAN-aware Linux bridges closed that gap years ago, and the old advice has outlived its justification.

Reach for OVS when you need something it uniquely provides, such as RSTP participation, NetFlow or sFlow export off the virtual switch, OpenFlow control, or its richer bonding hash modes. Those are real requirements in some environments. They are not homelab requirements.

The costs are worth stating plainly. You add a userspace daemon to the path of your own management network, so an OVS problem becomes an access problem. You manage state with ovs-vsctl instead of the standard ip and bridge tooling, so half the answers you find online do not apply. And giving the host an IP inside a tagged VLAN needs an OVS IntPort rather than the simple vmbr0.10 interface a Linux bridge uses.

Mixing both on one host is legal and almost always a mistake. Pick one per host and keep it consistent across a cluster.

VLAN-aware bridges versus a bridge per VLAN

The older pattern builds a VLAN subinterface for each VLAN and gives each one its own bridge: eno1.20 into vmbr20, eno1.30 into vmbr30, and so on. It works, but every new VLAN becomes a host network change, and every host network change is a chance to lose the host.

A VLAN-aware bridge moves the tagging decision to the guest. Configure the bridge once, declare which VLAN IDs are allowed, and after that adding a guest to VLAN 40 is a field in the VM’s network device. No /etc/network/interfaces edit, no Apply, no lockout window. That is an uptime argument, not just a convenience one.

A typical VLAN-aware config with management on VLAN 10:

auto lo
iface lo inet loopback

iface eno1 inet manual

auto vmbr0
iface vmbr0 inet manual
    bridge-ports eno1
    bridge-stp off
    bridge-fd 0
    bridge-vlan-aware yes
    bridge-vids 10 20 30 40

auto vmbr0.10
iface vmbr0.10 inet static
    address 192.168.10.5/24
    gateway 192.168.10.1

Two details matter there. The bridge is inet manual and carries no IP; the address lives on vmbr0.10, the VLAN 10 interface of the bridge. And bridge-vids is an explicit list. The GUI will happily give you the full 2-4094 range, which turns the host into a trunk for every VLAN you own. If your switch trunks four VLANs to this port, list those four. A narrower bridge-vids is cheap blast-radius reduction.

Keep a bridge-per-VLAN in three cases: an isolated internal bridge with bridge-ports none for guest-to-guest networks that must never reach the wire, an OVS deployment, or one VLAN needing a different MTU from the rest.

Tagging guests

On a VLAN-aware bridge, the tag is a property of the guest’s virtual NIC. In the GUI it is the VLAN Tag field on the network device. On disk it is a tag= in the guest config.

A VM, in /etc/pve/qemu-server/<vmid>.conf:

net0: virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=20

A container, in /etc/pve/lxc/<ctid>.conf:

net0: name=eth0,bridge=vmbr0,ip=dhcp,tag=20

The guest operating system sees plain untagged traffic and must not be configured with a VLAN of its own. Setting tag=20 on the host and a VLAN 20 subinterface inside the guest produces double tagging, and the symptom is a machine that looks perfectly configured and receives nothing. It is a recurring theme in Proxmox VLAN support threads.

The exception is a guest that genuinely needs several VLANs on one virtual NIC, such as a firewall or router VM. For that, use the trunks option instead of a single tag, listing the VLANs explicitly:

net0: virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,trunks=20;30;40

Now the guest receives tagged frames and handles VLANs internally, which is what a firewall distribution expects. List them explicitly rather than relying on the default behavior of an untagged port.

Two practical notes. Whether a VLAN tag change reaches a running guest depends on that guest’s hotplug setting: with network hotplug enabled the tap interface is re-plugged onto the new VLAN, and without it the edit sits as a pending change until the guest stops and starts. Verify the guest actually moved rather than assuming either outcome. And if you build guests from cloud-init templates, the tag lives in the template’s net0 line and every clone inherits it. The choice between LXC containers and full VMs changes none of this; both use the same field.

Bonds under the bridge

With two or more NICs the stack is physical interfaces into bond0, bond0 into vmbr0, and the host IP on vmbr0.10. The bond carries no IP of its own.

Active-backup is the right default. It needs no switch configuration at all, and if the two links go to two different switches it survives one of them rebooting. LACP (802.3ad) needs a matching port-channel on the switch side, and if that configuration is wrong or absent, the host disappears. Configure the switch first, verify it, then configure Proxmox, with console access open.

Set MTU consistently or not at all. For jumbo frames, the physical NICs, the bond, the bridge, the guest NIC, and every switch port in between all have to agree. A partial MTU change produces the worst class of network fault: pings work, SSH connects, and large transfers hang forever.

How not to lock yourself out

This is the part people skip and then post about.

1. Have out-of-band access before you start. IPMI, iDRAC, or iLO on the motherboard, or a monitor and keyboard within reach. A remote-management port is a hardware purchase decision, which is why it belongs in your Proxmox hardware planning rather than in your recovery plan.

2. Back up the file. cp /etc/network/interfaces /etc/network/interfaces.bak-$(date +%F)

3. Schedule the undo before you make the change. With at installed:

   echo "cp /etc/network/interfaces.bak-$(date +%F) /etc/network/interfaces && ifreload -a" | at now + 10 minutes

   The quotes are double on purpose, so $(date +%F) expands now and the job restores the exact file you just backed up in step 2. A single-quoted version would look correct, do nothing when it fired, and leave you locked out of a host you thought had a safety net. If you still have your session afterwards, find the job with atq and cancel it with atrm <job>. If you do not, the host repairs itself while you are still typing. This rescues you from a bad host config, not from a switch that is now misconfigured, so treat it as one layer rather than the whole plan.

4. Know what Apply actually does. The GUI stages edits into /etc/network/interfaces.new, and on an ifupdown2 host, which is what current Proxmox VE installs use, Apply Configuration puts them live immediately with no automatic revert. Undoing it means editing and applying again, which is precisely what you cannot do from a dead session. On an older host still running legacy ifupdown, the staged file instead waits for a reboot, so the failure mode moves rather than disappearing.

5. Change one thing per apply. Moving management to a tagged VLAN and adding a bond in the same edit means that when it breaks you cannot tell which half broke it.

6. Keep a rescue path. A spare NIC on an untagged access port with a static address, deliberately left out of the bridge, is the cheapest insurance in the rack.

7. Test with a throwaway guest first. Create a small container with tag=20 and confirm it gets a lease and reaches its gateway before moving the host’s own management interface onto that VLAN.

8. One default gateway, on one interface. A second gateway line is a routing bug waiting for a reboot.

Cluster and storage caveats

Networking changes are riskier on a cluster member. Corosync rides a specific network, and a node that loses quorum stops accepting cluster writes. If high availability is active, that node will fence itself, meaning an unscheduled hard reboot of everything running on it. Work on one node at a time so the rest of the cluster keeps quorum.

Keep corosync off the VLAN carrying bulk guest and backup traffic. It is latency-sensitive rather than bandwidth-hungry, and a saturated link is what turns a busy evening into a fencing event. Ceph wants its own networks for the same reason. Plan this at cluster setup time, because retrofitting it later means exactly the risky changes this guide is about.

When a VLAN does not work

Work through these in order before rebuilding anything:

• bridge vlan show lists the VLAN IDs actually programmed per port, including the tap and veth interfaces of running guests. If a guest’s port is not carrying the VID you expect, the problem is on this host.
• ip -d link show vmbr0 confirms VLAN filtering is genuinely enabled and not merely checked in the GUI.
• Check whether /etc/network/interfaces.new still exists. Staged-but-unapplied config explains a lot of “I already fixed that” reports.
• Check the switch. Is the port a trunk, is the VLAN allowed on it, and does the native VLAN match what the host expects? Plenty of reported Proxmox VLAN bugs turn out to be switch port configuration.
• Check for double tagging inside the guest.

If the fault survives all five, the general troubleshooting guide covers the wider diagnostic path.

Next steps

• Segmenting guests with VLANs pairs naturally with host-level rules; see Proxmox firewall configuration.
• If this host is about to become node one of several, read Proxmox cluster setup before you finalize the network layout.