doc/rawshark.pod

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