doc/man_pages/rawshark.adoc

   1 include::../attributes.adoc[]
   2 = rawshark(1)
   3 :doctype: manpage
   4 :stylesheet: ws.css
   5 :linkcss:
   6 :copycss: {css_dir}/{stylesheet}
   7
   8 == NAME
   9
  10 rawshark - Dump and analyze raw pcap data
  11
  12 == SYNOPSIS
  13
  14 [manarg]
  15 *rawshark*
  16 [ *-d* <encap:linktype>|<proto:protoname> ]
  17 [ *-F* <field to display> ]
  18 [ *-l* ]
  19 [ *-m* <bytes> ]
  20 [ *-o* <preference setting> ] ...
  21 [ *-p* ]
  22 [ *-r* <pipe>|- ]
  23 [ *-R* <read (display) filter> ]
  24 [ *-s* ]
  25 [ *-S* <field format> ]
  26 [ *options* ]
  27
  28 [manarg]
  29 *rawshark*
  30 *-h|--help*
  31
  32 [manarg]
  33 *rawshark*
  34 *-v|--version*
  35
  36 == DESCRIPTION
  37
  38 *Rawshark* reads a stream of packets from a file or pipe, and prints a line
  39 describing its output, followed by a set of matching fields for each packet
  40 on stdout.
  41
  42 == INPUT
  43
  44 Unlike *TShark*, *Rawshark* makes no assumptions about encapsulation or
  45 input. The *-d* and *-r* flags must be specified in order for it to run.
  46 One or more *-F* flags should be specified in order for the output to be
  47 useful. The other flags listed above follow the same conventions as
  48 *Wireshark* and *TShark*.
  49
  50 *Rawshark* expects input records with the following format by default. This
  51 matches the format of the packet header and packet data in a pcap-formatted
  52 file on disk.
  53
  54     struct rawshark_rec_s {
  55         uint32_t ts_sec;      /* Time stamp (seconds) */
  56         uint32_t ts_usec;     /* Time stamp (microseconds) */
  57         uint32_t caplen;      /* Length of the packet buffer */
  58         uint32_t len;         /* "On the wire" length of the packet */
  59         uint8_t data[caplen]; /* Packet data */
  60     };
  61
  62 If *-p* is supplied *rawshark* expects the following format.  This
  63 matches the __struct pcap_pkthdr__ structure and packet data used in
  64 libpcap or Npcap.  This structure's format is platform-dependent; the
  65 size of the __tv_sec__ field in the __struct timeval__ structure could be
  66 32 bits or 64 bits.  For *rawshark* to work, the layout of the
  67 structure in the input must match the layout of the structure in
  68 *rawshark*.  Note that this format will probably be the same as the
  69 previous format if *rawshark* is a 32-bit program, but will not
  70 necessarily be the same if *rawshark* is a 64-bit program.
  71
  72     struct rawshark_rec_s {
  73         struct timeval ts;    /* Time stamp */
  74         uint32_t caplen;      /* Length of the packet buffer */
  75         uint32_t len;         /* "On the wire" length of the packet */
  76         uint8_t data[caplen]; /* Packet data */
  77     };
  78
  79 In either case, the endianness (byte ordering) of each integer must match the
  80 system on which *rawshark* is running.
  81
  82 == OUTPUT
  83
  84 If one or more fields are specified via the *-F* flag, *Rawshark* prints
  85 the number, field type, and display format for each field on the first line
  86 as "packet number" 0. For each record, the packet number, matching fields,
  87 and a "1" or "0" are printed to indicate if the field matched any supplied
  88 display filter. A "-" is used to signal the end of a field description and
  89 at the end of each packet line. For example, the flags *-F ip.src -F
  90  dns.qry.type* might generate the following output:
  91
  92     0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX -
  93     1 1="1" 0="192.168.77.10" 1 -
  94     2 1="1" 0="192.168.77.250" 1 -
  95     3 0="192.168.77.10" 1 -
  96     4 0="74.125.19.104" 1 -
  97
  98 Note that packets 1 and 2 are DNS queries, and 3 and 4 are not. Adding *-R "not dns"* still prints each line, but there's an indication
  99 that packets 1 and 2 didn't pass the filter:
 100
 101     0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX -
 102     1 1="1" 0="192.168.77.10" 0 -
 103     2 1="1" 0="192.168.77.250" 0 -
 104     3 0="192.168.77.10" 1 -
 105     4 0="74.125.19.104" 1 -
 106
 107 Also note that the output may be in any order, and that multiple matching
 108 fields might be displayed.
 109
 110 == OPTIONS
 111
 112 -d  <encapsulation>::
 113 +
 114 --
 115 Specify how the packet data should be dissected. The encapsulation is of the
 116 form __type:value__, where __type__ is one of:
 117
 118 *encap*:__name__ Packet data should be dissected using the
 119 libpcap/Npcap data link type (DLT) __name__, e.g. *encap:EN10MB* for
 120 Ethernet.  Names are converted using pcap_datalink_name_to_val().
 121 A complete list of DLTs can be found at
 122 https://www.tcpdump.org/linktypes.html.
 123
 124 *encap*:__number__ Packet data should be dissected using the
 125 libpcap/Npcap LINKTYPE_ __number__, e.g. *encap:105* for raw IEEE
 126 802.11 or *encap:101* for raw IP.
 127
 128 *proto*:__protocol__ Packet data should be passed to the specified Wireshark
 129 protocol dissector, e.g. *proto:http* for HTTP data.
 130 --
 131
 132 -F  <field to display>::
 133 +
 134 --
 135 Add the matching field to the output. Fields are any valid display filter
 136 field. More than one *-F* flag may be specified, and each field can match
 137 multiple times in a given packet. A single field may be specified per *-F*
 138 flag. If you want to apply a display filter, use the *-R* flag.
 139 --
 140
 141 -h|--help::
 142 Print the version number and options and exit.
 143
 144 -l::
 145 +
 146 --
 147 Flush the standard output after the information for each packet is
 148 printed.  (This is not, strictly speaking, line-buffered if *-V*
 149 was specified; however, it is the same as line-buffered if *-V* wasn't
 150 specified, as only one line is printed for each packet, and, as *-l* is
 151 normally used when piping a live capture to a program or script, so that
 152 output for a packet shows up as soon as the packet is seen and
 153 dissected, it should work just as well as true line-buffering.  We do
 154 this as a workaround for a deficiency in the Microsoft Visual C++ C
 155 library.)
 156
 157 This may be useful when piping the output of *TShark* to another
 158 program, as it means that the program to which the output is piped will
 159 see the dissected data for a packet as soon as *TShark* sees the
 160 packet and generates that output, rather than seeing it only when the
 161 standard output buffer containing that data fills up.
 162 --
 163
 164 -m  <memory limit bytes>::
 165 Limit rawshark's memory usage to the specified number of bytes. POSIX
 166 (non-Windows) only.
 167
 168 -o  <preference>:<value>::
 169 +
 170 --
 171 Set a preference value, overriding the default value and any value read
 172 from a preference file.  The argument to the option is a string of the
 173 form __prefname:value__, where __prefname__ is the name of the
 174 preference (which is the same name that would appear in the preference
 175 file), and __value__ is the value to which it should be set.
 176 --
 177
 178 -p::
 179 +
 180 --
 181 Assume that packet data is preceded by a pcap_pkthdr struct as defined in
 182 pcap.h. On some systems the size of the timestamp data will be different from
 183 the data written to disk. On other systems they are identical and this flag has
 184 no effect.
 185 --
 186
 187 -r  <pipe>|-::
 188 +
 189 --
 190 Read packet data from __input source__. It can be either the name of a FIFO
 191 (named pipe) or ``-'' to read data from the standard input, and must have
 192 the record format specified above.
 193
 194 If you are sending data to rawshark from a parent process on Windows you
 195 should not close rawshark's standard input handle prematurely, otherwise
 196 the C runtime might trigger an exception.
 197 --
 198
 199 -R|--read-filter <read (display) filter>::
 200 +
 201 --
 202 Cause the specified filter (which uses the syntax of read/display filters,
 203 rather than that of capture filters) to be applied before printing the output.
 204 Read filters and display filters are synonymous in *rawshark*.
 205 --
 206
 207 -s::
 208 Allows standard pcap files to be used as input, by skipping over the 24
 209 byte pcap file header.
 210
 211 -S::
 212 +
 213 --
 214 Use the specified format string to print each field. The following formats
 215 are supported:
 216
 217 *%D* Field name or description, e.g. "Type" for dns.qry.type
 218
 219 *%N* Base 10 numeric value of the field.
 220
 221 *%S* String value of the field.
 222
 223 For something similar to Wireshark's standard display ("Type: A (1)") you
 224 could use *%D: %S (%N)*.
 225 --
 226
 227 -v|--version::
 228 Print the full version information and exit.
 229
 230 -Y|--display-filter <read (display) filter>::
 231 +
 232 --
 233 Cause the specified filter (which uses the syntax of read/display filters,
 234 rather than that of capture filters) to be applied before printing the output.
 235 Read filters and display filters are synonymous in *rawshark*.
 236 --
 237
 238 include::dissection-options.adoc[tags=**;!tshark;!decode_as]
 239
 240 include::diagnostic-options.adoc[]
 241
 242 == READ FILTER SYNTAX
 243
 244 For a complete table of protocol and protocol fields that are filterable
 245 in *Rawshark* see the xref:wireshark-filter.html[wireshark-filter](4) manual page.
 246
 247 include::files.adoc[tags=**;!gui]
 248
 249 == ENVIRONMENT VARIABLES
 250
 251 // Should this be moved to an include file?
 252
 253 WIRESHARK_CONFIG_DIR::
 254 +
 255 --
 256 This environment variable overrides the location of personal
 257 configuration files.  On UNIX-compatible systems, such as Linux, macOS,
 258 \*BSD, Solaris, and AIX, it defaults to __$XDG_CONFIG_HOME/wireshark__
 259 (or, if that directory doesn't exist but __$HOME/.wireshark__ does
 260 exist, __$HOME/.wireshark__); this is typically
 261 __$HOME/.config/wireshark__.  On Windows, it defaults to
 262 __%APPDATA%\Wireshark__ (or, if %APPDATA% isn't defined,
 263 __%USERPROFILE%\Application Data\Wireshark__).  Available since
 264 Wireshark 3.0.
 265 --
 266
 267 WIRESHARK_DEBUG_WMEM_OVERRIDE::
 268 +
 269 --
 270 Setting this environment variable forces the wmem framework to use the
 271 specified allocator backend for *all* allocations, regardless of which
 272 backend is normally specified by the code. This is mainly useful to developers
 273 when testing or debugging. See __README.wmem__ in the source distribution for
 274 details.
 275 --
 276
 277 WIRESHARK_RUN_FROM_BUILD_DIRECTORY::
 278 +
 279 --
 280 This environment variable causes the plugins and other data files to be
 281 loaded from the build directory (where the program was compiled) rather
 282 than from the standard locations.  It has no effect when the program in
 283 question is running with root (or setuid) permissions on UNIX-compatible
 284 systems, such as Linux, macOS, \*BSD, Solaris, and AIX.
 285 --
 286
 287 WIRESHARK_DATA_DIR::
 288 +
 289 --
 290 This environment variable causes the various data files to be loaded from
 291 a directory other than the standard locations.  It has no effect when the
 292 program in question is running with root (or setuid) permissions on
 293 UNIX-compatible systems.
 294 --
 295
 296 ERF_RECORDS_TO_CHECK::
 297 +
 298 --
 299 This environment variable controls the number of ERF records checked when
 300 deciding if a file really is in the ERF format.  Setting this environment
 301 variable a number higher than the default (20) would make false positives
 302 less likely.
 303 --
 304
 305 IPFIX_RECORDS_TO_CHECK::
 306 +
 307 --
 308 This environment variable controls the number of IPFIX records checked when
 309 deciding if a file really is in the IPFIX format.  Setting this environment
 310 variable a number higher than the default (20) would make false positives
 311 less likely.
 312 --
 313
 314 WIRESHARK_ABORT_ON_DISSECTOR_BUG::
 315 +
 316 --
 317 If this environment variable is set, *Rawshark* will call abort(3)
 318 when a dissector bug is encountered.  abort(3) will cause the program to
 319 exit abnormally; if you are running *Rawshark* in a debugger, it
 320 should halt in the debugger and allow inspection of the process, and, if
 321 you are not running it in a debugger, it will, on some OSes, assuming
 322 your environment is configured correctly, generate a core dump file.
 323 This can be useful to developers attempting to troubleshoot a problem
 324 with a protocol dissector.
 325 --
 326
 327 WIRESHARK_ABORT_ON_TOO_MANY_ITEMS::
 328 +
 329 --
 330 If this environment variable is set, *Rawshark* will call abort(3)
 331 if a dissector tries to add too many items to a tree (generally this
 332 is an indication of the dissector not breaking out of a loop soon enough).
 333 abort(3) will cause the program to exit abnormally; if you are running
 334 *Rawshark* in a debugger, it should halt in the debugger and allow
 335 inspection of the process, and, if you are not running it in a debugger,
 336 it will, on some OSes, assuming your environment is configured correctly,
 337 generate a core dump file.  This can be useful to developers attempting to
 338 troubleshoot a problem with a protocol dissector.
 339 --
 340
 341 == SEE ALSO
 342
 343 xref:wireshark-filter.html[wireshark-filter](4), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:editcap.html[editcap](1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:dumpcap.html[dumpcap](1),
 344 xref:text2pcap.html[text2pcap](1), xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8)
 345
 346 == NOTES
 347
 348 This is the manual page for *Rawshark* {wireshark-version}.
 349 *Rawshark* is part of the *Wireshark* distribution.
 350 The latest version of *Wireshark* can be found at https://www.wireshark.org.
 351
 352 HTML versions of the Wireshark project man pages are available at
 353 https://www.wireshark.org/docs/man-pages.
 354
 355 == AUTHORS
 356
 357 *Rawshark* uses the same packet dissection code that *Wireshark* does, as
 358 well as using many other modules from *Wireshark*; see the list of authors
 359 in the *Wireshark* man page for a list of authors of that code.
 360