BITTWISTE(1)

📦

version 4.7 · 3 versions

4.7 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
2.0 · debian bookworm, ubuntu jammy
3.8 · opensuse-leap 16.0, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ bittwiste ✨ (General Commands Manual, section 1, and yes she's THAT girl)

okay bestie, buckle up 💖 you're about to meet bittwiste, and she is not like other girls — she edits pcap files and she does it flawlessly.

🌸 NAME 🌸

bittwiste — pcap capture file editor 🎀

🦋 SYNOPSIS 🦋

bittwiste [ -I input ] [ -O output ] [ -L layer ] [ -X payload ]
          [ -C ] [ -M linktype ] [ -D offset ] [ -R range ]
          [ -S timeframe ] [ -N repeat ] [ -G gaprange ] [ -P seed ]
          [ -T header ] [ header-specific-options ] [ -h ]

💜 DESCRIPTION 💜

This whole doc is about bittwiste, aka the pcap(3) capture file editor. Real talk: bittwiste only fw Ethernet frames, like link type DLT_EN10MB in pcap(3), and the max frame size is 1514 bytes — which is literally an MTU of 1500 bytes plus 14 bytes of Ethernet header. math is mathing ✨

Right now bittwiste can edit Ethernet, VLAN, ARP, IPv4, IPv6, ICMPv4, ICMPv6, TCP, and UDP headers. BUT — IPv6 packets with extension headers, or with a next header field that doesn't match ICMPv6, TCP, or UDP? Not supported, no cap. When she runs into those, she just writes them to the output trace file as-is while she's going through the input trace file. she's not gonna fight them, she's gonna move on 💅

If you run her with the -X flag, you can append your own payload after any of the supported headers — you say which ones with the -L and -T flags. And unless you also passed -C, bittwiste will recalculate the checksums for IPv4, ICMPv4, ICMPv6, TCP, and UDP headers… except for the last fragment of a fragmented IPv4 datagram. That one she cannot fix — checksum correction for the last fragment of a fragmented IPv4 datagram is not currently supported, periodt.

While she's parsing packets in an input trace file, bittwiste skips (i.e. writes to the output trace file exactly as-is) any truncated packet. Example bestie: an ICMPv4 packet with a captured length of 25 bytes? We need at least 28 bytes — 14 bytes for the Ethernet header, minimum 20 bytes for the IP header, and 4 bytes for the ICMPv4 header. So there's just not enough info in that ICMPv4 header for her to read and modify it. 🙈 In that case you can use the -L and -T flags to copy the original packet up to its IP header, then append your own customized ICMPv4 header and data using the -X flag. And when you're specifying a payload that covers the ICMPv4, ICMPv6, TCP, or UDP header and its data, you can drop zeros in there — like 0000 for 2 bytes of zeros — for the header checksum, and bittwiste will correct it automatically for you. she's got you 🫶

Now, to keep the way options get specified simple: you can only edit packets of one specific type per execution, and that type goes to the -T flag. Also — and this matters — the -T flag must appear last among the general options. The general options are -I, -O, -L, -X, -C, -M, -D, -R, -S, -N, -G, and -P. so -T is the main character who walks in last 💅

✨ OPTIONS ✨

-I input — your input pcap based trace file. Usually input is just a file path to a pcap based trace file. But for convenience, these template names are also accepted, and they load the trace file from one of the built-in templates:
- eth : Ethernet header
- vlan : VLAN header
- arp : ARP header
- ip : IPv4 header
- ip6 : IPv6 header
- icmp : ICMPv4 header
- icmp6 : ICMPv6 header
- tcp : IPv4 TCP header
- ip6tcp : IPv6 TCP header
- udp : IPv4 UDP header
- ip6udp : IPv6 UDP header

Example: -I icmp

-O output — output trace file. that's it, that's the tweet 💖
-L layer — copy up to the specified layer and discard all the remaining data. layer has to be either 2, 3, or 4, where 2 is for Ethernet and VLAN, 3 is for ARP, IPv4, or IPv6, and 4 is for ICMPv4, ICMPv6, TCP, or UDP.
-X payload or range or range:payload — append payload in hex digits to the end of each packet. If you specify a range, like 0-1000, then a random payload sized somewhere between 0 and 1000 bytes (inclusive) gets generated for each packet. If you specify range:payload, like 0-1000:0302aad1, you get a payload of random size between 0 and 1000 bytes that contains a repeated sequence of those specified bytes (0x0302aad1). Max payload size is 65535 bytes.

Examples:

-X 0302aad1
-X 0-1000
-X 20-20
-X 0-1000:00
-X 0-1000:ff
-X 0-1000:0302aad1

psst — the -X flag gets ignored if -L and -T aren't specified. don't do all that work for nothing bestie 😭

-C — pass this flag to disable checksum correction. Checksum correction only applies to non-fragmented supported packets anyway.
-M linktype — replace the linktype stored in the pcap file header. Typically linktype is 1 for Ethernet. Example: -M 12 (for raw IP), -M 51 (for PPPoE).

For the complete list, see: https://www.tcpdump.org/linktypes.html

-D offset — delete the specified byte offset from each packet. The first byte (starting from the link layer header) starts from 1. Heads up: -L, -X, -C and -T flags get ignored if -D is specified. Example: -D 15-40, -D 10, or -D 18-9999
-R range — save only the specified range of packets. Example: -R 5-21 or -R 9
-S timeframe — save only the packets inside the specified timeframe, with up to one-second resolution, using DD/MM/YYYY,HH:MM:SS as the format for the start and end time in timeframe. Example: -S 22/10/2006,21:47:35-24/10/2006,13:16:05. The -S flag gets evaluated after the -R flag.
-N repeat — duplicate packets from the input trace file repeat times. Use this one to build a stream of packets — each with, say, a random tcp sequence number — out of a 1-packet trace file. Example: -N 100000. The -N flag gets evaluated after the -R and -S flags.
-G gaprange — apply an inter-packet gap between packets, in microseconds, from 0 to (2^31 - 1). The values in gaprange are inclusive and picked randomly. A single value means a fixed gap. Example: -G 1000-10000 or -G 1000. The -G flag gets evaluated after the -R, -S, and -N flags.
-P seed — a positive integer (0 to 2^32 - 1) to seed the random number generator (RNG), which is used for stuff like generating a random port number. If you don't set it, the current timestamp becomes the RNG seed.

bittwiste uses Mersenne Twister for high-speed uniformly distributed random number generation. she's fast AND fair, we love that for her ✨

-T header — edit only the specified header. The possible keywords for header are eth, vlan, arp, ip, ip6, icmp, icmp6, tcp, or udp. And remember: the -T flag must appear last among the general options. main character entrance, every time 💅
header-specific-options — every packet that matches the type you gave to the -T flag gets modified based on the options below:

🍓 Options for eth (RFC 894) 🍓

-d dmac or omac,nmac — destination MAC address. If omac and nmac are specified, any instances of omac in the destination MAC address field get replaced with nmac. You can also use the string 'rand' for a random MAC address.

Examples:

-d 00:08:55:64:65:6a
-d rand
-d 00:08:55:64:65:6a,rand

-s smac or omac,nmac — source MAC address. If omac and nmac are specified, any instances of omac in the source MAC address field get replaced with nmac. You can also use the string 'rand' for a random MAC address.

Examples:

-s 00:13:20:3e:ab:cf
-s rand
-s 00:13:20:3e:ab:cf,rand

-t type or ot,nt — EtherType, as an integer value between 0 to 65535 or a hexadecimal value between 0x0000 to 0xffff (16-bit). If ot and nt are specified, any instances of ot in the EtherType field get replaced with nt. You can use the string 'rand' for a random EtherType. These keywords are also accepted:
- vlan : 0x8100 (802.1Q VLAN)
- ctag : 0x8100 (802.1ad VLAN C-TAG for Q-in-Q)
- stag : 0x88a8 (802.1ad VLAN S-TAG for Q-in-Q)
- ip : 0x0800
- ip6 : 0x86dd
- arp : 0x0806

Examples:

-t ip
-t 0x0800
-t rand
-t 0x0800,rand

For the complete list, see: https://www.iana.org/assignments/ieee-802-numbers

🧚 Options for vlan (IEEE 802.1Q, 802.1ad) 🧚

-i id or oi,ni — VLAN ID as an integer value between 0 to 4095. If oi and ni are specified, any instances of oi in the VLAN ID field get replaced with ni. You can use the string 'rand' for a random VLAN ID. This option can be repeated up to 4 times to edit stacked VLAN headers, i.e. Q-in-Q.

Examples:

-i 2000
-i rand
-i 1000,rand
-i 100 -i 200 (outer S-TAG = 100, inner C-TAG = 200)

-d dei or od,nd — VLAN DEI (drop eligible indicator; also known as CFI for canonical format indicator). Value must be 0 or 1. If od and nd are specified, any instances of od in the VLAN DEI field get replaced with nd. You can use the string 'rand' for a random VLAN DEI. This option can be repeated up to 4 times to edit stacked VLAN headers, i.e. Q-in-Q.

Examples:

-d 0
-d rand
-d 1,rand
-d 0 -d 1

-p pcp or op,np — VLAN PCP (priority code point) as an integer value between 0 to 7. If op and np are specified, any instances of op in the VLAN PCP field get replaced with np. You can use the string 'rand' for a random VLAN PCP. This option can be repeated up to 4 times to edit stacked VLAN headers, i.e. Q-in-Q.

Mapping of pcp value from IEEE P802.1p:

0 : Best effort
1 : Background
2 : Excellent effort
3 : Critical applications
4 : Video, < 100 ms latency and jitter
5 : Voice, < 10 ms latency and jitter
6 : Internetwork control
7 : Network control

Examples:

-p 2
-p rand
-p 3,rand
-p 7 -p 0

-t type or ot,nt — okay bestie, this sets the encapsulated EtherType 💖. It's an integer from 0 to 65535 or hex from 0x0000 to 0xffff (16-bit, periodt). If you give both ot and nt, then every instance of ot in the encapsulated EtherType field gets swapped for nt. You can also use the string rand for a random encapsulated EtherType. These keywords are also accepted:
- vlan : 0x8100 (802.1Q VLAN)
- ctag : 0x8100 (802.1ad VLAN C-TAG for Q-in-Q)
- stag : 0x88a8 (802.1ad VLAN S-TAG for Q-in-Q)
- ip : 0x0800
- ip6 : 0x86dd
- arp : 0x0806

This option can be repeated up to 4 times to edit stacked VLAN headers, i.e. Q-in-Q. Iconic.

Examples:

-t ip
-t 0x0800
-t rand
-t 0x0800,rand
-t ctag -t ip

For the complete list, see: https://www.iana.org/assignments/ieee-802-numbers

🌸 Options for arp (RFC 826) 🌸

-o opcode — Operation code as an integer between 0 and 65535. For example, set opcode to 1 for ARP request, 2 for ARP reply.
-s smac or omac,nmac — Sender MAC address. If omac and nmac are given, any instances of omac in the sender MAC address field get replaced with nmac. You can also use the string rand for a random MAC address. slay

Examples:

-s 00:13:20:3e:ab:cf
-s rand
-s 00:13:20:3e:ab:cf,rand

-p sip or oip,nip — Sender IP address. Example: -p 192.168.0.1. If oip and nip are specified, any instances of oip in the sender IP address field get replaced with nip.
-t tmac or omac,nmac — Target MAC address. If omac and nmac are specified, any instances of omac in the target MAC address field get replaced with nmac. You can also use rand for a random MAC address.

Examples:

-t 00:08:55:64:65:6a
-t rand
-t 00:08:55:64:65:6a,rand

-q tip or oip,nip — Target IP address. Example: -q 192.168.0.2. If oip and nip are specified, any instances of oip in the target IP address field get replaced with nip.

🔥 Options for ip (RFC 791) 🔥

-c ds_field — 6-bit DS field (first 6-bit of 8-bit type of service field). Some service class name mapping to ds_field value from RFC 4594:
- 0 : Standard (CS0)
- 8 : Low-priority data (CS1)
- 16 : OAM (CS2)
- 24 : Broadcast video (CS3)
- 32 : Real-time interactive (CS4)

Example: -c 16 or -c 0x10 (to classify packet for operation and management of the network). For more information on DS field, see RFC 2474 and RFC 4594.

-e ecn_field — 2-bit ECN field (last 2-bit of 8-bit type of service field). ecn_field can be set to one of the 4 values below:
- 0 : Not-ECT
- 1 : ECT(1)
- 2 : ECT(0)
- 3 : CE

Example: -e 3 or -e 0x03 (to indicate congestion to the end hosts). For more information on ECN field, see RFC 3168.

-i id or oi,ni — Identification in integer value between 0 to 65535. If oi and ni are specified, any instances of oi in the identification field will be replaced with ni. You can also use the string rand for a random identification.

Example: -i 2000, -i rand, or -i 1000,rand

-f flags — Control flags. Possible characters for flags are:
- - : remove all flags
- r : set the reserved flag
- d : set the don't fragment flag
- m : set the more fragment flag

Example: -f d. If any of the flags is specified, all original flags are removed automatically.

-o offset — Fragment offset in integer value between 0 to 7770. Value for offset represents the number of 64-bit segments contained in earlier fragments which must not exceed 7770 (62160 bytes).
-t ttl or ot,nt — Time to live in integer value between 0 to 255 (milliseconds). If ot and nt are specified, any instances of ot in the time to live field will be replaced with nt. You can also use the string rand for a random time to live.

Example: -t 64, -i rand, or -i 64,rand

-p proto or op,np — Protocol number in integer value between 0 to 255. If op and np are specified, any instances of op in the protocol number field will be replaced with np. You can also use the string rand for a random protocol number. Some common protocol numbers are:
- 1 : Internet Control Message (ICMP)
- 6 : Transmission Control (TCP)
- 17 : User Datagram (UDP)

For the complete list, see: https://www.iana.org/assignments/protocol-numbers

-s sip or oip,nip — Source IP address. If oip and nip are specified, any instances of oip in the source IP address field will be replaced with nip. If CIDR notation (RFC 4632) is specified, e.g. 192.168.0.0/16, an IP address will be selected at random from the range.

Examples:

-s 192.168.0.1
-s 127.0.0.1,192.168.0.0/16
-s 0.0.0.0/0 (random IPv4 throughout the entire range)

-d dip or oip,nip — Destination IP address. If oip and nip are specified, any instances of oip in the destination IP address field will be replaced with nip. If CIDR notation (RFC 4632) is specified, e.g. 192.168.0.0/16, an IP address will be selected at random from the range.

Examples:

-d 192.168.0.2
-d 127.0.0.2,192.168.0.0/16
-d 0.0.0.0/0 (random IPv4 throughout the entire range)

🦋 Options for ip6 (RFC 8200) 🦋

-c ds_field — 6-bit DS field (first 6-bit of 8-bit traffic class field). Some of the service class name mapping to ds_field value from RFC 4594:
- 0 : Standard (CS0)
- 8 : Low-priority data (CS1)
- 16 : OAM (CS2)
- 24 : Broadcast video (CS3)
- 32 : Real-time interactive (CS4)

Example: -c 16 or -c 0x10 (to classify packet for operation and management of the network). For more information on DS field, see RFC 2474 and RFC 4594.

-e ecn_field — 2-bit ECN field (last 2-bit of 8-bit traffic class field). ecn_field can be set to one of the 4 values below:
- 0 : Not-ECT
- 1 : ECT(1)
- 2 : ECT(0)
- 3 : CE

Example: -e 3 or -e 0x03 (to indicate congestion to the end hosts). For more information on ECN field, see RFC 3168.

-f flow_label — Flow label in integer value between 0 to 1048575 or hexadecimal value between 0x00000 to 0xfffff (20-bit). Example: -f 0. Value of 0 is to indicate that the packet does not belong to any flow. For more information, see RFC 6437.
-n next_header or on,nn — Next header number in integer value between 0 to 255. If on and nn are specified, any instances of on in the next header field will be replaced with nn. You can also use the string rand for a random next header number. Example of next header numbers:
- 0 : IPv6 Hop-by-Hop Option (HOPOPT)
- 6 : Transmission Control (TCP)
- 17 : User Datagram (UDP)
- 50 : Encap Security Payload (ESP)
- 51 : Authentication Header (AH)
- 58 : ICMP for IPv6 (IPv6-ICMP)

For the complete list, see: https://www.iana.org/assignments/protocol-numbers

-h hop_limit or oh,nh — Hop limit in integer value between 0 to 255. If oh and nh are specified, any instances of oh in the hop limit field will be replaced with nh. You can also use the string rand for a random hop limit. Destination host should not discard a packet with hop limit equal to 0.
-s sip or oip,nip — Source IP address. If oip and nip are specified, any instances of oip in the source IP address field will be replaced with nip. If CIDR notation (RFC 4291) is specified, e.g. 2001:db8::/64, an IP address will be selected at random from the range.

Examples:

-s fd00::1
-s ::1,2001:db8::/64
-s ::/0 (random IPv6 throughout the entire range)

-d dip or oip,nip — Destination IP address. If oip and nip are specified, any instances of oip in the destination IP address field will be replaced with nip. If CIDR notation (RFC 4291) is specified, e.g. 2001:db8::/64, an IP address will be selected at random from the range.

Examples:

-d fd00::2
-d ::2,2001:db8::/64
-d ::/0 (random IPv6 throughout the entire range)

💜 Options for icmp (RFC 792) 💜

-t type — Type of message in integer value between 0 to 255. Some common messages are:
- 0 : Echo reply
- 3 : Destination unreachable
- 8 : Echo
- 11 : Time exceeded

For the complete list, see: https://www.iana.org/assignments/icmp-parameters

-c code — this is the error code for your ICMPv4 message, an integer from 0 to 255. For example, the code for a time exceeded message may have one of the following values:
- 0 : transit TTL exceeded
- 1 : reassembly TTL exceeded

For the complete list, see: https://www.iana.org/assignments/icmp-parameters

✨ Options for icmp6 (RFC 4443): ✨

-t type — type of message, integer 0 to 255. Some common messages are:
- 3 : Time Exceeded
- 128 : Echo Request
- 129 : Echo Reply

For the complete list, see: https://www.iana.org/assignments/icmpv6-parameters

-c code — code for this ICMPv6 message, integer 0 to 255. For example, the code for a Time Exceeded message may have one of the following values:
- 0 : hop limit exceeded in transit
- 1 : fragment reassembly time exceeded

For the complete list, see: https://www.iana.org/assignments/icmpv6-parameters

🔥 Options for tcp (RFC 9293): 🔥

-s sport or op,np — source port number, integer 0 to 65535. If op and np are specified, any instances of op in the source port field will be replaced with np. You can also use the string 'rand' for a random port number.

Example: -s 2000, -s rand, or -s 1000,rand

-d dport or op,np — destination port number, integer 0 to 65535. If op and np are specified, any instances of op in the destination port field will be replaced with np. You can also use the string 'rand' for a random port number.

Example: -d 2000, -d rand, or -d 1000,rand

-q seq or os,ns — sequence number, integer 0 to 4294967295. If SYN control bit is set, e.g. character s is supplied to the -f flag, seq represents the initial sequence number (ISN) and the first data byte is ISN + 1. If os and ns are specified, any instances of os in the sequence number field will be replaced with ns. You can also use the string 'rand' for a random sequence number.

Example: -q 100000, -q rand, or -q 100000,rand

-a ack or oa,na — acknowledgment number, integer 0 to 4294967295. If ACK control bit is set, e.g. character a is supplied to the -f flag, ack represents the value of the next sequence number that the receiver is expecting to receive. If oa and na are specified, any instances of oa in the acknowledgment number field will be replaced with na. You can also use the string 'rand' for a random acknowledgment number.

Example: -a 100000, -a rand, or -a 100000,rand

-f flags — control flags. Possible characters for flags are:
- - : remove all flags
- c : congestion window reduced
- e : explicit congestion notification echo
- u : urgent pointer field is significant
- a : acknowledgment field is significant
- p : push function
- r : resets the connection
- s : synchronizes the sequence numbers
- f : no more data from sender

Example: -f s If any of the flags is specified, all original flags are removed automatically.

-w win — window size, integer 0 to 65535. If ACK control bit is set, e.g. character a is supplied to the -f flag, win represents the number of data bytes, beginning with the one indicated in the acknowledgment number field that the receiver is willing to accept.
-u urg — urgent pointer, integer 0 to 65535. If URG control bit is set, e.g. character u is supplied to the -f flag, urg represents a pointer that points to the first data byte following the urgent data.

🦋 Options for udp (RFC 768): 🦋

-s sport or op,np — source port number, integer 0 to 65535. If op and np are specified, any instances of op in the source port field will be replaced with np. You can also use the string 'rand' for a random port number.

Example: -s 2000, -s rand, or -s 1000,rand

-d dport or op,np — destination port number, integer 0 to 65535. If op and np are specified, any instances of op in the destination port field will be replaced with np. You can also use the string 'rand' for a random port number.

Example: -d 2000, -d rand, or -d 1000,rand

💖 SEE ALSO 💖

bittwist(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.

When running bittwiste with both the -N and -G flags, large inter-packet gap may result in the packet timestamp beyond Unix epoch 2147483647 (2038-01-19 03:14:07 UTC) to overflow. This is due to the use of signed 32-bit integer to store timestamp in pcap(3) header. Simply changing the data type, e.g. using unsigned 64-bit integer, would break the compatibility of the output trace file with existing systems.

The workaround built into bittwiste is to use Unix epoch 946684800 (2020-01-01 00:00:00 UTC) as the starting reference timestamp when -G flag is specified. This translates to a maximum timespan of 38 years or 559165 packets in the output trace file when using the maximum inter-packet gap, i.e. -G 2147483647.

👑 COPYRIGHT 👑

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

And that's a wrap, bestie 💅 This was BITTWISTE(1), dated 1 November 2024 — go forth and packet-craft responsibly 🎀✨

📦 where this page comes from

debian trixie: bittwist 4.7+ds-2 · GPL-2.0-or-later
ubuntu questing: bittwist 4.7+ds-2
ubuntu resolute: bittwist 4.7+ds-2build1 · GPL-2.0-or-later
ubuntu stonking: bittwist 4.7+ds-2build1 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms