nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1  
2 =head1 NAME
3  
4 editcap - Edit and/or translate the format of capture files
5  
6 =head1 SYNOPSIS
7  
8 B<editcap>
9 S<[ B<-a> E<lt>frame:commentE<gt> ]>
10 S<[ B<-A> E<lt>start timeE<gt> ]>
11 S<[ B<-B> E<lt>stop timeE<gt> ]>
12 S<[ B<-c> E<lt>packets per fileE<gt> ]>
13 S<[ B<-C> [offset:]E<lt>choplenE<gt> ]>
14 S<[ B<-E> E<lt>error probabilityE<gt> ]>
15 S<[ B<-F> E<lt>file formatE<gt> ]>
16 S<[ B<-h> ]>
17 S<[ B<-i> E<lt>seconds per fileE<gt> ]>
18 S<[ B<-o> E<lt>change offsetE<gt> ]>
19 S<[ B<-L> ]>
20 S<[ B<-r> ]>
21 S<[ B<-s> E<lt>snaplenE<gt> ]>
22 S<[ B<-S> E<lt>strict time adjustmentE<gt> ]>
23 S<[ B<-t> E<lt>time adjustmentE<gt> ]>
24 S<[ B<-T> E<lt>encapsulation typeE<gt> ]>
25 S<[ B<-v> ]>
26 I<infile>
27 I<outfile>
28 S<[ I<packet#>[-I<packet#>] ... ]>
29  
30 B<editcap>
31 S< B<-d> > |
32 S< B<-D> E<lt>dup windowE<gt> > |
33 S< B<-w> E<lt>dup time windowE<gt> >
34 S<[ B<-v> ]>
35 S<[ B<-I> E<lt>bytes to ignoreE<gt> ]>
36 I<infile>
37 I<outfile>
38  
39 B<editcap>
40 S<[ B<-V> ]>
41  
42 =head1 DESCRIPTION
43  
44 B<Editcap> is a program that reads some or all of the captured packets from the
45 I<infile>, optionally converts them in various ways and writes the
46 resulting packets to the capture I<outfile> (or outfiles).
47  
48 By default, it reads all packets from the I<infile> and writes them to the
49 I<outfile> in pcap file format.
50  
51 An optional list of packet numbers can be specified on the command tail;
52 individual packet numbers separated by whitespace and/or ranges of packet
53 numbers can be specified as I<start>-I<end>, referring to all packets from
54 I<start> to I<end>. By default the selected packets with those numbers will
55 I<not> be written to the capture file. If the B<-r> flag is specified, the
56 whole packet selection is reversed; in that case I<only> the selected packets
57 will be written to the capture file.
58  
59 B<Editcap> can also be used to remove duplicate packets. Several different
60 options (B<-d>, B<-D> and B<-w>) are used to control the packet window
61 or relative time window to be used for duplicate comparison.
62  
63 B<Editcap> can be used to assign comment strings to frame numbers.
64  
65 B<Editcap> is able to detect, read and write the same capture files that
66 are supported by B<Wireshark>.
67 The input file doesn't need a specific filename extension; the file
68 format and an optional gzip compression will be automatically detected.
69 Near the beginning of the DESCRIPTION section of wireshark(1) or
70 L<https://www.wireshark.org/docs/man-pages/wireshark.html>
71 is a detailed description of the way B<Wireshark> handles this, which is
72 the same way B<Editcap> handles this.
73  
74 B<Editcap> can write the file in several output formats. The B<-F>
75 flag can be used to specify the format in which to write the capture
76 file; B<editcap -F> provides a list of the available output formats.
77  
78 =head1 OPTIONS
79  
80 =over 4
81  
82 =item -a E<lt>framenum:commentE<gt>
83  
84 For the specificed frame number, assign the given comment string.
85 Can be repeated for multiple frames. Quotes should be used with comment
86 strings that include spaces.
87  
88 =item -A E<lt>start timeE<gt>
89  
90 Saves only the packets whose timestamp is on or after start time.
91 The time is given in the following format YYYY-MM-DD HH:MM:SS
92  
93 =item -B E<lt>stop timeE<gt>
94  
95 Saves only the packets whose timestamp is before stop time.
96 The time is given in the following format YYYY-MM-DD HH:MM:SS
97  
98 =item -c E<lt>packets per fileE<gt>
99  
100 Splits the packet output to different files based on uniform packet counts
101 with a maximum of <packets per file> each. Each output file will
102 be created with a suffix -nnnnn, starting with 00000. If the specified
103 number of packets is written to the output file, the next output file is
104 opened. The default is to use a single output file.
105  
106 =item -C [offset:]E<lt>choplenE<gt>
107  
108 Sets the chop length to use when writing the packet data. Each packet is
109 chopped by <choplen> bytes of data. Positive values chop at the packet
110 beginning while negative values chop at the packet end.
111  
112 If an optional offset precedes the <choplen>, then the bytes chopped will be
113 offset from that value. Positive offsets are from the packet beginning, while
114 negative offsets are from the packet end.
115  
116 This is useful for chopping headers for decapsulation of an entire capture,
117 removing tunneling headers, or in the rare case that the conversion between two
118 file formats leaves some random bytes at the end of each packet. Another use is
119 for removing vlan tags.
120  
121 NOTE: This option can be used more than once, effectively allowing you to chop
122 bytes from up to two different areas of a packet in a single pass provided that
123 you specify at least one chop length as a positive value and at least one as a
124 negative value. All positive chop lengths are added together as are all
125 negative chop lengths.
126  
127 =item -d
128  
129 Attempts to remove duplicate packets. The length and MD5 hash of the
130 current packet are compared to the previous four (4) packets. If a
131 match is found, the current packet is skipped. This option is equivalent
132 to using the option B<-D 5>.
133  
134 =item -D E<lt>dup windowE<gt>
135  
136 Attempts to remove duplicate packets. The length and MD5 hash of the
137 current packet are compared to the previous <dup window> - 1 packets.
138 If a match is found, the current packet is skipped.
139  
140 The use of the option B<-D 0> combined with the B<-v> option is useful
141 in that each packet's Packet number, Len and MD5 Hash will be printed
142 to standard out. This verbose output (specifically the MD5 hash strings)
143 can be useful in scripts to identify duplicate packets across trace
144 files.
145  
146 The <dup window> is specified as an integer value between 0 and 1000000 (inclusive).
147  
148 NOTE: Specifying large <dup window> values with large tracefiles can
149 result in very long processing times for B<editcap>.
150  
151 =item -E E<lt>error probabilityE<gt>
152  
153 Sets the probability that bytes in the output file are randomly changed.
154 B<Editcap> uses that probability (between 0.0 and 1.0 inclusive)
155 to apply errors to each data byte in the file. For instance, a
156 probability of 0.02 means that each byte has a 2% chance of having an error.
157  
158 This option is meant to be used for fuzz-testing protocol dissectors.
159  
160 =item -F E<lt>file formatE<gt>
161  
162 Sets the file format of the output capture file.
163 B<Editcap> can write the file in several formats, B<editcap -F>
164 provides a list of the available output formats. The default
165 is the B<pcap> format.
166  
167 =item -h
168  
169 Prints the version and options and exits.
170  
171 =item -i E<lt>seconds per fileE<gt>
172  
173 Splits the packet output to different files based on uniform time intervals
174 using a maximum interval of <seconds per file> each. Each output file will
175 be created with a suffix -nnnnn, starting with 00000. If packets for the specified
176 time interval are written to the output file, the next output file is
177 opened. The default is to use a single output file.
178  
179 =item -I E<lt>bytes to ignoreE<gt>
180  
181 Ignore the specified bytes number at the beginning of the frame during MD5 hash calculation
182 Useful to remove duplicated packets taken on several routers(differents mac addresses for example)
183 e.g. -I 26 in case of Ether/IP/ will ignore ether(14) and IP header(20 - 4(src ip) - 4(dst ip)).
184 The default value is 0.
185  
186 =item -L
187  
188 Adjust the original frame length accordingly when chopping and/or snapping
189 (in addition to the captured length, which is always adjusted regardless of
190 whether B<-L> is specified or not). See also B<-C <choplen>> and B<-s <snaplen>>.
191  
192 =item -o E<lt>change offsetE<gt>
193  
194 When used in conjunction with -E, skip some bytes from the beginning of the packet
195 from being changed. In this way some headers don't get changed, and the fuzzer is
196 more focused on a smaller part of the packet. Keeping a part of the packet fixed
197 the same dissector is triggered, that make the fuzzing more precise.
198  
199 =item -r
200  
201 Reverse the packet selection.
202 Causes the packets whose packet numbers are specified on the command
203 line to be written to the output capture file, instead of discarding them.
204  
205 =item -s E<lt>snaplenE<gt>
206  
207 Sets the snapshot length to use when writing the data.
208 If the B<-s> flag is used to specify a snapshot length, packets in the
209 input file with more captured data than the specified snapshot length
210 will have only the amount of data specified by the snapshot length
211 written to the output file.
212  
213 This may be useful if the program that is
214 to read the output file cannot handle packets larger than a certain size
215 (for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
216 appear to reject Ethernet packets larger than the standard Ethernet MTU,
217 making them incapable of handling gigabit Ethernet captures if jumbo
218 packets were used).
219  
220 =item -S E<lt>strict time adjustmentE<gt>
221  
222 Time adjust selected packets to ensure strict chronological order.
223  
224 The <strict time adjustment> value represents relative seconds
225 specified as [-]I<seconds>[I<.fractional seconds>].
226  
227 As the capture file is processed each packet's absolute time is
228 I<possibly> adjusted to be equal to or greater than the previous
229 packet's absolute timestamp depending on the <strict time
230 adjustment> value.
231  
232 If <strict time adjustment> value is 0 or greater (e.g. 0.000001)
233 then B<only> packets with a timestamp less than the previous packet
234 will adjusted. The adjusted timestamp value will be set to be
235 equal to the timestamp value of the previous packet plus the value
236 of the <strict time adjustment> value. A <strict time adjustment>
237 value of 0 will adjust the minimum number of timestamp values
238 necessary to ensure that the resulting capture file is in
239 strict chronological order.
240  
241 If <strict time adjustment> value is specified as a
242 negative value, then the timestamp values of B<all>
243 packets will be adjusted to be equal to the timestamp value
244 of the previous packet plus the absolute value of the
245 <lt>strict time adjustment<gt> value. A <strict time
246 adjustment> value of -0 will result in all packets
247 having the timestamp value of the first packet.
248  
249 This feature is useful when the trace file has an occasional
250 packet with a negative delta time relative to the previous
251 packet.
252  
253 =item -t E<lt>time adjustmentE<gt>
254  
255 Sets the time adjustment to use on selected packets.
256 If the B<-t> flag is used to specify a time adjustment, the specified
257 adjustment will be applied to all selected packets in the capture file.
258 The adjustment is specified as [-]I<seconds>[I<.fractional seconds>].
259 For example, B<-t> 3600 advances the timestamp on selected packets by one
260 hour while B<-t> -0.5 reduces the timestamp on selected packets by
261 one-half second.
262  
263 This feature is useful when synchronizing dumps
264 collected on different machines where the time difference between the
265 two machines is known or can be estimated.
266  
267 =item -T E<lt>encapsulation typeE<gt>
268  
269 Sets the packet encapsulation type of the output capture file.
270 If the B<-T> flag is used to specify an encapsulation type, the
271 encapsulation type of the output capture file will be forced to the
272 specified type.
273 B<editcap -T> provides a list of the available types. The default
274 type is the one appropriate to the encapsulation type of the input
275 capture file.
276  
277 Note: this merely
278 forces the encapsulation type of the output file to be the specified
279 type; the packet headers of the packets will not be translated from the
280 encapsulation type of the input capture file to the specified
281 encapsulation type (for example, it will not translate an Ethernet
282 capture to an FDDI capture if an Ethernet capture is read and 'B<-T
283 fddi>' is specified). If you need to remove/add headers from/to a
284 packet, you will need od(1)/text2pcap(1).
285  
286 =item -v
287  
288 Causes B<editcap> to print verbose messages while it's working.
289  
290 Use of B<-v> with the de-duplication switches of B<-d>, B<-D> or B<-w>
291 will cause all MD5 hashes to be printed whether the packet is skipped
292 or not.
293  
294 =item -V
295  
296 Print the version and exit.
297  
298 =item -w E<lt>dup time windowE<gt>
299  
300 Attempts to remove duplicate packets. The current packet's arrival time
301 is compared with up to 1000000 previous packets. If the packet's relative
302 arrival time is I<less than or equal to> the <dup time window> of a previous packet
303 and the packet length and MD5 hash of the current packet are the same then
304 the packet to skipped. The duplicate comparison test stops when
305 the current packet's relative arrival time is greater than <dup time window>.
306  
307 The <dup time window> is specified as I<seconds>[I<.fractional seconds>].
308  
309 The [.fractional seconds] component can be specified to nine (9) decimal
310 places (billionths of a second) but most typical trace files have resolution
311 to six (6) decimal places (millionths of a second).
312  
313 NOTE: Specifying large <dup time window> values with large tracefiles can
314 result in very long processing times for B<editcap>.
315  
316 NOTE: The B<-w> option assumes that the packets are in chronological order.
317 If the packets are NOT in chronological order then the B<-w> duplication
318 removal option may not identify some duplicates.
319  
320 =back
321  
322 =head1 EXAMPLES
323  
324 To see more detailed description of the options use:
325  
326 editcap -h
327  
328 To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use:
329  
330 editcap -s 64 -F snoop capture.pcap shortcapture.snoop
331  
332 To delete packet 1000 from the capture file use:
333  
334 editcap capture.pcap sans1000.pcap 1000
335  
336 To limit a capture file to packets from number 200 to 750 (inclusive) use:
337  
338 editcap -r capture.pcap small.pcap 200-750
339  
340 To get all packets from number 1-500 (inclusive) use:
341  
342 editcap -r capture.pcap first500.pcap 1-500
343  
344 or
345  
346 editcap capture.pcap first500.pcap 501-9999999
347  
348 To exclude packets 1, 5, 10 to 20 and 30 to 40 from the new file use:
349  
350 editcap capture.pcap exclude.pcap 1 5 10-20 30-40
351  
352 To select just packets 1, 5, 10 to 20 and 30 to 40 for the new file use:
353  
354 editcap -r capture.pcap select.pcap 1 5 10-20 30-40
355  
356 To remove duplicate packets seen within the prior four frames use:
357  
358 editcap -d capture.pcap dedup.pcap
359  
360 To remove duplicate packets seen within the prior 100 frames use:
361  
362 editcap -D 101 capture.pcap dedup.pcap
363  
364 To remove duplicate packets seen I<equal to or less than> 1/10th of a second:
365  
366 editcap -w 0.1 capture.pcap dedup.pcap
367  
368 To display the MD5 hash for all of the packets (and NOT generate any
369 real output file):
370  
371 editcap -v -D 0 capture.pcap /dev/null
372  
373 or on Windows systems
374  
375 editcap -v -D 0 capture.pcap NUL
376  
377 To advance the timestamps of each packet forward by 3.0827 seconds:
378  
379 editcap -t 3.0827 capture.pcap adjusted.pcap
380  
381 To ensure all timestamps are in strict chronological order:
382  
383 editcap -S 0 capture.pcap adjusted.pcap
384  
385 To introduce 5% random errors in a capture file use:
386  
387 editcap -E 0.05 capture.pcap capture_error.pcap
388  
389 To remove vlan tags from all packets within an Ethernet-encapsulated capture
390 file, use:
391  
392 editcap -L -C 12:4 capture_vlan.pcap capture_no_vlan.pcap
393  
394 To chop both the 10 byte and 20 byte regions from the following 75 byte packet
395 in a single pass, use any of the 8 possible methods provided below:
396  
397 <--------------------------- 75 ---------------------------->
398  
399 +---+-------+-----------+---------------+-------------------+
400 | 5 | 10 | 15 | 20 | 25 |
401 +---+-------+-----------+---------------+-------------------+
402  
403 1) editcap -C 5:10 -C -25:-20 capture.pcap chopped.pcap
404 2) editcap -C 5:10 -C 50:-20 capture.pcap chopped.pcap
405 3) editcap -C -70:10 -C -25:-20 capture.pcap chopped.pcap
406 4) editcap -C -70:10 -C 50:-20 capture.pcap chopped.pcap
407 5) editcap -C 30:20 -C -60:-10 capture.pcap chopped.pcap
408 6) editcap -C 30:20 -C 15:-10 capture.pcap chopped.pcap
409 7) editcap -C -45:20 -C -60:-10 capture.pcap chopped.pcap
410 8) editcap -C -45:20 -C 15:-10 capture.pcap chopped.pcap
411  
412 To add comment strings to the first 2 input frames, use:
413  
414 editcap -a "1:1st frame" -a 2:Second capture.pcap capture-comments.pcap
415  
416 =head1 SEE ALSO
417  
418 pcap(3), wireshark(1), tshark(1), mergecap(1), dumpcap(1), capinfos(1),
419 text2pcap(1), od(1), pcap-filter(7) or tcpdump(8)
420  
421 =head1 NOTES
422  
423 B<Editcap> is part of the B<Wireshark> distribution. The latest version
424 of B<Wireshark> can be found at L<https://www.wireshark.org>.
425  
426 HTML versions of the Wireshark project man pages are available at:
427 L<https://www.wireshark.org/docs/man-pages>.
428  
429 =head1 AUTHORS
430  
431 Original Author
432 -------- ------
433 Richard Sharpe <sharpe[AT]ns.aus.com>
434  
435  
436 Contributors
437 ------------
438 Guy Harris <guy[AT]alum.mit.edu>
439 Ulf Lamping <ulf.lamping[AT]web.de>