Bridge troubleshooting — finding the broken bridge fast

A broken bridge has a small set of common failure modes. This lesson is the diagnostic flow that finds the root cause in five minutes, the commands that reveal the FDB and STP state, and the symptoms that identify each failure.

The diagnostic flow

flowchart TB
  A[Bridge broken] --> B[Step 1: bridge up?<br/>ip link show br0]
  B --> C{Bridge up?}
  C -->|no| D[VyOS configuration]
  C -->|yes| E[Step 2: members up?<br/>show bridge]
  E --> F{Members up?}
  F -->|no| G[Member link state]
  F -->|yes| H[Step 3: FDB learning?<br/>brctl showmacs]
  H --> I{FDB learning?}
  I -->|no| J[MAC learning issue]
  I -->|yes| K[Step 4: STP state?<br/>show spanning-tree]
  K --> L{STP converged?}
  L -->|no| M[STP configuration]
  L -->|yes| N[Step 5: broadcast storm?<br/>tcpdump -i br0]

Step 1 — bridge up

vyos@vyos:~$ ip link show br0
3: br0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 ...

If the bridge is down, the issue is the VyOS configuration:

vyos@vyos:~$ show configuration commands | match "interfaces bridge"

Step 2 — members up

vyos@vyos:~$ show bridge
Interface      State
br0            UP
eth0           UP
eth1           UP

If a member is down, the issue is the member’s link or configuration.

Step 3 — FDB learning

vyos@vyos:~$ brctl showmacs br0
port    mac                 is-local?   age
eth0    aa:bb:cc:dd:ee:ff   no           12
eth1    11:22:33:44:55:66   no           8

If the FDB is not learning, the issue is the MAC learning configuration or the bridge is not receiving frames.

Step 4 — STP state

vyos@vyos:~$ show spanning-tree
Bridge br0
  Root ID:    8000.525400123456
  Bridge ID:  8000.525400123456
Interface  Role    State    Cost
eth0       Root    FWD      4
eth1       Desg    FWD      4

If STP has not converged, the issue is the STP configuration or a loop.

Step 5 — broadcast storm

vyos@vyos:~$ tcpdump -i br0 -c 100

A high count of broadcast frames indicates a broadcast storm, usually caused by a bridge loop.

Common failure modes

How the result is validated

The diagnostic commands confirm:

• Bridge state: ip link show br0
• Members: show bridge
• FDB: brctl showmacs br0
• STP: show spanning-tree
• Broadcast: tcpdump -i br0

How it fails

The diagnostic commands themselves can fail:

• show bridge with empty output: the bridge has no members.
• show spanning-tree with no output: STP is disabled.
• brctl showmacs with no entries: the bridge is not receiving frames.
• tcpdump -i br0 with no output: the bridge has no traffic.

Rollback

The recovery from a broken bridge:

• Bridge down: reconfigure with set interfaces bridge br0.
• Members down: reconfigure or fix the physical link.
• STP not converging: enable STP and identify the loop.

Production discipline

Cross-course references

The OPNsense course’s XIV-OPNsense-VLAN covers the equivalent L2 concepts. The Linux course’s XXII-Linux-NetTroubleshoot covers the underlying network troubleshooting. The Observability course’s LX-Observability-NetworkObs covers how to alert on bridge state changes.

Quiz