bittwistb -- pcap based ethernet bridge
bittwistb [
-dvh ] [
-i interfaces ]
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.
- -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.
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.
bittwist(1), bittwiste(1), pcap(3), tcpdump(1)
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 (C) 2006 - 2011 Addy Yeow Chin Heng <ayeowch@gmail.com>
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.
Original author and current maintainer:
- Addy Yeow Chin Heng
The current version is available from http://bittwist.sourceforge.net