๐ŸŽ New User? Get 20% off your first purchase with code NEWUSER20 ยท โšก Instant download ยท ๐Ÿ”’ Secure checkout Register Now โ†’
Menu

Categories

Linux Bridge Configuration and Troubleshooting Guide

Linux Bridge Configuration and Troubleshooting Guide
You run a KVM host or a container platform; your VMs or containers need to talk to the physical network, so you create a Linux bridge. The command succeeds, but packets vanish. The bridge is a software switch, but Linux treats it like a firewall too: netfilter hooks sit between ports, sysctl toggles break forwarding, and VLAN config hides in unfamiliar subcommands. This guide walks through linux bridge configuration with the tools and flags that matter.

You will see the modern ip and bridge commands alongside legacy brctl, learn which sysctl knobs silently block traffic, and inspect the MAC address table when learning fails. The examples use real interface names, real error messages, and the netfilter interactions that break bridges in production.

A bridge is a virtual switch that forwards Ethernet frames between attached interfaces. You create the bridge device, enslave physical or virtual interfaces to it, then bring everything up. Miss one of those steps and the bridge sits silent.

Creating the Bridge Device

Create the bridge with ip link:

# ip link add br0 type bridge

This creates a bridge interface named br0. The bridge exists but has no ports and is down. You can name it anything, but br0, virbr0, or lxcbr0 are common. If you have muscle memory for brctl addbr br0, that still works on systems with the bridge-utils package, but ip link is the modern path and does not require an extra package.

Adding Ports to the Bridge

Enslave a physical interface to the bridge:

# ip link set eth0 master br0

This makes eth0 a port of br0. Frames arriving on eth0 are forwarded according to the bridge's MAC table. The equivalent brctl command is brctl addif br0 eth0. You can add multiple interfaces: ip link set eth1 master br0, ip link set tap0 master br0, and so on. Verify with:

# ip -d link show br0
4: br0: <BROADCAST,MULTICAST> mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default 
    link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff promiscuity 0 
    bridge forward_delay 1500 hello_time 200 max_age 2000 ageing_time 30000 stp_state 0 priority 32768 vlan_filtering 0 vlan_protocol 802.1Q

The state DOWN means the bridge is not up yet. The -d flag shows bridge-specific parameters like STP state and VLAN filtering.

Bringing the Bridge Up

Bring up the bridge and its ports:

# ip link set br0 up
# ip link set eth0 up

Both commands are required. A common trap: bringing up the bridge but leaving the enslaved interface down. The bridge will show state UP, but eth0 remains state DOWN and no traffic crosses. Check with ip link show eth0. If eth0 had an IP address before you enslaved it, remove it: ip addr flush dev eth0. The bridge itself gets the IP if you need one for management.

Bridge Forwarding and sysctl Knobs

A bridge forwards at Layer 2 without routing, but netfilter hooks can intercept bridged packets and apply iptables rules meant for routed traffic. Two sysctl settings control this and are the first place to look when bridge traffic vanishes.

IPv4 Forwarding on the Bridge

The net.ipv4.ip_forward sysctl enables routing between interfaces. For a pure bridge with no IP address, you do not need it; the bridge forwards frames regardless. But if the bridge has an IP or if you route between the bridge and another interface, enable it:

# sysctl -w net.ipv4.ip_forward=1

Make it persistent in /etc/sysctl.d/99-bridge.conf:

net.ipv4.ip_forward = 1

For most VM and container setups, the real problem is netfilter, not routing.

Disabling Netfilter on Bridge Ports

By default, bridged packets traverse the FORWARD chain in iptables. If you have a host firewall with iptables -P FORWARD DROP, guest traffic dies. Disable netfilter on bridges:

# sysctl -w net.bridge.bridge-nf-call-iptables=0
# sysctl -w net.bridge.bridge-nf-call-ip6tables=0
# sysctl -w net.bridge.bridge-nf-call-arptables=0

If those keys do not exist, load the module:

# modprobe br_netfilter

Then set the sysctls again. With these set to 0, bridged frames bypass iptables entirely. If you need to filter guest traffic, do it on the bridge ports with ebtables or within the guests. For KVM and LXC hosts, setting these to 0 is standard; see the Linux Firewall Configuration eBook for more on separating host and guest firewall policies.

Persistent Configuration

Put all three in /etc/sysctl.d/99-bridge.conf:

net.bridge.bridge-nf-call-iptables = 0
net.bridge.bridge-nf-call-ip6tables = 0
net.bridge.bridge-nf-call-arptables = 0

On Debian and Ubuntu, also create /etc/modules-load.d/br_netfilter.conf with a single line br_netfilter so the module loads at boot. Red Hat and SUSE load it automatically when the bridge module loads.

Inspecting Bridge State and MAC Table

When traffic does not cross the bridge, inspect the port state and the forwarding database. The bridge command shows what the kernel's bridge code sees.

Listing Bridge Ports and Status

Show all ports attached to all bridges:

# bridge link show
4: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding priority 32 cost 4 
5: tap0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding priority 32 cost 100

Each line shows the port name, its master bridge, and the STP state. state forwarding means the port is active. If you see state disabled or state blocking, STP has shut it down. For a specific bridge:

# bridge link show master br0

The master keyword is documented in bridge(8). If a port you enslaved does not appear, check that you brought it up with ip link set port up.

Viewing the Forwarding Database

The forwarding database (FDB) is the bridge's MAC address table. Show it with:

# bridge fdb show dev br0
52:54:00:12:34:56 master br0 permanent
52:54:00:ab:cd:ef dev eth0 master br0 
52:54:00:11:22:33 dev tap0 vlan 1 master br0 

The permanent entry is the bridge's own MAC. Learned entries appear without the permanent flag and age out after ageing_time seconds (default 300). An empty FDB except for the permanent entry means no traffic has been seen yet. If you send traffic and the FDB stays empty, the port is not forwarding: check ip link show port for state UP.

Checking STP State

Show detailed STP information with:

# bridge -d link show
4: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding priority 32 cost 4 
    hairpin off guard off root_block off fastleave off learning on flood on mcast_flood on neigh_suppress off vlan_tunnel off

The state forwarding, priority, and cost are STP parameters. If STP is enabled and a port is state blocking, another bridge on the network has a lower priority. To watch MAC learning in real time:

# bridge monitor fdb
52:54:00:99:88:77 dev eth0 master br0 
Deleted 52:54:00:99:88:77 dev eth0 master br0

This streams FDB changes. You see new MACs appear when traffic arrives and deletions when entries age out.

VLAN Filtering on Bridge Ports

Linux bridges can tag and untag VLAN frames on each port, turning the bridge into a VLAN-aware switch. You enable VLAN filtering globally, then assign VLANs to ports with bridge vlan commands. The kernel strips or adds 802.1Q tags as frames cross the bridge, but only if you turn on the global flag.

Enabling VLAN Filtering

VLAN commands are silently ignored unless you enable filtering on the bridge:

# ip link set br0 type bridge vlan_filtering 1

Verify with ip -d link show br0 and check for vlan_filtering 1 in the output. If you forget this step, bridge vlan add returns success but does nothing. The default is 0 (off), so every new bridge needs this command. To make it permanent, add it to your network configuration scripts or use a systemd service that runs on boot.

Tagging and Untagging VLANs on Ports

Add a trunk port carrying tagged VLAN 100:

# bridge vlan add dev eth0 vid 100

Frames arriving on eth0 with VLAN tag 100 are accepted; frames leaving eth0 for VLAN 100 are tagged. For an access port that strips tags on egress and expects untagged frames on ingress:

# bridge vlan add dev eth0 vid 200 pvid untagged

The pvid (port VLAN ID) assigns VLAN 200 to untagged ingress frames. The untagged flag strips the tag on egress. This matches a switchport in access mode. You can combine both: a port can be pvid untagged for VLAN 200 and also carry tagged VLAN 100 for trunk traffic. A common trap: setting pvid without untagged or vice versa. For most access ports you want both; for trunk ports you omit both.

Inspecting VLAN Configuration

Show the VLAN table with:

# bridge vlan show
port    vlan ids
br0     1 PVID Egress Untagged
eth0    1 PVID Egress Untagged
        100
        200 PVID Egress Untagged
tap0    1 PVID Egress Untagged

The default VLAN 1 appears on all ports unless you delete it with bridge vlan del dev eth0 vid 1. PVID means untagged ingress frames get that VLAN; Egress Untagged means frames leaving the port have the tag stripped. If your VMs are not getting network and you see VLAN config on the bridge, compare this output to the upstream switch configuration. A mismatch in pvid or untagged settings will black-hole traffic.

Common Bridge Failures and Fixes

Bridges fail silently. Interfaces show up, the bridge is up, but packets vanish. You check three places: link state, netfilter rules, and VLAN config. Each has a specific tool and a specific output to interpret.

Traffic Not Crossing the Bridge

Start with link state. Check the bridge and every port:

# ip link show br0
4: br0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default 
# ip link show eth0
2: eth0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default 

If eth0 shows state DOWN, bring it up: ip link set eth0 up. If the bridge is state UP but a port is state DOWN, no traffic crosses that port. Next, check the forwarding database:

# bridge fdb show dev br0
52:54:00:12:34:56 master br0 permanent

An empty FDB (only the permanent entry) means the bridge has not learned any MACs. Send a ping from a VM or container and check again. If the source MAC does not appear, the port is not forwarding. Use tcpdump to see where packets stop:

# tcpdump -i eth0 -n icmp
# tcpdump -i br0 -n icmp

If you see packets on eth0 but not on br0, the bridge is not forwarding from that port. Check bridge link show for state forwarding. If STP is on and the port is state blocking, disable STP: ip link set br0 type bridge stp_state 0.

Netfilter Dropping Bridge Packets

If tcpdump shows packets arriving but not leaving, netfilter is probably dropping them. Check the FORWARD chain:

# iptables -L FORWARD -v -n
Chain FORWARD (policy DROP 142 packets, 8520 bytes)
 pkts bytes target     prot opt in     out     source               destination         
    0     0 ACCEPT     all  --  br0    eth1    0.0.0.0/0            0.0.0.0/0           
  142  8520 DROP       all  --  *      *       0.0.0.0/0            0.0.0.0/0           

The policy DROP and the packet counter (142 packets) confirm that iptables is blocking bridge traffic. The fix depends on your needs. If you do not need host-level filtering of guest traffic, disable netfilter on the bridge:

# sysctl -w net.bridge.bridge-nf-call-iptables=0
# sysctl -w net.bridge.bridge-nf-call-ip6tables=0

If you need to filter guests, add an explicit rule before the drop:

# iptables -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT

This accepts all bridged packets. For finer control, match on --physdev-in or --physdev-out. See Firewall Configuration with iptables and firewalld for examples of per-guest rules.

VLAN Mismatch Between Ports

If VLAN filtering is on, a VLAN config error black-holes traffic. Check the VLAN table:

# bridge vlan show
port    vlan ids
br0     1 PVID Egress Untagged
eth0    100
tap0    200 PVID Egress Untagged

Here eth0 expects tagged VLAN 100, but tap0 sends untagged VLAN 200. No traffic crosses. If the upstream switch port is an access port for VLAN 100, configure eth0 the same way:

# bridge vlan del dev eth0 vid 1
# bridge vlan add dev eth0 vid 100 pvid untagged

Use tcpdump -i eth0 -e -n to see VLAN tags in the Ethernet header. If you see vlan 100 in the output, the frames are tagged; if not, they are untagged. Match your pvid untagged settings to what the switch sends. For more on Layer 2 diagnostics, see Linux Network Bridge Monitoring.

Bridge Configuration for KVM and LXC

KVM and LXC create virtual network interfaces for guests; you tell them which bridge to attach those interfaces to. The hypervisor or container runtime handles the veth pair or tap device; you just provide the bridge name in the configuration.

KVM libvirt Bridge Networks

libvirt can create its own bridge (the default virbr0 with NAT) or use an existing bridge. To use your own bridge, define a network with mode='bridge'. Create /etc/libvirt/qemu/networks/br0.xml:

<network>
  <name>br0</name>
  <forward mode='bridge'/>
  <bridge name='br0'/>
</network>

Define and start the network:

# virsh net-define /etc/libvirt/qemu/networks/br0.xml
# virsh net-start br0
# virsh net-autostart br0

In the VM's XML, reference the network by name:

<interface type='network'>
  <source network='br0'/>
</interface>

libvirt creates a tap device and enslaves it to br0 when the VM starts. A common trap: using mode='nat' or omitting the mode attribute entirely. That tells libvirt to create its own bridge with NAT, ignoring yours. Always use mode='bridge' when you want to attach to an existing bridge. The libvirt network XML format documentation covers all modes.

LXC Container Bridge Setup

LXC containers use veth pairs: one end inside the container, one end enslaved to the host bridge. Configure the default bridge in /etc/lxc/default.conf:

lxc.net.0.type = veth
lxc.net.0.link = br0
lxc.net.0.flags = up
lxc.net.0.hwaddr = 00:16:3e:xx:xx:xx

The link = br0 line tells LXC which bridge to use. The flags = up brings the host side of the veth up automatically. LXC generates a random MAC for hwaddr if you omit it. When you start a container, LXC creates the veth pair, enslaves the host end to br0, and moves the container end into the container's network namespace. Check with:

# lxc-start -n mycontainer
# bridge link show master br0
6: vethXXXXXX@if5: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 master br0 state forwarding priority 32 cost 2 

The veth name is random. If the container has no network, check that br0 exists and is up before starting the container, and verify the veth appears in bridge link show. For persistent containers, LXC recreates the veth on every start, so the interface name changes.

Bridge Performance and Security Tuning

Most production bridges run with defaults: STP off, learning on, standard ageing. You tune a bridge when you have specific hardware (VEPA-capable NICs), single-MAC guests that do not need learning, or L2 firewall requirements. These settings change per-port or bridge-wide behavior.

Hairpin Mode and Learning Control

Hairpin mode reflects traffic arriving on a port back out the same port. You need it for VEPA (Virtual Ethernet Port Aggregator) setups where an external switch does the switching. Enable it per-port:

# bridge link set dev eth0 hairpin on

Most VM and container bridges leave hairpin off; guests talk through the bridge, not back out the same port. To disable MAC learning on a port (useful for a tap that will only ever have one MAC):

# bridge link set dev tap0 learning off
# bridge link set dev tap0 flood off

With learning off, the bridge does not add MACs from that port to the FDB. With flood off, unknown-unicast frames are not flooded out that port. This saves CPU on high-traffic bridges with many single-MAC taps. Verify with bridge -d link show dev tap0 and look for learning off flood off.

MAC Table Ageing and L2 Firewalling

The default MAC ageing time is 300 seconds. Reduce it if you have guests that change MACs often (container migration):

# ip link set br0 type bridge ageing_time 30000

The value is in centiseconds, so 30000 = 300 seconds. Check with ip -d link show br0. For Layer 2 firewalling on the bridge itself, use ebtables. iptables sees IP packets after bridging; ebtables sees Ethernet frames during bridging. Example: block ARP from a specific MAC:

# ebtables -A FORWARD -s 52:54:00:aa:bb:cc -p ARP -j DROP

This drops ARP frames from that MAC on any bridge port. For most server workloads you do not need ebtables; guest isolation happens with VLANs or higher-layer firewalls. See Linux Firewall Configuration for separating host and guest security policies.

Persistent Bridge Configuration Across Distributions

Manual ip and bridge commands vanish on reboot. Each distribution has its own config format for persistent network setup. Mixing tools (ifupdown and systemd-networkd on the same host, or NetworkManager and netplan) scatters configuration across files and leaves you debugging which tool won.

Debian and Ubuntu with ifupdown

On Debian and older Ubuntu releases, edit /etc/network/interfaces:

auto br0
iface br0 inet dhcp
    bridge_ports eth0
    bridge_stp off
    bridge_fd 0

The bridge_ports line enslaves eth0. The bridge_stp off disables spanning tree; bridge_fd 0 sets forwarding delay to zero (no learning delay). For a static IP:

iface br0 inet static
    address 192.168.1.10
    netmask 255.255.255.0
    gateway 192.168.1.1
    bridge_ports eth0

The enslaved interface eth0 does not need its own stanza; bridge_ports brings it up automatically. Apply with ifup br0 or reboot. If eth0 already has a config block, remove it or set it to manual.

RHEL, Rocky, and AlmaLinux with network-scripts

On RHEL 8 and clones, create /etc/sysconfig/network-scripts/ifcfg-br0:

DEVICE=br0
TYPE=Bridge
BOOTPROTO=dhcp
ONBOOT=yes
STP=no
DELAY=0

Then edit /etc/sysconfig/network-scripts/ifcfg-eth0:

DEVICE=eth0
TYPE=Ethernet
BOOTPROTO=none
ONBOOT=yes
BRIDGE=br0

The BRIDGE=br0 line enslaves eth0. Remove any IPADDR or NETMASK lines from ifcfg-eth0; the bridge gets the IP. Restart networking with nmcli connection reload and nmcli connection up br0, or reboot. RHEL 9 defaults to NetworkManager; the network-scripts package is optional.

Ubuntu 20.04+ with netplan

Ubuntu 20.04 and later use netplan, which generates config for systemd-networkd or NetworkManager. Edit /etc/netplan/01-netcfg.yaml:

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: no
  bridges:
    br0:
      interfaces: [eth0]
      dhcp4: yes

Apply with netplan apply. For a static IP, replace dhcp4: yes with addresses: [192.168.1.10/24] and gateway4: 192.168.1.1 under br0. The renderer: networkd line tells netplan to generate systemd-networkd config; omit it to use NetworkManager. A common trap: leaving dhcp4: yes on eth0. The enslaved interface must not have an IP config.

systemd-networkd Native Configuration

For distributions using systemd-networkd directly (Arch, some embedded systems), create /etc/systemd/network/br0.netdev:

[NetDev]
Name=br0
Kind=bridge

Then /etc/systemd/network/br0.network:

[Match]
Name=br0

[Network]
DHCP=yes

Finally, enslave eth0 with /etc/systemd/network/eth0.network:

[Match]
Name=eth0

[Network]
Bridge=br0

Restart networkd: systemctl restart systemd-networkd. Check status with networkctl status br0. NetworkManager can also manage bridges with nmcli con add type bridge ifname br0 and nmcli con add type ethernet ifname eth0 master br0, but most server admins avoid NetworkManager for bridges and use netplan or systemd-networkd instead. Mixing tools leaves config in /etc/network/interfaces, /etc/netplan, and /etc/systemd/network simultaneously; pick one and disable the others.

Bridge Troubleshooting Checklist

When a bridge does not forward traffic, work through these steps in order:

  • Check link state: ip link show br0 and ip link show port must both show state UP. Bring up any DOWN interface with ip link set dev up.
  • Verify port membership: bridge link show master br0 must list every port. If a port is missing, enslave it with ip link set port master br0.
  • Inspect the forwarding database: bridge fdb show dev br0. Send traffic and check again. An empty FDB means the port is not forwarding or learning is off.
  • Check netfilter settings: sysctl net.bridge.bridge-nf-call-iptables and sysctl net.bridge.bridge-nf-call-ip6tables should be 0 for most VM/container bridges. If 1, check iptables -L FORWARD -v -n for drops.
  • If VLAN filtering is on (ip -d link show br0 | grep vlan_filtering), verify VLAN config with bridge vlan show. Mismatched pvid or untagged settings black-hole traffic.
  • Use tcpdump -i port -e -n to see where packets stop. Compare ingress and egress on the bridge and each port.

For deeper network troubleshooting techniques, see Linux Network Troubleshooting: A Systematic Approach for Administrators. The Network Bridge Monitoring Cheat Sheet lists all the inspection commands in one place.

Frequently Asked Questions

How do I add a physical interface to an existing Linux bridge?

Enslave the interface with ip link set ethX master br0, then bring it up: ip link set ethX up. Remove any IP address from the interface first with ip addr flush dev ethX. Verify with bridge link show master br0; the interface should appear with state forwarding. If you see state blocking, disable STP on the bridge or wait for STP convergence.

Why is bridge traffic being blocked by iptables rules?

By default, bridged packets traverse the FORWARD chain in iptables. If your host firewall has a DROP policy, guest traffic is blocked. Disable netfilter on the bridge with sysctl -w net.bridge.bridge-nf-call-iptables=0 and sysctl -w net.bridge.bridge-nf-call-ip6tables=0. Make it persistent in /etc/sysctl.d/99-bridge.conf. Alternatively, add an explicit ACCEPT rule for bridged traffic before the drop policy.

What is the difference between brctl and the ip bridge command?

brctl is the legacy tool from the bridge-utils package; ip and bridge are modern replacements from iproute2, which is always installed. brctl addbr becomes ip link add type bridge; brctl addif becomes ip link set master; brctl show becomes bridge link show. The ip and bridge commands expose more kernel features (VLAN filtering, per-port flags) and do not require an extra package. Use them for new scripts.

How do I configure VLAN tagging on a bridge port?

Enable VLAN filtering on the bridge: ip link set br0 type bridge vlan_filtering 1. For a trunk port carrying tagged VLAN 100, run bridge vlan add dev eth0 vid 100. For an access port that strips tags, use bridge vlan add dev eth0 vid 200 pvid untagged. The pvid assigns VLAN 200 to untagged ingress frames; untagged strips the tag on egress. Verify with bridge vlan show.

Why does my bridge MAC table stay empty even with active VMs?

Check that the VM's network interface is actually attached to the bridge with bridge link show master br0. If the port appears but the FDB stays empty, verify the port is state forwarding (not disabled or blocking). Run tcpdump -i port -e to confirm frames are arriving. If learning is explicitly disabled (bridge -d link show dev port shows learning off), enable it with bridge link set dev port learning on. Also check that VLAN filtering is not silently dropping frames due to VLAN mismatch.

Share this article:
Thomas Ellison
About the Author

Thomas Ellison

Database Administration, Applied Mathematics, Technical Education, Documentation

Thomas Ellison is a database administrator and mathematics teacher with a strong focus on structured thinking, data integrity, and reliable system design.

He has extensive experience managing database systems in professional environments, ensuring performance, consistency, and long-term maintainability. His work includ...

Database Administration SQL Data Modeling Performance Optimization Mathematical Foundations

Stay Updated

Subscribe to our newsletter for the latest tutorials, tips, and exclusive offers.