Man Linux: Main Page and Category List


       bittwist -- pcap based ethernet packet generator


       bittwist [ -dvh ] [ -i interface ] [ -s length ] [ -l loop ]
                [ -c count ] [ -m speed ] [ -r rate ] [ -p sleep ]


       This  document  describes  the  bittwist  program,  the  pcap(3)  based
       Ethernet packet generator. Bittwist is designed to work under  Ethernet
       II  (IEEE  802.3)  network  with  a  MTU  of up to 1500 bytes on 10Mbps
       (10Base-T Ethernet) or 100Mbps (Fast Ethernet) link speed. Packets  are
       generated  from saved tcpdump(1) capture file referred to as trace file
       in this document.  Some  familiarity  with  tcpdump(1)  and  its  basic
       options  are  assumed  in  this document. Since bittwist uses functions
       provided by pcap(3) library, e.g. pcap_open_live()  and  pcap_inject(),
       to write packets onto the network, it may require that you have special
       privileges, e.g. read access to /dev/bpf* on  BSD  or  root  access  on
       Linux,  to  generate  packets or to enumerate network devices with, for
       example, the -d flag.

       Bittwist will, if not run with the -s flag, inject each  packet  up  to
       its  actual  length  (on-wire)  instead  of its captured length. If the
       captured length is less than the actual length, bittwist will  pad  the
       packet  with zeros up to its actual length prior to injection. Bittwist
       will, if not run with the -m, -r, or -p flag,  inject  packets  from  a
       trace  file  based  on  the  captured  intervals,  in  particular,  the
       timestamp difference between two adjacent packets, except for the first
       packet  in a trace file, which is always injected immediately. Bittwist
       is designed to not to interfere with the packet data; it merely read  a
       packet and inject it as is onto the network. If modification is desired
       prior to injection of a packet, you can use the  bittwiste(1)  program,
       which does just that.


       -d     Print a list of network interfaces available.

       -v     Print timestamp for each packet.

       -vv    Print timestamp and hex data for each packet.

       -i interface
              Send pcap-file(s) out onto the network through interface.

       -s length
              Packet length to send. Set length to:

              0 to send the actual packet length. This is the default.
              -1 to send the captured length.

              or any other value from 14 to 1514.

       -l loop
              Send  pcap-file(s) out onto the network for loop times. Set loop
              to 0 to send pcap-file(s) until stopped. To stop, type  Control-

       -c count
              Send  up  to  count packets. Default is to send all packets from

       -m speed
              Set interval multiplier to speed. Set speed to 0 or less to send
              the next packet immediately. Minimum positive value for speed is

       -r rate
              Limit the sending to rate Mbps. Value for rate must be between 1
              to  1000.  This  option  is  meant  to  limit the maximum packet
              throughput.  If you  want  to  send  packets  at  line  rate  of
              100Mbps, try -m 0 -r 100

       -p sleep
              Set   interval  to  sleep  (in  seconds),  ignoring  the  actual
              interval. Value for sleep must be between 1 to 2146.

       -h     Print version information and usage.


       bittwistb(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  you  run  bittwist  with  -m  flag  set  to  0 without limiting the
       throughput with -r flag, pcap_inject() may return  an  error  with  the
       following error string:

              send: No buffer space available

       We  recommend  that  you  specify  the  -r  flag  to  limit  the packet
       throughput, e.g. -m 0 -r 100 to inject packets at  a  maximum  rate  of


       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

       This  program  is  distributed  in the hope that it will be useful, but
       WITHOUT  ANY  WARRANTY;  without   even   the   implied   warranty   of
       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