diff options
author | Ulf Lamping <ulf.lamping@web.de> | 2006-02-09 21:49:02 +0000 |
---|---|---|
committer | Ulf Lamping <ulf.lamping@web.de> | 2006-02-09 21:49:02 +0000 |
commit | 07173c5578137e877cf51c528bcc9191ce5d30fc (patch) | |
tree | 418ab3a78736b422f81c506676da9c3cb70a6165 /doc/dumpcap.pod | |
parent | ba7b92bc020da26f46ea913085d9c5e5adaa7d03 (diff) |
add dumpcap manual page
svn path=/trunk/; revision=17237
Diffstat (limited to 'doc/dumpcap.pod')
-rw-r--r-- | doc/dumpcap.pod | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/doc/dumpcap.pod b/doc/dumpcap.pod new file mode 100644 index 0000000000..3ddfb24351 --- /dev/null +++ b/doc/dumpcap.pod @@ -0,0 +1,215 @@ + +=head1 NAME + +dumpcap - Dump network traffic + +=head1 SYNOPSYS + +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<-c> E<lt>capture packet countE<gt> ]> +S<[ B<-D> ]> +S<[ B<-f> E<lt>capture filterE<gt> ]> +S<[ B<-h> ]> +S<[ B<-i> E<lt>capture interfaceE<gt>|- ]> +S<[ B<-L> ]> +S<[ B<-p> ]> +S<[ B<-s> E<lt>capture snaplenE<gt> ]> +S<[ B<-v> ]> +S<[ B<-w> E<lt>outfileE<gt> ]> +S<[ B<-y> E<lt>capture link 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 +native capture file format is B<libpcap> format, which is also the format +used by B<Ethereal>, 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. +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> +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<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_00001_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 if 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> 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. + +=item -c E<lt>capture packet countE<gt> + +Set the maximum number of packets to read when capturing live +data. + +=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). + +=item -h + +Print the version and options and exits. + +=item -i E<lt>capture interfaceE<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 libpcap format. + +Note: the Win32 version of B<Dumpcap> doesn't support capturing from +pipes or stdin! + +=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 -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. + +=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. + +=item -v + +Print the version and exit. + +=item -w E<lt>outfileE<gt> + +Write raw packet data to I<outfile>. + +NOTE: The usage of "-" for stdout is not allowed here! + +=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. + +=back + +=head1 CAPTURE FILTER SYNTAX + +See the manual page of I<tcpdump(8)>. + +=head1 SEE ALSO + +I<ethereal(1)>, I<tethereal(1)>, I<editcap(1)>, I<tcpdump(8)>, I<pcap(3)> + +=head1 NOTES + +B<Dumpcap> is part of the B<Ethereal> distribution. The latest version +of B<Ethereal> can be found at B<http://www.ethereal.com>. + +HTML versions of the Ethereal project man pages are available at: +http://www.ethereal.com/docs/man-pages + +=head1 AUTHORS + +B<Dumpcap> is derived from the B<Ethereal> capturing engine code; +see the list of +authors in the B<Ethereal> man page for a list of authors of that code. |