diff options
Diffstat (limited to 'doc/dumpcap.adoc')
| -rw-r--r-- | doc/dumpcap.adoc | 188 |
1 files changed, 63 insertions, 125 deletions
diff --git a/doc/dumpcap.adoc b/doc/dumpcap.adoc index a9984f5b2d..49d8838e11 100644 --- a/doc/dumpcap.adoc +++ b/doc/dumpcap.adoc @@ -1,4 +1,4 @@ -include::../docbook/attributes.adoc[] +include::attributes.adoc[] = dumpcap(1) :doctype: manpage :stylesheet: ws.css @@ -22,7 +22,6 @@ dumpcap - Dump network traffic [ *-D*|*--list-interfaces* ] [ *-f* <capture filter> ] [ *-g* ] -[ *-h*|*--help* ] [ *-i*|*--interface* <capture interface>|rpcap://<host>:<port>/<capture interface>|TCP@<host>:<port>|- ] [ *-I*|*--monitor-mode* ] [ *-k* <freq>,[<type>],[<center_freq1>],[<center_freq2>] ] @@ -38,12 +37,21 @@ dumpcap - Dump network traffic [ *-s*|*--snapshot-length* <capture snaplen> ] [ *-S* ] [ *-t* ] -[ *-v*|*--version* ] +[ *--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 @@ -56,10 +64,10 @@ When the *-P* option is specified, the output file is written in the 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. +capture file. If the *-w* option is not specified, *Dumpcap* writes to a newly -created pcap file with a randomly chosen name. +created capture file with a randomly chosen name. If the *-w* option is specified, *Dumpcap* writes to the file specified by that option. @@ -87,7 +95,7 @@ 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. Same as *-c* <capture packet count>. +have been written. Acts the same as *-c* <capture packet count>. -- -b|--ring-buffer <capture ring buffer option>:: @@ -97,9 +105,10 @@ 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_20210714120117.pcap, outfile_00002_20210714120523.pcap, ... +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_20240714120117.pcapng, +outfile_00002_20240714120523.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, @@ -153,8 +162,9 @@ 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 +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 @@ -166,49 +176,27 @@ the default capture buffer size is used instead. -- -c <capture packet count>:: -+ --- Set the maximum number of packets to read when capturing live -data. Same as *-a packets:*<capture packet count>. --- +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* 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 *ifconfig -a* or Linux systems lacking -*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 *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 "*dumpcap -D*" is not run from such an account, it will not list -any interfaces. --- +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>:: + @@ -224,25 +212,15 @@ 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. - -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: *-f "predef:MyPredefinedHostOnlyFilter"* -- -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 and options and exits. --- +Print the version number and options and exit. -i|--interface <capture interface>|rpcap://<host>:<port>/<capture interface>|TCP@<host>:<port>|-:: + @@ -250,11 +228,9 @@ Print the version and options and exits. 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 -"*dumpcap -D*" (described above); a number, as reported by -"*dumpcap -D*", can also be used. If you're using UNIX, "*netstat - -i*", "*ifconfig -a*" or "*ip link*" might also work to list interface names, -although not all versions of UNIX support the *-a* option to *ifconfig*. +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 @@ -264,27 +240,25 @@ there are no non-loopback interfaces. If there are no interfaces at all, 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 +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. +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 the interface or +Use __name__ as the name in the capture file for the interface or pipe specified before it with *-i*. --- -I|--monitor-mode:: + @@ -316,55 +290,25 @@ __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 --- +NOHT:: Used for non-802.11n/non-802.1ac channels -HT20:: -+ --- -20 MHz channel --- +HT20:: 20 MHz channel -HT40-:: -+ --- -40 MHz primary channel and a lower secondary channel --- +HT40-:: 40 MHz primary channel and a lower secondary channel -HT40+:: -+ --- -40 MHz primary channel and a higher secondary channel --- +HT40+:: 40 MHz primary channel and a higher secondary channel -HT80:: -+ --- -80 MHz channel, with __centerfreq1__ as its center frequency --- +HT80:: 80 MHz channel, with __centerfreq1__ as its center frequency VHT80+80:: -+ --- -two 80 MHz channels combined, with __centerfreq1__ and __centerfreq2__ as +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 --- +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:: + @@ -376,10 +320,7 @@ The machine-readable output is intended to be read by *Wireshark* and -- -n:: -+ --- Save files as pcapng. This is the default. --- -N <packet limit>:: + @@ -409,12 +350,9 @@ 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:: + @@ -446,28 +384,27 @@ the default snapshot length is used if provided. -- -S:: -+ --- Print statistics for each interface once every second. --- -t:: -+ --- Use a separate thread per interface. --- --v|--version:: +--temp-dir <directory>:: + -- -Print the version and exit. +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>:: + @@ -497,17 +434,18 @@ 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 |