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