brctl: Ethernet Bridge Administration

brctl: Ethernet Bridge Administration

brctl is a classic tool for managing Ethernet bridges on Linux. It’s simple to use for quick tasks, but note that newer systems may prefer iproute2 for some bridge operations. This guide focuses on practical, common tasks with concrete examples.

Quickstart: what you can do with brctl

  • Show current bridges and their ports
  • Create a new bridge
  • Delete a bridge
  • Add an interface to a bridge
  • Remove an interface from a bridge

All commands typically require root privileges (sudo).

1) Show existing bridges

What it does: lists bridges and their member interfaces.

sudo brctl show

Common output tells you the bridge name, bridge ID, STP status, and ports.

Common pitfall: if you don’t see any bridges, it might be because the bridge module isn’t loaded or you’re running in a container with limited network namespace support.

2) Create a new bridge

What it does: creates a new bridge device you can attach interfaces to.

sudo brctl add {{bridge_name}}

Example:

sudo brctl add br0

Pitfall: creating the bridge does not automatically move any interfaces into it. You must add interfaces with brctl addif.

3) Delete a bridge

What it does: removes the bridge device. The bridge must be empty (no ports) before deletion.

sudo brctl del {{bridge_name}}

Example:

sudo brctl del br0

If the bridge still has ports, remove them first with brctl delif or detach them from the interface.

4) Add an interface to a bridge

What it does: attaches a network interface to an existing bridge.

sudo brctl addif {{bridge_name}} {{interface_name}}

Example:

sudo brctl addif br0 eth0

Common pitfall: bringing the interface up after adding it to the bridge is often necessary, but in many setups the bridge will handle the traffic once the port is added. If you don’t see traffic, check the interface state and IP configuration.

5) Remove an interface from a bridge

What it does: detaches an interface from a bridge but does not delete the interface itself.

sudo brctl delif {{bridge_name}} {{interface_name}}

Example:

sudo brctl delif br0 eth0

After removing, you may want to reconfigure the interface (e.g., assign it to the host or another bridge).

Common pitfalls and tips

  • sudo needed: brctl usually requires root privileges.
  • Not all distros install brctl by default anymore; if commands fail, install the bridge utilities package (often named bridge-utils).
  • Brnetplan/iproute2: Some modern Linux distributions managing bridges with iproute2 tools (ip) instead of brctl. For many tasks, you can use ip link set, ip addr, and ip link set dev br0 up. brctl remains functional but is considered legacy in some setups.
  • Ensure the bridge is up: after creating a bridge and adding ports, bring the bridge up with:
sudo ip link set dev {{bridge_name}} up
  • When troubleshooting connectivity, verify:
    • The member interfaces are up or enslaved to the bridge
    • IP addresses are assigned to the bridge (not to the member interfaces) if you’re using the bridge as the gateway
    • Spanning Tree Protocol (STP) settings if you rely on it; brctl show can display STP status

Quick reference cheatsheet

  • List bridges:
    • sudo brctl show
  • Create a bridge:
    • sudo brctl add br0
  • Delete a bridge (only if empty):
    • sudo brctl del br0
  • Add interface to bridge:
    • sudo brctl addif br0 eth0
  • Remove interface from bridge:
    • sudo brctl delif br0 eth0

If you’re on a system where brctl is deprecated, consider using iproute2 equivalents or consult your distro’s networking guide for the recommended bridge management workflow.

See Also