Adding upstream version 4.2.2.upstream/4.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 473 insertions, 0 deletions

diff --git a/doc/dumpcap.adoc b/doc/dumpcap.adoc
new file mode 100644
index 00000000..672599bc
--- /dev/null
+++ b/doc/dumpcap.adoc
@@ -0,0 +1,473 @@
+include::../docbook/attributes.adoc[]
+= dumpcap(1)
+:doctype: manpage
+:stylesheet: ws.css
+:linkcss:
+:copycss: ../docbook/{stylesheet}
+
+== NAME
+
+dumpcap - Dump network traffic
+
+== SYNOPSIS
+
+[manarg]
+*dumpcap*
+[ *-a*|*--autostop* <capture autostop condition> ] ...
+[ *-b*|*--ring-buffer* <capture ring buffer option> ] ...
+[ *-B*|*--buffer-size* <capture buffer size> ]
+[ *-c* <capture packet count> ]
+[ *-C* <byte limit> ]
+[ *-d* ]
+[ *-D*|*--list-interfaces* ]
+[ *-f* <capture filter> ]
+[ *-g* ]
+[ *-i*|*--interface* <capture interface>|rpcap://<host>:<port>/<capture interface>|TCP@<host>:<port>|- ]
+[ *-I*|*--monitor-mode* ]
+[ *-k* <freq>,[<type>],[<center_freq1>],[<center_freq2>] ]
+[ *-L*|*--list-data-link-types* ]
+[ *-M* ]
+[ *-n* ]
+[ *-N* <packet limit> ]
+[ *-p*|*--no-promiscuous-mode* ]
+[ *--ifdescr* <description> ]
+[ *--ifname* <name> ]
+[ *-P* ]
+[ *-q* ]
+[ *-s*|*--snapshot-length* <capture snaplen> ]
+[ *-S* ]
+[ *-t* ]
+[ *--temp-dir* <directory> ]
+[ *-w* <outfile> ]
+[ *-y*|*--linktype* <capture link type> ]
+[ *--capture-comment* <comment> ]
+[ *--list-time-stamp-types* ]
+[ *--time-stamp-type* <type> ]
+[ *--update-interval* <interval> ]
+
+[manarg]
+*dumpcap*
+*-h|--help*
+
+[manarg]
+*dumpcap*
+*-v|--version*
+
+== DESCRIPTION
+
+*Dumpcap* is a network traffic dump tool.  It lets you capture packet
+data from a live network and write the packets to a file.  *Dumpcap*'s
+default capture file format is *pcapng* format.
+When the *-P* option is specified, the output file is written in the
+*pcap* format.
+
+Without any options set it will use the libpcap, Npcap, or WinPcap library to
+capture traffic from the first available network interface and writes
+the received raw packet data, along with the packets' time stamps into a
+capture file.
+
+If the *-w* option is not specified, *Dumpcap* writes to a newly
+created capture file with a randomly chosen name.
+If the *-w* option is specified, *Dumpcap* writes to the file
+specified by that option.
+
+Packet capturing is performed with the pcap library.  The capture filter
+syntax follows the rules of the pcap library.
+
+== OPTIONS
+
+-a|--autostop  <capture autostop condition>::
++
+--
+Specify a criterion that specifies when *Dumpcap* is to stop writing
+to a capture file.  The criterion is of the form __test:value__,
+where __test__ is one of:
+
+*duration*:__value__ Stop writing to a capture file after __value__ seconds have
+elapsed. Floating point values (e.g. 0.5) are allowed.
+
+*files*:__value__ Stop writing to capture files after __value__ number of files
+were written.
+
+*filesize*:__value__ Stop writing to a capture file after it reaches a size of
+__value__ kB. If this option is used together with the -b option, dumpcap will
+stop writing to the current capture file and switch to the next one if filesize
+is reached.  Note that the filesize is limited to a maximum value of 2 GiB.
+
+*packets*:__value__ Stop writing to a capture file after __value__ packets
+have been written. Acts the same as *-c* <capture packet count>.
+--
+
+-b|--ring-buffer  <capture ring buffer option>::
++
+--
+Cause *Dumpcap* to run in "multiple files" mode.  In "multiple files" mode,
+*Dumpcap* will write to several capture files. When the first capture file
+fills up, *Dumpcap* will switch writing to the next file and so on.
+
+The created filenames are based on the filename given with the *-w*
+option, the number of the file and on the creation date and time, e.g.
+outfile_00001_20230714120117.pcapng,
+outfile_00002_20230714120523.pcapng, ...
+
+With the __files__ option it's also possible to form a "ring buffer".
+This will fill up new files until the number of files specified,
+at which point *Dumpcap* will discard the data in the first file and start
+writing to that file and so on. If the __files__ option is not set,
+new files filled up until one of the capture stop conditions match (or
+until the disk is full).
+
+The criterion is of the form __key:value__,
+where __key__ is one of:
+
+*duration*:__value__ switch to the next file after __value__ seconds have
+elapsed, even if the current file is not completely filled up. Floating
+point values (e.g. 0.5) are allowed.
+
+*files*:__value__ begin again with the first file after __value__ number of
+files were written (form a ring buffer).  This value must be less than 100000.
+Caution should be used when using large numbers of files: some filesystems do
+not handle many files in a single directory well.  The *files* criterion
+requires either *duration*, *interval* or *filesize* to be specified to
+control when to go to the next file.  It should be noted that each *-b*
+parameter takes exactly one criterion; to specify two criterion, each must be
+preceded by the *-b* option.
+
+*filesize*:__value__ switch to the next file after it reaches a size of
+__value__ kB.  Note that the filesize is limited to a maximum value of 2 GiB.
+
+*interval*:__value__ switch to the next file when the time is an exact
+multiple of __value__ seconds.  For example, use 3600 to switch to a new file
+every hour on the hour.
+
+*packets*:__value__ switch to the next file after it contains __value__
+packets.
+
+*printname*:__filename__ print the name of the most recently written file
+to __filename__ after the file is closed. __filename__ can be `stdout` or `-`
+for standard output, or `stderr` for standard error.
+
+Example: *-b filesize:1000 -b files:5* results in a ring buffer of five files
+of size one megabyte each.
+--
+
+-B|--buffer-size  <capture buffer size>::
++
+--
+Set capture buffer size (in MiB, default is 2 MiB).  This is used by
+the capture driver to buffer packet data until that data can be written
+to disk.  If you encounter packet drops while capturing, try to increase
+this size.  Note that, while *Dumpcap* attempts to set the buffer size
+to 2 MiB by default, and can be told to set it to a larger value, the
+system or interface on which you're capturing might silently limit the
+capture buffer size to a lower value or raise it to a higher value.
+
+This is available on UNIX-compatible systems, such as Linux, macOS,
+\*BSD, Solaris, and AIX, with libpcap 1.0.0 or later, and on Windows.
+It is not available on UNIX-compatible systems with earlier versions of
+libpcap.
+
+This option can occur multiple times. If used before the first
+occurrence of the *-i* option, it sets the default capture buffer size.
+If used after an *-i* option, it sets the capture buffer size for
+the interface specified by the last *-i* option occurring before
+this option. If the capture buffer size is not set specifically,
+the default capture buffer size is used instead.
+--
+
+-c  <capture packet count>::
+Set the maximum number of packets to read when capturing live
+data. Acts the same as *-a packets:*<capture packet count>.
+
+-C  <byte limit>::
+Limit the amount of memory in bytes used for storing captured packets
+in memory while processing it.
+If used in combination with the *-N* option, both limits will apply.
+Setting this limit will enable the usage of the separate thread per interface.
+
+-d::
+Dump the code generated for the capture filter in a human-readable form,
+and exit.
+
+-D|--list-interfaces::
+Print a list of the interfaces on which *Dumpcap* can capture, and
+exit.  For each network interface, a number and an interface name,
+possibly followed by a text description of the interface, is printed.
+The interface name or the number can be supplied to the *-i* flag to
+specify an interface on which to capture.  The number can be useful on
+Windows systems, where the interfaces have long names that usually
+contain a GUID.
+
+-f  <capture filter>::
++
+--
+Set the capture filter expression.
+
+The entire filter expression must be specified as a single argument (which means
+that if it contains spaces, it must be quoted).
+
+This option can occur multiple times. If used before the first
+occurrence of the *-i* option, it sets the default capture filter expression.
+If used after an *-i* option, it sets the capture filter expression for
+the interface specified by the last *-i* option occurring before
+this option. If the capture filter expression is not set specifically,
+the default capture filter expression is used if provided.
+--
+
+-g::
+This option causes the output file(s) to be created with group-read permission
+(meaning that the output file(s) can be read by other members of the calling
+user's group).
+
+-h|--help::
+Print the version number and options and exit.
+
+-i|--interface  <capture interface>|rpcap://<host>:<port>/<capture interface>|TCP@<host>:<port>|-::
++
+--
+Set the name of the network interface or pipe to use for live packet
+capture.
+
+Network interface names should match one of the names listed in "*tshark
+-D*" (described above); a number, as reported by "*dumpcap -D*", can
+also be used.
+
+If no interface is specified, *Dumpcap* searches the list of
+interfaces, choosing the first non-loopback interface if there are any
+non-loopback interfaces, and choosing the first loopback interface if
+there are no non-loopback interfaces. If there are no interfaces at all,
+*Dumpcap* reports an error and doesn't start the capture.
+
+Pipe names should be either the name of a FIFO (named pipe) or "-" to
+read data from the standard input.  On Windows systems, pipe names must be
+of the form +"\\.\pipe\+*pipename*".  Data read from pipes must be in
+standard pcapng or pcap format. Pcapng data must have the same
+endianness as the capturing host.
+
+"TCP@<host>:<port>" causes *Dumpcap* to attempt to connect to the
+specified port on the specified host and read pcapng or pcap data.
+
+This option can occur multiple times. When capturing from multiple
+interfaces, the capture file will be saved in pcapng format, even if
+*-P* is specified.
+--
+
+--ifdescr> <description>::
+Use __description__ as the description in the capture file for the
+interface or pipe specified before it with *-i*.
+
+--ifname> <name>::
+Use __name__ as the name in the capture file for the interface or
+pipe specified before it with *-i*.
+
+-I|--monitor-mode::
++
+--
+Put the interface in "monitor mode"; this is supported only on IEEE
+802.11 Wi-Fi interfaces, and supported only on some operating systems.
+
+Note that in monitor mode the adapter might disassociate from the
+network with which it's associated, so that you will not be able to use
+any wireless networks with that adapter.  This could prevent accessing
+files on a network server, or resolving host names or network addresses,
+if you are capturing in monitor mode and are not connected to another
+network with another adapter.
+
+This option can occur multiple times. If used before the first
+occurrence of the *-i* option, it enables the monitor mode for all interfaces.
+If used after an *-i* option, it enables the monitor mode for
+the interface specified by the last *-i* option occurring before
+this option.
+--
+
+-k  <freq>,[<type>],[<center_freq1>],[<center_freq2>>::
++
+--
+Set the channel on the interface; this is supported only on IEEE
+802.11 Wi-Fi interfaces, and supported only on some operating systems.
+
+__freq__ is the frequency of the channel.  __type__ is the type of the
+channel, for 802.11n and 802.11ac.  The values for __type__ are
+--
+
+NOHT:: Used for non-802.11n/non-802.1ac channels
+
+HT20:: 20 MHz channel
+
+HT40-:: 40 MHz primary channel and a lower secondary channel
+
+HT40+:: 40 MHz primary channel and a higher secondary channel
+
+HT80:: 80 MHz channel, with __centerfreq1__ as its center frequency
+
+VHT80+80::
+Two 80 MHz channels combined, with __centerfreq1__ and __centerfreq2__ as
+the center frequencies of the two channels
+
+VHT160:: 160 MHz channel, with __centerfreq1__ as its center frequency
+
+-L|--list-data-link-types::
+List the data link types supported by the interface and exit. The reported
+link types can be used for the *-y* option.
+
+-M::
++
+--
+When used with *-D*, *-L*, *-S* or *--list-time-stamp-types* print
+machine-readable output.
+The machine-readable output is intended to be read by *Wireshark* and
+*TShark*; its format is subject to change from release to release.
+--
+
+-n::
+Save files as pcapng. This is the default.
+
+-N  <packet limit>::
++
+--
+Limit the number of packets used for storing captured packets
+in memory while processing it.
+If used in combination with the *-C* option, both limits will apply.
+Setting this limit will enable the usage of the separate thread per interface.
+--
+
+-p|--no-promiscuous-mode::
++
+--
+__Don't__ put the interface into promiscuous mode.  Note that the
+interface might be in promiscuous mode for some other reason; hence,
+*-p* cannot be used to ensure that the only traffic that is captured is
+traffic sent to or from the machine on which *Dumpcap* is running,
+broadcast traffic, and multicast traffic to addresses received by that
+machine.
+
+This option can occur multiple times. If used before the first
+occurrence of the *-i* option, no interface will be put into the
+promiscuous mode.
+If used after an *-i* option, the interface specified by the last *-i*
+option occurring before this option will not be put into the
+promiscuous mode.
+--
+
+-P::
+Save files as pcap instead of the default pcapng. In situations that require
+pcapng, such as capturing from multiple interfaces, this option will be
+overridden.
+
+-q::
++
+--
+When capturing packets, don't display the continuous count of packets
+captured that is normally shown when saving a capture to a file;
+instead, just display, at the end of the capture, a count of packets
+captured.  On systems that support the SIGINFO signal, such as various
+BSDs, you can cause the current count to be displayed by typing your
+"status" character (typically control-T, although it
+might be set to "disabled" by default on at least some BSDs, so you'd
+have to explicitly set it to use it).
+--
+
+-s|--snapshot-length  <capture snaplen>::
++
+--
+Set the default snapshot length to use when capturing live data.
+No more than __snaplen__ bytes of each network packet will be read into
+memory, or saved to disk.  A value of 0 specifies a snapshot length of
+262144, so that the full packet is captured; this is the default.
+
+This option can occur multiple times. If used before the first
+occurrence of the *-i* option, it sets the default snapshot length.
+If used after an *-i* option, it sets the snapshot length for
+the interface specified by the last *-i* option occurring before
+this option. If the snapshot length is not set specifically,
+the default snapshot length is used if provided.
+--
+
+-S::
+Print statistics for each interface once every second.
+
+-t::
+Use a separate thread per interface.
+
+--temp-dir <directory>::
++
+--
+Specifies the directory into which temporary files (including capture
+files) are to be written.  The default behavior on UNIX-compatible systems,
+such as Linux, macOS, \*BSD, Solaris, and AIX, is to use the environment
+variable __$TMPDIR__ if set, and the system default, typically __/tmp__, if it
+is not.  On Windows, the __%TEMP%__ environment variable is used, which
+typically defaults to __%USERPROFILE%\AppData\Local\Temp__.
+--
+
+-v|--version::
+Print the full version information and exit.
+
+-w  <outfile>::
+Write raw packet data to __outfile__. Use "-" for stdout.
+
+-y|--linktype  <capture link type>::
++
+--
+Set the data link type to use while capturing packets.  The values
+reported by *-L* are the values that can be used.
+
+This option can occur multiple times. If used before the first
+occurrence of the *-i* option, it sets the default capture link type.
+If used after an *-i* option, it sets the capture link type for
+the interface specified by the last *-i* option occurring before
+this option. If the capture link type is not set specifically,
+the default capture link type is used if provided.
+--
+
+--capture-comment  <comment>::
++
+--
+Add a capture comment to the output file, if supported by the output
+file format.
+
+This option is only available if we output the captured packets to a
+single file.
+
+This option may be specified multiple times.  Note that Wireshark
+currently only displays the first comment of a capture file.
+--
+
+--list-time-stamp-types::
+List time stamp types supported for the interface. If no time stamp type can be
+set, no time stamp types are listed.
+
+--time-stamp-type  <type>::
+Change the interface's timestamp method.
+
+--update-interval  <interval>::
+Set the length of time in milliseconds between new packet reports during
+a capture. Also sets the granularity of file duration conditions.
+The default value is 100ms.
+
+include::diagnostic-options.adoc[]
+
+== CAPTURE FILTER SYNTAX
+
+See the manual page of xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or, if that doesn't exist, xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8),
+or, if that doesn't exist, https://gitlab.com/wireshark/wireshark/-/wikis/CaptureFilters.
+
+== SEE ALSO
+
+xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:editcap.html[editcap](1), xref:mergecap.html[mergecap](1), xref:capinfos.html[capinfos](1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3),
+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 *Dumpcap* {wireshark-version}.
+*Dumpcap* 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
+
+*Dumpcap* is derived from the *Wireshark* capturing engine code;
+see the list of
+authors in the *Wireshark* man page for a list of authors of that code.