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