diff options
Diffstat (limited to 'doc/rawshark.adoc')
| -rw-r--r-- | doc/rawshark.adoc | 551 |
1 files changed, 551 insertions, 0 deletions
diff --git a/doc/rawshark.adoc b/doc/rawshark.adoc new file mode 100644 index 00000000..9a28edac --- /dev/null +++ b/doc/rawshark.adoc @@ -0,0 +1,551 @@ +include::../docbook/attributes.adoc[] += rawshark(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{stylesheet} + +== NAME + +rawshark - Dump and analyze raw pcap data + +== SYNOPSIS + +[manarg] +*rawshark* +[ *-d* <encap:linktype>|<proto:protoname> ] +[ *-F* <field to display> ] +[ *-l* ] +[ *-m* <bytes> ] +[ *-o* <preference setting> ] ... +[ *-p* ] +[ *-r* <pipe>|- ] +[ *-R* <read (display) filter> ] +[ *-s* ] +[ *-S* <field format> ] +[ *options* ] + +[manarg] +*rawshark* +*-h|--help* + +[manarg] +*rawshark* +*-v|--version* + +== DESCRIPTION + +*Rawshark* reads a stream of packets from a file or pipe, and prints a line +describing its output, followed by a set of matching fields for each packet +on stdout. + +== INPUT + +Unlike *TShark*, *Rawshark* makes no assumptions about encapsulation or +input. The *-d* and *-r* flags must be specified in order for it to run. +One or more *-F* flags should be specified in order for the output to be +useful. The other flags listed above follow the same conventions as +*Wireshark* and *TShark*. + +*Rawshark* expects input records with the following format by default. This +matches the format of the packet header and packet data in a pcap-formatted +file on disk. + + struct rawshark_rec_s { + uint32_t ts_sec; /* Time stamp (seconds) */ + uint32_t ts_usec; /* Time stamp (microseconds) */ + uint32_t caplen; /* Length of the packet buffer */ + uint32_t len; /* "On the wire" length of the packet */ + uint8_t data[caplen]; /* Packet data */ + }; + +If *-p* is supplied *rawshark* expects the following format. This +matches the __struct pcap_pkthdr__ structure and packet data used in +libpcap, Npcap, or WinPcap. This structure's format is platform-dependent; the +size of the __tv_sec__ field in the __struct timeval__ structure could be +32 bits or 64 bits. For *rawshark* to work, the layout of the +structure in the input must match the layout of the structure in +*rawshark*. Note that this format will probably be the same as the +previous format if *rawshark* is a 32-bit program, but will not +necessarily be the same if *rawshark* is a 64-bit program. + + struct rawshark_rec_s { + struct timeval ts; /* Time stamp */ + uint32_t caplen; /* Length of the packet buffer */ + uint32_t len; /* "On the wire" length of the packet */ + uint8_t data[caplen]; /* Packet data */ + }; + +In either case, the endianness (byte ordering) of each integer must match the +system on which *rawshark* is running. + +== OUTPUT + +If one or more fields are specified via the *-F* flag, *Rawshark* prints +the number, field type, and display format for each field on the first line +as "packet number" 0. For each record, the packet number, matching fields, +and a "1" or "0" are printed to indicate if the field matched any supplied +display filter. A "-" is used to signal the end of a field description and +at the end of each packet line. For example, the flags *-F ip.src -F + dns.qry.type* might generate the following output: + + 0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX - + 1 1="1" 0="192.168.77.10" 1 - + 2 1="1" 0="192.168.77.250" 1 - + 3 0="192.168.77.10" 1 - + 4 0="74.125.19.104" 1 - + +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 +that packets 1 and 2 didn't pass the filter: + + 0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX - + 1 1="1" 0="192.168.77.10" 0 - + 2 1="1" 0="192.168.77.250" 0 - + 3 0="192.168.77.10" 1 - + 4 0="74.125.19.104" 1 - + +Also note that the output may be in any order, and that multiple matching +fields might be displayed. + +== OPTIONS + +-d <encapsulation>:: ++ +-- +Specify how the packet data should be dissected. The encapsulation is of the +form __type:value__, where __type__ is one of: + +*encap*:__name__ Packet data should be dissected using the +libpcap/Npcap/WinPcap data link type (DLT) __name__, e.g. *encap:EN10MB* for +Ethernet. Names are converted using pcap_datalink_name_to_val(). +A complete list of DLTs can be found at +https://www.tcpdump.org/linktypes.html. + +*encap*:__number__ Packet data should be dissected using the +libpcap/Npcap/WinPcap LINKTYPE_ __number__, e.g. *encap:105* for raw IEEE +802.11 or *encap:101* for raw IP. + +*proto*:__protocol__ Packet data should be passed to the specified Wireshark +protocol dissector, e.g. *proto:http* for HTTP data. +-- + +-F <field to display>:: ++ +-- +Add the matching field to the output. Fields are any valid display filter +field. More than one *-F* flag may be specified, and each field can match +multiple times in a given packet. A single field may be specified per *-F* +flag. If you want to apply a display filter, use the *-R* flag. +-- + +-h|--help:: +Print the version number and options and exit. + +-l:: ++ +-- +Flush the standard output after the information for each packet is +printed. (This is not, strictly speaking, line-buffered if *-V* +was specified; however, it is the same as line-buffered if *-V* wasn't +specified, as only one line is printed for each packet, and, as *-l* is +normally used when piping a live capture to a program or script, so that +output for a packet shows up as soon as the packet is seen and +dissected, it should work just as well as true line-buffering. We do +this as a workaround for a deficiency in the Microsoft Visual C++ C +library.) + +This may be useful when piping the output of *TShark* to another +program, as it means that the program to which the output is piped will +see the dissected data for a packet as soon as *TShark* sees the +packet and generates that output, rather than seeing it only when the +standard output buffer containing that data fills up. +-- + +-m <memory limit bytes>:: +Limit rawshark's memory usage to the specified number of bytes. POSIX +(non-Windows) only. + +-o <preference>:<value>:: ++ +-- +Set a preference value, overriding the default value and any value read +from a preference file. The argument to the option is a string of the +form __prefname:value__, where __prefname__ is the name of the +preference (which is the same name that would appear in the preference +file), and __value__ is the value to which it should be set. +-- + +-p:: ++ +-- +Assume that packet data is preceded by a pcap_pkthdr struct as defined in +pcap.h. On some systems the size of the timestamp data will be different from +the data written to disk. On other systems they are identical and this flag has +no effect. +-- + +-r <pipe>|-:: ++ +-- +Read packet data from __input source__. It can be either the name of a FIFO +(named pipe) or ``-'' to read data from the standard input, and must have +the record format specified above. + +If you are sending data to rawshark from a parent process on Windows you +should not close rawshark's standard input handle prematurely, otherwise +the C runtime might trigger an exception. +-- + +-R <read (display) filter>:: ++ +-- +Cause the specified filter (which uses the syntax of read/display filters, +rather than that of capture filters) to be applied before printing the output. +-- + +-s:: +Allows standard pcap files to be used as input, by skipping over the 24 +byte pcap file header. + +-S:: ++ +-- +Use the specified format string to print each field. The following formats +are supported: + +*%D* Field name or description, e.g. "Type" for dns.qry.type + +*%N* Base 10 numeric value of the field. + +*%S* String value of the field. + +For something similar to Wireshark's standard display ("Type: A (1)") you +could use *%D: %S (%N)*. +-- + +-v|--version:: +Print the full version information and exit. + +include::dissection-options.adoc[tags=!tshark;!decode_as] + +include::diagnostic-options.adoc[] + +== READ FILTER SYNTAX + +For a complete table of protocol and protocol fields that are filterable +in *TShark* see the xref:wireshark-filter.html[wireshark-filter](4) manual page. + +== FILES + +These files contains various *Wireshark* configuration values. + +Preferences:: ++ +-- +The __preferences__ files contain global (system-wide) and personal +preference settings. If the system-wide preference file exists, it is +read first, overriding the default settings. If the personal preferences +file exists, it is read next, overriding any previous values. Note: If +the command line option *-o* is used (possibly more than once), it will +in turn override values from the preferences files. + +The preferences settings are in the form __prefname:value__, +one per line, +where __prefname__ is the name of the preference +and __value__ is the value to +which it should be set; white space is allowed between *:* and +__value__. A preference setting can be continued on subsequent lines by +indenting the continuation lines with white space. A *#* character +starts a comment that runs to the end of the line: + + # Capture in promiscuous mode? + # TRUE or FALSE (case-insensitive). + capture.prom_mode: TRUE + +The global preferences file is looked for in the __wireshark__ directory +under the __share__ subdirectory of the main installation directory. On +macOS, this would typically be +__/Application/Wireshark.app/Contents/Resources/share__; on other +UNIX-compatible systems, such as Linux, \*BSD, Solaris, and AIX, this +would typically be __/usr/share/wireshark/preferences__ for +system-installed packages and __/usr/local/share/wireshark/preferences__ +for locally-installed packages; on Windows, this would typically be +__C:\Program Files\Wireshark\preferences__. + +On UNIX-compatible systems, the personal preferences file is looked for +in __$XDG_CONFIG_HOME/wireshark/preferences__, (or, if +__$XDG_CONFIG_HOME/wireshark__ does not exist while __$HOME/.wireshark__ +does exist, __$HOME/.wireshark/preferences__); this is typically +__$HOME/.config/wireshark/preferences__. On Windows, +the personal preferences file is looked for in +__%APPDATA%\Wireshark\preferences__ (or, if %APPDATA% isn't defined, +__%USERPROFILE%\Application Data\Wireshark\preferences__). +-- + +Disabled (Enabled) Protocols:: ++ +-- +The __disabled_protos__ files contain system-wide and personal lists of +protocols that have been disabled, so that their dissectors are never +called. The files contain protocol names, one per line, where the +protocol name is the same name that would be used in a display filter +for the protocol: + + http + tcp # a comment + +The global __disabled_protos__ file uses the same directory as the global +preferences file. + +The personal __disabled_protos__ file uses the same directory as the +personal preferences file. +-- + +Name Resolution (hosts):: ++ +-- +If the personal __hosts__ file exists, it is +used to resolve IPv4 and IPv6 addresses before any other +attempts are made to resolve them. The file has the standard __hosts__ +file syntax; each line contains one IP address and name, separated by +whitespace. The same directory as for the personal preferences file is +used. + +Capture filter name resolution is handled by libpcap on UNIX-compatible +systems, such as Linux, macOS, \*BSD, Solaris, and AIX, and by Npcap or +WinPcap on Windows. As such the Wireshark personal __hosts__ file will +not be consulted for capture filter name resolution. +-- + +Name Resolution (subnets):: ++ +-- +If an IPv4 address cannot be translated via name resolution (no exact +match is found) then a partial match is attempted via the __subnets__ file. + +Each line of this file consists of an IPv4 address, a subnet mask length +separated only by a / and a name separated by whitespace. While the address +must be a full IPv4 address, any values beyond the mask length are subsequently +ignored. + +An example is: + +# Comments must be prepended by the # sign! +192.168.0.0/24 ws_test_network + +A partially matched name will be printed as "subnet-name.remaining-address". +For example, "192.168.0.1" under the subnet above would be printed as +"ws_test_network.1"; if the mask length above had been 16 rather than 24, the +printed address would be ``ws_test_network.0.1". +-- + +Name Resolution (ethers):: ++ +-- +The __ethers__ files are consulted to correlate 6-byte hardware addresses to +names. First the personal __ethers__ file is tried and if an address is not +found there the global __ethers__ file is tried next. + +Each line contains one hardware address and name, separated by +whitespace. The digits of the hardware address are separated by colons +(:), dashes (-) or periods (.). The same separator character must be +used consistently in an address. The following three lines are valid +lines of an __ethers__ file: + + ff:ff:ff:ff:ff:ff Broadcast + c0-00-ff-ff-ff-ff TR_broadcast + 00.00.00.00.00.00 Zero_broadcast + +The global __ethers__ file is looked for in the __/etc__ directory on +UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX, +and in the main installation directory (for example, __C:\Program +Files\Wireshark__) on Windows systems. + +The personal __ethers__ file is looked for in the same directory as the personal +preferences file. + +Capture filter name resolution is handled by libpcap on UNIX-compatible +systems and Npcap or WinPcap on Windows. As such the Wireshark personal +__ethers__ file will not be consulted for capture filter name resolution. +-- + +Name Resolution (manuf):: ++ +-- +The __manuf__ file is used to match the 3-byte vendor portion of a 6-byte +hardware address with the manufacturer's name; it can also contain well-known +MAC addresses and address ranges specified with a netmask. The format of the +file is the same as the __ethers__ files, except that entries of the form: + + 00:00:0C Cisco + +can be provided, with the 3-byte OUI and the name for a vendor, and +entries such as: + + 00-00-0C-07-AC/40 All-HSRP-routers + +can be specified, with a MAC address and a mask indicating how many bits +of the address must match. The above entry, for example, has 40 +significant bits, or 5 bytes, and would match addresses from +00-00-0C-07-AC-00 through 00-00-0C-07-AC-FF. The mask need not be a +multiple of 8. + +The __manuf__ file is looked for in the same directory as the global +preferences file. +-- + +Name Resolution (services):: ++ +-- +The __services__ file is used to translate port numbers into names. + +The file has the standard __services__ file syntax; each line contains one +(service) name and one transport identifier separated by white space. The +transport identifier includes one port number and one transport protocol name +(typically tcp, udp, or sctp) separated by a /. + +An example is: + + mydns 5045/udp # My own Domain Name Server + mydns 5045/tcp # My own Domain Name Server +-- + +Name Resolution (ipxnets):: ++ +-- +The __ipxnets__ files are used to correlate 4-byte IPX network numbers to +names. First the global __ipxnets__ file is tried and if that address is not +found there the personal one is tried next. + +The format is the same as the __ethers__ +file, except that each address is four bytes instead of six. +Additionally, the address can be represented as a single hexadecimal +number, as is more common in the IPX world, rather than four hex octets. +For example, these four lines are valid lines of an __ipxnets__ file: + + C0.A8.2C.00 HR + c0-a8-1c-00 CEO + 00:00:BE:EF IT_Server1 + 110f FileServer3 + +The global __ipxnets__ file is looked for in the __/etc__ directory on +UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX, +and in the main installation directory (for example, __C:\Program +Files\Wireshark__) on Windows systems. + +The personal __ipxnets__ file is looked for in the same directory as the +personal preferences file. +-- + +== ENVIRONMENT VARIABLES + +// Should this be moved to an include file? + +WIRESHARK_CONFIG_DIR:: ++ +-- +This environment variable overrides the location of personal +configuration files. On UNIX-compatible systems, such as Linux, macOS, +\*BSD, Solaris, and AIX, it defaults to __$XDG_CONFIG_HOME/wireshark__ +(or, if that directory doesn't exist but __$HOME/.wireshark__ does +exist, __$HOME/.wireshark__); this is typically +__$HOME/.config/wireshark__. On Windows, it defaults to +__%APPDATA%\Wireshark__ (or, if %APPDATA% isn't defined, +__%USERPROFILE%\Application Data\Wireshark__). Available since +Wireshark 3.0. +-- + +WIRESHARK_DEBUG_WMEM_OVERRIDE:: ++ +-- +Setting this environment variable forces the wmem framework to use the +specified allocator backend for *all* allocations, regardless of which +backend is normally specified by the code. This is mainly useful to developers +when testing or debugging. See __README.wmem__ in the source distribution for +details. +-- + +WIRESHARK_RUN_FROM_BUILD_DIRECTORY:: ++ +-- +This environment variable causes the plugins and other data files to be +loaded from the build directory (where the program was compiled) rather +than from the standard locations. It has no effect when the program in +question is running with root (or setuid) permissions on UNIX-compatible +systems, such as Linux, macOS, \*BSD, Solaris, and AIX. +-- + +WIRESHARK_DATA_DIR:: ++ +-- +This environment variable causes the various data files to be loaded from +a directory other than the standard locations. It has no effect when the +program in question is running with root (or setuid) permissions on +UNIX-compatible systems. +-- + +ERF_RECORDS_TO_CHECK:: ++ +-- +This environment variable controls the number of ERF records checked when +deciding if a file really is in the ERF format. Setting this environment +variable a number higher than the default (20) would make false positives +less likely. +-- + +IPFIX_RECORDS_TO_CHECK:: ++ +-- +This environment variable controls the number of IPFIX records checked when +deciding if a file really is in the IPFIX format. Setting this environment +variable a number higher than the default (20) would make false positives +less likely. +-- + +WIRESHARK_ABORT_ON_DISSECTOR_BUG:: ++ +-- +If this environment variable is set, *Rawshark* will call abort(3) +when a dissector bug is encountered. abort(3) will cause the program to +exit abnormally; if you are running *Rawshark* in a debugger, it +should halt in the debugger and allow inspection of the process, and, if +you are not running it in a debugger, it will, on some OSes, assuming +your environment is configured correctly, generate a core dump file. +This can be useful to developers attempting to troubleshoot a problem +with a protocol dissector. +-- + +WIRESHARK_ABORT_ON_TOO_MANY_ITEMS:: ++ +-- +If this environment variable is set, *Rawshark* will call abort(3) +if a dissector tries to add too many items to a tree (generally this +is an indication of the dissector not breaking out of a loop soon enough). +abort(3) will cause the program to exit abnormally; if you are running +*Rawshark* in a debugger, it should halt in the debugger and allow +inspection of the process, and, if you are not running it in a debugger, +it will, on some OSes, assuming your environment is configured correctly, +generate a core dump file. This can be useful to developers attempting to +troubleshoot a problem with a protocol dissector. +-- + +== SEE ALSO + +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), +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) + +== NOTES + +This is the manual page for *Rawshark* {wireshark-version}. +*Rawshark* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +*Rawshark* uses the same packet dissection code that *Wireshark* does, as +well as using many other modules from *Wireshark*; see the list of authors +in the *Wireshark* man page for a list of authors of that code. + |