diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/man_pages/androiddump.adoc (renamed from doc/androiddump.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/asn2deb.adoc (renamed from doc/asn2deb.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/capinfos.adoc (renamed from doc/capinfos.adoc) | 26 | ||||
| -rw-r--r-- | doc/man_pages/captype.adoc (renamed from doc/captype.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/ciscodump.adoc (renamed from doc/ciscodump.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/diagnostic-options.adoc (renamed from doc/diagnostic-options.adoc) | 0 | ||||
| -rw-r--r-- | doc/man_pages/dissection-options.adoc (renamed from doc/dissection-options.adoc) | 3 | ||||
| -rw-r--r-- | doc/man_pages/dpauxmon.adoc (renamed from doc/dpauxmon.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/dumpcap.adoc (renamed from doc/dumpcap.adoc) | 49 | ||||
| -rw-r--r-- | doc/man_pages/editcap.adoc (renamed from doc/editcap.adoc) | 44 | ||||
| -rw-r--r-- | doc/man_pages/etwdump.adoc (renamed from doc/etwdump.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/extcap.adoc (renamed from doc/extcap.adoc) | 8 | ||||
| -rw-r--r-- | doc/man_pages/falcodump.adoc | 231 | ||||
| -rw-r--r-- | doc/man_pages/files.adoc | 458 | ||||
| -rw-r--r-- | doc/man_pages/idl2deb.adoc (renamed from doc/idl2deb.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/idl2wrs.adoc (renamed from doc/idl2wrs.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/mergecap.adoc (renamed from doc/mergecap.adoc) | 15 | ||||
| -rw-r--r-- | doc/man_pages/mmdbresolve.adoc (renamed from doc/mmdbresolve.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/randpkt.adoc (renamed from doc/randpkt.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/randpktdump.adoc (renamed from doc/randpktdump.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/rawshark.adoc (renamed from doc/rawshark.adoc) | 219 | ||||
| -rw-r--r-- | doc/man_pages/reordercap.adoc (renamed from doc/reordercap.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/sdjournal.adoc (renamed from doc/sdjournal.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/sshdump.adoc (renamed from doc/sshdump.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/text2pcap.adoc (renamed from doc/text2pcap.adoc) | 34 | ||||
| -rw-r--r-- | doc/man_pages/tshark.adoc (renamed from doc/tshark.adoc) | 345 | ||||
| -rw-r--r-- | doc/man_pages/udpdump.adoc (renamed from doc/udpdump.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/wifidump.adoc (renamed from doc/wifidump.adoc) | 4 | ||||
| -rw-r--r-- | doc/man_pages/wireshark-filter.adoc (renamed from doc/wireshark-filter.adoc) | 131 | ||||
| -rw-r--r-- | doc/man_pages/wireshark.adoc | 1099 |
30 files changed, 2194 insertions, 532 deletions
diff --git a/doc/androiddump.adoc b/doc/man_pages/androiddump.adoc index d68a3a3a..21f5f79b 100644 --- a/doc/androiddump.adoc +++ b/doc/man_pages/androiddump.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = androiddump(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/asn2deb.adoc b/doc/man_pages/asn2deb.adoc index db976522..e02844cc 100644 --- a/doc/asn2deb.adoc +++ b/doc/man_pages/asn2deb.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = asn2deb(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/capinfos.adoc b/doc/man_pages/capinfos.adoc index 4dec8136..c609ab72 100644 --- a/doc/capinfos.adoc +++ b/doc/man_pages/capinfos.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = capinfos(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME @@ -93,11 +93,10 @@ the same way *Capinfos* handles this. == OPTIONS -a:: -Displays the start time of the capture. *Capinfos* considers -the earliest timestamp seen to be the start time, so the -first packet in the capture is not necessarily the earliest - -if packets exist "out-of-order", time-wise, in the capture, -*Capinfos* detects this. +Displays the timestamp of the earliest packet in the capture. The +earliest packet in the capture is not necessarily the first packet in +the capture - if packets exist "out-of-order", time-wise, in the +capture, *Capinfos* detects this. -A:: Generate all infos. By default *Capinfos* will display @@ -162,11 +161,10 @@ Displays a count of the number of decryption secrets in the file. This informati is not available in table format. -e:: -Displays the end time of the capture. *Capinfos* considers -the latest timestamp seen to be the end time, so the -last packet in the capture is not necessarily the latest - -if packets exist "out-of-order", time-wise, in the capture, -*Capinfos* detects this. +Displays the timestamp of the latest packet in the capture. The latest +packet in the capture is not necessarily the last packet in the capture +- if packets exist "out-of-order", time-wise, in the capture, *Capinfos* +detects this. -E:: Displays the per-file encapsulation of the capture file. @@ -285,8 +283,8 @@ Displays the size of the file, in bytes. This reports the size of the capture file itself. -S:: -Display the start and end times as seconds since January -1, 1970. Handy for synchronizing dumps using *editcap -t*. +Display the earliest and latest packet timestamps as seconds since +January 1, 1970. Handy for synchronizing dumps using *editcap -t*. -t:: Displays the capture type of the capture file. diff --git a/doc/captype.adoc b/doc/man_pages/captype.adoc index 11eb6bf0..94c07274 100644 --- a/doc/captype.adoc +++ b/doc/man_pages/captype.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = captype(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/ciscodump.adoc b/doc/man_pages/ciscodump.adoc index b721b284..10ce4b69 100644 --- a/doc/ciscodump.adoc +++ b/doc/man_pages/ciscodump.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = ciscodump(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/diagnostic-options.adoc b/doc/man_pages/diagnostic-options.adoc index 1500168f..1500168f 100644 --- a/doc/diagnostic-options.adoc +++ b/doc/man_pages/diagnostic-options.adoc diff --git a/doc/dissection-options.adoc b/doc/man_pages/dissection-options.adoc index 5c55a763..f46a06af 100644 --- a/doc/dissection-options.adoc +++ b/doc/man_pages/dissection-options.adoc @@ -111,6 +111,9 @@ MaxMind databases *N* to enable using external resolvers (e.g., DNS) for network address resolution; no effect without *n* also enabled. +*s* to enable address resolution using SNI information found in captured +handshake packets + *t* to enable transport-layer port number resolution *v* to enable VLAN IDs to names resolution diff --git a/doc/dpauxmon.adoc b/doc/man_pages/dpauxmon.adoc index cf98cecb..9d2a9e5c 100644 --- a/doc/dpauxmon.adoc +++ b/doc/man_pages/dpauxmon.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = dpauxmon(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/dumpcap.adoc b/doc/man_pages/dumpcap.adoc index a9998d2a..9fdcf72c 100644 --- a/doc/dumpcap.adoc +++ b/doc/man_pages/dumpcap.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = dumpcap(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME @@ -21,6 +21,7 @@ dumpcap - Dump network traffic [ *-d* ] [ *-D*|*--list-interfaces* ] [ *-f* <capture filter> ] +[ *-F* <file format> ] [ *-g* ] [ *-i*|*--interface* <capture interface>|rpcap://<host>:<port>/<capture interface>|TCP@<host>:<port>|- ] [ *-I*|*--monitor-mode* ] @@ -34,6 +35,7 @@ dumpcap - Dump network traffic [ *--ifname* <name> ] [ *-P* ] [ *-q* ] +[ *-Q* ] [ *-s*|*--snapshot-length* <capture snaplen> ] [ *-S* ] [ *-t* ] @@ -57,9 +59,8 @@ dumpcap - Dump network traffic *Dumpcap* is a network traffic dump tool. It lets you capture packet data from a live network and write the packets to a file. *Dumpcap*'s -default capture file format is *pcapng* format. -When the *-P* option is specified, the output file is written in the -*pcap* format. +default capture file format is *pcapng* format. The *-F* option can +be specified to write the output file in the *pcap* format instead. Without any options set it will use the libpcap, Npcap, or WinPcap library to capture traffic from the first available network interface and writes @@ -92,7 +93,7 @@ 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, dumpcap will stop writing to the current capture file and switch to the next one if filesize -is reached. Note that the filesize is limited to a maximum value of 2 GiB. +is reached. Note that the filesize is limited to a maximum value of 2 TB. *packets*:__value__ Stop writing to a capture file after __value__ packets have been written. Acts the same as *-c* <capture packet count>. @@ -134,7 +135,7 @@ 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. *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 @@ -214,6 +215,17 @@ this option. If the capture filter expression is not set specifically, the default capture filter expression is used if provided. -- +-F <file format>:: +Set the file format of the output capture file written using the *-w* +option. In situations that require the *pcapng* format, such as capturing +from multiple interfaces, this option will be overridden. The option *-F* +without a value will list the available formats. The default is the +*pcapng* format. + +Fewer formats are supported than by xref:tshark.html[tshark](1); this is +intentional for security reasons. Use *tshark* or capture and then convert +the file with xref:editcap.html[editcap](1) if another format is needed. + -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 @@ -320,7 +332,8 @@ The machine-readable output is intended to be read by *Wireshark* and -- -n:: -Save files as pcapng. This is the default. +Save files as pcapng. This is the default. This option is deprecated +and may be removed. -N <packet limit>:: + @@ -352,7 +365,8 @@ promiscuous mode. -P:: Save files as pcap instead of the default pcapng. In situations that require pcapng, such as capturing from multiple interfaces, this option will be -overridden. +overridden. This option is deprecated in favor of the *-F* option and +may be removed. -q:: + @@ -367,6 +381,23 @@ might be set to "disabled" by default on at least some BSDs, so you'd have to explicitly set it to use it). -- +-Q:: ++ +-- +When capturing packets, don't display, on the standard error, the initial +message indicating on what interfaces the capture is being done, the +messages indicating to what file a capture is being written, the continuous +count of packets captured that is normally shown when saving a capture to +a file, and the message at the end of the capture giving a count of packets +captured. This outputs less than the *-q* option; only true errors are +displayed on the standard error. + +On systems that support the SIGINFO signal, such as various BSDs, you can +cause the current count to be displayed by typing your "status" character +(typically control-T, although it might be set to "disabled" by default on +at least some BSDs, so you'd have to explicitly set it to use it). +-- + -s|--snapshot-length <capture snaplen>:: + -- diff --git a/doc/editcap.adoc b/doc/man_pages/editcap.adoc index 20fadc1a..5b4be3fc 100644 --- a/doc/editcap.adoc +++ b/doc/man_pages/editcap.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = editcap(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME @@ -52,6 +52,13 @@ __outfile__ [manarg] *editcap* +*--extract-secrets* +[ *-V* ] +__infile__ +__outfile__ + +[manarg] +*editcap* *-h|--help* [manarg] @@ -97,6 +104,13 @@ the same way *Editcap* handles this. *Editcap* can write the file in several output formats. The *-F* flag can be used to specify the format in which to write the capture file; *editcap -F* provides a list of the available output formats. +*Editcap* can also compress the output file. The *--compress* option +can specify the compression type. If that option is not given, then the desired +compression method, if any, is deduced from the extension of __outfile__; +e.g., if the output filename has the .gz extension, then the gzip format is used. + +*Editcap* can also be used to extract embedded decryption secrets from file +formats like *pcapng* that contain them, in lieu of writing a capture file. == OPTIONS @@ -452,13 +466,27 @@ additional configuration in protocol preferences. The file format is described by <secrets type> which can be one of: -__tls__ TLS Key Log as described at https://developer.mozilla.org/NSS_Key_Log_Format + -__wg__ WireGuard Key Log, see https://gitlab.com/wireshark/wireshark/-/wikis/WireGuard#key-log-format +__opcua__ OPC UA Key Log, see https://ietf-opsawg-wg.github.io/draft-ietf-opsawg-pcap/draft-ietf-opsawg-pcapng.html#name-decryption-secrets-block + +__ssh__ SSH Key Log, see {wireshark-wiki-url}SSH#key-log-format + +__tls__ TLS Key Log, see https://tlswg.org/sslkeylogfile/draft-ietf-tls-keylogfile.html + +__wg__ WireGuard Key Log, see {wireshark-wiki-url}WireGuard#key-log-format This option may be specified multiple times. The available options for <secrets type> can be listed with *--inject-secrets help*. -- +--extract-secrets:: ++ +-- +Extracts each Decryption Secrets Block (DSB) contained within __infile__. +If there is only one, it is written to __outfile__ instead of a capture file. +If there is more than one, they are each written to unique output files named +with an infix _nnnnn before the file extension of __outfile__ in a manner +similar to the *-c* flag (unless writing to standard output.) + +Incompatible with other options except for *-V*. + +-- --discard-all-secrets:: + -- @@ -502,6 +530,14 @@ file. Does not discard comments added by *-a* in the same command line. -- +--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__. +-- + include::diagnostic-options.adoc[] == EXAMPLES diff --git a/doc/etwdump.adoc b/doc/man_pages/etwdump.adoc index b1070d38..f9df8ac6 100644 --- a/doc/etwdump.adoc +++ b/doc/man_pages/etwdump.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = etwdump(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/extcap.adoc b/doc/man_pages/extcap.adoc index 511a59cc..ce8ae933 100644 --- a/doc/extcap.adoc +++ b/doc/man_pages/extcap.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = extcap(4) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME @@ -29,8 +29,8 @@ The extcap subsystem is made of multiple extcap binaries that are automatically called by the GUI in a row. In the following chapters we will refer to them as "the extcaps". -Extcaps may be any binary or script within the extcap directory. Please note, that scripts -need to be executable without prefacing a script interpreter before the call. +Extcaps may be any binary or script within the _extcap/wireshark_ or _extcap/logray_ directories. +Please note that scripts need to be executable without prefacing a script interpreter before the call. WINDOWS USERS: Because of restrictions directly calling the script may not always work. In such a case, a batch file may be provided, which then in turn executes the script. Please diff --git a/doc/man_pages/falcodump.adoc b/doc/man_pages/falcodump.adoc new file mode 100644 index 00000000..9e5b94f0 --- /dev/null +++ b/doc/man_pages/falcodump.adoc @@ -0,0 +1,231 @@ +include::../attributes.adoc[] += falcodump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +falcodump - Dump log data to a file using a Falco source plugin. + +== SYNOPSIS + +.Common options +[manarg] +*falcodump* +[ *--help* ] +[ *--version* ] +[ *--plugin-api-version* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--extcap-capture-filter*=<capture filter> ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--plugin-source*=<source path or URL> ] +[ *--log-level*=<log level> ] +[ *--log-file*=<path to file> ] + +.System call options +[manarg] +[ *--include-capture-processes=<TRUE or FALSE> ] +[ *--include-switch-calls=<TRUE or FALSE> ] + + +.CloudTrail plugin options +[manarg] +[ *--cloudtrail-s3downloadconcurrency*=<number of concurrent downloads> ] +[ *--cloudtrail-s3interval*=<timeframe> ] +[ *--cloudtrail-s3accountlist*=<comma separated account IDs> ] +[ *--cloudtrail-sqsdelete*=<true or false> ] +[ *--cloudtrail-useasync*=<true or false> ] +[ *--cloudtrail-uses3sns*=<true or false> ] +[ *--cloudtrail-aws-region*=<AWS region> ] +[ *--cloudtrail-aws-profile*=<AWS profile> ] +[ *--cloudtrail-aws-config*=<path> ] +[ *--cloudtrail-aws-credentials*=<path to file> ] + + +== DESCRIPTION + +*falcodump* is an extcap tool that allows one to capture log messages from cloud providers. + +Each plugin is listed as a separate interface. +For example, the AWS CloudTrail plugin is listed as “cloudtrail”. + +== OPTIONS + +--help:: +Print program arguments. +This will also list the configuration arguments for each plugin. + +--version:: +Print the program version. + +--plugin-api-version:: +Print the Falco plugin API version. + +--extcap-interfaces:: +List the available interfaces. + +--extcap-interface=<interface>:: +Use the specified interface. + +--extcap-dlts:: +List the DLTs of the specified interface. + +--extcap-config:: +List the configuration options of specified interface. + +--extcap-capture-filter=<capture filter>:: +The capture filter. +Must be a valid Sysdig / Falco filter. + +--capture:: +Start capturing from the source specified by --plugin-source via the specified interface and write raw packet data to the location specified by --fifo. + +--fifo=<path to file or pipe>:: +Save captured packet to file or send it through pipe. + +--plugin-source=<source path or URL>:: +Capture from the specified location. + +--log-level:: +Set the log level + +--log-file:: +Set a log file to log messages in addition to the console + +== SYSTEM CALL OPTIONS + +--include-capture-processes:: +Include system calls for capture processes (falcodump, dumpcap, and Logray) if TRUE. +Defaults to FALSE. + +--include-switch-calls:: +Include "switch" calls if TRUE. +Defaults to FALSE. + + +== PLUGINS + +=== cloudtrail (AWS CloudTrail) + +--cloudtrail-s3downloadconcurrency:: +Controls the number of background goroutines used to download S3 files (Default: 32) + +--cloudtrail-s3interval:: +Download log files over the specified interval (Default: no interval) + +--cloudtrail-s3accountlist:: +If source is an organization CloudTrail S3 bucket download log files for all specified account IDs (Default: no account IDs) + +--cloudtrail-sqsdelete:: +If true then the plugin will delete SQS messages from the queue immediately after receiving them (Default: true) + +--cloudtrail-useasync:: +If true then async extraction optimization is enabled (Default: true) + +--cloudtrail-uses3sns:: +If true then the plugin will expect SNS messages to originate from S3 instead of directly from Cloudtrail (Default: false) + +--cloudtrail-aws-profile:: +If non-empty overrides the AWS shared configuration profile (e.g. 'default') and environment variables such as AWS_PROFILE (Default: empty) + +--cloudtrail-aws-region:: +If non-empty overrides the AWS region specified in the profile (e.g. 'us-east-1') and environment variables such as AWS_REGION (Default: empty) + +--cloudtrail-aws-config:: +If non-empty overrides the AWS shared configuration filepath (e.g. ~/.aws/config) and env variables such as AWS_CONFIG_FILE (Default: empty) + +--cloudtrail-aws-credentials:: +If non-empty overrides the AWS shared credentials filepath (e.g. ~/.aws/credentials) and env variables such as AWS_SHARED_CREDENTIALS_FILE (Default: empty) + +CloudTrail sources can be S3 buckets or SQS queue URLs. S3 bucket URLs have the form + +'s3://__bucket_name__/__prefix__/AWSLogs/__account-id__/CloudTrail/__region__/__year__/__month__/__day__' + +For organization CloudTrail the S3 bucket URL can be + +'s3://__bucket_name__/__prefix__/AWSLogs/__org-id__/__account-id__/CloudTrail/__region__/__year__/__month__/__day__' + +The __region__, __year__, __month__, and __day__ components can be omitted in order to fetch more or less data. +For example, the source 's3://mybucket/AWSLogs/012345678/CloudTrail/us-west-2/2023' will fetch all CloudWatch logs for the year 2023. + +If the URL ends with '__account-id__/' or '__account-id__/CloudTrail/' (for example 's3://mybucket/AWSLOGS/012345678912/') the option '--cloudtrail-s3interval' can be used to define the time frame. A s3interval of '1d' for example would get all events of the last 24 hours from all available regions. A s3interval of '2w-1w' would get all events from all regions from two weeks ago up to one week ago. The s3invterval can also be defined as a RFC 3339-style timestamp like '2024-02-29T18:07:17Z' or '2024-02-29T00:00:00Z-2024-03-01T23:59:59Z'. + +If the URL ends with 'AWSLogs/__org-id__' option '--cloudtrail-s3accountlist' can be used to specify account IDs. This can be combined with '--cloudtrail-s3interval'. A source like 's3://my-org-bucket/AWSLogs/o-123abc/' with '--cloudstrail-s3accountlist' set to '123456789012,987654321098' and '--cloudtrail-s3interval' set to '30m' would get all events of the last 30min from all regions for accounts 123456789012 and 987654321098. + +If source URL is the organization CloudTrail bucket (like 's3://my-org-bucket/AWSLogs/o-123abc') and '--s3accountlist' is not set the plugin iterates over all accounts (limited by '--s3interval' if set). Attention: Depending on the size of the organization and the time interval, this can take a long time. + +The cloudtrail plugin uses the AWS SDK for Go, which can obtain profile, region, and credential settings from a set of standard https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/[environment variables and configuration files]. +Falcodump will show a list of locally configured profiles and the current regions, and will let you supply a custom value as well. + +More information is available in the https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md[README] of the CloudTrail plugin. + +== EXAMPLES + +To see program arguments: + + falcodump --help + +To see program version: + + falcodump --version + +To see interfaces: + + falcodump --extcap-interfaces + +Only one interface (falcodump) is supported. + +.Example output + interface {value=cloudtrail}{display=Falco plugin} + +To see interface DLTs: + + falcodump --extcap-interface=cloudtrail --extcap-dlts + +.Example output + dlt {number=147}{name=cloudtrail}{display=USER0} + +To see interface configuration options: + + falcodump --extcap-interface=cloudtrail --extcap-config + +.Example output + arg {number=0}{call=--plugin-source}{display=Plugin source}{type=string}{tooltip=The plugin data source. This us usually a URL.}{placeholder=Enter a source URL…}{required=true}{group=Capture} + arg {number=1}{call=cloudtrail-s3downloadconcurrency}{display=s3DownloadConcurrency}{type=integer}{default=1}{tooltip=Controls the number of background goroutines used to download S3 files (Default: 1)}{group=Capture} + arg {number=2}{call=cloudtrail-sqsdelete}{display=sqsDelete}{type=boolean}{default=true}{tooltip=If true then the plugin will delete sqs messages from the queue immediately after receiving them (Default: true)}{group=Capture} + arg {number=3}{call=cloudtrail-useasync}{display=useAsync}{type=boolean}{default=true}{tooltip=If true then async extraction optimization is enabled (Default: true)}{group=Capture} + +To capture AWS CloudTrail events from an S3 bucket: + + falcodump --extcap-interface=cloudtrail --fifo=/tmp/cloudtrail.pcap --plugin-source=s3://aws-cloudtrail-logs.../CloudTrail/us-east-2/... --capture + +or: + + falcodump --capture --extcap-interface cloudtrail --fifo ~/cloudtrail.pcap --plugin-source s3://my-cloudtrail-bucket/AWSLogs/o-abc12345/123456789012/ --cloudtrail-s3downloadconcurrency 32 --cloudtrail-s3interval 5d-2d --cloudtrail-aws-region eu-west-1 + +NOTE: kbd:[CTRL+C] should be used to stop the capture in order to ensure clean termination. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4) +//, xref:logray.html[logray](1) + +== NOTES + +*falcodump* is part of the *Logray* distribution. +The latest version of *Logray* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Gerald Combs <gerald[AT]wireshark.org> diff --git a/doc/man_pages/files.adoc b/doc/man_pages/files.adoc new file mode 100644 index 00000000..9653ff27 --- /dev/null +++ b/doc/man_pages/files.adoc @@ -0,0 +1,458 @@ +== FILES + +These files contain various *Wireshark* configuration settings. + +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 flag *-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: + + # Vertical scrollbars should be on right side? + # TRUE or FALSE (case-insensitive). + gui.scrollbar_on_right: 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__). + +// tag::gui[] +Note: Whenever the preferences are saved by using the __Save__ button +in the __Edit:Preferences__ dialog box, your personal preferences file +will be overwritten with the new settings, destroying any comments and +unknown/obsolete settings that were in the file. +// end::gui[] +-- + +// tag::gui[] +Recent:: ++ +-- +The __recent__ file contains personal settings (mostly GUI related) such +as the current *Wireshark* window size. The file is saved at program exit and +read in at program start automatically. Note: The command line flag *-o* +may be used to override settings from this file. + +The settings in this file have the same format as in the __preferences__ +files, and the same directory as for the personal preferences file is +used. + +Note: Whenever Wireshark is closed, your recent file +will be overwritten with the new settings, destroying any comments and +unknown/obsolete settings that were in the file. +-- +// end::gui[] + +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 + +If a protocol is listed in the global __disabled_protos__ file it cannot +be enabled by the user. +// tag::gui[] +Thus it is not displayed in the __Analyze::Enabled Protocols__ dialog box. +// end::gui[] + +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. + +The __disabled_protos__ files list only protocols that are enabled by default +but have been disabled; protocols that are disabled by default (such as some +postdissectors) are not listed. There are analogous __enabled_protos__ files +for protocols that are disabled by default but have been enabled. + +// tag::gui[] +Note: Whenever the disabled protocols list is saved by using the __Save__ +button in the __Analyze:Enabled Protocols__ dialog box, your personal +disabled protocols file will be overwritten with the new settings, +destroying any comments that were in the file. +// end::gui[] +-- + +Heuristic Dissectors:: ++ +-- +The __heuristic_protos__ files contain system-wide and personal lists of +heuristic dissectors and indicate whether they are enabled or disabled. +The files contain heuristic dissector unique short names, one per line, +followed by a comma and 0 for disabled and 1 for enabled: + + quic,1 + rtcp_stun,1 + rtcp_udp,1 + rtp_stun,0 + rtp_udp,0 + tls_tcp,1 + +The global __heuristic_protos__ file uses the same directory as the global +preferences file. + +The personal __heuristic_protos__ file uses the same directory as the +personal preferences file. + +// The global heuristic_protos doesn't have the "set_cant_toggle" +// features that the enabled_protos and disabled_protos files do. +-- + +Name Resolution (hosts):: ++ +-- +Entries in __hosts__ files in the global and personal preferences +directory are 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 personal __hosts__ +file, if present, overrides the one in the global directory. + +Capture filter name resolution is handled by libpcap on UNIX-compatible +systems, such as Linux, macOS, \*BSD, Solaris, and AIX, and 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. +Both the global __subnets__ file and personal __subnets__ files are used +if they exist. + +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 similar the __ethers__ files, except that entries such as: + + 00:00:0C Cisco Cisco Systems, Inc + +can be provided, with the 3-byte OUI and both an abbreviated and long 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. + +A global __manuf__ file is looked for in the same directory as the global +preferences file, and a personal __manuf__ file is looked for in the same +directory as the personal preferences file. + +In earlier versions of Wireshark, official information from the IEEE +Registration Authority was distributed in this format as the global +__manuf__ file. This information is now compiled in to speed program +startup, but the internal information can be written out in this format +with *tshark -G manuf*. + +In addition to the __manuf__ file, another file with the same format, +__wka__, is looked for in the global directory. This file is distributed +with Wireshark, and contains data about well-known MAC adddresses and +address ranges assembled from various non IEEE but respected sources. +-- + +Name Resolution (services):: ++ +-- +The __services__ file is used to translate port numbers into names. +Both the global __services__ file and personal __services__ files are used +if they exist. + +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 + +In earlier versions of Wireshark, official information from the IANA +Registry was distributed in this format as the global __services__ file. +This information is now compiled in to speed program startup, but the +internal information can be written out in this format with *tshark -G services*. +-- + +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. +-- + +Name Resolution (ss7pcs):: ++ +-- +The __ss7pcs__ file is used to translate SS7 point codes to names. +It is read from the personal configuration directory. + +Each line in this file consists of one network indicator followed by a dash +followed by a point code in decimal and a node name separated by whitespace. +An example is: + + 2-1234 MyPointCode1 + +-- + +Name Resolution (vlans):: ++ +-- +The __vlans__ file is used to translate VLAN tag IDs into names. +It is read from the personal configuration directory. + +Each line in this file consists of one VLAN tag ID separated by whitespace +from a name. An example is: + + 123 Server-Lan + 2049 HR-Client-LAN + +-- + +// tag::gui[] +Capture Filters:: ++ +-- +The __cfilters__ files contain system-wide and personal capture filters. +Each line contains one filter, starting with the string displayed in the +dialog box in quotation marks, followed by the filter string itself: + + "HTTP" port 80 + "DCERPC" port 135 + +The global __cfilters__ file uses the same directory as the +global preferences file. + +The personal __cfilters__ file uses the same directory as the personal +preferences file. It is written through the Capture:Capture Filters +dialog. + +If the global __cfilters__ file exists, it is used only if the personal +__cfilters__ file does not exist; global and personal capture filters are +not merged. +-- + +Display Filters:: ++ +-- +The __dfilters__ files contain system-wide and personal display filters. +Each line contains one filter, starting with the string displayed in the +dialog box in quotation marks, followed by the filter string itself: + + "HTTP" http + "DCERPC" dcerpc + +The global __dfilters__ file uses the same directory as the +global preferences file. + +The personal __dfilters__ file uses the same directory as the +personal preferences file. It is written through the Analyze:Display +Filters dialog. + +If the global __dfilters__ file exists, it is used only if the personal +__dfilters__ file does not exist; global and personal display filters are +not merged. +-- + +Display Filter Macros:: ++ +-- +The __dmacros__ files contain system-wide and personal display filter macros. +Each line contains one filter, starting with the string displayed in the +dialog box in quotation marks, followed by the macro expression itself: + + "private_ipv6" ipv6 && $1 == fc00::/7 + "private_ethernet" $1[0] & 0x0F == 2 + "private_ipv4" $1 == 192.168.0.0/16 or $1 == 172.16.0.0/12 or $1 == 10.0.0.0/8 + +The global __dmacros__ file uses the same directory as the +global preferences file. + +The personal __dmacros__ file uses the same directory as the +personal preferences file. It is written through the Analyze:Display +Filter Macros dialog. + +If the global __dmacros__ file exists, it is used only if the personal +__dmacros__ file does not exist; global and personal display filters are +not merged. + +Prior to Wireshark 4.4, a __dfilter_macros__ file with a somewhat different +syntax was used. That file is looked for at startup if a __dmacros__ file is +not found and used to migrate to the new format. +-- +// end::gui[] + +Color Filters (Coloring Rules):: ++ +-- +The __colorfilters__ files contain system-wide and personal color filters. +Each line contains one filter, starting with the string displayed in the +dialog box, followed by the corresponding display filter. Then the +background and foreground colors are appended: + + # a comment + @tcp@tcp@[59345,58980,65534][0,0,0] + @udp@udp@[28834,57427,65533][0,0,0] + +The global __colorfilters__ file uses the same directory as the +global preferences file. + +The personal __colorfilters__ file uses the same directory as the +personal preferences file. It is written through the View:Coloring Rules +dialog. + +If the global __colorfilters__ file exists, it is used only if the personal +__colorfilters__ file does not exist; global and personal color filters are +not merged. +-- + +Plugins:: ++ +-- +Wireshark looks for plugins in both a personal plugin folder and a +global plugin folder. + +On UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and +AIX, the global plugin directory is __lib/wireshark/plugins/__ (on +some systems substitute __lib64__ for __lib__) under the main installation +directory (for example, __/usr/local/lib/wireshark/plugins/__). The personal +plugin directory is __$HOME/.local/lib/wireshark/plugins__. + +On macOS, if Wireshark is installed as an application bundle, the global plugin +folder is instead __%APPDIR%/Contents/PlugIns/wireshark__. + +On Windows, the global plugin folder is __plugins/__ under the main +installation directory (for example, __C:\Program Files\Wireshark\plugins\__). +The personal plugin folder is __%APPDATA%\Wireshark\plugins__ (or, if +%APPDATA% isn't defined, __%USERPROFILE%\Application Data\Wireshark\plugins__). + +Lua plugins are stored in the plugin folders; +compiled plugins are stored in subfolders of the plugin folders, with +the subfolder name being the Wireshark minor version number (X.Y). There is +another hierarchical level for each Wireshark plugin type (libwireshark, +libwiretap and codecs). For example, the location for a libwireshark plugin +_foo.so_ (_foo.dll_ on Windows) would be _PLUGINDIR/X.Y/epan_ +(libwireshark used to be called libepan; the other folder names are _codecs_ +and _wiretap_). + +NOTE: On UNIX-compatible systems, Lua plugins (but not binary plugins) may also +be placed in __$XDG_CONFIG_HOME/wireshark/plugins__, +(or, if __$XDG_CONFIG_HOME/wireshark__ does not exist while __$HOME/.wireshark__ +does exist, __$HOME/.wireshark/plugins__.) + +Note that a dissector plugin module may support more than one protocol; +there is not necessarily a one-to-one correspondence between dissector plugin +modules and protocols. Protocols supported by a dissector plugin module are +enabled and disabled in the same way as protocols built into Wireshark. +-- diff --git a/doc/idl2deb.adoc b/doc/man_pages/idl2deb.adoc index 146672fd..f622fdf9 100644 --- a/doc/idl2deb.adoc +++ b/doc/man_pages/idl2deb.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = idl2deb(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/idl2wrs.adoc b/doc/man_pages/idl2wrs.adoc index c046c536..605f441a 100644 --- a/doc/idl2wrs.adoc +++ b/doc/man_pages/idl2wrs.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = idl2wrs(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/mergecap.adoc b/doc/man_pages/mergecap.adoc index a5c9a6c3..43412375 100644 --- a/doc/mergecap.adoc +++ b/doc/man_pages/mergecap.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = mergecap(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME @@ -145,8 +145,19 @@ Causes *mergecap* to print a number of messages while it's working. -w <outfile>|-:: Sets the output filename. If the name is '*-*', stdout will be used. +If the *--compress* option is not given, then the filename extension is +used to deduce the desired compression method, if any; e.g., if the name has +the extension '.gz', then the output file is compressed to a gzip archive. This setting is mandatory. +--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__. +-- + include::diagnostic-options.adoc[] == EXAMPLES diff --git a/doc/mmdbresolve.adoc b/doc/man_pages/mmdbresolve.adoc index 4b880401..af66d6b4 100644 --- a/doc/mmdbresolve.adoc +++ b/doc/man_pages/mmdbresolve.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = mmdbresolve(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/randpkt.adoc b/doc/man_pages/randpkt.adoc index 97104b70..a9b799a5 100644 --- a/doc/randpkt.adoc +++ b/doc/man_pages/randpkt.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = randpkt(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/randpktdump.adoc b/doc/man_pages/randpktdump.adoc index 3e13a77f..8862b108 100644 --- a/doc/randpktdump.adoc +++ b/doc/man_pages/randpktdump.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = randpktdump(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/rawshark.adoc b/doc/man_pages/rawshark.adoc index a52e594a..5b52f034 100644 --- a/doc/rawshark.adoc +++ b/doc/man_pages/rawshark.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = rawshark(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME @@ -196,11 +196,12 @@ should not close rawshark's standard input handle prematurely, otherwise the C runtime might trigger an exception. -- --R <read (display) filter>:: +-R|--read-filter <read (display) filter>:: + -- Cause the specified filter (which uses the syntax of read/display filters, rather than that of capture filters) to be applied before printing the output. +Read filters and display filters are synonymous in *rawshark*. -- -s:: @@ -226,216 +227,24 @@ could use *%D: %S (%N)*. -v|--version:: Print the full version information and exit. -include::dissection-options.adoc[tags=**;!tshark;!decode_as] - -include::diagnostic-options.adoc[] - -== READ FILTER SYNTAX - -For a complete table of protocol and protocol fields that are filterable -in *TShark* see the xref:wireshark-filter.html[wireshark-filter](4) manual page. - -== FILES - -These files contains various *Wireshark* configuration values. - -Preferences:: -+ --- -The __preferences__ files contain global (system-wide) and personal -preference settings. If the system-wide preference file exists, it is -read first, overriding the default settings. If the personal preferences -file exists, it is read next, overriding any previous values. Note: If -the command line option *-o* is used (possibly more than once), it will -in turn override values from the preferences files. - -The preferences settings are in the form __prefname:value__, -one per line, -where __prefname__ is the name of the preference -and __value__ is the value to -which it should be set; white space is allowed between *:* and -__value__. A preference setting can be continued on subsequent lines by -indenting the continuation lines with white space. A *#* character -starts a comment that runs to the end of the line: - - # Capture in promiscuous mode? - # TRUE or FALSE (case-insensitive). - capture.prom_mode: TRUE - -The global preferences file is looked for in the __wireshark__ directory -under the __share__ subdirectory of the main installation directory. On -macOS, this would typically be -__/Application/Wireshark.app/Contents/Resources/share__; on other -UNIX-compatible systems, such as Linux, \*BSD, Solaris, and AIX, this -would typically be __/usr/share/wireshark/preferences__ for -system-installed packages and __/usr/local/share/wireshark/preferences__ -for locally-installed packages; on Windows, this would typically be -__C:\Program Files\Wireshark\preferences__. - -On UNIX-compatible systems, the personal preferences file is looked for -in __$XDG_CONFIG_HOME/wireshark/preferences__, (or, if -__$XDG_CONFIG_HOME/wireshark__ does not exist while __$HOME/.wireshark__ -does exist, __$HOME/.wireshark/preferences__); this is typically -__$HOME/.config/wireshark/preferences__. On Windows, -the personal preferences file is looked for in -__%APPDATA%\Wireshark\preferences__ (or, if %APPDATA% isn't defined, -__%USERPROFILE%\Application Data\Wireshark\preferences__). --- - -Disabled (Enabled) Protocols:: -+ --- -The __disabled_protos__ files contain system-wide and personal lists of -protocols that have been disabled, so that their dissectors are never -called. The files contain protocol names, one per line, where the -protocol name is the same name that would be used in a display filter -for the protocol: - - http - tcp # a comment - -The global __disabled_protos__ file uses the same directory as the global -preferences file. - -The personal __disabled_protos__ file uses the same directory as the -personal preferences file. --- - -Name Resolution (hosts):: -+ --- -If the personal __hosts__ file exists, it is -used to resolve IPv4 and IPv6 addresses before any other -attempts are made to resolve them. The file has the standard __hosts__ -file syntax; each line contains one IP address and name, separated by -whitespace. The same directory as for the personal preferences file is -used. - -Capture filter name resolution is handled by libpcap on UNIX-compatible -systems, such as Linux, macOS, \*BSD, Solaris, and AIX, and by Npcap or -WinPcap on Windows. As such the Wireshark personal __hosts__ file will -not be consulted for capture filter name resolution. --- - -Name Resolution (subnets):: -+ --- -If an IPv4 address cannot be translated via name resolution (no exact -match is found) then a partial match is attempted via the __subnets__ file. - -Each line of this file consists of an IPv4 address, a subnet mask length -separated only by a / and a name separated by whitespace. While the address -must be a full IPv4 address, any values beyond the mask length are subsequently -ignored. - -An example is: - -# Comments must be prepended by the # sign! -192.168.0.0/24 ws_test_network - -A partially matched name will be printed as "subnet-name.remaining-address". -For example, "192.168.0.1" under the subnet above would be printed as -"ws_test_network.1"; if the mask length above had been 16 rather than 24, the -printed address would be ``ws_test_network.0.1". --- - -Name Resolution (ethers):: -+ --- -The __ethers__ files are consulted to correlate 6-byte hardware addresses to -names. First the personal __ethers__ file is tried and if an address is not -found there the global __ethers__ file is tried next. - -Each line contains one hardware address and name, separated by -whitespace. The digits of the hardware address are separated by colons -(:), dashes (-) or periods (.). The same separator character must be -used consistently in an address. The following three lines are valid -lines of an __ethers__ file: - - ff:ff:ff:ff:ff:ff Broadcast - c0-00-ff-ff-ff-ff TR_broadcast - 00.00.00.00.00.00 Zero_broadcast - -The global __ethers__ file is looked for in the __/etc__ directory on -UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX, -and in the main installation directory (for example, __C:\Program -Files\Wireshark__) on Windows systems. - -The personal __ethers__ file is looked for in the same directory as the personal -preferences file. - -Capture filter name resolution is handled by libpcap on UNIX-compatible -systems and Npcap or WinPcap on Windows. As such the Wireshark personal -__ethers__ file will not be consulted for capture filter name resolution. --- - -Name Resolution (manuf):: +-Y|--display-filter <read (display) filter>:: + -- -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 +Cause the specified filter (which uses the syntax of read/display filters, +rather than that of capture filters) to be applied before printing the output. +Read filters and display filters are synonymous in *rawshark*. -- -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. +include::dissection-options.adoc[tags=**;!tshark;!decode_as] -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: +include::diagnostic-options.adoc[] - C0.A8.2C.00 HR - c0-a8-1c-00 CEO - 00:00:BE:EF IT_Server1 - 110f FileServer3 +== READ FILTER SYNTAX -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. +For a complete table of protocol and protocol fields that are filterable +in *Rawshark* see the xref:wireshark-filter.html[wireshark-filter](4) manual page. -The personal __ipxnets__ file is looked for in the same directory as the -personal preferences file. --- +include::files.adoc[tags=**;!gui] == ENVIRONMENT VARIABLES diff --git a/doc/reordercap.adoc b/doc/man_pages/reordercap.adoc index fd57b0a7..0d03b166 100644 --- a/doc/reordercap.adoc +++ b/doc/man_pages/reordercap.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = reordercap(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/sdjournal.adoc b/doc/man_pages/sdjournal.adoc index bf9a3689..d8736704 100644 --- a/doc/sdjournal.adoc +++ b/doc/man_pages/sdjournal.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = sdjournal(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/sshdump.adoc b/doc/man_pages/sshdump.adoc index 8acacd1f..562336c4 100644 --- a/doc/sshdump.adoc +++ b/doc/man_pages/sshdump.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = sshdump(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/text2pcap.adoc b/doc/man_pages/text2pcap.adoc index ab894747..9c2a8195 100644 --- a/doc/text2pcap.adoc +++ b/doc/man_pages/text2pcap.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = text2pcap(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME @@ -16,7 +16,7 @@ text2pcap - Generate a capture file from an ASCII hexdump of packets [ *-a* ] [ *-b* 2|8|16|64 ] [ *-D* ] -[ *-e* <l3pid> ] +[ *-e* <ethertype> ] [ *-E* <encapsulation type> ] [ *-F* <file format> ] [ *-i* <proto> ] @@ -57,7 +57,11 @@ hexdumps of application-level data only. The *-F* flag can be used to specify the format in which to write the capture file, *text2pcap -F* provides a list of the available output formats. By default, it writes the packets to __outfile__ in the *pcapng* -file format. +file format. *Text2cap* also supports compression formats, which can +be specified with the *--compress* options. If that option is not given, +the the desired compression method, if any, is deduced from the extension +of __outfile__; e.g. if it has the extension '.gz', then the output file +is compressed to a gzip archive. *Text2pcap* understands a hexdump of the form generated by __od -Ax -tx1 -v__. In other words, each byte is individually displayed, with @@ -203,10 +207,10 @@ supports it (e.g. pcapng), and is also used when generating dummy headers to swap the source and destination addresses and ports as appropriate. -- --e <l3pid>:: +-e <ethertype>:: + -- -Include a dummy Ethernet header before each packet. Specify the L3PID +Include a dummy Ethernet header before each packet. Specify the EtherType for the Ethernet header in hex. Use this option if your dump has Layer 3 header and payload (e.g. IP header), but no Layer 2 encapsulation. Example: __-e 0x806__ to specify an ARP packet. @@ -297,11 +301,11 @@ direction indicators or timestamps after the first byte along with any offsets. + -- Include an EXPORTED_PDU header before each packet. Specify, as a -string, the dissector to be called for the packet (DISSECTOR_NAME tag). +string, the dissector to be called for the packet (DISSECTOR_NAME tag). Use this option if your dump is the payload for a single upper layer protocol (so specifying a link layer type would not work) and you wish -to create a capture file without a full dummy protocol stack. -Automatically sets the link layer type to Wireshark Upper PDU export. +to create a capture file without a full dummy protocol stack. +Automatically sets the link layer type to Wireshark Upper PDU export. Without this option, if the Upper PDU export link layer type (252) is selected the dissector defaults to "data". -- @@ -385,7 +389,7 @@ Print the full version information and exit. -4 <srcip>,<destip>:: + -- -Prepend dummy IP header with specified IPv4 dest and source address. +Prepend dummy IP header with specified IPv4 source and destination addresses. This option should be accompanied by one of the following options: -i, -s, -S, -T, -u Use this option to apply "custom" IP addresses. Example: __-4 10.0.0.1,10.0.0.2__ to use 10.0.0.1 and 10.0.0.2 for all IP packets. @@ -394,13 +398,21 @@ Example: __-4 10.0.0.1,10.0.0.2__ to use 10.0.0.1 and 10.0.0.2 for all IP packet -6 <srcip>,<destip>:: + -- -Prepend dummy IP header with specified IPv6 dest and source address. +Prepend dummy IP header with specified IPv6 source and destination addresses. This option should be accompanied by one of the following options: -i, -s, -S, -T, -u Use this option to apply "custom" IP addresses. Example: __-6 2001:db8::b3ff:fe1e:8329,2001:0db8:85a3::8a2e:0370:7334__ to use 2001:db8::b3ff:fe1e:8329 and 2001:0db8:85a3::8a2e:0370:7334 for all IP packets. -- +--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__. +-- + include::diagnostic-options.adoc[] == SEE ALSO 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 diff --git a/doc/udpdump.adoc b/doc/man_pages/udpdump.adoc index 8739ab6f..37b5934c 100644 --- a/doc/udpdump.adoc +++ b/doc/man_pages/udpdump.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = udpdump(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/wifidump.adoc b/doc/man_pages/wifidump.adoc index e202d05a..d23ee092 100644 --- a/doc/wifidump.adoc +++ b/doc/man_pages/wifidump.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = wifidump(1) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME diff --git a/doc/wireshark-filter.adoc b/doc/man_pages/wireshark-filter.adoc index 3e8a7b84..2de71423 100644 --- a/doc/wireshark-filter.adoc +++ b/doc/man_pages/wireshark-filter.adoc @@ -1,9 +1,9 @@ -include::../docbook/attributes.adoc[] +include::../attributes.adoc[] = wireshark-filter(4) :doctype: manpage :stylesheet: ws.css :linkcss: -:copycss: ../docbook/{stylesheet} +:copycss: {css_dir}/{stylesheet} == NAME @@ -138,6 +138,9 @@ The filter language has the following functions: len(field) - returns the byte length of a string or bytes field count(field) - returns the number of field occurrences in a frame string(field) - converts a non-string field to string + vals(field) - converts a field value to its value string + dec(field) - converts an unsigned integer to a decimal string + hex(field) - converts an unsigned integer to a hexadecimal string max(f1,...,fn) - return the maximum value min(f1,...,fn) - return the minimum value abs(field) - return the absolute value of numeric fields @@ -155,11 +158,77 @@ byte fields. For example: string(frame.number) matches "[13579]$" -gives you all the odd packets. +gives you all the odd packets. Note that the "matches" operator implicitly +converts types of their value string representation; to match against the +decimal representation of an integer field use string(). + +vals() converts an integer or boolean field value to a string using the +field's associated value string, if it has one. This produces strings +similar to those seen in custom columns. The resultant string can also +be used with other operators. E.g.: + + vals(pfcp.msg_type) contains "Request" + +would match all packets which have a PFCP request, even if that request is not +matched with a response. + +dec() and hex() convert unsigned integer fields to decimal or hexadecimal +representation. Currently dec() and string() give same result for an unsigned +integer, but it is possible that in the future string() will use the native +base of the field. max() and min() take any number of arguments and returns one value, respectively the largest/smallest. The arguments must all have the same type. +There is also a set of functions to test IP addresses: + + ip_special_name(ip) - Returns the IP special-purpose block name as a string + ip_special_mask(ip) - Returns the IP special-purpose block flags as a mask. The bits are: + 4 3 2 1 0 + --------- + S D F G R + S = Source, D = Destination, F = Forwardable, G = Globally-reachable, R = Reserved-by-protocol + + ip_linklocal(ip) - true if the IPv4 or IPv6 address is link-local + ip_multicast(ip) - true if the IPv4 or IPv6 address is multicast + ip_rfc1918(ipv4) - true if the IPv4 address is private-use (from the allocation in RFC 1918) + ip_ula(ipv6) - true if the IPv6 address is unique-local (ULA) as in RFC 4193 + +=== Macros + +It is possible to define display filter macros. Macro are names that are +replaced with the associated expression, possibly performing argument substitution. +Macro expansions are purely textual replacements and performed recursively before compilation. +They allow replacing long and often used expressions with easy to use names. + +Macros are defined using the GUI or directly in the "dmacros" configuration +file. For example the definition + + "addplusone" {$1 + $2 + 1} + +creates a macro called `addplusone` that takes two arguments and expands to the given expression. +Arguments in the replacement expression are given using the dollar sign. + +Macros are invoked like function but preceded with a dollar sign +(sometimes also called a sigil): + + $addplusone(udp.src_port,udp.dst_port) + +results in the expression + + {udp.src_port + udp.dst_port + 1} + +after argument substitution. There is an older alternative notation to invoke macros: + + ${addplusone:udp.src_port;udp.dst_port} + +or + + ${addplusone;udp.src_port;udp.dst_port} + +Both forms are equivalent and can be used interchangibly as a matter of +preference. + === Protocol field types Each protocol field is typed. The types are: @@ -483,12 +552,46 @@ can be convenient: frame[4] == 0xff frame[1:4] contains 0x02 +An integer or boolean field that has a value string can be compared to +to one of the strings that corresponds with a value. +As with stringlike fields and comparisons, it is possible to perform +the comparison with an unquoted literal, though this is deprecated and +will not work if the literal contains a space (as with "Modify Bearer +Response" above). Double quotes are recommended. + +If there is a unique reverse mapping from the string literal into a +numeric value, the string is converted into that number and the +comparison function is applied using arithmetic rules. If the mapping +is not unique, then equality and inequality can be tested, but not the +ordered comparisons. + +This is in contrast to the `string()` and `vals()` function, which +convert the field value to a string and applies string (lexicographic) +comparisons, as well as work with all operators that take strings. +Therefore the following two filters give the same result: + + gtpv2.message_type <= 35 + gtpv2.message_type <= "Modify Bearer Response" + +whereas + + vals(gtpv2.message_type) <= "Modify Bearer Response" + +matches all messages whose value string precedes "Modify Bearer Response" +in lexicographical order, and + + string(gtpv2.message_type) <= "35" + +matches all messages such that the message type comes before "35" in +lexicographical order, i.e. would also match "170" (the message type +for "Release Access Bearers Request.") + === Bitwise operators It is also possible to define tests with bitwise operations. Currently the following bitwise operator is supported: - bitwise_and, & Bitwise AND + bitand, bitwise_and, & Bitwise AND The bitwise AND operation allows masking bits and testing to see if one or more bits are set. Bitwise AND operates on integer protocol fields and slices. @@ -519,6 +622,13 @@ Arithmetic expressions are supported with the usual operators: / Division % Modulo (integer remainder) +Arithmetic operations can be performed on numeric types. Numeric types are +integers, floating point numbers and date and time values. + +Date and time values can only be multiplied by integers or floating point +numbers (i.e: scalars) and furthermore the scalar multiplier must appear on +the right-hand side of the arithmetic operation. + For example it is possible to filter for UDP destination ports greater or equal by one to the source port with the expression: @@ -537,13 +647,17 @@ or "A - B". === Protocol field references -A variable using a sigil with the form ${some.proto.field} is called a field +A variable using a sigil with the form $some.proto.field or ${some.proto.field} is called a field reference. A field reference is a field value read from the currently selected frame in the GUI. This is useful to build dynamic filters such as, frames since the last five minutes to the selected frame: frame.time_relative >= ${frame.time_relative} - 300 +or more simply + + frame.time_relative >= $frame.time_relative - 300 + Field references share a similar notation to macros but are distinct syntactical elements in the filter language. @@ -618,7 +732,7 @@ can find references and examples at the following locations: * `tshark -G fields` on the command line -* The Wireshark wiki: https://gitlab.com/wireshark/wireshark/-/wikis/DisplayFilters +* The Wireshark wiki: {wireshark-wiki-url}DisplayFilters == NOTES @@ -631,11 +745,10 @@ See https://www.pcre.org/ for more information. This manpage does not describe the capture filter syntax, which is different. 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 +xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8), or, if that doesn't exist, {wireshark-wiki-url}CaptureFilters for a description of capture filters. -Display Filters are also described in the User's Guide: -https://www.wireshark.org/docs/wsug_html_chunked/ChWorkBuildDisplayFilterSection.html +Display Filters are also described in the link:{wireshark-users-guide-url}ChWorkBuildDisplayFilterSection.html[Wireshark User's Guide]. == SEE ALSO diff --git a/doc/man_pages/wireshark.adoc b/doc/man_pages/wireshark.adoc new file mode 100644 index 00000000..c5e963e1 --- /dev/null +++ b/doc/man_pages/wireshark.adoc @@ -0,0 +1,1099 @@ +include::../attributes.adoc[] += wireshark(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +wireshark - Interactively dump and analyze network traffic + +== SYNOPSIS + +[manarg] +*wireshark* +[ *-i* <capture interface>|- ] +[ *-f* <capture filter> ] +[ *-Y* <display filter> ] +[ *-w* <outfile> ] +[ *options* ] +[ <infile> ] + +[manarg] +*wireshark* +*-h|--help* + +[manarg] +*wireshark* +*-v|--version* + +== DESCRIPTION + +*Wireshark* is a GUI network protocol analyzer. It lets you +interactively browse packet data from a live network or from a +previously saved capture file. *Wireshark*'s native capture file +formats are *pcapng* format and *pcap* format; it can read and write +both formats.. *pcap* format is also the format used by *tcpdump* and +various other tools; *tcpdump*, when using newer versions of the +*libpcap* library, can also read some pcapng files, and, on newer +versions of macOS, can read all pcapng files and can write them as well. + +*Wireshark* can also read / import the following file formats: + +* Oracle (previously Sun) *snoop* and *atmsnoop* captures + +* Finisar (previously Shomiti) *Surveyor* captures + +* Microsoft *Network Monitor* captures + +* Novell *LANalyzer* captures + +* AIX's *iptrace* captures + +* Cinco Networks *NetXRay* captures + +* NETSCOUT (previously Network Associates/Network General) Windows-based +*Sniffer* captures + +* Network General/Network Associates DOS-based *Sniffer* captures +(compressed or uncompressed) + +* LiveAction (previously WildPackets/Savvius) **Peek*/*EtherHelp*/*PacketGrabber* captures + +* *RADCOM*'s WAN/LAN analyzer captures + +* Viavi (previously Network Instruments) *Observer* captures + +* *Lucent/Ascend* router debug output + +* captures from HP-UX *nettl* + +* *Toshiba's* ISDN routers dump output + +* the output from *i4btrace* from the ISDN4BSD project + +* traces from the *EyeSDN* USB S0 + +* the *IPLog* format output from the Cisco Secure Intrusion Detection System + +* *pppd logs* (pppdump format) + +* the output from VMS's *TCPIPtrace*/*TCPtrace*/*UCX$TRACE* utilities + +* the text output from the *DBS Etherwatch* VMS utility + +* Visual Networks' *Visual UpTime* traffic capture + +* the output from *CoSine* L2 debug + +* the output from InfoVista (previously Accellent) *5View* LAN agents + +* Endace Measurement Systems' ERF format captures + +* Linux Bluez Bluetooth stack *hcidump -w* traces + +* Catapult DCT2000 .out files + +* Gammu generated text output from Nokia DCT3 phones in Netmonitor mode + +* IBM Series (OS/400) Comm traces (ASCII & UNICODE) + +* Juniper Netscreen snoop files + +* Symbian OS btsnoop files + +* TamoSoft CommView files + +* Tektronix K12xx 32bit .rf5 format files + +* Tektronix K12 text file format captures + +* Apple PacketLogger files + +* Captures from Aethra Telecommunications' PC108 software for their test +instruments + +* Citrix NetScaler Trace files + +* Android Logcat binary and text format logs + +* Colasoft Capsa and PacketBuilder captures + +* Micropross mplog files + +* Unigraf DPA-400 DisplayPort AUX channel monitor traces + +* 802.15.4 traces from Daintree's Sensor Network Analyzer + +* MPEG-2 Transport Streams as defined in ISO/IEC 13818-1 + +* Log files from the _candump_ utility + +* Logs from the BUSMASTER tool + +* Ixia IxVeriWave raw captures + +* Rabbit Labs CAM Inspector files + +* _systemd_ journal files + +* 3GPP TS 32.423 trace files + +There is no need to tell *Wireshark* what type of +file you are reading; it will determine the file type by itself. +*Wireshark* is also capable of reading any of these file formats if they +are compressed using gzip, LZ4, or Zstandard, if compiled with the +appropriate support. *Wireshark* recognizes this directly from the file; +the '.gz' or other extension is not required for this purpose. + +Like other protocol analyzers, *Wireshark*'s main window shows 3 views +of a packet. It shows a summary line, briefly describing what the +packet is. A packet details display is shown, allowing you to drill +down to exact protocol or field that you interested in. Finally, a hex +dump shows you exactly what the packet looks like when it goes over the +wire. + +In addition, *Wireshark* has some features that make it unique. It can +assemble all the packets in a TCP conversation and show you the ASCII +(or EBCDIC, or hex) data in that conversation. Display filters in +*Wireshark* are very powerful; more fields are filterable in *Wireshark* +than in other protocol analyzers, and the syntax you can use to create +your filters is richer. As *Wireshark* progresses, expect more and more +protocol fields to be allowed in display filters. + +Packet capturing is performed with the pcap library. The capture filter +syntax follows the rules of the pcap library. This syntax is different +from the display filter syntax. + +Compressed file support uses (and therefore requires) the zlib library. +If the zlib library is not present, *Wireshark* will compile, but will +be unable to read compressed files. + +The pathname of a capture file to be read can be specified with the +*-r* option or can be specified as a command-line argument. + +== OPTIONS + +Most users will want to start *Wireshark* without options and configure +it from the menus instead. Those users may just skip this section. + +-a|--autostop <capture autostop condition>:: ++ +-- +Specify a criterion that specifies when *Wireshark* 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, Wireshark +will stop writing to the current capture file and switch to the next one if +filesize is reached. Note that the filesize is limited to a maximum value of +2 TB, although you might have problems viewing the file in the GUI before then if +the number of packets exceeds 2^31^ (2147483648). + +*packets*:__value__ Stop writing to a capture file after it contains __value__ +packets. Acts the same as *-c*<capture packet count>. +-- + +-b|--ring-buffer <capture ring buffer option>:: ++ +-- +Cause *Wireshark* to run in "multiple files" mode. In "multiple files" mode, +*Wireshark* will write to several capture files. When the first capture file +fills up, *Wireshark* will switch writing to the next file and so on. + +The created filenames are based on the filename given with the *-w* flag, +the number of the file and on the creation date and time, +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, +at which point *Wireshark* 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 one of the other criteria 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 criteria, 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 TB, +although you might have problems viewing the file in the GUI before then if +the number of packets exceeds 2^31^ (2147483648). + +*interval*:__value__ switch to the next file when the time is an exact +multiple of __value__ seconds. + +*packets*:__value__ switch to the next file after it contains __value__ +packets. + +Example: *-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 *Wireshark* 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. Acts the same as *-a packets:*<capture packet count>. +-- + +-C <configuration profile>:: ++ +-- +Start with the given configuration profile. +-- + +--capture-comment <comment>:: ++ +-- +When performing a capture file from the command line, with the *-k* +flag, add a capture comment to the output file, if supported by the +capture format. + +This option may be specified multiple times. Note that Wireshark +currently only displays the first comment of a capture file. +-- + +-D|--list-interfaces:: ++ +-- +Print a list of the interfaces on which *Wireshark* 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. +-- + +--display <X display to use>:: ++ +-- +Specifies the X display to use. A hostname and screen (otherhost:0.0) +or just a screen (:0.0) can be specified. This option is not available +under macOS or Windows. +-- + +-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: *-f "predef:MyPredefinedHostOnlyFilter"* +-- + +-F <file format>:: +When performing a capture file from the command line, with the *-k* option, +set the file format of the output capture file written using the *-w* option. +In situations that require the *pcapng* format, such as capturing from +multiple interfaces, this option will be overridden. The option *-F* +without a value will list the available formats. The default is the +*pcapng* format (unless the default has been changed in preferences.) + +This does not support every format to which Wireshark can convert a file; +this is intentional for security reasons. Capture in a supported format and +then save the file in a different format if so desired. + +--fullscreen:: ++ +-- +Start Wireshark in full screen mode (kiosk mode). To exit from fullscreen mode, +open the View menu and select the Full Screen option. Alternatively, press the +F11 key (or Ctrl + Cmd + F for macOS). +-- + +-g <packet number>:: +After reading in a capture file using the *-r* flag, go to the given __packet number__. + +-h|--help:: +Print the version number and options and exit. + +-H:: +Hide the capture info dialog during live packet capture. + +-i|--interface <capture interface>|-:: ++ +-- +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 "*wireshark +-D*" (described above); a number, as reported by "*tshark -D*", can also +be used. + +If no interface is specified, *Wireshark* searches the list of +interfaces, choosing the first non-loopback interface if there are any +non-loopback interfaces, and choosing the first loopback interface if +there are no non-loopback interfaces. If there are no interfaces at all, +*Wireshark* reports an error and doesn't start the capture. + +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 +standard pcapng or pcap format. Pcapng data must have the same +endianness as the capturing host. + +"TCP@<host>:<port>" causes *Wireshark* 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. +-- + +-I|--monitor-mode:: ++ +-- +Put the interface in "monitor mode"; this is supported only on IEEE +802.11 Wi-Fi interfaces, and supported only on some operating systems. + +Note that in monitor mode the adapter might disassociate from the +network with which it's associated, so that you will not be able to use +any wireless networks with that adapter. This could prevent accessing +files on a network server, or resolving host names or network addresses, +if you are capturing in monitor mode and are not connected to another +network with another adapter. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it enables the monitor mode for all interfaces. +If used after an *-i* option, it enables the monitor mode for +the interface specified by the last *-i* option occurring before +this option. +-- + +-j:: +Use after *-J* to change the behavior when no exact match is found for +the filter. With this option select the first packet before. + +-J <jump filter>:: ++ +-- +After reading in a capture file using the *-r* flag, jump to the packet +matching the filter (display filter syntax). If no exact match is found +the first packet after that is selected. +-- + +-k:: ++ +-- +Start the capture session immediately. If the *-i* flag was +specified, the capture uses the specified interface. Otherwise, +*Wireshark* searches the list of interfaces, choosing the first +non-loopback interface if there are any non-loopback interfaces, and +choosing the first loopback interface if there are no non-loopback +interfaces; if there are no interfaces, *Wireshark* reports an error and +doesn't start the capture. +-- + +-l:: +Turn on automatic scrolling if the packet display is being updated +automatically as packets arrive during a capture (as specified by the +*-S* flag). + +-L|--list-data-link-types:: +List the data link types supported by the interface and exit. + +--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. + +-o <preference/recent setting>:: ++ +-- +Set a preference or recent value, overriding the default value and any value +read from a preference/recent file. The argument to the flag is a string of +the form __prefname:value__, where __prefname__ is the name of the +preference/recent value (which is the same name that would appear in the +preference/recent file), and __value__ is the value to which it should be set. +Since *Ethereal* 0.10.12, the recent settings replaces the formerly used +-B, -P and -T flags to manipulate the GUI dimensions. + +If __prefname__ is "uat", you can override settings in various user access +tables using the form "uat:__uat filename__:__uat record__". __uat filename__ +must be the name of a UAT file, e.g. __user_dlts__. __uat_record__ must be in +the form of a valid record for that file, including quotes. For instance, to +specify a user DLT from the command line, you would use + + -o "uat:user_dlts:\"User 0 (DLT=147)\",\"cops\",\"0\",\"\",\"0\",\"\"" +-- + +-p|--no-promiscuous-mode:: ++ +-- +__Don't__ put the interface into promiscuous mode. Note that the +interface might be in promiscuous mode for some other reason; hence, +*-p* cannot be used to ensure that the only traffic that is captured is +traffic sent to or from the machine on which *Wireshark* is running, +broadcast traffic, and multicast traffic to addresses received by that +machine. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, no interface will be put into the +promiscuous mode. +If used after an *-i* option, the interface specified by the last *-i* +option occurring before this option will not be put into the +promiscuous mode. +-- + +-P <path setting>:: ++ +-- +Special path settings usually detected automatically. This is used for +special cases, e.g. starting Wireshark from a known location on an USB stick. + +The criterion is of the form __key:path__, where __key__ is one of: + +*persconf*:__path__ path of personal configuration files, like the +preferences files. + +*persdata*:__path__ path of personal data files, it's the folder initially +opened. After the very first initialization, the recent file will keep the +folder last used. +-- + +-r|--read-file <infile>:: ++ +-- +Read packet data from __infile__, can be any supported capture file format +(including compressed files). It's not possible to use named pipes or stdin +here, unlike *TShark*! To capture from a pipe or from stdin use *-i -*. +-- + +-R|--read-filter <read (display) filter>:: ++ +-- +When reading a capture file specified with the *-r* flag, causes the +specified filter (which uses the syntax of display filters, rather than +that of capture filters) to be applied to all packets read from the +capture file; packets not matching the filter are discarded. +-- + +-s|--snapshot-length <capture snaplen>:: ++ +-- +Set the default snapshot length to use when capturing live data. +No more than __snaplen__ bytes of each network packet will be read into +memory, or saved to disk. A value of 0 specifies a snapshot length of +262144, so that the full packet is captured; this is the default. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it sets the default snapshot length. +If used after an *-i* option, it sets the snapshot length for +the interface specified by the last *-i* option occurring before +this option. If the snapshot length is not set specifically, +the default snapshot length is used if provided. +-- + +-S:: +Automatically update the packet display as packets are coming in. + +--temp-dir <directory>:: ++ +-- +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__. +-- + +--time-stamp-type <type>:: +Change the interface's timestamp method. See --list-time-stamp-types. + +--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. + +-v|--version:: +Print the full version information and exit. + +-w <outfile>:: +Set the default capture file name, or '-' for standard output. + +-X <eXtension options>:: ++ +-- +Specify an option to be passed to an *Wireshark* module. The eXtension option +is in the form __extension_key:value__, where __extension_key__ can be: + +*lua_script*:__lua_script_filename__ tells *Wireshark* to load the given script in addition to the +default Lua scripts. + +**lua_script**__num__:__argument__ tells *Wireshark* to pass the given argument +to the lua script identified by 'num', which is the number indexed order of the 'lua_script' command. +For example, if only one script was loaded with '-X lua_script:my.lua', then '-X lua_script1:foo' +will pass the string 'foo' to the 'my.lua' script. If two scripts were loaded, such as '-X lua_script:my.lua' +and '-X lua_script:other.lua' in that order, then a '-X lua_script2:bar' would pass the string 'bar' to the second lua +script, namely 'other.lua'. + +*read_format*:__file_format__ tells *Wireshark* to use the given file format to read in the +file (the file given in the *-r* command option). + +*stdin_descr*:__description__ tells *Wireshark* to use the given description when +capturing from standard input (*-i -*). +-- + +-y|--linktype <capture link type>:: ++ +-- +If a capture is started from the command line with *-k*, set the data +link type to use while capturing packets. The values reported by *-L* +are the values that can be used. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it sets the default capture link type. +If used after an *-i* option, it sets the capture link type for +the interface specified by the last *-i* option occurring before +this option. If the capture link type is not set specifically, +the default capture link type is used if provided. +-- + +-Y|--display-filter <displaY filter>:: +Start with the given display filter. + +-z <statistics>:: ++ +-- +Get *Wireshark* to collect various types of statistics and display the result +in a window that updates in semi-real time. + +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* 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 +want to generate the statistics; currently the supported ones are: + + "eth" Ethernet addresses + "fc" Fibre Channel addresses + "fddi" FDDI addresses + "ip" IPv4 addresses + "ipv6" IPv6 addresses + "ipx" IPX 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 + +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. By default, the table is sorted according to +the total number of packets. + +These tables can also be generated at runtime by selecting the appropriate +conversation type from the menu "Tools/Statistics/Conversation List/". +-- + +*-z* dcerpc,srt,__name-or-uuid__,__major__.__minor__[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for DCERPC interface +__name__ or __uuid__, version __major__.__minor__. +Data collected is the number of calls for each procedure, MinSRT, MaxSRT +and AvgSRT. +Interface __name__ and __uuid__ are case-insensitive. + +Example: [.nowrap]#*-z dcerpc,srt,12345778-1234-abcd-ef00-0123456789ac,1.0*# will 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* dhcp,stat[,__filter__]:: +Show DHCP (BOOTP) statistics. + +*-z* expert:: +Show expert information. + +*-z* fc,srt[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for FC. Data collected +is the number of calls for each Fibre Channel command, MinSRT, MaxSRT and AvgSRT. + +Example: *-z fc,srt* +will calculate the Service Response Time as the time delta between the +First packet of the exchange and the Last packet of the exchange. + +The data will be presented as separate tables for all normal FC commands, +Only those commands that are seen in the capture will have its stats +displayed. + +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 "fc,srt,fc.id==01.02.03"* will collect stats only for +FC packets exchanged by the host at FC address 01.02.03 . +-- + +*-z* h225,counter[__,filter__]:: ++ +-- +Count ITU-T H.225 messages and their reasons. In the first column you get a +list of H.225 messages and H.225 message reasons which occur in the current +capture file. The number of occurrences of each message or reason is displayed +in the second column. + +Example: *-z h225,counter* + +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,counter,ip.addr==1.2.3.4"* will collect stats only for +H.225 packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* h225,srt[__,filter__]:: ++ +-- +Collect request/response SRT (Service Response Time) data for ITU-T H.225 RAS. +Data collected is the 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. +You will also get the number of Open Requests (Unresponded Requests), +Discarded Responses (Responses without matching request) and Duplicate Messages. + +Example: *-z h225,srt* + +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 collect stats only for +ITU-T H.225 RAS packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* io,stat:: ++ +-- +Collect packet/bytes statistics for the capture in intervals of 1 second. +This option will open a window with up to 5 color-coded graphs where +number-of-packets-per-second or number-of-bytes-per-second statistics +can be calculated and displayed. + +This option can be used multiple times on the command line. + +This graph window can also be opened from the Analyze:Statistics:Traffic:IO-Stat +menu item. +-- + +*-z* ldap,srt[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for LDAP. Data collected +is the number of calls for each implemented LDAP command, MinSRT, MaxSRT and AvgSRT. + +Example: *-z ldap,srt* +will calculate the Service Response Time as the time delta between the +Request and the Response. + +The data will be presented as separate tables for all implemented LDAP commands, +Only those commands that are seen in the capture will have its stats +displayed. + +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: use *-z "ldap,srt,ip.addr==10.1.1.1"* will collect stats only for +LDAP packets exchanged by the host at IP address 10.1.1.1 . + +The only LDAP commands that are currently implemented and for which the stats will be available are: +BIND +SEARCH +MODIFY +ADD +DELETE +MODRDN +COMPARE +EXTENDED +-- + +*-z* megaco,srt[__,filter__]:: ++ +-- +Collect request/response SRT (Service Response Time) data for MEGACO. +(This is similar to *-z smb,srt*). Data collected is the number of calls +for each known MEGACO Command, Minimum SRT, Maximum SRT and Average SRT. + +Example: *-z megaco,srt* + +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 "megaco,srt,ip.addr==1.2.3.4"* will collect stats only for +MEGACO packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* mgcp,srt[__,filter__]:: ++ +-- +Collect request/response SRT (Service Response Time) data for MGCP. +(This is similar to *-z smb,srt*). Data collected is the number of calls +for each known MGCP Type, Minimum SRT, Maximum SRT and Average SRT. + +Example: *-z mgcp,srt* + +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,srt,ip.addr==1.2.3.4"* will collect stats only for +MGCP packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* mtp3,msus[,<filter>]:: +Show MTP3 MSU statistics. + +*-z* multicast,stat[,<filter>]:: +Show UDP multicast stream statistics. + +*-z* rpc,programs:: ++ +-- +Collect call/reply SRT data for all known ONC-RPC programs/versions. +Data collected is the number of calls for each protocol/version, MinSRT, +MaxSRT and AvgSRT. +-- + +*-z* rpc,srt,__name-or-number__,__version__[,<filter>]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for program +__name__/__version__ or __number__/__version__. +Data collected is the number of calls for each procedure, MinSRT, MaxSRT and +AvgSRT. +Program __name__ is case-insensitive. + +Example: *-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: [.nowrap]#*-z rpc,srt,nfs,3,nfs.fh.hash==0x12345678*# will collect NFS v3 +SRT statistics for a specific file. +-- + +*-z* scsi,srt,__cmdset__[,<filter>]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for SCSI commandset <cmdset>. + +Commandsets are 0:SBC 1:SSC 5:MMC + +Data collected +is the number of calls for each procedure, MinSRT, MaxSRT and AvgSRT. + +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__]:: ++ +-- +This option will activate a counter for SIP messages. You will get the number +of occurrences of each SIP Method and of each SIP Status-Code. Additionally you +also get the number of resent SIP Messages (only for SIP over UDP). + +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 collect stats only for +SIP packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* smb,srt[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for SMB. Data collected +is the number of calls for each SMB command, MinSRT, MaxSRT and AvgSRT. + +Example: *-z smb,srt* + +The data will be presented as separate tables for all normal SMB commands, +all Transaction2 commands and all NT Transaction commands. +Only those commands that are seen in the capture will have their stats +displayed. +Only the first command in a xAndX command chain will be used in the +calculation. So for common SessionSetupAndX + TreeConnectAndX chains, +only the SessionSetupAndX call will be used in the statistics. +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 collect stats only for +SMB packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* voip,calls:: ++ +-- +This option will show a window that shows VoIP calls found in the capture file. +This is the same window shown as when you go to the Statistics Menu and choose +VoIP Calls. + +Example: *-z voip,calls* +-- + +*-z* wlan,stat[,<filter>]:: +Show IEEE 802.11 network and station statistics. + +*-z* wsp,stat[,<filter>]:: +Show WSP packet counters. + +include::dissection-options.adoc[tags=**;!tshark] + +include::diagnostic-options.adoc[] + +== INTERFACE + +The link:{wireshark-users-guide-url}[Wireshark User's Guide] contains a description of the user interface. It also may be installed locally along with Wireshark. Pressing the F1 key will attempt to open the guide locally if present, falling back to the online guide if not. + +== 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, {wireshark-wiki-url}CaptureFilters. + +== DISPLAY FILTER SYNTAX + +For a complete table of protocol and protocol fields that are filterable +in *Wireshark* see the xref:wireshark-filter.html[wireshark-filter](4) manual page. + +include::files.adoc[] + +== ENVIRONMENT VARIABLES + +// Should this be moved to an include file? + +WIRESHARK_CONFIG_DIR:: ++ +-- +This environment variable overrides the location of personal +configuration files. On UNIX-compatible systems, such as Linux, macOS, +\*BSD, Solaris, and AIX, it defaults to __$XDG_CONFIG_HOME/wireshark__ +(or, if that directory doesn't exist but __$HOME/.wireshark__ does +exist, __$HOME/.wireshark__); this is typically +__$HOME/.config/wireshark__. On Windows, it defaults to +__%APPDATA%\Wireshark__ (or, if %APPDATA% isn't defined, +__%USERPROFILE%\Application Data\Wireshark__). Available since +Wireshark 3.0. +-- + +WIRESHARK_DEBUG_WMEM_OVERRIDE:: +Setting this environment variable forces the wmem framework to use the +specified allocator backend for *all* allocations, regardless of which +backend is normally specified by the code. This is mainly useful to developers +when testing or debugging. See __README.wmem__ in the source distribution for +details. + +WIRESHARK_RUN_FROM_BUILD_DIRECTORY:: +This environment variable causes the plugins and other data files to be +loaded from the build directory (where the program was compiled) rather +than from the standard locations. It has no effect when the program in +question is running with root (or setuid) permissions on UNIX-compatible +systems, such as Linux, macOS, \*BSD, Solaris, and AIX. + +WIRESHARK_DATA_DIR:: +This environment variable causes the various data files to be loaded from +a directory other than the standard locations. It has no effect when the +program in question is running with root (or setuid) permissions on +UNIX-compatible systems. + +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, *Wireshark* will call abort(3) +when a dissector bug is encountered. abort(3) will cause the program to +exit abnormally; if you are running *Wireshark* in a debugger, it +should halt in the debugger and allow inspection of the process, and, if +you are not running it in a debugger, it will, on some OSes, assuming +your environment is configured correctly, generate a core dump file. +This can be useful to developers attempting to troubleshoot a problem +with a protocol dissector. + +WIRESHARK_ABORT_ON_TOO_MANY_ITEMS:: +If this environment variable is set, *Wireshark* will call abort(3) +if a dissector tries to add too many items to a tree (generally this +is an indication of the dissector not breaking out of a loop soon enough). +abort(3) will cause the program to exit abnormally; if you are running +*Wireshark* in a debugger, it should halt in the debugger and allow +inspection of the process, and, if you are not running it in a debugger, +it will, on some OSes, assuming your environment is configured correctly, +generate a core dump file. This can be useful to developers attempting to +troubleshoot a problem with a protocol dissector. + +WIRESHARK_QUIT_AFTER_CAPTURE:: +Cause *Wireshark* to exit after the end of the capture session. This +doesn't automatically start a capture; you must still use *-k* to do +that. You must also specify an autostop condition, e.g. *-c* or *-a +duration:...*. This means that you will not be able to see the results +of the capture after it stops; it's primarily useful for testing. + +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. + +== AUTHORS + +Wireshark would not be the powerful, featureful application it is without the generous contributions of hundreds of developers. + +A complete list of authors can be found in the AUTHORS file in Wireshark's source code repository and at https://www.wireshark.org/about.html#authors. + +== SEE ALSO + +xref:wireshark-filter.html[wireshark-filter](4), xref:tshark.html[tshark](1), xref:editcap.html[editcap](1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:dumpcap.html[dumpcap](1), xref:mergecap.html[mergecap](1), +xref:text2pcap.html[text2pcap](1), xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8) + +== NOTES + +This is the manual page for *Wireshark* {wireshark-version}. +The latest version of *Wireshark* can be found at +{wireshark-main-url}. + +HTML versions of the Wireshark project man pages are available at +{wireshark-man-page-url}. + +The Wireshark's User Guide is available at +{wireshark-users-guide-url}. |