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> ]
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 -h|--help
23
24       editcap -v|--version
25

DESCRIPTION

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

OPTIONS

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

DIAGNOSTIC OPTIONS

395       --log-level <level>
396           Set the active log level. Supported levels in lowest to highest
397           order are "noisy", "debug", "info", "message", "warning",
398           "critical", and "error". Messages at each level and higher will be
399           printed, for example "warning" prints "warning", "critical", and
400           "error" messages and "noisy" prints all messages. Levels are case
401           insensitive.
402
403       --log-fatal <level>
404           Abort the program if any messages are logged at the specified level
405           or higher. For example, "warning" aborts on any "warning",
406           "critical", or "error" messages.
407
408       --log-domains <list>
409           Only print messages for the specified log domains, e.g.
410           "GUI,Epan,sshdump". List of domains must be comma-separated.
411
412       --log-debug <list>
413           Force the specified domains to log at the "debug" level. List of
414           domains must be comma-separated.
415
416       --log-noisy <list>
417           Force the specified domains to log at the "noisy" level. List of
418           domains must be comma-separated.
419
420       --log-file <path>
421           Write log messages and stderr output to the specified file.
422

EXAMPLES

424       To see more detailed description of the options use:
425
426           editcap -h
427
428       To shrink the capture file by truncating the packets at 64 bytes and
429       writing it as Sun snoop file use:
430
431           editcap -s 64 -F snoop capture.pcapng shortcapture.snoop
432
433       To delete packet 1000 from the capture file use:
434
435           editcap capture.pcapng sans1000.pcapng 1000
436
437       To limit a capture file to packets from number 200 to 750 (inclusive)
438       use:
439
440           editcap -r capture.pcapng small.pcapng 200-750
441
442       To get all packets from number 1-500 (inclusive) use:
443
444           editcap -r capture.pcapng first500.pcapng 1-500
445
446       or
447
448           editcap capture.pcapng first500.pcapng 501-9999999
449
450       To exclude packets 1, 5, 10 to 20 and 30 to 40 from the new file use:
451
452           editcap capture.pcapng exclude.pcapng 1 5 10-20 30-40
453
454       To select just packets 1, 5, 10 to 20 and 30 to 40 for the new file
455       use:
456
457           editcap -r capture.pcapng select.pcapng 1 5 10-20 30-40
458
459       To remove duplicate packets seen within the prior four frames use:
460
461           editcap -d capture.pcapng dedup.pcapng
462
463       To remove duplicate packets seen within the prior four frames while
464       skipping radiotap headers use:
465
466           editcap -d --skip-radiotap-header capture.pcapng dedup.pcapng
467
468       To remove duplicate packets seen within the prior 100 frames use:
469
470           editcap -D 101 capture.pcapng dedup.pcapng
471
472       To remove duplicate packets seen equal to or less than 1/10th of a
473       second:
474
475           editcap -w 0.1 capture.pcapng dedup.pcapng
476
477       To display the MD5 hash for all of the packets (and NOT generate any
478       real output file):
479
480           editcap -V -D 0 capture.pcapng /dev/null
481
482       or on Windows systems
483
484           editcap -V -D 0 capture.pcapng NUL
485
486       To advance the timestamps of each packet forward by 3.0827 seconds:
487
488           editcap -t 3.0827 capture.pcapng adjusted.pcapng
489
490       To ensure all timestamps are in strict chronological order:
491
492           editcap -S 0 capture.pcapng adjusted.pcapng
493
494       To introduce 5% random errors in a capture file use:
495
496           editcap -E 0.05 capture.pcapng capture_error.pcapng
497
498       To remove vlan tags from all packets within an Ethernet-encapsulated
499       capture file, use:
500
501           editcap -L -C 12:4 capture_vlan.pcapng capture_no_vlan.pcapng
502
503       To chop both the 10 byte and 20 byte regions from the following 75 byte
504       packet in a single pass, use any of the 8 possible methods provided
505       below:
506
507           <--------------------------- 75 ---------------------------->
508
509           +---+-------+-----------+---------------+-------------------+
510           | 5 |   10  |     15    |       20      |         25        |
511           +---+-------+-----------+---------------+-------------------+
512
513           1) editcap -C 5:10 -C -25:-20 capture.pcapng chopped.pcapng
514           2) editcap -C 5:10 -C 50:-20 capture.pcapng chopped.pcapng
515           3) editcap -C -70:10 -C -25:-20 capture.pcapng chopped.pcapng
516           4) editcap -C -70:10 -C 50:-20 capture.pcapng chopped.pcapng
517           5) editcap -C 30:20 -C -60:-10 capture.pcapng chopped.pcapng
518           6) editcap -C 30:20 -C 15:-10 capture.pcapng chopped.pcapng
519           7) editcap -C -45:20 -C -60:-10 capture.pcapng chopped.pcapng
520           8) editcap -C -45:20 -C 15:-10 capture.pcapng chopped.pcapng
521
522       To add comment strings to the first 2 input frames, use:
523
524           editcap -a "1:1st frame" -a 2:Second capture.pcapng capture-comments.pcapng
525

SEE ALSO

527       pcap(3), wireshark(1), tshark(1), mergecap(1), dumpcap(1), capinfos(1),
528       text2pcap(1), reordercap(1), od(1), pcap-filter(7) or tcpdump(8)
529

NOTES

531       This is the manual page for Editcap 4.0.8. Editcap is part of the
532       Wireshark distribution. The latest version of Wireshark can be found at
533       https://www.wireshark.org.
534
535       HTML versions of the Wireshark project man pages are available at
536       https://www.wireshark.org/docs/man-pages.
537

AUTHORS

539       Original Author
540       Richard Sharpe <sharpe[AT]ns.aus.com>
541
542       Contributors
543       Guy Harris <guy[AT]alum.mit.edu>
544       Ulf Lamping <ulf.lamping[AT]web.de>
545
546
547
548                                  2023-08-31                        EDITCAP(1)
Impressum