Clean up the example for the "-m" flag.
[obnox/wireshark/wip.git] / doc / text2pcap.pod
1
2 =head1 NAME
3
4 text2pcap - Generate a capture file from an ASCII hexdump of packets
5
6 =head1 SYNOPSYS
7
8 B<text2pcap>
9 S<[ B<-h> ]>
10 S<[ B<-d> ]>
11 S<[ B<-q> ]>
12 S<[ B<-o> hex|oct ]>
13 S<[ B<-l> typenum ]>
14 S<[ B<-e> l3pid ]>
15 S<[ B<-i> proto ]>
16 S<[ B<-m> max-packet ]>
17 S<[ B<-u> srcport,destport ]>
18 S<[ B<-T> srcport,destport ]>
19 S<[ B<-s> srcport,destport,tag ]>
20 S<[ B<-S> srcport,destport,ppi ]>
21 S<[ B<-t> timefmt ]>
22 I<infile>
23 I<outfile>
24
25 =head1 DESCRIPTION
26
27 B<Text2pcap> is a program that reads in an ASCII hex dump and writes
28 the data described into a B<libpcap>-style capture file. B<text2pcap>
29 can read hexdumps with multiple packets in them, and build a capture
30 file of multiple packets. B<text2pcap> is also capable of generating
31 dummy Ethernet, IP and UDP or TCP headers, in order to build fully
32 processable packet dumps from hexdumps of application-level data
33 only. 
34
35 B<Text2pcap> understands a hexdump of the form generated by I<od -t
36 x1>. In other words, each byte is individually displayed and
37 surrounded with a space. Each line begins with an offset describing
38 the position in the file. The offset is a hex number (can also be
39 octal - see B<-o>), of more than two hex digits. Here is a sample dump
40 that B<text2pcap> can recognize:
41
42     000000 00 e0 1e a7 05 6f 00 10 ........
43     000008 5a a0 b9 12 08 00 46 00 ........
44     000010 03 68 00 00 00 00 0a 2e ........
45     000018 ee 33 0f 19 08 7f 0f 19 ........
46     000020 03 80 94 04 00 00 10 01 ........
47     000028 16 a2 0a 00 03 50 00 0c ........
48     000030 01 01 0f 19 03 80 11 01 ........
49
50 There is no limit on the width or number of bytes per line. Also the
51 text dump at the end of the line is ignored. Bytes/hex numbers can be
52 uppercase or lowercase. Any text before the offset is ignored,
53 including email forwarding characters '>'. Any lines of text between
54 the bytestring lines is ignored. The offsets are used to track the
55 bytes, so offsets must be correct. Any line which has only bytes
56 without a leading offset is ignored. An offset is recognized as being
57 a hex number longer than two characters. Any text after the bytes is
58 ignored (e.g. the character dump). Any hex numbers in this text are
59 also ignored. An offset of zero is indicative of starting a new
60 packet, so a single text file with a series of hexdumps can be
61 converted into a packet capture with multiple packets. Multiple
62 packets are read in with timestamps differing by one second each. In
63 general, short of these restrictions, B<text2pcap> is pretty liberal
64 about reading in hexdumps and has been tested with a variety of
65 mangled outputs (including being forwarded through email multiple
66 times, with limited line wrap etc.)
67
68 There are a couple of other special features to note. Any line where
69 the first non-whitespace character is '#' will be ignored as a
70 comment. Any line beginning with #TEXT2PCAP is a directive and options
71 can be inserted after this command to be processed by
72 B<text2pcap>. Currently there are no directives implemented; in the
73 future, these may be used to give more fine grained control on the
74 dump and the way it should be processed e.g. timestamps, encapsulation
75 type etc.
76
77 B<Text2pcap> also allows the user to read in dumps of
78 application-level data, by inserting dummy L2, L3 and L4 headers
79 before each packet. The user can elect to insert Ethernet headers,
80 Ethernet and IP, or Ethernet, IP and UDP/TCP headers before each
81 packet. This allows Ethereal or any other full-packet decoder to
82 handle these dumps.
83
84 =head1 OPTIONS
85
86 =over 4
87
88 =item -h
89
90 Displays a help message.
91
92 =item -d
93
94 Displays debugging information during the process. Can be used
95 multiple times to generate more debugging information.
96
97 =item -q
98
99 Be completely quiet during the process.
100
101 =item -o hex|oct
102
103 Specify the radix for the offsets (hex or octal). Defaults to
104 hex. This corresponds to the C<-A> option for I<od>.
105
106 =item -l
107
108 Specify the link-layer type of this packet. Default is Ethernet
109 (1). See I<net/bpf.h> for the complete list of possible
110 encapsulations. Note that this option should be used if your dump is a
111 complete hex dump of an encapsulated packet and you wish to specify
112 the exact type of encapsulation. Example: I<-l 7> for ARCNet packets.
113
114 =item -e l3pid
115
116 Include a dummy Ethernet header before each packet. Specify the L3PID
117 for the Ethernet header in hex. Use this option if your dump has Layer
118 3 header and payload (e.g. IP header), but no Layer 2
119 encapsulation. Example: I<-e 0x806> to specify an ARP packet. 
120
121 For IP packets, instead of generating a fake Ethernet header you can
122 also use I<-l 12> to indicate a raw IP packet to Ethereal. Note that
123 I<-l 12> does not work for any non-IP Layer 3 packet (e.g. ARP),
124 whereas generating a dummy Ethernet header with I<-e> works for any
125 sort of L3 packet.
126
127 =item -i proto
128
129 Include dummy IP headers before each packet. Specify the IP protocol
130 for the packet in decimal. Use this option if your dump is the payload
131 of an IP packet (i.e. has complete L4 information) but does not have
132 an IP header. Note that this automatically includes an appropriate
133 Ethernet header as well. Example: I<-i 46> to specify an RSVP packet
134 (IP protocol 46).
135
136 =item -m max-packet
137
138 Set the maximum packet length, default is 64000.
139 Useful for testing various packet boundaries when only an application
140 level datastream is available.  Example:
141
142 I<od -Ax -tx1 stream | text2pcap -m1460 -T1234,1234 - stream.pcap>
143
144 will convert from plain datastream format to a sequence of Ethernet
145 TCP packets.
146
147 =item -u srcport,destport
148
149 Include dummy UDP headers before each packet. Specify the source and
150 destination UDP ports for the packet in decimal. Use this option if
151 your dump is the UDP payload of a packet but does not include any UDP,
152 IP or Ethernet headers. Note that this automatically includes
153 appropriate Ethernet and IP headers with each packet. Example: I<-u
154 1000,69> to make the packets look like TFTP/UDP packets.
155
156 =item -T srcport,destport
157
158 Include dummy TCP headers before each packet. Specify the source and
159 destination TCP ports for the packet in decimal. Use this option if
160 your dump is the TCP payload of a packet but does not include any TCP,
161 IP or Ethernet headers. Note that this automatically includes
162 appropriate Ethernet and IP headers with each packet.
163 Sequence numbers will start a 0.
164
165 =item -s srcport,destport,tag
166
167 Include dummy SCTP headers before each packet.  Specify, in decimal, the
168 source and destination SCTP ports, and verification tag, for the packet. 
169 Use this option if your dump is the SCTP payload of a packet but does
170 not include any SCTP, IP or Ethernet headers.  Note that this
171 automatically includes appropriate Ethernet and IP headers with each
172 packet.  A CRC32C checksum will be put into the SCTP header.
173
174 =item -S srcport,destport,ppi
175
176 Include dummy SCTP headers before each packet.  Specify, in decimal, the
177 source and destination SCTP ports, and a verification tag of 0, for the
178 packet, and prepend a dummy SCTP DATA chunk header with a payload
179 protocol identifier if I<ppi>.  Use this option if your dump is the SCTP
180 payload of a packet but does not include any SCTP, IP or Ethernet
181 headers.  Note that this automatically includes appropriate Ethernet and
182 IP headers with each packet.  A CRC32C checksum will be put into the
183 SCTP header.
184
185 =item -t timefmt
186
187 Treats the text before the packet as a date/time code; I<timefmt> is a
188 format string of the sort supported by B<strptime(3)>.
189 Example: The time "10:15:14.5476" has the format code "%H:%M:%S."
190
191 B<NOTE:> The subsecond component delimiter must be specified (.) but no
192 pattern is required; the remaining number is assumed to be fractions of
193 a second.
194
195 =head1 SEE ALSO
196
197 I<tcpdump(8)>, I<pcap(3)>, I<ethereal(1)>, I<editcap(1)>, I<strptime(3)>.
198
199 =head1 NOTES
200
201 B<Text2pcap> is part of the B<Ethereal> distribution.  The latest version
202 of B<Ethereal> can be found at B<http://www.ethereal.com>.
203
204 =head1 AUTHORS
205
206   Ashok Narayanan          <ashokn[AT]cisco.com>