1 files changed, 464 insertions, 0 deletions
diff --git a/doc/dumpcap.adoc b/doc/dumpcap.adoc
new file mode 100644
index 0000000000..29ca7a8ff2
--- /dev/null
+++ b/doc/dumpcap.adoc
@@ -0,0 +1,464 @@
+=begin man
+
+=encoding utf8
+
+=end man
+
+=head1 NAME
+
+dumpcap - Dump network traffic
+
+=head1 SYNOPSIS
+
+B<dumpcap>
+S<[ B<-a>|B<--autostop> E<lt>capture autostop conditionE<gt> ] ...>
+S<[ B<-b>|B<--ring-buffer> E<lt>capture ring buffer optionE<gt> ] ...>
+S<[ B<-B>|B<--buffer-size> E<lt>capture buffer sizeE<gt> ]>
+S<[ B<-c> E<lt>capture packet countE<gt> ]>
+S<[ B<-C> E<lt>byte limitE<gt> ]>
+S<[ B<-d> ]>
+S<[ B<-D>|B<--list-interfaces> ]>
+S<[ B<-f> E<lt>capture filterE<gt> ]>
+S<[ B<-g> ]>
+S<[ B<-h>|B<--help> ]>
+S<[ B<-i>|B<--interface> E<lt>capture interfaceE<gt>|rpcap://E<lt>hostE<gt>:E<lt>portE<gt>/E<lt>capture interfaceE<gt>|TCP@E<lt>hostE<gt>:E<lt>portE<gt>|- ]>
+S<[ B<-I>|B<--monitor-mode> ]>
+S<[ B<-k> E<lt>freqE<gt>,[E<lt>typeE<gt>],[E<lt>center_freq1E<gt>],[E<lt>center_freq2E<gt>] ]>
+S<[ B<-L>|B<--list-data-link-types> ]>
+S<[ B<-M> ]>
+S<[ B<-n> ]>
+S<[ B<-N> E<lt>packet limitE<gt> ]>
+S<[ B<-p>|B<--no-promiscuous-mode> ]>
+S<[ B<--ifdescr> E<lt>descriptionE<gt> ]>
+S<[ B<--ifname> E<lt>nameE<gt> ]>
+S<[ B<-P> ]>
+S<[ B<-q> ]>
+S<[ B<-s>|B<--snapshot-length> E<lt>capture snaplenE<gt> ]>
+S<[ B<-S> ]>
+S<[ B<-t> ]>
+S<[ B<-v>|B<--version> ]>
+S<[ B<-w> E<lt>outfileE<gt> ]>
+S<[ B<-y>|B<--linktype> E<lt>capture link typeE<gt> ]>
+S<[ B<--capture-comment> E<lt>commentE<gt> ]>
+S<[ B<--list-time-stamp-types> ]>
+S<[ B<--time-stamp-type> E<lt>typeE<gt> ]>
+
+=head1 DESCRIPTION
+
+B<Dumpcap> is a network traffic dump tool.  It lets you capture packet
+data from a live network and write the packets to a file.  B<Dumpcap>'s
+default capture file format is B<pcapng> format.
+When the B<-P> option is specified, the output file is written in the
+B<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
+pcap file.
+
+If the B<-w> option is not specified, B<Dumpcap> writes to a newly
+created pcap file with a randomly chosen name.
+If the B<-w> option is specified, B<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.
+
+=head1 OPTIONS
+
+=over 4
+
+=item -a|--autostop  E<lt>capture autostop conditionE<gt>
+
+Specify a criterion that specifies when B<Dumpcap> is to stop writing
+to a capture file.  The criterion is of the form I<test:value>,
+where I<test> is one of:
+
+B<duration>:I<value> Stop writing to a capture file after I<value> seconds have
+elapsed. Floating point values (e.g. 0.5) are allowed.
+
+B<files>:I<value> Stop writing to capture files after I<value> number of files
+were written.
+
+B<filesize>:I<value> Stop writing to a capture file after it reaches a size of
+I<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.
+
+B<packets>:I<value> Stop writing to a capture file after I<value> packets
+have been written. Same as B<-c> E<lt>capture packet countE<gt>.
+
+=item -b|--ring-buffer  E<lt>capture ring buffer optionE<gt>
+
+Cause B<Dumpcap> to run in "multiple files" mode.  In "multiple files" mode,
+B<Dumpcap> will write to several capture files. When the first capture file
+fills up, B<Dumpcap> will switch writing to the next file and so on.
+
+The created filenames are based on the filename given with the B<-w> option,
+the number of the file and on the creation date and time,
+e.g. outfile_00001_20210714120117.pcap, outfile_00002_20210714120523.pcap, ...
+
+With the I<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 B<Dumpcap> will discard the data in the first file and start
+writing to that file and so on. If the I<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 I<key:value>,
+where I<key> is one of:
+
+B<duration>:I<value> switch to the next file after I<value> seconds have
+elapsed, even if the current file is not completely filled up. Floating
+point values (e.g. 0.5) are allowed.
+
+B<files>:I<value> begin again with the first file after I<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 B<files> criterion
+requires either B<duration>, B<interval> or B<filesize> to be specified to
+control when to go to the next file.  It should be noted that each B<-b>
+parameter takes exactly one criterion; to specify two criterion, each must be
+preceded by the B<-b> option.
+
+B<filesize>:I<value> switch to the next file after it reaches a size of
+I<value> kB.  Note that the filesize is limited to a maximum value of 2 GiB.
+
+B<interval>:I<value> switch to the next file when the time is an exact
+multiple of I<value> seconds.  For example, use 3600 to switch to a new file
+every hour on the hour.
+
+B<packets>:I<value> switch to the next file after it contains I<value>
+packets.
+
+B<printname>:I<filename> print the name of the most recently written file
+to I<filename> after the file is closed. I<filename> can be C<stdout> or C<->
+for standard output, or C<stderr> for standard error.
+
+Example: B<-b filesize:1000 -b files:5> results in a ring buffer of five files
+of size one megabyte each.
+
+=item -B|--buffer-size  E<lt>capture buffer sizeE<gt>
+
+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 B<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 systems with libpcap 1.0.0 or later and on
+Windows.  It is not available on UNIX systems with earlier versions of
+libpcap.
+
+This option can occur multiple times. If used before the first
+occurrence of the B<-i> option, it sets the default capture buffer size.
+If used after an B<-i> option, it sets the capture buffer size for
+the interface specified by the last B<-i> option occurring before
+this option. If the capture buffer size is not set specifically,
+the default capture buffer size is used instead.
+
+=item -c  E<lt>capture packet countE<gt>
+
+Set the maximum number of packets to read when capturing live
+data. Same as B<-a packets:>E<lt>capture packet countE<gt>.
+
+=item -C  E<lt>byte limitE<gt>
+
+Limit the amount of memory in bytes used for storing captured packets
+in memory while processing it.
+If used in combination with the B<-N> option, both limits will apply.
+Setting this limit will enable the usage of the separate thread per interface.
+
+=item -d
+
+Dump the code generated for the capture filter in a human-readable form,
+and exit.
+
+=item -D|--list-interfaces
+
+Print a list of the interfaces on which B<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 B<-i> option to specify an interface on which to capture.
+
+This can be useful on systems that don't have a command to list them
+(UNIX systems lacking B<ifconfig -a> or Linux systems lacking
+B<ip link show>). The number can be useful on Windows systems, where
+the interface name might be a long name or a GUID.
+
+Note that "can capture" means that B<Dumpcap> was able to open
+that device to do a live capture. Depending on your system you may need to
+run dumpcap from an account with special privileges (for example, as root)
+to be able to capture network traffic.
+If "B<dumpcap -D>" is not run from such an account, it will not list
+any interfaces.
+
+=item -f  E<lt>capture filterE<gt>
+
+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 B<-i> option, it sets the default capture filter expression.
+If used after an B<-i> option, it sets the capture filter expression for
+the interface specified by the last B<-i> option occurring before
+this option. If the capture filter expression is not set specifically,
+the default capture filter expression is used if provided.
+
+Pre-defined capture filter names, as shown in the GUI menu item Capture->Capture Filters,
+can be used by prefixing the argument with "predef:".
+Example: B<-f "predef:MyPredefinedHostOnlyFilter">
+
+=item -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).
+
+=item -h|--help
+
+Print the version and options and exits.
+
+=item -i|--interface  E<lt>capture interfaceE<gt>|rpcap://E<lt>hostE<gt>:E<lt>portE<gt>/E<lt>capture interfaceE<gt>|TCP@E<lt>hostE<gt>:E<lt>portE<gt>|-
+
+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
+"B<dumpcap -D>" (described above); a number, as reported by
+"B<dumpcap -D>", can also be used.  If you're using UNIX, "B<netstat
+-i>", "B<ifconfig -a>" or "B<ip link>" might also work to list interface names,
+although not all versions of UNIX support the B<-a> option to B<ifconfig>.
+
+If no interface is specified, B<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,
+B<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\.\B<pipename>".  Data read from pipes must be in
+standard pcapng or pcap format. Pcapng data must have the same
+endianness as the capturing host.
+
+This option can occur multiple times. When capturing from multiple
+interfaces, the capture file will be saved in pcapng format.
+
+=item --ifdescr> E<lt>descriptionE<gt>
+
+Use I<description> as the description in the capture file for the
+interface or pipe specified before it with B<-i>.
+
+=item --ifname> E<lt>nameE<gt>
+
+Use I<name> as the name in the capture file for the the interface or
+pipe specified before it with B<-i>.
+
+=item -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 B<-i> option, it enables the monitor mode for all interfaces.
+If used after an B<-i> option, it enables the monitor mode for
+the interface specified by the last B<-i> option occurring before
+this option.
+
+=item -k  E<lt>freqE<gt>,[E<lt>typeE<gt>],[E<lt>center_freq1E<gt>],[E<lt>center_freq2>E<gt>
+
+Set the channel on the interface; this is supported only on IEEE
+802.11 Wi-Fi interfaces, and supported only on some operating systems.
+
+I<freq> is the frequency of the channel.  I<type> is the type of the
+channel, for 802.11n and 802.11ac.  The values for I<type> are
+
+=over 8
+
+=item NOHT
+
+Used for non-802.11n/non-802.1ac channels
+
+=item HT20
+
+20 MHz channel
+
+=item HT40-
+
+40 MHz primary channel and a lower secondary channel
+
+=item HT40+
+
+40 MHz primary channel and a higher secondary channel
+
+=item HT80
+
+80 MHz channel, with I<centerfreq1> as its center frequency
+
+=item VHT80+80
+
+two 80 MHz channels combined, with I<centerfreq1> and I<centerfreq2> as
+the center frequencies of the two channels
+
+=item VHT160
+
+160 MHz channel, with I<centerfreq1> as its center frequency
+
+=back
+
+=item -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 B<-y> option.
+
+=item -M
+
+When used with B<-D>, B<-L>, B<-S> or B<--list-time-stamp-types> print
+machine-readable output.
+The machine-readable output is intended to be read by B<Wireshark> and
+B<TShark>; its format is subject to change from release to release.
+
+=item -n
+
+Save files as pcapng. This is the default.
+
+=item -N  E<lt>packet limitE<gt>
+
+Limit the number of packets used for storing captured packets
+in memory while processing it.
+If used in combination with the B<-C> option, both limits will apply.
+Setting this limit will enable the usage of the separate thread per interface.
+
+=item -p|--no-promiscuous-mode
+
+I<Don't> put the interface into promiscuous mode.  Note that the
+interface might be in promiscuous mode for some other reason; hence,
+B<-p> cannot be used to ensure that the only traffic that is captured is
+traffic sent to or from the machine on which B<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 B<-i> option, no interface will be put into the
+promiscuous mode.
+If used after an B<-i> option, the interface specified by the last B<-i>
+option occurring before this option will not be put into the
+promiscuous mode.
+
+=item -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.
+
+=item -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).
+
+=item -s|--snapshot-length  E<lt>capture snaplenE<gt>
+
+Set the default snapshot length to use when capturing live data.
+No more than I<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 B<-i> option, it sets the default snapshot length.
+If used after an B<-i> option, it sets the snapshot length for
+the interface specified by the last B<-i> option occurring before
+this option. If the snapshot length is not set specifically,
+the default snapshot length is used if provided.
+
+=item -S
+
+Print statistics for each interface once every second.
+
+=item -t
+
+Use a separate thread per interface.
+
+=item -v|--version
+
+Print the version and exit.
+
+=item -w  E<lt>outfileE<gt>
+
+Write raw packet data to I<outfile>. Use "-" for stdout.
+
+=item -y|--linktype  E<lt>capture link typeE<gt>
+
+Set the data link type to use while capturing packets.  The values
+reported by B<-L> are the values that can be used.
+
+This option can occur multiple times. If used before the first
+occurrence of the B<-i> option, it sets the default capture link type.
+If used after an B<-i> option, it sets the capture link type for
+the interface specified by the last B<-i> option occurring before
+this option. If the capture link type is not set specifically,
+the default capture link type is used if provided.
+
+=item --capture-comment  E<lt>commentE<gt>
+
+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.
+
+=item --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.
+
+=item --time-stamp-type  E<lt>typeE<gt>
+
+Change the interface's timestamp method.
+
+=back
+
+=head1 CAPTURE FILTER SYNTAX
+
+See the manual page of pcap-filter(7) or, if that doesn't exist, tcpdump(8),
+or, if that doesn't exist, L<https://gitlab.com/wireshark/wireshark/-/wikis/CaptureFilters>.
+
+=head1 SEE ALSO
+
+wireshark(1), tshark(1), editcap(1), mergecap(1), capinfos(1), pcap(3),
+pcap-filter(7) or tcpdump(8)
+
+=head1 NOTES
+
+B<Dumpcap> is part of the B<Wireshark> distribution.  The latest version
+of B<Wireshark> can be found at L<https://www.wireshark.org>.
+
+HTML versions of the Wireshark project man pages are available at:
+L<https://www.wireshark.org/docs/man-pages>.
+
+=head1 AUTHORS
+
+B<Dumpcap> is derived from the B<Wireshark> capturing engine code;
+see the list of
+authors in the B<Wireshark> man page for a list of authors of that code.