4 editcap - Edit and/or translate the format of capture files
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> ]>
17 S<[ B<-i> E<lt>seconds per fileE<gt> ]>
18 S<[ B<-o> E<lt>change offsetE<gt> ]>
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> ]>
28 S<[ I<packet#>[-I<packet#>] ... ]>
32 S< B<-D> E<lt>dup windowE<gt> > |
33 S< B<-w> E<lt>dup time windowE<gt> >
35 S<[ B<-I> E<lt>bytes to ignoreE<gt> ]>
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).
48 By default, it reads all packets from the I<infile> and writes them to the
49 I<outfile> in pcap file format.
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.
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.
63 B<Editcap> can be used to assign comment strings to frame numbers.
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.
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.
82 =item -a E<lt>framenum:commentE<gt>
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.
88 =item -A E<lt>start timeE<gt>
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
93 =item -B E<lt>stop timeE<gt>
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
98 =item -c E<lt>packets per fileE<gt>
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.
106 =item -C [offset:]E<lt>choplenE<gt>
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.
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.
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.
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.
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>.
134 =item -D E<lt>dup windowE<gt>
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.
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
146 The <dup window> is specified as an integer value between 0 and 1000000 (inclusive).
148 NOTE: Specifying large <dup window> values with large tracefiles can
149 result in very long processing times for B<editcap>.
151 =item -E E<lt>error probabilityE<gt>
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.
158 This option is meant to be used for fuzz-testing protocol dissectors.
160 =item -F E<lt>file formatE<gt>
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.
169 Prints the version and options and exits.
171 =item -i E<lt>seconds per fileE<gt>
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.
179 =item -I E<lt>bytes to ignoreE<gt>
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.
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>>.
192 =item -o E<lt>change offsetE<gt>
194 When used in conjuction 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.
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.
205 =item -s E<lt>snaplenE<gt>
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.
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
220 =item -S E<lt>strict time adjustmentE<gt>
222 Time adjust selected packets to ensure strict chronological order.
224 The <strict time adjustment> value represents relative seconds
225 specified as [-]I<seconds>[I<.fractional seconds>].
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
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.
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.
249 This feature is useful when the trace file has an occasional
250 packet with a negative delta time relative to the previous
253 =item -t E<lt>time adjustmentE<gt>
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
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.
267 =item -T E<lt>encapsulation typeE<gt>
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
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
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).
288 Causes B<editcap> to print verbose messages while it's working.
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
296 Print the version and exit.
298 =item -w E<lt>dup time windowE<gt>
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>.
307 The <dup time window> is specified as I<seconds>[I<.fractional seconds>].
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).
313 NOTE: Specifying large <dup time window> values with large tracefiles can
314 result in very long processing times for B<editcap>.
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.
324 To see more detailed description of the options use:
328 To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use:
330 editcap -s 64 -F snoop capture.pcap shortcapture.snoop
332 To delete packet 1000 from the capture file use:
334 editcap capture.pcap sans1000.pcap 1000
336 To limit a capture file to packets from number 200 to 750 (inclusive) use:
338 editcap -r capture.pcap small.pcap 200-750
340 To get all packets from number 1-500 (inclusive) use:
342 editcap -r capture.pcap first500.pcap 1-500
346 editcap capture.pcap first500.pcap 501-9999999
348 To exclude packets 1, 5, 10 to 20 and 30 to 40 from the new file use:
350 editcap capture.pcap exclude.pcap 1 5 10-20 30-40
352 To select just packets 1, 5, 10 to 20 and 30 to 40 for the new file use:
354 editcap -r capture.pcap select.pcap 1 5 10-20 30-40
356 To remove duplicate packets seen within the prior four frames use:
358 editcap -d capture.pcap dedup.pcap
360 To remove duplicate packets seen within the prior 100 frames use:
362 editcap -D 101 capture.pcap dedup.pcap
364 To remove duplicate packets seen I<equal to or less than> 1/10th of a second:
366 editcap -w 0.1 capture.pcap dedup.pcap
368 To display the MD5 hash for all of the packets (and NOT generate any
371 editcap -v -D 0 capture.pcap /dev/null
373 or on Windows systems
375 editcap -v -D 0 capture.pcap NUL
377 To advance the timestamps of each packet forward by 3.0827 seconds:
379 editcap -t 3.0827 capture.pcap adjusted.pcap
381 To ensure all timestamps are in strict chronological order:
383 editcap -S 0 capture.pcap adjusted.pcap
385 To introduce 5% random errors in a capture file use:
387 editcap -E 0.05 capture.pcap capture_error.pcap
389 To remove vlan tags from all packets within an Ethernet-encapsulated capture
392 editcap -L -C 12:4 capture_vlan.pcap capture_no_vlan.pcap
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:
397 <--------------------------- 75 ---------------------------->
399 +---+-------+-----------+---------------+-------------------+
400 | 5 | 10 | 15 | 20 | 25 |
401 +---+-------+-----------+---------------+-------------------+
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
412 To add comment strings to the first 2 input frames, use:
414 editcap -a "1:1st frame" -a 2:Second capture.pcap capture-comments.pcap
418 pcap(3), wireshark(1), tshark(1), mergecap(1), dumpcap(1), capinfos(1),
419 text2pcap(1), od(1), pcap-filter(7) or tcpdump(8)
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>.
426 HTML versions of the Wireshark project man pages are available at:
427 L<https://www.wireshark.org/docs/man-pages>.
433 Richard Sharpe <sharpe[AT]ns.aus.com>
438 Guy Harris <guy[AT]alum.mit.edu>
439 Ulf Lamping <ulf.lamping[AT]web.de>