Adding upstream version 4.2.2.upstream/4.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.
+