Linux network -- Bridge

[Copy from http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge]

bridge

A bridge is a way to connect two Ethernetsegments together in a protocol independent way. Packets are forwardedbased on Ethernet address, rather than IP address (like a router).Since forwarding is done at Layer 2, all protocols can go transparentlythrough a bridge.

The Linux bridge code implements a subset of the ANSI/IEEE 802.1d standard. [1].The original Linux bridging was first done in Linux 2.2, then rewrittenby Lennert Buytenhek. The code for bridging has been integrated into2.4 and 2.6 kernel series.

Bridging and Firewalling

A Linux bridge is more powerful than a pure hardware bridge becauseit can also filter and shape traffic. The combination of bridging andfirewalling is done with the companion projectebtables.

Status

The code is updated as part of the 2.4 and 2.6 kernels available at kernel.org.

Possible future enhancements are:

• Document STP filtering
• Netlink interface to control bridges (prototype in 2.6.18)
• STP should be in user space
• Support RSTP and other 802.1d STP extensions

Downloading

Bridging is supported in the current 2.4 (and 2.6) kernels from allthe major distributors. The required administration utilities are inthe bridge-utils package in most distributions. Package releases aremaintained on theDownload page.

You can also build your own up to date version by getting the latest kernel fromkernel.org and build the utilities based from the source code in bridge-utils GIT repository.

 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/bridge-utils.git
 $ cd bridge-utils
 $ autoconf
 $ ./configure

Kernel Configuration

You need to enable bridging in the kernel. Set "networking -> 802.1d Ethernet Bridging" to either yes or module

Manual Configuration

Network cards

Before you start make sure both network cards are set up and workingproperly. Don't set the IP address, and don't let the startup scriptsrun DHCP on the ethernet interfaces either. The IP address needs to beset after the bridge has been configured.

The command ifconfig should show both network cards, and they should be DOWN.

Module loading

In most cases, the bridge code is built as a module. If the moduleis configured and installed correctly, it will get automatically loadedon the first brctl command.

If your bridge-utilities have been correctly built and your kerneland bridge-module are OK, then issuing a brctl should show a smallcommand synopsis.

# brctl
# commands:
        addbr           <bridge>                add bridge
        delbr           <bridge>                delete bridge
        addif           <bridge> <device>       add interface to bridge
        delif           <bridge> <device>       delete interface from bridge
        setageing       <bridge> <time>         set ageing time
        setbridgeprio   <bridge> <prio>         set bridge priority
        setfd           <bridge> <time>         set bridge forward delay
        sethello        <bridge> <time>         set hello time
        setmaxage       <bridge> <time>         set max message age
        setpathcost     <bridge> <port> <cost>  set path cost
        setportprio     <bridge> <port> <prio>  set port priority
        show                                    show a list of bridges
        showmacs        <bridge>                show a list of mac addrs
        showstp         <bridge>                show bridge stp info
        stp             <bridge> <state>        turn stp on/off

Creating a bridge device

The command

 brctl addbr "bridgename"

creates a logical bridge instance with the name bridgename.You will need at least one logical instance to do any bridging at all.You can interpret the logical bridge as a container for the interfacestaking part in the bridging. Each bridging instance is represented by anew network interface.

The corresponding shutdown command is:

 brctl delbr bridgename

Adding devices to a bridge

The command

 brctl addif bridgename device

adds the network device device to take part in the bridging of"bridgename." All the devices contained in a bridge act as one bignetwork. It is not possible to add a device to multiple bridges orbridge a bridge device, because it just wouldn't make any sense! Thebridge will take a short amount of time when a device is added to learnthe Ethernet addresses on the segment before starting to forward.

The corresponding command to take an interface out of the bridge is:

 brctl delif  bridgename device

Showing devices in a bridge

The brctl show command gives you a summary about the overall bridge status, and the instances running as shown below:

 # brctl addbr br549
 # brctl addif br549 eth0
 # brctl addif br549 eth1
 # brctl show
 bridge name     bridge id               STP enabled     interfaces
 br549           8000.00004c9f0bd2       no              eth0
                                                         eth1

Once a bridge is running the brctl showmacs will showinformation about network addresses of traffic being forwarded (and thebridge itself).

 # brctl showmacs br549
 port no mac addr                is local?       ageing timer
   1     00:00:4c:9f:0b:ae       no                17.84
   1     00:00:4c:9f:0b:d2       yes                0.00
   2     00:00:4c:9f:0b:d3       yes                0.00
   1     00:02:55:1a:35:09       no                53.84
   1     00:02:55:1a:82:87       no                11.53
  ...

The aging time is the number of seconds a MAC address will bekept in the forwarding database after having received a packet fromthis MAC address. The entries in the forwarding database areperiodically timed out to ensure they won't stay around forever.Normally there should be no need to modify this parameter, but it canbe changed with (time is in seconds).

  # brctl setageing bridgename time

Setting ageing time to zero makes all entries permanent.

Spanning Tree Protocol

If you are running multiple or redundant bridges, then you need to enable the Spanning Tree Protocol (STP) to handle multiple hops and avoid cyclic routes.

 # brctl stp br549 on

You can see the STP parameters with:

 # brctl showstp br549
 br549
  bridge id              8000.00004c9f0bd2
  designated root        0000.000480295a00
  root port                 1                    path cost                104
  max age                  20.00                 bridge max age           200.00
  hello time                2.00                 bridge hello time         20.00
  forward delay           150.00                 bridge forward delay      15.00
  ageing time             300.00                 gc interval                0.00
  hello timer               0.00                 tcn timer                  0.00
  topology change timer     0.00                 gc timer                   0.33
  flags
 
 eth0 (1)
  port id                8001                    state                   forwarding
  designated root        0000.000480295a00       path cost                100
  designated bridge      001e.00048026b901       message age timer         17.84
  designated port        80c1                    forward delay timer        0.00
  designated cost           4                    hold timer                 0.00
  flags
 
 eth1 (2)
  port id                8002                    state                   disabled
  designated root        8000.00004c9f0bd2       path cost                100
  designated bridge      8000.00004c9f0bd2       message age timer          0.00
  designated port        8002                    forward delay timer        0.00
  designated cost           0                    hold timer                 0.00
  flags

STP tuning

There are a number of parameters related to the Spanning Tree Protocolthat can be configured. The code autodetects the speed of the link andother parameters, so these usually don't need to be changed.

Bridge priority

Each bridge has a relative priority and cost. Each interface isassociated with a port (number) in the STP code. Each has a priorityand a cost, that is used to decide which is the shortest path toforward a packet. The lowest cost path is always used unless the otherpath is down. If you have multiple bridges and interfaces then you mayneed to adjust the priorities to achieve optimium performance.

  # brctl setbridgeprio bridgename priority

The bridge with the lowest priority will be elected as theroot bridge. The root bridge is the "central" bridge in the spanningtree.

Path priority and cost

Each interface in a bridge could have a different speed and thisvalue is used when deciding which link to use. Faster interfaces shouldhave lower costs.

 # brctl setpathcost bridge port cost

For multiple ports with the same cost there is also a priority

Forwarding delay

Forwarding delay time is the time spent in each of the Listening andLearning states before the Forwarding state is entered. This delay isso that when a new bridge comes onto a busy network it looks at sometraffic before participating.

 #  brctl setfd bridgename time

Hello time

Periodically, a hello packet is sent out by the Root Bridge and theDesignated Bridges. Hello packets are used to communicate informationabout the topology throughout the entire Bridged Local Area Network.

 # brctl sethello bridgename time

Max age

If a another bridge in the spanning tree does not send out a hellopacket for a long period of time, it is assumed to be dead. Thistimeout is set with:

 # brctl maxage  bridgename time

Multicast (IGMP) snooping

IGMP snooping support is not yet included in bridge-utils oriproute2, but it can be easily controlled through sysfs interface. ForbrN, the settings can be found under/sys/devices/virtual/net/brN/bridge.

multicast_snooping

This option allows the user to disable IGMP snoopingcompletely. It also allows the user to reenable snooping when it hasbeen automatically disabled due to hash collisions. If the collisionshave not been resolved however the system will refuse to reenablesnooping.

multicast_router

This allows the user to forcibly enable/disable ports ashaving multicast routers attached. A port with a multicast router willreceive all multicast traffic.

The value 0 disables it completely. The default is 1 which lets thesystem automatically detect the presence of routers (currently this islimited to picking up queries), and 2 means that the ports will alwaysreceive all multicast traffic.

Note: this setting can be enabled/disable on a per-port basis, alsothrough sysfs interface (e.g. if eth0 is some bridge's active port,then you can adjust /sys/...../eth0/brport/multicast_router)

hash_{max,elasticity}

These settings allow the user to control the hashelasticity/max parameters. The elasticity setting does not take effectuntil the next new multicast group is added. At which point it ischecked and if after rehashing it still can't be satisfied thensnooping will be disabled.

The max setting on the other hand takes effect immediately. It mustbe a power of two and cannot be set to a value less than the currentnumber of multicast group entries. This is the only way to shrink themulticast hash.

remaining multicast_* options

These allow the user to control various values related to IGMP snooping.

More details about the options, some discussions and rationale can be found inhttp://thread.gmane.org/gmane.linux.network/153338

Sample setup

The basic setup of a bridge is done like:

 # ifconfig eth0 0.0.0.0
 # ifconfig eth1 0.0.0.0
 # brctl addbr mybridge
 # brctl addif mybridge eth0
 # brctl addif mybridge eth1 
 # ifconfig mybridge up

This will set the host up as a pure bridge, it will not havean IP address for itself, so it can not be remotely accessed (orhacked) via TCP/IP.

Optionally you can configure the virtual interface mybridge to takepart in your network. It behaves like one interface (like a normalnetwork card). Exactly that way you configure it, replacing theprevious command with something like:

 # ifconfig mybridge 192.168.100.5 netmask 255.255.255.0

If you want your bridge to automatically get its IP address from the ADSL modem via DHCP (or a similar configuration), do this:

 # ifconfig eth0 0.0.0.0
 # ifconfig eth1 0.0.0.0
 # brctl addbr mybridge
 # brctl addif mybridge eth0
 # brctl addif mybridge eth1 
 # dhclient mybridge

If you do this many times, you may end up with lots of dhclient processes. Either kill them impolitely or learn aboutomshell(1).

Configuration with /etc/net

In /etc/net we first configure two ethernet devices port0 and port1:

 # cat >> /etc/net/iftab
 port0 mac 00:13:46:66:01:5e
 port1 mac 00:13:46:66:01:5f
 ^D
 # mkdir /etc/net/ifaces/port0
 # cat > /etc/net/ifaces/port0/options
 TYPE=eth
 MODULE=via-rhine
 # mkdir /etc/net/ifaces/port1
 # cat > /etc/net/ifaces/port1/options
 TYPE=eth
 MODULE=via-rhine
 ^D

Then we describe the bridge:

 # mkdir /etc/net/ifaces/mybridge
 # cat > /etc/net/ifaces/mybridge/options
 TYPE=bri
 HOST='port0 port1'
 ^D
 # cat > /etc/net/ifaces/mybridge/brctl
 stp AUTO on
 ^D

Now we can use "ifup mybridge" to bring it up. port0 and port1 will be brought up automatically.

FAQ

What does a bridge do?

A bridge transparently relays traffic between multiple networkinterfaces. In plain English this means that a bridge connects two ormore physical Ethernets together to form one bigger (logical) Ethernet.

Is it protocol independent?

Yes. The bridge knows nothing about protocols, it only sees Ethernetframes. As such, the bridging functionality is protocol independent,and there should be no trouble relaying IPX, NetBEUI, IP, IPv6, etc.

Why is this code better than a switch?

Please note that this code wasn't written with the intent of havingLinux boxes take over from dedicated networking hardware. Don't see theLinux bridging code as a replacement for switches, but rather as anextension of the Linux networking capabilities. Just as there aresituations where a Linux router is better than a dedicated router (andvice versa), there are situations where a Linux bridge is better than adedicated bridge (and vice versa).

Most of the power of the Linux bridging code lies in itsflexibility. There is a whole lot of bizarre stuff you can do withLinux already (read Linux Advanced Routing and Traffic Control documentto see some of the possiblities), and the bridging code adds some morefilter into the mix.

One of the most significant advantages of a Linux solution over adedicated solution that come to mind is Linux' extensive firewallingcapabilities. It is possible to use the full functionality of netfilter(iptables) in combination with bridging, which provides way morefunctionality than most proprietary offerings do.

Why is this code worse than a switch?

In order to act a a bridge, the network device must be placed intopromiscuous mode which means it receives all traffic on a network. On areally busy network, this can eat significant bandwidth out of theprocessor, memory slowing the system down. The answer is to setupeither a separate dedicated Linux box as the bridge, or use a hardwareswitch.

What is the performance of the bridge?

The performance is limited by the network cards used and theprocessor. A research paper was done by James Yu at Depaul Universitycomparing Linux bridging with a Catalyst switchYu-Linux-TSM2004.pdf

My bridge does not show up in traceroute!

It's not supposed to. The operation of a bridge is (supposed to be)fully transparent to the network, the networks that a bridge connectstogether are actually to be viewed as one big network. That's why thebridge does not show up in traceroute; the packets do not feel likethey are crossing a subnet boundary.

For more information on this, read a book about TCP/IP networking.

It doesn't work!

It says: "br_add_bridge: bad address" when I try to add a bridge!

Either your kernel is old (2.2 or earlier), or you forgot to configure Ethernet bridging into your kernel.

No traffic gets trough (except ARP and STP)

Your kernel might have ethernet filtering (ebtables, bridge-nf,arptables) enabled, and traffic gets filtered. The easiest way todisable this is to go to /proc/sys/net/bridge. Check if the bridge-nf-*entries in there are set to 1; in that case, set them to zero and tryagain.

 # cd /proc/sys/net/bridge
 # ls
 bridge-nf-call-arptables  bridge-nf-call-iptables
 bridge-nf-call-ip6tables  bridge-nf-filter-vlan-tagged
 # for f in bridge-nf-*; do echo 0 > $f; done

Does bridging work on 2.2?

The base kernel for 2.2, did not support the current bridging code.The original development was on 2.2, and there used to be patchesavailable for it. But these patches are no longer maintained.

Are there plans for RSTP (802.1w) support?

Yes, work is being done to integrate RSTP support in a future 2.6release. The code was done for a version of 2.4 and needs to be cleanedup, tested and updated.

What can be bridged?

Linux bridging is very flexible; the LAN's can be either traditionalEthernet device's, or pseudo-devices such as PPP, VPN's or VLAN's. Theonly restrictions are that the devices:

• All devices share the same maximum packet size (MTU). The bridge doesn't fragment packets.
• Devices must look like Ethernet. i.e have 6 byte source and destination address.
• Support promiscuous operation. The bridge needs to be able toreceive all network traffic, not just traffic destined for its ownaddress.
• Allow source address spoofing. The bridge must be able to send data over network as if it came from another host.

Can I do bridging in combination with netfilter/iptables?

Yes. The code for this is available in most kernels. See ebtables project.

Does it work with Token Ring , FDDI, or Firewire?

No, the addressing and frame sizes are different.

I keep getting the message retransmitting tcn bpdu!

It means that your Linux bridge is retransmitting a Topology ChangeNotification Bridge Protocol Data Unit (so now you know what theletters are for :-). Seriously, there is probably another switch (orLinux bridge) nearby that isn't complying to the rules of the spanningtree protocol (which is what bridges speak).

In each bridged local area network, there is one 'master bridge',which is also called the root bridge. You can find out which bridgethis is using brctl.

When the topology of a bridged local area network changes (f.e.somebody unplugs a cable between two bridges), the bridge which detectsthis sends a topology change notification to the root bridge. The rootbridge will respond to this by setting a 'topology changed' bit in thehello packets it sends out for the next X seconds (X usually being 30).This way, all bridges will learn of the topology change, so that theycan take measures like timing out learned MAC entries faster forexample.

After having sent out a topology change notification, if a bridgedoes not find the 'topology changed' bit set in the hello packetsreceived (which in essence serves as the 'acknowledgment' of thetopology change notification), it concludes that the topology changenotification was lost. So it will retransmit it. However, some bridgesrun lobotomized implementations of the Spanning Tree Protocol whichcauses them not to acknowledge topology change notifications. If youhave one of those bridges as your root bridge, all of the other bridgeswill keep retransmitting their topology changed notifications. Whichwill lead to these kinds of syslog messages.

There are a number of things you can do:

• Find out which bridge is the root bridge, find out where it islocated, and what internetworking software it runs. Please report thisinfo to the mailing list (or to me directly), so that I can keep ablacklist.
• Force the linux bridge to be the root bridge. See what the priorityof the current root bridge is, and use the brctl 'setbridgeprio'command to set the priority of the linux bridge to 1 lower. (The bridgewith the lowest priority always becomes the root bridge.)
• Disable the spanning tree protocol on your linux bridge altogether.In this case, watch out for bridging loops! If you have loops in yourtopology, and if no bridge in the loop is running the spanning treeprotocol, mayhem will come your way, as packets will be forwardedforever. Don't Do This(TM).

It doesn't work with my regular Ethernet card!

Unfortunately, some network cards have buggy drivers that fail underload. The situation is improving, so having a current kernel andnetwork driver can help. Also try swapping with another brand.

Please report all problems to the Bridge mailing list: bridge@osdl.org. If your network card doesn't work (even without bridging) then try the Linux networking mailing listlinux-net@vger.kernel.org

It doesn't work with my Wireless card!

This is a known problem, and it is not caused by the bridge code.Many wireless cards don't allow spoofing of the source address. It is afirmware restriction with some chipsets. You might find someinformation in the bridge mailing list archives to help. Has anyonefound a way to get around Wavelan not allowing anything but its own MACaddress? (answer by Michael Renzmann (mrenzmann at compulan.de))

Well, for 99% of computer users there will never be a way to get ridof this. For this function a special firmware is needed. This firmwarecan be loaded into the RAM of any WaveLAN card, so it could do its jobwith bridging. But there is no documentation on the interface availableto the public. The only way to achieve this is to have a full versionof the hcf library which controls every function of the card and alsoallows accessing the card's RAM. To get this full version Lucent wantsto know that it will be a financial win for them, also you have to signan NDA. So be sure that you won't most probably get access to thispeace of software until Lucent does not change its mind in this (whichI doubt never will happen).

If you urgently need to have a wireless LAN card which is able tobridge, you should use one of those having the prism chipset onboard(manufactured by Harris Intersil). There are drivers for those cardsavailable atwww.linux-wlan.com(which is the website from Absoval), and I found a mail that says thatthere is the necessary firmware and an upload tool available for Linuxto the public. If you need additional features of an access point youshould also talk to Absoval.

I still don't understand!!

Doing full bridging of wireless (802.11) requires supporting WDS . The current implementation doesn't do it.

It is possible to do limited wireless to Ethernet functionality withsome wireless drivers. This requires the device to be able to support adifferent sender address and source address. That is what WDS provides.

There are ways to make it work, but it is not always straightforwardand you probably won't get it right without a pretty solidunderstanding of 802.11, it's modes, and the frame header format.

I get the error 'too much work in interrupt'

This is because the network card is getting lots of packets. Thereare a few things you can try. First, build the driver with NAPI support(if it isn't on by default). NAPI means the driver will do the receiveprocessing at soft IRQ, not at the low level interrupt.

If the driver doesn't support NAPI, you can try to increase theamount of work a driver will attempt to do in an interrupt. For 3c59xthis is done with the option max_interrupt_work (so add something like'options 3c59x max_interrupt_work=10000' to your /etc/modules.conffile), other cards might have similar options.

Does DHCP work over/through a bridge?

The bridge will forward DHCP traffic (broadcasts) and responses. Youcan also use DHCP to set the local IP address of the bridgepseudo-interface.

One common mistake is that the default bridge forwarding delaysetting is 30 seconds. This means that for the first 30 seconds afteran interface joins a bridge, it won't send anything. This is because ifthe bridge is being used in a complex topology, it needs to discoverother bridges and not create loops. This problem was one of the reasonsfor the creation of Rapid Spanning Tree Protocol (RSTP).

If the bridge is being used standalone (no other bridges near by).Then it is safe to turn the forwarding delay off (set it to zero),before adding interface to a bridge. Then you can run DHCP client rightaway.

 # brctl setfd br0 0
 # brctl addif br0 eth0
 # dhclient eth0

Contact Info

The code is currently maintained by Stephen Hemminger <shemminger@osdl.org> for both 2.4 and 2.6 Linux. Bridge bugs and enhancements are discussed on the Bridge mailing list<bridge@osdl.org>. The list is open to anyone interested, use the web mailman interfacehttp://lists.osdl.org/mailman/listinfo/bridge to subscribe.

External Links

• Ethernet VPN bridging
• Ebtables firewalling
• Ethernet-bridge HOWTO
• Linux-bridge STP HOWTO
• wikipedia:Spanning_tree_protocol
• Understanding Spanning-Tree Protocol (Cisco)