added <>: [-c packets per file] -> [-c <packets per file>]
[obnox/wireshark/wip.git] / doc / editcap.pod
1
2 =head1 NAME
3
4 editcap - Edit and/or translate the format of capture files
5
6 =head1 SYNOPSYS
7
8 B<editcap>
9 S<[ B<-c> E<lt>packets per fileE<gt> ]>
10 S<[ B<-C> E<lt>choplenE<gt> ]>
11 S<[ B<-E> E<lt>error probabilityE<gt> ]>
12 S<[ B<-F> E<lt>file formatE<gt> ]>
13 S<[ B<-h> ]>
14 S<[ B<-r> ]>
15 S<[ B<-s> E<lt>snaplenE<gt> ]>
16 S<[ B<-t> E<lt>time adjustmentE<gt> ]>
17 S<[ B<-T> E<lt>encapsulation typeE<gt> ]>
18 S<[ B<-v> ]>
19 I<infile>
20 I<outfile>
21 S<[ I<packet#>[-I<packet#>] ... ]>
22
23 =head1 DESCRIPTION
24
25 B<Editcap> is a program that reads some or all of the captured packets from the 
26 I<infile>, optionally converts them in various ways and writes the 
27 resulting packets to the capture I<outfile> (or outfiles). 
28
29 By default, it reads all packets from the I<infile> and writes them to the I<outfile>
30 in libpcap file format.
31
32 A list of packet numbers can be specified on the command line; ranges of packet numbers can be
33 specified as I<start>-I<end>, referring to all packets from I<start> to
34 I<end>.
35 The selected packets with those numbers will I<not> be written to the capture file. 
36 If the B<-r> flag is specified, the whole packet selection is reversed; in that case I<only> the selected packets
37 will be written to the capture file.  
38
39 The supported input and output capture file formats are described in a section below.
40
41 =head1 OPTIONS
42
43 =over 4
44
45 =item -c  E<lt>packets per fileE<gt>
46
47 Sets the maximum number of packets per output file. Each output file will 
48 be created with a suffix -nnnnn, starting with 00000. If the specified 
49 number of packets are written to the output file, the next output file is 
50 opened. The default is to use a single output file.
51
52 =item -C  E<lt>choplenE<gt>
53
54 Sets the chop length to use when writing the packet data.
55 Each packet is chopped at the packet end by a few <choplen> bytes of data.
56
57 This is useful in the rare case that the conversion between two file 
58 formats leaves some random bytes at the end of each packet.
59
60 =item -E  E<lt>error probabilityE<gt>
61
62 Sets the probabilty that bytes in the output file are randomly changed.
63 B<Editcap> uses that probability (between 0.0 and 1.0 inclusive) 
64 to apply errors to each data byte in the file.  For instance, a 
65 probability of 0.02 means that each byte has a 2% chance of having an error.
66
67 This option is meant to be used for fuzz-testing protocol dissectors.
68
69 =item -F  E<lt>file formatE<gt>
70
71 Sets the file format of the output capture file.
72 B<Editcap> can write the file in several formats, B<editcap -F> 
73 provides a list of the available output formats. The default
74 is the B<libpcap> format.
75
76 =item -h
77
78 Prints the version and options and exits.
79
80 =item -r
81
82 Reverse the packet selection.
83 Causes the packets whose packet numbers are specified on the command
84 line to be written to the output capture file, instead of discarding them.
85
86 =item -s  E<lt>snaplenE<gt>
87
88 Sets the snapshot length to use when writing the data.
89 If the B<-s> flag is used to specify a snapshot length, packets in the
90 input file with more captured data than the specified snapshot length
91 will have only the amount of data specified by the snapshot length
92 written to the output file.  
93
94 This may be useful if the program that is
95 to read the output file cannot handle packets larger than a certain size
96 (for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
97 appear to reject Ethernet packets larger than the standard Ethernet MTU,
98 making them incapable of handling gigabit Ethernet captures if jumbo
99 packets were used).
100
101 =item -t  E<lt>time adjustmentE<gt>
102
103 Sets the time adjustment to use on selected packets.
104 If the B<-t> flag is used to specify a time adjustment, the specified
105 adjustment will be applied to all selected packets in the capture file.
106 The adjustment is specified as [-]I<seconds>[I<.fractional seconds>].
107 For example, B<-t> 3600 advances the timestamp on selected packets by one
108 hour while B<-t> -0.5 reduces the timestamp on selected packets by
109 one-half second.  
110
111 This feature is useful when synchronizing dumps
112 collected on different machines where the time difference between the
113 two machines is known or can be estimated.
114
115 =item -T  E<lt>encapsulation typeE<gt>
116
117 Sets the packet encapsulation type of the output capture file.
118 If the B<-T> flag is used to specify an encapsulation type, the
119 encapsulation type of the output capture file will be forced to the
120 specified type. 
121 B<editcap -T> provides a list of the available types. The default
122 type is the one appropriate to the encapsulation type of the input 
123 capture file.
124
125 Note: this merely
126 forces the encapsulation type of the output file to be the specified
127 type; the packet headers of the packets will not be translated from the
128 encapsulation type of the input capture file to the specified
129 encapsulation type (for example, it will not translate an Ethernet
130 capture to an FDDI capture if an Ethernet capture is read and 'B<-T
131 fddi>' is specified).
132
133 =item -v
134
135 Causes B<editcap> to print verbose messages while it's working.
136
137 =back
138
139 =head1 EXAMPLES
140
141 To see more detailed description of the options use:
142
143     editcap -h
144
145 To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use:
146
147     editcap -s 64 -F snoop capture.pcap shortcapture.snoop
148
149 To delete packet 1000 from the capture file use:
150
151     editcap capture.pcap sans1000.pcap 1000
152
153 To limit a capture file to packets from number 200 to 750 (inclusive) use:
154
155     editcap -r capture.pcap small.pcap 200-750
156
157 To get all packets from number 1-500 (inclusive) use:
158
159     editcap -r capture.pcap 500.pcap 1-500
160
161 or
162
163     editcap capture.pcap 500.pcap 501-9999999
164
165 To filter out packets 10 to 20 and 30 to 40 into a new file use:
166
167     editcap capture.pcap selection.pcap 10-20 30-40
168
169 To introduce 5% random errors in a capture file use:
170
171 =over 4
172
173   editcap -E 0.05 capture.pcap capture_error.pcap
174
175 =back
176
177 =head1 Capture File Formats
178
179 There is no need to tell B<Editcap> what type of
180 file you are reading; it will determine the file type by itself. 
181
182 B<Editcap> is also capable of reading any of these file formats if they
183 are compressed using gzip. It recognizes this directly from the
184 file; the '.gz' extension is not required for this purpose.
185
186 The following I<input> file formats are supported:
187
188 =over 4
189
190 =item *
191 libpcap/WinPcap, tcpdump and various other tools using tcpdump's capture format
192
193 =item *
194 B<snoop> and B<atmsnoop>
195
196 =item *
197 Shomiti/Finisar B<Surveyor> captures
198
199 =item *
200 Novell B<LANalyzer> captures
201
202 =item *
203 Microsoft B<Network Monitor> captures
204
205 =item *
206 AIX's B<iptrace> captures
207
208 =item *
209 Cinco Networks B<NetXRay> captures
210
211 =item *
212 Network Associates Windows-based B<Sniffer> captures
213
214 =item *
215 Network General/Network Associates DOS-based B<Sniffer> (compressed or uncompressed) captures
216
217 =item *
218 AG Group/WildPackets B<EtherPeek>/B<TokenPeek>/B<AiroPeek>/B<EtherHelp>/B<PacketGrabber> captures
219
220 =item *
221 B<RADCOM>'s WAN/LAN analyzer captures
222
223 =item *
224 Network Instruments B<Observer> version 9 captures
225
226 =item *
227 B<Lucent/Ascend> router debug output
228
229 =item *
230 files from HP-UX's B<nettl>
231
232 =item *
233 B<Toshiba's> ISDN routers dump output
234
235 =item *
236 the output from B<i4btrace> from the ISDN4BSD project
237
238 =item *
239 traces from the B<EyeSDN> USB S0.
240
241 =item *
242 the output in B<IPLog> format from the Cisco Secure Intrusion Detection System
243
244 =item *
245 B<pppd logs> (pppdump format)
246
247 =item *
248 the output from VMS's B<TCPIPtrace>/B<TCPtrace>/B<UCX$TRACE> utilities
249
250 =item *
251 the text output from the B<DBS Etherwatch> VMS utility
252
253 =item *
254 Visual Networks' B<Visual UpTime> traffic capture
255
256 =item *
257 the output from B<CoSine> L2 debug
258
259 =item *
260 the output from Accellent's B<5Views> LAN agents
261
262 =item *
263 Endace Measurement Systems' ERF format captures 
264
265 =item *
266 Linux Bluez Bluetooth stack B<hcidump -w> traces
267
268 =back
269
270 B<Editcap> can write the file in several output formats. The B<-F>
271 flag can be used to specify the format in which to write the capture
272 file, B<editcap -F> provides
273 a list of the available output formats.
274
275 =head1 SEE ALSO
276
277 I<tcpdump(8)>, I<pcap(3)>, I<ethereal(1)>, I<mergecap(1)>
278
279 =head1 NOTES
280
281 B<Editcap> is part of the B<Ethereal> distribution.  The latest version
282 of B<Ethereal> can be found at B<http://www.ethereal.com>.
283
284 =head1 AUTHORS
285
286   Original Author
287   -------- ------
288   Richard Sharpe           <sharpe[AT]ns.aus.com>
289
290
291   Contributors
292   ------------
293   Guy Harris               <guy[AT]alum.mit.edu>
294   Ulf Lamping              <ulf.lamping[AT]web.de>