Add some info about extended value string to section 1.7.1
[obnox/wireshark/wip.git] / doc / dumpcap.pod
1
2 =head1 NAME
3
4 dumpcap - Dump network traffic
5
6 =head1 SYNOPSIS
7
8 B<dumpcap>
9 S<[ B<-a> E<lt>capture autostop conditionE<gt> ] ...>
10 S<[ B<-b> E<lt>capture ring buffer optionE<gt>] ...>
11 S<[ B<-B> E<lt>capture buffer sizeE<gt> ] >
12 S<[ B<-c> E<lt>capture packet countE<gt> ]>
13 S<[ B<-d> ]>
14 S<[ B<-D> ]>
15 S<[ B<-f> E<lt>capture filterE<gt> ]>
16 S<[ B<-h> ]>
17 S<[ B<-i> E<lt>capture interfaceE<gt>|- ]>
18 S<[ B<-I> ]>
19 S<[ B<-L> ]>
20 S<[ B<-n> ]>
21 S<[ B<-M> ]>
22 S<[ B<-p> ]>
23 S<[ B<-q> ]>
24 S<[ B<-s> E<lt>capture snaplenE<gt> ]>
25 S<[ B<-S> ]>
26 S<[ B<-v> ]>
27 S<[ B<-w> E<lt>outfileE<gt> ]>
28 S<[ B<-y> E<lt>capture link typeE<gt> ]>
29
30 =head1 DESCRIPTION
31
32 B<Dumpcap> is a network traffic dump tool.  It lets you capture packet
33 data from a live network and write the packets to a file.  B<Dumpcap>'s
34 native capture file format is B<libpcap> format, which is also the format
35 used by B<Wireshark>, B<tcpdump> and various other tools.
36 When the B<-n> option is specified, the output file is written in the
37 new B<pcapng> format.
38
39 Without any options set it will
40 use the pcap library to capture traffic from the first available network
41 interface and writes the received raw packet data, along with the packets'
42 time stamps into a libpcap file.
43
44 If the B<-w> option is not specified, B<Dumpcap> writes to a newly
45 created libpcap file with a randomly chosen name.
46 If the B<-w> option is specified, B<Dumpcap> writes to the file
47 specified by that option.
48
49 Packet capturing is performed with the pcap library.  The capture filter
50 syntax follows the rules of the pcap library.
51
52 =head1 OPTIONS
53
54 =over 4
55
56 =item -a  E<lt>capture autostop conditionE<gt>
57
58 Specify a criterion that specifies when B<Dumpcap> is to stop writing
59 to a capture file.  The criterion is of the form I<test>B<:>I<value>,
60 where I<test> is one of:
61
62 B<duration>:I<value> Stop writing to a capture file after I<value> seconds have
63 elapsed.
64
65 B<filesize>:I<value> Stop writing to a capture file after it reaches a size of
66 I<value> kilobytes (where a kilobyte is 1024 bytes). If this option is used
67 together with the -b option, dumpcap will stop writing to the current capture
68 file and switch to the next one if filesize is reached.
69
70 B<files>:I<value> Stop writing to capture files after I<value> number of files
71 were written.
72
73 =item -b  E<lt>capture ring buffer optionE<gt>
74
75 Cause B<Dumpcap> to run in "multiple files" mode.  In "multiple files" mode,
76 B<Dumpcap> will write to several capture files. When the first capture file
77 fills up, B<Dumpcap> will switch writing to the next file and so on.
78
79 The created filenames are based on the filename given with the B<-w> option,
80 the number of the file and on the creation date and time,
81 e.g. outfile_00001_20050604120117.pcap, outfile_00002_20050604120523.pcap, ...
82
83 With the I<files> option it's also possible to form a "ring buffer".
84 This will fill up new files until the number of files specified,
85 at which point B<Dumpcap> will discard the data in the first file and start
86 writing to that file and so on. If the I<files> option is not set,
87 new files filled up until one of the capture stop conditions match (or
88 until the disk is full).
89
90 The criterion is of the form I<key>B<:>I<value>,
91 where I<key> is one of:
92
93 B<duration>:I<value> switch to the next file after I<value> seconds have
94 elapsed, even if the current file is not completely filled up.
95
96 B<filesize>:I<value> switch to the next file after it reaches a size of
97 I<value> kilobytes (where a kilobyte is 1024 bytes).
98
99 B<files>:I<value> begin again with the first file after I<value> number of
100 files were written (form a ring buffer).  This value must be less than 100000.
101 Caution should be used when using large numbers of files: some filesystems do
102 not handle many files in a single directory well.  The B<files> criterion
103 requires either B<duration> or B<filesize> to be specified to control when to
104 go to the next file.  It should be noted that each B<-b> parameter takes exactly
105 one criterion; to specify two criterion, each must be preceded by the B<-b>
106 option.
107
108 Example: B<-b filesize:1024 -b files:5> results in a ring buffer of five files
109 of size one megabyte.
110
111 =item -B  E<lt>capture buffer sizeE<gt>
112
113 Set capture buffer size (in MB, default is 1MB).  This is used by the
114 the capture driver to buffer packet data until that data can be written
115 to disk.  If you encounter packet drops while capturing, try to increase
116 this size.  Note that, while B<Dumpcap> attempts to set the buffer size
117 to 1MB by default, and can be told to set it to a larger value, the
118 system or interface on which you're capturing might silently limit the
119 capture buffer size to a lower value or raise it to a higher value.
120
121 This is available on on UNIX systems with libpcap 1.0.0 or later and on
122 Windows.  It is not available on UNIX systems with earlier versions of
123 libpcap.
124
125 =item -c  E<lt>capture packet countE<gt>
126
127 Set the maximum number of packets to read when capturing live
128 data.
129
130 =item -d
131
132 Dump the code generated for the capture filter in a human-readable form,
133 and exit.
134
135 =item -D
136
137 Print a list of the interfaces on which B<Dumpcap> can capture, and
138 exit.  For each network interface, a number and an
139 interface name, possibly followed by a text description of the
140 interface, is printed.  The interface name or the number can be supplied
141 to the B<-i> option to specify an interface on which to capture.
142
143 This can be useful on systems that don't have a command to list them
144 (e.g., Windows systems, or UNIX systems lacking B<ifconfig -a>);
145 the number can be useful on Windows 2000 and later systems, where the
146 interface name is a somewhat complex string.
147
148 Note that "can capture" means that B<Dumpcap> was able to open
149 that device to do a live capture. Depending on your system you may need to
150 run dumpcap from an account with special privileges (for example, as root)
151 to be able to capture network traffic.
152 If "B<dumpcap -D>" is not run from such an account, it will not list
153 any interfaces.
154
155 =item -f  E<lt>capture filterE<gt>
156
157 Set the capture filter expression.
158
159 The entire filter expression must be specified as a single argument (which means
160 that if it contains spaces, it must be quoted).
161
162 =item -h
163
164 Print the version and options and exits.
165
166 =item -i  E<lt>capture interfaceE<gt>|-
167
168 Set the name of the network interface or pipe to use for live packet
169 capture.
170
171 Network interface names should match one of the names listed in
172 "B<dumpcap -D>" (described above); a number, as reported by
173 "B<dumpcap -D>", can also be used.  If you're using UNIX, "B<netstat
174 -i>" or "B<ifconfig -a>" might also work to list interface names,
175 although not all versions of UNIX support the B<-a> option to B<ifconfig>.
176
177 If no interface is specified, B<Dumpcap> searches the list of
178 interfaces, choosing the first non-loopback interface if there are any
179 non-loopback interfaces, and choosing the first loopback interface if
180 there are no non-loopback interfaces. If there are no interfaces at all,
181 B<Dumpcap> reports an error and doesn't start the capture.
182
183 Pipe names should be either the name of a FIFO (named pipe) or ``-'' to
184 read data from the standard input.  Data read from pipes must be in
185 standard libpcap format.
186
187 Note: the Win32 version of B<Dumpcap> doesn't support capturing from
188 pipes or stdin!
189
190 =item -I
191
192 Put the interface in "monitor mode"; this is supported only on IEEE
193 802.11 Wi-Fi interfaces, and supported only on some operating systems.
194
195 Note that in monitor mode the adapter might disassociate from the
196 network with which it's associated, so that you will not be able to use
197 any wireless networks with that adapter.  This could prevent accessing
198 files on a network server, or resolving host names or network addresses,
199 if you are capturing in monitor mode and are not connected to another
200 network with another adapter.
201
202 =item -L
203
204 List the data link types supported by the interface and exit. The reported
205 link types can be used for the B<-y> option.
206
207 =item -M
208
209 When used with B<-D>, B<-L> and B<-S>, print machine-readable output.
210 The machine-readable output is intended to be read by B<Wireshark> and
211 B<TShark>; its format is subject to change from release to release.
212
213 =item -n
214
215 Write the output file in the pcap-ng format instead of the default pcap
216 format.
217
218 =item -p
219
220 I<Don't> put the interface into promiscuous mode.  Note that the
221 interface might be in promiscuous mode for some other reason; hence,
222 B<-p> cannot be used to ensure that the only traffic that is captured is
223 traffic sent to or from the machine on which B<Dumpcap> is running,
224 broadcast traffic, and multicast traffic to addresses received by that
225 machine.
226
227 =item -q
228
229 When capturing packets, don't display the continuous count of packets
230 captured that is normally shown when saving a capture to a file;
231 instead, just display, at the end of the capture, a count of packets
232 captured.  On systems that support the SIGINFO signal, such as various
233 BSDs, you can cause the current count to be displayed by typing your
234 "status" character (typically control-T, although it
235 might be set to "disabled" by default on at least some BSDs, so you'd
236 have to explicitly set it to use it).
237
238 =item -s  E<lt>capture snaplenE<gt>
239
240 Set the default snapshot length to use when capturing live data.
241 No more than I<snaplen> bytes of each network packet will be read into
242 memory, or saved to disk.  A value of 0 specifies a snapshot length of
243 65535, so that the full packet is captured; this is the default.
244
245 =item -S
246
247 Print statistics for each interface once every second.
248
249 =item -v
250
251 Print the version and exit.
252
253 =item -w  E<lt>outfileE<gt>
254
255 Write raw packet data to I<outfile>.
256
257 NOTE: The usage of "-" for stdout is not allowed here!
258
259 =item -y  E<lt>capture link typeE<gt>
260
261 Set the data link type to use while capturing packets.  The values
262 reported by B<-L> are the values that can be used.
263
264 =back
265
266 =head1 CAPTURE FILTER SYNTAX
267
268 See the manual page of pcap-filter(4) or, if that doesn't exist, tcpdump(8),
269 or, if that doesn't exist, L<http://wiki.wireshark.org/CaptureFilters>.
270
271 =head1 SEE ALSO
272
273 wireshark(1), tshark(1), editcap(1), mergecap(1), capinfos(1), pcap-filter(4),
274 tcpdump(8), pcap(3)
275
276 =head1 NOTES
277
278 B<Dumpcap> is part of the B<Wireshark> distribution.  The latest version
279 of B<Wireshark> can be found at L<http://www.wireshark.org>.
280
281 HTML versions of the Wireshark project man pages are available at:
282 L<http://www.wireshark.org/docs/man-pages>.
283
284 =head1 AUTHORS
285
286 B<Dumpcap> is derived from the B<Wireshark> capturing engine code;
287 see the list of
288 authors in the B<Wireshark> man page for a list of authors of that code.