Linux bridges and bridge VLANs · Linux

A Linux bridge is a software implementation of an Ethernet switch. It connects multiple interfaces at layer 2 and forwards frames between them based on MAC addresses. Bridges are the foundation of KVM/libvirt networking, container networks (Docker bridge, CNI), and many virtualisation stacks.

Create a bridge

ip link add br0 type bridge
ip link set br0 up
ip addr add 10.0.0.10/24 dev br0
ip route add default via 10.0.0.1 dev br0

The bridge br0 now acts like a switch. You can attach physical interfaces or VLAN subinterfaces to it.

Attach interfaces

ip link set eth0 master br0
ip link set eth1 master br0

Both interfaces now forward frames into the bridge. To detach:

ip link set eth0 nomaster

A host’s main IP is usually on the bridge, not on the underlying physical interfaces. The physical interfaces become “bridge ports” with no IP of their own.

Inspect

ip link show master br0
bridge link show
bridge fdb show                # forwarding database
bridge vlan show

The forwarding database (FDB) is the bridge’s MAC table: which MAC is reachable on which port. Entries age out after 5 minutes by default.

Bridge VLAN filtering

By default a bridge forwards all VLAN tags between ports. To restrict which VLANs each port carries, enable VLAN filtering:

ip link set br0 type bridge vlan_filtering 1

Then set per-port VLAN membership:

bridge vlan add dev eth0 vid 100 pvid untagged
bridge vlan add dev eth0 vid 200
bridge vlan add dev eth1 vid 200 pvid untagged

pvid untagged means “frames arriving without a tag on this port are assigned VLAN 100”. vid 100 without untagged means “frames arriving tagged with VLAN 100 are forwarded”.

A trunk port has pvid untagged for the native VLAN and vid for every VLAN it carries. An access port has pvid untagged for one VLAN and no others.

Configure with Netplan

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: no
    eth1:
      dhcp4: no
  bridges:
    br0:
      addresses:
        - 10.0.0.10/24
      routes:
        - to: default
          via: 10.0.0.1
      interfaces:
        - eth0
        - eth1

For VLAN filtering:

  bridges:
    br0:
      addresses:
        - 10.0.0.10/24
      interfaces:
        - eth0
        - eth1
      vlans:
        - id: 100
          member:
            port: eth0
        - id: 200
          member:
            port: eth0
            vlan: 
              - eth0
              - eth1

Configure with systemd-networkd

A .netdev file creates the bridge:

# /etc/systemd/network/10-br0.netdev
[NetDev]
Name=br0
Kind=bridge

[Bridge]
VLANFiltering=true

A .network file attaches the ports:

# /etc/systemd/network/11-br0.network
[Match]
Name=br0

[Network]
Address=10.0.0.10/24
Gateway=10.0.0.1

And for each port, the .network file has:

# /etc/systemd/network/12-eth0.network
[Match]
Name=eth0

[Network]
Bridge=br0

Use cases

Virtualisation host: KVM/QEMU uses bridges to attach VMs to the network. Each VM gets a tap interface on the bridge.
Container host: Docker creates a bridge by default for container networking.
Bond + VLAN aggregation: a bond becomes a bridge port, carrying multiple VLANs.
Network namespaces: bridges can span namespaces for complex topologies.

Linux bridges have STP disabled by default

A new Linux bridge starts with Spanning Tree Protocol off (stp_state 0). ip link add br0 type bridge does not enable it. Neither Netplan nor systemd-networkd enable it unless you ask. A bridge on a fresh host therefore has no loop protection at all.

This is the opposite of the assumption most operators carry over from physical switches, where STP is on out of the box. The mistaken belief is dangerous in one specific direction: you think a loop will be contained, so you tolerate a topology that can form one. It will not be contained. A second uplink, a mis-patched cable, or a VM bridged to two networks produces a broadcast storm that saturates the whole access layer, not just the bridge host.

Check what you actually have:

cat /sys/class/net/br0/bridge/stp_state    # 0 = off, 1 = kernel STP, 2 = user-space STP

Enable it explicitly wherever a loop is possible:

ip link set br0 type bridge stp_state 1

# /etc/systemd/network/10-br0.netdev
[Bridge]
STP=yes

# Netplan
  bridges:
    br0:
      parameters:
        stp: true

Reading port state correctly

bridge link show prints a per-port state. The vocabulary matters during an incident:

forwarding — the port passes traffic. Normal.
blocking — STP has blocked this port to break a loop. This is the state to look for when one link is up but no traffic flows.
listening / learning — transitional STP states during convergence. Classic STP takes about 30 seconds to move a port from listening through learning to forwarding.
disabled — the port is administratively down. It has nothing to do with STP.

Reading disabled as “STP blocked it” sends the responder looking for a loop that does not exist, while the real cause — an interface that was never brought up — sits in plain sight.

Enabling STP is not free either: a port that joins the bridge takes roughly two forward delays (about 30 s) to reach forwarding, which is long enough to break DHCP on a VM that boots quickly. Where the topology genuinely cannot loop, leave STP off; where it can, enable STP and accept the delay, or use RSTP on the upstream switch.