add dumpcap manual page

svn path=/trunk/; revision=17237

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.