Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
BITTWISTB(1)		    General Commands Manual		  BITTWISTB(1)

       bittwistb -- pcap based ethernet	bridge

       bittwistb [ -dvh	] [ -i interfaces ]

       This document describes the bittwistb program, the pcap(3) based	Ether-
       net 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	inter-
       faces 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 re-
       sides 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  con-
       tinue  to forward packets destined to the host through its old LAN seg-
       ment. The presence of this host in a new	LAN segment is known only  af-
       ter at most 5 minutes.

       Copyright (C) 2006 - 2011 Addy Yeow Chin	Heng <>

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


Want to link to this manual page? Use this URL:

home | help