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.
Creating a Bridge with ip link and bridge
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 br0andip link show portmust both showstate UP. Bring up anyDOWNinterface withip link set dev up. - Verify port membership:
bridge link show master br0must list every port. If a port is missing, enslave it withip 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-iptablesandsysctl net.bridge.bridge-nf-call-ip6tablesshould be 0 for most VM/container bridges. If 1, checkiptables -L FORWARD -v -nfor drops. - If VLAN filtering is on (
ip -d link show br0 | grep vlan_filtering), verify VLAN config withbridge vlan show. Mismatchedpvidoruntaggedsettings black-hole traffic. - Use
tcpdump -i port -e -nto 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.