NAME

       bittwist -- pcap based ethernet packet generator

SYNOPSIS

       bittwist [ -djvh ] [ -i interface ] [ -s len ] [ -l loop ]
                [ -c count ] [ -p pps ] [ -r rate ] [ -t gap ]
                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),  1Gbps  (1000BASE-T),  or  10Gbps (10GBASE-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, -r,
       or -t 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.

       -j     Enable jumbo frame with an MTU of up to 9000 bytes. Specify this flag if you wish to send  packets
              with length greater than the typical MTU of 1500 bytes.

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

               0 : Send the actual packet length. This is the default.
              -1 : Send the captured length.

              or any other value from 14 to 9014. Value greater than 1514 requires -j flag to be specified.

       -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.  This  flag  takes
              precedence over the -r flag.

       -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.  This flag takes precedence over the -t flag.

       -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.

       -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 - 2024 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

                                                 1 November 2024                                     BITTWIST(1)