diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/FAQ | 2 | ||||
| -rw-r--r-- | doc/FIREWALL | 38 | ||||
| -rw-r--r-- | doc/HOWTO | 105 | ||||
| -rw-r--r-- | doc/Makefile.in | 21 | ||||
| -rw-r--r-- | doc/PROJECTS | 2 | ||||
| -rw-r--r-- | doc/RPM-GPG-KEY | 30 | ||||
| -rw-r--r-- | doc/SMPNOTES | 21 | ||||
| -rw-r--r-- | doc/WISHLIST | 25 | ||||
| -rw-r--r-- | doc/brctl.8 | 172 |
9 files changed, 416 insertions, 0 deletions
@@ -0,0 +1,2 @@ +The FAQ is now located at + http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge diff --git a/doc/FIREWALL b/doc/FIREWALL new file mode 100644 index 0000000..7ffff86 --- /dev/null +++ b/doc/FIREWALL @@ -0,0 +1,38 @@ +Bridging and firewalling +------------------------ +It is possible to use bridging in combination with firewalling. This is +a blatant violation of the OSI model, but it's very useful, so we don't +care. + +Assuming you are on a non-stone age kernel (less than 5 years old). +You can use the regular iptables firewalling as if you were doing +routing. So, rules for forwarding are added to the FORWARD chain, +rules for input to the local machine are added to the INPUT chain, +etc. Things will work like you expect them to. +So a rule like + + # iptables -A INPUT -i eth0 -j DROP + +will drop all traffic coming from 'eth0', even if the interface the packets +are logically from is, say, 'br0'. + + + +Lennert Buytenhek, November 7th 2001 +<buytenh@gnu.org> + + + +-------------------------- +Bridge+firewalling with 2.2 kernels is also possible, but deprecated. I +would severely recommend against using a 2.2 kernel and ipchains for bridge +firewalling. But if there's really a need, it's still possible. Apply the +extra firewalling patch available from the 'patches' section to your +already-patched-with-the-vanilla-bridge-patch 2.2 kernel, and recompile. Now +if you boot this kernel, the bridging code will check each to-be-forwarded +packet against the ipchains chain which has the same name as the bridge. So.. +if a packet on eth0 is to be forwarded to eth1, and those interfaces are +both part of the bridge group br0, the bridging code will check the packet +against the chain called 'br0'. If the chain does not exist, the packet will +be forwarded. So if you want to do firewalling, you'll have to create the +chain yourself. This is important! diff --git a/doc/HOWTO b/doc/HOWTO new file mode 100644 index 0000000..3729618 --- /dev/null +++ b/doc/HOWTO @@ -0,0 +1,105 @@ +Hello everybody, + +Although there is a man page which documents most of the actual +commands, there is still a 'gap' concerning what bridges are, and how +to set them up. This document attempts to fill this gap. + +In fact, this document is a 15-min hack, so feel free to {complain +about,improve on} it. Especially if this document (or the FAQ) does +not tell you what you want to know; I would consider that to be a bug. + + +Have fun! +Lennert Buytenhek + + +<================= CUT HERE AND DAMAGE YOUR SCREEN =================> + + + +1. The basics +------------- + +What does a bridge actually do? In plain English, a bridge connects +two or more different physical ethernets together to form one large +(logical) ethernet. The physical ethernets being connected together +correspond to network interfaces in your linux box. The bigger +(logical) ethernet corresponds to a virtual network interface in linux +(often called br0, br1, br2, etc.) + +Let's say we want to tie eth0 and eth1 together, turning those +networks into one larger network. What do we do? Well, we need to +create an instance of the bridge first. + + # brctl addbr br0 + +(You can check that this gives you a network interface called br0.) +Now we want to enslave eth0 and eth1 to this bridge. + + # brctl addif br0 eth0 + # brctl addif br0 eth1 + +And now... because we connected the two ethernets together, they now +form one large subnet. We are actually only on only one subnet, namely +br0. We can forget about the fact that br0 is actually eth[01] in +disguise; we will only deal with br0 from now on. Because we are only +on one subnet, we only need one IP address for the bridge. This +address we assign to br0. eth0 and eth1 should not have IP addresses +allocated to them. + + # ifconfig eth0 0.0.0.0 + # ifconfig eth1 0.0.0.0 + # ifconfig br0 my.ip.address.here + +The last command also puts the interface br0 into the 'up' state. This +will activate the forwarding of packets, which in plain English means +that from that point on, eth0 and eth1 will be 'joined' +together. Hosts on eth0 should 'see' hosts on eth1 and vice versa. + +The bridge will also (automatically) activate the Spanning Tree +Protocol: this is a network protocol spoken by switches for (roughly +speaking) calculating the shortest distances and eliminating loops in +the topology of the network. You can disable the stp if you really +want/need to; see brctl(8) for details. + + + +2. More complicated setups +-------------------------- + +We can create multiple bridge port groups and do filtering/NATting +between them, just like we can do that with ordinary network +interfaces. + +For example: on a quadport network card, dedicate two ports to a LAN +on which we have IP 10.16.0.254, and the other two ports to a LAN on +which we have IP 192.168.10.1 (this is an actual setup) + + # brctl addbr br_10 + # brctl addif br_10 eth0 + # brctl addif br_10 eth1 + # ifconfig br_10 10.16.0.254 + + # brctl addbr br_192 + # brctl addif br_192 eth2 + # brctl addif br_192 eth3 + # ifconfig br_192 192.168.10.1 + +You now have logical network interfaces br_10 and br_192, which will +act just like ordinary interfaces. The only difference is that they +each correspond to two physical network interfaces, but nobody cares +about that. + +So.. for example, if 192.168.10.2 is the only host on the 192.* +network that is allowed to access the 10.* network, we would do: + +ipchains -P forward REJECT +ipchains -A forward -s 192.168.10.2/32 -d 10.0.0.0/8 -i br_10 -j ACCEPT + +(just like you were used to). + + + + + +Hope this helped. If not, send a cry for help to the mailing list. diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..23bfb06 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,21 @@ + +DESTDIR= +KERNEL_HEADERS=-I@KERNEL_HEADERS@ + +INSTALL=@INSTALL@ + +prefix=@prefix@ +exec_prefix=@exec_prefix@ +bindir=@bindir@ +sbindir=@sbindir@ +mandir=@mandir@ + +SUBDIRS=libbridge brctl + +all: + +clean: + +install: + mkdir -p $(DESTDIR)$(mandir)/man8 + $(INSTALL) -m 644 brctl.8 $(DESTDIR)$(mandir)/man8 diff --git a/doc/PROJECTS b/doc/PROJECTS new file mode 100644 index 0000000..de6dfb3 --- /dev/null +++ b/doc/PROJECTS @@ -0,0 +1,2 @@ +- Kristian Rietveld <kristian@planet.nl> is working on a GNOME + interface. diff --git a/doc/RPM-GPG-KEY b/doc/RPM-GPG-KEY new file mode 100644 index 0000000..83b1956 --- /dev/null +++ b/doc/RPM-GPG-KEY @@ -0,0 +1,30 @@ +Hi, + +This public key is the GPG public key I use to sign the bridge-utils +and bridge-utils-devel RPM packages. You can use this key to verify +the integrity of those packages. + +Lennert Buytenhek +<buytenh@gnu.org> + + + + +-----BEGIN PGP PUBLIC KEY BLOCK----- +Version: GnuPG v1.0.1 (GNU/Linux) +Comment: For info see http://www.gnupg.org + +mQGiBDiT6YIRBADbn6OduygntL0gYcBD3333gje45DSWl0PVghw9CtJQUZRZSBFp +Z1CgkxI1F3kza4gJwIj/fgtuC8PWi1200rOwCLL8kLkFIH9Zy0VEuXskoXLeDU/f +V14e+9GVtoVLQ5Bx2bTez3+2dEU7N0axKH5MJQsyWZx+U863unNk/qGO1wCgjYZ5 +zKhTuvWnR51tYjdwbfXyq0sD/iflTEUFkQ0MEQc/eJ+RU9kL55GyhT7f227CR6XZ +/d2LCUkdaCdihAsJLXEL66gS7MOUd5I6dolPXG0vG0wQMBqt/jcKr2JRZsSf2Zjg +IxTvlv+6h6LyaHBiq45yCAE1KC2ka2ebtdK0BubdRjKlxDMmGJMrMTeK6RsLbDej +SEhqBACTtgUO9gOAFB53TAAjpftMW91mTOiokg1znKxqunbJ/4Ndo9Z9KI1m4wH8 +RsyGJBEkwlR5PNjnLZbE0ET2hk01RLFWX8yDXORXDx1bkcW/NJgMkyUua3A2QaTV +D1SdIfnMLB2vg4FzjUdo9QXS+zNQ24jS7G6tDq8McvVM2DSwp7Q3TGVubmVydCBC +dXl0ZW5oZWsgKFJQTSBzaWduYXR1cmUga2V5KSA8YnV5dGVuaEBnbnUub3JnPohW +BBMRAgAWBQI4k+mCBAsKBAMDFQMCAxYCAQIXgAAKCRD/CxH2tC7NLt6pAKCGnrIT +EfdFTc5S/Fz+LAYokMWKTwCfU7DQG4bkaOJTcv5fRUOD4UZ2MTk= +=om8h +-----END PGP PUBLIC KEY BLOCK----- diff --git a/doc/SMPNOTES b/doc/SMPNOTES new file mode 100644 index 0000000..ba54836 --- /dev/null +++ b/doc/SMPNOTES @@ -0,0 +1,21 @@ +Notes on the (20000210) SMP-ization of the bridging code: + +Each bridge has a hash table of MAC addresses. This table is protected +by a rwlock hash_lock. The entries are refcounted; 'getting' an entry +is done in the usual way: read_lock the table, find the entry, +increment it's refcount and unlock the table. Bottom half context +acquires this lock in read as well as write mode, therefore we always +need to locally disable BHs when acquiring this lock. + +Each bridge also has an rwlock called lock. This slightly misnamed +lock protects the bridge's port_list. All stp code acquires this lock +in read mode, the only piece of code that acquires this lock in write +mode is the ioctl code (br_ioctl.c). Bottom halves never acquire this +lock in write mode, therefore we can use read_lock instead of +read_lock_bh in all cases. + +All ioctls are globally serialized by the semaphore ioctl_mutex. All +code which acquires the bridge lock in write mode also acquires +ioctl_mutex. Therefore, if we have already grabbed ioctl_mutex we +don't need to read_lock the bridge lock anymore; the ioctl_mutex will +protect against concurrent writers. diff --git a/doc/WISHLIST b/doc/WISHLIST new file mode 100644 index 0000000..43ca124 --- /dev/null +++ b/doc/WISHLIST @@ -0,0 +1,25 @@ +Would be nice if: + +- Add address learning limiting (hard limit at a fixed # of + addresses? or maybe using rate markers?). There is a nasty DoS in + here. + +- Add fdb entry port # change limiting. For example: if one MAC + address switches port more than once in the same second, there is + something wrong (somebody trying to spoof?), so print a warning. + +- Faster port state cycling; currently it takes 30 seconds for ports + to cycle to the forwarding state. + +- Detect port speed and adjust path cost accordingly? + +- Use MII ioctls for detecting link beat lost quickly? + +- Keep the IEEE 802.1d-mandated statistics (counters, mostly). + +- Maybe integrate Kristian's GNOME frontend (see PROJECTS) once it + stabilises. It looks nice. + +- A cgi bridge configurer (a la Samba's SWAT, yummy....) + + diff --git a/doc/brctl.8 b/doc/brctl.8 new file mode 100644 index 0000000..a708bc1 --- /dev/null +++ b/doc/brctl.8 @@ -0,0 +1,172 @@ +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +.\" +.\" +.TH BRCTL 8 "November 7, 2001" "" "" +.SH NAME +brctl \- ethernet bridge administration +.SH SYNOPSIS +.BR "brctl [command]" +.SH DESCRIPTION +.B 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. + + +.SH INSTANCES +The command +.B brctl addbr <name> +creates a new instance of the ethernet bridge. The network interface +corresponding to the bridge will be called <name>. + +The command +.B 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 +.B brctl show +shows all current instances of the ethernet bridge. + + +.SH PORTS +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 +.IR traceroute(8) +). + +The command +.B 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 +.B brctl delif <brname> <ifname> +will detach the interface <ifname> from the bridge <brname>. + +The command +.B brctl show <brname> +will show some information on the bridge and its attached ports. + + +.SH AGEING +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. + +.B brctl showmacs <brname> +shows a list of learned MAC addresses for this bridge. + +.B 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). + +.B 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> seconds. + + +.SH SPANNING TREE PROTOCOL +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 +01:80:c2:00:00:00. + +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.) + +.IR 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. + +.B 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. + + +.B 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'. + +.B brctl setfd <bridge> <time> +sets the bridge's 'bridge forward delay' to <time> seconds. + +.B brctl sethello <bridge> <time> +sets the bridge's 'bridge hello time' to <time> seconds. + +.B brctl setmaxage <bridge> <time> +sets the bridge's 'maximum message age' to <time> seconds. + +.B brctl setpathcost <bridge> <port> <cost> +sets the port cost of the port <port> to <cost>. This is a +dimensionless metric. + +.B 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 algorithms. + + +.SH NOTES +.BR brctl(8) +replaces the older brcfg tool. + +.SH SEE ALSO +.BR ipchains(8), +.BR iptables(8) + +.SH AUTHOR +Lennert Buytenhek <buytenh@gnu.org> |