dumpcap - Dump network traffic
-=head1 SYNOPSYS
+=head1 SYNOPSIS
B<dumpcap>
S<[ B<-a> E<lt>capture autostop conditionE<gt> ] ...>
S<[ B<-b> E<lt>capture ring buffer optionE<gt>] ...>
-S<[ B<-B> E<lt>capture buffer size (Win32 only)E<gt> ] >
+S<[ B<-B> 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> ]>
S<[ B<-f> E<lt>capture filterE<gt> ]>
+S<[ B<-g> ]>
S<[ B<-h> ]>
-S<[ B<-i> E<lt>capture interfaceE<gt>|- ]>
+S<[ B<-i> E<lt>capture interfaceE<gt>|rpcap://E<lt>hostE<gt>/E<lt>capture interfaceE<gt>|TCP@E<lt>hostE<gt>:E<lt>portE<gt>|- ]>
+S<[ B<-I> ]>
S<[ B<-L> ]>
+S<[ B<-M> ]>
+S<[ B<-n> ]>
+S<[ B<-N> E<lt>packet limitE<gt> ]>
S<[ B<-p> ]>
+S<[ B<-P> ]>
+S<[ B<-q> ]>
S<[ B<-s> E<lt>capture snaplenE<gt> ]>
+S<[ B<-S> ]>
+S<[ B<-t> ]>
S<[ B<-v> ]>
S<[ B<-w> E<lt>outfileE<gt> ]>
S<[ B<-y> E<lt>capture link typeE<gt> ]>
+S<[ B<--capture-comment> E<lt>commentE<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
-native capture file format is B<libpcap> format, which is also the format
-used by B<Wireshark>, B<tcpdump> and various other tools.
-
-Without any options set it will
-use the pcap 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 libpcap file.
-
-If the B<-w> option is not specified, B<Dumpcap> writes to a newly
-created libpcap file with a randomly chosen name.
+data from a live network and write the packets to a file. B<Dumpcap>'s
+default capture file format is B<pcap-ng> 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/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.
to a capture file. The criterion is of the form I<test>B<:>I<value>,
where I<test> is one of:
-B<duration>:I<value> Stop writing to a capture file after I<value> seconds have elapsed.
+B<duration>:I<value> Stop writing to a capture file after I<value> seconds have
+elapsed.
-B<filesize>:I<value> Stop writing to a capture file after it reaches a size of I<value>
-kilobytes (where a kilobyte is 1024 bytes). 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.
+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<files>:I<value> Stop writing to capture files after I<value> number of files were written.
+B<files>:I<value> Stop writing to capture files after I<value> number of files
+were written.
=item -b 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
+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_20050604120117.pcap, outfile_00001_20050604120523.pcap, ...
+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_20050604120117.pcap, outfile_00002_20050604120523.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
+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 if full).
+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>B<:>I<value>,
where I<key> is one of:
-B<duration>:I<value> switch to the next file after I<value> seconds have
+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.
-B<filesize>:I<value> switch to the next file after it reaches a size of
-I<value> kilobytes (where a kilobyte is 1024 bytes).
-
-B<files>:I<value> begin again with the first file after I<value> number of
-files were written (form a ring buffer).
-
-=item -B E<lt>capture buffer size (Win32 only)E<gt>
-
-Win32 only: set capture buffer size (in MB, default is 1MB). This is used by the
-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.
+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<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> 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.
+
+Example: B<-b filesize:1000 -b files:5> results in a ring buffer of five files
+of size one megabyte each.
+
+=item -B 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.
+=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
Print a list of the interfaces on which B<Dumpcap> can capture, and
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
-(e.g., Windows systems, or UNIX systems lacking B<ifconfig -a>);
-the number can be useful on Windows 2000 and later systems, where the
-interface name is a somewhat complex string.
+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)
+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
+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).
+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
Print the version and options and exits.
-=item -i E<lt>capture interfaceE<gt>|-
+=item -i E<lt>capture interfaceE<gt>|rpcap://E<lt>hostE<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.
+capture.
Network interface names should match one of the names listed in
"B<dumpcap -D>" (described above); a number, as reported by
Pipe names should be either the name of a FIFO (named pipe) or ``-'' to
read data from the standard input. Data read from pipes must be in
-standard libpcap format.
+standard pcap format.
+
+This option can occur multiple times. When capturing from multiple
+interfaces, the capture file will be saved in pcap-ng format.
Note: the Win32 version of B<Dumpcap> doesn't support capturing from
pipes or stdin!
+=item -I
+
+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 -L
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> or B<-S>, 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 pcap-ng. 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
I<Don't> put the interface into promiscuous mode. Note that the
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 pcap-ng. In situations that require
+pcap-ng, 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 E<lt>capture snaplenE<gt>
-Set the default snapshot length to use when capturing live data.
+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.
+memory, or saved to disk. A value of 0 specifies a snapshot length of
+65535, 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
=item -w E<lt>outfileE<gt>
-Write raw packet data to I<outfile>.
-
-NOTE: The usage of "-" for stdout is not allowed here!
+Write raw packet data to I<outfile>. Use "-" for stdout.
=item -y 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.
+
+This option is only available if we output the captured packets to a
+single file in pcap-ng format. Only one capture comment may be set per
+output file.
+
=back
=head1 CAPTURE FILTER SYNTAX
-See the manual page of tcpdump(8).
+See the manual page of pcap-filter(7) or, if that doesn't exist, tcpdump(8),
+or, if that doesn't exist, L<https://wiki.wireshark.org/CaptureFilters>.
=head1 SEE ALSO
-wireshark(1), tshark(1), editcap(1), tcpdump(8), pcap(3)
+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<http://www.wireshark.org>.
+of B<Wireshark> can be found at L<https://www.wireshark.org>.
HTML versions of the Wireshark project man pages are available at:
-L<http://www.wireshark.org/docs/man-pages>.
+L<https://www.wireshark.org/docs/man-pages>.
=head1 AUTHORS
-B<Dumpcap> is derived from the B<Wireshark> capturing engine code;
+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.
git.samba.org / metze / wireshark / wip.git / blobdiff