Initial revision

11 files changed, 558 insertions, 0 deletions

diff --git a/doc/FAQ b/doc/FAQ
new file mode 100644
index 0000000..ed1d05b
--- /dev/null
+++ b/doc/FAQ
@@ -0,0 +1,80 @@
+Hi,
+
+If you have still unanswered questions after reading the HOWTO and the
+FAQ, you have found a bug. Please report bugs to bridge@openrock.net
+
+
+greetings,
+Lennert Buytenhek
+
+
+
+Questions that were Asked Frequently enough to get listed here
+==============================================================
+
+
+
+What does a bridge do?
+----------------------
+  A bridge transparently relays traffic between multiple network
+  interfaces. In plain English this means that a bridge connects two
+  or more physical ethernets together to form one bigger (logical)
+  ethernet.
+
+
+Is it protocol independent?
+---------------------------
+  Yes. The bridge knows nothing about protocols, it only sees ethernet
+  frames. As such, the bridging functionality is protocol independent,
+  and there should be no trouble relaying IPX, NetBEUI, IP, IPv6, etc.
+
+
+How is this bridging stuff different from a so-called 'switch'?
+---------------------------------------------------------------
+  It isn't.
+
+
+Why is your code better than a switch?
+--------------------------------------
+  First of all, my code wasn't written with the intent of having linux
+  boxen take over from dedicated networking hardware. Don't see the
+  linux bridging code as a replacement for switches, but rather as an
+  extension of the linux networking capabilities. Just like there are
+  situations where a linux router/dedicated brand router is better
+  than the other, there are situations where a linux bridge/dedicated
+  brand bridge is better than the other.
+
+  Most of the power of the linux bridging code lies in its
+  flexibility. There is a whole lot of bizarre stuff you can do with
+  linux already (read the 2.4 Advanced Routing document at
+  http://ds9a.nl if you're interested), and the bridging code merely
+  adds some more possibilities for obfuscation into the mix.
+
+  The most important uses for the linux bridge code I see as follows:
+  - Small bridges (up to 8 ports).
+  - Load sharing a server's traffic over multiple interfaces by
+    connecting sets of clients to different physical network
+    interfaces.
+  - A transparent firewall solution (using the ipchains/iptables
+    firewalling patch).
+
+
+My bridge does not show up in traceroute!
+-----------------------------------------
+  It is supposed not to. The operation of a bridge is (supposed to be)
+  fully transparent to the network, the networks that a bridge
+  connects together are actually to be viewed as one big
+  network. That's why the bridge does not show up in traceroute; the
+  packets do not feel like they are crossing a subnet boundary.
+
+  For more information on this, read a book about TCP/IP networking.
+
+
+Are there plans for MAC address filtering?
+------------------------------------------
+  You should be able to firewall on MAC addresses with the 2.4
+  firewalling patch. iptables has the ability to filter on MAC
+  addresses, and the firewalling patch should add that capability to
+  the bridging code. I only released the first incarnation of the 2.4
+  firewalling patch yesterday though, so don't expect this to be
+  stable yet.
diff --git a/doc/FIREWALL b/doc/FIREWALL
new file mode 100644
index 0000000..ea000ee
--- /dev/null
+++ b/doc/FIREWALL
@@ -0,0 +1,35 @@
+Several people have asked me for ipchains firewalling on bridge
+forwarding. Although this is a violation of the OSI model it turns out
+to be very useful, and it was very easy to implement, so I did it.
+
+Now how does it work?
+
+First of all, if you want to use bridge firewalling, you'll have to
+apply the extra patch bridge-ipchains.diff in the bridge-utils
+distribution to your (already patched with the bridge patch) kernel
+tree. Recompile the kernel.
+
+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!
+
+
+
+Example:
+# brctl addbr br0
+# brctl addif br0 eth0
+# brctl addif br0 eth1
+# ifconfig br0 10.0.0.254
+# ipchains -N br0
+# ipchains -A br0 -s 10.0.0.1/8 -i eth0 -j DENY
+
+
+
+Lennert Buytenhek
+<buytenh@openrock.net>
diff --git a/doc/FIREWALL.IPTABLES b/doc/FIREWALL.IPTABLES
new file mode 100644
index 0000000..7ba69d4
--- /dev/null
+++ b/doc/FIREWALL.IPTABLES
@@ -0,0 +1,53 @@
+It is now possible to use iptables to firewall on bridge
+forwarding. It works mostly like the 2.2 patch, but with this
+difference that the packets are just passed to the 'main' chains.
+
+As of current, the bridge calls into the PRE_ROUTING, FORWARD, and
+POST_ROUTING netfilter ipv4 hooks. This means all IP packets that
+enter the bridge will be passed over the PREROUTING chain, if they are
+to be forwarded they will be tested against the FORWARD chain, and for
+every device that they are to leave, they are tested against the
+POSTROUTING chain.
+
+
+Example
+-------
+
+bash# iptables -L -v
+Chain INPUT (policy ACCEPT 74 packets, 7943 bytes)
+ pkts bytes target     prot opt in     out     source               destination
+
+Chain FORWARD (policy ACCEPT 14 packets, 1176 bytes)
+ pkts bytes target     prot opt in     out     source               destination
+   13  1092 LOG        all  --  any    any     anywhere             anywhere           LOG level warning prefix `FWD '
+
+Chain OUTPUT (policy ACCEPT 127 packets, 12269 bytes)
+ pkts bytes target     prot opt in     out     source               destination
+bash# iptables -L -v -t nat
+Chain PREROUTING (policy ACCEPT 6 packets, 504 bytes)
+ pkts bytes target     prot opt in     out     source               destination
+    5   420 LOG        all  --  any    any     anywhere             anywhere           LOG level warning prefix `PRE '
+
+Chain POSTROUTING (policy ACCEPT 11 packets, 864 bytes)
+ pkts bytes target     prot opt in     out     source               destination
+   10   780 LOG        all  --  any    any     anywhere             anywhere           LOG level warning prefix `PST '
+
+Chain OUTPUT (policy ACCEPT 5 packets, 360 bytes)
+ pkts bytes target     prot opt in     out     source               destination
+bash# /data/bd/bridge-utils/brctl/brctl show
+bridge name     bridge id               STP enabled     interfaces
+br0             8000.fefd00000000       no              tap0
+                                                        tap1
+bash# cat packet > /dev/tap0
+PRE IN=tap0 OUT= MAC=fe:fd:31:32:33:34:fe:fd:34:33:32:31:08:00 SRC=10.20.30.40 DST=10.30.40.50 LEN=84 TOS=0x00 PREC=0x00 TTL=64
+ID=0 DF PROTO=ICMP TYPE=8 CODE=0 ID=56329 SEQ=2304
+FWD IN=tap0 OUT=tap1 SRC=10.20.30.40 DST=10.30.40.50 LEN=84 TOS=0x00 PREC=0x00 TTL=64 ID=0 DF PROTO=ICMP TYPE=8 CODE=0 ID=56329
+SEQ=2304
+PST IN= OUT=tap1 SRC=10.20.30.40 DST=10.30.40.50 LEN=84 TOS=0x00 PREC=0x00 TTL=64 ID=0 DF PROTO=ICMP TYPE=8 CODE=0 ID=56329 SEQ=2304
+bash#
+
+
+
+
+Lennert Buytenhek
+<buytenh@openrock.net>
diff --git a/doc/HOWTO b/doc/HOWTO
new file mode 100644
index 0000000..e01d946
--- /dev/null
+++ b/doc/HOWTO
@@ -0,0 +1,110 @@
+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 (see
+http://openrock.net/mailman/listinfo/bridge for more information), or
+send me an email at buytenh@openrock.net
+
+
+That's all folks!
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..67e38bb
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,5 @@
+all:			FAQ HOWTO PROJECTS RPM-GPG-KEY TODO
+
+clean:
+			rcsclean *
+			rm -f *~
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/TODO b/doc/TODO
new file mode 100644
index 0000000..3e6aca9
--- /dev/null
+++ b/doc/TODO
@@ -0,0 +1,23 @@
+Longer term:
+
+- We have a tiny deviation from IEEE 802.1d: we don't kill the awaiting-tx
+  skb queue when a port leaves the FORWARDING state. Not that anyone
+  should care. But it's there.
+
+- For the firewall add-on patch:
+  - Firewalling on input or output interface?
+
+- RH initscripts for setting up bridge interfaces automatically. Right
+  now, on my home machines, I kludge a bit. Things ought to be
+  transparent, just like the bonding stuff.
+
+- The telnet server thingy (brctld) is too limited: it does not do
+  authentication (should be easy with PAM though), but more
+  importantly: it does not allow setting up/down of devices and
+  configuring of IP addresses. Without these, it is essentially useless.
+
+- Improve documentation:
+	* man page
+	* FAQ
+	* HOWTO
+	  rewrite bridging howtos and update Configure.help to reflect that
diff --git a/doc/WISHLIST b/doc/WISHLIST
new file mode 100644
index 0000000..fdc664c
--- /dev/null
+++ b/doc/WISHLIST
@@ -0,0 +1,28 @@
+Would be nice if:
+
+- Get the 802.1d tcpdump patch merged into Alexey's version.
+
+- Kernel driver (a la ipip and ip_gre) which encapsulates raw ethernet
+  frames in raw IP (proto 97) or UDP/IP packets.
+
+- 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..20928e4
--- /dev/null
+++ b/doc/brctl.8
@@ -0,0 +1,171 @@
+.\"
+.\"	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 "January 22, 2000" "" ""
+.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 it's 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 setageingtime <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 eachother
+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)
+
+.SH AUTHOR
+Lennert Buytenhek <buytenh@gnu.org>