591 lines
20 KiB
Plaintext
591 lines
20 KiB
Plaintext
include::../docbook/attributes.adoc[]
|
|
= editcap(1)
|
|
:doctype: manpage
|
|
:stylesheet: ws.css
|
|
:linkcss:
|
|
:copycss: ../docbook/{stylesheet}
|
|
|
|
== NAME
|
|
|
|
editcap - Edit and/or translate the format of capture files
|
|
|
|
== SYNOPSIS
|
|
|
|
[manarg]
|
|
*editcap*
|
|
[ *-a* <frame:comment> ]
|
|
[ *-A* <start time> ]
|
|
[ *-B* <stop time> ]
|
|
[ *-c* <packets per file> ]
|
|
[ *-C* [offset:]<choplen> ]
|
|
[ *-E* <error probability> ]
|
|
[ *-F* <file format> ]
|
|
[ *-i* <seconds per file> ]
|
|
[ *-o* <change offset> ]
|
|
[ *-L* ]
|
|
[ *-r* ]
|
|
[ *-s* <snaplen> ]
|
|
[ *-S* <strict time adjustment> ]
|
|
[ *-t* <time adjustment> ]
|
|
[ *-T* <encapsulation type> ]
|
|
[ *-V* ]
|
|
[ *--inject-secrets* <secrets type>,<file> ]
|
|
[ *--discard-all-secrets* ]
|
|
[ *--capture-comment* <comment> ]
|
|
[ *--discard-capture-comment* ]
|
|
__infile__
|
|
__outfile__
|
|
[ __packet#__[-__packet#__] ... ]
|
|
|
|
[manarg]
|
|
*editcap*
|
|
*-d*
|
|
*-D* <dup window>
|
|
*-w* <dup time window>
|
|
[ *-V* ]
|
|
[ *-I* <bytes to ignore> ]
|
|
[ *--skip-radiotap-header* ]
|
|
__infile__
|
|
__outfile__
|
|
|
|
[manarg]
|
|
*editcap*
|
|
*-h|--help*
|
|
|
|
[manarg]
|
|
*editcap*
|
|
*-v|--version*
|
|
|
|
== DESCRIPTION
|
|
|
|
*Editcap* is a program that reads some or all of the captured packets from the
|
|
__infile__, optionally converts them in various ways and writes the
|
|
resulting packets to the capture __outfile__ (or outfiles).
|
|
|
|
By default, it reads all packets from the __infile__ and writes them to the
|
|
__outfile__ in pcapng file format. Use '-' for __infile__ or __outfile__
|
|
to read from standard input or write to standard output, respectively.
|
|
|
|
The *-A* and *-B* option allow you to limit the time range from which packets
|
|
are read from the __infile__.
|
|
|
|
An optional list of packet numbers can be specified on the command tail;
|
|
individual packet numbers separated by whitespace and/or ranges of packet
|
|
numbers can be specified as __start__-__end__, referring to all packets from
|
|
__start__ to __end__. By default the selected packets with those numbers will
|
|
__not__ be written to the capture file. If the *-r* flag is specified, the
|
|
whole packet selection is reversed; in that case __only__ the selected packets
|
|
will be written to the capture file.
|
|
|
|
*Editcap* can also be used to remove duplicate packets. Several different
|
|
options (*-d*, *-D* and *-w*) are used to control the packet window
|
|
or relative time window to be used for duplicate comparison.
|
|
|
|
*Editcap* can be used to assign comment strings to frame numbers.
|
|
|
|
*Editcap* is able to detect, read and write the same capture files that
|
|
are supported by *Wireshark*.
|
|
The input file doesn't need a specific filename extension; the file
|
|
format and an optional gzip, zstd or lz4 compression will be automatically detected.
|
|
Near the beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or
|
|
https://www.wireshark.org/docs/man-pages/wireshark.html
|
|
is a detailed description of the way *Wireshark* handles this, which is
|
|
the same way *Editcap* handles this.
|
|
|
|
*Editcap* can write the file in several output formats. The *-F*
|
|
flag can be used to specify the format in which to write the capture
|
|
file; *editcap -F* provides a list of the available output formats.
|
|
|
|
== OPTIONS
|
|
|
|
-a <framenum:comment>::
|
|
+
|
|
--
|
|
For the specified frame number, assign the given comment string.
|
|
Can be repeated for multiple frames. Quotes should be used with comment
|
|
strings that include spaces.
|
|
--
|
|
|
|
-A <start time>::
|
|
+
|
|
--
|
|
Reads only the packets whose timestamp is on or after start time.
|
|
The time is given in ISO 8601 format, either
|
|
YYYY-MM-DD HH:MM:SS[.nnnnnnnnn][Z|±hh:mm] or
|
|
YYYY-MM-DDTHH:MM:SS[.nnnnnnnnn][Z|±hh:mm] .
|
|
The fractional seconds are optional, as is the time zone offset from UTC
|
|
(in which case local time is assumed). Unix epoch timestamps
|
|
(floating point format) are also accepted.
|
|
--
|
|
|
|
-B <stop time>::
|
|
+
|
|
--
|
|
Reads only the packets whose timestamp is before stop time.
|
|
The time is given in ISO 8601 format, either
|
|
YYYY-MM-DD HH:MM:SS[.nnnnnnnnn][Z|±hh:mm] or
|
|
YYYY-MM-DDTHH:MM:SS[.nnnnnnnnn][Z|±hh:mm] .
|
|
The fractional seconds are optional, as is the time zone offset from UTC
|
|
(in which case local time is assumed). Unix epoch timestamps
|
|
(floating point format) are also accepted.
|
|
--
|
|
|
|
-c <packets per file>::
|
|
+
|
|
--
|
|
Splits the packet output to different files based on uniform packet counts
|
|
with a maximum of <packets per file> each.
|
|
|
|
Each output file will be created with an infix _nnnnn[_YYYYmmddHHMMSS] inserted
|
|
before the file extension (which may be null) of __outfile__. The infix
|
|
consists of the ordinal number of the output file, starting with 00000,
|
|
followed by the timestamp of its first packet. The timestamp is omitted if
|
|
the input file does not contain timestamp information.
|
|
|
|
After the specified number of packets is written to the output file, the next
|
|
output file is opened. The default is to use a single output file.
|
|
This option conflicts with *-i*.
|
|
--
|
|
|
|
-C [offset:]<choplen>::
|
|
+
|
|
--
|
|
Sets the chop length to use when writing the packet data. Each packet is
|
|
chopped by <choplen> bytes of data. Positive values chop at the packet
|
|
beginning while negative values chop at the packet end.
|
|
|
|
If an optional offset precedes the <choplen>, then the bytes chopped will be
|
|
offset from that value. Positive offsets are from the packet beginning, while
|
|
negative offsets are from the packet end.
|
|
|
|
This is useful for chopping headers for decapsulation of an entire capture,
|
|
removing tunneling headers, or in the rare case that the conversion between two
|
|
file formats leaves some random bytes at the end of each packet. Another use is
|
|
for removing vlan tags.
|
|
|
|
NOTE: This option can be used more than once, effectively allowing you to chop
|
|
bytes from up to two different areas of a packet in a single pass provided that
|
|
you specify at least one chop length as a positive value and at least one as a
|
|
negative value. All positive chop lengths are added together as are all
|
|
negative chop lengths.
|
|
--
|
|
|
|
-d::
|
|
+
|
|
--
|
|
Attempts to remove duplicate packets. The length and MD5 hash of the
|
|
current packet are compared to the previous four (4) packets. If a
|
|
match is found, the current packet is skipped. This option is equivalent
|
|
to using the option *-D 5*.
|
|
--
|
|
|
|
-D <dup window>::
|
|
+
|
|
--
|
|
Attempts to remove duplicate packets. The length and MD5 hash of the
|
|
current packet are compared to the previous <dup window> - 1 packets.
|
|
If a match is found, the current packet is skipped.
|
|
|
|
The use of the option *-D 0* combined with the *-V* option is useful
|
|
in that each packet's Packet number, Len and MD5 Hash will be printed
|
|
to standard error. This verbose output (specifically the MD5 hash strings)
|
|
can be useful in scripts to identify duplicate packets across trace
|
|
files.
|
|
|
|
The <dup window> is specified as an integer value between 0 and 1000000 (inclusive).
|
|
|
|
NOTE: Specifying large <dup window> values with large tracefiles can
|
|
result in very long processing times for *editcap*.
|
|
--
|
|
|
|
-E <error probability>::
|
|
+
|
|
--
|
|
Sets the probability that bytes in the output file are randomly changed.
|
|
*Editcap* uses that probability (between 0.0 and 1.0 inclusive)
|
|
to apply errors to each data byte in the file. For instance, a
|
|
probability of 0.02 means that each byte has a 2% chance of having an error.
|
|
|
|
This option is meant to be used for fuzz-testing protocol dissectors.
|
|
--
|
|
|
|
-F <file format>::
|
|
+
|
|
--
|
|
Sets the file format of the output capture file.
|
|
*Editcap* can write the file in several formats, *editcap -F*
|
|
provides a list of the available output formats. The default
|
|
is the *pcapng* format.
|
|
--
|
|
|
|
-h|--help::
|
|
+
|
|
--
|
|
Prints the version and options and exits.
|
|
--
|
|
|
|
-i <seconds per file>::
|
|
+
|
|
--
|
|
Splits the packet output to different files based on uniform time
|
|
intervals using a maximum interval of <seconds per file> each. Floating
|
|
point values (e.g. 0.5) are allowed.
|
|
|
|
Each output file will be created with an infix _nnnnn[_YYYYmmddHHMMSS] inserted
|
|
before the file extension (which may be null) of __outfile__. The infix
|
|
consists of the ordinal number of the output file, starting with 00000,
|
|
followed by the timestamp of its first packet. The timestamp is omitted if
|
|
the input file does not contain timestamp information.
|
|
|
|
After packets for the specified time interval are written to the output file,
|
|
the next output file is opened. The default is to use a single output file.
|
|
This option conflicts with *-c*.
|
|
--
|
|
|
|
-I <bytes to ignore>::
|
|
+
|
|
--
|
|
Ignore the specified number of bytes at the beginning of the frame during MD5 hash calculation,
|
|
unless the frame is too short, then the full frame is used.
|
|
Useful to remove duplicated packets taken on several routers (different mac addresses for example)
|
|
e.g. -I 26 in case of Ether/IP will ignore ether(14) and IP header(20 - 4(src ip) - 4(dst ip)).
|
|
The default value is 0.
|
|
--
|
|
|
|
-L::
|
|
+
|
|
--
|
|
Adjust the original frame length accordingly when chopping and/or snapping
|
|
(in addition to the captured length, which is always adjusted regardless of
|
|
whether *-L* is specified or not). See also *-C <choplen*> and *-s <snaplen*>.
|
|
--
|
|
|
|
-o <change offset>::
|
|
+
|
|
--
|
|
When used in conjunction with -E, skip some bytes from the beginning of the packet
|
|
from being changed. In this way some headers don't get changed, and the fuzzer is
|
|
more focused on a smaller part of the packet. Keeping a part of the packet fixed
|
|
the same dissector is triggered, that make the fuzzing more precise.
|
|
--
|
|
|
|
-r::
|
|
+
|
|
--
|
|
Reverse the packet selection.
|
|
Causes the packets whose packet numbers are specified on the command
|
|
line to be written to the output capture file, instead of discarding them.
|
|
--
|
|
|
|
-s <snaplen>::
|
|
+
|
|
--
|
|
Sets the snapshot length to use when writing the data.
|
|
If the *-s* flag is used to specify a snapshot length, packets in the
|
|
input file with more captured data than the specified snapshot length
|
|
will have only the amount of data specified by the snapshot length
|
|
written to the output file.
|
|
|
|
This may be useful if the program that is
|
|
to read the output file cannot handle packets larger than a certain size
|
|
(for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6
|
|
appear to reject Ethernet packets larger than the standard Ethernet MTU,
|
|
making them incapable of handling gigabit Ethernet captures if jumbo
|
|
packets were used).
|
|
--
|
|
|
|
--seed <seed>::
|
|
+
|
|
--
|
|
When used in conjunction with -E, set the seed for the pseudo-random number generator.
|
|
This is useful for recreating a particular sequence of errors.
|
|
--
|
|
|
|
--skip-radiotap-header::
|
|
+
|
|
--
|
|
Skip the radiotap header of each frame when checking for packet duplicates. This is useful
|
|
when processing a capture created by combining outputs of multiple capture devices on the same
|
|
channel in the vicinity of each other.
|
|
--
|
|
|
|
-S <strict time adjustment>::
|
|
+
|
|
--
|
|
Time adjust selected packets to ensure strict chronological order.
|
|
|
|
The <strict time adjustment> value represents relative seconds
|
|
specified as [-]__seconds__[__.fractional seconds__].
|
|
|
|
As the capture file is processed each packet's absolute time is
|
|
__possibly__ adjusted to be equal to or greater than the previous
|
|
packet's absolute timestamp depending on the <strict time
|
|
adjustment> value.
|
|
|
|
If <strict time adjustment> value is 0 or greater (e.g. 0.000001)
|
|
then *only* packets with a timestamp less than the previous packet
|
|
will adjusted. The adjusted timestamp value will be set to be
|
|
equal to the timestamp value of the previous packet plus the value
|
|
of the <strict time adjustment> value. A <strict time adjustment>
|
|
value of 0 will adjust the minimum number of timestamp values
|
|
necessary to ensure that the resulting capture file is in
|
|
strict chronological order.
|
|
|
|
If <strict time adjustment> value is specified as a
|
|
negative value, then the timestamp values of *all*
|
|
packets will be adjusted to be equal to the timestamp value
|
|
of the previous packet plus the absolute value of the
|
|
<strict time adjustment> value. A <strict time
|
|
adjustment> value of -0 will result in all packets
|
|
having the timestamp value of the first packet.
|
|
|
|
This feature is useful when the trace file has an occasional
|
|
packet with a negative delta time relative to the previous
|
|
packet.
|
|
--
|
|
|
|
-t <time adjustment>::
|
|
+
|
|
--
|
|
Sets the time adjustment to use on selected packets.
|
|
If the *-t* flag is used to specify a time adjustment, the specified
|
|
adjustment will be applied to all selected packets in the capture file.
|
|
The adjustment is specified as [-]__seconds__[__.fractional seconds__].
|
|
For example, *-t* 3600 advances the timestamp on selected packets by one
|
|
hour while *-t* -0.5 reduces the timestamp on selected packets by
|
|
one-half second.
|
|
|
|
This feature is useful when synchronizing dumps
|
|
collected on different machines where the time difference between the
|
|
two machines is known or can be estimated.
|
|
--
|
|
|
|
-T <encapsulation type>::
|
|
+
|
|
--
|
|
Sets the packet encapsulation type of the output capture file.
|
|
If the *-T* flag is used to specify an encapsulation type, the
|
|
encapsulation type of the output capture file will be forced to the
|
|
specified type.
|
|
*editcap -T* provides a list of the available types. The default
|
|
type is the one appropriate to the encapsulation type of the input
|
|
capture file.
|
|
|
|
Note: this merely
|
|
forces the encapsulation type of the output file to be the specified
|
|
type; the packet headers of the packets will not be translated from the
|
|
encapsulation type of the input capture file to the specified
|
|
encapsulation type (for example, it will not translate an Ethernet
|
|
capture to an FDDI capture if an Ethernet capture is read and '*-T
|
|
fddi*' is specified). If you need to remove/add headers from/to a
|
|
packet, you will need od(1)/xref:text2pcap.html[text2pcap](1).
|
|
--
|
|
|
|
-v|--version::
|
|
+
|
|
--
|
|
Print the version and exit.
|
|
--
|
|
|
|
-V::
|
|
+
|
|
--
|
|
Causes *editcap* to print verbose messages while it's working.
|
|
|
|
Use of *-V* with the de-duplication switches of *-d*, *-D* or *-w*
|
|
will cause all MD5 hashes to be printed whether the packet is skipped
|
|
or not.
|
|
--
|
|
|
|
-w <dup time window>::
|
|
+
|
|
--
|
|
Attempts to remove duplicate packets. The current packet's arrival time
|
|
is compared with up to 1000000 previous packets. If the packet's relative
|
|
arrival time is __less than or equal to__ the <dup time window> of a previous packet
|
|
and the packet length and MD5 hash of the current packet are the same then
|
|
the packet to skipped. The duplicate comparison test stops when
|
|
the current packet's relative arrival time is greater than <dup time window>.
|
|
|
|
The <dup time window> is specified as __seconds__[__.fractional seconds__].
|
|
|
|
The [.fractional seconds] component can be specified to nine (9) decimal
|
|
places (billionths of a second) but most typical trace files have resolution
|
|
to six (6) decimal places (millionths of a second).
|
|
|
|
NOTE: Specifying large <dup time window> values with large tracefiles can
|
|
result in very long processing times for *editcap*.
|
|
|
|
NOTE: The *-w* option assumes that the packets are in chronological order.
|
|
If the packets are NOT in chronological order then the *-w* duplication
|
|
removal option may not identify some duplicates.
|
|
--
|
|
|
|
--inject-secrets <secrets type>,<file>::
|
|
+
|
|
--
|
|
Inserts the contents of <file> into a Decryption Secrets Block (DSB)
|
|
within the pcapng output file. This enables decryption without requiring
|
|
additional configuration in protocol preferences.
|
|
|
|
The file format is described by <secrets type> which can be one of:
|
|
|
|
__tls__ TLS Key Log as described at https://developer.mozilla.org/NSS_Key_Log_Format
|
|
__wg__ WireGuard Key Log, see https://gitlab.com/wireshark/wireshark/-/wikis/WireGuard#key-log-format
|
|
|
|
This option may be specified multiple times. The available options for
|
|
<secrets type> can be listed with *--inject-secrets help*.
|
|
--
|
|
|
|
--discard-all-secrets::
|
|
+
|
|
--
|
|
Discard all decryption secrets from the input file when writing the
|
|
output file. Does not discard secrets added by *--inject-secrets* in
|
|
the same command line.
|
|
--
|
|
|
|
--capture-comment <comment>::
|
|
+
|
|
--
|
|
Adds the given comment to the output file, if supported by the output
|
|
file format. New comments will be added __after__ any comments present
|
|
in the input file unless *--discard-capture-comment* is also specified.
|
|
|
|
This option may be specified multiple times. Note that Wireshark
|
|
currently only displays the first comment of a capture file.
|
|
--
|
|
|
|
--discard-capture-comment::
|
|
+
|
|
--
|
|
Discard all capture file comments from the input file when writing the output
|
|
file. Does not discard comments added by *--capture-comment* in the same
|
|
command line.
|
|
--
|
|
|
|
include::diagnostic-options.adoc[]
|
|
|
|
== EXAMPLES
|
|
|
|
To see more detailed description of the options use:
|
|
|
|
editcap -h
|
|
|
|
To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use:
|
|
|
|
editcap -s 64 -F snoop capture.pcapng shortcapture.snoop
|
|
|
|
To delete packet 1000 from the capture file use:
|
|
|
|
editcap capture.pcapng sans1000.pcapng 1000
|
|
|
|
To limit a capture file to packets from number 200 to 750 (inclusive) use:
|
|
|
|
editcap -r capture.pcapng small.pcapng 200-750
|
|
|
|
To get all packets from number 1-500 (inclusive) use:
|
|
|
|
editcap -r capture.pcapng first500.pcapng 1-500
|
|
|
|
or
|
|
|
|
editcap capture.pcapng first500.pcapng 501-9999999
|
|
|
|
To exclude packets 1, 5, 10 to 20 and 30 to 40 from the new file use:
|
|
|
|
editcap capture.pcapng exclude.pcapng 1 5 10-20 30-40
|
|
|
|
To select just packets 1, 5, 10 to 20 and 30 to 40 for the new file use:
|
|
|
|
editcap -r capture.pcapng select.pcapng 1 5 10-20 30-40
|
|
|
|
To remove duplicate packets seen within the prior four frames use:
|
|
|
|
editcap -d capture.pcapng dedup.pcapng
|
|
|
|
To remove duplicate packets seen within the prior four frames while skipping radiotap headers use:
|
|
|
|
editcap -d --skip-radiotap-header capture.pcapng dedup.pcapng
|
|
|
|
To remove duplicate packets seen within the prior 100 frames use:
|
|
|
|
editcap -D 101 capture.pcapng dedup.pcapng
|
|
|
|
To remove duplicate packets seen __equal to or less than__ 1/10th of a second:
|
|
|
|
editcap -w 0.1 capture.pcapng dedup.pcapng
|
|
|
|
To display the MD5 hash for all of the packets (and NOT generate any
|
|
real output file):
|
|
|
|
editcap -V -D 0 capture.pcapng /dev/null
|
|
|
|
or on Windows systems
|
|
|
|
editcap -V -D 0 capture.pcapng NUL
|
|
|
|
To advance the timestamps of each packet forward by 3.0827 seconds:
|
|
|
|
editcap -t 3.0827 capture.pcapng adjusted.pcapng
|
|
|
|
To ensure all timestamps are in strict chronological order:
|
|
|
|
editcap -S 0 capture.pcapng adjusted.pcapng
|
|
|
|
To introduce 5% random errors in a capture file use:
|
|
|
|
editcap -E 0.05 capture.pcapng capture_error.pcapng
|
|
|
|
To remove vlan tags from all packets within an Ethernet-encapsulated capture
|
|
file, use:
|
|
|
|
editcap -L -C 12:4 capture_vlan.pcapng capture_no_vlan.pcapng
|
|
|
|
To chop both the 10 byte and 20 byte regions from the following 75 byte packet
|
|
in a single pass, use any of the 8 possible methods provided below:
|
|
|
|
<--------------------------- 75 ---------------------------->
|
|
|
|
+---+-------+-----------+---------------+-------------------+
|
|
| 5 | 10 | 15 | 20 | 25 |
|
|
+---+-------+-----------+---------------+-------------------+
|
|
|
|
1) editcap -C 5:10 -C -25:-20 capture.pcapng chopped.pcapng
|
|
2) editcap -C 5:10 -C 50:-20 capture.pcapng chopped.pcapng
|
|
3) editcap -C -70:10 -C -25:-20 capture.pcapng chopped.pcapng
|
|
4) editcap -C -70:10 -C 50:-20 capture.pcapng chopped.pcapng
|
|
5) editcap -C 30:20 -C -60:-10 capture.pcapng chopped.pcapng
|
|
6) editcap -C 30:20 -C 15:-10 capture.pcapng chopped.pcapng
|
|
7) editcap -C -45:20 -C -60:-10 capture.pcapng chopped.pcapng
|
|
8) editcap -C -45:20 -C 15:-10 capture.pcapng chopped.pcapng
|
|
|
|
To add comment strings to the first 2 input frames, use:
|
|
|
|
editcap -a "1:1st frame" -a 2:Second capture.pcapng capture-comments.pcapng
|
|
|
|
== SEE ALSO
|
|
|
|
xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:mergecap.html[mergecap](1), xref:dumpcap.html[dumpcap](1), xref:capinfos.html[capinfos](1),
|
|
xref:text2pcap.html[text2pcap](1), xref:reordercap.html[reordercap](1), od(1), xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8)
|
|
|
|
== NOTES
|
|
|
|
This is the manual page for *Editcap* {wireshark-version}.
|
|
*Editcap* is part of the *Wireshark* distribution.
|
|
The latest version of *Wireshark* can be found at https://www.wireshark.org.
|
|
|
|
HTML versions of the Wireshark project man pages are available at
|
|
https://www.wireshark.org/docs/man-pages.
|
|
|
|
== AUTHORS
|
|
|
|
.Original Author
|
|
[%hardbreaks]
|
|
Richard Sharpe <sharpe[AT]ns.aus.com>
|
|
|
|
.Contributors
|
|
[%hardbreaks]
|
|
Guy Harris <guy[AT]alum.mit.edu>
|
|
Ulf Lamping <ulf.lamping[AT]web.de>
|