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)