diff options
Diffstat (limited to 'doc/rawshark.adoc')
-rw-r--r-- | doc/rawshark.adoc | 558 |
1 files changed, 558 insertions, 0 deletions
diff --git a/doc/rawshark.adoc b/doc/rawshark.adoc new file mode 100644 index 0000000000..525df2ac7b --- /dev/null +++ b/doc/rawshark.adoc @@ -0,0 +1,558 @@ +=begin man + +=encoding utf8 + +=end man + +=head1 NAME + +rawshark - Dump and analyze raw pcap data + +=head1 SYNOPSIS + +B<rawshark> +S<[ B<-d> E<lt>encap:linktypeE<gt>|E<lt>proto:protonameE<gt> ]> +S<[ B<-F> E<lt>field to displayE<gt> ]> +S<[ B<-h> ]> +S<[ B<-l> ]> +S<[ B<-m> E<lt>bytesE<gt> ]> +S<[ B<-n> ]> +S<[ B<-N> E<lt>name resolving flagsE<gt> ]> +S<[ B<-o> E<lt>preference settingE<gt> ] ...> +S<[ B<-p> ]> +S<[ B<-r> E<lt>pipeE<gt>|- ]> +S<[ B<-R> E<lt>read (display) filterE<gt> ]> +S<[ B<-s> ]> +S<[ B<-S> E<lt>field formatE<gt> ]> +S<[ B<-t> a|ad|adoy|d|dd|e|r|u|ud|udoy ]> +S<[ B<-v> ]> + +=head1 DESCRIPTION + +B<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. + +=head1 INPUT + +Unlike B<TShark>, B<Rawshark> makes no assumptions about encapsulation or +input. The B<-d> and B<-r> flags must be specified in order for it to run. +One or more B<-F> flags should be specified in order for the output to be +useful. The other flags listed above follow the same conventions as +B<Wireshark> and B<TShark>. + +B<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 B<-p> is supplied B<rawshark> expects the following format. This +matches the I<struct pcap_pkthdr> structure and packet data used in +libpcap, Npcap, or WinPcap. This structure's format is platform-dependent; the +size of the I<tv_sec> field in the I<struct timeval> structure could be +32 bits or 64 bits. For B<rawshark> to work, the layout of the +structure in the input must match the layout of the structure in +B<rawshark>. Note that this format will probably be the same as the +previous format if B<rawshark> is a 32-bit program, but will not +necessarily be the same if B<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 B<rawshark> is running. + +=head1 OUTPUT + +If one or more fields are specified via the B<-F> flag, B<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 B<-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 B<-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. + +=head1 OPTIONS + +=over 4 + +=item -d E<lt>encapsulationE<gt> + +Specify how the packet data should be dissected. The encapsulation is of the +form I<type:value>, where I<type> is one of: + +B<encap>:I<name> Packet data should be dissected using the +libpcap/Npcap/WinPcap data link type (DLT) I<name>, e.g. B<encap:EN10MB> for +Ethernet. Names are converted using pcap_datalink_name_to_val(). +A complete list of DLTs can be found at +L<https://www.tcpdump.org/linktypes.html>. + +B<encap>:I<number> Packet data should be dissected using the +libpcap/Npcap/WinPcap LINKTYPE_ I<number>, e.g. B<encap:105> for raw IEEE +802.11 or B<encap:101> for raw IP. + +B<proto>:I<protocol> Packet data should be passed to the specified Wireshark +protocol dissector, e.g. B<proto:http> for HTTP data. + +=item -F E<lt>field to displayE<gt> + +Add the matching field to the output. Fields are any valid display filter +field. More than one B<-F> flag may be specified, and each field can match +multiple times in a given packet. A single field may be specified per B<-F> +flag. If you want to apply a display filter, use the B<-R> flag. + +=item -h + +Print the version and options and exits. + +=item -l + +Flush the standard output after the information for each packet is +printed. (This is not, strictly speaking, line-buffered if B<-V> +was specified; however, it is the same as line-buffered if B<-V> wasn't +specified, as only one line is printed for each packet, and, as B<-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 B<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 B<TShark> sees the +packet and generates that output, rather than seeing it only when the +standard output buffer containing that data fills up. + +=item -m E<lt>memory limit bytesE<gt> + +Limit rawshark's memory usage to the specified number of bytes. POSIX +(non-Windows) only. + +=item -n + +Disable network object name resolution (such as hostname, TCP and UDP port +names), the B<-N> flag might override this one. + +=item -N E<lt>name resolving flagsE<gt> + +Turn on name resolving only for particular types of addresses and port +numbers, with name resolving for other types of addresses and port +numbers turned off. This flag overrides B<-n> if both B<-N> and B<-n> are +present. If both B<-N> and B<-n> flags are not present, all name resolutions are +turned on. + +The argument is a string that may contain the letters: + +B<m> to enable MAC address resolution + +B<n> to enable network address resolution + +B<N> to enable using external resolvers (e.g., DNS) for network address +resolution + +B<t> to enable transport-layer port number resolution + +B<d> to enable resolution from captured DNS packets + +B<v> to enable VLAN IDs to names resolution + +=item -o E<lt>preferenceE<gt>:E<lt>valueE<gt> + +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 I<prefname:value>, where I<prefname> is the name of the +preference (which is the same name that would appear in the preference +file), and I<value> is the value to which it should be set. + +=item -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. + +=item -r E<lt>pipeE<gt>|- + +Read packet data from I<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. + +=item -R E<lt>read (display) filterE<gt> + +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. + +=item -s + +Allows standard pcap files to be used as input, by skipping over the 24 +byte pcap file header. + +=item -S + +Use the specified format string to print each field. The following formats +are supported: + +B<%D> Field name or description, e.g. "Type" for dns.qry.type + +B<%N> Base 10 numeric value of the field. + +B<%S> String value of the field. + +For something similar to Wireshark's standard display ("Type: A (1)") you +could use B<%D: %S (%N)>. + +=item -t a|ad|adoy|d|dd|e|r|u|ud|udoy + +Set the format of the packet timestamp printed in summary lines. +The format can be one of: + +B<a> absolute: The absolute time, as local time in your time zone, +is the actual time the packet was captured, with no date displayed + +B<ad> absolute with date: The absolute date, displayed as YYYY-MM-DD, +and time, as local time in your time zone, is the actual time and date +the packet was captured + +B<adoy> absolute with date using day of year: The absolute date, +displayed as YYYY/DOY, and time, as local time in your time zone, +is the actual time and date the packet was captured + +B<d> delta: The delta time is the time since the previous packet was +captured + +B<dd> delta_displayed: The delta_displayed time is the time since the +previous displayed packet was captured + +B<e> epoch: The time in seconds since epoch (Jan 1, 1970 00:00:00) + +B<r> relative: The relative time is the time elapsed between the first packet +and the current packet + +B<u> UTC: The absolute time, as UTC, is the actual time the packet was +captured, with no date displayed + +B<ud> UTC with date: The absolute date, displayed as YYYY-MM-DD, +and time, as UTC, is the actual time and date the packet was captured + +B<udoy> UTC with date using day of year: The absolute date, displayed +as YYYY/DOY, and time, as UTC, is the actual time and date the packet +was captured + +The default format is relative. + +=item -v + +Print the version and exit. + +=back + +=head1 READ FILTER SYNTAX + +For a complete table of protocol and protocol fields that are filterable +in B<TShark> see the wireshark-filter(4) manual page. + +=head1 FILES + +These files contains various B<Wireshark> configuration values. + +=over 4 + +=item Preferences + +The F<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 B<-o> is used (possibly more than once), it will +in turn override values from the preferences files. + +The preferences settings are in the form I<prefname:value>, +one per line, +where I<prefname> is the name of the preference +and I<value> is the value to +which it should be set; white space is allowed between B<:> and +I<value>. A preference setting can be continued on subsequent lines by +indenting the continuation lines with white space. A B<#> 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 F<wireshark> directory +under the F<share> subdirectory of the main installation directory (for +example, F</usr/local/share/wireshark/preferences>) on UNIX-compatible +systems, and in the main installation directory (for example, +F<C:\Program Files\Wireshark\preferences>) on Windows systems. + +The personal preferences file is looked for in +F<$XDG_CONFIG_HOME/wireshark/preferences> +(or, if F<$XDG_CONFIG_HOME/wireshark> does not exist while F<$HOME/.wireshark> +is present, F<$HOME/.wireshark/preferences>) on +UNIX-compatible systems and F<%APPDATA%\Wireshark\preferences> (or, if +%APPDATA% isn't defined, F<%USERPROFILE%\Application +Data\Wireshark\preferences>) on Windows systems. + +=item Disabled (Enabled) Protocols + +The F<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 F<disabled_protos> file uses the same directory as the global +preferences file. + +The personal F<disabled_protos> file uses the same directory as the +personal preferences file. + +=item Name Resolution (hosts) + +If the personal F<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 F<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 and Npcap or WinPcap on Windows. As such the Wireshark personal +F<hosts> file will not be consulted for capture filter name resolution. + +=item 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 F<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". + +=item Name Resolution (ethers) + +The F<ethers> files are consulted to correlate 6-byte hardware addresses to +names. First the personal F<ethers> file is tried and if an address is not +found there the global F<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 F<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 F<ethers> file is looked for in the F</etc> directory on +UNIX-compatible systems, and in the main installation directory (for +example, F<C:\Program Files\Wireshark>) on Windows systems. + +The personal F<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 +F<ethers> file will not be consulted for capture filter name resolution. + +=item Name Resolution (manuf) + +The F<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 F<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 F<manuf> file is looked for in the same directory as the global +preferences file. + +=item Name Resolution (services) + +The F<services> file is used to translate port numbers into names. + +The file has the standard F<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 + +=item Name Resolution (ipxnets) + +The F<ipxnets> files are used to correlate 4-byte IPX network numbers to +names. First the global F<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 F<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 F<ipxnets> file: + + C0.A8.2C.00 HR + c0-a8-1c-00 CEO + 00:00:BE:EF IT_Server1 + 110f FileServer3 + +The global F<ipxnets> file is looked for in the F</etc> directory on +UNIX-compatible systems, and in the main installation directory (for +example, F<C:\Program Files\Wireshark>) on Windows systems. + +The personal F<ipxnets> file is looked for in the same directory as the +personal preferences file. + +=back + +=head1 ENVIRONMENT VARIABLES + +=over 4 + +=item WIRESHARK_CONFIG_DIR + +This environment variable overrides the location of personal configuration +files. It defaults to F<$XDG_CONFIG_HOME/wireshark> (or F<$HOME/.wireshark> if +the former is missing while the latter exists). On Windows, +F<%APPDATA%\Wireshark> is used instead. Available since Wireshark 3.0. + +=item 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 I<README.wmem> in the source distribution for +details. + +=item 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 *NIX. + +=item 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 *NIX. + +=item 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. + +=item 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. + +=item WIRESHARK_ABORT_ON_DISSECTOR_BUG + +If this environment variable is set, B<Rawshark> will call abort(3) +when a dissector bug is encountered. abort(3) will cause the program to +exit abnormally; if you are running B<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. + +=item WIRESHARK_ABORT_ON_TOO_MANY_ITEMS + +If this environment variable is set, B<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 +B<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. + +=back + +=head1 SEE ALSO + +wireshark-filter(4), wireshark(1), tshark(1), editcap(1), pcap(3), dumpcap(1), +text2pcap(1), pcap-filter(7) or tcpdump(8) + +=head1 NOTES + +B<Rawshark> is part of the B<Wireshark> distribution. The latest version of +B<Wireshark> can be found at L<https://www.wireshark.org>. + +HTML versions of the Wireshark project man pages are available at: +L<https://www.wireshark.org/docs/man-pages>. + +=head1 AUTHORS + +B<Rawshark> uses the same packet dissection code that B<Wireshark> does, as +well as using many other modules from B<Wireshark>; see the list of authors +in the B<Wireshark> man page for a list of authors of that code. + |