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 - 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 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
6 July 2023 BITTWIST(1)