diff options
Diffstat (limited to 'doc/editcap.adoc')
| -rw-r--r-- | doc/editcap.adoc | 628 |
1 files changed, 628 insertions, 0 deletions
diff --git a/doc/editcap.adoc b/doc/editcap.adoc new file mode 100644 index 00000000..20fadc1a --- /dev/null +++ b/doc/editcap.adoc @@ -0,0 +1,628 @@ +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* ] +[ *--discard-packet-comments* ] +__infile__ +__outfile__ +[ __packet#__[-__packet#__] ... ] + +[manarg] +*editcap* +*-d* +*-D* <dup window> +*-w* <dup time window> +[ *-V* ] +[ *-I* <bytes to ignore> ] +[ *--skip-radiotap-header* ] +[ *--set-unused* ] +__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 may be given either in ISO 8601 format or in Unix epoch +timestamp format. + +ISO 8601 format is 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 format is in seconds since the Unix epoch and nanoseconds, +with either a period or a comma separating the seconds and nanoseconds. +The nanoseconds are optional. +The Unix epoch is 1970-01-01 00:00:00 UTC, so this format is not local +time. +-- + +-B <stop time>:: ++ +-- +Reads only the packets whose timestamp is before <stop time>. +The time may be given either in ISO 8601 format or in Unix epoch +timestamp format. + +ISO 8601 format is 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 format is in seconds since the Unix epoch and nanoseconds, +with either a period or a comma separating the seconds and nanoseconds. +The nanoseconds are optional. +The Unix epoch is 1970-01-01 00:00:00 UTC, so this format is not local +time. +-- + +-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:: +Print the version number and options and exit. + +-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 full version information 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. +-- + +--set-unused:: ++ +-- +Set the unused bytes (if any) to zero in SLL link type. Useful when when checking for duplicates. +As the unused bytes can be anything. When the packet traverses the device stack +for bonded interfaces on Linux for example. +-- + +--discard-packet-comments:: ++ +-- +Discard all packet comments from the input file when writing the output +file. Does not discard comments added by *-a* 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> |