    BITTWISTE(1)                                                      BITTWISTE(1)

    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 frag-
           mented IP datagram; bittwiste does not currently support checksum  cor-
           rection  for the last fragment of a fragmented IP datagram. While pars-
           ing 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  cor-
                  rection  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 occurences 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 occurences 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 occurences 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 occurences 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 occurences 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 occurences 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 con-
                         tained in earlier fragments which must  not  exceed  7770
                         (62160 bytes).

                  -t ttl
                         Time to live in integer value between 0 to 255 (millisec-
                         onds).

                  -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 occurences 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 occurences 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 occur-
                         rences 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 num-
                         ber (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, begin-
                         ning 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 occur-
                         rences 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  MER-
           CHANTABILITY  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)