diff options
author | Gerald Combs <gerald@wireshark.org> | 2021-09-30 15:31:36 -0700 |
---|---|---|
committer | Wireshark GitLab Utility <gerald+gitlab-utility@wireshark.org> | 2021-10-01 16:42:34 +0000 |
commit | 9f1607ab473c578d714320fa735fb0bc4e1d1e96 (patch) | |
tree | 6e8ae12807953db651f60aaf6a29c9589ebca9bc /doc/dumpcap.adoc | |
parent | 04b0e2b80be9654bbe307c66943222fadf1f93c1 (diff) |
Docs: Prep for POD to Asciidoctor conversion.
[skip ci]
Rename each of our .pod files to .adoc. Add pod2adoc.py, which converts
POD markup to Asciidoctor, along with customizations specific to us.
Diffstat (limited to 'doc/dumpcap.adoc')
-rw-r--r-- | doc/dumpcap.adoc | 464 |
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. |