Provided by: bittwist_2.0-15_amd64 bug

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 ] [ -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 a MTU of 1500 bytes, 14 bytes for
       Ethernet header.

       Bittwiste can currently edit Ethernet, ARP, IP, ICMP, TCP, and UDP headers.  If  run  with
       the  -X  flag, you can append your own payload after any of these headers; specified using
       the -L and -T flag. Bittwiste will, if not run with the -C flag, recalculate the checksums
       for  IP,  ICMP,  TCP,  and  UDP  packets,  except for the last fragment of a fragmented IP
       datagram; bittwiste does not currently support checksum correction for the  last  fragment
       of  a  fragmented  IP  datagram. While parsing the packets in a trace file, bittwiste will
       skip, i.e. write to output file as is, any truncated packet, for example, an  ICMP  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 ICMP header) does not give  enough
       information  on its ICMP 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  ICMP  header and data to the packet using the -X flag. When specifying payload
       that covers the ICMP, 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 a 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 and -S flag.

OPTIONS

       -I input
              Input pcap based trace file.

       -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, 3 for ARP or IP, and 4 for ICMP,  TCP  or
              UDP.

       -X payload
              Append payload in hex digits to the end of each packet.
              Example: -X 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 IP, ICMP, TCP, and UDP 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:
              http://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.

       -T header
              Edit  only  the  specified  header. Possible keywords for header are, eth, arp, ip,
              icmp, 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. Example: -d 00:08:55:64:65:6a
                     If  omac  and  nmac  are  specified  instead, all occurrences of omac in the
                     destination MAC address field will be replaced with nmac.

              -s smac or omac,nmac
                     Source MAC address. Example: -s 00:13:20:3e:ab:cf
                     If omac and nmac are specified instead,  all  occurrences  of  omac  in  the
                     source MAC address field will be replaced with nmac.

              -t type
                     EtherType. Possible keywords for type are, ip and arp only.

              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. Example: -s 00:13:20:3e:ab:cf
                     If omac and nmac are specified instead,  all  occurrences  of  omac  in  the
                     sender MAC address field will be replaced with nmac.

              -p sip or oip,nip
                     Sender IP address. Example: -p 192.168.0.1
                     If  oip  and nip are specified instead, all occurrences of oip in the sender
                     IP address field will be replaced with nip.

              -t tmac or omac,nmac
                     Target MAC address. Example: -t 00:08:55:64:65:6a
                     If omac and nmac are specified instead,  all  occurrences  of  omac  in  the
                     target MAC address field will be replaced with nmac.

              -q tip or oip,nip
                     Target IP address. Example: -q 192.168.0.2
                     If  oip  and nip are specified instead, all occurrences of oip in the target
                     IP address field will be replaced with nip.

              Options for ip (RFC 791):

              -i id
                     Identification in integer value between 0 to 65535.

              -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
                     Time to live in integer value between 0 to 255 (milliseconds).

              -p proto
                     Protocol  number  in  integer  value  between 0 to 255. Some common protocol
                     numbers are:

                     1  : Internet Control Message Protocol (ICMP)
                     6  : Transmission Control Protocol (TCP)
                     17 : User Datagram Protocol (UDP)

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

              -s sip or oip,nip
                     Source IP address. Example: -s 192.168.0.1
                     If oip and nip are specified instead, all occurrences of oip in  the  source
                     IP address field will be replaced with nip.

              -d dip or oip,nip
                     Destination IP address. Example: -d 192.168.0.2
                     If  oip  and  nip  are  specified  instead,  all  occurrences  of oip in the
                     destination IP address field will be replaced with nip.

              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:
                     http://www.iana.org/assignments/icmp-parameters

              -c code
                     Error code for this ICMP 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:
                     http://www.iana.org/assignments/icmp-parameters

              Options for tcp (RFC 793):

              -s sport or op,np
                     Source port number in integer value between 0 to 65535. If  op  and  np  are
                     specified  instead,  all  occurrences of op in the source port field will be
                     replaced with np.

              -d dport or op,np
                     Destination port number in integer value between 0 to 65535. If  op  and  np
                     are  specified  instead, all occurrences of op in the destination port field
                     will be replaced with np.

              -q seq
                     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.

              -a ack
                     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.

              -f flags
                     Control flags. Possible characters for flags are:

                     - : remove all flags
                     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 instead, all occurrences of op in the source port  field  will  be
                     replaced with np.

              -d dport or op,np
                     Destination  port  number  in integer value between 0 to 65535. If op and np
                     are specified instead, all occurrences of op in the destination  port  field
                     will be replaced with np.

SEE ALSO

       bittwist(1), pcap(3), tcpdump(1)

BUGS

       File your bug report and send to:

              Addy Yeow Chin Heng <ayeowch@gmail.com>

       Make sure you are using the latest stable version before submitting your bug report.

COPYRIGHT

       Copyright (C) 2006 - 2012 Addy Yeow Chin Heng <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 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 Chin Heng

       The current version is available from http://bittwist.sourceforge.net

                                          21 April 2012                              BITTWISTE(1)