Provided by: bittwist_4.7+ds-2_amd64 
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 document describes the bittwiste program, the pcap(3) capture file editor. Bittwiste is designed to
work only with Ethernet frame, e.g. link type DLT_EN10MB in pcap(3), with a maximum frame size of 1514
bytes which is equivalent to an MTU of 1500 bytes, 14 bytes for Ethernet header.
Bittwiste can currently edit Ethernet, VLAN, ARP, IPv4, IPv6, ICMPv4, ICMPv6, TCP, and UDP headers. IPv6
packets with extension headers or next header field not matching ICMPv6, TCP, or UDP are not supported;
bittwiste will simply write such packets as is to output trace file as it encounters them in the input
trace file.
If run with the -X flag, you can append your own payload after any of the supported headers; specified
using the -L and -T flag. Bittwiste will, if not run with the -C flag, recalculate the checksums for
IPv4, ICMPv4, ICMPv6, TCP, and UDP headers, except for the last fragment of a fragmented IPv4 datagram;
bittwiste does not currently support checksum correction for the last fragment of a fragmented IPv4
datagram.
While parsing the packets in an input trace file, bittwiste will skip, i.e. write to output trace file as
is, any truncated packet, for example, an ICMPv4 packet with a captured length of 25 bytes (we need at
least 28 bytes; 14 bytes for Ethernet header, minimum 20 bytes for IP header, and 4 bytes for ICMPv4
header) does not give enough information on its ICMPv4 header for bittwiste to read and modify it. In
this case, you can utilize the -L and -T flag to copy the original packet up to its IP header and append
your customized ICMPv4 header and data to the packet using the -X flag. When specifying payload that
covers the ICMPv4, ICMPv6, TCP, or UDP header and its data, you can use zeros, e.g. 0000 for 2 bytes of
zeros, for the header checksum which is then corrected automatically by bittwiste.
In order to simplify the way options are specified, you can only edit packets of a specific type supplied
to the -T flag per execution of bittwiste on an input trace file. In addition, the -T flag must appear
last among the general options which are the -I, -O, -L, -X, -C, -M, -D, -R, -S, -N, -G, and -P flag.
OPTIONS
-I input
Input pcap based trace file. Typically, input should be a file path to a pcap based trace file.
However, for convenience, the following template names are also accepted to load 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.
-L layer
Copy up to the specified layer and discard the remaining data. Value for layer must be either 2,
3, or 4 where 2 for Ethernet and VLAN, 3 for ARP, IPv4, or IPv6, and 4 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 range is specified, e.g. 0-1000, a
random payload with a size between 0 and 1000 bytes (inclusive) will be generated for each packet.
If range:payload is specified, e.g. 0-1000:0302aad1, a payload of random size between 0 to 1000
bytes will be generated, containing a repeated sequence of the specified bytes (0x0302aad1). The
maximum 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
-X flag is ignored if -L and -T flag are not specified.
-C Specify this flag to disable checksum correction. Checksum correction is applicable for non-
fragmented supported packets only.
-M linktype
Replace the linktype stored in the pcap file header. Typically, value for 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.
First byte (starting from link layer header) starts from 1.
-L, -X, -C and -T flag are ignored if -D flag 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 within the specified timeframe with up to one-second resolution using
DD/MM/YYYY,HH:MM:SS as the format for start and end time in timeframe.
Example: -S 22/10/2006,21:47:35-24/10/2006,13:16:05
-S flag is evaluated after -R flag.
-N repeat
Duplicate packets from the input trace file repeat times. Use this flag to create a stream of
packets, each with, for example, a random tcp sequence number, from a 1-packet trace file.
Example: -N 100000
-N flag is evaluated after -R and -S flag.
-G gaprange
Apply inter-packet gap between packets in microseconds from 0 to (2^31 - 1). Values in gaprange
are inclusive and selected randomly. A single value implies a fixed gap.
Example: -G 1000-10000 or -G 1000
-G flag is evaluated after -R, -S, and -N flag.
-P seed
Positive integer (0 to 2^32 - 1) to seed the random number generator (RNG) used, for example, to
generate random port number. If unset, current timestamp will be used as the RNG seed.
bittwiste uses Mersenne Twister for high-speed uniformly distributed random number generation.
-T header
Edit only the specified header. Possible keywords for header are, eth, vlan, arp, ip, ip6, icmp,
icmp6, tcp, or udp. -T flag must appear last among the general options.
-h Print version information and usage.
header-specific-options
Each packet that matches the type supplied to the -T flag is modified based on the options
described 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 will be 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 will be 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 in integer value between 0 to 65535 or hexadecimal value between 0x0000 to 0xffff
(16-bit). If ot and nt are specified, any instances of ot in the EtherType field will be
replaced with nt. You can use the string 'rand' for a random EtherType. Following 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 in integer value between 0 to 4095. If oi and ni are specified, any instances of oi
in the VLAN ID field will be 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 will
be 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) in integer value between 0 to 7. If op and np are specified,
any instances of op in the VLAN PCP field will be 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
Encapsulated EtherType in integer value between 0 to 65535 or hexadecimal value between
0x0000 to 0xffff (16-bit). If ot and nt are specified, any instances of ot in the
encapsulated EtherType field will be replaced with nt. You can use the string 'rand' for a
random encapsulated EtherType. Following 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.
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 in integer value between 0 to 65535. For example, you can set opcode to 1
for ARP request, 2 for ARP reply.
-s smac or omac,nmac
Sender MAC address. If omac and nmac are specified, any instances of omac in the sender MAC
address field will be 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
-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 will be
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 will be replaced with nmac. You can also use the string '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 will be
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 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 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
Error code for this ICMPv4 message in integer value between 0 to 255. For example, code for
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 in integer value between 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 in integer value between 0 to 255. For example, code for 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 in integer value between 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 in integer value between 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 in integer value between 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 in integer value between 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 in integer value between 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 in integer value between 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 in integer value between 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 in integer value between 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
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
1 November 2024 BITTWISTE(1)