Future tense -> present tense for the encoding argument to
[obnox/wireshark/wip.git] / doc / rawshark.pod
1
2 =head1 NAME
3
4 rawshark - Dump and analyze raw libpcap data
5
6 =head1 SYNOPSIS
7
8 B<rawshark>
9 S<[ B<-d> E<lt>encap:dltE<gt>|E<lt>proto:protonameE<gt> ]>
10 S<[ B<-F> E<lt>field to displayE<gt> ]>
11 S<[ B<-h> ]>
12 S<[ B<-l> ]>
13 S<[ B<-n> ]>
14 S<[ B<-N> E<lt>name resolving flagsE<gt> ]>
15 S<[ B<-o> E<lt>preference settingE<gt> ] ...>
16 S<[ B<-p> ]>
17 S<[ B<-r> E<lt>pipeE<gt>|- ]>
18 S<[ B<-R> E<lt>read (display) filterE<gt> ]>
19 S<[ B<-s> ]>
20 S<[ B<-S> E<lt>field formatE<gt> ]>
21 S<[ B<-t> ad|a|r|d|e ]>
22 S<[ B<-v> ]>
23
24 =head1 DESCRIPTION
25
26 B<Rawshark> reads a stream of packets from a file or pipe, and prints a line
27 describing its output, followed by a set of matching fields for each packet
28 on stdout.
29
30 =head1 INPUT
31
32 Unlike B<TShark>, B<Rawshark> makes no assumptions about encapsulation or
33 input. The B<-d> and B<-r> flags must be specified in order for it to run.
34 One or more B<-F> flags should be specified in order for the output to be
35 useful. The other flags listed above follow the same conventions as
36 B<Wireshark> and B<TShark>.
37
38 B<Rawshark> expects input records with the following format by default. This
39 matches the format of the packet header and packet data in a libpcap-formatted
40 file on disk.
41
42     struct rawshark_rec_s {
43         uint32_t ts_sec;      /* Time stamp (seconds) */
44         uint32_t ts_usec;     /* Time stamp (microseconds) */
45         uint32_t caplen;      /* Length of the packet buffer */
46         uint32_t len;         /* "On the wire" length of the packet */
47         uint8_t data[caplen]; /* Packet data */
48     };
49
50 If B<-p> is supplied B<rawshark> expects the following format. This matches the
51 pcap_pkthdr struct and packet data used in libpcap. Note that the time stamp
52 value will match the previous format on some systems but not others.
53
54     struct rawshark_rec_s {
55         struct timeval ts;    /* Time stamp */
56         uint32_t caplen;      /* Length of the packet buffer */
57         uint32_t len;         /* "On the wire" length of the packet */
58         uint8_t *data;        /* Packet data */
59     };
60
61 In either case, the endianness (byte ordering) of each integer must match the
62 system on which B<rawshark> is running.
63
64 =head1 OUTPUT
65
66 If one or more fields are specified via the B<-F> flag, B<Rawshark> prints
67 the number, field type, and display format for each field on the first line
68 as "packet number" 0. For each record, the packet number, matching fields,
69 and a "1" or "0" are printed to indicate if the field matched any supplied
70 display filter. A "-" is used to signal the end of a field description and
71 at the end of each packet line. For example, the flags B<-F ip.src -F
72 dns.qry.type> might generate the following output:
73
74     0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX -
75     1 1="1" 0="192.168.77.10" 1 -
76     2 1="1" 0="192.168.77.250" 1 -
77     3 0="192.168.77.10" 1 -
78     4 0="74.125.19.104" 1 -
79
80 Note that packets 1 and 2 are DNS queries, and 3 and 4 are not. Adding B<-R "not dns"> still prints each line, but there's an indication
81 that packets 1 and 2 didn't pass the filter:
82
83     0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX -
84     1 1="1" 0="192.168.77.10" 0 -
85     2 1="1" 0="192.168.77.250" 0 -
86     3 0="192.168.77.10" 1 -
87     4 0="74.125.19.104" 1 -
88
89 Also note that the output may be in any order, and that multiple matching
90 fields might be displayed.
91
92 =head1 OPTIONS
93
94 =over 4
95
96 =item -d  E<lt>encapsulationE<gt>
97
98 Specify how the packet data should be dissected. The encapsulation is of the
99 form I<type>B<:>I<value>, where I<type> is one of:
100
101 B<encap>:I<name> Packet data should be dissected using the libpcap data link
102 type (DLT) I<name>, e.g. B<encap:EN10MB> for Ethernet. Names are converted
103 using pcap_datalink_name_to_val().
104
105 B<encap>:I<number> Packet data should be dissected using the libpcap DLT
106 I<number>, e.g. B<encap:105> for raw IEEE 802.11. A complete list of DLTs
107 can be found in pcap-bpf.h in the libpcap sources.
108
109 B<proto>:I<protocol> Packet data should be passed to the specified Wireshark
110 protocol dissector, e.g. B<proto:http> for HTTP data.
111
112 =item -F  E<lt>field to displayE<gt>
113
114 Add the matching field to the output. Fields are any valid display filter
115 field. More than one B<-F> flag may be specified, and each field can match
116 multiple times in a given packet. A single field may be specified per B<-F>
117 flag. If you want to apply a display filter, use the B<-R> flag.
118
119 =item -h
120
121 Print the version and options and exits.
122
123 =item -l
124
125 Flush the standard output after the information for each packet is
126 printed.  (This is not, strictly speaking, line-buffered if B<-V>
127 was specified; however, it is the same as line-buffered if B<-V> wasn't
128 specified, as only one line is printed for each packet, and, as B<-l> is
129 normally used when piping a live capture to a program or script, so that
130 output for a packet shows up as soon as the packet is seen and
131 dissected, it should work just as well as true line-buffering.  We do
132 this as a workaround for a deficiency in the Microsoft Visual C++ C
133 library.)
134
135 This may be useful when piping the output of B<TShark> to another
136 program, as it means that the program to which the output is piped will
137 see the dissected data for a packet as soon as B<TShark> sees the
138 packet and generates that output, rather than seeing it only when the
139 standard output buffer containing that data fills up.
140
141 =item -n
142
143 Disable network object name resolution (such as hostname, TCP and UDP port
144 names), the B<-N> flag might override this one.
145
146 =item -N  E<lt>name resolving flagsE<gt>
147
148 Turn on name resolving only for particular types of addresses and port
149 numbers, with name resolving for other types of addresses and port
150 numbers turned off. This flag overrides B<-n> if both B<-N> and B<-n> are
151 present. If both B<-N> and B<-n> flags are not present, all name resolutions are
152 turned on.
153
154 The argument is a string that may contain the letters:
155
156 B<m> to enable MAC address resolution
157
158 B<n> to enable network address resolution
159
160 B<t> to enable transport-layer port number resolution
161
162 B<C> to enable concurrent (asynchronous) DNS lookups
163
164 =item -o  E<lt>preferenceE<gt>:E<lt>valueE<gt>
165
166 Set a preference value, overriding the default value and any value read
167 from a preference file.  The argument to the option is a string of the
168 form I<prefname>B<:>I<value>, where I<prefname> is the name of the
169 preference (which is the same name that would appear in the preference
170 file), and I<value> is the value to which it should be set.
171
172 =item -p
173
174 Assume that packet data is preceded by a pcap_pkthdr struct as defined in
175 pcap.h. On some systems the size of the timestamp data will be different from
176 the data written to disk. On other systems they are identical and this flag has
177 no effect.
178
179 =item -r  E<lt>pipeE<gt>|-
180
181 Read packet data from I<input source>. It can be either the name of a FIFO
182 (named pipe) or ``-'' to read data from the standard input, and must have
183 the record format specified above.
184
185 =item -R  E<lt>read (display) filterE<gt>
186
187 Cause the specified filter (which uses the syntax of read/display filters,
188 rather than that of capture filters) to be applied before printing the output.
189
190 =item -s
191
192 Allows standard pcap files to be used as input, by skipping over the 24
193 byte pcap file header.
194
195 =item -S
196
197 Use the specified format string to print each field. The following formats
198 are supported:
199
200 =over 4
201
202 B<%D> Field name or description, e.g. "Type" for dns.qry.type
203
204 B<%N> Base 10 numeric value of the field.
205
206 B<%S> String value of the field.
207
208 =back
209
210 For something similar to Wireshark's standard display ("Type: A (1)") you
211 could use B<%D: %S (%N)>.
212
213 =item -t  ad|a|r|d|e
214
215 Set the format of the packet timestamp printed in summary lines, the default
216 is relative. The format can be one of:
217
218 B<ad> absolute with date: The absolute date and time is the actual time and
219 date the packet was captured
220
221 B<a> absolute: The absolute time is the actual time the packet was captured,
222 with no date displayed
223
224 B<r> relative: The relative time is the time elapsed between the first packet
225 and the current packet
226
227 B<d> delta: The delta time is the time since the previous packet was
228 captured
229
230 B<e> epoch: The time in seconds since epoch (Jan 1, 1970 00:00:00)
231
232 =item -v
233
234 Print the version and exit.
235
236 =back
237
238 =head1 READ FILTER SYNTAX
239
240 For a complete table of protocol and protocol fields that are filterable
241 in B<TShark> see the wireshark-filter(4) manual page.
242
243 =head1 FILES
244
245 These files contains various B<Wireshark> configuration values.
246
247 =over 4
248
249 =item Preferences
250
251 The F<preferences> files contain global (system-wide) and personal
252 preference settings. If the system-wide preference file exists, it is
253 read first, overriding the default settings. If the personal preferences
254 file exists, it is read next, overriding any previous values. Note: If
255 the command line option B<-o> is used (possibly more than once), it will
256 in turn override values from the preferences files.
257
258 The preferences settings are in the form I<prefname>B<:>I<value>,
259 one per line,
260 where I<prefname> is the name of the preference
261 and I<value> is the value to
262 which it should be set; white space is allowed between B<:> and
263 I<value>.  A preference setting can be continued on subsequent lines by
264 indenting the continuation lines with white space.  A B<#> character
265 starts a comment that runs to the end of the line:
266
267   # Capture in promiscuous mode?
268   # TRUE or FALSE (case-insensitive).
269   capture.prom_mode: TRUE
270
271 The global preferences file is looked for in the F<wireshark> directory
272 under the F<share> subdirectory of the main installation directory (for
273 example, F</usr/local/share/wireshark/preferences>) on UNIX-compatible
274 systems, and in the main installation directory (for example,
275 F<C:\Program Files\Wireshark\preferences>) on Windows systems.
276
277 The personal preferences file is looked for in
278 F<$HOME/.wireshark/preferences> on
279 UNIX-compatible systems and F<%APPDATA%\Wireshark\preferences> (or, if
280 %APPDATA% isn't defined, F<%USERPROFILE%\Application
281 Data\Wireshark\preferences>) on Windows systems.
282
283 =item Disabled (Enabled) Protocols
284
285 The F<disabled_protos> files contain system-wide and personal lists of
286 protocols that have been disabled, so that their dissectors are never
287 called.  The files contain protocol names, one per line, where the
288 protocol name is the same name that would be used in a display filter
289 for the protocol:
290
291   http
292   tcp     # a comment
293
294 The global F<disabled_protos> file uses the same directory as the global
295 preferences file.
296
297 The personal F<disabled_protos> file uses the same directory as the
298 personal preferences file.
299
300 =item Name Resolution (hosts)
301
302 If the personal F<hosts> file exists, it is
303 used to resolve IPv4 and IPv6 addresses before any other
304 attempts are made to resolve them.  The file has the standard F<hosts>
305 file syntax; each line contains one IP address and name, separated by
306 whitespace. The same directory as for the personal preferences file is
307 used.
308
309 Capture filter name resolution is handled by libpcap on UNIX-compatible
310 systems and WinPCAP on Windows.  As such the Wireshark personal F<hosts> file
311 will not be consulted for capture filter name resolution.
312
313 =item Name Resolution (ethers)
314
315 The F<ethers> files are consulted to correlate 6-byte hardware addresses to
316 names. First the personal F<ethers> file is tried and if an address is not
317 found there the global F<ethers> file is tried next.
318
319 Each line contains one hardware address and name, separated by
320 whitespace.  The digits of the hardware address are separated by colons
321 (:), dashes (-) or periods (.).  The same separator character must be
322 used consistently in an address. The following three lines are valid
323 lines of an F<ethers> file:
324
325   ff:ff:ff:ff:ff:ff          Broadcast
326   c0-00-ff-ff-ff-ff          TR_broadcast
327   00.00.00.00.00.00          Zero_broadcast
328
329 The global F<ethers> file is looked for in the F</etc> directory on
330 UNIX-compatible systems, and in the main installation directory (for
331 example, F<C:\Program Files\Wireshark>) on Windows systems.
332
333 The personal F<ethers> file is looked for in the same directory as the personal
334 preferences file.
335
336 Capture filter name resolution is handled by libpcap on UNIX-compatible
337 systems and WinPCAP on Windows.  As such the Wireshark personal F<ethers> file
338 will not be consulted for capture filter name resolution.
339
340 =item Name Resolution (manuf)
341
342 The F<manuf> file is used to match the 3-byte vendor portion of a 6-byte
343 hardware address with the manufacturer's name; it can also contain well-known
344 MAC addresses and address ranges specified with a netmask.  The format of the
345 file is the same as the F<ethers> files, except that entries of the form:
346
347   00:00:0C      Cisco
348
349 can be provided, with the 3-byte OUI and the name for a vendor, and
350 entries such as:
351
352   00-00-0C-07-AC/40     All-HSRP-routers
353
354 can be specified, with a MAC address and a mask indicating how many bits
355 of the address must match. The above entry, for example, has 40
356 significant bits, or 5 bytes, and would match addresses from
357 00-00-0C-07-AC-00 through 00-00-0C-07-AC-FF. The mask need not be a
358 multiple of 8.
359
360 The F<manuf> file is looked for in the same directory as the global
361 preferences file.
362
363 =item Name Resolution (ipxnets)
364
365 The F<ipxnets> files are used to correlate 4-byte IPX network numbers to
366 names. First the global F<ipxnets> file is tried and if that address is not
367 found there the personal one is tried next.
368
369 The format is the same as the F<ethers>
370 file, except that each address is four bytes instead of six.
371 Additionally, the address can be represented as a single hexadecimal
372 number, as is more common in the IPX world, rather than four hex octets.
373 For example, these four lines are valid lines of an F<ipxnets> file:
374
375   C0.A8.2C.00              HR
376   c0-a8-1c-00              CEO
377   00:00:BE:EF              IT_Server1
378   110f                     FileServer3
379
380 The global F<ipxnets> file is looked for in the F</etc> directory on
381 UNIX-compatible systems, and in the main installation directory (for
382 example, F<C:\Program Files\Wireshark>) on Windows systems.
383
384 The personal F<ipxnets> file is looked for in the same directory as the
385 personal preferences file.
386
387 =back
388
389 =head1 ENVIRONMENT VARIABLES
390
391 =over 4
392
393 =item WIRESHARK_DEBUG_EP_NO_CHUNKS
394
395 Normally per-packet memory is allocated in large "chunks."  This behavior
396 doesn't work well with debugging tools such as Valgrind or ElectricFence.
397 Export this environment variable to force individual allocations.
398 Note: disabling chunks also disables canaries (see below).
399
400 =item WIRESHARK_DEBUG_SE_NO_CHUNKS
401
402 Normally per-file memory is allocated in large "chunks."  This behavior
403 doesn't work well with debugging tools such as Valgrind or ElectricFence.
404 Export this environment variable to force individual allocations.
405 Note: disabling chunks also disables canaries (see below).
406
407 =item WIRESHARK_DEBUG_EP_NO_CANARY
408
409 Normally per-packet memory allocations are separated by "canaries" which
410 allow detection of memory overruns.  This comes at the expense of some extra
411 memory usage.  Exporting this environment variable disables these canaries.
412
413 =item WIRESHARK_DEBUG_SE_USE_CANARY
414
415 Exporting this environment variable causes per-file memory allocations to be
416 protected with "canaries" which allow for detection of memory overruns.
417 This comes at the expense of significant extra memory usage.
418
419 =item WIRESHARK_DEBUG_SCRUB_MEMORY
420
421 If this environment variable is exported, the contents of per-packet and
422 per-file memory is initialized to 0xBADDCAFE when the memory is allocated
423 and is reset to 0xDEADBEEF when the memory is freed.  This functionality is
424 useful mainly to developers looking for bugs in the way memory is handled.
425
426 =item WIRESHARK_RUN_FROM_BUILD_DIRECTORY
427
428 This environment variable causes the plugins and other data files to be loaded
429 from the build directory (where the program was compiled) rather than from the
430 standard locations.  It has no effect when the program in question is running
431 with root (or setuid) permissions on *NIX.
432
433 =item WIRESHARK_DATA_DIR
434
435 This environment variable causes the various data files to be loaded from
436 a directory other than the standard locations.  It has no effect when the
437 program in question is running with root (or setuid) permissions on *NIX.
438
439 =item WIRESHARK_PYTHON_DIR
440
441 This environment variable points to an alternate location for Python.
442 It has no effect when the program in question is running with root (or setuid)
443 permissions on *NIX.
444
445 =item ERF_RECORDS_TO_CHECK
446
447 This environment variable controls the number of ERF records checked when
448 deciding if a file really is in the ERF format.  Setting this environment
449 variable a number higher than the default (20) would make false positives
450 less likely.
451
452 =item IPFIX_RECORDS_TO_CHECK
453
454 This environment variable controls the number of IPFIX records checked when
455 deciding if a file really is in the IPFIX format.  Setting this environment
456 variable a number higher than the default (20) would make false positives
457 less likely.
458
459 =item WIRESHARK_ABORT_ON_DISSECTOR_BUG
460
461 If this environment variable is set, B<Rawshark> will call abort(3)
462 when a dissector bug is encountered.  abort(3) will cause the program to
463 exit abnormally; if you are running B<Rawshark> in a debugger, it
464 should halt in the debugger and allow inspection of the process, and, if
465 you are not running it in a debugger, it will, on some OSes, assuming
466 your environment is configured correctly, generate a core dump file.
467 This can be useful to developers attempting to troubleshoot a problem
468 with a protocol dissector.
469
470 =item WIRESHARK_EP_VERIFY_POINTERS
471
472 This environment variable, if exported, causes certain uses of pointers to be
473 audited to ensure they do not point to memory that is deallocated after each
474 packet has been fully dissected.  This can be useful to developers writing or
475 auditing code.
476
477 =item WIRESHARK_SE_VERIFY_POINTERS
478
479 This environment variable, if exported, causes certain uses of pointers to be
480 audited to ensure they do not point to memory that is deallocated after when
481 a capture file is closed.  This can be useful to developers writing or
482 auditing code.
483
484 =back
485
486 =head1 SEE ALSO
487
488 wireshark-filter(4), wireshark(1), tshark(1), editcap(1), tcpdump(8),
489 pcap(3), dumpcap(1), text2pcap(1)
490
491 =head1 NOTES
492
493 B<Rawshark> is part of the B<Wireshark> distribution. The latest version of
494 B<Wireshark> can be found at L<http://www.wireshark.org>.
495
496 HTML versions of the Wireshark project man pages are available at:
497 L<http://www.wireshark.org/docs/man-pages>.
498
499 =head1 AUTHORS
500
501 B<Rawshark> uses the same packet dissection code that B<Wireshark> does, as
502 well as using many other modules from B<Wireshark>; see the list of authors
503 in the B<Wireshark> man page for a list of authors of that code.
504