Provided by: bittwist_1.1-1_amd64 bug


       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

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

                                         12 December 2009                            BITTWISTB(1)