diff options
Diffstat (limited to 'doc/rawshark.adoc')
| -rw-r--r-- | doc/rawshark.adoc | 551 |
1 files changed, 0 insertions, 551 deletions
diff --git a/doc/rawshark.adoc b/doc/rawshark.adoc deleted file mode 100644 index a52e594a..00000000 --- a/doc/rawshark.adoc +++ /dev/null @@ -1,551 +0,0 @@ -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. - |