NAME

bittwistb -- pcap based ethernet bridge

SYNOPSIS

bittwistb [ -dvh ] [ -i interfaces ]

DESCRIPTION

This document describes the bittwistb program, the pcap(3) based Ethernet bridge. Bittwistb is designed to allow a single host to do bridging on independent sets of Ethernet-type interfaces under Ethernet II (IEEE 802.3) network with a MTU of up to 1500 bytes. Since bittwistb uses functions provided by pcap(3) library, e.g. pcap_open_live() and pcap_inject(), to capture and write packets, it may require that you have special privileges, e.g. read access to /dev/bpf* on BSD or root access on Linux, to do the bridging or to enumerate network devices with, for example, the -d flag.

Bittwistb works by polling, poll(2), for packets on all of the interfaces supplied to the -i flag and forward them from one interface to another according to the bridging rules below:

: Multicast and broadcast packets are always forwarded to all of the interfaces supplied to the -i flag except for the interface on which the packets arrive.
: For unicast packets, bittwistb learns which MAC addresses are associated with which interfaces and it will forward the packets selectively. Like most bridges, bittwistb uses a hash table to store known MAC addresses. Each entry in the hash table is kept for at most 5 minutes.

Bittwistb terminates when it receives an interrupt signal, SIGINT, which is typically generated by typing Control-C.

OPTIONS

-d: Print a list of network interfaces available.
-v: Print forwarding information including the destination and source MAC addresses of forwarded packets.
-i interfaces: List of comma separated Ethernet-type interfaces to bridge.
Example: -i vr0,fxp0
You can specify between 2 to 8 interfaces.
-h: Print version information and usage.

EXAMPLES

Bittwistb will, if run with the -v flag, print forwarding information as shown in the example below:

: 1 : root@localhost# bittwistb -i vr0,fxp0 -v
2 : vr0=00:08:54:36:5e:01,port=1
3 : fxp0=00:13:20:3e:ab:cf,port=2
4 : [057451]mac=00:0d:61:b2:59:6b,port=1
5 : dmac=ff:ff:ff:ff:ff:ff,smac=00:0d:61:b2:59:6b,outport=2
6 : [056851]mac=00:13:46:76:20:13,port=1
7 : dmac=01:00:5e:7f:ff:fa,smac=00:13:46:76:20:13,outport=2
8 : [056851]deleted
9 : [057451]deleted

Line numbers are not visible in the actual output. MAC addresses and ports associated with the interfaces supplied to the -i flag are printed at line 2 and 3. At line 4, a new MAC address is stored in the bridging hash table at index 57451. This MAC address belongs to a host which resides on port 1, i.e. the first LAN segment. At line 5, a broadcast packet is forwarded out through all ports except port 1 of which the source MAC address resides on, hence the outport=2. At line 6, a new MAC address which belongs to a host in the first LAN segment is stored at index 56851. At line 7, a multicast packet is forwarded out through all ports except port 1 of which the source MAC address resides on, hence the outport=2. At line 8 and 9, entry 56851 and 57451 are removed from the hash table after approximately 5 minutes.

Under normal use, we do not recommend running bittwistb with the -v flag set as this may result in a poor bridging performance due to the standard I/O operation.

BUGS

File your bug report and send to:

: Addy Yeow Chin Heng <ayeowch@gmail.com>.

Make sure you are using the latest stable version before submitting your bug report.

If a known host relocates to another LAN segment, bittwistb will continue to forward packets destined to the host through its old LAN segment. The presence of this host in a new LAN segment is known only after at most 5 minutes.

COPYRIGHT

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 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

AUTHORS

Original author and current maintainer:

: Addy Yeow Chin Heng

The current version is available from http://bittwist.sourceforge.net