doc/text2pcap.pod

   1
   2 =head1 NAME
   3
   4 text2pcap - Generate a capture file from an ASCII hexdump of packets
   5
   6 =head1 SYNOPSIS
   7
   8 B<text2pcap>
   9 S<[ B<-a> ]>
  10 S<[ B<-d> ]>
  11 S<[ B<-D> ]>
  12 S<[ B<-e> E<lt>l3pidE<gt> ]>
  13 S<[ B<-h> ]>
  14 S<[ B<-i> E<lt>protoE<gt> ]>
  15 S<[ B<-l> E<lt>typenumE<gt> ]>
  16 S<[ B<-n> ]>
  17 S<[ B<-m> E<lt>max-packetE<gt> ]>
  18 S<[ B<-o> hex|oct|dec ]>
  19 S<[ B<-q> ]>
  20 S<[ B<-s> E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>tagE<gt> ]>
  21 S<[ B<-S> E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>ppiE<gt> ]>
  22 S<[ B<-t> E<lt>timefmtE<gt> ]>
  23 S<[ B<-T> E<lt>srcportE<gt>,E<lt>destportE<gt> ]>
  24 S<[ B<-u> E<lt>srcportE<gt>,E<lt>destportE<gt> ]>
  25 S<[ B<-v> ]>
  26 E<lt>I<infile>E<gt>|-
  27 E<lt>I<outfile>E<gt>|-
  28
  29 =head1 DESCRIPTION
  30
  31 B<Text2pcap> is a program that reads in an ASCII hex dump and writes the
  32 data described into a B<pcap> capture file.  B<text2pcap> can
  33 read hexdumps with multiple packets in them, and build a capture file of
  34 multiple packets.  B<text2pcap> is also capable of generating dummy
  35 Ethernet, IP and UDP, TCP, or SCTP headers, in order to build fully
  36 processable packet dumps from hexdumps of application-level data only.
  37
  38 B<Text2pcap> understands a hexdump of the form generated by I<od -Ax
  39 -tx1 -v>.  In other words, each byte is individually displayed, with
  40 spaces separating the bytes from each other.  Each line begins with an offset
  41 describing the position in the packet, each new packet starts with an offset
  42 of 0 and there is a space separating the offset from the following bytes.
  43 The offset is a hex number (can also be octal or decimal - see B<-o>),
  44 of more than two hex digits.
  45
  46 Here is a sample dump that B<text2pcap> can recognize:
  47
  48     000000 00 0e b6 00 00 02 00 0e b6 00 00 01 08 00 45 00
  49     000010 00 28 00 00 00 00 ff 01 37 d1 c0 00 02 01 c0 00
  50     000020 02 02 08 00 a6 2f 00 01 00 01 48 65 6c 6c 6f 20
  51     000030 57 6f 72 6c 64 21
  52     000036
  53
  54 Note the last byte must either be followed by the expected next offset value
  55 as in the example above or a space or a line-end character(s).
  56
  57 There is no limit on the width or number of bytes per line. Also the
  58 text dump at the end of the line is ignored. Bytes/hex numbers can be
  59 uppercase or lowercase. Any text before the offset is ignored,
  60 including email forwarding characters '>'. Any lines of text between
  61 the bytestring lines is ignored. The offsets are used to track the
  62 bytes, so offsets must be correct. Any line which has only bytes
  63 without a leading offset is ignored. An offset is recognized as being
  64 a hex number longer than two characters. Any text after the bytes is
  65 ignored (e.g. the character dump). Any hex numbers in this text are
  66 also ignored. An offset of zero is indicative of starting a new
  67 packet, so a single text file with a series of hexdumps can be
  68 converted into a packet capture with multiple packets. Packets may be
  69 preceded by a timestamp. These are interpreted according to the format
  70 given on the command line (see B<-t>). If not, the first packet
  71 is timestamped with the current time the conversion takes place. Multiple
  72 packets are written with timestamps differing by one microsecond each.
  73 In general, short of these restrictions, B<text2pcap> is pretty liberal
  74 about reading in hexdumps and has been tested with a variety of
  75 mangled outputs (including being forwarded through email multiple
  76 times, with limited line wrap etc.)
  77
  78 There are a couple of other special features to note. Any line where
  79 the first non-whitespace character is '#' will be ignored as a
  80 comment. Any line beginning with #TEXT2PCAP is a directive and options
  81 can be inserted after this command to be processed by
  82 B<text2pcap>. Currently there are no directives implemented; in the
  83 future, these may be used to give more fine grained control on the
  84 dump and the way it should be processed e.g. timestamps, encapsulation
  85 type etc.
  86
  87 B<Text2pcap> also allows the user to read in dumps of
  88 application-level data, by inserting dummy L2, L3 and L4 headers
  89 before each packet. The user can elect to insert Ethernet headers,
  90 Ethernet and IP, or Ethernet, IP and UDP/TCP/SCTP headers before each
  91 packet. This allows Wireshark or any other full-packet decoder to
  92 handle these dumps.
  93
  94 =head1 OPTIONS
  95
  96 =over 4
  97
  98 =item -a
  99
 100 Enables ASCII text dump identification. It allows one to identify the start of
 101 the ASCII text dump and not include it in the packet even if it looks like HEX.
 102
 103 B<NOTE:> Do not enable it if the input file does not contain the ASCII text dump.
 104
 105 =item -d
 106
 107 Displays debugging information during the process. Can be used
 108 multiple times to generate more debugging information.
 109
 110 =item -D
 111
 112 The text before the packet starts either with an I or O indicating that
 113 the packet is inbound or outbound.
 114 This is only stored if the output format is pcapng.
 115
 116 =item -e E<lt>l3pidE<gt>
 117
 118 Include a dummy Ethernet header before each packet. Specify the L3PID
 119 for the Ethernet header in hex. Use this option if your dump has Layer
 120 3 header and payload (e.g. IP header), but no Layer 2
 121 encapsulation. Example: I<-e 0x806> to specify an ARP packet.
 122
 123 For IP packets, instead of generating a fake Ethernet header you can
 124 also use I<-l 101> to indicate a raw IP packet to Wireshark. Note that
 125 I<-l 101> does not work for any non-IP Layer 3 packet (e.g. ARP),
 126 whereas generating a dummy Ethernet header with I<-e> works for any
 127 sort of L3 packet.
 128
 129 =item -h
 130
 131 Displays a help message.
 132
 133 =item -i E<lt>protoE<gt>
 134
 135 Include dummy IP headers before each packet. Specify the IP protocol
 136 for the packet in decimal. Use this option if your dump is the payload
 137 of an IP packet (i.e. has complete L4 information) but does not have
 138 an IP header with each packet. Note that an appropriate Ethernet header
 139 is automatically included with each packet as well.
 140 Example: I<-i 46> to specify an RSVP packet (IP protocol 46).  See
 141 L<http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml> for
 142 the complete list of assigned internet protocol numbers.
 143
 144 =item -l
 145
 146 Specify the link-layer header type of this packet.  Default is Ethernet
 147 (1).  See L<http://www.tcpdump.org/linktypes.html> for the complete list
 148 of possible encapsulations.  Note that this option should be used if
 149 your dump is a complete hex dump of an encapsulated packet and you wish
 150 to specify the exact type of encapsulation.  Example: I<-l 7> for ARCNet
 151 packets encapsulated BSD-style.
 152
 153 =item -m E<lt>max-packetE<gt>
 154
 155 Set the maximum packet length, default is 262144.
 156 Useful for testing various packet boundaries when only an application
 157 level datastream is available.  Example:
 158
 159 I<od -Ax -tx1 -v stream | text2pcap -m1460 -T1234,1234 - stream.pcap>
 160
 161 will convert from plain datastream format to a sequence of Ethernet
 162 TCP packets.
 163
 164 =item -n
 165
 166 Write the file in pcapng format rather than pcap format.
 167
 168 =item -o hex|oct|dec
 169
 170 Specify the radix for the offsets (hex, octal or decimal). Defaults to
 171 hex. This corresponds to the C<-A> option for I<od>.
 172
 173 =item -q
 174
 175 Be completely quiet during the process.
 176
 177 =item -s E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>tagE<gt>
 178
 179 Include dummy SCTP headers before each packet.  Specify, in decimal, the
 180 source and destination SCTP ports, and verification tag, for the packet.
 181 Use this option if your dump is the SCTP payload of a packet but does
 182 not include any SCTP, IP or Ethernet headers.  Note that appropriate
 183 Ethernet and IP headers are automatically also included with each
 184 packet.  A CRC32C checksum will be put into the SCTP header.
 185
 186 =item -S E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>ppiE<gt>
 187
 188 Include dummy SCTP headers before each packet.  Specify, in decimal, the
 189 source and destination SCTP ports, and a verification tag of 0, for the
 190 packet, and prepend a dummy SCTP DATA chunk header with a payload
 191 protocol identifier if I<ppi>.  Use this option if your dump is the SCTP
 192 payload of a packet but does not include any SCTP, IP or Ethernet
 193 headers.  Note that appropriate Ethernet and IP headers are
 194 automatically included with each packet.  A CRC32C checksum will be put
 195 into the SCTP header.
 196
 197 =item -t E<lt>timefmtE<gt>
 198
 199 Treats the text before the packet as a date/time code; I<timefmt> is a
 200 format string of the sort supported by strptime(3).
 201 Example: The time "10:15:14.5476" has the format code "%H:%M:%S."
 202
 203 B<NOTE:> The subsecond component delimiter must be specified (.) but no
 204 pattern is required; the remaining number is assumed to be fractions of
 205 a second.
 206
 207 B<NOTE:> Date/time fields from the current date/time are
 208 used as the default for unspecified fields.
 209
 210 =item -T E<lt>srcportE<gt>,E<lt>destportE<gt>
 211
 212 Include dummy TCP headers before each packet. Specify the source and
 213 destination TCP ports for the packet in decimal. Use this option if
 214 your dump is the TCP payload of a packet but does not include any TCP,
 215 IP or Ethernet headers. Note that appropriate Ethernet and IP headers
 216 are automatically also included with each packet.
 217 Sequence numbers will start at 0.
 218
 219 =item -u E<lt>srcportE<gt>,E<lt>destportE<gt>
 220
 221 Include dummy UDP headers before each packet. Specify the source and
 222 destination UDP ports for the packet in decimal. Use this option if
 223 your dump is the UDP payload of a packet but does not include any UDP,
 224 IP or Ethernet headers. Note that appropriate Ethernet and IP headers
 225 are automatically also included with each packet.
 226 Example: I<-u1000,69> to make the packets look like TFTP/UDP packets.
 227
 228 =item -v
 229
 230 Print the version and exit.
 231
 232 =item -4 E<lt>srcipE<gt>,E<lt>destipE<gt>
 233
 234 Prepend dummy IP header with specified IPv4 dest and source address.
 235 This option should be accompanied by one of the following options: -i, -s, -S, -T, -u
 236 Use this option to apply "custom" IP addresses.
 237 Example: I<-4 10.0.0.1,10.0.0.2> to use 10.0.0.1 and 10.0.0.2 for all IP packets.
 238
 239 =item -6 E<lt>srcipE<gt>,E<lt>destipE<gt>
 240
 241 Prepend dummy IP header with specified IPv6 dest and source address.
 242 This option should be accompanied by one of the following options: -i, -s, -S, -T, -u
 243 Use this option to apply "custom" IP addresses.
 244 Example: I<-6 fe80:0:0:0:202:b3ff:fe1e:8329, 2001:0db8:85a3:0000:0000:8a2e:0370:7334> to
 245 use fe80:0:0:0:202:b3ff:fe1e:8329 and 2001:0db8:85a3:0000:0000:8a2e:0370:7334 for all IP packets.
 246
 247 =back
 248
 249 =head1 SEE ALSO
 250
 251 od(1), pcap(3), wireshark(1), tshark(1), dumpcap(1), mergecap(1),
 252 editcap(1), strptime(3), pcap-filter(7) or tcpdump(8)
 253
 254 =head1 NOTES
 255
 256 B<Text2pcap> is part of the B<Wireshark> distribution.  The latest version
 257 of B<Wireshark> can be found at L<https://www.wireshark.org>.
 258
 259 =head1 AUTHORS
 260
 261   Ashok Narayanan          <ashokn[AT]cisco.com>