From 07173c5578137e877cf51c528bcc9191ce5d30fc Mon Sep 17 00:00:00 2001 From: Ulf Lamping Date: Thu, 9 Feb 2006 21:49:02 +0000 Subject: [PATCH] add dumpcap manual page svn path=/trunk/; revision=17237 --- doc/Makefile.am | 14 +++ doc/Makefile.nmake | 17 +++- doc/dumpcap.pod | 215 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 244 insertions(+), 2 deletions(-) create mode 100644 doc/dumpcap.pod diff --git a/doc/Makefile.am b/doc/Makefile.am index ebe49fe5da..4ac5b3dbe3 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -127,6 +127,18 @@ ethereal-filter.pod: ethereal-filter.pod.template ../tethereal --noindex \ $(srcdir)/text2pcap.pod > ../text2pcap.html +../dumpcap.1: dumpcap.pod ../config.h + $(POD2MAN) \ + --center="The Ethereal Network Analyzer" \ + --release=$(VERSION) \ + $(srcdir)/dumpcap.pod > ../dumpcap.1 + +../dumpcap.html: dumpcap.pod ../config.h + $(POD2HTML) \ + --title="dumpcap - The Ethereal Network Analyzer $(VERSION)" \ + --noindex \ + $(srcdir)/dumpcap.pod > ../dumpcap.html + CLEANFILES = \ ethereal-filter.pod \ ethereal-tmp.pod \ @@ -144,6 +156,8 @@ CLEANFILES = \ ../tethereal.html \ ../text2pcap.1 \ ../text2pcap.html \ + ../dumpcap.1 \ + ../dumpcap.html \ ../idl2eth.1 \ ../idl2eth.html diff --git a/doc/Makefile.nmake b/doc/Makefile.nmake index efdb784143..63b203031c 100644 --- a/doc/Makefile.nmake +++ b/doc/Makefile.nmake @@ -27,10 +27,10 @@ include ../config.nmake doc: ethereal.html tethereal.html ethereal-filter.html capinfos.html \ - editcap.html idl2eth.html mergecap.html text2pcap.html + editcap.html idl2eth.html mergecap.html text2pcap.html dumpcap.html man: ethereal.1 tethereal.1 ethereal-filter.4 capinfos.1 editcap.1 \ - idl2eth.1 mergecap.1 text2pcap.1 + idl2eth.1 mergecap.1 text2pcap.1 dumpcap.1 ethereal-tmp.pod: ethereal.pod ../AUTHORS-SHORT-FORMAT copy /B ethereal.pod + ..\AUTHORS-SHORT-FORMAT ethereal-tmp.pod @@ -149,6 +149,18 @@ text2pcap.html: text2pcap.pod ../config.h --noindex \ text2pcap.pod > text2pcap.html +dumpcap.1: dumpcap.pod ../config.h + $(POD2MAN) \ + --center="The Ethereal Network Analyzer" \ + --release=$(VERSION) \ + dumpcap.pod > dumpcap.1 + +dumpcap.html: dumpcap.pod ../config.h + $(POD2HTML) \ + --title="dumpcap - The Ethereal Network Analyzer $(VERSION)" \ + --noindex \ + dumpcap.pod > dumpcap.html + clean: rm -f ethereal.html ethereal.1 ethereal-tmp.pod rm -f tethereal.html tethereal.1 @@ -158,6 +170,7 @@ clean: rm -f idl2eth.html idl2eth.1 rm -f mergecap.html mergecap.1 rm -f text2pcap.html text2pcap.1 + rm -f dumpcap.html dumpcap.1 rm -f pod2htm* distclean: clean 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 +S<[ B<-a> Ecapture autostop conditionE ] ...> +S<[ B<-b> Ecapture ring buffer optionE] ...> +S<[ B<-B> Ecapture buffer size (Win32 only)E ] > +S<[ B<-c> Ecapture packet countE ]> +S<[ B<-D> ]> +S<[ B<-f> Ecapture filterE ]> +S<[ B<-h> ]> +S<[ B<-i> Ecapture interfaceE|- ]> +S<[ B<-L> ]> +S<[ B<-p> ]> +S<[ B<-s> Ecapture snaplenE ]> +S<[ B<-v> ]> +S<[ B<-w> EoutfileE ]> +S<[ B<-y> Ecapture link typeE ]> + +=head1 DESCRIPTION + +B is a network traffic dump tool. It lets you capture packet +data from a live network and write the packets to a file. B's +native capture file format is B format, which is also the format +used by B, B 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 writes to a newly +created libpcap file with a randomly chosen name. +If the B<-w> option is specified, B 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 Ecapture autostop conditionE + +Specify a criterion that specifies when B is to stop writing +to a capture file. The criterion is of the form IB<:>I, +where I is one of: + +B:I Stop writing to a capture file after I seconds have elapsed. + +B:I Stop writing to a capture file after it reaches a size of I +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:I Stop writing to capture files after I number of files were written. + +=item -b Ecapture ring buffer optionE + +Cause B to run in "multiple files" mode. In "multiple files" mode, +B will write to several capture files. When the first capture file +fills up, B 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 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 will discard the data in the first file and start +writing to that file and so on. If the I 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 IB<:>I, +where I is one of: + +B:I switch to the next file after I seconds have +elapsed, even if the current file is not completely filled up. + +B:I switch to the next file after it reaches a size of +I kilobytes (where a kilobyte is 1024 bytes). + +B:I begin again with the first file after I number of +files were written (form a ring buffer). + +=item -B Ecapture buffer size (Win32 only)E + +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 Ecapture packet countE + +Set the maximum number of packets to read when capturing live +data. + +=item -D + +Print a list of the interfaces on which B 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); +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 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" is not run from such an account, it will not list +any interfaces. + +=item -f Ecapture filterE + +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 Ecapture interfaceE|- + +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" (described above); a number, as reported by +"B", can also be used. If you're using UNIX, "B" or "B" might also work to list interface names, +although not all versions of UNIX support the B<-a> option to B. + +If no interface is specified, B 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 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 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 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 is running, +broadcast traffic, and multicast traffic to addresses received by that +machine. + +=item -s Ecapture snaplenE + +Set the default snapshot length to use when capturing live data. +No more than I bytes of each network packet will be read into +memory, or saved to disk. + +=item -v + +Print the version and exit. + +=item -w EoutfileE + +Write raw packet data to I. + +NOTE: The usage of "-" for stdout is not allowed here! + +=item -y Ecapture link typeE + +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. + +=head1 SEE ALSO + +I, I, I, I, I + +=head1 NOTES + +B is part of the B distribution. The latest version +of B can be found at B. + +HTML versions of the Ethereal project man pages are available at: +http://www.ethereal.com/docs/man-pages + +=head1 AUTHORS + +B is derived from the B capturing engine code; +see the list of +authors in the B man page for a list of authors of that code.