---
name: "bittwist"
section: "1"
platform: "linux"
package: "bittwist"
version: "4.7+ds-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/bittwist"
---

# 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)](/pcap/3.md) 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)](/tcpdump/1.md) capture file referred to as trace file in this document. Some familiarity with [*tcpdump*(1)](/tcpdump/1.md) and its basic options are assumed in this document. Since *bittwist* uses functions provided by [*pcap*(3)](/pcap/3.md) 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)](/bittwiste/1.md) 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)](/bittwiste/1.md), [pcap(3)](/pcap/3.md), [tcpdump(1)](/tcpdump/1.md)

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