bittwist.1
Description: bittwist -- pcap based ethernet packet generator

    BITTWIST(1)                 General Commands Manual                BITTWIST(1)

    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 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), 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_send-
           packet(),  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 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, -t, or -r 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.

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

                                    11 October 2024                    BITTWIST(1)