brctl - ethernet bridge administration
is used to set up, maintain, and inspect the ethernet bridge
configuration in the Linux kernel.
An ethernet bridge is a device commonly used to connect different networks of
ethernets together, so that these ethernets will appear as one ethernet to the
Each of the ethernets being connected corresponds to one physical interface in
the bridge. These individual ethernets are bundled into one bigger ('logical')
ethernet, this bigger ethernet corresponds to the bridge network interface.
The command brctl addbr <name>
creates a new instance of the
ethernet bridge. The network interface corresponding to the bridge will be
The command brctl delbr <name>
deletes the instance <name> of
the ethernet bridge. The network interface corresponding to the bridge must be
down before it can be deleted!
The command brctl show
shows all current instances of the ethernet
Each bridge has a number of ports attached to it. Network traffic coming in on
any of these ports will be forwarded to the other ports transparently, so that
the bridge is invisible to the rest of the network (i.e. it will not show up
The command brctl addif <brname> <ifname>
will make the
interface <ifname> a port of the bridge <brname>. This means that
all frames received on <ifname> will be processed as if destined for the
bridge. Also, when sending frames on <brname>, <ifname> will be
considered as a potential output interface.
The command brctl delif <brname> <ifname>
will detach the
interface <ifname> from the bridge <brname>.
The command brctl show <brname>
will show some information on the
bridge and its attached ports.
The bridge keeps track of ethernet addresses seen on each port. When it needs to
forward a frame, and it happens to know on which port the destination ethernet
address (specified in the frame) is located, it can 'cheat' by forwarding the
frame to that port only, thus saving a lot of redundant copies and transmits.
However, the ethernet address location data is not static data. Machines can
move to other ports, network cards can be replaced (which changes the
machine's ethernet address), etc.
brctl showmacs <brname>
shows a list of learned MAC addresses for
brctl setageing <brname> <time>
sets the ethernet (MAC)
address ageing time, in seconds. After <time> seconds of not having seen
a frame coming from a certain address, the bridge will time out (delete) that
address from the Forwarding DataBase (fdb).
brctl setgcint <brname> <time>
sets the garbage collection
interval for the bridge <brname> to <time> seconds. This means
that the bridge will check the forwarding database for timed out entries every
Multiple ethernet bridges can work together to create even larger networks of
ethernets using the IEEE 802.1d spanning tree protocol. This protocol is used
for finding the shortest path between two ethernets, and for eliminating loops
from the topology. As this protocol is a standard, Linux bridges will
interwork properly with other third party bridge products. Bridges communicate
with each other by sending and receiving BPDUs (Bridge Protocol Data Units).
These BPDUs can be recognised by an ethernet destination address of
The spanning tree protocol can also be turned off (for those situations where it
just doesn't make sense, for example when this Linux box is the only bridge on
the LAN, or when you know that there are no loops in the topology.)
can be used for configuring certain spanning tree protocol
parameters. For an explanation of these parameters, see the IEEE 802.1d
specification (or send me an email). The default values should be just fine.
If you don't know what these parameters mean, you probably won't feel the
desire to tweak them.
brctl stp <bridge> <state>
controls this bridge instance's
participation in the spanning tree protocol. If <state> is
"on" or "yes" the STP will be turned on, otherwise it will
be turned off. When turned off, the bridge will not send or receive BPDUs, and
will thus not participate in the spanning tree protocol. If your bridge isn't
the only bridge on the LAN, or if there are loops in the LAN's topology, DO
NOT turn this option off. If you turn this option off, please know what you
brctl setbridgeprio <bridge> <priority>
sets the bridge's
priority to <priority>. The priority value is an unsigned 16-bit
quantity (a number between 0 and 65535), and has no dimension. Lower priority
values are 'better'. The bridge with the lowest priority will be elected 'root
brctl setfd <bridge> <time>
sets the bridge's 'bridge forward
delay' to <time> seconds.
brctl sethello <bridge> <time>
sets the bridge's 'bridge
hello time' to <time> seconds.
brctl setmaxage <bridge> <time>
sets the bridge's 'maximum
message age' to <time> seconds.
brctl setpathcost <bridge> <port> <cost>
sets the port
cost of the port <port> to <cost>. This is a dimensionless metric.
brctl setportprio <bridge> <port> <priority>
port <port>'s priority to <priority>. The priority value is an
unsigned 8-bit quantity (a number between 0 and 255), and has no dimension.
This metric is used in the designated port and root port selection algorithms.
is obsolete. Some features such as STP guard, harpin mode,
fastleave and root block are intentionally not implemented in this command.
Instead use bridge
command from iproute2
package for a more full
set of features.
Lennert Buytenhek <email@example.com> Stephen Hemminger