Man Linux: Main Page and Category List


       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 <>.

       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 - 2010 Addy Yeow Chin Heng <> 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

       This  program  is  distributed  in the hope that it will be useful, but
       WITHOUT  ANY  WARRANTY;  without   even   the   implied   warranty   of
       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

                               12 December 2009