diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/man_pages/tshark.adoc (renamed from doc/tshark.adoc) | 345 |
1 files changed, 103 insertions, 242 deletions
diff --git a/doc/tshark.adoc b/doc/man_pages/tshark.adoc index 543579d5..2893a7d3 100644 --- a/doc/tshark.adoc +++ b/doc/man_pages/tshark.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = tshark(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME @@ -23,7 +23,9 @@ 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* @@ -53,7 +55,7 @@ from the file and displaying a summary line on the standard output for each packet read. *TShark* is able to detect, read and write the same capture files that are supported by *Wireshark*. The input file doesn't need a specific filename extension; the file format and an -optional gzip, zstd or lz4 compression will be automatically detected. Near the +optional gzip, Zstandard, 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 @@ -62,7 +64,8 @@ description of the way *Wireshark* handles this, which is the same way Compressed file support uses (and therefore requires) the zlib library. If the zlib library is not present when compiling *TShark*, it will be possible to compile it, but the resulting program will be unable to read -compressed files. +compressed files. Similarly, LZ4 and ZStandard also require their respective +libraries. When displaying packets on the standard output, *TShark* writes, by default, a summary line containing the fields specified by the @@ -134,9 +137,16 @@ will be displayed along with the detail lines. When writing packets to a file, *TShark*, by default, writes the file in *pcapng* format, and writes all of the packets it sees to the output file. The *-F* option can be used to specify the format in which to -write the file. This list of available file formats is displayed by the -*-F* option without a value. However, you can't specify a file format -for a live capture. +write the file. The list of available file formats is displayed by the +*-F* option without a value. However, for a live capture, you can only +specify a file format supported by xref:dumpcap.html[dumpcap](1), viz. +*pcapng* or *pcap*. The *--compress* option can be used to specify +a compression method as well; the list of supported compression methods +for writing can be displayed by the *--compress* method without an +argument. If the *--compress* option is not given, then the desired +compression method, if any, is deduced from the extension of the filename +given as argument to the *-w* option. Compression is not supported for +live capture. When capturing packets, *TShark* writes to the standard error an initial line listing the interfaces from which packets are being @@ -167,7 +177,9 @@ to dump one of several types of internal glossaries and then exit. 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. +frame dependencies to be calculated correctly. This requires the ability +to seek backwards on the input, and as such cannot be used with live captures +or when reading from a pipe or FIFO. -- -a|--autostop <capture autostop condition>:: @@ -189,7 +201,8 @@ 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 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. +the filesize is limited to a maximum value of 2 TB, although you might have +problems before then if the number of packets exceeds exceeds 2^32^ (4294967296). *packets*:__value__ switch to the next file after it contains __value__ packets. @@ -241,7 +254,9 @@ parameter takes exactly one criterion; to specify two criterion, each must be preceded by the *-b* option. *filesize*:__value__ switch to the next file after it reaches a size of -__value__ kB. Note that the filesize is limited to a maximum value of 2 GiB. +__value__ kB. Note that the filesize is limited to a maximum value of 2 TB, +although you might have problems before then if the number of packets exceeds +exceeds 2^32^ (4294967296). *interval*:__value__ switch to the next file when the time is an exact multiple of __value__ seconds. For example, use 3600 to switch to a new file @@ -250,6 +265,10 @@ 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_20240714164426.pcap). If @@ -299,7 +318,9 @@ may differ from *-a packets:*<capture packet count>. -C <configuration profile>:: + -- -Run with the given configuration profile. +Run with the given configuration profile. If used in conjucton with +--global-profile, then the global profile with the associated name +would be used. -- -D|--list-interfaces:: @@ -322,7 +343,7 @@ 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 types may be used prefixed with "_ws.col." -Example: *tshark -e frame.number -e ip.addr -e udp -e _ws.col.info* +Example: *tshark -T fields -e frame.number -e ip.addr -e udp -e _ws.col.info* Fields are separated by tab characters by default. *-E* controls the format of the printed fields. @@ -366,11 +387,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) and backspace 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*. +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>:: @@ -394,7 +418,9 @@ Example: *tshark -f "predef:MyPredefinedHostOnlyFilter"* 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. +without a value will list the available formats. The default is the +*pcapng* format (unless the default has been changed in preferences.) +. -g:: This option causes the output file(s) to be created with group-read permission @@ -405,8 +431,9 @@ user's group). + -- 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. +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: @@ -443,10 +470,10 @@ 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. Fields falling in the default case (string) won't be mapped. @@ -506,7 +533,7 @@ 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 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") @@ -638,7 +665,7 @@ Protocol match filter used for ek|json|jsonraw|pdml output file types. Only the protocol's parent node is included. Child nodes are only included if explicitly specified in the filter. -Example: *tshark -j "ip ip.flags http"* +Example: *tshark -T json -j "ip ip.flags http"* -- -J <protocol match filter>:: @@ -648,7 +675,7 @@ Protocol top level filter used for ek|json|jsonraw|pdml output file types. The protocol's parent node and all child nodes are included. Lower-level protocols must be explicitly specified in the filter. -Example: *tshark -J "tcp http"* +Example: *tshark -T pdml -J "tcp http"* -- -l:: @@ -662,7 +689,7 @@ 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.) +library.) This also sets *--update-interval* to 0 ms. 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 @@ -761,9 +788,13 @@ printed, just the statistics. + -- Read packet data from __infile__, can be any supported capture file format -(including gzipped files). It is possible to use named pipes or stdin (-) -here but only with certain (not compressed) capture file formats (in -particular: those that can be read without seeking backwards). +(including compressed files). It is possible to use named pipes or stdin (-) +here but only with certain capture file formats (in particular: those that +can be read without seeking backwards.) + +TIP: Reading a live capture from the standard out of another process through +a pipe can circumvent restrictions that apply to *TShark* during live capture, +such as file formats or compression. -- -R|--read-filter <Read filter>:: @@ -903,7 +934,10 @@ Cause *TShark* to print a view of the packet details. + -- Write raw packet data to __outfile__ or to the standard output if -__outfile__ is '-'. +__outfile__ is '-'. The *-F* and *--compress* options can be used +to control the file format and compression method. If the latter is +not given, then the extension may be used to deduce the desired +compression algorithm, if supported, e.g. a gzip archive for '.gz'. 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* @@ -1904,19 +1938,19 @@ queries collated by receiver address and then topic name. Calculate statistics on LBM Topic Resolution Packets. Displays topic queries collated by topic name and then receiver address. -*-z* mac-lte,stat[,__filter__]:: +*-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. -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__]:: @@ -1968,6 +2002,12 @@ 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 @@ -2018,19 +2058,19 @@ 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-lte,stat[,__filter__]:: +*-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. -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:: @@ -2215,7 +2255,7 @@ 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 +{wireshark-wiki-url}ColoringRules for more information on configuring color filters. --no-duplicate-keys:: @@ -2252,6 +2292,27 @@ Output JSON containing elapsed times for each pass tshark does to process a capt 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). +--compress <type>:: ++ +-- +Compress the output file using the type compression format. +*--compress* with no argument provides a list of the compression formats supported +for writing. The type given takes precedence over the extension of __outfile__. + +NOTE: This option only works with the *-r* option, i.e., when reading a +capture file, not for live captures. +//// +The --compress-type option is not documented anywhere; it works with live captures, +but only a limited set of capture options (multiple file mode (-b), but not +ringbuffer mode (no -b files), and only compressed upon file rotation.) +It works with TShark and dumpcap, but not from the command line in Wireshark +(though the Wireshark GUI can pass the option to dumpcap.) + +Should we document it? Deprecate it in favor of also using compress? Do nothing +until it has closer feature parity to *--compress* but for captures? +//// +-- + include::dissection-options.adoc[tags=**;!not_tshark] include::diagnostic-options.adoc[] @@ -2259,214 +2320,14 @@ include::diagnostic-options.adoc[] == CAPTURE FILTER SYNTAX See the manual page of xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or, if that doesn't exist, xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8), -or, if that doesn't exist, https://gitlab.com/wireshark/wireshark/-/wikis/CaptureFilters. +or, if that doesn't exist, {wireshark-wiki-url}CaptureFilters. == 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. --- +include::files.adoc[tags=**;!gui] == OUTPUT |