wireshark/doc/tshark.adoc

include::../docbook/attributes.adoc[]
= tshark(1)
:doctype: manpage
:stylesheet: ws.css
:linkcss:
:copycss: ../docbook/{stylesheet}

== NAME

tshark - Dump and analyze network traffic

== SYNOPSIS

[manarg]
*tshark*
[ *-i* <capture interface>|- ]
[ *-f* <capture filter> ]
[ *-2* ]
[ *-r* <infile> ]
[ *-w* <outfile>|- ]
[ *options* ]
[ <filter> ]

[manarg]
*tshark*
*-G* [ <report type> ] [ --elastic-mapping-filter <protocols> ]

== DESCRIPTION

*TShark* is a network protocol analyzer.  It lets you capture packet
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.

Without any options set, *TShark* will work much like *tcpdump*.  It
will use the pcap library to capture traffic from the first available
network interface and displays a summary line on the standard output for
each received packet.

When run with the *-r* option, specifying a capture file from which to
read, *TShark* will again work much like *tcpdump*, reading packets
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
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.

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.

When displaying packets on the standard output, *TShark* writes, by
default, a summary line containing the fields specified by the
preferences file (which are also the fields displayed in the packet list
pane in *Wireshark*), although if it's writing packets as it captures
them, rather than writing packets from a saved capture file, it won't
show the "frame number" field.  If the *-V* option is specified, it
instead writes a view of the details of the packet, showing all the
fields of all protocols in the packet.  If the *-O* option is
specified, it will only show the full details for the protocols
specified, and show only the top-level detail line for all other
protocols.  Use the output of "*tshark -G protocols*" to find the
abbreviations of the protocols you can specify.  If the *-P* option is
specified with either the *-V* or *-O* options, both the summary line
for the entire packet and the details will be displayed.

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 display filter syntax described below,
and the filtering mechanism is limited in its abilities.

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 display filters.
Display filters use the same syntax as display and color filters in
*Wireshark*; a display filter is specified with the *-Y* option.

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 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
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 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.  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
the file (do __not__ use the *-w* option).

If you want the packets to be displayed to the standard output and also
saved to a file, specify the *-P* option in addition to the *-w*
option to have the summary line displayed, specify the *-V* option
in addition to the *-w* option to have the details of the packet
displayed, and specify the *-O* option, with a list of protocols, to
have the full details of the specified protocols and the top-level
detail line for all other protocols to be displayed.  If the *-P*
option is used together with the *-V* or *-O* option, the summary line
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.

When capturing packets, *TShark* writes to the standard error an
initial line listing the interfaces from which packets are being
captured and, if packet information isn't being displayed to the
terminal, writes a continuous count of packets captured to the standard
output.  If the *-q* option is specified, neither the continuous count
nor the packet information will be displayed; instead, at the end of the
capture, a count of packets captured will be displayed.  If the *-Q*
option is specified, neither the initial line, nor the packet
information, nor any packet counts will be displayed.  If the *-q* or
*-Q* option is used, the *-P*, *-V*, or *-O* option can be used to
cause the corresponding output to be displayed even though other output
is suppressed.

When reading packets, the *-q* and *-Q* option will suppress the
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*
to dump one of several types of internal glossaries and then exit.

== OPTIONS

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

-a|--autostop  <capture autostop condition>::
+
--
Specify a criterion that specifies when *TShark* is to stop writing
to a capture file.  The criterion is of the form __test:value__,
where __test__ is one of:

*duration*:__value__ Stop writing to a capture file after __value__ seconds
have elapsed. Floating point values (e.g. 0.5) are allowed.

*files*:__value__ Stop writing to capture files after __value__ number of files
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*
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.

*packets*:__value__ switch to the next file after it contains __value__
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>::
+
--
Specify a user and a password when *TShark* captures from a rpcap:// interface
where authentication is required.

This option is available with libpcap with enabled remote support.
--

-b|--ring-buffer  <capture ring buffer option>::
+
--
Cause *TShark* to run in "multiple files" mode.  In "multiple files" mode,
*TShark* will write to several capture files.  When the first capture file
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_20230714120117.pcap, outfile_00002_20230714120523.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,
at which point *TShark* will discard the data in the first file and start
writing to that file and so on.  If the __files__ option is not set,
new files filled up until one of the capture stop conditions match (or
until the disk is full).

The criterion is of the form __key:value__,
where __key__ is one of:

*duration*:__value__ switch to the next file after __value__ seconds have
elapsed, even if the current file is not completely filled up. Floating
point values (e.g. 0.5) are allowed.

*files*:__value__ begin again with the first file after __value__ number of
files were written (form a ring buffer).  This value must be less than 100000.
Caution should be used when using large numbers of files: some filesystems do
not handle many files in a single directory well.  The *files* criterion
requires either *duration*, *interval* or *filesize* to be specified to
control when to go to the next file.  It should be noted that each *-b*
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.

*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
every hour on the hour.

*packets*:__value__ switch to the next file after it contains __value__
packets.

*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_20230714164426.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
same directory close to each other.

Example: *tshark -b filesize:1000 -b files:5* results in a ring buffer of five
files of size one megabyte each.
--

-B|--buffer-size  <capture buffer size>::
+
--
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
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-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
occurrence of the *-i* option, it sets the default capture buffer size.
If used after an *-i* option, it sets the capture buffer size for
the interface specified by the last *-i* option occurring before
this option.  If the capture buffer size is not set specifically,
the default capture buffer size is used instead.
--

-c  <capture packet count>::
+
--
Set the maximum number of packets to read when capturing live
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>::
+
--
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* 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>::
+
--
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."

Example: *tshark -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.
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>::
+
--
Set an option controlling the printing of fields when *-T fields* is
selected.

Options are:

*bom=y|n* If *y*, prepend output with the UTF-8 byte order mark
(hexadecimal ef, bb, bf). Defaults to *n*.

*header=y|n* If *y*, print a list of the field names given using *-e*
as the first line of the output; the field name will be separated using
the same character as the field values.  Defaults to *n*.

*separator=/t|/s|*<character> Set the separator character to
use for fields.  If */t* tab will be used (this is the default), if
*/s*, a single space will be used.  Otherwise any character that can be
accepted by the command line as part of the option may be used.

*occurrence=f|l|a* Select which occurrence to use for fields that have
multiple occurrences.  If *f* the first occurrence will be used, if *l*
the last occurrence will be used and if *a* all occurrences will be used
(this is the default).

*aggregator=,|/s|*<character> Set the aggregator character to
use for fields that have multiple occurrences.  If *,* a comma will be used
(this is the default), if */s*, a single space will be used.  Otherwise
any character that can be accepted by the command line as part of the
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).
--

-f  <capture filter>::
+
--
Set the capture filter expression.

This option can occur multiple times.  If used before the first
occurrence of the *-i* option, it sets the default capture filter expression.
If used after an *-i* option, it sets the capture filter expression for
the interface specified by the last *-i* option occurring before
this option.  If the capture filter expression is not set specifically,
the default capture filter expression is used if provided.

Pre-defined capture filter names, as shown in the GUI menu item Capture->Capture
Filters, can be used by prefixing the argument with "predef:".
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.
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*.
There is one record per line.  The fields are tab-delimited.

[horizontal]
Field 1:: format string (e.g. "%rD")
Field 2:: text description of format string (e.g. "Dest port (resolved)")

*currentprefs*  Dumps a copy of the current preferences file to stdout.

*decodes* Dumps the "layer type"/"decode as" associations to stdout.
There is one record per line.  The fields are tab-delimited.

[horizontal]
Field 1:: layer type, e.g. "tcp.port"
Field 2:: selector in decimal
Field 3:: "decode as" name, e.g. "http"

*defaultprefs*  Dumps a default preferences file to stdout.

*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 4:: base for display (for integer types)