BITTWIST(1)

💖 BITTWIST(1) 💖

okay bestie, so this is the manual for bittwist — it lives in the General Commands Manual section, and it's literally the pcap based ethernet packet generator. sit with me, we're gonna get through this together 🫶

---

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

okay so this whole doc is about bittwist, the pcap(3) based Ethernet packet generator. no cap. bittwist is built to work on an Ethernet II (IEEE 802.3) network with an MTU of up to 1500 bytes, on link speeds of 10Mbps (10Base-T), 100Mbps (100BASE-TX), 1Gbps (1000BASE-T), or 10Gbps (10GBASE-T). iconic range honestly.

the packets it generates come from a saved tcpdump(1) capture file, which this doc calls a trace file. so yeah, it's assumed you already know tcpdump(1) and its basic options — some familiarity, that's the vibe check.

because bittwist uses functions from the pcap(3) library — think pcap_open_live() and pcap_sendpacket() — to write packets onto the network, it may need you to have special privileges. like, read access to /dev/bpf* on BSD, or root access on Linux, whether you're generating packets or just enumerating network devices with, for example, the -d flag. so bestie, check your permissions first 💅

here's the tea on how it behaves by default:

• if you don't run with the -s flag, bittwist injects each packet up to its actual length (on-wire) rather than its captured length. and if the captured length is less than the actual length? it pads the packet with zeros up to its actual length before injecting. slay.
• if you don't run with the -p, -r, or -t flag, bittwist injects packets from a trace file based on the captured intervals — specifically, the timestamp difference between two adjacent packets. the one exception: the first packet in a trace file is always injected immediately. no waiting around for her 👑
• bittwist is designed to not interfere with the packet data. it literally just reads a packet and injects it as is onto the network. that's it, that's the whole job.

and if you do want to modify a packet before injecting it, that's what bittwiste(1) is for — it does exactly that. different girl, different job 💅

---

🎀 OPTIONS 🎀

• -d — print a list of the network interfaces available. window shopping, but for NICs ✨
• -j — enable jumbo frame with an MTU of up to 9000 bytes. specify this flag if you wanna send packets with a length greater than the typical MTU of 1500 bytes. big packet energy.
• -v — print timestamp for each packet.
• -vv — print timestamp and hex data for each packet. double v, double detail, we love to see it 🔥
• -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. a value greater than 1514 requires the -j flag to be specified.
• -l loop — send pcap-file(s) out onto the network loop times. set loop to 0 to send pcap-file(s) until stopped. and 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. the value for pps must be between 1 to 1000000. this flag takes precedence over the -r flag. main character flag, honestly 👑
• -r rate — limit the sending to rate Mbps. the 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). the value for gap must be between 1 to 86400.
• -h — print version information and usage. the classic.

---

👀 SEE ALSO 👀

bittwiste(1), pcap(3), tcpdump(1)

---

💀 BUGS 💀

got a bug report? file it and send it to:

Addy Yeow <ayeowch@gmail.com>

make sure you're using the latest stable version before submitting your bug report. pls and thank you 🙈

also, real talk: if you run bittwist with the -r flag, pcap_sendpacket() may return an error with this error string:

send: No buffer space available

we recommend that you adjust the value for the -r flag to limit the packet throughput to a lower level that is supported by your interface. for example, start from -r 10 to inject packets at a maximum rate of 10Mbps, then adjust the value accordingly. gentle start, then go off 💅

---

🌈 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

---

okay that's the whole page bestie, you ate it 🍓 periodt. and just so you have the receipts: this is bittwist(1) from the General Commands Manual, dated 1 November 2024. go forth and generate packets responsibly, mwah 💖✨🎀