The vmbr0 bridge: how a guest gets on the network
The installer creates one bridge — vmbr0 — and puts the first network card into it. The host’s address is on
the bridge, not on the card. Each guest connects to the bridge with its own virtual port: tap<id>i<n> for a VM,
veth<id>i<n> for a container.
router 10.0.0.1 ── cable ── nic0 ─┐
├─ vmbr0 10.0.0.2 ← host, web UI :8006
VM 101 ── tap101i0 ──┤ ← guest: own MAC, address from the router
container 201 ── veth201i0 ─┘
To the router, guests are devices just like phones: each with its own MAC, an address from the router’s DHCP or one you set. Traffic between guests on one host never reaches the router; the bridge forwards it itself.
The network file after install:
auto lo
iface lo inet loopback
iface nic0 inet manual
auto vmbr0
iface vmbr0 inet static
address 10.0.0.2/24
gateway 10.0.0.1
bridge-ports nic0
bridge-stp off
bridge-fd 0
iface nic0 inet manual— the card has no address of its own; it’s just a bridge port.bridge-ports nic0— which cards are in the bridge. A bridge without cards (bridge-ports none) is a network between the guests and the host only.bridge-stp off,bridge-fd 0— no STP and no forwarding delay: the bridge has one card, so there are no loops.
The network is applied by ifupdown2: ifreload -a rereads the file and changes only what changed, without
stopping guests. In the UI, edits go through /etc/network/interfaces.new and the Apply Configuration button.
Editing /etc/network/interfaces by hand and running ifreload -a is the same thing.
Network card names
The kernel names a card by its bus position: eno1, enp3s0, and USB adapters by MAC, enx74d4…. After a kernel
update the position may read differently: the 9.1 release notes say new PCIe features in the recent kernel change
names. The bridge refers to the old name, and the host is left without network.
The protection is pinned names:
- In the installer since 9.1 — an option to pin names. The cards are called
nic0,nic1, and the name doesn’t depend on the kernel. - On an existing host —
pve-network-interface-pinning generate. The tool writes.linkfiles to/usr/local/lib/systemd/network/and updates the Proxmox configs for the new names; they take effect after a reboot.
The kernel keeps the old name as an alternative one: ip link shows altname enx74d43519a642 on nic0.
VLANs
A VLAN splits one physical network into several: guest, smart home, lab. If the router and switch support VLANs (Wired on MikroTik), the Proxmox bridge hands them out to guests by tag. Add two lines to the bridge:
auto vmbr0
iface vmbr0 inet static
address 10.0.0.2/24
gateway 10.0.0.1
bridge-ports nic0
bridge-stp off
bridge-fd 0
bridge-vlan-aware yes
bridge-vids 2-4094
Then set a VLAN Tag on the guest’s network card, say 20 — in the guest config that’s
net0: virtio=…,bridge=vmbr0,tag=20. The guest doesn’t know about the VLAN: it sees a normal network, and the
bridge adds and strips the tag. The switch port the host is plugged into must pass these VLANs tagged (trunk).
A private network behind NAT
Sometimes guests need a separate network: a rented server has one public address, the host is on Wi-Fi, or test machines shouldn’t see the home network. Then make a second bridge with no cards and let it out through the host’s NAT — the way a home router lets out the apartment:
auto vmbr1
iface vmbr1 inet static
address 10.10.10.1/24
bridge-ports none
bridge-stp off
bridge-fd 0
post-up echo 1 > /proc/sys/net/ipv4/ip_forward
post-up iptables -t nat -A POSTROUTING -s '10.10.10.0/24' -o vmbr0 -j MASQUERADE
post-down iptables -t nat -D POSTROUTING -s '10.10.10.0/24' -o vmbr0 -j MASQUERADE
- Guests on
vmbr1get10.10.10.xaddresses with gateway10.10.10.1. There’s no DHCP here: set the address yourself — in a cloud-init template it’s one--ipconfig0option (VM template with cloud-init). -o vmbr0is the interface the host uses to reach the outside. If the host’s address is directly on the card rather than a bridge, put the card name here.- A guest port to the outside is a DNAT rule:
iptables -t nat -A PREROUTING -i vmbr0 -p tcp --dport 2222 -j DNAT --to-destination 10.10.10.11:22. It also goes in as apost-upline and comes off inpost-down. - If the Proxmox firewall is on, the documentation recommends one more line — conntrack zones for outgoing
connections:
post-up iptables -t raw -I PREROUTING -i fwbr+ -j CT --zone 1.
With more than three rules, move them into your own script called by post-up and pre-down: the rules then come
off with one command and don’t duplicate when the bridge comes up again.
The same NAT with DHCP can be put together with the mouse: Datacenter › SDN, a Simple zone with the SNAT and DHCP
checkboxes. Proxmox brings up dnsmasq itself and hands out addresses to the guests. DHCP in SDN has been a
technology preview since 8.1.
Two cards: a bond
Two cards in one bond give a reserve in case a cable or port fails. 802.3ad (LACP) mode adds up their speed across
different connections but needs switch support. active-backup works with any switch: one card works, the other
waits. The bridge is then built on top of the bond: bridge-ports bond0.
The Proxmox firewall
The Proxmox firewall is built in and off by default. Rules live on three levels:
| Level | Where in the UI | What it closes |
|---|---|---|
| Datacenter | Datacenter › Firewall | the master switch and rules for all nodes; rule groups, address sets |
| Node | node › Firewall | incoming traffic to the host itself: 8006, 22, 3128 (SPICE proxy) |
| Guest | VM or container › Firewall | traffic to the guest at the bridge level; the guest doesn’t know about it |
The order of turning it on matters. Turn the firewall on at Datacenter, and incoming traffic to the hosts is denied
except 8006 and 22 from the local network. For a guest, the firewall applies only if it’s on both for the guest
(its Firewall › Options › Firewall) and for its network card (firewall=1; in the UI new cards are created with this
checkbox).
There are two implementations. The main one is pve-firewall on iptables. Since 8.2 there’s proxmox-firewall on
nftables — a technology preview, enabled per node: Firewall › Options › nftables. The rules in the UI are the same;
only what enforces them changes.
At home a simpler setup is common: the Proxmox firewall is off, nothing is forwarded to the outside, and the host’s 8006 and SSH are reachable only from the home network (8006 from inside only). Internet-facing guests are closed with their own firewall — ufw on Ubuntu (The ufw firewall).
If it doesn’t work
Changed the network in the UI — nothing changed
- Cause
- The UI writes edits to
/etc/network/interfaces.new, and they reach the live file only with the Apply Configuration button. - Fix
- Node › System › Network › Apply Configuration. What exactly will change is shown at the bottom of the same page, under Pending changes.
After a kernel update the host dropped off the network
- Cause
- The new kernel named the card differently (
enp3s0instead ofenp2s0), whilevmbr0has the old name inbridge-ports. - Fix
- From a monitor:
ip -br linkshows the new name; fixbridge-portsin/etc/network/interfacesand runifreload -a. Then pin the names:pve-network-interface-pinning generateand a reboot.
A laptop host on Wi-Fi works, but guests on the bridge have no network
- Cause
- A Wi-Fi client passes only frames with its own MAC: the access point won’t accept frames from guest MACs, so a bridge over Wi-Fi doesn’t work.
- Fix
- Put the guests on a private network behind NAT (
vmbr1with MASQUERADE, below), or connect the host with a cable.
Rented server: a guest was added to the bridge with a public address — the provider shut the port or sent a complaint
- Cause
- The provider sees several MACs on the port and treats it as a violation: the Proxmox documentation explicitly warns that many hosting providers do this.
- Fix
- Put the guests on a NAT network on
vmbr1and expose ports through DNAT or a proxy on the host. If the provider issues virtual MACs for extra addresses, set them on the guests’ network cards.
A VM with a VLAN tag doesn’t get an address
- Cause
- The bridge isn’t VLAN-aware, so the tag has nowhere to go, or the switch and router port doesn’t pass that VLAN tagged.
- Fix
- On
vmbr0—bridge-vlan-aware yesandbridge-vids 2-4094; on the switch, the port to the host is a trunk with the VLAN. Check from the host:bridge vlan show— thetap<id>i0port has the tag.
Turned the firewall on at Datacenter — lost access to the UI
- Cause
- With the firewall on, incoming traffic to the host is denied except ports 8006 and 22 from the local network. Coming in from another subnet means falling under the ban.
- Fix
- From the host console:
pve-firewall stop, then a rule for your address in Datacenter › Firewall andpve-firewall start. Orenable: 0in/etc/pve/firewall/cluster.fw.