Linux BRIDGE-STP-HOWTO Uwe Böhme           Johann-Heinrich-Abt-Straße 7           95213           Münchberg           Germany           +49/9251 960877           +49/9251 960878           uwe@bnhof.de          Lennert Buytenhenk bridge code maintainer and developer gnu.org           buytenh@gnu.org          Release v0.04 Copyright © 2000 by Uwe Böhme Revision History Revision v0.04 11 January 2001 Revised by: U.B. Changed Lennert`s Bridge Homepage URL; added NIC to list. Revision v0.03 17 July 2000 Revised by: U.B. Overwork pdf. Download links in doc. Revision v0.02 16 July 2000 Revised by: U.B. Fixed broken graphics in html dsl. Prepared pdf. Typos. Revision v0.01 25 June 2000 Revised by: U.B. Changes name from BRIDGE-HOWTO to BRIDGE-STP-HOWTO (avoid interference with BRIDGE-HOWTO by Christopher Cole) and kill version 1.xx. Lennert Buytenhenk announced as coauthor. Revision v0.00 01 June 2000 Revised by: U.B. Initial Release. ----------------------------------------------------------------------------- Table of Contents 1. License 2. Document Home and Downloads 2.1. The Bridge Sources And Utilities 2.2. The Mailing-List 2.3. This Document 3. What Is A Bridge? 4. Rules On Bridging 5. Preparing The Bridge 5.1. Get The Files 5.2. Apply The Patches 5.3. Configure The Kernel 5.4. Compile The Kernel 5.5. Compile The Bridge Utilities 6. Set Up The Bridge 6.1. brctl Command Synopsis 6.2. Basic Setup 7. Advanced Bridge Features 7.1. Spanning Tree Protocol 7.2. Bridge And The IP-Chains 8. A Practical Setup Example 8.1. Hardware-setup 8.2. Software-setup 8.3. See It Work 8.4. Bridge Tests 8.4.1. Tear The Patch Wire Test 8.4.2. Kill The Root Bridge Test A. Network Interface Cards B. Recommended Reading C. FAQ About The Linux Modular Bridge And STP This document describes how to setup a bridge with the recent kernel patches and brctl utility by Lennert Buytenhek. and tries to explain about the STP implementation in this code. With developer kernel 2.3.47 the new bridging code is part of the mainstream. There are patches for stable kernels 2.2.14 to 2.2.16, where each is also available as a ipchains-patch. ----------------------------------------------------------------------------- 1. License Copyright (c) 2000 by Uwe Böhme. This document may be distributed only subject to the terms and conditions set forth in the LDP License available at [http://www.linuxdoc.org//manifesto.html] http://www.linuxdoc.org/ ----------------------------------------------------------------------------- 2. Document Home and Downloads 2.1. The Bridge Sources And Utilities Official url is [http://www.math.leidenuniv.nl/~buytenh/bridge/] http:// www.math.leidenuniv.nl/~buytenh/bridge/. With developer kernel 2.3.47 the new bridging code is part of the mainstream. ----------------------------------------------------------------------------- 2.2. The Mailing-List The Bridge-Mailinglist is homed at [http://www.math.leidenuniv.nl/mailman/ listinfo/bridge] http://www.math.leidenuniv.nl/mailman/listinfo/bridge. ----------------------------------------------------------------------------- 2.3. This Document This document has it's official homepage at [http://www.bnhof.de/~uwe/ bridge-stp-howto/BRIDGE-STP-HOWTO/] http://www.bnhof.de/~uwe/bridge-stp-howto /BRIDGE-STP-HOWTO/. It's a part of the Linux Documentation Project located at [http://www.linuxdoc.org/] http://www.linuxdoc.org/. Download Types and Locations Build environment as tar.gziped file [http://www.bnhof.de/~uwe/bridge-stp-howto/BRIDGE-STP-HOWTO.tar.gz] http: //www.bnhof.de/~uwe/bridge-stp-howto/BRIDGE-STP-HOWTO.tar.gz HTML-gziped file [http://www.bnhof.de/~uwe/bridge-stp-howto/BRIDGE-STP-HOWTO.html.tar.gz] http://www.bnhof.de/~uwe/bridge-stp-howto/BRIDGE-STP-HOWTO.html.tar.gz PDF-gziped file [http://www.bnhof.de/~uwe/bridge-stp-howto/BRIDGE-STP-HOWTO.pdf.gz] http: //www.bnhof.de/~uwe/bridge-stp-howto/BRIDGE-STP-HOWTO.pdf.gz PS-gziped file [http://www.bnhof.de/~uwe/bridge-stp-howto/BRIDGE-STP-HOWTO.ps.gz] http:/ /www.bnhof.de/~uwe/bridge-stp-howto/BRIDGE-STP-HOWTO.ps.gz ----------------------------------------------------------------------------- 3. What Is A Bridge? A bridge is a device that separates two or more network segments within one logical network (e.g. a single IP-subnet). A bridge is usually placed between two separate groups of computers that talk with each other, but not that much with the computers in the other group. A good example of this is to consider a cluster of Macintoshes and a cluster of Unix machines. Both of these groups of machines tend to be quite chatty amongst themselves, and the traffic they produce on the network causes collisions for the other machines who are trying to speak to one another. The job of the bridge is to examine the destination of the data packets one at a time and decide whether or not to pass the packets to the other side of the Ethernet segment. The result is a faster, quieter network with less collisions. The bridging code decides whether to bridge data or to drop it not by looking at the protocol type (IP, IPX, NetBEUI), but by looking at the MAC-address unique to each NIC. Important: It's vital to understand that a bridge is neither a router nor a fire-wall. Spoken in simple term a bridge behaves like a network switch (i.e. Layer 2 Switch), making it a transparent network component (which is not absolutely true, but nearly). Read more about this at Section 4. In addition, you can overcome hardware incompatibilities with a bridge, without leaving the address-range of your IP-net or subnet. E.g. it's possible to bridge between different physical media like 10 Base T and 100 Base TX. My personal reason for starting to set up a bridge was that in my work I had to connect Fast Ethernet components to a existing HP Voice Grade network, which is a proprietary networking standard. Features Above Pure Bridging STP The Spanning Tree Protocol is a nifty method of keeping Ethernet devices connected in multiple paths working. The participating switches negotiate the shortest available path by STP. This feature will be discussed in Section 7.1. Multiple Bridge Instances Multiple bridge instances allow you to have more than one bridge on your box up and running, and to control each instance separately. Fire-walling There is a patch to the bridging code which allows you to use IP chains on the interface inside a bridge. More info about this you'll find at Section 7.2. ----------------------------------------------------------------------------- 4. Rules On Bridging There is a number of rules you are not allowed to break (otherwise your bridge will do).   * A port can only be a member of one bridge.   * A bridge knows nothing about routes.   * A bridge knows nothing about higher protocols than ARP. That's the reason why it can bridge any possible protocol possibly running on your Ethernet.   * No matter how many ports you have in your logical bridge, it's covered by only one logical interface   * As soon as a port (e.g. a NIC) is added to a bridge you have no more direct control about it. +---------------------------------------------------------------------------+ | Warning | +---------------------------------------------------------------------------+ |If one of the points mentioned above is not clear to you now, don't | |continue reading. Read the documents listed in Appendix B first. | +---------------------------------------------------------------------------+ If you ever tried to ping an unmanaged switch, you will know that it doesn't work, because you don't have a IP-address for it. To switch datagrams it doesn't need one. The other thing is if you want to manage the switch. It's too much strain, to take a dumb terminal, walk to the place you installed it (normally a dark, dusty and warm room, with a lot of green and red Christmas lights), to connect the terminal and to change the settings. What you want is remote management, usually by SNMP, telnet, rlogin or (best) ssh. For all this services you will need a IP. That's the exception to the transparency. The new code allows you without any problem to assign a IP address to the virtual interface formed by the bridge-instance you will create in Section 6.2. All NIC's (or other interfaces) in your bridge will happily listen and respond to datagrams destined to this IP. All other data will not interfere with the bridge. The bridge just acts like a switch. ----------------------------------------------------------------------------- 5. Preparing The Bridge This section describes what you need and how you do to prepare your bridge. ----------------------------------------------------------------------------- 5.1. Get The Files Here you can find a list of the files and down-loads you will need for the setup of the bridge. If you have one of the mentioned files or packages on your distribution, of course there is no need to create network load. I'll only mention the files for the 2.2.14 kernel. If you want to try a different one (e.g. 2.2.15 or the recent development kernel) just replace the kernel version number and look whether you find it. Important: You have read the abstract, didn't you? So you know that there is no need to download any kernel-patch if you're working with a kernel later than 2.3.47. File and package list Unpatched kernel-sources E.g. linux-2.2.14.tar.bz2 available from your local kernel.org mirror. Please check first if you find it in your distribution (take unpatched kernel-sources). If you don't, please check The Linux Kernel Archive Mirror System for a close by mirror and down-load it from there. Bridge patches Note: If your kernel is later than 2.3.47 you don't need this. The bridging is part of the mainstream from that version. Get the bridge kernel patches for your kernel version from [http:// www.math.leidenuniv.nl/~buytenh/bridge/] http://www.math.leidenuniv.nl/ ~buytenh/bridge/. Identify the file by the kernel number. Note: There are also patches allowing to work with IP chains. I never tried it, for I don't see the need to fire-wall inside my LAN, and absolutely no need to bridge against the outer world. Feel free to contribute about that issue. Kernel patches for the stable 2.2 kernel. Available Kernel patches bridge-0.0.9-against-2.2.18.diff, the main kernel patch against 2.2.18 [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-0.0.9-against-2.2.18.diff] http://www.math.leidenuniv.nl/ ~buytenh/bridge/patches/bridge-0.0.9-against-2.2.18.diff bridge-ipchains-against-0.0.9-against-2.2.18.diff, an add-on patch for bridge firewalling against 2.2.18 [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.9-against-2.2.18.diff] http:// www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.9-against-2.2.18.diff bridge-0.0.8-against-2.2.18pre19.diff, the main kernel patch against 2.2.18pre19. [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-0.0.8-against-2.2.18pre19.diff] http://www.math.leidenuniv.nl/ ~buytenh/bridge/patches/bridge-0.0.8-against-2.2.18pre19.diff bridge-0.0.8-against-2.2.17-0.5.diff, the main kernel patch against 2.2.17-0.5 [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-0.0.8-against-2.2.17-0.5.diff] http://www.math.leidenuniv.nl/ ~buytenh/bridge/patches/bridge-0.0.8-against-2.2.17-0.5.diff bridge-ipchains-against-0.0.8-against-2.2.18pre19.diff, an add-on patch for bridge firewalling against 2.2.18pre19 [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.8-against-2.2.18pre19.diff] http:// www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.8-against-2.2.18pre19.diff bridge-ipchains-against-0.0.8-against-2.2.17-0.5.diff, an add-on patch for bridge firewalling against 2.2.17-0.5 [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.8-against-2.2.17-0.5.diff] http:// www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.8-against-2.2.17-0.5.diff bridge-0.0.7-against-2.2.18pre15.diff, the main kernel patch against 2.2.18pre15 [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-0.0.7-against-2.2.18pre15.diff] http://www.math.leidenuniv.nl/ ~buytenh/bridge/patches/bridge-0.0.7-against-2.2.18pre15.diff bridge-ipchains-against-0.0.7-against-2.2.18pre15.diff, an add-on patch for bridge firewalling against 2.2.18pre15 [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.7-against-2.2.18pre15.diff] http:// www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.7-against-2.2.18pre15.diff bridge-0.0.7-against-2.2.17.diff, the main kernel patch against 2.2.17 [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-0.0.7-against-2.2.17.diff] http://www.math.leidenuniv.nl/ ~buytenh/bridge/patches/bridge-0.0.7-against-2.2.17.diff bridge-ipchains-against-0.0.7-against-2.2.17.diff, an add-on patch for bridge firewalling against 2.2.17 [http://www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.7-against-2.2.17.diff] http:// www.math.leidenuniv.nl/~buytenh/bridge/patches/ bridge-ipchains-against-0.0.7-against-2.2.17.diff Bridge configuration utilities You also will need the bridge configuration utilities to set up the bridge Section 6. You can also download them from [http:// www.math.leidenuniv.nl/~buytenh/bridge/] http://www.math.leidenuniv.nl/ ~buytenh/bridge/. ----------------------------------------------------------------------------- 5.2. Apply The Patches Note: If your kernel is later than 2.3.47 you don't need this. The bridging is part of the mainstream from that version. Apply the bridging patch your kernel. If you don`t know how to do that read the Kernel-HOWTO which can be found in your distribution or at [http:// www.linuxdoc.org/HOWTO/Kernel-HOWTO.html] http://www.linuxdoc.org/HOWTO/ Kernel-HOWTO.html Example 1. Applying a kernel patch root@mbb-1:~ # cd /usr/src/linux-2.2.14 root@mbb-1:/usr/src/linux-2.2.14 # patch -p1 < \ bridge-0.0.5-against-2.2.14.diff . . ----------------------------------------------------------------------------- 5.3. Configure The Kernel Now it's time we configure our freshly patched kernel to create the ability to bridge. Run make config, make menuconfig or the click-o-rama make xconfig. Select bridging in the networking option section to be compiled as a module. AFAIK there is no strong reason why not to compile it as a kernel module, whereas I heard rumors about problems with compiling the bridging code directly into the kernel. root@mbb-1:~ # cd /usr/src/linux-2.2.14 root@mbb-1:/usr/src/linux-2.2.14 # make menuconfig . ----------------------------------------------------------------------------- 5.4. Compile The Kernel Compile your kernel Example 2. Make the new compiled kernel-image to be loaded. I don't know if the kernel patches only apply to the bridging-module or also modify some interfaces inside vmlinuz. So it might not be a error to give a reboot after you updated the kernel-image. Example 2. Commands To Compile Your Kernel root@mbb-1:/usr/src/linux-2.2.14 # make dep clean zImage modules modules_install zlilo ... ----------------------------------------------------------------------------- 5.5. Compile The Bridge Utilities This is how to compile and install from the scratch. Just unzip the utilities-tarball, cd into the newly created directory and give a make. Example 3. Commands To Compile Your Bridge-Utilities root@mbb-1:/usr/src/linux-2.2.14 # cd /usr/local/src root@mbb-1:/usr/local/src/ # tar xzvf bridge-utils-0.9.1.tar.gz ..... .... root@mbb-1:/usr/local/src # cd bridge root@mbb-1:/usr/local/src/bridge # make ..... .... After the compilation shown in Example 3 have worked properly, you can copy the executables to let's say /usr/local/sbin/ (at least I did). So the commands you have to give should be clear, but to be complete see Example 4 Example 4. Copy The Binaries Of The Utilities root@mbb-1:/usr/local/src/bridge # cd brctl root@mbb-1:/usr/local/src/bridge/brctl # cp brctl /usr/local/sbin root@mbb-1:/usr/local/src/bridge/brctl # chmod 700 /usr/local/sbin/brctl root@mbb-1:/usr/local/src/bridge/brctl # cp brctld /usr/local/sbin root@mbb-1:/usr/local/src/bridge/brctl # chmod 700 /usr/local/sbin/brctld Also now you can copy the new man-page to a decent place, as shown in Example 5. Example 5. Copy The Man-page Of brctl root@mbb-1:/usr/local/src/bridge # cd doc root@mbb-1:/usr/local/src/bridge/doc # gzip -c brctl.8 > /usr/local/man/man8/brctl.8.gz ----------------------------------------------------------------------------- 6. Set Up The Bridge Make sure all your network cards are working nicely and are accessible. If so, ifconfig will show you the hardware layout of the network-interface. If you have problems making your cards work please read the Ethernet-HOWTO at [http://www.linuxdoc.org/HOWTO/Ethernet-HOWTO.html] http://www.linuxdoc.org/ HOWTO/Ethernet-HOWTO.html. Don't mess around with IP-addresses or net-masks. You will not need it, until you bridge fully operational an up. After you did the steps mentioned above a modprobe -v bridge should show no errors. You can check the success by issuing a cat /proc/modules. Also for each of the network cards you want to use in the bridge the ifconfig whateverNameYourInterfaceHas should give you some information about the interface. If your bridge-utilities have been correctly built and your kernel and bridge-module are OK, then issuing a brctl should show a small command synopsis. ----------------------------------------------------------------------------- 6.1. brctl Command Synopsis root@mbb-1:~ # brctl commands: addbr add bridge (1) addif add interface to bridge (2) delbr delete bridge (3) delif delete interface from bridge (4) show show a list of bridges (5) showbr show bridge info (6) showmacs show a list of mac addrs (7) setageing