brctl(8) — Linux manual page


BRCTL(8)                                                            BRCTL(8)

NAME         top

       brctl - ethernet bridge administration

SYNOPSIS         top

       brctl [command]

DESCRIPTION         top

       brctl 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 participants.

       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.

INSTANCES         top

       The command brctl addbr <name> creates a new instance of the ethernet
       bridge. The network interface corresponding to the bridge will be
       called <name>.

       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

PORTS         top

       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 in traceroute(8) ).

       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.

AGEING         top

       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
       this bridge.

       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 <time>


       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.)

       brctl(8) 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 are doing.

       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 bridge'.

       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> sets the 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

NOTES         top

       brctl(8) 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.

SEE ALSO         top


AUTHOR         top

       Lennert Buytenhek <> Stephen Hemminger

COLOPHON         top

       This page is part of the bridge-utils (Ethernet bridge utilities)
       project.  Information about the project can be found at [unknown --
       if you know, please contact] If you have a bug
       report for this manual page, send it to  This page
       was obtained from the project's upstream Git repository
       on 2020-09-18.  (At that time, the date of the most recent commit
       that was found in the repository was 2020-06-23.)  If you discover
       any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail

                              November 7, 2001                      BRCTL(8)

Pages that refer to this page: network_namespaces(7)brctl(8)