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