bittwist man page
Description: bittwist -- pcap based ethernet packet generator

    BITTWIST(1)                 General Commands Manual                BITTWIST(1)

    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 Ether-
           net 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  tcp-
           dump(1)  and its basic options are assumed in this document. Since bit-
           twist uses functions provided by pcap(3) library, e.g. pcap_open_live()
           and  pcap_sendpacket(),  to  write packets onto the network, it may re-
           quire 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 cap-
           tured 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 time-
           stamp 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 re-
                  quires -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  ad-
           just 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 MER-
           CHANTABILITY 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)