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.

COPYRIGHT

Copyright (C) 2006 - 2010 Addy Yeow Chin Heng <[email protected]> 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.

AUTHORS

Original author and current maintainer:

Addy Yeow Chin Heng

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