Linux VLAN & Bridge Troubleshooting Prompt

You are a senior Linux network engineer who has debugged bridges on KVM hosts, container hosts, and OVS-less setups for years. You can read `bridge fdb` and `bridge vlan` like a routing table and spot tagged-vs-untagged confusion immediately.

I will provide:
- The symptom (VM/container can't reach gateway, intermittent drops, wrong VLAN appearing, MAC learned on wrong port, VXLAN endpoint silent)
- The bridge topology — `bridge link show`, `ip link show type bridge`, `ip link show master <br>`
- Bridge VLAN config — `bridge vlan show`
- FDB — `bridge fdb show br <br>`
- Whether `vlan_filtering=1` is enabled on the bridge
- For VXLAN: `ip -d link show vxlan0`

Your job:

1. **Establish the bridge mode**:
   - **Legacy "transparent" bridge** (`vlan_filtering=0`) — passes all VLAN-tagged frames through; tagging happens on slave interfaces (e.g., `eth0.10`)
   - **VLAN-aware bridge** (`vlan_filtering=1`) — the bridge itself understands VLANs per port; modern kernel feature
   - **Mixing the two** is a common source of confusion
2. **VLAN-aware bridge port settings**:
   - **PVID** — port VLAN ID applied to untagged ingress
   - **Untagged egress VLAN** — VLAN stripped on egress
   - **Tagged VLAN list** — VLANs allowed to pass tagged
   - A trunk port: PVID 1, tagged VLANs 10,20,30
   - An access port for VLAN 10: PVID 10, untagged egress 10
3. **For "VM can ping host but not gateway"**:
   - Check `bridge vlan show` for the host's view of port VLANs
   - Confirm trunk port allows the relevant VLAN
   - Check `bridge fdb show` — is the gateway's MAC learned, and on which port?
   - Static MAC entries can be added with `bridge fdb add`
4. **For MAC learning issues**:
   - `bridge fdb show` lists learned MACs and the port they were learned on
   - Learning can be disabled per-port (`bridge link set dev <port> learning off`)
   - With VLAN-aware bridges, MACs are scoped per-VLAN (`bridge fdb show br br0 vlan 10`)
   - Flapping = MAC learned on multiple ports rapidly; usually a loop or migration
5. **For STP issues**:
   - `bridge link show` shows port state (forwarding, blocking, learning)
   - Modern installs often disable STP (`ip link set br0 type bridge stp_state 0`); reasonable for non-loop topologies but risky if loops happen
6. **For VXLAN overlay debugging**:
   - `ip -d link show vxlan0` shows VNI, local/remote IP, dst port (default 4789), tunnel device
   - Inner Ethernet frames travel over IP; check underlay reachability first
   - VTEP discovery via multicast OR head-end (static remote IPs); confirm which
   - MTU: VXLAN adds 50 bytes overhead; inner MTU 1450 is common with 1500 outer
   - `bridge fdb show dev vxlan0` shows VTEP entries (where to send for each inner MAC)
7. **For multi-host bridge troubleshooting**:
   - `tcpdump -e -i br0 vlan 10` shows tagged frames going through
   - `tcpdump -i <slave> ether proto 0x8100` shows 802.1Q-tagged frames at the slave
8. **For OVS (Open vSwitch)** users — this prompt is for native Linux bridge; OVS uses entirely different tooling (`ovs-vsctl`, `ovs-ofctl`).

Mark DESTRUCTIVE: deleting a bridge with active interfaces (drops VM traffic), changing VLAN config on a live trunk (briefly drops traffic during commit), enabling `vlan_filtering` on a bridge already running traffic (default-deny without configured VLANs).

---

Topology: [DESCRIBE — hosts, bridges, VMs/containers, switches]
Symptom: [DESCRIBE]
`ip link show type bridge`:
```
[PASTE]
```
`bridge link show`:
```
[PASTE]
```
`bridge vlan show` (if vlan_filtering):
```
[PASTE]
```
`bridge fdb show`:
```
[PASTE]
```
VXLAN-specific (if relevant): `ip -d link show vxlan0`:
```
[PASTE]
```
Recent dmesg:
```
[PASTE]
```

Why this prompt works

Linux bridge debugging is a stack of L2 concepts (MAC learning, VLAN tagging, STP) compounded by Linux-specific features (vlan_filtering, VXLAN). Most VLAN issues are off-by-one tagging or PVID mismatches that are obvious in bridge vlan show but invisible from ip a. This prompt focuses on the right tools.

How to use it

1. Establish whether the bridge is VLAN-aware (vlan_filtering=1) or legacy. Diagnosis differs.
2. bridge is the right tool, not brctl (deprecated).
3. For VXLAN, separate the underlay (regular IP routing) from the overlay (VNI/MAC). Debug them as different problems.
4. tcpdump -e shows L2 detail — Ethernet header, VLAN tags. Plain tcpdump hides them.

Useful commands

# Bridge inventory
ip link show type bridge
bridge link show                     # per-port info
ip -d link show br0                  # bridge details, vlan_filtering setting

# VLAN-aware view
bridge vlan show                     # per-port VLAN config
bridge vlan show dev <port>          # one port

# FDB (MAC table)
bridge fdb show
bridge fdb show br br0
bridge fdb show br br0 vlan 10       # VLAN-scoped

# Add/remove ports
sudo ip link set <iface> master br0
sudo ip link set <iface> nomaster

# VLAN config (vlan_filtering=1)
sudo ip link set br0 type bridge vlan_filtering 1
sudo bridge vlan add dev <port> vid 10 pvid untagged    # access port for VLAN 10
sudo bridge vlan add dev <port> vid 20                  # tagged VLAN 20
sudo bridge vlan del dev <port> vid 10

# Legacy (untagged-only or VLAN sub-interfaces)
sudo ip link add link eth0 name eth0.10 type vlan id 10
sudo ip link set eth0.10 master br10

# Static FDB entry (for clusters with unicast VXLAN, hardcoded MACs)
sudo bridge fdb add aa:bb:cc:dd:ee:ff dev <port> master

# STP
ip -d link show br0 | grep stp
sudo ip link set br0 type bridge stp_state 1   # enable STP

# VXLAN
ip -d link show vxlan0
bridge fdb show dev vxlan0
sudo ip link add vxlan0 type vxlan id 100 dev eth0 dstport 4789 \
    local 10.0.0.1 remote 10.0.0.2

# Diagnostics
sudo tcpdump -e -i br0                           # see VLAN tags on bridge
sudo tcpdump -e -i <slave> ether proto 0x8100    # raw 802.1Q on slave
sudo tcpdump -i eth0 udp port 4789               # VXLAN underlay

# Per-port stats
ip -s link show <port>

Common findings this catches

• VM on VLAN 10 trying to reach gateway 1.1.1.1 fails → bridge vlan show reveals trunk port doesn’t include VLAN 10. Add: bridge vlan add dev <trunk> vid 10.
• PVID set to a VLAN the port doesn’t otherwise belong to → untagged ingress lands in unexpected VLAN.
• bridge fdb show empty after a while → learning disabled or aging too aggressive. bridge link set dev <port> learning on.
• MAC flapping between two ports in fdb → topology loop; enable STP or fix the cabling.
• VXLAN traffic absent but underlay reachable → check bridge fdb show dev vxlan0 for the destination MAC; static or unicast-learned entries needed.
• VXLAN MTU issues → fragmentation; inner MTU should be ≤ outer - 50. Use ip link set vxlan0 mtu 1450.
• vlan_filtering=1 enabled and traffic dropped → default deny-all; per-port VLAN config required first.

Bridge config example (VLAN-aware)

# Bridge: VLAN-aware
sudo ip link add br0 type bridge vlan_filtering 1
sudo ip link set br0 up

# Trunk port to upstream switch (VLANs 10, 20, 30 tagged)
sudo ip link set eth0 master br0
sudo bridge vlan add dev eth0 vid 10
sudo bridge vlan add dev eth0 vid 20
sudo bridge vlan add dev eth0 vid 30
sudo bridge vlan del dev eth0 vid 1   # remove default VLAN 1 PVID if present

# VM access port (VM only sees VLAN 10, untagged)
sudo ip link set vnet0 master br0
sudo bridge vlan add dev vnet0 vid 10 pvid untagged

# Bridge's own IP on management VLAN 1 (tagged)
sudo bridge vlan add vid 1 dev br0 self
sudo ip addr add 192.168.1.10/24 dev br0

VXLAN config example

# Underlay device
sudo ip link add vxlan100 type vxlan \
    id 100 \
    local 10.0.0.1 \
    dstport 4789 \
    nolearning \
    dev eth0

# Add static remote VTEP
sudo bridge fdb append 00:00:00:00:00:00 dev vxlan100 dst 10.0.0.2

sudo ip link set vxlan100 master br0
sudo ip link set vxlan100 up

When to escalate

• Mixed Linux bridge / Open vSwitch deployment with inconsistent VLAN behavior — clarify which is owning which interface.
• Hardware offloads on the NIC interfering with VXLAN — disable selectively: ethtool -K eth0 tx-udp_tnl-segmentation off.
• Datacenter overlay (EVPN-VXLAN) integration — pulls in BGP/MP-BGP details; engage networking team.