forked from osmocom/wireshark
cac102eee3
Most of our sites are now HTTPS-only. Update URLs accordingly. Update other URLs while we're at it. Remove or comment out dead links. Change-Id: I7c4f323e6585d22760bb90bf28fc0faa6b893a33 Reviewed-on: https://code.wireshark.org/review/7621 Petri-Dish: Gerald Combs <gerald@wireshark.org> Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org> Reviewed-by: Gerald Combs <gerald@wireshark.org>
373 lines
14 KiB
Text
373 lines
14 KiB
Text
|
|
=head1 NAME
|
|
|
|
dumpcap - Dump network traffic
|
|
|
|
=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 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>|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
|
|
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.
|
|
|
|
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 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>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<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.
|
|
|
|
=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
|
|
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_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
|
|
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>B<:>I<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.
|
|
|
|
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
|
|
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
|
|
(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.
|
|
|
|
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.
|
|
|
|
=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>|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.
|
|
|
|
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>" or "B<ifconfig -a>" 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. Data read from pipes must be in
|
|
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
|
|
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 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.
|
|
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
|
|
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
|
|
|
|
Print the version and exit.
|
|
|
|
=item -w E<lt>outfileE<gt>
|
|
|
|
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 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), 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.
|