brctl Bridge Control

brctl cheatsheet — create bridges, add interfaces, show bridge status. brctl addbr br0, brctl addif br0 eth0, brctl show. Linux network bridging reference.

5 min read

What it is

brctl is a command-line utility for controlling and inspecting Ethernet bridges on Linux systems, primarily used for managing network bridging for virtual machines or network segmentation.

Installation

Linux

brctl is typically part of the bridge-utils package.

# Debian/Ubuntu
sudo apt update
sudo apt install bridge-utils

# Fedora/CentOS/RHEL
sudo dnf install bridge-utils
# or
sudo yum install bridge-utils

Mac

brctl is not available on macOS. macOS uses networksetup and other built-in tools for network configuration.

Windows

brctl is not available on Windows. Windows uses its own Network Bridge feature through the GUI or PowerShell cmdlets like New-NetBridgeAdapter.

Core Concepts

Bridge: A software switch that forwards network traffic between network interfaces (physical or virtual) connected to it. It operates at Layer 2 (Data Link Layer) of the OSI model.
Interface: A network adapter (e.g., eth0, wlan0, tap0) that can be attached to a bridge.
MAC Address Table (Forwarding Database): The bridge learns which MAC addresses are reachable on which of its interfaces and uses this table to forward frames efficiently.
STP (Spanning Tree Protocol): A network protocol that ensures a loop-free topology by disabling redundant paths. brctl can be used to configure STP on a bridge.

Commands / Usage

Creating and Deleting Bridges

Create a new bridge:
```
sudo brctl addbr br0
```
Creates a new bridge device named br0.
Delete a bridge:
```
sudo brctl delbr br0
```
Deletes the bridge device br0. The bridge must be down and have no interfaces attached for deletion.

Adding and Removing Interfaces

Add an interface to a bridge:
```
sudo brctl addif br0 eth0
```
Attaches the network interface eth0 to the bridge br0. The interface eth0 must be up.
Remove an interface from a bridge:
```
sudo brctl delif br0 eth0
```
Detaches the network interface eth0 from the bridge br0.

Bridge Status and Information

List all bridges:
```
brctl show
```
Displays a list of all active bridges on the system, showing their interfaces.
Show detailed information about a specific bridge:
```
brctl show br0
```
Shows the interfaces attached to bridge br0 and its current configuration (STP status, etc.).
Show bridge forwarding database (MAC address table):
```
brctl showmacs br0
```
Displays the MAC addresses learned by bridge br0, along with the interface they were learned on and their age.
Show STP status for a bridge:
```
brctl showstp br0
```
Displays the Spanning Tree Protocol status for bridge br0, including port states (forwarding, blocking, etc.).

STP Configuration

Enable STP on a bridge:
```
sudo brctl stp br0 on
```
Enables Spanning Tree Protocol on bridge br0 to prevent network loops.
Disable STP on a bridge:
```
sudo brctl stp br0 off
```
Disables Spanning Tree Protocol on bridge br0. This is generally not recommended in complex networks.
Set bridge priority:
```
sudo brctl setbridgeprio br0 32768
```
Sets the priority of bridge br0. Lower values have higher priority in STP election. The default is 32768.
Set interface path cost:
```
sudo brctl setpathcost br0 eth0 10
```
Sets the Spanning Tree Protocol path cost for interface eth0 on bridge br0. Lower costs are preferred.
Set interface priority:
```
sudo brctl setportprio br0 eth0 128
```
Sets the Spanning Tree Protocol priority for interface eth0 on bridge br0. Lower values have higher priority.
Set hello time:
```
sudo brctl sethellotime br0 2
```
Sets the STP hello time (in seconds) for bridge br0. The default is 2 seconds.
Set forward delay:
```
sudo brctl setfwdelay br0 15
```
Sets the STP forward delay (in seconds) for bridge br0. This is the time a port stays in the listening and learning states before transitioning to forwarding. The default is 15 seconds.

Common Patterns

Setting up a basic bridge for VMs: This involves creating a bridge, bringing it up, adding a physical interface to it, and then adding virtual interfaces (e.g., from virt-manager or docker) to the bridge.
1. Create and bring up the bridge:
```
sudo brctl addbr br0
sudo ip link set br0 up
```
2. Add a physical interface (e.g., eth0) to the bridge:
```
sudo brctl addif br0 eth0
```
3. (Optional) Remove the IP address from the physical interface if the bridge will have an IP:
```
sudo ip addr flush dev eth0
```
4. (Optional) Assign an IP address to the bridge:
```
sudo ip addr add 192.168.1.100/24 dev br0
sudo ip route add default via 192.168.1.1
```
5. Now, virtual interfaces (like tap0 or veth pairs) can be added to br0.
Viewing learned MAC addresses on a bridge:
```
brctl showmacs br0
```
Useful for debugging connectivity issues between VMs or containers connected to the same bridge.
Disabling STP on a simple, isolated bridge (e.g., for Docker):
```
sudo brctl stp br0 off
```
Docker often manages its own network segmentation and may not require STP.
Checking which interface is connected to which bridge:
```
brctl show
```
This is the go-to command for a quick overview.

Gotchas

Interface must be UP: You cannot add an interface to a bridge if the interface itself is not in the UP state. Use sudo ip link set eth0 up before adding it.
Bridge must be UP: Similarly, the bridge device itself needs to be brought up using sudo ip link set br0 up before interfaces can be reliably added or traffic passed.
IP Address on Physical Interface: If you add a physical interface (like eth0) to a bridge, it’s generally recommended to remove the IP address from the physical interface itself (sudo ip addr flush dev eth0) and assign the IP address to the bridge device (br0) instead. Otherwise, you might experience routing conflicts or unexpected behavior.
STP and Loops: While STP prevents network loops, it can introduce latency and complex state management. For simple, contained bridging scenarios (like many Docker setups), disabling STP might be desired, but be aware of the risks in larger, interconnected networks.
Persistence: Changes made with brctl are typically not persistent across reboots. You’ll need to use network configuration files (e.g., /etc/network/interfaces on Debian/Ubuntu, NetworkManager configurations, or systemd-networkd) to make bridge configurations permanent.
Permissions: Most brctl commands require root privileges (sudo).
IPv6: brctl primarily deals with Layer 2 bridging. IPv6 configuration on bridges is usually handled by separate tools like ip6tables and radvd.