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.
SEE ALSO
bittwist(1), bittwiste(1), pcap(3), tcpdump(1)
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
Copyright (C) 2006 - 2010 Addy Yeow Chin Heng <ayeowch@gmail.com> and
nPulse Network Systems, LLC.
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
12 December 2009