--- name: "bittwistb" section: "1" platform: "linux" package: "bittwist" version: "1.1-1" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/bittwistb" --- # bittwistb(1) ## NAME **bittwistb** -- pcap based ethernet bridge ## SYNOPSIS **bittwistb** \[ **-dvh** \] \[ **-i** *interfaces* \] ## DESCRIPTION This document describes the *bittwistb* program, the [*pcap*(3)](/pcap/3.md) 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)](/pcap/3.md) 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)](/poll/2.md), 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)](/bittwist/1.md), [bittwiste(1)](/bittwiste/1.md), [pcap(3)](/pcap/3.md), [tcpdump(1)](/tcpdump/1.md) ## BUGS 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 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. ## AUTHORS Original author and current maintainer: - Addy Yeow Chin Heng The current version is available from http://bittwist.sourceforge.net