diff options
Diffstat (limited to 'doc/dumpcap.adoc')
| -rw-r--r-- | doc/dumpcap.adoc | 473 |
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. |