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)