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