From 9f153fbfec0fb9c9ce38e749a7c6f4a5e115d4e9 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Thu, 19 Sep 2024 06:14:33 +0200
Subject: Merging upstream version 4.4.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 doc/man_pages/editcap.adoc | 664 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 664 insertions(+)
 create mode 100644 doc/man_pages/editcap.adoc

(limited to 'doc/man_pages/editcap.adoc')

diff --git a/doc/man_pages/editcap.adoc b/doc/man_pages/editcap.adoc
new file mode 100644
index 00000000..5b4be3fc
--- /dev/null
+++ b/doc/man_pages/editcap.adoc
@@ -0,0 +1,664 @@
+include::../attributes.adoc[]
+= editcap(1)
+:doctype: manpage
+:stylesheet: ws.css
+:linkcss:
+:copycss: {css_dir}/{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*
+*--extract-secrets*
+[ *-V* ]
+__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.
+*Editcap* can also compress the output file. The *--compress* option
+can specify the compression type. If that option is not given, then the desired
+compression method, if any, is deduced from the extension of __outfile__;
+e.g., if the output filename has the .gz extension, then the gzip format is used.
+
+*Editcap* can also be used to extract embedded decryption secrets from file
+formats like *pcapng* that contain them, in lieu of writing a capture file.
+
+== 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:
+
+__opcua__  OPC UA Key Log, see https://ietf-opsawg-wg.github.io/draft-ietf-opsawg-pcap/draft-ietf-opsawg-pcapng.html#name-decryption-secrets-block +
+__ssh__  SSH Key Log, see {wireshark-wiki-url}SSH#key-log-format +
+__tls__  TLS Key Log, see https://tlswg.org/sslkeylogfile/draft-ietf-tls-keylogfile.html +
+__wg__   WireGuard Key Log, see {wireshark-wiki-url}WireGuard#key-log-format
+
+This option may be specified multiple times. The available options for
+<secrets type> can be listed with *--inject-secrets help*.
+--
+
+--extract-secrets::
++
+--
+Extracts each Decryption Secrets Block (DSB) contained within __infile__.
+If there is only one, it is written to __outfile__ instead of a capture file.
+If there is more than one, they are each written to unique output files named
+with an infix _nnnnn before the file extension of __outfile__ in a manner
+similar to the *-c* flag (unless writing to standard output.)
+
+Incompatible with other options except for *-V*.
+
+--
+--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.
+--
+
+--compress <type>::
++
+--
+Compress the output file using the type compression format.
+*--compress* with no argument provides a list of the compression formats supported
+for writing. The type given takes precedence over the extension of __outfile__.
+--
+
+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>
-- 
cgit v1.2.3