1EDITCAP(1)                                                          EDITCAP(1)
2
3
4

NAME

6       editcap - Edit and/or translate the format of capture files
7

SYNOPSIS

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
19       editcap -d -D <dup window> -w <dup time window> [ -v ]
20       [ -I <bytes to ignore> ] [ --skip-radiotap-header ] infile outfile
21
22       editcap [ -V ]
23

DESCRIPTION

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
29       By default, it reads all packets from the infile and writes them to the
30       outfile in pcapng file format.
31
32       The -A and -B option allow you to limit the time range from which
33       packets are read from the infile.
34
35       An optional list of packet numbers can be specified on the command
36       tail; individual packet numbers separated by whitespace and/or ranges
37       of packet numbers can be specified as start-end, referring to all
38       packets from start to end. By default the selected packets with those
39       numbers will not be written to the capture file. If the -r flag is
40       specified, the whole packet selection is reversed; in that case only
41       the selected packets will be written to the capture file.
42
43       Editcap can also be used to remove duplicate packets. Several different
44       options (-d, -D and -w) are used to control the packet window or
45       relative time window to be used for duplicate comparison.
46
47       Editcap can be used to assign comment strings to frame numbers.
48
49       Editcap is able to detect, read and write the same capture files that
50       are supported by Wireshark. The input file doesn’t need a specific
51       filename extension; the file format and an optional gzip, zstd or lz4
52       compression will be automatically detected. Near the beginning of the
53       DESCRIPTION section of wireshark(1) or
54       https://www.wireshark.org/docs/man-pages/wireshark.html is a detailed
55       description of the way Wireshark handles this, which is the same way
56       Editcap handles this.
57
58       Editcap can write the file in several output formats. The -F flag can
59       be used to specify the format in which to write the capture file;
60       editcap -F provides a list of the available output formats.
61

OPTIONS

63       -a  <framenum:comment>
64
65           For the specified frame number, assign the given comment string.
66           Can be repeated for multiple frames. Quotes should be used with
67           comment strings that include spaces.
68
69       -A  <start time>
70
71           Reads only the packets whose timestamp is on or after start time.
72           The time is given in ISO 8601 format, either YYYY-MM-DD
73           HH:MM:SS[.nnnnnnnnn][Z|±hh:mm] or
74           YYYY-MM-DDTHH:MM:SS[.nnnnnnnnn][Z|±hh:mm] . The fractional seconds
75           are optional, as is the time zone offset from UTC (in which case
76           local time is assumed). Unix epoch timestamps (floating point
77           format) are also accepted.
78
79       -B  <stop time>
80
81           Reads only the packets whose timestamp is before stop time. The
82           time is given in ISO 8601 format, either YYYY-MM-DD
83           HH:MM:SS[.nnnnnnnnn][Z|±hh:mm] or
84           YYYY-MM-DDTHH:MM:SS[.nnnnnnnnn][Z|±hh:mm] . The fractional seconds
85           are optional, as is the time zone offset from UTC (in which case
86           local time is assumed). Unix epoch timestamps (floating point
87           format) are also accepted.
88
89       -c  <packets per file>
90
91           Splits the packet output to different files based on uniform packet
92           counts with a maximum of <packets per file> each.
93
94           Each output file will be created with an infix
95           _nnnnn[_YYYYmmddHHMMSS] inserted before the file extension (which
96           may be null) of outfile. The infix consists of the ordinal number
97           of the output file, starting with 00000, followed by the timestamp
98           of its first packet. The timestamp is omitted if the input file
99           does not contain timestamp information.
100
101           After the specified number of packets is written to the output
102           file, the next output file is opened. The default is to use a
103           single output file. This option conflicts with -i.
104
105       -C  [offset:]<choplen>
106
107           Sets the chop length to use when writing the packet data. Each
108           packet is chopped by <choplen> bytes of data. Positive values chop
109           at the packet beginning while negative values chop at the packet
110           end.
111
112           If an optional offset precedes the <choplen>, then the bytes
113           chopped will be offset from that value. Positive offsets are from
114           the packet beginning, while negative offsets are from the packet
115           end.
116
117           This is useful for chopping headers for decapsulation of an entire
118           capture, removing tunneling headers, or in the rare case that the
119           conversion between two file formats leaves some random bytes at the
120           end of each packet. Another use is for removing vlan tags.
121
122               Note
123               This option can be used more than once, effectively allowing
124               you to chop bytes from up to two different areas of a packet in
125               a single pass provided that you specify at least one chop
126               length as a positive value and at least one as a negative
127               value. All positive chop lengths are added together as are all
128               negative chop lengths.
129
130       -d
131
132           Attempts to remove duplicate packets. The length and MD5 hash of
133           the current packet are compared to the previous four (4) packets.
134           If a match is found, the current packet is skipped. This option is
135           equivalent to using the option -D 5.
136
137       -D  <dup window>
138
139           Attempts to remove duplicate packets. The length and MD5 hash of
140           the current packet are compared to the previous <dup window> - 1
141           packets. If a match is found, the current packet is skipped.
142
143           The use of the option -D 0 combined with the -v option is useful in
144           that each packet’s Packet number, Len and MD5 Hash will be printed
145           to standard out. This verbose output (specifically the MD5 hash
146           strings) can be useful in scripts to identify duplicate packets
147           across trace files.
148
149           The <dup window> is specified as an integer value between 0 and
150           1000000 (inclusive).
151
152               Note
153               Specifying large <dup window> values with large tracefiles can
154               result in very long processing times for editcap.
155
156       -E  <error probability>
157
158           Sets the probability that bytes in the output file are randomly
159           changed. Editcap uses that probability (between 0.0 and 1.0
160           inclusive) to apply errors to each data byte in the file. For
161           instance, a probability of 0.02 means that each byte has a 2%
162           chance of having an error.
163
164           This option is meant to be used for fuzz-testing protocol
165           dissectors.
166
167       -F  <file format>
168
169           Sets the file format of the output capture file. Editcap can write
170           the file in several formats, editcap -F provides a list of the
171           available output formats. The default is the pcapng format.
172
173       -h
174
175           Prints the version and options and exits.
176
177       -i  <seconds per file>
178
179           Splits the packet output to different files based on uniform time
180           intervals using a maximum interval of <seconds per file> each.
181           Floating point values (e.g. 0.5) are allowed.
182
183           Each output file will be created with an infix
184           _nnnnn[_YYYYmmddHHMMSS] inserted before the file extension (which
185           may be null) of outfile. The infix consists of the ordinal number
186           of the output file, starting with 00000, followed by the timestamp
187           of its first packet. The timestamp is omitted if the input file
188           does not contain timestamp information.
189
190           After packets for the specified time interval are written to the
191           output file, the next output file is opened. The default is to use
192           a single output file. This option conflicts with -c.
193
194       -I  <bytes to ignore>
195
196           Ignore the specified number of bytes at the beginning of the frame
197           during MD5 hash calculation, unless the frame is too short, then
198           the full frame is used. Useful to remove duplicated packets taken
199           on several routers (different mac addresses for example) e.g. -I 26
200           in case of Ether/IP will ignore ether(14) and IP header(20 - 4(src
201           ip) - 4(dst ip)). The default value is 0.
202
203       -L
204
205           Adjust the original frame length accordingly when chopping and/or
206           snapping (in addition to the captured length, which is always
207           adjusted regardless of whether -L is specified or not). See also -C
208           <choplen> and -s <snaplen>.
209
210       -o  <change offset>
211
212           When used in conjunction with -E, skip some bytes from the
213           beginning of the packet from being changed. In this way some
214           headers don’t get changed, and the fuzzer is more focused on a
215           smaller part of the packet. Keeping a part of the packet fixed the
216           same dissector is triggered, that make the fuzzing more precise.
217
218       -r
219
220           Reverse the packet selection. Causes the packets whose packet
221           numbers are specified on the command line to be written to the
222           output capture file, instead of discarding them.
223
224       -s  <snaplen>
225
226           Sets the snapshot length to use when writing the data. If the -s
227           flag is used to specify a snapshot length, packets in the input
228           file with more captured data than the specified snapshot length
229           will have only the amount of data specified by the snapshot length
230           written to the output file.
231
232           This may be useful if the program that is to read the output file
233           cannot handle packets larger than a certain size (for example, the
234           versions of snoop in Solaris 2.5.1 and Solaris 2.6 appear to reject
235           Ethernet packets larger than the standard Ethernet MTU, making them
236           incapable of handling gigabit Ethernet captures if jumbo packets
237           were used).
238
239       --seed  <seed>
240
241           When used in conjunction with -E, set the seed for the
242           pseudo-random number generator. This is useful for recreating a
243           particular sequence of errors.
244
245       --skip-radiotap-header
246
247           Skip the radiotap header of each frame when checking for packet
248           duplicates. This is useful when processing a capture created by
249           combining outputs of multiple capture devices on the same channel
250           in the vicinity of each other.
251
252       -S  <strict time adjustment>
253
254           Time adjust selected packets to ensure strict chronological order.
255
256           The <strict time adjustment> value represents relative seconds
257           specified as seconds[.fractional seconds].
258
259           As the capture file is processed each packet’s absolute time is
260           possibly adjusted to be equal to or greater than the previous
261           packet’s absolute timestamp depending on the <strict time
262           adjustment> value.
263
264           If <strict time adjustment> value is 0 or greater (e.g. 0.000001)
265           then only packets with a timestamp less than the previous packet
266           will adjusted. The adjusted timestamp value will be set to be equal
267           to the timestamp value of the previous packet plus the value of the
268           <strict time adjustment> value. A <strict time adjustment> value of
269           0 will adjust the minimum number of timestamp values necessary to
270           ensure that the resulting capture file is in strict chronological
271           order.
272
273           If <strict time adjustment> value is specified as a negative value,
274           then the timestamp values of all packets will be adjusted to be
275           equal to the timestamp value of the previous packet plus the
276           absolute value of the <strict time adjustment> value. A <strict
277           time adjustment> value of -0 will result in all packets having the
278           timestamp value of the first packet.
279
280           This feature is useful when the trace file has an occasional packet
281           with a negative delta time relative to the previous packet.
282
283       -t  <time adjustment>
284
285           Sets the time adjustment to use on selected packets. If the -t flag
286           is used to specify a time adjustment, the specified adjustment will
287           be applied to all selected packets in the capture file. The
288           adjustment is specified as seconds[.fractional seconds]. For
289           example, -t 3600 advances the timestamp on selected packets by one
290           hour while -t -0.5 reduces the timestamp on selected packets by
291           one-half second.
292
293           This feature is useful when synchronizing dumps collected on
294           different machines where the time difference between the two
295           machines is known or can be estimated.
296
297       -T  <encapsulation type>
298
299           Sets the packet encapsulation type of the output capture file. If
300           the -T flag is used to specify an encapsulation type, the
301           encapsulation type of the output capture file will be forced to the
302           specified type. editcap -T provides a list of the available types.
303           The default type is the one appropriate to the encapsulation type
304           of the input capture file.
305
306           Note: this merely forces the encapsulation type of the output file
307           to be the specified type; the packet headers of the packets will
308           not be translated from the encapsulation type of the input capture
309           file to the specified encapsulation type (for example, it will not
310           translate an Ethernet capture to an FDDI capture if an Ethernet
311           capture is read and '-T fddi' is specified). If you need to
312           remove/add headers from/to a packet, you will need
313           od(1)/text2pcap(1).
314
315       -v
316
317           Causes editcap to print verbose messages while it’s working.
318
319           Use of -v with the de-duplication switches of -d, -D or -w will
320           cause all MD5 hashes to be printed whether the packet is skipped or
321           not.
322
323       -V
324
325           Print the version and exit.
326
327       -w  <dup time window>
328
329           Attempts to remove duplicate packets. The current packet’s arrival
330           time is compared with up to 1000000 previous packets. If the
331           packet’s relative arrival time is less than or equal to the <dup
332           time window> of a previous packet and the packet length and MD5
333           hash of the current packet are the same then the packet to skipped.
334           The duplicate comparison test stops when the current packet’s
335           relative arrival time is greater than <dup time window>.
336
337           The <dup time window> is specified as seconds[.fractional seconds].
338
339           The [.fractional seconds] component can be specified to nine (9)
340           decimal places (billionths of a second) but most typical trace
341           files have resolution to six (6) decimal places (millionths of a
342           second).
343
344               Note
345               Specifying large <dup time window> values with large tracefiles
346               can result in very long processing times for editcap.
347
348               Note
349               The -w option assumes that the packets are in chronological
350               order. If the packets are NOT in chronological order then the
351               -w duplication removal option may not identify some duplicates.
352
353       --inject-secrets <secrets type>,<file>
354
355           Inserts the contents of <file> into a Decryption Secrets Block
356           (DSB) within the pcapng output file. This enables decryption
357           without requiring additional configuration in protocol preferences.
358
359           The file format is described by <secrets type> which can be one of:
360
361           tls  TLS Key Log as described at
362           https://developer.mozilla.org/NSS_Key_Log_Format wg   WireGuard Key
363           Log, see
364           https://gitlab.com/wireshark/wireshark/-/wikis/WireGuard#key-log-format
365
366           This option may be specified multiple times. The available options
367           for <secrets type> can be listed with --inject-secrets help.
368
369       --discard-all-secrets
370
371           Discard all decryption secrets from the input file when writing the
372           output file. Does not discard secrets added by --inject-secrets in
373           the same command line.
374
375       --capture-comment <comment>
376
377           Adds the given comment to the output file, if supported by the
378           output file format. New comments will be added after any comments
379           present in the input file unless --discard-capture-comment is also
380           specified.
381
382           This option may be specified multiple times. Note that Wireshark
383           currently only displays the first comment of a capture file.
384
385       --discard-capture-comment
386
387           Discard all capture file comments from the input file when writing
388           the output file. Does not discard comments added by
389           --capture-comment in the same command line.
390

EXAMPLES

392       To see more detailed description of the options use:
393
394           editcap -h
395
396       To shrink the capture file by truncating the packets at 64 bytes and
397       writing it as Sun snoop file use:
398
399           editcap -s 64 -F snoop capture.pcapng shortcapture.snoop
400
401       To delete packet 1000 from the capture file use:
402
403           editcap capture.pcapng sans1000.pcapng 1000
404
405       To limit a capture file to packets from number 200 to 750 (inclusive)
406       use:
407
408           editcap -r capture.pcapng small.pcapng 200-750
409
410       To get all packets from number 1-500 (inclusive) use:
411
412           editcap -r capture.pcapng first500.pcapng 1-500
413
414       or
415
416           editcap capture.pcapng first500.pcapng 501-9999999
417
418       To exclude packets 1, 5, 10 to 20 and 30 to 40 from the new file use:
419
420           editcap capture.pcapng exclude.pcapng 1 5 10-20 30-40
421
422       To select just packets 1, 5, 10 to 20 and 30 to 40 for the new file
423       use:
424
425           editcap -r capture.pcapng select.pcapng 1 5 10-20 30-40
426
427       To remove duplicate packets seen within the prior four frames use:
428
429           editcap -d capture.pcapng dedup.pcapng
430
431       To remove duplicate packets seen within the prior four frames while
432       skipping radiotap headers use:
433
434           editcap -d --skip-radiotap-header capture.pcapng dedup.pcapng
435
436       To remove duplicate packets seen within the prior 100 frames use:
437
438           editcap -D 101 capture.pcapng dedup.pcapng
439
440       To remove duplicate packets seen equal to or less than 1/10th of a
441       second:
442
443           editcap -w 0.1 capture.pcapng dedup.pcapng
444
445       To display the MD5 hash for all of the packets (and NOT generate any
446       real output file):
447
448           editcap -v -D 0 capture.pcapng /dev/null
449
450       or on Windows systems
451
452           editcap -v -D 0 capture.pcapng NUL
453
454       To advance the timestamps of each packet forward by 3.0827 seconds:
455
456           editcap -t 3.0827 capture.pcapng adjusted.pcapng
457
458       To ensure all timestamps are in strict chronological order:
459
460           editcap -S 0 capture.pcapng adjusted.pcapng
461
462       To introduce 5% random errors in a capture file use:
463
464           editcap -E 0.05 capture.pcapng capture_error.pcapng
465
466       To remove vlan tags from all packets within an Ethernet-encapsulated
467       capture file, use:
468
469           editcap -L -C 12:4 capture_vlan.pcapng capture_no_vlan.pcapng
470
471       To chop both the 10 byte and 20 byte regions from the following 75 byte
472       packet in a single pass, use any of the 8 possible methods provided
473       below:
474
475           <--------------------------- 75 ---------------------------->
476
477           +---+-------+-----------+---------------+-------------------+
478           | 5 |   10  |     15    |       20      |         25        |
479           +---+-------+-----------+---------------+-------------------+
480
481           1) editcap -C 5:10 -C -25:-20 capture.pcapng chopped.pcapng
482           2) editcap -C 5:10 -C 50:-20 capture.pcapng chopped.pcapng
483           3) editcap -C -70:10 -C -25:-20 capture.pcapng chopped.pcapng
484           4) editcap -C -70:10 -C 50:-20 capture.pcapng chopped.pcapng
485           5) editcap -C 30:20 -C -60:-10 capture.pcapng chopped.pcapng
486           6) editcap -C 30:20 -C 15:-10 capture.pcapng chopped.pcapng
487           7) editcap -C -45:20 -C -60:-10 capture.pcapng chopped.pcapng
488           8) editcap -C -45:20 -C 15:-10 capture.pcapng chopped.pcapng
489
490       To add comment strings to the first 2 input frames, use:
491
492           editcap -a "1:1st frame" -a 2:Second capture.pcapng capture-comments.pcapng
493

SEE ALSO

495       pcap(3), wireshark(1), tshark(1), mergecap(1), dumpcap(1), capinfos(1),
496       text2pcap(1), reordercap(1), od(1), pcap-filter(7) or tcpdump(8)
497

NOTES

499       This is the manual page for Editcap 3.6.0. Editcap is part of the
500       Wireshark distribution. The latest version of Wireshark can be found at
501       https://www.wireshark.org.
502
503       HTML versions of the Wireshark project man pages are available at
504       https://www.wireshark.org/docs/man-pages.
505

AUTHORS

507       Original Author
508       Richard Sharpe <sharpe[AT]ns.aus.com>
509
510       Contributors
511       Guy Harris <guy[AT]alum.mit.edu>
512       Ulf Lamping <ulf.lamping[AT]web.de>
513
514
515
516                                  2021-11-25                        EDITCAP(1)
Impressum