Inspect and Change Linux Bridges with bridge

A VM stops talking to the network and someone blames "the bridge", and the bridge command from iproute2 is how you actually check. This guide covers reading which interfaces belong to a bridge, its forwarding database, multicast memberships and VLAN filters, then making one controlled port or table change when you need to. The examples match iproute2 6.1.0-1ubuntu6.4. Allow about 15 minutes for inspection, longer if you need to identify an unfamiliar interface first.

Before you start

You need a shell on the Linux host and the iproute2 package.
Read-only displays normally work as an ordinary user, though a restricted network namespace or host policy can still deny access.
Changing a link, forwarding entry, multicast database or VLAN needs root, so keep sudo for those commands only.
Have real values ready. Replace br0, eth0, 10 and 02:00:00:00:00:01 with names from your host. Do not guess: a typo can make a check look empty, while a correct but unrelated name can change live traffic.

1. Confirm the utility and list bridge ports

Start with the version and the link view. With no object command, bridge link lists bridge port configuration and flags. Output is intentionally compact, so cross-reference interface names against the wider link inventory from ip link:

bridge -V
ip link show
bridge link show

On this installation, bridge -V reports iproute2 6.1.0. A port line names the device and commonly shows its bridge master, state, STP cost or priority, and flags such as hairpin or learning. To narrow the inventory to one bridge, ask ip which links have a particular master:

ip link show master br0

Checkpoint: you should be able to name the bridge and distinguish it from each attached port before making any change. If bridge link show is empty, check the network namespace and whether the host is using a bridge at all.

2. Read the forwarding database

The forwarding database, or FDB, maps Ethernet addresses to devices. The kernel maintains it per bridge, but bridge fdb show displays entries across every bridge visible in the current namespace. Filter by bridge port when the table is large:

bridge fdb show
bridge fdb show brport eth0
bridge fdb show brport eth0 vlan 10
bridge -s fdb show brport eth0

The last command adds statistics, including last-updated and last-used information where the kernel supplies it. A dynamic entry is learned and can age out. A local or permanent entry terminates traffic on the host rather than forwarding it through a port. The self and master selectors matter when hardware offload is involved: self addresses the port driver, master addresses the bridge.

To look up one address, specify the bridge and the port or device. This is read-only:

bridge fdb get 02:00:00:00:00:01 br br0 dev eth0

Use an address that is actually present. An absent entry is useful evidence, not a reason to add a permanent entry immediately: check cabling, link state, VLAN membership and whether the peer has sent traffic first.

3. Inspect VLAN filters

bridge vlan show lists the VLAN filter entries on bridge devices and ports. A line marked PVID assigns untagged ingress traffic to that VLAN; Egress Untagged means the tag is removed on egress. Presentation varies with the kernel and iproute2 build, so treat the command output as the source of truth:

bridge vlan show
bridge vlan show dev br0
bridge vlan show dev eth0
bridge -d vlan show dev eth0
bridge -s vlan show dev eth0

Checkpoint: verify the VLAN exists on both the bridge and the intended port, and that the PVID and untagged choices match the device at the other end. A missing filter entry is different from a blocked STP state; do not fix one by changing the other.

4. Inspect multicast membership

The multicast database, or MDB, records group membership learned by IGMP or MLD snooping, plus entries added manually. List everything first, then narrow it to one bridge:

bridge mdb show
bridge mdb show dev br0
bridge -d mdb show dev br0
bridge -s mdb show dev br0

The detail view can show router ports; statistics expose timer values. An empty table does not prove multicast is broken: membership is learned from host reports, and the bridge's multicast settings and VLAN filters also affect delivery.

5. Make a narrowly scoped port change

Changing a bridge port can interrupt traffic. Record the current state first:

bridge link show dev eth0

The following example enables hairpin mode on one port, which allows a frame received on a port to be sent back out through that same port. It is useful for some virtualisation or service-chain layouts, but it is not a general connectivity fix and can create an unexpected traffic path:

sudo bridge link set dev eth0 hairpin on
bridge link show dev eth0

Undo it with the inverse value:

sudo bridge link set dev eth0 hairpin off
bridge link show dev eth0

The same syntax applies to supported bridge-port attributes such as learning, flood, mcast_flood, isolated and locked. Read the current line, change one attribute, then verify the line again: do not combine unrelated changes in one command, since a later recovery is much easier when each change has a clear undo.

6. Add or remove a table entry only with a rollback ready

FDB and MDB edits are state changes. Capture the relevant entry before touching it, and keep the matching delete command in the same terminal notes. For example, a static FDB entry can be added to a port:

bridge fdb show brport eth0 vlan 10
sudo bridge fdb add 02:00:00:00:00:01 dev eth0 vlan 10 static
bridge fdb show brport eth0 vlan 10

Remove precisely that entry with:

sudo bridge fdb del 02:00:00:00:00:01 dev eth0 vlan 10 static
bridge fdb show brport eth0 vlan 10

Warning: do not use bridge fdb flush as a first diagnostic step. It deletes matching forwarding entries, and a broad match can affect every learned address on a port or device. If a flush is genuinely required, constrain it with the correct device, bridge port, VLAN and entry class, then verify the reduced table and expect traffic to be relearned.

A manually maintained multicast membership uses the same identifying arguments for add and delete:

sudo bridge mdb add dev br0 port eth0 grp 239.192.0.10 permanent
bridge mdb show dev br0
sudo bridge mdb del dev br0 port eth0 grp 239.192.0.10 permanent

Use a permanent L3 group only when the network design calls for manually managed membership. The manpage requires the permanent form for layer-2 multicast groups, while IPv4 and IPv6 entries can be temporary. A manually added entry does not replace checking IGMP, MLD or snooping behaviour.

7. Watch changes as they happen

When the problem is intermittent, monitor the relevant netlink events in a second shell:

bridge monitor link fdb vlan mdb

The command keeps listening until you stop it with Ctrl-C. Use one object, such as bridge monitor fdb, when the combined stream is distracting. The monitor shows changes; it is not a replacement for a fresh show command after a change.

Done means

Identified the bridge and its ports in the current network namespace.
Checked the relevant FDB, VLAN and MDB state before editing anything.
Limited every state change to the intended device, address, VLAN or group.
Ran the matching show command after the change.
Kept an inverse command ready for every temporary test, and stopped any monitor no longer needed.