DragonFly On-Line Manual Pages

Search: Section:  

BITTWISTB(1)           DragonFly General Commands Manual          BITTWISTB(1)


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


AUTHORS

       Original author and current maintainer:

              Addy Yeow Chin Heng

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

                               12 December 2009                   BITTWISTB(1)

Search: Section: