diff options
Diffstat (limited to 'doc/tshark.adoc')
| -rw-r--r-- | doc/tshark.adoc | 1268 |
1 files changed, 762 insertions, 506 deletions
diff --git a/doc/tshark.adoc b/doc/tshark.adoc index 81d0b56e44..bbb07cbf41 100644 --- a/doc/tshark.adoc +++ b/doc/tshark.adoc @@ -1,4 +1,4 @@ -include::../docbook/attributes.adoc[] +include::attributes.adoc[] = tshark(1) :doctype: manpage :stylesheet: ws.css @@ -23,7 +23,15 @@ tshark - Dump and analyze network traffic [manarg] *tshark* -*-G* [ <report type> ] [ --elastic-mapping-filter <protocols> ] +*-G* [ <report type> ] [ --elastic-mapping-filter <protocols> ] [ *-C* <profile> ] + +[manarg] +*tshark* +*-h|--help* + +[manarg] +*tshark* +*-v|--version* == DESCRIPTION @@ -32,7 +40,7 @@ data from a live network, or read packets from a previously saved capture file, either printing a decoded form of those packets to the standard output or writing the packets to a file. *TShark*'s native capture file format is *pcapng* format, which is also the format used -by *wireshark* and various other tools. +by *Wireshark* and various other tools. Without any options set, *TShark* will work much like *tcpdump*. It will use the pcap library to capture traffic from the first available @@ -49,7 +57,7 @@ optional gzip, zstd or lz4 compression will be automatically detected. Near the beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or https://www.wireshark.org/docs/man-pages/wireshark.html is a detailed description of the way *Wireshark* handles this, which is the same way -*Tshark* handles this. +*TShark* handles this. Compressed file support uses (and therefore requires) the zlib library. If the zlib library is not present when compiling *TShark*, it will be @@ -75,24 +83,24 @@ Packet capturing is performed with the pcap library. That library supports specifying a filter expression; packets that don't match that filter are discarded. The *-f* option is used to specify a capture filter. The syntax of a capture filter is defined by the pcap library; -this syntax is different from the read filter syntax described below, +this syntax is different from the display filter syntax described below, and the filtering mechanism is limited in its abilities. -Read filters in *TShark*, which allow you to select which packets are +Display filters in *TShark*, which allow you to select which packets are to be decoded or written to a file, are very powerful; more fields are filterable in *TShark* than in other protocol analyzers, and the syntax you can use to create your filters is richer. As *TShark* progresses, -expect more and more protocol fields to be allowed in read filters. -Read filters use the same syntax as display and color filters in -*Wireshark*; a read filter is specified with the *-R* option. +expect more and more protocol fields to be allowed in display filters. +Display filters use the same syntax as display and color filters in +*Wireshark*; a display filter is specified with the *-Y* option. -Read filters can be specified when capturing or when reading from a -capture file. Note that that capture filters are much more efficient -than read filters, and it may be more difficult for *TShark* to keep up -with a busy network if a read filter is specified for a live capture, so -you might be more likely to lose packets if you're using a read filter. +Display filters can be specified when capturing or when reading from a +capture file. Note that capture filters are much more efficient +than display filters, and it may be more difficult for *TShark* to keep up +with a busy network if a display filter is specified for a live capture, so +you might be more likely to lose packets if you're using a display filter. -A capture or read filter can either be specified with the *-f* or *-R* +A capture or display filter can either be specified with the *-f* or *-Y* option, respectively, in which case the entire filter expression must be specified as a single argument (which means that if it contains spaces, it must be quoted), or can be specified with command-line arguments @@ -100,13 +108,14 @@ after the option arguments, in which case all the arguments after the filter arguments are treated as a filter expression. If the filter is specified with command-line arguments after the option arguments, it's a capture filter if a capture is being done (i.e., if no *-r* option was -specified) and a read filter if a capture file is being read (i.e., if a +specified) and a display filter if a capture file is being read (i.e., if a *-r* option was specified). If the *-w* option is specified when capturing packets or reading from a capture file, *TShark* does not display packets on the standard output. Instead, it writes the packets to a capture file with the name -specified by the *-w* option. +specified by the *-w* option. Note that display filters are currently +not supported when capturing and saving the captured packets. If you want to write the decoded form of packets to a file, run *TShark* without the *-w* option, and redirect its standard output to @@ -147,7 +156,7 @@ display of the packet summary or details; this would be used if *-z* options are specified in order to display statistics, so that only the statistics, not the packet information, is displayed. -The *-G* option is a special mode that simply causes *Tshark* +The *-G* option is a special mode that simply causes *TShark* to dump one of several types of internal glossaries and then exit. == OPTIONS @@ -155,7 +164,7 @@ to dump one of several types of internal glossaries and then exit. -2:: + -- -Perform a two-pass analysis. This causes tshark to buffer output until the +Perform a two-pass analysis. This causes *TShark* to buffer output until the entire first pass is done, but allows it to fill in fields that require future knowledge, such as 'response in frame #' fields. Also permits reassembly frame dependencies to be calculated correctly. @@ -175,7 +184,7 @@ have elapsed. Floating point values (e.g. 0.5) are allowed. were written. *filesize*:__value__ Stop writing to a capture file after it reaches a size of -__value__ kB. If this option is used together with the -b option, *TShark* +__value__ kB. If this option is used together with the *-b* option, *TShark* will stop writing to the current capture file and switch to the next one if filesize is reached. When reading a capture file, *TShark* will stop reading the file after the number of bytes read exceeds this number (the complete @@ -183,7 +192,9 @@ packet will be read, so more bytes than this number may be read). Note that the filesize is limited to a maximum value of 2 GiB. *packets*:__value__ switch to the next file after it contains __value__ -packets. Same as *-c*<capture packet count>. +packets. +This does not include any packets that do not pass the display filter, so it +may differ from *-c*<capture packet count>. -- -A <user>:<password>:: @@ -204,7 +215,7 @@ fills up, *TShark* will switch writing to the next file and so on. The created filenames are based on the filename given with the *-w* option, the number of the file and on the creation date and time, -e.g. outfile_00001_20210714120117.pcap, outfile_00002_20210714120523.pcap, ... +e.g. outfile_00001_20240714120117.pcap, outfile_00002_20240714120523.pcap, ... With the __files__ option it's also possible to form a "ring buffer". This will fill up new files until the number of files specified, @@ -239,9 +250,13 @@ every hour on the hour. *packets*:__value__ switch to the next file after it contains __value__ packets. +*printname*:__filename__ print the name of the most recently written file +to __filename__ after the file is closed. __filename__ can be `stdout` or `-` +for standard output, or `stderr` for standard error. + *nametimenum*:__value__ Choose between two save filename templates. If __value__ is 1, make running file number part before start time part; this is -the original and default behaviour (e.g. log_00001_20210714164426.pcap). If +the original and default behaviour (e.g. log_00001_20240714164426.pcap). If __value__ is greater than 1, make start time part before running number part (e.g. log_20210828164426_00001.pcap). The latter makes alphabetical sorting order equal to creation time order, and keeps related multiple file sets in @@ -257,13 +272,14 @@ files of size one megabyte each. Set capture buffer size (in MiB, default is 2 MiB). This is used by the capture driver to buffer packet data until that data can be written to disk. If you encounter packet drops while capturing, try to increase -this size. Note that, while *Tshark* attempts to set the buffer size +this size. Note that, while *TShark* attempts to set the buffer size to 2 MiB by default, and can be told to set it to a larger value, the system or interface on which you're capturing might silently limit the capture buffer size to a lower value or raise it to a higher value. -This is available on UNIX systems with libpcap 1.0.0 or later and on -Windows. It is not available on UNIX systems with earlier versions of +This is available on UNIX-compatible systems, such as Linux, macOS, +\*BSD, Solaris, and AIX, with libpcap 1.0.0 or later, and on Windows. +It is not available on UNIX-compatible systems with earlier versions of libpcap. This option can occur multiple times. If used before the first @@ -278,8 +294,10 @@ the default capture buffer size is used instead. + -- Set the maximum number of packets to read when capturing live -data. Same as *-a packets:*<capture packet count>. +data. If reading a capture file, set the maximum number of packets to read. +This includes any packets that do not pass the display filter, so it +may differ from *-a packets:*<capture packet count>. -- -C <configuration profile>:: @@ -288,51 +306,16 @@ If reading a capture file, set the maximum number of packets to read. Run with the given configuration profile. -- --d <layer type>==<selector>,<decode-as protocol>:: -+ --- -Like Wireshark's *Decode As...* feature, this lets you specify how a -layer type should be dissected. If the layer type in question (for example, -*tcp.port* or *udp.port* for a TCP or UDP port number) has the specified -selector value, packets should be dissected as the specified protocol. - -Example: *tshark -d tcp.port==8888,http* will decode any traffic running over -TCP port 8888 as HTTP. - -Example: *tshark -d tcp.port==8888:3,http* will decode any traffic running over -TCP ports 8888, 8889 or 8890 as HTTP. - -Example: *tshark -d tcp.port==8888-8890,http* will decode any traffic running -over TCP ports 8888, 8889 or 8890 as HTTP. - -Using an invalid selector or protocol will print out a list of valid selectors -and protocol names, respectively. - -Example: *tshark -d .* is a quick way to get a list of valid selectors. - -Example: *tshark -d ethertype==0x0800.* is a quick way to get a list of -protocols that can be selected with an ethertype. --- - -D|--list-interfaces:: + -- Print a list of the interfaces on which *TShark* can capture, and -exit. For each network interface, a number and an -interface name, possibly followed by a text description of the -interface, is printed. The interface name or the number can be supplied -to the *-i* option to specify an interface on which to capture. - -This can be useful on systems that don't have a command to list them -(UNIX systems lacking *ifconfig -a* or Linux systems lacking -*ip link show*). The number can be useful on Windows systems, where -the interface name might be a long name or a GUID. - -Note that "can capture" means that *TShark* was able to open that -device to do a live capture. Depending on your system you may need to -run tshark from an account with special privileges (for example, as -root) to be able to capture network traffic. If *tshark -D* is not run -from such an account, it will not list any interfaces. +exit. For each network interface, a number and an interface name, +possibly followed by a text description of the interface, is printed. +The interface name or the number can be supplied to the *-i* flag to +specify an interface on which to capture. The number can be useful on +Windows systems, where the interfaces have long names that usually +contain a GUID. -- -e <field>:: @@ -341,14 +324,17 @@ from such an account, it will not list any interfaces. Add a field to the list of fields to display if *-T ek|fields|json|pdml* is selected. This option can be used multiple times on the command line. At least one field must be provided if the *-T fields* option is -selected. Column names may be used prefixed with "_ws.col." +selected. Column types may be used prefixed with "_ws.col." -Example: *tshark -e frame.number -e ip.addr -e udp -e _ws.col.Info* +Example: *tshark -e frame.number -e ip.addr -e udp -e _ws.col.info* -Giving a protocol rather than a single field will print multiple items -of data about the protocol as a single field. Fields are separated by -tab characters by default. *-E* controls the format of the printed -fields. +Fields are separated by tab characters by default. *-E* controls the +format of the printed fields. +Giving a protocol rather than a single field will print the protocol summary +(subtree label) from the packet details as a single field. +If the protocol summary contains only the protocol name +(e.g. "Hypertext Transfer Protocol") then the protocol filter name ("http") +will be printed. -- -E <field print option>:: @@ -384,6 +370,14 @@ option may be used. *quote=d|s|n* Set the quote character to use to surround fields. *d* uses double-quotes, *s* single-quotes, *n* no quotes (the default). +If the quote character appears in a field value, it will be escaped +by being duplicated. + +*escape=y|n* If *y*, the whitespace control characters (tab, line feed, +carriage return, form feed, and vertical tab) backspace, and the +backslash will be replaced in field values by C-style escapes, e.g. +"\n" for line feed. If *n*, field value strings will be printed as-is. +Defaults to *y*. -- -f <capture filter>:: @@ -404,33 +398,28 @@ Example: *tshark -f "predef:MyPredefinedHostOnlyFilter"* -- -F <file format>:: -+ --- Set the file format of the output capture file written using the *-w* option. The output written with the *-w* option is raw packet data, not text, so there is no *-F* option to request text output. The option *-F* without a value will list the available formats. --- -g:: -+ --- This option causes the output file(s) to be created with group-read permission (meaning that the output file(s) can be read by other members of the calling user's group). --- -G [ <report type> ]:: + -- -The *-G* option will cause *Tshark* to dump one of several types of glossaries -and then exit. If no specific glossary type is specified, then the *fields* -report will be generated by default. +The *-G* option will cause *TShark* to dump one of several types of glossaries +and then exit. If no glossary type is specified, then the *fields* report +will be generated by default; this is deprecated and a future version will +require the report type argument. The *-G* option must be the first option given. Using the report type of *help* lists all the current report types. The available report types include: -*column-formats* Dumps the column formats understood by tshark. +*column-formats* Dumps the column formats understood by *TShark*. There is one record per line. The fields are tab-delimited. [horizontal] @@ -449,18 +438,28 @@ Field 3:: "decode as" name, e.g. "http" *defaultprefs* Dumps a default preferences file to stdout. +*dissectors* Dumps a list of registered dissectors to stdout. There is +one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: dissector name +Field 2:: dissector description + *dissector-tables* Dumps a list of dissector tables to stdout. There is one record per line. The fields are tab-delimited. [horizontal] Field 1:: dissector table name, e.g. "tcp.port" Field 2:: name used for the dissector table in the GUI -Field 3:: type (textual representation of the ftenum type) +Field 3:: type (textual representation of the ftenum type, or "heuristic") Field 4:: base for display (for integer types) Field 5:: protocol name -Field 6:: "decode as" support +Field 6:: "decode as" support (for non-heuristic tables) -*elastic-mapping* Dumps the ElasticSearch mapping file to stdout. +*elastic-mapping* Dumps the ElasticSearch mapping file to stdout. Fields +falling in the default case (string) won't be mapped. + +*enterprises* Dumps the IANA Private Enterprise Number (PEN) table. *fieldcount* Dumps the number of header fields to stdout. @@ -487,7 +486,16 @@ Field 6:: base for display (for integer types); "parent bitfield width" for FT_B Field 7:: bitmask: format: hex: 0x.... Field 8:: blurb describing field -*folders* Dumps various folders used by tshark. This is essentially the +An optional search prefix argument can be given to +*fields*, in which case the output is limited to protocols and fields whose +abbreviation starts with the search prefix. + +.Search Output +[horizontal] +Field 1:: protocol or field abbreviation +Field 2:: descriptive protocol or field name + +*folders* Dumps various folders used by *TShark*. This is essentially the same data reported in Wireshark's About | Folders tab. There is one record per line. The fields are tab-delimited. @@ -495,7 +503,7 @@ There is one record per line. The fields are tab-delimited. Field 1:: Folder type (e.g "Personal configuration:") Field 2:: Folder location (e.g. "/home/vagrant/.config/wireshark/") -*ftypes* Dumps the "ftypes" (fundamental types) understood by tshark. +*ftypes* Dumps the "ftypes" (fundamental types) understood by *TShark*. There is one record per line. The fields are tab-delimited. [horizontal] @@ -506,12 +514,17 @@ Field 2:: text description of type (e.g. "IPv6 address") There is one record per line. The fields are tab-delimited. [horizontal] -Field 1:: underlying dissector (e.g. "tcp") -Field 2:: name of heuristic decoder (e.g. ucp") +Field 1:: heuristic dissector table name (e.g. "tcp") +Field 2:: name of heuristic decoder (e.g. "ucp") Field 3:: heuristic enabled (e.g. "T" or "F") +Field 4:: heuristic enabled by default (e.g. "T" or "F") +Field 5:: heuristic short name (e.g. "ucp_tcp") +Field 6:: heuristic display name (e.g. "UCP over TCP") *help* Displays the available report types. +*manuf* Dumps the MAC address lookup table in `manuf` format. + *plugins* Dumps the plugins currently installed. There is one record per line. The fields are tab-delimited. @@ -529,6 +542,11 @@ or HTML or whatever. There is one record per line. The fields are tab-delimite Field 1:: protocol name Field 2:: protocol short name Field 3:: protocol filter name +Field 4:: protocol enabled (e.g. "T" or "F") +Field 5:: protocol enabled by default (e.g. "T" or "F") +Field 6:: protocol can toggle (e.g. "T" or "F") + +*services* Dumps the TCP, UDP, and SCTP transport service (port) table. *values* Dumps the value_strings, range_strings or true/false strings for fields that have them. There is one record per line. Fields are @@ -560,10 +578,7 @@ Field 4:: False String -- -h|--help:: -+ --- -Print the version and options and exit. --- +Print the version number and options and exit. -H <input hosts file>:: + @@ -581,11 +596,9 @@ https://en.wikipedia.org/wiki/Hosts_(file). Set the name of the network interface or pipe to use for live packet capture. -Network interface names should match one of the names listed in -"*tshark -D*" (described above); a number, as reported by -"*tshark -D*", can also be used. If you're using UNIX, "*netstat - -i*", "*ifconfig -a*" or "*ip link*" might also work to list interface names, -although not all versions of UNIX support the *-a* option to *ifconfig*. +Network interface names should match one of the names listed in "*tshark +-D*" (described above); a number, as reported by "*tshark -D*", can also +be used. If no interface is specified, *TShark* searches the list of interfaces, choosing the first non-loopback interface if there are any @@ -595,10 +608,13 @@ there are no non-loopback interfaces. If there are no interfaces at all, Pipe names should be either the name of a FIFO (named pipe) or "-" to read data from the standard input. On Windows systems, pipe names must be -of the form "\\pipe\.\*pipename*". Data read from pipes must be in +of the form +"\\.\pipe\+*pipename*". Data read from pipes must be in standard pcapng or pcap format. Pcapng data must have the same endianness as the capturing host. +"TCP@<host>:<port>" causes *TShark* to attempt to connect to the +specified port on the specified host and read pcapng or pcap data. + This option can occur multiple times. When capturing from multiple interfaces, the capture file will be saved in pcapng format. -- @@ -643,15 +659,6 @@ Lower-level protocols must be explicitly specified in the filter. Example: *tshark -J "tcp http"* -- --K <keytab>:: -+ --- -Load kerberos crypto keys from the specified keytab file. -This option can be used multiple times to load keys from several files. - -Example: *tshark -K krb5.keytab* --- - -l:: + -- @@ -673,46 +680,8 @@ standard output buffer containing that data fills up. -- -L|--list-data-link-types:: -+ --- List the data link types supported by the interface and exit. The reported link types can be used for the *-y* option. --- - --n:: -+ --- -Disable network object name resolution (such as hostname, TCP and UDP port -names); the *-N* option might override this one. --- - --N <name resolving flags>:: -+ --- -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 option overrides *-n* if both *-N* and *-n* -are present. This option and *-n* override the options from the preferences, -including preferences set via the *-o* option. If both *-N* and *-n* options -are not present, the values from the preferences are used, which default to -*d*, *m*, and *N* turned on and the other options turned off. (NB, *N* does -not actually do anything without *n* enabled as well.) - -The argument is a string that may contain the letters: - -*d* to enable resolution from captured DNS packets - -*m* to enable MAC address resolution - -*n* to enable network address resolution - -*N* to enable using external resolvers (e.g., DNS) for network address -resolution; no effect without *n* also enabled - -*t* to enable transport-layer port number resolution - -*v* to enable VLAN IDs to names resolution --- -o <preference>:<value>:: + @@ -787,10 +756,8 @@ done, the continuous count of packets captured shown when saving a capture to a file, and the final message giving the count of packets captured. Only true errors are displayed on the standard error. -only display true errors; don't display the -initial message indicating the. This outputs less -than the *-q* option, so the interface name and total packet -count and the end of a capture are not sent to stderr. +This outputs less than the *-q* option, so the interface name and total +packet count and the end of a capture are not sent to stderr. When reading a capture file, or when capturing and not saving to a file, don't print packet information; this is useful if you're using a *-z* @@ -813,11 +780,11 @@ particular: those that can be read without seeking backwards). Cause the specified filter (which uses the syntax of read/display filters, rather than that of capture filters) to be applied during the first pass of analysis. Packets not matching the filter are not considered for future -passes. Only makes sense with multiple passes, see -2. For regular filtering -on single-pass dissect see -Y instead. +passes. Only makes sense with multiple passes, see *-2*. For regular filtering +on single-pass dissect see *-Y* instead. Note that forward-looking fields such as 'response in frame #' cannot be used -with this filter, since they will not have been calculate when this filter is +with this filter, since they will not have been calculated when this filter is applied. -- @@ -838,51 +805,7 @@ the default snapshot length is used if provided. -- -S <separator>:: -+ --- Set the line separator to be printed between packets. --- - --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: - -*a* absolute: The absolute time, as local time in your time zone, -is the actual time the packet was captured, with no date displayed - -*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 - -*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 - -*d* delta: The delta time is the time since the previous packet was -captured - -*dd* delta_displayed: The delta_displayed time is the time since the -previous displayed packet was captured - -*e* epoch: The time in seconds since epoch (Jan 1, 1970 00:00:00) - -*r* relative: The relative time is the time elapsed between the first packet -and the current packet - -*u* UTC: The absolute time, as UTC, is the actual time the packet was -captured, with no date displayed - -*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 - -*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. --- -T ek|fields|json|jsonraw|pdml|ps|psml|tabs|text:: + @@ -934,7 +857,7 @@ Example of usage: *pdml* Packet Details Markup Language, an XML-based format for the details of a decoded packet. This information is equivalent to the -packet details printed with the *-V* option. Using the --color option +packet details printed with the *-V* option. Using the *--color* option will add color attributes to *pdml* output. These attributes are nonstandard. @@ -945,7 +868,7 @@ depending on whether the *-V* option was specified. *psml* Packet Summary Markup Language, an XML-based format for the summary information of a decoded packet. This information is equivalent to the information shown in the one-line summary printed by default. -Using the --color option will add color attributes to *pdml* output. These +Using the *--color* option will add color attributes to *pdml* output. These attributes are nonstandard. *tabs* Similar to the default *text* report except the human-readable one-line @@ -957,37 +880,32 @@ multi-line view of the details of each of the packets, depending on whether the *-V* option was specified. This is the default. -- --u <seconds type>:: +--temp-dir <directory>:: + -- -Specifies the seconds type. Valid choices are: - -*s* for seconds - -*hms* for hours, minutes and seconds +Specifies the directory into which temporary files (including capture +files) are to be written. The default behavior on UNIX-compatible systems, +such as Linux, macOS, \*BSD, Solaris, and AIX, is to use the environment +variable __$TMPDIR__ if set, and the system default, typically __/tmp__, if it +is not. On Windows, the __%TEMP%__ environment variable is used, which +typically defaults to __%USERPROFILE%\AppData\Local\Temp__. -- -U <tap name>:: + -- PDUs export, exports PDUs from infile to outfile according to the tap -name given. Use -Y to filter. +name given. Use *-Y* to filter. Enter an empty tap name "" or a tap name of ? to get a list of available names. -- -v|--version:: -+ --- -Print the version and exit. --- +Print the full version information and exit. -V:: -+ --- Cause *TShark* to print a view of the packet details. --- -w <outfile> | -:: + @@ -995,7 +913,7 @@ Cause *TShark* to print a view of the packet details. Write raw packet data to __outfile__ or to the standard output if __outfile__ is '-'. -NOTE: -w provides raw packet data, not text. If you want text output +NOTE: *-w* provides raw packet data, not text. If you want text output you need to redirect stdout (e.g. using '>'), don't use the *-w* option for this. -- @@ -1010,7 +928,7 @@ example, will save host name resolution records along with captured packets. -Future versions of *Tshark* may automatically change the capture format +Future versions of *TShark* may automatically change the capture format to *pcapng* as needed. The argument is a string that may contain the following letter: @@ -1019,10 +937,77 @@ The argument is a string that may contain the following letter: -- -x:: +Cause *TShark* to print a hex and ASCII dump of the packet data +after printing the summary and/or details, if either are also being displayed. + +--hexdump <hexoption>:: + -- Cause *TShark* to print a hex and ASCII dump of the packet data -after printing the summary and/or details, if either are also being displayed. +with the ability to select which data sources to dump and how to +format or exclude the ASCII dump text. + +This option can be used multiple times where the data source *<hexoption>* +is *all* or *frames* and the ASCII dump text *<hexoption>* is *ascii*, +*delimit*, *noascii*. + + Example: tshark ... --hexdump frames --hexdump delimit ... + +*all*:: + +Enable hexdump, generate hexdump blocks for all data sources associated +with each frame. Used to negate earlier use of `--hexdump frames`. +The *-x* option displays all data sources by default. + +*frames*:: + +Enable hexdump, generate hexdump blocks only for the frame data. Use +this option to exclude, from hexdump output, any hexdump blocks for +secondary data sources such as 'Bitstring tvb', 'Reassembled TCP', +'De-chunked entity body', etc. + +*ascii*:: + +Enable hexdump, with undelimited ASCII dump text. Used to negate earlier +use of `--hexdump delimit` or `--hexdump noascii`. The *-x* option +displays undelimited ASCII dump text by default. + +*delimit*:: + +Enable hexdump with the ASCII dump text delimited with '|' characters. +This is useful to unambiguously determine the last of the hex byte text +and start of the ASCII dump text. + +*noascii*:: + +Enable hexdump without printing any ASCII dump text. + +*help*:: + +Display *--hexdump* specific help then exit. + +The use of *--hexdump <hexoption>* is particularly useful to generate output +that can be used to create a pcap or pcapng file from a capture file type such +as Microsoft NetMon 2.x which *TShark* and *Wireshark* can read but can not +directly do a "Save as" nor export packets from. + +Examples: + +Generate hexdump output, with only the frame data source, with delimited ASCII +dump text, with each frame hex block preceded by a human readable timestamp that +is directly usable by the *text2pcap* utility: + + tshark ... --hexdump frames --hexdump delimit \ + -P -t ad -o gui.column.format:"Time","%t" \ + | text2pcap -n -t '%F %T.%f' - MYNEWPCAPNG + +Generate hexdump output, with only the frame data source, with no ASCII dump text, +with each frame hex block preceded by an epoch timestamp that is directly +usable by the *text2pcap* utility: + + tshark ... --hexdump frames --hexdump noascii \ + -P -t e -o gui.column.format:"Time","%t" \ + | text2pcap -n -t %s.%f - MYNEWPCAPNG -- -X <eXtension options>:: @@ -1044,8 +1029,13 @@ pass the string 'bar' to the second lua script, namely 'other.lua'. *read_format*:__file_format__ tells *TShark* to use the given file format to read in the file (the file given in the *-r* command option). Providing no -__file_format__ argument, or an invalid one, will produce a file of available -file formats to use. +__file_format__ argument, or an invalid one, will produce a list of available +file formats to use. For example, + + tshark -r rtcp_broken.pcapng -X read_format:"MIME Files Format" -V + +will display the internal file structure and allow access to the +`file-pcapng` fields. -- -y|--linktype <capture link type>:: @@ -1073,8 +1063,8 @@ depend upon (e.g., fragments), are not printed but are written to file; packets not matching the filter nor depended upon are discarded rather than being printed or written. -Use this instead of -R for filtering using single-pass analysis. If doing -two-pass analysis (see -2) then only packets matching the read filter (if there +Use this instead of *-R* for filtering using single-pass analysis. If doing +two-pass analysis (see *-2*) then only packets matching the read filter (if there is one) will be checked against this filter. -- @@ -1082,13 +1072,13 @@ is one) will be checked against this filter. + -- Automatically reset internal session when reached to specified number of packets. -for example, +For example, tshark -M 100000 will reset session every 100000 packets. -This feature does not support -2 two-pass analysis +This feature does not support *-2* two-pass analysis -- -z <statistics>:: @@ -1099,6 +1089,11 @@ result after finishing reading the capture file. Use the *-q* option if you're reading a capture file and only want the statistics printed, not any per-packet information. +Statistics are calculated independently of the normal per-packet output, +unaffected by the main display filter. However, most have their own +optional __filter__ parameter, and only packets that match that filter (and +any capture filter or read filter) will be used in the calculations. + Note that the *-z proto* option is different - it doesn't cause statistics to be gathered and printed when the capture is complete, it modifies the regular packet summary output to include the values of @@ -1112,55 +1107,119 @@ Some of the currently implemented statistics are: -- *-z help*:: -+ --- Display all possible values for *-z*. --- *-z* afp,srt[,__filter__]:: -+ --- Show Apple Filing Protocol service response time statistics. --- -*-z* camel,srt:: -+ --- --- +*-z* ancp,tree[,__filter__]:: +Calculate statistics on Access Node Control Protocol message types +and adjacency packet codes. + +*-z* ansi_a,bsmap[,__filter__]:: +Count the number of ANSI A-I/F BSMAP messages of each type. + +*-z* ansi_a,dtap[,__filter__]:: +Count the number of ANSI A-I/F DTAP messages of each type. + +*-z* ansi_map[,__filter__]:: +Count the number of ANSI MAP messages of each type, and calculate the +total number of bytes and average bytes of each message type. + +*-z* asap,stat[,__filter__]:: +Calculate statistics on Aggregate Service Access Protocol (ASAP). +For each ASAP message type, displays the number, rate, and share among +all ASAP message types of both packets and bytes, and the first and last +time that it is seen. + +*-z* bacapp_instanceid,tree[,__filter__]:: +Calculate statistics on BACnet APDUs, collated by instance ID. +Displayed information includes source and destination address and +service type. + +*-z* bacapp_ip,tree[,__filter__]:: +Calculate statistics on BACnet APDUs, collated by source and destination +address. Displayed information includes service type, object ID, and +instance ID. + +*-z* bacapp_objectid,tree[,__filter__]:: +Calculate statistics on BACnet APDUs, collated by object ID. +Displayed information includes source and destination address, +service type, and instance ID. + +*-z* bacapp_service,tree[,__filter__]:: +Calculate statistics on BACnet APDUs, collated by service type. +Displayed information includes source and destination address, +object ID, and instance ID. + +*-z* calcappprotocol,stat[,__filter__]:: +Calculate statistics on the Calculation Application Protocol of +Reliable Server Pooling. For each message type, displays the number, +rate, and share among all message types of both packets and bytes, +and the first and last time that it is seen. + +*-z* camel,counter[,__filter__]:: +Count the number of CAMEL messages for each opcode. + +*-z* camel,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for CAMEL. +Data collected is number of request messages with corresponding response +of each CAMEL message type, along with the minimum, maximum, and average +response time. + +*-z* collectd,tree[,__filter__]:: +Calculate statistics for collectd. The gathered statistics are the number +of collectd packets and the total number of value segments, along with the +host, plugin, and type of the values. + +*-z* componentstatusprotocol,stat[,__filter__]:: +Calculate statistics on the Calculation Status Protocol of Reliable +Server Pooling. For each message type, displays the number, rate +and share among all message types of both packets and bytes, and the +first and last time that it is seen. *-z* conv,__type__[,__filter__]:: + -- Create a table that lists all conversations that could be seen in the -capture. __type__ specifies the conversation endpoint types for which we +capture. __type__ specifies the conversation endpoint type for which we want to generate the statistics; currently the supported ones are: - "bluetooth" Bluetooth addresses - "eth" Ethernet addresses - "fc" Fibre Channel addresses - "fddi" FDDI addresses - "ip" IPv4 addresses - "ipv6" IPv6 addresses - "ipx" IPX addresses - "jxta" JXTA message addresses - "ncp" NCP connections - "rsvp" RSVP connections - "sctp" SCTP addresses - "tcp" TCP/IP socket pairs Both IPv4 and IPv6 are supported - "tr" Token Ring addresses - "usb" USB addresses - "udp" UDP/IP socket pairs Both IPv4 and IPv6 are supported - "wlan" IEEE 802.11 addresses - -If the optional __filter__ is specified, only those packets that match the -filter will be used in the calculations. - -The table is presented with one line for each conversation and displays -the number of packets/bytes in each direction as well as the total -number of packets/bytes. The table is sorted according to the total -number of frames. + "bluetooth" Bluetooth addresses + "dccp" DCCP/IP socket pairs Both IPv4 and IPv6 are supported + "eth" Ethernet addresses + "fc" Fibre Channel addresses + "fddi" FDDI addresses + "ip" IPv4 addresses + "ipv6" IPv6 addresses + "ipx" IPX addresses + "jxta" JXTA message addresses + "mptcp" Multipath TCP connections + "ncp" NCP connections + "rsvp" RSVP connections + "sctp" SCTP/IP socket pairs Both IPv4 and IPv6 are supported + "sll" Linux "cooked mode" capture addresses + "tcp" TCP/IP socket pairs Both IPv4 and IPv6 are supported + "tr" Token Ring addresses + "udp" UDP/IP socket pairs Both IPv4 and IPv6 are supported + "usb" USB addresses + "wlan" IEEE 802.11 addresses + "wpan" IEEE 802.15.4 addresses + "zbee_nwk" ZigBee Network Layer addresses + +The table is presented with one line for each conversation which displays +the number of frames/bytes in each direction, the total number of +frames/bytes, relative start time and duration. +The table is sorted according to the total number of frames. -- +*-z* credentials:: +Collect credentials (username/passwords) from packets. The report includes +the packet number, the protocol that had that credential, the username and +the password. For protocols just using one single field as authentication, +this is provided as a password and a placeholder in place of the user. +Currently implemented protocols include FTP, HTTP, IMAP, POP, and SMTP. + *-z* dcerpc,srt,__uuid__,__major__.__minor__[,__filter__]:: + -- @@ -1174,18 +1233,16 @@ collect data for the CIFS SAMR Interface. This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. - Example: [.nowrap]#*-z dcerpc,srt,12345778-1234-abcd-ef00-0123456789ac,1.0,ip.addr==1.2.3.4*# will collect SAMR SRT statistics for a specific host. -- +*-z* dests,tree[,__filter__]:: +Calculate statistics on IPv4 destination addresses and the protocols +and ports appearing on each address. + *-z* dhcp,stat[,__filter__]:: -+ --- Show DHCP (BOOTP) statistics. --- *-z* diameter,avp[,__cmd.code__,__field__,__field__,__...__]:: + @@ -1194,7 +1251,7 @@ This option enables extraction of most important diameter fields from large capture files. Exactly one text line for each diameter message with matched *diameter.cmd.code* will be printed. -Empty diameter command code or '*' can be specified to mach any *diameter.cmd.code* +Empty diameter command code or +'*'+ can be specified to match any *diameter.cmd.code* Example: *-z diameter,avp* extract default field set from diameter messages. @@ -1231,51 +1288,62 @@ Multiple diameter messages in one frame are supported. Several fields with same name within one diameter message are supported, e.g. __diameter.Subscription-Id-Data__ or __diameter.Rating-Group__. -Note: *tshark -q* option is recommended to suppress default *tshark* output. +Note: *tshark -q* option is recommended to suppress default *TShark* output. -- +*-z* diameter,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for Diameter. +Data collected is number of request and response pairs of each Diameter +command code, Minimum SRT, Maximum SRT, Average SRT, and Sum SRT. +Currently no statistics are gathered on unpaired messages. + *-z* dns,tree[,__filter__]:: -+ --- Create a summary of the captured DNS packets. General information are collected such as qtype and qclass distribution. For some data (as qname length or DNS payload) max, min and average values are also displayed. --- *-z* endpoints,__type__[,__filter__]:: + -- Create a table that lists all endpoints that could be seen in the -capture. __type__ specifies the endpoint types for which we +capture. __type__ specifies the endpoint type for which we want to generate the statistics; currently the supported ones are: - "bluetooth" Bluetooth addresses - "eth" Ethernet addresses - "fc" Fibre Channel addresses - "fddi" FDDI addresses - "ip" IPv4 addresses - "ipv6" IPv6 addresses - "ipx" IPX addresses - "jxta" JXTA message addresses - "ncp" NCP connections - "rsvp" RSVP connections - "sctp" SCTP addresses - "tcp" TCP/IP socket pairs Both IPv4 and IPv6 are supported - "tr" Token Ring addresses - "usb" USB addresses - "udp" UDP/IP socket pairs Both IPv4 and IPv6 are supported - "wlan" IEEE 802.11 addresses - -If the optional __filter__ is specified, only those packets that match the -filter will be used in the calculations. - -The table is presented with one line for each conversation and displays -the number of packets/bytes in each direction as well as the total -number of packets/bytes. The table is sorted according to the total -number of frames. --- - -*-z* expert[__,error|,warn|,note|,chat|,comment__][__,filter__]:: + "bluetooth" Bluetooth addresses + "dccp" DCCP/IP socket pairs Both IPv4 and IPv6 are supported + "eth" Ethernet addresses + "fc" Fibre Channel addresses + "fddi" FDDI addresses + "ip" IPv4 addresses + "ipv6" IPv6 addresses + "ipx" IPX addresses + "jxta" JXTA message addresses + "mptcp" Multipath TCP connections + "ncp" NCP connections + "rsvp" RSVP connections + "sctp" SCTP/IP socket pairs Both IPv4 and IPv6 are supported + "sll" Linux "cooked mode" capture addresses + "tcp" TCP/IP socket pairs Both IPv4 and IPv6 are supported + "tr" Token Ring addresses + "udp" UDP/IP socket pairs Both IPv4 and IPv6 are supported + "usb" USB addresses + "wlan" IEEE 802.11 addresses + "wpan" IEEE 802.15.4 addresses + "zbee_nwk" ZigBee Network Layer addresses + +The table is presented with one line for each endpoint which displays +the total number of packets/bytes and the number of packets/bytes in +each direction. +The table is sorted according to the total number of packets. +-- + +*-z* enrp,stat[,__filter__]:: +Calculate statistics on Endpoint Handlespace Redundancy Protocol (ENRP). +For each message type, displays the number, rate, and share among +all message types of both packets and bytes, and the first and last +time that it is seen. + +*-z* expert[__,error|,warn|,note|,chat|,comment__][,__filter__]:: + -- Collects information about all expert info, and will display them in order, @@ -1286,14 +1354,34 @@ match the sip protocol. This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. - Example: *-z "expert,note,tcp"* will only collect expert items for frames that include the tcp protocol, with a severity of note or higher. -- -*-z* flow,__name__,__mode__,[__filter__]:: +*-z* f1ap,tree[,__filter__]:: +Calculate the distribution of F1AP packets, grouped by packet types. + +*-z* f5_tmm_dist,tree[,__filter__]:: +Calculate the F5 Ethernet trailer Traffic Management Microkernel distribution. +Displayed information is the number of packets and bytes, grouped by the TMM +slot and number, whether packets are ingress or egress, and whether there is +a flow ID and virtual server name, a flow ID without virtual server name, or +no flow ID, along with total for all packets with F5 trailers. + +*-z* f5_virt_dist,tree[,__filter__]:: +Calculate F5 Ethernet trailer Virtual Server distribution. +Displayed information is the number of packets and bytes, grouped by the +virtual server name if it exists, or by whether there is a flow ID or not +if there is no virtual server name, as well as totals for all packets with +F5 trailers. + +*-z* fc,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for GTP. +Data collected is the number of request/response pairs, minimum SRT, +maximum SRT, average SRT, and sum SRT for each value of the Type field +(next protocol). No statistics are gathered on unpaired messages. + +*-z* flow,__name__,__mode__[,__filter__]:: + -- Displays the flow of data between two nodes. Output is the same as ASCII format @@ -1315,7 +1403,7 @@ __mode__ specifies the address type. It can be one of: Example: *-z flow,tcp,network* will show data flow for all TCP frames -- -*-z* follow,__prot__,__mode__,__filter__[__,range__]:: +*-z* follow,__prot__,__mode__,__filter__[,__range__]:: + -- Displays the contents of a TCP or UDP stream between two nodes. The data @@ -1326,30 +1414,48 @@ __prot__ specifies the transport protocol. It can be one of: tcp TCP udp UDP + dccp DCCP tls TLS or SSL + http HTTP streams http2 HTTP/2 streams quic QUIC streams +NOTE: While the usage help presents sip as an option, the proper +stream filters are not implemented so SIP calls cannot be followed +in *TShark*, only in *Wireshark*. + __mode__ specifies the output mode. It can be one of: ascii ASCII output with dots for non-printable characters ebcdic EBCDIC output with dots for non-printable characters hex Hexadecimal and ASCII data with offsets raw Hexadecimal data + utf-8 UTF-8 output with REPLACEMENT CHARACTERs for invalid sequences yaml YAML format -Since the output in *ascii* or *ebcdic* mode may contain newlines, the length -of each section of output plus a newline precedes each section of output. +Since the output in *ascii*, *ebcdic*, or *utf-8* mode may contain newlines, +each section of output is preceded by its length in bytes plus a newline. +(Note that for *utf-8* this is not UTF-8 characters, and may be different +than the length as transmitted due to the substitution of replacement +characters for invalid sequences.) -__filter__ specifies the stream to be displayed. UDP/TCP streams are selected -with either the stream index or IP address plus port pairs. TLS streams are -selected with the stream index. HTTP/2 streams are selected by combination of -UDP/TCP and HTTP/2 streams indices. For example: +__filter__ specifies the stream to be displayed. There are three formats: ip-addr0:port0,ip-addr1:port1 stream-index stream-index,substream-index +The first format specifies IP addresses and TCP, UDP, or DCCP port pairs. +(TCP ports are used for TLS, HTTP, and HTTP2; QUIC does not support address +and port matching because of connection migration.) + +The second format specifies stream indices, and is used for TCP, UDP, DCCP, +TLS, and HTTP. (TLS and HTTP use TCP stream indices.) + +The third format, specifying streams and substreams, is used for HTTP/2 and +QUIC due to their use of multiplexing. (TCP stream and HTTP/2 stream indices +for HTTP/2, QUIC connection number and stream ID for QUIC.) + __range__ optionally specifies which "chunks" of the stream should be displayed. Example: *-z "follow,tcp,hex,1"* will display the contents of the second TCP @@ -1398,12 +1504,67 @@ stream on the first TCP session (index 0) with HTTP/2 Stream ID 1. 00000020 34 a0 5b b8 21 5c 0b ea 62 d1 bf 4.[.!\.. b.. 0000002B 00 40 00 00 00 00 00 00 01 89 50 4e 47 0d 0a 1a .@...... ..PNG... -QUIC streams can be selected through *-z "follow,quic,hex,3,0"*, the first -number indicates the QUIC connection number whereas the second number selects the QUIC -Stream ID. -- -*-z* h225,counter[__,filter__]:: +*-z* fractalgeneratorprotocol,stat[,__filter__]:: ++ +-- +Calculate statistics on the Fractal Generator Protocol of Reliable +Server Pooling. For each message type, displays the number, rate +and share among all message types of both packets and bytes, and the +first and last time that it is seen. +-- + +*-z* gsm_a:: ++ +-- +Count the number of GSM A-I/F messages of each type within the following +categories: BSSMAP, DTAP Mobility Management, DTAP Radio Resource +Management, DTAP Call Control, DTAP GPRS Mobility Management, DTAP SMS +messages, DTAP GPRS Session Management, DTAP Supplementary Services, DTAP +Special Conformance Testing Functions, and SACCH Radio Resource Management. + +Unlike the individual statistics for each category that follow, this only +prints a line for each message type that appears, instead of including lines +for message types with a count of zero. +-- + +*-z* gsm_a,__category__[,__filter__]:: ++ +-- +Count the number of messages of each type in GSM A-I/F __category__, which +can be one of: + + bssmap BSSMAP + dtap_cc DTAP Call Control + dtap_gmm DTAP GPRS Mobility Management + dtap_mm DTAP Mobility Management + dtap_rr DTAP Radio Resource Management + dtap_sacch SACCH Radio Resource Management + dtap_sm DTAP GPRS Session Management + dtap_sms DTAP Short Message Service + dtap_ss DTAP Supplementary Services + dtap_tp DTAP Special Conformance Testing Functions +-- + +*-z* gsm_map,operation[,__filter__]:: +Calculate statistics on GSM MAP. For each op code, the total number of +invokes and results, along with the average and total bytes for invokes +and results separately and combined is displayed. + +*-z* gtp,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for GTP. +Data collected is the number of calls, minimum SRT, maximum SRT, average +SRT, and sum SRT for certain commands. Currently no statistics are gathered +on unpaired messages. + +*-z* gtpv2,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for GTP. +Data collected is the number of calls, minimum SRT, maximum SRT, average +SRT, and sum SRT for certain commands. Currently no statistics are gathered +on unpaired messages. + +*-z* h225,counter[,__filter__]:: + -- Count ITU-T H.225 messages and their reasons. In the first column you get a @@ -1413,88 +1574,73 @@ in the second column. Example: *-z h225,counter*. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. Example: use *-z "h225,counter,ip.addr==1.2.3.4"* to only collect stats for H.225 packets exchanged by the host at IP address 1.2.3.4 . This option can be used multiple times on the command line. -- -*-z* h225,srt[__,filter__]:: +*-z* h225_ras,rtd[,__filter__]:: + -- -Collect requests/response SRT (Service Response Time) data for ITU-T H.225 RAS. +Collect requests/response RTD (Response Time Delay) data for ITU-T H.225 RAS. Data collected is number of calls of each ITU-T H.225 RAS Message Type, -Minimum SRT, Maximum SRT, Average SRT, Minimum in Packet, and Maximum in Packet. +Minimum RTD, Maximum RTD, Average RTD, Minimum in Frame, and Maximum in Frame. You will also get the number of Open Requests (Unresponded Requests), Discarded Responses (Responses without matching request) and Duplicate Messages. -Example: *tshark -z h225,srt* +Example: *tshark -z h225_ras,rtd* This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. - -Example: *-z "h225,srt,ip.addr==1.2.3.4"* will only collect stats for +Example: *-z "h225_ras,rtd,ip.addr==1.2.3.4"* will only collect stats for ITU-T H.225 RAS packets exchanged by the host at IP address 1.2.3.4 . -- +*-z* hart_ip,tree[,__filter__]:: +Calculate statistics on HART-IP packets, grouping by message types and +message IDs within types. + *-z* hosts[,ip][,ipv4][,ipv6]:: + -- -Dump any collected IPv4 and/or IPv6 addresses in "hosts" format. Both IPv4 -and IPv6 addresses are dumped by default. "ip" argument will dump only ipv4 -addresses. +Dump any collected resolved IPv4 and/or IPv6 addresses in "hosts" format. +Both IPv4 and IPv6 addresses are dumped by default. "ip" argument will dump +only IPv4 addresses. Addresses are collected from a number of sources, including standard "hosts" -files and captured traffic. +files and captured traffic. Resolution must be enabled, e.g. through the +*-n* option. -- *-z* hpfeeds,tree[,__filter__]:: -+ --- Calculate statistics for HPFEEDS traffic such as publish per channel, and opcode distribution. --- -*-z* http,stat,:: -+ --- -Calculate the HTTP statistics distribution. Displayed values are -the HTTP status codes and the HTTP request methods. --- +*-z* http,stat[,__filter__]:: +Count the HTTP response status codes and the HTTP request methods. -*-z* http,tree:: -+ --- +*-z* http,tree[,__filter__]:: Calculate the HTTP packet distribution. Displayed values are the -HTTP request modes and the HTTP status codes. --- - -*-z* http_ref,tree:: -+ --- -Calculate the HTTP requests by referer. Displayed values are the -referring URI. --- +response status codes and request methods. -*-z* http_req,tree:: -+ --- +*-z* http_req,tree[,__filter__]:: Calculate the HTTP requests by server. Displayed values are the server name and the URI path. --- -*-z* http_srv,tree:: -+ --- +*-z* http_seq,tree[,__filter__]:: +Calculate the HTTP request sequence statistics, which correlate +referring URIs with request URIs. + +*-z* http_srv,tree[,__filter__]:: Calculate the HTTP requests and responses by server. For the HTTP requests, displayed values are the server IP address and server hostname. For the HTTP responses, displayed values are the server IP address and status. --- + +*-z* http2,tree[,__filter__]:: +Calculate the HTTP/2 packet distribution. Displayed values are the +frame types. *-z* icmp,srt[,__filter__]:: + @@ -1526,9 +1672,6 @@ This option can be used multiple times on the command line. + -- Create Protocol Hierarchy Statistics listing both number of packets and bytes. -If no __filter__ is specified the statistics will be calculated for all packets. -If a __filter__ is specified statistics will only be calculated for those -packets that match the filter. This option can be used multiple times on the command line. -- @@ -1541,7 +1684,6 @@ __interval__ seconds. __Interval__ can be specified either as a whole or fractional second and can be specified with microsecond (us) resolution. If __interval__ is 0, the statistics will be calculated over all packets. -If no __filter__ is specified the statistics will be calculated for all packets. If one or more __filters__ are specified statistics will be calculated for all filters and presented with one column of statistics for each filter. @@ -1690,24 +1832,102 @@ the total number of bytes transmitted to the client (unidirectionally) at IP add ======================================================================================================================= -- -*-z* mac-lte,stat[__,filter__]:: +*-z* ip_hosts,tree[,__filter__]:: +Calculate statistics on IPv4 addresses, with source and destination addresses +all grouped together. + +*-z* ip_srcdst,tree[,__filter__]:: +Calculate statistics on IPv4 addresses, with source and destination addresses +separated into separate categories. + +*-z* ip_ttl,tree[,__filter__]:: +Calculate statistics on the time to live (TTL) values that occur for each +IPv4 source address. + +*-z* ip6_dests,tree[,__filter__]:: +Calculate statistics on IPv6 destination addresses and the protocols +and ports appearing on each address. + +*-z* ip6_hosts,tree[,__filter__]:: +Calculate statistics on IPv6 addresses, with source and destination addresses +all grouped together. + +*-z* ip6_ptype,tree[,__filter__]:: +Calculate statistics on port types that occur on IPv6 packets. + +*-z* ip6_srcdst,tree[,__filter__]:: +Calculate statistics on IPv6 addresses, with source and destination addresses +separated into separate categories. + +*-z* ip6_hop,tree[,__filter__]:: +Calculate statistics on the hop limits that occur for each IPv6 source address. + +*-z* isup_msg,tree[,__filter__]:: +Calculate statistics on ISUP messages. Displayed information is message +types and direction (originating point code and destination point code.) + +*-z* lbmr_queue_ads_queue,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays queue +advertisements collated by queue name and then source addresses and port. + +*-z* lbmr_queue_ads_source,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays queue +advertisements collated by source address and then queue and port. + +*-z* lbmr_queue_queries_queue,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays queue +queries collated by queue name and then receiver addresses. + +*-z* lbmr_queue_queries_receiver,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays queue +queries collated by receiver address and then queue. + +*-z* lbmr_topic_ads_source,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +advertisements collated by source address and then topic name and +source string. + +*-z* lbmr_topic_ads_topic,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +advertisements collated by topic name and then source address and +source string. + +*-z* lbmr_topic_ads_transport,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +advertisements collated by source string and then topic name. + +*-z* lbmr_topic_queries_pattern,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +queries collated by pattern and then receiver address. + +*-z* lbmr_topic_queries_pattern_receiver,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +queries collated by receiver address and then pattern. + +*-z* lbmr_topic_queries_receiver,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +queries collated by receiver address and then topic name. + +*-z* lbmr_topic_queries_topic,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +queries collated by topic name and then receiver address. + +*-z* mac-3gpp,stat[,__filter__]:: + -- -This option will activate a counter for LTE MAC messages. You will get +This option will activate a counter for LTE or NR MAC messages. You will get information about the maximum number of UEs/TTI, common messages and various counters for each UE that appears in the log. -Example: *tshark -z mac-lte,stat*. +Example: *tshark -z mac-3gpp,stat*. This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -for those frames that match that filter. -Example: *-z "mac-lte,stat,mac-lte.rnti>3000"* will only collect stats for -UEs with an assigned RNTI whose value is more than 3000. +Example: *-z "mac-3gpp,stat,mac-lte.rnti>3000"* will only collect stats for +LTE UEs with an assigned RNTI whose value is more than 3000. -- -*-z* megaco,rtd[__,filter__]:: +*-z* megaco,rtd[,__filter__]:: + -- Collect requests/response RTD (Response Time Delay) data for MEGACO. @@ -1717,15 +1937,13 @@ Additionally you get the number of duplicate requests/responses, unresponded requests, responses, which don't match with any request. Example: *-z megaco,rtd*. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. Example: *-z "megaco,rtd,ip.addr==1.2.3.4"* will only collect stats for MEGACO packets exchanged by the host at IP address 1.2.3.4 . This option can be used multiple times on the command line. -- -*-z* mgcp,rtd[__,filter__]:: +*-z* mgcp,rtd[,__filter__]:: + -- Collect requests/response RTD (Response Time Delay) data for MGCP. @@ -1737,20 +1955,42 @@ Example: *-z mgcp,rtd*. This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. Example: *-z "mgcp,rtd,ip.addr==1.2.3.4"* will only collect stats for MGCP packets exchanged by the host at IP address 1.2.3.4 . -- -*-z* credentials:: -+ --- -Collect credentials (username/passwords) from packets. The report includes -the packet number, the protocol that had that credential, the username and -the password. For protocols just using one single field as authentication, -this is provided as a password and a placeholder in place of the user. --- +*-z* mtp3,msus[,__filter__]:: +Calculate statistics on MTP3 MSUs. For each combination of originating +point code, destination point code, and service indicator, calculates +the total number of MSUs, the total bytes, and the average bytes per MSU. + +*-z* ncp,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for Netware +Core Protocol. Minimum SRT, maximum SRT, average SRT, and sum SRT is +displayed for request/response pairs, organized by group, function and +subfunction, and verb. No statistics are gathered on unpaired messages. + +*-z* osmux,tree[,__filter__]:: +Calculate statistics for the OSmux voice/signaling multiplex protocol. +Displays the total number of OSmux packets, and displays for each stream +the number of packets, number of packets with the RTP market bit set, +number of AMR frames, jitter analysis, and sequence number analysis. + +*-z* pfcp,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for PFCP. +Data collected is the number of calls, minimum SRT, maximum SRT, average +SRT, and sum SRT for certain commands. Currently no statistics are gathered +on unpaired messages. + +*-z* pingpongprotocol,stat[,__filter__]:: +Calculate statistics on the Ping Pong Protocol of Reliable +Server Pooling. For each message type, displays the number, rate +and share among all message types of both packets and bytes, and the +first and last time that it is seen. + +*-z* plen,tree[,__filter__]:: +Calculate statistics on packet lengths. Packets are grouped into buckets +that grow exponentially with powers of two. *-z* proto,colinfo,__filter__,__field__:: + @@ -1782,21 +2022,29 @@ host 1.2.3.4 use: This option can be used multiple times on the command line. -- -*-z* rlc-lte,stat[__,filter__]:: +*-z* ptype,tree[,__filter__]:: +Calculate statistics on port types that occur on IPv4 packets. + +*-z* radius,rtd[,__filter__]:: +Collect requests/response RTD (Response Time Delay) data for RADIUS. +The data collected for each RADIUS code is the number of calls, +Minimum RTD, Maximum RTD, Average RTD, Minimum in Frame, and Maximum in Frame, +along with the number of Open Requests (Unresponded Requests), Discarded +Responses (Responses without matching request) and Duplicate Messages. + +*-z* rlc-3gpp,stat[,__filter__]:: + -- -This option will activate a counter for LTE RLC messages. You will get +This option will activate a counter for LTE or NR RLC messages. You will get information about common messages and various counters for each UE that appears in the log. -Example: *tshark -z rlc-lte,stat*. +Example: *tshark -z rlc-3gpp,stat*. This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -for those frames that match that filter. -Example: *-z "rlc-lte,stat,rlc-lte.ueid>3000"* will only collect stats for -UEs with a UEId of more than 3000. +Example: *-z "rlc-3gpp,stat,rlc-nr.ueid>3000"* will only collect stats for +NR UEs with a UEId of more than 3000. -- *-z* rpc,programs:: @@ -1819,19 +2067,24 @@ Example: *tshark -z rpc,srt,100003,3* will collect data for NFS v3. This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. - Example: *-z rpc,srt,100003,3,nfs.fh.hash==0x12345678* will collect NFS v3 SRT statistics for a specific file. -- *-z* rtp,streams:: -+ --- Collect statistics for all RTP streams and calculate max. delta, max. and mean jitter and packet loss percentages. --- + +*-z* rtsp,stat[,__filter__]:: +Count the RTSP response status codes and the RSTP request methods. + +*-z* rtsp,tree[,__filter__]:: +Calculate the RTSP packet distribution. Displayed values are the +response status codes and request methods. + +*-z* sametime,tree[,__filter__]:: +Calculate statistics on SAMETIME messages. Displayed values are the +messages type, send type, and user status. *-z* scsi,srt,__cmdset__[,__filter__]:: + @@ -1847,14 +2100,18 @@ Example: *-z scsi,srt,0* will collect data for SCSI BLOCK COMMANDS (SBC). This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. - Example: *-z scsi,srt,0,ip.addr==1.2.3.4* will collect SCSI SBC SRT statistics for a specific iscsi/ifcp/fcip host. -- -*-z* sip,stat[__,filter__]:: +*-z* sctp,stat:: +Activate a counter for SCTP chunks. In addition to the total number of +SCTP packets, for each source and destination address and port combination +the number of chunks of the most common types (DATA, SACK, HEARTBEAT, +HEARTBEAT ACK, INIT, INIT ACK, COOKIE ECHO, COOKIE ACK, ABORT, and ERROR) +are displayed. + +*-z* sip,stat[,__filter__]:: + -- This option will activate a counter for SIP messages. You will get the number @@ -1865,8 +2122,6 @@ Example: *-z sip,stat*. This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. Example: *-z "sip,stat,ip.addr==1.2.3.4"* will only collect stats for SIP packets exchanged by the host at IP address 1.2.3.4 . -- @@ -1906,13 +2161,47 @@ This is a flaw that might be fixed in the future. This option can be used multiple times on the command line. -If the optional __filter__ is provided, the stats will only be calculated -on those calls that match that filter. - Example: *-z "smb,srt,ip.addr==1.2.3.4"* will only collect stats for SMB packets exchanged by the host at IP address 1.2.3.4 . -- +*-z* smb2,srt[,__filter__]:: +Collect call/reply SRT (Service Response Time) data for SMB versions 2 and 3. +The data collected for each normal command type is the number of calls, +MinSRT, MaxSRT, AvgSRT, and SumSRT. No data is collected on cancel or +oplock break requests, or on unpaired commands. Only the first response to +a given request is used; retransmissions are not included in the calculation. + +*-z* smpp_commands,tree[,__filter__]:: +Calculate the SMPP command distribution. Displayed values are +command IDs for both requests and responses, and status for responses. + +*-z* snmp,srt[,__filter__]:: +Collect call/reply SRT (Service Response Time) data for SNMP. The data +collected for each PDU type is the number of request/response pairs, +MinSRT, MaxSRT, AvgSRT, and SumSRT. No data is collected on unpaired +messages. + +*-z* someip_messages,tree[,__filter__]:: +Create statistic of SOME/IP messages. Messages are counted and displayed +as Messages grouped by sender/receiver. + +*-z* someipsd_entries,tree[,__filter__]:: +Create statistic of SOME/IP-SD entries. Entries are counted and displayed +as Entries grouped by sender/receiver. + +*-z* sv:: +Print out the time since the start of the capture and sample count for each +IEC 61850 Sampled Values packet. + +*-z* ucp_messages,tree[,__filter__]:: +Calculate the message distribution of UCP packets. Displayed values are +operation types for both operations and results, and whether results are +positive or negative, with error codes displayed for negative results. + +*-z* wsp,stat[,__filter__]:: +Count the PDU types and the status codes of reply packets for WSP packets. + --capture-comment <comment>:: + -- @@ -1924,36 +2213,29 @@ currently only displays the first comment of a capture file. -- --list-time-stamp-types:: -+ --- List time stamp types supported for the interface. If no time stamp type can be set, no time stamp types are listed. --- --time-stamp-type <type>:: -+ --- Change the interface's timestamp method. --- + +--update-interval <interval>:: +Set the length of time in milliseconds between new packet reports during +a capture. Also sets the granularity of file duration conditions. +The default value is 100ms. --color:: -+ --- Enable coloring of packets according to standard Wireshark color filters. On Windows colors are limited to the standard console character attribute colors. Other platforms require a terminal that handles 24-bit "true color" terminal escape sequences. See https://gitlab.com/wireshark/wireshark/-/wikis/ColoringRules for more information on configuring color filters. --- --no-duplicate-keys:: -+ --- If a key appears multiple times in an object, only write it a single time with as value a json array containing all the separate values. (Only works with --T json) --- +*-T json*) --elastic-mapping-filter <protocol>,<protocol>,...:: + @@ -1979,29 +2261,14 @@ before the file extension. This interface is subject to change, adding the possibility to filter on files. -- ---enable-protocol <proto_name>:: -+ --- -Enable dissection of proto_name. --- - ---disable-protocol <proto_name>:: -+ --- -Disable dissection of proto_name. --- +--print-timers:: +Output JSON containing elapsed times for each pass tshark does to process a capture +file and the sum elapsed time for all passes. The per-pass output contains the total +elapsed time and aggregate counters for per-packet operations (dissection and filtering). ---enable-heuristic <short_name>:: -+ --- -Enable dissection of heuristic protocol. --- +include::dissection-options.adoc[tag=!not_tshark] ---disable-heuristic <short_name>:: -+ --- -Disable dissection of heuristic protocol. --- +include::diagnostic-options.adoc[] == CAPTURE FILTER SYNTAX @@ -2041,18 +2308,23 @@ starts a comment that runs to the end of the line: capture.prom_mode: TRUE The global preferences file is looked for in the __wireshark__ directory -under the __share__ subdirectory of the main installation directory (for -example, __/usr/local/share/wireshark/preferences__) on UNIX-compatible -systems, and in the main installation directory (for example, -__C:\Program Files\Wireshark\preferences__) on Windows 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__ -is present, __$HOME/.wireshark/preferences__) on -UNIX-compatible systems and __%APPDATA%\Wireshark\preferences__ (or, if -%APPDATA% isn't defined, __%USERPROFILE%\Application - Data\Wireshark\preferences__) on Windows systems. +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:: @@ -2085,8 +2357,9 @@ 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 -__hosts__ file will not be consulted for capture filter name resolution. +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):: @@ -2129,8 +2402,9 @@ lines of an __ethers__ file: 00.00.00.00.00.00 Zero_broadcast The global __ethers__ file is looked for in the __/etc__ directory on -UNIX-compatible systems, and in the main installation directory (for -example, __C:\Program Files\Wireshark__) on Windows systems. +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. @@ -2200,8 +2474,9 @@ For example, these four lines are valid lines of an __ipxnets__ file: 110f FileServer3 The global __ipxnets__ file is looked for in the __/etc__ directory on -UNIX-compatible systems, and in the main installation directory (for -example, __C:\Program Files\Wireshark__) on Windows systems. +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. @@ -2214,9 +2489,10 @@ output might not be valid. For example, a dissector might generate invalid UTF-8 character sequences. Programs reading *TShark* output should expect UTF-8 and be prepared for invalid output. -If *TShark* detects that it is writing to a TTY on UNIX or Linux and -the locale does not support UTF-8, output will be re-encoded to match the -current locale. +If *TShark* detects that it is writing to a TTY on a UNIX-compatible +system, such as Linux, macOS, \*BSD, Solaris, and AIX, and the locale +does not support UTF-8, output will be re-encoded to match the current +locale. If *TShark* detects that it is writing to the console on Windows, dissection output will be encoded as UTF-16LE. Other output will be @@ -2229,62 +2505,61 @@ and using a modern terminal application if possible. // Should this be moved to an include file? WIRESHARK_CONFIG_DIR:: -+ --- -This environment variable overrides the location of personal configuration -files. It defaults to __$XDG_CONFIG_HOME/wireshark__ (or __$HOME/.wireshark__ if -the former is missing while the latter exists). On Windows, -__%APPDATA%\Wireshark__ is used instead. Available since Wireshark 3.0. --- +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 *NIX. --- +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 *NIX. --- +program in question is running with root (or setuid) permissions on +UNIX-compatible systems. + +WIRESHARK_EXTCAP_DIR:: +This environment variable causes the various extcap programs and scripts +to be run 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. + +WIRESHARK_PLUGIN_DIR:: +This environment variable causes the various plugins 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, *TShark* will call abort(3) when a dissector bug is encountered. abort(3) will cause the program to exit abnormally; if you are running *TShark* in a debugger, it @@ -2293,11 +2568,8 @@ 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, *TShark* 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). @@ -2307,48 +2579,32 @@ 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_LOG_LEVEL:: -+ --- This environment variable controls the verbosity of diagnostic messages to the console. From less verbose to most verbose levels can be `critical`, `warning`, `message`, `info`, `debug` or `noisy`. Levels above the current level are also active. Levels `critical` and `error` are always active. --- WIRESHARK_LOG_FATAL:: -+ --- Sets the fatal log level. Fatal log levels cause the program to abort. This level can be set to `Error`, `critical` or `warning`. `Error` is always fatal and is the default. --- WIRESHARK_LOG_DOMAINS:: -+ --- This environment variable selects which log domains are active. The filter is given as a case-insensitive comma separated list. If set only the included domains will be enabled. The default domain is always considered to be enabled. Domain filter lists can be preceded by '!' to invert the sense of the match. --- WIRESHARK_LOG_DEBUG:: -+ --- List of domains with `debug` log level. This sets the level of the provided log domains and takes precedence over the active domains filter. If preceded by '!' this disables the `debug` level instead. --- WIRESHARK_LOG_NOISY:: -+ --- Same as above but for `noisy` log level instead. --- == SEE ALSO |