NAME

       bittwist -- pcap based ethernet packet generator

SYNOPSIS

       bittwist [ -dvh ] [ -i interface ] [ -s length ] [ -l loop ]
                [ -c count ] [ -p pps ] [ -t gap ] [ -r rate ]
                pcap-file(s)

DESCRIPTION

       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 an  MTU  of  up  to  1500  bytes  on  10Mbps
       (10Base-T),  100Mbps  (100BASE-TX), or 1000Mbps (1000BASE-T) 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_sendpacket(), 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 -p,  -t,
       or  -r  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.

OPTIONS

       -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 (in bytes). Set length to:

               0 : Send the actual packet length. This is the default.
              -1 : 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.

       -c count
              Send up to count packets. Default is to send all packets from pcap-file(s).

       -p pps Send pps packets per second. Value for pps must be between 1 to 1000000.

       -t gap Set inter-packet gap in seconds, ignoring the captured interval between packets  in  pcap-file(s).
              Value for gap must be between 1 to 86400.

       -r rate
              Limit  the  sending to rate Mbps. Value for rate must be between 0 to 10000. This flag is intended
              to set the desired packet throughput. If you want to send packets at line rate of 1000  Mbps,  try
              -r  1000.  If  you  want to send packets without rate limit, try -r 0. This flag is typically used
              with -l 0 to send pcap-file(s) until stopped.

       -h     Print version information and usage.

SEE ALSO

       bittwiste(1), pcap(3), tcpdump(1)

BUGS

       File your bug report and send to:

              Addy Yeow <ayeowch@gmail.com>

       Make sure you are using the latest stable version before submitting your bug report.

       If you run bittwist with -r flag, pcap_sendpacket() may return an error with the following error string:

              send: No buffer space available

       We recommend that you adjust the value for -r flag to limit the packet throughput to a lower  level  that
       is  supported  by your interface, e.g. start from -r 10 to inject packets at a maximum rate of 10Mbps and
       adjust the value accordingly.

COPYRIGHT

       Copyright (C) 2006 - 2023 Addy Yeow <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
       (at your option) 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

       The current version is available from https://bittwist.sourceforge.io

                                                   6 July 2023                                       BITTWIST(1)