diff options
Diffstat (limited to 'doc/man_pages')
30 files changed, 10371 insertions, 0 deletions
diff --git a/doc/man_pages/androiddump.adoc b/doc/man_pages/androiddump.adoc new file mode 100644 index 00000000..21f5f79b --- /dev/null +++ b/doc/man_pages/androiddump.adoc @@ -0,0 +1,256 @@ +include::../attributes.adoc[] += androiddump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +androiddump - Provide interfaces to capture from Android devices + +== SYNOPSIS + +[manarg] +*androiddump* +[ *--help* ] +[ *--version* ] +[ *--extcap-version* ] +[ *--debug* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--extcap-capture-filter*=<capture filter> ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--adb-server-ip*=<IP address> ] +[ *--adb-server-tcp-port*=<TCP port> ] +[ *--logcat-text*=<TRUE or FALSE> ] +[ *--bt-server-tcp-port*=<TCP port> ] +[ *--bt-forward-socket*=<TRUE or FALSE> ] +[ *--bt-local-ip*=<IP address> ] +[ *--bt-local-tcp-port*=<TCP port> ] + +[manarg] +*androiddump* +*--extcap-interfaces* +[ *--adb-server-ip*=<IP address> ] +[ *--adb-server-tcp-port*=<TCP port> ] + +[manarg] +*androiddump* +*--extcap-interface*=<interface> +[ *--extcap-dlts* ] + +[manarg] +*androiddump* +*--extcap-interface*=<interface> +[ *--extcap-config* ] + +[manarg] +*androiddump* +*--extcap-interface*=<interface> +*--fifo*=<path to file or pipe> +*--capture* + +== DESCRIPTION + +*Androiddump* is a extcap tool that provide interfaces to capture from +an Android device. There are only two requirements: + +1. You must have the Android SDK and add it to your PATH environment variable. +PATH should contain directory with tools like "adb" and "android". +Android SDK for various platform are available on: +https://developer.android.com/sdk/index.html#Other + +2. You must have permission to capture from the Android device. +Some Android devices require on-screen authentication. + +Supported interfaces: + +1. Logcat Main (binary [++<=++Jelly Bean] or text) +2. Logcat System (binary [++<=++Jelly Bean] or text) +3. Logcat Events (binary [++<=++Jelly Bean] or text) +4. Logcat Radio (binary [++<=++Jelly Bean] or text) +5. Logcat Crash (text; from Lollipop) +6. Bluetooth Hcidump [++<=++Jelly Bean] +7. Bluetooth Bluedroid External Parser [Kitkat] +8. Bluetooth BtsnoopNet [>=Lollipop] +9. WiFi/Ethernet tcpdump [needs tcpdump on phone] + +Please note that Androiddump will work also for FirefoxOS or other +Android-based operating systems. + +== OPTIONS + +--help:: +Print program arguments. + +--version:: +Print program version. + +--extcap-version:: +Print extcapized version. + +--debug:: +Print additional messages. + +--extcap-interfaces:: +List available interfaces. + +--extcap-interface=<interface>:: +Use specified interfaces. + +--extcap-dlts:: +List DLTs of specified interface. + +--extcap-config:: +List configuration options of specified interface. + +--extcap-capture-filter=<capture filter>:: +The capture filter. It corresponds to the value provided via the *tshark -f* +option, and the Capture Filter field next to the interfaces list in the +Wireshark interface. ++ +NOTE: This is only respected for Wifi/Ethernet (tcpdump) capturing, not for +Bluetooth or logcat. + +--capture:: +Start capturing from the specified interface and save it in the location +specified with --fifo. + +--fifo=<path to file or pipe>:: +Save captured packet to file or send it through pipe. + +--adb-server-ip=<IP address>:: +Use other than default (127.0.0.1) ADB daemon's IP address. + +--adb-server-tcp-port=<TCP port>:: +Use other than default (5037) ADB daemon's TCP port. + +--logcat-text=<TRUE or FALSE>:: ++ +-- +If TRUE then use text logcat rather then binary. This option only has an +effect on +Logcat interfaces. This have no effect from Lollipop where is no binary Logcat +available. + +Defaults to FALSE. +-- + +--bt-server-tcp-port=<TCP port>:: ++ +-- +Use other than default Bluetooth server TCP port on Android side. +On Lollipop defaults is 8872, earlier 4330. +-- + +--bt-forward-socket=<TRUE or FALSE>:: ++ +-- +If TRUE then socket from Android side is forwarded to host side. + +Defaults to FALSE. +-- + +--bt-local-ip=<IP address>:: +Use other than default (127.0.0.1) IP address on host side for forwarded socket. + +--bt-local-tcp-port=<TCP port>:: +Specify port to be used on host side for forwarded socket. + +== EXAMPLES + +To see program arguments: + + androiddump --help + +To see program version: + + androiddump --version + +To see interfaces: + + androiddump --extcap-interfaces + +.Example output +---- +interface {display=Android Logcat Main unknown MSM7627A}{value=android-logcat-main-MSM7627A} +interface {display=Android Logcat System unknown MSM7627A}{value=android-logcat-system-MSM7627A} +interface {display=Android Logcat Radio unknown MSM7627A}{value=android-logcat-radio-MSM7627A} +interface {display=Android Logcat Events unknown MSM7627A}{value=android-logcat-events-MSM7627A} +interface {display=Android Bluetooth Hcidump unknown MSM7627A}{value=android-bluetooth-hcidump-MSM7627A} +---- + +Human-readable display name of interfaces contains interface type, one of: + + android-logcat-main (Android Logcat Main) + android-logcat-system (Android Logcat System) + android-logcat-radio (Android Logcat Radio) + android-logcat-events (Android Logcat Events) + android-logcat-text-main (Android Logcat Main) + android-logcat-text-system (Android Logcat System) + android-logcat-text-radio (Android Logcat Radio) + android-logcat-text-events (Android Logcat Events) + android-logcat-text-crash (Android Logcat Crash) + android-bluetooth-hcidump (Android Bluetooth Hcidump) + android-bluetooth-external-parser (Android Bluetooth External Parser) + android-bluetooth-btsnoop-net (Android Bluetooth Btsnoop Net) + android-tcpdump (Android tcpdump) + +For tcpdump this is followed by target network device name (like `eth0`). + +Then Android Device's name if available, otherwise `unknown`. + +Last part of it is DeviceID - the identificator of the device provided by Android SDK (see `adb devices`). + +For example: `Android Logcat Main unknown MSM7627A` + +- `Android Logcat Main` - user-friendly type of interface +- `unknown` - name of Android Device +- `MSM7627A` - device ID + +To see interface DLTs: + + androiddump --extcap-interface=android-bluetooth-hcidump-MSM7627A --extcap-dlts + +.Example output + dlt {number=99}{name=BluetoothH4}{display=Bluetooth HCI UART transport layer plus pseudo-header} + +To see interface configuration options: + + androiddump --extcap-interface=android-bluetooth-hcidump-MSM7627A --extcap-config + +.Example output + arg {number=0}{call=--adb-server-ip}{display=ADB Server IP Address}{type=string}{default=127.0.0.1} + arg {number=1}{call=--adb-server-tcp-port}{display=ADB Server TCP Port}{type=integer}{range=0,65535}{default=5037} + +To capture: + + androiddump --extcap-interface=android-bluetooth-hcidump-MSM7627A --fifo=/tmp/bluetooth.pcapng --capture + +NOTE: To stop capturing CTRL+C/kill/terminate the application. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4) + +== NOTES + +*Androiddump* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Michal Labedzki <michal.labedzki[AT]tieto.com> + +.Contributors +[%hardbreaks] +Roland Knall <rknall[AT]gmail.com> diff --git a/doc/man_pages/asn2deb.adoc b/doc/man_pages/asn2deb.adoc new file mode 100644 index 00000000..e02844cc --- /dev/null +++ b/doc/man_pages/asn2deb.adoc @@ -0,0 +1,84 @@ +include::../attributes.adoc[] += asn2deb(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +asn2deb - Create a Debian package for BER monitoring from ASN.1 + +== SYNOPSIS + +[manarg] +*asn2deb* +[ *-a* <ASN.1 file> ] +[ *--asn*=<ASN.1 file> ] +[ *-d* <opts> ] +[ *--dbopts*=<opts> ] +[ *-e* <address> ] +[ *--email*=<address> ] +[ *-h* ] +[ *--help* ] +[ *-n* <name> ] +[ *--name*=<name> ] +[ *-p* ] +[ *--preserve* ] +[ *-v* ] +[ *--version* ] + +== DESCRIPTION + +This manual page documents briefly the *asn2deb* command. *asn2deb* +takes an ASN.1 file as input and creates a Debian package from it. The package +contains a loadable type table file for the Wireshark network analyzer. +The type table is generated by the ASN.1 compiler *snacc*. + +== OPTIONS + +-a <ASN.1 file> --asn=<ASN.1 file>:: +ASN.1 file to use (mandatory). + +-d <opts> --dbopts=<opts>:: +options for dpkg-buildpackage. + +-e <address> --email=<address>:: +use e-mail address. + +-h --help:: +print help and exit. + +-n <name> --name=<name>:: +use user name. + +-p --preserve:: +do not overwrite files. + +-v --version:: +print version and exit. + +== EXAMPLES + +/usr/bin/asn2deb -e me@foo.net -a bar.asn1 \-n "My Name" -d "-rfakeroot -uc -us"-d "-rfakeroot -uc -us" + +== SEE ALSO + +A lot of tools are used, which you have to *apt-get install*: wireshark-dev, python, cdbs, autotools-dev, debhelper, dpkg-dev, +snacc. + +== COPYING + +This manual page was written by W. Borgert debacle@debian.org +for Debian GNU/Linux (but may be used by others). Permission is granted +to copy, distribute and/or modify this document under the terms of the +GNU General Public License, Version 2 or any later version published by +the Free Software Foundation. + +== AUTHOR + +*W. Borgert* Author. + +== COPYRIGHT + +Copyright (C) 2003, 2005 W. Borger diff --git a/doc/man_pages/capinfos.adoc b/doc/man_pages/capinfos.adoc new file mode 100644 index 00000000..c609ab72 --- /dev/null +++ b/doc/man_pages/capinfos.adoc @@ -0,0 +1,388 @@ +include::../attributes.adoc[] += capinfos(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +capinfos - Prints information about capture files + +== SYNOPSIS + +[manarg] +*capinfos* +[ *-a* ] +[ *-A* ] +[ *-b* ] +[ *-B* ] +[ *-c* ] +[ *-C* ] +[ *-d* ] +[ *-D* ] +[ *-e* ] +[ *-E* ] +[ *-F* ] +[ *-h* ] +[ *-H* ] +[ *-i* ] +[ *-I* ] +[ *-k* ] +[ *-K* ] +[ *-l* ] +[ *-L* ] +[ *-m* ] +[ *-M* ] +[ *-n* ] +[ *-N* ] +[ *-o* ] +[ *-p* ] +[ *-P* ] +[ *-q* ] +[ *-Q* ] +[ *-r* ] +[ *-R* ] +[ *-s* ] +[ *-S* ] +[ *-t* ] +[ *-T* ] +[ *-u* ] +[ *-v* ] +[ *-x* ] +[ *-y* ] +[ *-z* ] +<__infile__> +__...__ + +[manarg] +*capinfos* +*-h|--help* + +[manarg] +*capinfos* +*-v|--version* + +== DESCRIPTION + +*Capinfos* is a program that reads one or more capture files and +returns some or all available statistics (infos) of each <__infile__> +in one of two types of output formats: long or table. + +The long output is suitable for a human to read. The table output +is useful for generating a report that can be easily imported into +a spreadsheet or database. + +The user specifies what type of output (long or table) and which +statistics to display by specifying flags (options) that corresponding +to the report type and desired infos. If no options are specified, +*Capinfos* will report all statistics available in "long" format. + +Options are processed from left to right order with later options +superseding or adding to earlier options. + +*Capinfos* is able to detect and read the same capture files that are +supported by *Wireshark*. +The input files don't need a specific filename extension; the file +format and an optional gzip, zstd or lz4 compression will be automatically detected. +Near the beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or +https://www.wireshark.org/docs/man-pages/wireshark.html +is a detailed description of the way *Wireshark* handles this, which is +the same way *Capinfos* handles this. + +== OPTIONS + +-a:: +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 +all infos values for each input file, but enabling +any of the individual display infos options will +disable the generate all option. + +-b:: ++ +-- +Separate infos with ASCII SPACE (0x20) characters. +This option is only useful when generating a table +style report (-T). The various info values will be +separated (delimited) from one another with a single +ASCII SPACE character. + +NOTE: Since some of the header labels as well as some +of the value fields contain SPACE characters. This +option is of limited value unless one of the quoting +options (-q or -Q) is also specified. +-- + +-B:: +Separate the infos with ASCII TAB characters. +This option is only useful when generating a table +style report (-T). The various info values will be +separated (delimited) from one another with a single +ASCII TAB character. The TAB character is the default +delimiter when -T style report is enabled. + +-c:: +Displays the number of packets in the capture file. + +-C:: ++ +-- +Cancel processing any additional files if and +when *Capinfos* fails to open an input file +or gets an error reading an input file. +By default *Capinfos* will continue processing files +even if it gets an error opening or reading a file. + +Note: An error message will be written to stderr +whenever *Capinfos* fails to open a file or gets +an error reading from a file regardless whether +the -C option is specified or not. +Upon exit, *Capinfos* will return an error status +if any errors occurred during processing. +-- + +-d:: +Displays the total length of all packets in the file, in +bytes. This counts the size of the packets as they appeared +in their original form, not as they appear in this file. +For example, if a packet was originally 1514 bytes and only +256 of those bytes were saved to the capture file (if packets +were captured with a snaplen or other slicing option), +*Capinfos* will consider the packet to have been 1514 bytes. + +-D:: +Displays a count of the number of decryption secrets in the file. This information +is not available in table format. + +-e:: +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. + +-F:: +Displays additional capture file information. + +-h|--help:: +Print the version number and options and exit. + +-H:: +Displays the SHA256 and SHA1 hashes for the file. +SHA1 output may be removed in the future. + +-i:: +Displays the average data rate, in bits/sec + +-I:: +Displays detailed capture file interface information. This information +is not available in table format. + +-k:: +Displays the capture comment. For pcapng files, this is the comment from the +section header block. + +-K:: +Use this option to suppress printing capture comments. By default capture +comments are enabled. Capture comments are relatively freeform and might +contain embedded new-line characters and/or other delimiting characters +making it harder for a human or machine to easily parse the *Capinfos* output. +Excluding capture comments can aid in post-processing of output. + +-l:: +Display the snaplen (if any) for a file. +snaplen (if available) is determined from the capture file header +and by looking for truncated records in the capture file. + +-L:: +Generate long report. *Capinfos* can generate two +different styles of reports. The "long" report is +the default style of output and is suitable for a +human to use. + +-m:: +Separate the infos with comma (,) characters. This option +is only useful when generating a table style report (-T). +The various info values will be separated (delimited) +from one another with a single comma "," character. + +-M:: +Print raw (machine readable) values in long reports. +By default *Capinfos* prints numeric values with human-readable SI +suffixes, and shows human-readable file type and encapsulation. +Table reports (-T) always print raw values. + +-n:: +Displays a count of the number of resolved IPv4 addresses and a count of +the number of resolved IPv6 addresses in the file. This information +is not available in table format. + +-N:: +Do not quote the infos. This option is only useful +when generating a table style report (-T). Excluding +any quoting characters around the various values and +using a TAB delimiter produces a very "clean" table +report that is easily parsed with CLI tools. By +default infos are *NOT* quoted. + +-o:: +Displays "True" if packets exist in strict chronological order +or "False" if one or more packets in the capture exists +"out-of-order" time-wise. + +-p:: +Display individual packet comments. It is recommended +to print raw values (-M) when using this option as +packet comments may include newlines and other special +characters. + +-P:: +Disable displaying individual packet comments. + +-q:: +Quote infos with single quotes ('). This option is +only useful when generating a table style report (-T). +When this option is enabled, each value will be +encapsulated within a pair of single quote (') +characters. This option (when used with the -m +option) is useful for generating one type of CSV +style file report. + +-Q:: +Quote infos with double quotes ("). This option is +only useful when generating a table style report (-T). +When this option is enabled, each value will be +encapsulated within a pair of double quote (") +characters. This option (when used with the -m +option) is useful for generating the most common +type of CSV style file report. + +-r:: +Do not generate header record. This option is only +useful when generating a table style report (-T). +If this option is specified then *no* header record will be +generated within the table report. + +-R:: +Generate header record. This option is only useful +when generating a table style report (-T). A header +is generated by default. A header record (if generated) +is the first line of data reported and includes labels +for all the columns included within the table report. + +-s:: +Displays the size of the file, in bytes. This reports +the size of the capture file itself. + +-S:: +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. + +-T:: +Generate a table report. A table report is a text file +that is suitable for importing into a spreadsheet or +database. *Capinfos* can build a tab delimited text file +(the default) or several variations on Comma-separated +values (CSV) files. + +-u:: +Displays the capture duration, in seconds. This is the +difference in time between the earliest packet seen and +latest packet seen. + +-v|--version:: +Print the full version information and exit. + +-x:: +Displays the average packet rate, in packets/sec + +-y:: +Displays the average data rate, in bytes/sec + +-z:: +Displays the average packet size, in bytes + +include::diagnostic-options.adoc[] + +== EXAMPLES + +To see a description of the options use: + + capinfos -h + +To generate a long form report for the capture file +mycapture.pcap use: + + capinfos mycapture.pcap + +To generate a TAB delimited table form report for the capture +file mycapture.pcap use: + + capinfos -T mycapture.pcap + +To generate a CSV style table form report for the capture +file mycapture.pcap use: + + capinfos -T -m -Q mycapture.pcap + +or + + capinfos -TmQ mycapture.pcap + +To generate a TAB delimited table style report with just the +filenames, capture type, capture encapsulation type and packet +count for all the pcap files in the current directory use: + + capinfos -T -t -E -c *.pcap + +or + + capinfos -TtEc *.pcap + +Note: The ability to use of filename globbing characters are +a feature of *nix style command shells. + +To generate a CSV delimited table style report of all infos +for all pcap files in the current directory and write it to +a text file called mycaptures.csv use: + + capinfos -TmQ *.pcap >mycaptures.csv + +The resulting mycaptures.csv file can be easily imported +into spreadsheet applications. + +== SEE ALSO + +xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:mergecap.html[mergecap](1), xref:editcap.html[editcap](1), xref:tshark.html[tshark](1), +xref:dumpcap.html[dumpcap](1), xref:captype.html[captype](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 *Capinfos* {wireshark-version}. +*Capinfos* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Ian Schorr <ian[AT]ianschorr.com> + +.Contributors +[%hardbreaks] +Gerald Combs <gerald[AT]wireshark.org> +Jim Young <jyoung[AT]gsu.edu> diff --git a/doc/man_pages/captype.adoc b/doc/man_pages/captype.adoc new file mode 100644 index 00000000..94c07274 --- /dev/null +++ b/doc/man_pages/captype.adoc @@ -0,0 +1,73 @@ +include::../attributes.adoc[] += captype(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +captype - Prints the types of capture files + +== SYNOPSIS + +[manarg] +*captype* +<__infile__> +__...__ + +[manarg] +*captype* +*-h|--help* + +[manarg] +*captype* +*-v|--version* + +== DESCRIPTION + +*Captype* is a program that opens one or more capture files and +prints the capture file type of each <__infile__>. + +*Captype* is able to detect and read the same capture files that are +supported by *Wireshark*. +The input files don't need a specific filename extension; the file +format and an optional gzip, zstd or lz4 compression will be automatically detected. +Near the beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or +https://www.wireshark.org/docs/man-pages/wireshark.html +is a detailed description of the way *Wireshark* handles this, which is +the same way *Captype* handles this. + +== OPTIONS + +-h|--help:: +Print the version number and options and exit. + +-v|--version:: +Print the full version information and exit. + +include::diagnostic-options.adoc[] + +== SEE ALSO + +xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:mergecap.html[mergecap](1), xref:editcap.html[editcap](1), xref:tshark.html[tshark](1), +xref:dumpcap.html[dumpcap](1), xref:capinfos.html[capinfos](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 + +*Captype* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Ian Schorr <ian[AT]ianschorr.com> + +.Contributors +[%hardbreaks] +Gerald Combs <gerald[AT]wireshark.org> +Jim Young <jyoung[AT]gsu.edu> diff --git a/doc/man_pages/ciscodump.adoc b/doc/man_pages/ciscodump.adoc new file mode 100644 index 00000000..10ce4b69 --- /dev/null +++ b/doc/man_pages/ciscodump.adoc @@ -0,0 +1,324 @@ +include::../attributes.adoc[] += ciscodump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +ciscodump - Provide interfaces to capture from a remote Cisco device through SSH. + +== SYNOPSIS + +[manarg] +*ciscodump* +[ *--help* ] +[ *--version* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--extcap-capture-filter*=<capture filter> ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--remote-host*=<IP address> ] +[ *--remote-port*=<TCP port> ] +[ *--remote-username*=<username> ] +[ *--remote-password*=<password> ] +[ *--remote-filter*=<filter> ] +[ *--sshkey*=<public key path> ] +[ *--remote-interface*=<interface> ] +[ *--remote-count*=<count> ] + +[manarg] +*ciscodump* +*--extcap-interfaces* + +[manarg] +*ciscodump* +*--extcap-interface*=ciscodump +*--extcap-dlts* + +[manarg] +*ciscodump* +*--extcap-interface*=ciscodump +*--extcap-config* + +[manarg] +*ciscodump* +*--extcap-interface*=ciscodump +*--fifo*=<path to file or pipe> +*--capture* +*--remote-host*=remotedevice +*--remote-port*=22 +*--remote-username*=user +*--remote-interface*=<the device interface> +*--remote-count*=<count> + +== DESCRIPTION + +*Ciscodump* is an extcap tool that relies on Cisco EPC to allow a user to run a remote capture +on a Cisco device in a SSH connection. It supports IOS, IOS-XE based device and ASA devices. + +The tool configures capture on the device, reads data and removes configuration from the device. Provided credentials must allow the tool to configure the device. + +When capture is started, packets are provided as they are received from the device. Capture stops when: + +* requested count of packets is reached (*--remote-count* is mandatory) +* when capture finishes on the device (e.g. capture buffer is full) +* the capture is stopped by the user + +Capture performance depends on a device type. The tool tries to read packets as soon as they received, but is usually slower than capturing device captures packets. Therefore packets are read in batches. + +IOS/IOS-XE provides only access to all captured packets from the top. Therefore reading of second batch means to read all packets from first batch, but ignore them and then read new packets in second batch. + +ASA provides access to specific packet so tool reads every packet just once. + + +=== SUPPORTED CISCO SOFTWARE + +The application supports IOS version is 12.4 and higher. The IOS version supporting capture feature is 12.4(20)T and higher. More details can be +found here: https://www.cisco.com/c/en/us/products/collateral/ios-nx-os-software/ios-embedded-packet-capture/datasheet_c78-502727.html + +The application supports IOS-XE version 16.1 and higher. Search for "Embedded Packet Capture Configuration Guide, Cisco IOS XE" to get more details. + +The application supports ASA version 8.4 and higher. More details can be found here: https://community.cisco.com/t5/security-documents/asa-using-packet-capture-to-troubleshoot-asa-firewall/ta-p/3129889 + + +== OPTIONS + +--help:: +Print program arguments. + +--version:: +Print program version. + +--extcap-interfaces:: +List available interfaces. + +--extcap-interface=<interface>:: +Use specified interfaces. + +--extcap-dlts:: +List DLTs of specified interface. + +--extcap-config:: +List configuration options of specified interface. + +--capture:: +Start capturing from specified interface and save it in place specified by --fifo. + +--fifo=<path to file or pipe>:: +Save captured packet to file or send it through pipe. + +--remote-host=<remote host>:: +The address of the remote host for capture. + +--remote-port=<remote port>:: +The SSH port of the remote host. + +--remote-username=<username>:: +The username for ssh authentication. + +--remote-password=<password>:: +The password to use (if not ssh-agent and pubkey are used). WARNING: the +passwords are stored in plaintext and visible to all users on this system. It is +recommended to use keyfiles with a SSH agent. + +--remote-filter=<filter>:: ++ +-- +The remote filter on the device. This is a capture filter that follows the Cisco +standards. + +For IOS/IOS-XE see https://www.cisco.com/c/en/us/support/docs/ip/access-lists/26448-ACLsamples.html. + +For ASA see https://www.cisco.com/c/en/us/td/docs/security/asa/asa96/configuration/firewall/asa-96-firewall-config/access-acls.html. + +Multiple filters can be specified using a comma between them. BEWARE: when using +a filter, the default behavior is to drop all the packets except the ones that +fall into the filter. + +Examples for IOS/IOS-XE: + + permit ip host MYHOST any, permit ip any host MYHOST (capture the traffic for MYHOST) + + deny ip host MYHOST any, deny ip any host MYHOST, permit ip any any (capture all the traffic except MYHOST) + +Examples for ASA: + + permit any4 host MYHOST, permit host MYHOST any4 (capture IPv4 traffic for MYHOST) + +NOTE: Different capture types support or do not support specific ACL keywords. The tool is not able to check it, just tries to configure it. If error occurs, the tool just reports it and terminates. Debris are left in configuration in this case. +-- + +--sshkey=<SSH private key path>:: +The path to a private key for authentication. + +--remote-interface=<remote interface>:: ++ +-- +The remote network interface to capture from. One interface or list of interface names can be used. Interfaces are separated by comma. Interface names must be supported by the device. + +There are interface names causing different capture types. They are specific to used Cisco software. + +*IOS special names* + +* `process-switched` - capture process switched packets in both directions +* `from-us` - capture process switched packets originating at the device + +*IOS-XE special names* + +* `control-plane` - captures in/out packets touching control plane + +*ASA special names* + +* `asp-drop` - capture packets dropped by all asp categories +* `TYPE---ifname` - syntax to refer ASA capture types, see https://www.cisco.com/c/en/us/td/docs/security/asa/asa-cli-reference/A-H/asa-command-ref-A-H/ca-cld-commands.html#wp2435483314 +** `isakmp---ifname` - capture isakmp packets +** `lacp---ifname` - capture lacp packets (just physical interfaces are supported) +** `tls-proxy---ifname` - capture tls-proxy packets +** `inline-tag---ifname` - capture all SGT tagged packets +** `raw-data---ifname` - same as `ifname` +* syntax to capture decrypted traffic for some of capture types: +** `isakmp/decrypted---ifname` - capture isakmp packets including decrypted payload +** `tls-proxy/decrypted---ifname` - capture tls-proxy packets including decrypted payload +** `inline-tag/decrypted---ifname` - capture inline-tag packets including decrypted payload +** `raw-data/decrypted---ifname` - capture raw-data packets including decrypted payload + +Use e. g. `isakmp/decrypted---outside` to capture encrypted and decrypted isakmp traffic on `outside` interface. +-- + +--remote-count=<count>:: +Count of packets to capture. Capture is stopped when count is reached. + +--extcap-capture-filter=<capture filter>:: +Unused (compatibility only). + +== EXAMPLES + +To see program arguments: + + ciscodump --help + +To see program version: + + ciscodump --version + +To see interfaces: + + ciscodump --extcap-interfaces + +Only one interface (ciscodump) is supported. + +.Example output + interface {value=ciscodump}{display=SSH remote capture} + +To see interface DLTs: + + ciscodump --extcap-interface=ciscodump --extcap-dlts + +.Example output + dlt {number=147}{name=ciscodump}{display=Remote capture dependent DLT} + +To see interface configuration options: + + ciscodump --extcap-interface=ciscodump --extcap-config + +.Example output + ciscodump --extcap-interface=ciscodump --extcap-config + arg {number=0}{call=--remote-host}{display=Remote SSH server address} + {type=string}{tooltip=The remote SSH host. It can be both an IP address or a hostname} + {required=true}{group=Server} + arg {number=1}{call=--remote-port}{display=Remote SSH server port} + {type=unsigned}{default=22}{tooltip=The remote SSH host port (1-65535)} + {range=1,65535}{group=Server} + arg {number=2}{call=--remote-username}{display=Remote SSH server username} + {type=string}{default=<current user>}{tooltip=The remote SSH username. If not provided, the current user will be used} + {group=Authentication} + arg {number=3}{call=--remote-password}{display=Remote SSH server password} + {type=password}{tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.} + {group=Authentication} + arg {number=4}{call=--sshkey}{display=Path to SSH private key} + {type=fileselect}{tooltip=The path on the local filesystem of the private ssh key} + {group=Authentication} + arg {number=5}{call=--proxycommand}{display=ProxyCommand} + {type=string}{tooltip=The command to use as proxy for the SSH connection}{group=Authentication} + arg {number=6}{call--sshkey-passphrase}{display=SSH key passphrase} + {type=password}{tooltip=Passphrase to unlock the SSH private key}{group=Authentication + arg {number=7}{call=--remote-interface}{display=Remote interface} + {type=string}{tooltip=The remote network interface used for capture} + {required=true}{group=Capture} + arg {number=8}{call=--remote-filter}{display=Remote capture filter} + {type=string}{tooltip=The remote capture filter}{default=<filter to exclude current host>} + {group=Capture} + arg {number=9}{call=--remote-count}{display=Packets to capture} + {type=unsigned}{tooltip=The number of remote packets to capture.} + {required=true}{group=Capture} + arg {number=10}{call=--debug}{display=Run in debug mode} + {type=boolflag}{default=false}{tooltip=Print debug messages} + {required=false}{group=Debug} + arg {number=11}{call=--debug-file}{display=Use a file for debug} + {type=string}{tooltip=Set a file where the debug messages are written} + {required=false}{group=Debug} + +To capture on IOS/IOS-XE: + + ciscodump --extcap-interface ciscodump --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10 + --remote-username user --remote-interface gigabit0/0,gigiabit0/1 + --remote-filter "permit ip host 192.168.1.1 any, permit ip any host 192.168.1.1" + --remote-count=10 + +To capture on IOS/IOS-XE: + + ciscodump --extcap-interface ciscodump --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10 + --remote-username user --remote-interface outside,dmz + --remote-filter "permit host 192.168.1.1 any4, permit any4 host 192.168.1.1" + --remote-count=10 + + ciscodump --extcap-interface ciscodump --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10 + --remote-username user --remote-interface raw-data/decrypted---outside + --remote-filter "permit host 192.168.1.1 any4, permit any4 host 192.168.1.1" + +== KNOWN ISSUES + +When capture stopped by the user before it finishes on Windows platform, configuration is not cleared on the device. Next run will probably fails because parts of configuration already exists on the device. + +Reading performance on IOS/IOS-XE is poor because re-reading of capture buffer over and over. + +The configuration of the capture on the device is a multi-step process. If the SSH connection is interrupted during +it, the configuration can be in an inconsistent state. That can happen also if the capture is stopped and ciscodump +can't clean the configuration up. In this case it is necessary to log into the device and manually clean the +configuration, removing configuration elements: + +* IOS +** capture points WSC_P_<number> (depends on count of capture interfaces) +** the capture buffer WSC_B +** the capture capture acl WSC_ACL (if filter was used) +* IOS-XE +** the capture WSC +** the capture capture acl WSC_ACL (if filter was used) +* ASA +** the capture WSC +** the capture capture acl WSC_ACL (if filter was used) + +On IOS platforms, only IPv4 commands issued and only IPv4 packets are captured. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4), xref:sshdump.html[sshdump](1) + +== NOTES + +*ciscodump* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Dario Lombardo <lomato[AT]gmail.com> diff --git a/doc/man_pages/diagnostic-options.adoc b/doc/man_pages/diagnostic-options.adoc new file mode 100644 index 00000000..1500168f --- /dev/null +++ b/doc/man_pages/diagnostic-options.adoc @@ -0,0 +1,24 @@ +== DIAGNOSTIC OPTIONS + +--log-level <level>:: Set the active log level. +Supported levels in lowest to highest order are "noisy", "debug", "info", "message", "warning", "critical", and "error". +Messages at each level and higher will be printed, for example "warning" prints "warning", "critical", and "error" messages and "noisy" prints all messages. +Levels are case insensitive. + +--log-fatal <level>:: Abort the program if any messages are logged at the specified level or higher. +For example, "warning" aborts on any "warning", "critical", or "error" messages. + +// XXX List available domains if no list is provided? +--log-domains <list>:: Only print messages for the specified log domains, e.g. "GUI,Epan,sshdump". +List of domains must be comma-separated. Can be negated with "!" as the first character (inverts the match). + +--log-debug <list>:: Force the specified domains to log at the "debug" level. +List of domains must be comma-separated. Can be negated with "!" as the first character (inverts the match). + +--log-noisy <list>:: Force the specified domains to log at the "noisy" level. +List of domains must be comma-separated. Can be negated with "!" as the first character (inverts the match). + +--log-fatal-domains <list>:: Abort the program if any messages are logged for the specified log domains. +List of domains must be comma-separated. + +--log-file <path>:: Write log messages and stderr output to the specified file. diff --git a/doc/man_pages/dissection-options.adoc b/doc/man_pages/dissection-options.adoc new file mode 100644 index 00000000..f46a06af --- /dev/null +++ b/doc/man_pages/dissection-options.adoc @@ -0,0 +1,188 @@ +== DISSECTION OPTIONS + +// tag::decode_as[] +[#decode_as] +-d <layer type>==<selector>,<decode-as protocol>:: ++ +-- +Like Wireshark's *Decode As...* feature, this lets you specify how a +layer type should be dissected. If the layer type in question (for example, +*tcp.port* or *udp.port* for a TCP or UDP port number) has the specified +selector value, packets should be dissected as the specified protocol. + +.Decode As Port +[example] +*-d tcp.port==8888,http* will decode any traffic running over +TCP port 8888 as HTTP. + +// tag::tshark[] +.Decode As Port Range +[example] +*-d tcp.port==8888-8890,http* will decode any traffic running +over TCP ports 8888, 8889 or 8890 as HTTP. + +.Decode As Port Range via Length +[example] +*-d tcp.port==8888:3,http* will decode any traffic running over +the three TCP ports 8888, 8889 or 8890 as HTTP. + +Using an invalid selector or protocol will print out a list of valid selectors +and protocol names, respectively. + +.Decode As List of Selectors +[example] +*-d .* is a quick way to get a list of valid selectors. + +.Decode As List of Values for a Selector +[example] +*-d ethertype==0x0800,.* is a quick way to get a list of protocols +that can be selected with an ethertype. +// end::tshark[] +// tag::not_tshark[] +See the xref:tshark.html#decode_as[tshark](1) manual page for more examples. +// end::not_tshark[] +-- +// end::decode_as[] + +--disable-all-protocols:: +Disable dissection of all protocols. + +--disable-protocol <proto_name>[,<proto_name>,...]:: +Disable dissection of proto_name. +Use a proto_name of *ALL* to override +your chosen profile's default enabled protocol list and temporarily +disable all protocols. + +--disable-heuristic <short_name>:: +Disable dissection of heuristic protocol. + +--enable-protocol <proto_name>[,<proto_name>,...]:: ++ +-- +Enable dissection of proto_name. +Use a proto_name of *ALL* to override +your chosen profile's default disabled protocol list and temporarily +enable all protocols which are enabled by default. + +If a protocol is implicated in both *--disable-protocol* +and *--enable-protocol*, the protocol is enabled. This allows you to +temporarily disable all protocols but a list of exceptions. +Example: *--disable-protocol ALL --enable-protocol eth,ip* +-- + +--enable-heuristic <short_name>:: +Enable dissection of heuristic protocol. + +-K <keytab>:: ++ +-- +Load kerberos crypto keys from the specified keytab file. +This option can be used multiple times to load keys from several files. + +Example: *-K krb5.keytab* +-- + +-n:: +Disable network object name resolution (such as hostname, TCP and UDP port +names); the *-N* option might override this one. + +-N <name resolving flags>:: ++ +-- +Turn on name resolving only for particular types of addresses and port +numbers, with name resolving for other types of addresses and port +numbers turned off. This option (along with *-n*) can be specified +multiple times; the last value given overrides earlier ones. This option +and *-n* override the options from the preferences, including preferences +set via the *-o* option. If both *-N* and *-n* options are not present, +the values from the preferences are used, which default to *-N dmN*. + +The argument is a string that may contain the letters: + +*d* to enable resolution from captured DNS packets + +*g* to enable IP address geolocation information lookup from configured +MaxMind databases + +*m* to enable MAC address resolution + +*n* to enable network address resolution + +*N* to enable using external resolvers (e.g., DNS) for network address +resolution; no effect without *n* also enabled. + +*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 + +// tag::tshark[] +[CAUTION] +In tshark single-pass mode, external resolution and geolocation lookup is +performed synchronously. For live captures, which are always in single-pass +mode, this makes it more difficult for dissection to keep up with a busy +network, possibly leading to dropped packets. +// end::tshark[] +-- + +--only-protocols <protocols>:: +Only enable dissection of these protocols, comma separated. Disable everything else. + +-t (a|ad|adoy|d|dd|e|r|u|ud|udoy)[.[N]]|.[N]:: ++ +-- +Set the format of the packet timestamp displayed in the default time +column. The format can be one of: + +*a* absolute: The absolute time, as local time in your time zone, +is the actual time the packet was captured, with no date displayed + +*ad* absolute with date: The absolute date, displayed as YYYY-MM-DD, +and time, as local time in your time zone, is the actual time and date +the packet was captured + +*adoy* absolute with date using day of year: The absolute date, +displayed as YYYY/DOY, and time, as local time in your time zone, +is the actual time and date the packet was captured + +*d* delta: The delta time is the time since the previous packet was +captured + +*dd* delta_displayed: The delta_displayed time is the time since the +previous displayed packet was captured + +*e* epoch: The time in seconds since epoch (Jan 1, 1970 00:00:00) + +*r* relative: The relative time is the time elapsed between the first packet +and the current packet + +*u* UTC: The absolute time, as UTC, is the actual time the packet was +captured, with no date displayed + +*ud* UTC with date: The absolute date, displayed as YYYY-MM-DD, +and time, as UTC, is the actual time and date the packet was captured + +*udoy* UTC with date using day of year: The absolute date, displayed +as YYYY/DOY, and time, as UTC, is the actual time and date the packet +was captured + +*.[N]* Set the precision: N is the number of decimals (0 through 9). +If using "." without N, automatically determine precision from trace. + +The default format is relative with precision based on capture format. +-- + +-u <s|hms>:: ++ +-- +Specifies how packet timestamp formats in *-t* which are relative times +(i.e. relative, delta, and delta_displayed) are displayed. Valid choices are: + +*s* for seconds + +*hms* for hours, minutes, and seconds + +The default format is seconds. +-- diff --git a/doc/man_pages/dpauxmon.adoc b/doc/man_pages/dpauxmon.adoc new file mode 100644 index 00000000..9d2a9e5c --- /dev/null +++ b/doc/man_pages/dpauxmon.adoc @@ -0,0 +1,142 @@ +include::../attributes.adoc[] += dpauxmon(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +dpauxmon - Provide interfaces to capture DisplayPort AUX channel data. + +== SYNOPSIS + +[manarg] +*dpauxmon* +[ *--help* ] +[ *--version* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--extcap-capture-filter*=<capture filter> ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--interface_id*=<Interface ID to capture> ] + +[manarg] +*dpauxmon* +*--extcap-interfaces* + +[manarg] +*dpauxmon* +*--extcap-interface*=<interface> +*--extcap-dlts* + +[manarg] +*dpauxmon* +*--extcap-interface*=<interface> +*--extcap-config* + +[manarg] +*dpauxmon* +*--extcap-interface*=<interface> +*--fifo*=<path to file or pipe> +*--capture* +*--interface_id=interface_id* + +== DESCRIPTION + +*dpauxmon* is an extcap tool that can capture DisplayPort AUX channel data +from linux kernel drivers using the generic netlink interface. + +Supported interfaces: + +1. dpauxmon + +== OPTIONS + +--help:: +Print program arguments. + +--version:: +Print program version. + +--extcap-interfaces:: +List available interfaces. + +--extcap-interface=<interface>:: +Use specified interfaces. + +--extcap-dlts:: +List DLTs of specified interface. + +--extcap-config:: +List configuration options of specified interface. + +--capture:: +Start capturing from specified interface and save it in place specified by --fifo. + +--fifo=<path to file or pipe>:: +Save captured packet to file or send it through pipe. + +--interface_idt=<interface id>:: +The interface for capture. + +== EXAMPLES + +To see program arguments: + + dpauxmon --help + +To see program version: + + dpauxmon --version + +To see interfaces: + + dpauxmon --extcap-interfaces + +Only one interface (dpauxmon) is supported. + +.Example output + interface {value=dpauxmon}{display=DisplayPort AUX channel capture} + +To see interface DLTs: + + dpauxmon --extcap-interface=dpauxmon --extcap-dlts + +.Example output + dlt {number=275}{name=dpauxmon}{display=DisplayPort AUX channel monitor DLT} + +To see interface configuration options: + + dpauxmon --extcap-interface=dpauxmon --extcap-config + +.Example output + dpauxmon --extcap-interface=dpauxmon --extcap-config + arg {number=0}{call=--interface_id}{display=Interface Id} + {type=unsigned}{tooltip=The Interface Id} + {required=true} + +To capture: + + dpauxmon --extcap-interface=dpauxmon --fifo=/tmp/dpauxmon.pcap --capture --interface_id 0 + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4) + +== NOTES + +*dpauxmon* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Dirk Eibach <dirk.eibach[AT]gdsys.cc> diff --git a/doc/man_pages/dumpcap.adoc b/doc/man_pages/dumpcap.adoc new file mode 100644 index 00000000..9fdcf72c --- /dev/null +++ b/doc/man_pages/dumpcap.adoc @@ -0,0 +1,504 @@ +include::../attributes.adoc[] += dumpcap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +dumpcap - Dump network traffic + +== SYNOPSIS + +[manarg] +*dumpcap* +[ *-a*|*--autostop* <capture autostop condition> ] ... +[ *-b*|*--ring-buffer* <capture ring buffer option> ] ... +[ *-B*|*--buffer-size* <capture buffer size> ] +[ *-c* <capture packet count> ] +[ *-C* <byte limit> ] +[ *-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* ] +[ *-k* <freq>,[<type>],[<center_freq1>],[<center_freq2>] ] +[ *-L*|*--list-data-link-types* ] +[ *-M* ] +[ *-n* ] +[ *-N* <packet limit> ] +[ *-p*|*--no-promiscuous-mode* ] +[ *--ifdescr* <description> ] +[ *--ifname* <name> ] +[ *-P* ] +[ *-q* ] +[ *-Q* ] +[ *-s*|*--snapshot-length* <capture snaplen> ] +[ *-S* ] +[ *-t* ] +[ *--temp-dir* <directory> ] +[ *-w* <outfile> ] +[ *-y*|*--linktype* <capture link type> ] +[ *--capture-comment* <comment> ] +[ *--list-time-stamp-types* ] +[ *--time-stamp-type* <type> ] +[ *--update-interval* <interval> ] + +[manarg] +*dumpcap* +*-h|--help* + +[manarg] +*dumpcap* +*-v|--version* + +== DESCRIPTION + +*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. 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 +the received raw packet data, along with the packets' time stamps into a +capture file. + +If the *-w* option is not specified, *Dumpcap* writes to a newly +created capture file with a randomly chosen name. +If the *-w* option is specified, *Dumpcap* writes to the file +specified by that option. + +Packet capturing is performed with the pcap library. The capture filter +syntax follows the rules of the pcap library. + +== OPTIONS + +-a|--autostop <capture autostop condition>:: ++ +-- +Specify a criterion that specifies when *Dumpcap* 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, 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 TB. + +*packets*:__value__ Stop writing to a capture file after __value__ packets +have been written. Acts the same as *-c* <capture packet count>. +-- + +-b|--ring-buffer <capture ring buffer option>:: ++ +-- +Cause *Dumpcap* to run in "multiple files" mode. In "multiple files" mode, +*Dumpcap* will write to several capture files. When the first capture file +fills up, *Dumpcap* will switch writing to the next file and so on. + +The created filenames are based on the filename given with the *-w* +option, the number of the file and on the creation date and time, e.g. +outfile_00001_20240714120117.pcapng, +outfile_00002_20240714120523.pcapng, ... + +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 *Dumpcap* will discard the data in the first file and start +writing to that file and so on. If the __files__ option is not set, +new files filled up until one of the capture stop conditions match (or +until the disk is full). + +The criterion is of the form __key:value__, +where __key__ is one of: + +*duration*:__value__ switch to the next file after __value__ seconds have +elapsed, even if the current file is not completely filled up. Floating +point values (e.g. 0.5) are allowed. + +*files*:__value__ begin again with the first file after __value__ number of +files were written (form a ring buffer). This value must be less than 100000. +Caution should be used when using large numbers of files: some filesystems do +not handle many files in a single directory well. The *files* criterion +requires either *duration*, *interval* or *filesize* to be specified to +control when to go to the next file. It should be noted that each *-b* +parameter takes exactly one criterion; to specify two criterion, each must be +preceded by the *-b* option. + +*filesize*:__value__ switch to the next file after it reaches a size of +__value__ kB. Note that the filesize is limited to a maximum value of 2 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 +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. + +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 *Dumpcap* 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 <byte limit>:: +Limit the amount of memory in bytes used for storing captured packets +in memory while processing it. +If used in combination with the *-N* option, both limits will apply. +Setting this limit will enable the usage of the separate thread per interface. + +-d:: +Dump the code generated for the capture filter in a human-readable form, +and exit. + +-D|--list-interfaces:: +Print a list of the interfaces on which *Dumpcap* 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. + +-f <capture filter>:: ++ +-- +Set the capture filter expression. + +The entire filter expression must be specified as a single argument (which means +that if it contains spaces, it must be quoted). + +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. +-- + +-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 +user's group). + +-h|--help:: +Print the version number and options and exit. + +-i|--interface <capture interface>|rpcap://<host>:<port>/<capture interface>|TCP@<host>:<port>|-:: ++ +-- +Set the name of the network interface or pipe to use for live packet +capture. + +Network interface names should match one of the names listed in "*tshark +-D*" (described above); a number, as reported by "*dumpcap -D*", can +also be used. + +If no interface is specified, *Dumpcap* 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, +*Dumpcap* 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 *Dumpcap* 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, even if +*-P* is specified. +-- + +--ifdescr> <description>:: +Use __description__ as the description in the capture file for the +interface or pipe specified before it with *-i*. + +--ifname> <name>:: +Use __name__ as the name in the capture file for the interface or +pipe specified before it with *-i*. + +-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. +-- + +-k <freq>,[<type>],[<center_freq1>],[<center_freq2>>:: ++ +-- +Set the channel on the interface; this is supported only on IEEE +802.11 Wi-Fi interfaces, and supported only on some operating systems. + +__freq__ is the frequency of the channel. __type__ is the type of the +channel, for 802.11n and 802.11ac. The values for __type__ are +-- + +NOHT:: Used for non-802.11n/non-802.1ac channels + +HT20:: 20 MHz channel + +HT40-:: 40 MHz primary channel and a lower secondary channel + +HT40+:: 40 MHz primary channel and a higher secondary channel + +HT80:: 80 MHz channel, with __centerfreq1__ as its center frequency + +VHT80+80:: +Two 80 MHz channels combined, with __centerfreq1__ and __centerfreq2__ as +the center frequencies of the two channels + +VHT160:: 160 MHz channel, with __centerfreq1__ as its center frequency + +-L|--list-data-link-types:: +List the data link types supported by the interface and exit. The reported +link types can be used for the *-y* option. + +-M:: ++ +-- +When used with *-D*, *-L*, *-S* or *--list-time-stamp-types* print +machine-readable output. +The machine-readable output is intended to be read by *Wireshark* and +*TShark*; its format is subject to change from release to release. +-- + +-n:: +Save files as pcapng. This is the default. This option is deprecated +and may be removed. + +-N <packet limit>:: ++ +-- +Limit the number of packets used for storing captured packets +in memory while processing it. +If used in combination with the *-C* option, both limits will apply. +Setting this limit will enable the usage of the separate thread per interface. +-- + +-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 *Dumpcap* 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:: +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. This option is deprecated in favor of the *-F* option and +may be removed. + +-q:: ++ +-- +When capturing packets, don't display the continuous count of packets +captured that is normally shown when saving a capture to a file; +instead, just display, at the end of the capture, a count of packets +captured. 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). +-- + +-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>:: ++ +-- +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:: +Print statistics for each interface once every second. + +-t:: +Use a separate thread per interface. + +--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__. +-- + +-v|--version:: +Print the full version information and exit. + +-w <outfile>:: +Write raw packet data to __outfile__. Use "-" for stdout. + +-y|--linktype <capture link type>:: ++ +-- +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. +-- + +--capture-comment <comment>:: ++ +-- +Add a capture comment to the output file, if supported by the output +file format. + +This option is only available if we output the captured packets to a +single file. + +This option may be specified multiple times. Note that Wireshark +currently only displays the first comment of a capture file. +-- + +--list-time-stamp-types:: +List time stamp types supported for the interface. If no time stamp type can be +set, no time stamp types are listed. + +--time-stamp-type <type>:: +Change the interface's timestamp method. + +--update-interval <interval>:: +Set the length of time in milliseconds between new packet reports during +a capture. Also sets the granularity of file duration conditions. +The default value is 100ms. + +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. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:editcap.html[editcap](1), xref:mergecap.html[mergecap](1), xref:capinfos.html[capinfos](1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), +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 *Dumpcap* {wireshark-version}. +*Dumpcap* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +*Dumpcap* is derived from the *Wireshark* capturing engine code; +see the list of +authors in the *Wireshark* man page for a list of authors of that code. diff --git a/doc/man_pages/editcap.adoc b/doc/man_pages/editcap.adoc new file mode 100644 index 00000000..5b4be3fc --- /dev/null +++ b/doc/man_pages/editcap.adoc @@ -0,0 +1,664 @@ +include::../attributes.adoc[] += editcap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +editcap - Edit and/or translate the format of capture files + +== SYNOPSIS + +[manarg] +*editcap* +[ *-a* <frame:comment> ] +[ *-A* <start time> ] +[ *-B* <stop time> ] +[ *-c* <packets per file> ] +[ *-C* [offset:]<choplen> ] +[ *-E* <error probability> ] +[ *-F* <file format> ] +[ *-i* <seconds per file> ] +[ *-o* <change offset> ] +[ *-L* ] +[ *-r* ] +[ *-s* <snaplen> ] +[ *-S* <strict time adjustment> ] +[ *-t* <time adjustment> ] +[ *-T* <encapsulation type> ] +[ *-V* ] +[ *--inject-secrets* <secrets type>,<file> ] +[ *--discard-all-secrets* ] +[ *--capture-comment* <comment> ] +[ *--discard-capture-comment* ] +[ *--discard-packet-comments* ] +__infile__ +__outfile__ +[ __packet#__[-__packet#__] ... ] + +[manarg] +*editcap* +*-d* +*-D* <dup window> +*-w* <dup time window> +[ *-V* ] +[ *-I* <bytes to ignore> ] +[ *--skip-radiotap-header* ] +[ *--set-unused* ] +__infile__ +__outfile__ + +[manarg] +*editcap* +*--extract-secrets* +[ *-V* ] +__infile__ +__outfile__ + +[manarg] +*editcap* +*-h|--help* + +[manarg] +*editcap* +*-v|--version* + +== DESCRIPTION + +*Editcap* is a program that reads some or all of the captured packets from the +__infile__, optionally converts them in various ways and writes the +resulting packets to the capture __outfile__ (or outfiles). + +By default, it reads all packets from the __infile__ and writes them to the +__outfile__ in pcapng file format. Use '-' for __infile__ or __outfile__ +to read from standard input or write to standard output, respectively. + +The *-A* and *-B* option allow you to limit the time range from which packets +are read from the __infile__. + +An optional list of packet numbers can be specified on the command tail; +individual packet numbers separated by whitespace and/or ranges of packet +numbers can be specified as __start__-__end__, referring to all packets from +__start__ to __end__. By default the selected packets with those numbers will +__not__ be written to the capture file. If the *-r* flag is specified, the +whole packet selection is reversed; in that case __only__ the selected packets +will be written to the capture file. + +*Editcap* can also be used to remove duplicate packets. Several different +options (*-d*, *-D* and *-w*) are used to control the packet window +or relative time window to be used for duplicate comparison. + +*Editcap* can be used to assign comment strings to frame numbers. + +*Editcap* is able to detect, read and write the same capture files that +are supported by *Wireshark*. +The input file doesn't need a specific filename extension; the file +format and an optional gzip, zstd or lz4 compression will be automatically detected. +Near the beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or +https://www.wireshark.org/docs/man-pages/wireshark.html +is a detailed description of the way *Wireshark* handles this, which is +the same way *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 + +-a <framenum:comment>:: ++ +-- +For the specified frame number, assign the given comment string. +Can be repeated for multiple frames. Quotes should be used with comment +strings that include spaces. +-- + +-A <start time>:: ++ +-- +Reads only the packets whose timestamp is on or after <start time>. +The time may be given either in ISO 8601 format or in Unix epoch +timestamp format. + +ISO 8601 format is either + + YYYY-MM-DD HH:MM:SS[.nnnnnnnnn][Z|±hh:mm] + +or + + YYYY-MM-DDTHH:MM:SS[.nnnnnnnnn][Z|±hh:mm] + +The fractional seconds are optional, as is the time zone offset from UTC +(in which case local time is assumed). + +Unix epoch format is in seconds since the Unix epoch and nanoseconds, +with either a period or a comma separating the seconds and nanoseconds. +The nanoseconds are optional. +The Unix epoch is 1970-01-01 00:00:00 UTC, so this format is not local +time. +-- + +-B <stop time>:: ++ +-- +Reads only the packets whose timestamp is before <stop time>. +The time may be given either in ISO 8601 format or in Unix epoch +timestamp format. + +ISO 8601 format is either + + YYYY-MM-DD HH:MM:SS[.nnnnnnnnn][Z|±hh:mm] + +or + + YYYY-MM-DDTHH:MM:SS[.nnnnnnnnn][Z|±hh:mm] + +The fractional seconds are optional, as is the time zone offset from UTC +(in which case local time is assumed). + +Unix epoch format is in seconds since the Unix epoch and nanoseconds, +with either a period or a comma separating the seconds and nanoseconds. +The nanoseconds are optional. +The Unix epoch is 1970-01-01 00:00:00 UTC, so this format is not local +time. +-- + +-c <packets per file>:: ++ +-- +Splits the packet output to different files based on uniform packet counts +with a maximum of <packets per file> each. + +Each output file will be created with an infix _nnnnn[_YYYYmmddHHMMSS] inserted +before the file extension (which may be null) of __outfile__. The infix +consists of the ordinal number of the output file, starting with 00000, +followed by the timestamp of its first packet. The timestamp is omitted if +the input file does not contain timestamp information. + +After the specified number of packets is written to the output file, the next +output file is opened. The default is to use a single output file. +This option conflicts with *-i*. +-- + +-C [offset:]<choplen>:: ++ +-- +Sets the chop length to use when writing the packet data. Each packet is +chopped by <choplen> bytes of data. Positive values chop at the packet +beginning while negative values chop at the packet end. + +If an optional offset precedes the <choplen>, then the bytes chopped will be +offset from that value. Positive offsets are from the packet beginning, while +negative offsets are from the packet end. + +This is useful for chopping headers for decapsulation of an entire capture, +removing tunneling headers, or in the rare case that the conversion between two +file formats leaves some random bytes at the end of each packet. Another use is +for removing vlan tags. + +NOTE: This option can be used more than once, effectively allowing you to chop +bytes from up to two different areas of a packet in a single pass provided that +you specify at least one chop length as a positive value and at least one as a +negative value. All positive chop lengths are added together as are all +negative chop lengths. +-- + +-d:: ++ +-- +Attempts to remove duplicate packets. The length and MD5 hash of the +current packet are compared to the previous four (4) packets. If a +match is found, the current packet is skipped. This option is equivalent +to using the option *-D 5*. +-- + +-D <dup window>:: ++ +-- +Attempts to remove duplicate packets. The length and MD5 hash of the +current packet are compared to the previous <dup window> - 1 packets. +If a match is found, the current packet is skipped. + +The use of the option *-D 0* combined with the *-V* option is useful +in that each packet's Packet number, Len and MD5 Hash will be printed +to standard error. This verbose output (specifically the MD5 hash strings) +can be useful in scripts to identify duplicate packets across trace +files. + +The <dup window> is specified as an integer value between 0 and 1000000 (inclusive). + +NOTE: Specifying large <dup window> values with large tracefiles can +result in very long processing times for *editcap*. +-- + +-E <error probability>:: ++ +-- +Sets the probability that bytes in the output file are randomly changed. +*Editcap* uses that probability (between 0.0 and 1.0 inclusive) +to apply errors to each data byte in the file. For instance, a +probability of 0.02 means that each byte has a 2% chance of having an error. + +This option is meant to be used for fuzz-testing protocol dissectors. +-- + +-F <file format>:: ++ +-- +Sets the file format of the output capture file. +*Editcap* can write the file in several formats, *editcap -F* +provides a list of the available output formats. The default +is the *pcapng* format. +-- + +-h|--help:: +Print the version number and options and exit. + +-i <seconds per file>:: ++ +-- +Splits the packet output to different files based on uniform time +intervals using a maximum interval of <seconds per file> each. Floating +point values (e.g. 0.5) are allowed. + +Each output file will be created with an infix _nnnnn[_YYYYmmddHHMMSS] inserted +before the file extension (which may be null) of __outfile__. The infix +consists of the ordinal number of the output file, starting with 00000, +followed by the timestamp of its first packet. The timestamp is omitted if +the input file does not contain timestamp information. + +After packets for the specified time interval are written to the output file, +the next output file is opened. The default is to use a single output file. +This option conflicts with *-c*. +-- + +-I <bytes to ignore>:: ++ +-- +Ignore the specified number of bytes at the beginning of the frame during MD5 hash calculation, +unless the frame is too short, then the full frame is used. +Useful to remove duplicated packets taken on several routers (different mac addresses for example) +e.g. -I 26 in case of Ether/IP will ignore ether(14) and IP header(20 - 4(src ip) - 4(dst ip)). +The default value is 0. +-- + +-L:: ++ +-- +Adjust the original frame length accordingly when chopping and/or snapping +(in addition to the captured length, which is always adjusted regardless of +whether *-L* is specified or not). See also *-C <choplen*> and *-s <snaplen*>. +-- + +-o <change offset>:: ++ +-- +When used in conjunction with -E, skip some bytes from the beginning of the packet +from being changed. In this way some headers don't get changed, and the fuzzer is +more focused on a smaller part of the packet. Keeping a part of the packet fixed +the same dissector is triggered, that make the fuzzing more precise. +-- + +-r:: ++ +-- +Reverse the packet selection. +Causes the packets whose packet numbers are specified on the command +line to be written to the output capture file, instead of discarding them. +-- + +-s <snaplen>:: ++ +-- +Sets the snapshot length to use when writing the data. +If the *-s* flag is used to specify a snapshot length, packets in the +input file with more captured data than the specified snapshot length +will have only the amount of data specified by the snapshot length +written to the output file. + +This may be useful if the program that is +to read the output file cannot handle packets larger than a certain size +(for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6 +appear to reject Ethernet packets larger than the standard Ethernet MTU, +making them incapable of handling gigabit Ethernet captures if jumbo +packets were used). +-- + +--seed <seed>:: ++ +-- +When used in conjunction with -E, set the seed for the pseudo-random number generator. +This is useful for recreating a particular sequence of errors. +-- + +--skip-radiotap-header:: ++ +-- +Skip the radiotap header of each frame when checking for packet duplicates. This is useful +when processing a capture created by combining outputs of multiple capture devices on the same +channel in the vicinity of each other. +-- + +-S <strict time adjustment>:: ++ +-- +Time adjust selected packets to ensure strict chronological order. + +The <strict time adjustment> value represents relative seconds +specified as [-]__seconds__[__.fractional seconds__]. + +As the capture file is processed each packet's absolute time is +__possibly__ adjusted to be equal to or greater than the previous +packet's absolute timestamp depending on the <strict time +adjustment> value. + +If <strict time adjustment> value is 0 or greater (e.g. 0.000001) +then *only* packets with a timestamp less than the previous packet +will adjusted. The adjusted timestamp value will be set to be +equal to the timestamp value of the previous packet plus the value +of the <strict time adjustment> value. A <strict time adjustment> +value of 0 will adjust the minimum number of timestamp values +necessary to ensure that the resulting capture file is in +strict chronological order. + +If <strict time adjustment> value is specified as a +negative value, then the timestamp values of *all* +packets will be adjusted to be equal to the timestamp value +of the previous packet plus the absolute value of the +<strict time adjustment> value. A <strict time +adjustment> value of -0 will result in all packets +having the timestamp value of the first packet. + +This feature is useful when the trace file has an occasional +packet with a negative delta time relative to the previous +packet. +-- + +-t <time adjustment>:: ++ +-- +Sets the time adjustment to use on selected packets. +If the *-t* flag is used to specify a time adjustment, the specified +adjustment will be applied to all selected packets in the capture file. +The adjustment is specified as [-]__seconds__[__.fractional seconds__]. +For example, *-t* 3600 advances the timestamp on selected packets by one +hour while *-t* -0.5 reduces the timestamp on selected packets by +one-half second. + +This feature is useful when synchronizing dumps +collected on different machines where the time difference between the +two machines is known or can be estimated. +-- + +-T <encapsulation type>:: ++ +-- +Sets the packet encapsulation type of the output capture file. +If the *-T* flag is used to specify an encapsulation type, the +encapsulation type of the output capture file will be forced to the +specified type. +*editcap -T* provides a list of the available types. The default +type is the one appropriate to the encapsulation type of the input +capture file. + +Note: this merely +forces the encapsulation type of the output file to be the specified +type; the packet headers of the packets will not be translated from the +encapsulation type of the input capture file to the specified +encapsulation type (for example, it will not translate an Ethernet +capture to an FDDI capture if an Ethernet capture is read and '*-T + fddi*' is specified). If you need to remove/add headers from/to a +packet, you will need od(1)/xref:text2pcap.html[text2pcap](1). +-- + +-v|--version:: +Print the full version information and exit. + +-V:: ++ +-- +Causes *editcap* to print verbose messages while it's working. + +Use of *-V* with the de-duplication switches of *-d*, *-D* or *-w* +will cause all MD5 hashes to be printed whether the packet is skipped +or not. +-- + +-w <dup time window>:: ++ +-- +Attempts to remove duplicate packets. The current packet's arrival time +is compared with up to 1000000 previous packets. If the packet's relative +arrival time is __less than or equal to__ the <dup time window> of a previous packet +and the packet length and MD5 hash of the current packet are the same then +the packet to skipped. The duplicate comparison test stops when +the current packet's relative arrival time is greater than <dup time window>. + +The <dup time window> is specified as __seconds__[__.fractional seconds__]. + +The [.fractional seconds] component can be specified to nine (9) decimal +places (billionths of a second) but most typical trace files have resolution +to six (6) decimal places (millionths of a second). + +NOTE: Specifying large <dup time window> values with large tracefiles can +result in very long processing times for *editcap*. + +NOTE: The *-w* option assumes that the packets are in chronological order. +If the packets are NOT in chronological order then the *-w* duplication +removal option may not identify some duplicates. +-- + +--inject-secrets <secrets type>,<file>:: ++ +-- +Inserts the contents of <file> into a Decryption Secrets Block (DSB) +within the pcapng output file. This enables decryption without requiring +additional configuration in protocol preferences. + +The file format is described by <secrets type> which can be one of: + +__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:: ++ +-- +Discard all decryption secrets from the input file when writing the +output file. Does not discard secrets added by *--inject-secrets* in +the same command line. +-- + +--capture-comment <comment>:: ++ +-- +Adds the given comment to the output file, if supported by the output +file format. New comments will be added __after__ any comments present +in the input file unless *--discard-capture-comment* is also specified. + +This option may be specified multiple times. Note that Wireshark +currently only displays the first comment of a capture file. +-- + +--discard-capture-comment:: ++ +-- +Discard all capture file comments from the input file when writing the output +file. Does not discard comments added by *--capture-comment* in the same +command line. +-- + +--set-unused:: ++ +-- +Set the unused bytes (if any) to zero in SLL link type. Useful when when checking for duplicates. +As the unused bytes can be anything. When the packet traverses the device stack +for bonded interfaces on Linux for example. +-- + +--discard-packet-comments:: ++ +-- +Discard all packet comments from the input file when writing the output +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 + +To see more detailed description of the options use: + + editcap -h + +To shrink the capture file by truncating the packets at 64 bytes and writing it as Sun snoop file use: + + editcap -s 64 -F snoop capture.pcapng shortcapture.snoop + +To delete packet 1000 from the capture file use: + + editcap capture.pcapng sans1000.pcapng 1000 + +To limit a capture file to packets from number 200 to 750 (inclusive) use: + + editcap -r capture.pcapng small.pcapng 200-750 + +To get all packets from number 1-500 (inclusive) use: + + editcap -r capture.pcapng first500.pcapng 1-500 + +or + + editcap capture.pcapng first500.pcapng 501-9999999 + +To exclude packets 1, 5, 10 to 20 and 30 to 40 from the new file use: + + editcap capture.pcapng exclude.pcapng 1 5 10-20 30-40 + +To select just packets 1, 5, 10 to 20 and 30 to 40 for the new file use: + + editcap -r capture.pcapng select.pcapng 1 5 10-20 30-40 + +To remove duplicate packets seen within the prior four frames use: + + editcap -d capture.pcapng dedup.pcapng + +To remove duplicate packets seen within the prior four frames while skipping radiotap headers use: + + editcap -d --skip-radiotap-header capture.pcapng dedup.pcapng + +To remove duplicate packets seen within the prior 100 frames use: + + editcap -D 101 capture.pcapng dedup.pcapng + +To remove duplicate packets seen __equal to or less than__ 1/10th of a second: + + editcap -w 0.1 capture.pcapng dedup.pcapng + +To display the MD5 hash for all of the packets (and NOT generate any +real output file): + + editcap -V -D 0 capture.pcapng /dev/null + +or on Windows systems + + editcap -V -D 0 capture.pcapng NUL + +To advance the timestamps of each packet forward by 3.0827 seconds: + + editcap -t 3.0827 capture.pcapng adjusted.pcapng + +To ensure all timestamps are in strict chronological order: + + editcap -S 0 capture.pcapng adjusted.pcapng + +To introduce 5% random errors in a capture file use: + + editcap -E 0.05 capture.pcapng capture_error.pcapng + +To remove vlan tags from all packets within an Ethernet-encapsulated capture +file, use: + + editcap -L -C 12:4 capture_vlan.pcapng capture_no_vlan.pcapng + +To chop both the 10 byte and 20 byte regions from the following 75 byte packet +in a single pass, use any of the 8 possible methods provided below: + + <--------------------------- 75 ----------------------------> + + +---+-------+-----------+---------------+-------------------+ + | 5 | 10 | 15 | 20 | 25 | + +---+-------+-----------+---------------+-------------------+ + + 1) editcap -C 5:10 -C -25:-20 capture.pcapng chopped.pcapng + 2) editcap -C 5:10 -C 50:-20 capture.pcapng chopped.pcapng + 3) editcap -C -70:10 -C -25:-20 capture.pcapng chopped.pcapng + 4) editcap -C -70:10 -C 50:-20 capture.pcapng chopped.pcapng + 5) editcap -C 30:20 -C -60:-10 capture.pcapng chopped.pcapng + 6) editcap -C 30:20 -C 15:-10 capture.pcapng chopped.pcapng + 7) editcap -C -45:20 -C -60:-10 capture.pcapng chopped.pcapng + 8) editcap -C -45:20 -C 15:-10 capture.pcapng chopped.pcapng + +To add comment strings to the first 2 input frames, use: + + editcap -a "1:1st frame" -a 2:Second capture.pcapng capture-comments.pcapng + +== SEE ALSO + +xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:mergecap.html[mergecap](1), xref:dumpcap.html[dumpcap](1), xref:capinfos.html[capinfos](1), +xref:text2pcap.html[text2pcap](1), xref:reordercap.html[reordercap](1), od(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 *Editcap* {wireshark-version}. +*Editcap* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Richard Sharpe <sharpe[AT]ns.aus.com> + +.Contributors +[%hardbreaks] +Guy Harris <guy[AT]alum.mit.edu> +Ulf Lamping <ulf.lamping[AT]web.de> diff --git a/doc/man_pages/etwdump.adoc b/doc/man_pages/etwdump.adoc new file mode 100644 index 00000000..f9df8ac6 --- /dev/null +++ b/doc/man_pages/etwdump.adoc @@ -0,0 +1,124 @@ +include::../attributes.adoc[] += etwdump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +etwdump - Provide an interface to read Event Tracing for Windows (ETW) + +== SYNOPSIS + +[manarg] +*etwdump* +[ *--help* ] +[ *--version* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--iue*=<Should undecidable events be included> ] +[ *--etlfile*=<etl file> ] +[ *--params*=<filter parameters> ] + +== DESCRIPTION + +*etwdump* is a extcap tool that provides access to a event trace log file or an event trace live session. +It is only used to display event trace on Windows that includes readable text message and different protocols (like MBIM and IP packets). + +== OPTIONS + +--help:: +Print program arguments. + +--version:: +Print program version. + +--extcap-interfaces:: +List available interfaces. + +--extcap-interface=<interface>:: +Use specified interfaces. + +--extcap-dlts:: +List DLTs of specified interface. + +--extcap-config:: +List configuration options of specified interface. + +--capture:: +Start capturing from specified interface save saved it in place specified by --fifo. + +--fifo=<path to file or pipe>:: +Save captured packet to file or send it through pipe. + +--iue=<Should undecidable events be included>:: +Choose if the undecidable event is included. + +--etlfile=<Etl file>:: +Select etl file to display in Wireshark. + +--params=<filter parameters>:: +Input providers, keyword and level filters for the etl file and live session. + +== EXAMPLES + +To see program arguments: + + etwdump --help + +To see program version: + + etwdump --version + +To see interfaces: + + etwdump --extcap-interfaces + +.Example output + interface {value=etwdump}{display=ETW reader} + +To see interface DLTs: + + etwdump --extcap-interface=etwdump --extcap-dlts + +.Example output + dlt {number=1}{name=etwdump}{display=DLT_ETW} + +To see interface configuration options: + + etwdump --extcap-interface=etwdump --extcap-config + +.Example output + arg {number=0}{call=--etlfile}{display=etl file}{type=fileselect}{tooltip=Select etl file to display in Wireshark}{group=Capture} + arg {number=1}{call=--params}{display=filter parmeters}{type=string}{tooltip=Input providers, keyword and level filters for the etl file and live session}{group=Capture} + arg {number=2}{call=--iue}{display=Should undecidable events be included}{type=boolflag}{default=false}{tooltip=Choose if the undecidable event is included}{group=Capture} + +To capture: + + etwdump --extcap-interface etwdump --fifo=/tmp/etw.pcapng --capture --params "--p=Microsoft-Windows-Wmbclass-Opn --p=Microsoft-Windows-wmbclass --k=0xff --l=4" + etwdump --extcap-interface etwdump --fifo=/tmp/etw.pcapng --capture --params "--p=Microsoft-Windows-Wmbclass-Opn --p=Microsoft-Windows-NDIS-PacketCapture" + +NOTE: To stop capturing CTRL+C/kill/terminate the application. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4) + +== NOTES + +*etwdump* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Odysseus Yang <wiresharkyyh@outlook.com> diff --git a/doc/man_pages/extcap.adoc b/doc/man_pages/extcap.adoc new file mode 100644 index 00000000..ce8ae933 --- /dev/null +++ b/doc/man_pages/extcap.adoc @@ -0,0 +1,145 @@ +include::../attributes.adoc[] += extcap(4) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +extcap - The extcap interface + +== DESCRIPTION + +The extcap interface is a versatile plugin interface that allows external binaries +to act as capture interfaces directly in Wireshark. It is used in scenarios, where +the source of the capture is not a traditional capture model +(live capture from an interface, from a pipe, from a file, etc). The typical +example is connecting esoteric hardware of some kind to the main Wireshark application. + +Without extcap, a capture can always be achieved by directly writing to a capture file: + + the-esoteric-binary --the-strange-flag --interface=stream1 --file dumpfile.pcap & + wireshark dumpfile.pcap + +but the extcap interface allows for such a connection to be easily established and +configured using the Wireshark GUI. + +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/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 +refer to doc/extcap_example.py for more information. + +When Wireshark launches an extcap, it automatically adds its installation path (normally _C:\Program Files\Wireshark\_) to the DLL search path so that the extcap library dependencies can be found (it is not designed to be launched by hand). +This is done on purpose. There should only be extcap programs (executables, Python scripts, ...) in the extcap folder to reduce the startup time and not have Wireshark trying to execute other file types. + +== GRAMMAR ELEMENTS + +Grammar elements: + +arg (options):: +argument for CLI calling + +number:: +Reference # of argument for other values, display order + +call:: +Literal argument to call (--call=...) + +display:: +Displayed name + +default:: +Default value, in proper form for type + +range:: +Range of valid values for UI checking (min,max) in proper form + +type:: ++ +-- +Argument type for UI filtering for raw, or UI type for selector: + + integer + unsigned + long (may include scientific / special notation) + double + string (display a textbox) + selector (display selector table, all values as strings) + editselector (selector table which can be overridden, all values as strings) + boolean (display checkbox) + booleanflag (display checkbox) + radio (display group of radio buttons with provided values, all values as strings) + fileselect (display a dialog to select a file from the filesystem, value as string) + multicheck (display a textbox for selecting multiple options, values as strings) + password (display a textbox with masked text) + timestamp (display a calendar) +-- + +value (options):: ++ +-- + Values for argument selection + arg Argument # this value applies to +-- + +== EXAMPLES + +Example 1: + + arg {number=0}{call=--channel}{display=Wi-Fi Channel}{type=integer}{required=true} + arg {number=1}{call=--chanflags}{display=Channel Flags}{type=radio} + arg {number=2}{call=--interface}{display=Interface}{type=selector} + value {arg=0}{range=1,11} + value {arg=1}{value=ht40p}{display=HT40+} + value {arg=1}{value=ht40m}{display=HT40-} + value {arg=1}{value=ht20}{display=HT20} + value {arg=2}{value=wlan0}{display=wlan0} + +Example 2: + + arg {number=0}{call=--usbdevice}{USB Device}{type=selector} + value {arg=0}{call=/dev/sysfs/usb/foo/123}{display=Ubertooth One sn 1234} + value {arg=0}{call=/dev/sysfs/usb/foo/456}{display=Ubertooth One sn 8901} + +Example 3: + + arg {number=0}{call=--usbdevice}{USB Device}{type=selector} + arg {number=1}{call=--server}{display=IP address for log server}{type=string}{validation=(?:\d{1,3}\.){3}\d{1,3}} + flag {failure=Permission denied opening Ubertooth device} + +Example 4: + + arg {number=0}{call=--username}{display=Username}{type=string} + arg {number=1}{call=--password}{display=Password}{type=password} + +Example 5: + + arg {number=0}{call=--start}{display=Start Time}{type=timestamp} + arg {number=1}{call=--end}{display=End Time}{type=timestamp} + +== Security Considerations + +- If you're running Wireshark as root, we can't save you. +- Dumpcap retains suid/setgid and group execute permissions for users in the “wireshark” group only. +- Third-party capture programs run with whatever privileges they're installed with. +- If an attacker can write to a system binary directory, it's game over. +- You can find your local extcap directory in menu:About[Folders]. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:androiddump.html[androiddump](1), xref:sshdump.html[sshdump](1), xref:randpktdump.html[randpktdump](1) + +== NOTES + +*Extcap* is feature of *Wireshark*. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. 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/man_pages/idl2deb.adoc b/doc/man_pages/idl2deb.adoc new file mode 100644 index 00000000..f622fdf9 --- /dev/null +++ b/doc/man_pages/idl2deb.adoc @@ -0,0 +1,82 @@ +include::../attributes.adoc[] += idl2deb(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +idl2deb - Create a Debian package for CORBA monitoring from IDL + +== SYNOPSIS + +[manarg] +*idl2deb* +[ *-d* <opts> ] +[ *--dbopts*=<opts> ] +[ *-e* <address> ] +[ *--email*=<address> ] +[ *-h* ] +[ *--help* ] +[ *-i* <idlfile> ] +[ *--idl*=<idlfile> ] +[ *-n* <name> ] +[ *--name*=<name> ] +[ *-p* ] +[ *--preserve* ] +[ *-v* ] +[ *--version* ] + +== DESCRIPTION + +This manual page documents briefly the *idl2deb* command. *idl2deb* +takes an CORBA IDL file as input and creates a Debian package from it. The +package contains a loadable module for the Wireshark network analyzer. + +== OPTIONS + +-d <opts> --dbopts=<opts>:: +options for dpkg-buildpackage. + +-e <address> --email=<address>:: +use e-mail address. + +-h --help:: +print help and exit. + +-i <idlfile> --idl=<idlfile>:: +IDL file to use (mandatory) + +-n <name> --name=<name>:: +use user name. + +-p --preserve:: +do not overwrite files. + +-v --version:: +print version and exit. + +== EXAMPLES + +/usr/bin/idl2deb -e me@foo.net -i bar.idl \-n "My Name" -d "-rfakeroot -uc -us"-d "-rfakeroot -uc -us" + +== SEE ALSO + +A lot of tools are used, which you have to *apt-get install*: wireshark-dev, python, cdbs, autotools-dev, debhelper, dpkg-dev. + +== COPYING + +This manual page was written by W. Borgert debacle@debian.org +for Debian GNU/Linux (but may be used by others). Permission is granted +to copy, distribute and/or modify this document under the terms of the +GNU General Public License, Version 2 or any later version published by +the Free Software Foundation. + +== AUTHOR + +*W. Borgert* Author. + +== COPYRIGHT + +Copyright (C) 2003, 2005 W. Borger diff --git a/doc/man_pages/idl2wrs.adoc b/doc/man_pages/idl2wrs.adoc new file mode 100644 index 00000000..605f441a --- /dev/null +++ b/doc/man_pages/idl2wrs.adoc @@ -0,0 +1,100 @@ +include::../attributes.adoc[] += idl2wrs(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +idl2wrs - CORBA IDL to Wireshark Plugin Generator + +== SYNOPSIS + +*idl2wrs* <filename> + +== DESCRIPTION + +*idl2wrs* is a program that takes a user specified *CORBA IDL* +file and generates *"C"* source code for a *Wireshark* "plugin". + +This resulting file can be compiled as a *Wireshark* plugin, and +used to monitor *GIOP/IIOP* traffic that is using this IDL. + +*idl2wrs* is actually a shell script wrapper for two *Python* programs. +These programs are: + +* *wireshark_be.py* +Contains the main IDL Visitor Class + +* *wireshark_gen.py* +Contains the Source Code Generator Class + +*idl2wrs* supports heuristic dissection of GIOP/IIOP traffic, +and some experimental code for explicit dissection, based on +Object Key <-> Repository Id mapping. +However, code for heuristic based plugins is +generated by default, and users should consider this the preferred +method unless you have some namespace collisions. + +== OPTIONS + +Currently there are no options. *idl2wrs* can be invoked as follows. + +1. To write the C code to stdout. + + idl2wrs <your_file.idl> + + eg: idl2wrs echo.idl + +2. To write to a file, just redirect the output. + + idl2wrs echo.idl > packet-test.c + +== ENVIRONMENT + +*idl2wrs* will look for *wireshark_be.py* and *wireshark_gen.py* in +*$PYTHONPATH/site-packages/* and if not found, will try the current +directory *./* + +The *-p* option passed to omniidl (inside *idl2wrs*) indicates where +*wireshark_be.py* and *wireshark_gen.py* will be searched. This may +need tweaking if you place these files somewhere else. + +If it complains about being unable to find some modules (eg tempfile.py), +you may want to check if PYTHONPATH is set correctly. + +eg: PYTHONPATH=/usr/lib/python3/ + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1) + +== NOTES + +*idl2wrs* (including *wireshark_be.py* and *wireshark_gen.py*) are part of +the *Wireshark* distribution. The latest version of *Wireshark* can +be found at https://www.wireshark.org. + +*idl2wrs* uses *omniidl*, an IDL parser, and can be found at +http://omniorb.sourceforge.net/ + +== TODO + +Some of the more important things to do are: + +* Improve Explicit dissection code. + +* Improve command line options. + +* Improve decode algorithm when we have operation name collision. + +== AUTHORS + +.Original Author +[%hardbreaks] +Frank Singleton <frank.singleton[AT]ericsson.com> + +.Contributors +[%hardbreaks] + diff --git a/doc/man_pages/mergecap.adoc b/doc/man_pages/mergecap.adoc new file mode 100644 index 00000000..43412375 --- /dev/null +++ b/doc/man_pages/mergecap.adoc @@ -0,0 +1,218 @@ +include::../attributes.adoc[] += mergecap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +mergecap - Merges two or more capture files into one + +== SYNOPSIS + +[manarg] +*mergecap* +[ *-a* ] +[ *-F* <__file format__> ] +[ *-I* <__IDB merge mode__> ] +[ *-s* <__snaplen__> ] +[ *-V* ] +*-w* <__outfile__>|- +<__infile__> [<__infile__> __...__] + +[manarg] +*mergecap* +*-h|--help* + +[manarg] +*mergecap* +*-v|--version* + +== DESCRIPTION + +*Mergecap* is a program that combines multiple saved capture files into +a single output file specified by the *-w* argument. *Mergecap* knows +how to read *pcap* and *pcapng* capture files, including those of +*tcpdump*, *Wireshark* and other tools that write captures in those +formats. + +By default, *Mergecap* writes the capture file in *pcapng* format, and +writes all of the packets from the input capture files to the output file. + +*Mergecap* is able to detect, read and write the same capture files that +are supported by *Wireshark*. +The input files don't need a specific filename extension; the file +format and an optional gzip, zstd or lz4 compression will be automatically detected. +Near the beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or +https://www.wireshark.org/docs/man-pages/wireshark.html +is a detailed description of the way *Wireshark* handles this, which is +the same way *Mergecap* handles this. + +*Mergecap* 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, *mergecap -F* provides a list of the available output +formats. + +Packets from the input files are merged in chronological order based on +each frame's timestamp, unless the *-a* flag is specified. *Mergecap* +assumes that frames within a single capture file are already stored in +chronological order. When the *-a* flag is specified, packets are +copied directly from each input file to the output file, independent of +each frame's timestamp. + +The output file frame encapsulation type is set to the type of the input +files if all input files have the same type. If not all of the input +files have the same frame encapsulation type, the output file type is +set to WTAP_ENCAP_PER_PACKET. Note that some capture file formats, most +notably *pcap*, do not currently support WTAP_ENCAP_PER_PACKET. +This combination will cause the output file creation to fail. + +== OPTIONS + +-a:: ++ +-- +Causes the frame timestamps to be ignored, writing all packets from the +first input file followed by all packets from the second input file. By +default, when *-a* is not specified, the contents of the input files +are merged in chronological order based on each frame's timestamp. + +Note: when merging, *mergecap* assumes that packets within a capture +file are already in chronological order. +-- + +-F <file format>:: ++ +-- +Sets the file format of the output capture file. *Mergecap* can write +the file in several formats; *mergecap -F* provides a list of the +available output formats. By default this is the *pcapng* format. +-- + +-h|--help:: +Print the version number and options and exit. + +-I <IDB merge mode>:: ++ +-- +Sets the Interface Description Block (IDB) merge mode to use during merging. +*mergecap -I* provides a list of the available IDB merge modes. + +Every input file has one or more IDBs, which describe the interface(s) the +capture was performed on originally. This includes encapsulation type, +interface name, etc. When mergecap merges multiple input files, it has to +merge these IDBs somehow for the new merged output file. This flag controls +how that is accomplished. The currently available modes are: + +*none*: No merging of IDBs is performed, and instead all IDBs are +copied to the merged output file. + +*all*: IDBs are merged only if all input files have the same number +of IDBs, and each IDB matches their respective entry in the +other files. (Only the IDBs that occur at the beginning of the files, +before any packet blocks, are compared. IDBs that occur later in the +files are merged with duplicates iff the initial IDBs were merged.) +This is the default mode. + +*any*: Any and all duplicate IDBs are merged into one IDB, regardless +of what file they are in. + +Note that an IDB is only considered a matching duplicate if it has the same +encapsulation type, name, speed, time precision, comments, description, etc. +-- + +-s <snaplen>:: ++ +-- +Sets the snapshot length to use when writing the data. +If the *-s* flag is used to specify a snapshot length, frames in the +input file with more captured data than the specified snapshot length +will have only the amount of data specified by the snapshot length +written to the output file. This may be useful if the program that is +to read the output file cannot handle packets larger than a certain size +(for example, the versions of snoop in Solaris 2.5.1 and Solaris 2.6 +appear to reject Ethernet frames larger than the standard Ethernet MTU, +making them incapable of handling gigabit Ethernet captures if jumbo +frames were used). +-- + +-v|--version:: +Print the full version information and exit. + +-V:: +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 + +To merge two capture files together into a third capture file, in which +the last packet of one file arrives 100 seconds before the first packet +of another file, use the following sequence of commands. + +First, use: + + capinfos -aeS a.pcap b.pcap + +to determine the start and end times of the two capture files, as +seconds since January 1, 1970, 00:00:00 UTC. + +If a.pcap starts at 1009932757 and b.pcap ends at 873660281, then the +time adjustment to b.pcap that would make it end 100 seconds before +a.pcap begins would be 1009932757 - 873660281 - 100 = 136272376 seconds. + +Thus, the next step would be to use: + + editcap -t 136272376 b.pcap b-shifted.pcap + +to generate a version of b.pcap with its time stamps shifted 136272376 +ahead. + +Then the final step would be to use : + + mergecap -w compare.pcap a.pcap b-shifted.pcap + +to merge a.pcap and the shifted b.pcap into compare.pcap. + +== SEE ALSO + +xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:editcap.html[editcap](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 + +*Mergecap* is based heavily upon *editcap* by Richard Sharpe +<sharpe[AT]ns.aus.com> and Guy Harris <guy[AT]alum.mit.edu>. + +This is the manual page for *Mergecap* {wireshark-version}. +*Mergecap* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Scott Renfro <scott[AT]renfro.org> + +.Contributors +[%hardbreaks] +Bill Guyton <guyton[AT]bguyton.com> diff --git a/doc/man_pages/mmdbresolve.adoc b/doc/man_pages/mmdbresolve.adoc new file mode 100644 index 00000000..af66d6b4 --- /dev/null +++ b/doc/man_pages/mmdbresolve.adoc @@ -0,0 +1,71 @@ +include::../attributes.adoc[] += mmdbresolve(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +mmdbresolve - Read IPv4 and IPv6 addresses and print their IP geolocation information. + +== SYNOPSIS + +[manarg] +*mmdbresolve* +*-f <dbfile>* +[ *-f <dbfile>* ] +__...__ + +== DESCRIPTION + +*mmdbresolve* reads IPv4 and IPv6 addresses on stdin and prints their IP geolocation information +on stdout. Each input line must contain exactly one address. Output is in INI format, with a section +delimiter named after the query address followed by a set of "key: value" pairs. A comment +beginning with "# End" is appended to each section. + +At startup an "[init]" section is printed that shows the status of each datbase and of mmdbresolve +itself. + +== OPTIONS + +-f:: +Path to a MaxMind Database file. Multiple databases may be specified. + +== EXAMPLES + +To resolve a single address: + + echo 4.4.4.4 | mmdbresolve -f /usr/share/GeoIP/GeoLite2-City.mmdb + +.Example output + [init] + db.0.path: /usr/share/GeoIP/GeoLite2-City.mmdb + db.0.status: OK + mmdbresolve.status: true + # End init + [4.4.4.4] + # GeoLite2-City + country.iso_code: US + country.names.en: United States + location.latitude: 37.751000 + location.longitude: -97.822000 + # End 4.4.4.4 + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1) + +== NOTES + +*mmdbresolve* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Gerald Combs <gerald[AT]wireshark.org> diff --git a/doc/man_pages/randpkt.adoc b/doc/man_pages/randpkt.adoc new file mode 100644 index 00000000..a9b799a5 --- /dev/null +++ b/doc/man_pages/randpkt.adoc @@ -0,0 +1,147 @@ +include::../attributes.adoc[] += randpkt(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +randpkt - Random packet generator + +== SYNOPSIS + +[manarg] +*randpkt* +[ *-b* <maxbytes> ] +[ *-c* <count> ] +[ *-F* <file format> ] +[ *-r* ] +[ *-t* <type> ] +<filename> + +[manarg] +*randpkt* +*-h|--help* + +[manarg] +*randpkt* +*-v|--version* + +== DESCRIPTION + +*randpkt* is a small utility that creates a trace file full of random packets. + +By creating many randomized packets of a certain type, you can +test packet sniffers to see how well they handle malformed packets. +The sniffer can never trust the data that it sees in the packet because +you can always sniff a very bad packet that conforms to no standard. +*randpkt* produces __very bad__ packets. + +When creating packets of a certain type, *randpkt* uses a sample +packet that is stored internally to *randpkt*. It uses this as the +starting point for your random packets, and then adds extra random +bytes to the end of this sample packet. + +For example, if you choose to create random ARP packets, *randpkt* +will create a packet which contains a predetermined Ethernet II header, +with the Type field set to ARP. After the Ethernet II header, it will +put a random number of bytes with random values. + +== OPTIONS + +-b <maxbytes>:: ++ +-- +Default 5000. + +Defines the maximum number of bytes added to the sample packet. +If you choose a *maxbytes* value that is less than the size of the +sample packet, then your packets would contain only the sample +packet... not much variance there! *randpkt* exits on that condition. +-- + +-c <count>:: ++ +-- +Default 1000. + +Defines the number of packets to generate. +-- + +-F <file format>:: ++ +-- +Default *pcapng*. + +Sets the file format of the output capture file. *randpkt* can write +the file in several formats; *randpkt -F* provides a list of the +available output formats. Note that not all output formats support +all packet types. +-- + +-h|--help:: +Print the version number and options and exit. + +-r:: ++ +-- +The packet type is determined randomly for each packet. This requires +an output format that can support different encapsulations per packet, +like *pcapng*. +-- + +-t <type>:: ++ +-- +Default Ethernet II frame. + +Defines the type of packet to generate: + + arp Address Resolution Protocol + bgp Border Gateway Protocol + bvlc BACnet Virtual Link Control + dns Domain Name Service + eth Ethernet + fddi Fiber Distributed Data Interface + giop General Inter-ORB Protocol + icmp Internet Control Message Protocol + ip Internet Protocol + ipv6 Internet Protocol Version 6 + llc Logical Link Control + m2m WiMAX M2M Encapsulation Protocol + megaco MEGACO + nbns NetBIOS-over-TCP Name Service + ncp2222 NetWare Core Protocol + sctp Stream Control Transmission Protocol + syslog Syslog message + tds TDS NetLib + tcp Transmission Control Protocol + tr Token-Ring + udp User Datagram Protocol + usb Universal Serial Bus + usb-linux Universal Serial Bus with Linux specific header +-- + +-v|--version:: +Print the full version information and exit. + +include::diagnostic-options.adoc[] + +== EXAMPLES + +To see a description of the randpkt options use: + + randpkt + +To generate a capture file with 1000 DNS packets use: + + randpkt -b 500 -t dns rand_dns.pcapng + +To generate a small capture file with just a single LLC frame use: + + randpkt -b 100 -c 1 -t llc single_llc.pcapng + +== SEE ALSO + +xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:editcap.html[editcap](1) diff --git a/doc/man_pages/randpktdump.adoc b/doc/man_pages/randpktdump.adoc new file mode 100644 index 00000000..8862b108 --- /dev/null +++ b/doc/man_pages/randpktdump.adoc @@ -0,0 +1,142 @@ +include::../attributes.adoc[] += randpktdump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +randpktdump - Provide an interface to generate random captures using randpkt + +== SYNOPSIS + +[manarg] +*randpktdump* +[ *--help* ] +[ *--version* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--maxbytes*=<bytes> ] +[ *--count*=<num> ] +[ *--delay*=<ms> ] +[ *--random-type*=<true|false> ] +[ *--all-random*=<true|false> ] +[ *--type*=<packet type> ] + +== DESCRIPTION + +*randpktdump* is a extcap tool that provides access to the random +packet generator (randpkt). It is mainly used for testing and +educational purpose. + +== OPTIONS + +--help:: +Print program arguments. + +--version:: +Print program version. + +--extcap-interfaces:: +List available interfaces. + +--extcap-interface=<interface>:: +Use specified interfaces. + +--extcap-dlts:: +List DLTs of specified interface. + +--extcap-config:: +List configuration options of specified interface. + +--capture:: +Start capturing from specified interface save saved it in place specified by --fifo. + +--fifo=<path to file or pipe>:: +Save captured packet to file or send it through pipe. + +--maxbytes=<bytes>:: +Set the max number of bytes per packet. + +--count=<num>:: +Number of packets to generate (-1 for infinite). + +--delay=<ms>:: +Wait a number of milliseconds after writing each packet. + +--random-type:: +Choose a random packet type for all packets if set to true. + +--all-random:: +Choose a different random packet type for each packet if set to true. + +--type=<packet type>:: +Use the selected packet type. To list all the available packet type, run randpktdump --help. + +== EXAMPLES + +To see program arguments: + + randpktdump --help + +To see program version: + + randpktdump --version + +To see interfaces: + + randpktdump --extcap-interfaces + +.Example output + interface {value=randpkt}{display=Random packet generator} + +To see interface DLTs: + + randpktdump --extcap-interface=randpkt --extcap-dlts + +.Example output + dlt {number=1}{name=randpkt}{display=Ethernet} + +To see interface configuration options: + + randpktdump --extcap-interface=randpkt --extcap-config + +.Example output + arg {number=0}{call=--maxbytes}{display=Max bytes in a packet}{type=unsigned}{range=1,5000}{default=5000}{tooltip=The max number of bytes in a packet} + arg {number=1}{call=--count}{display=Number of packets}{type=long}{default=1000}{tooltip=Number of packets to generate (-1 for infinite)} + arg {number=2}{call=--delay}{display=Packet delay (ms)}{type=long}{default=0}{tooltip=Milliseconds to wait after writing each packet} + arg {number=3}{call=--random-type}{display=Random type}{type=boolflag}{default=false}{tooltip=The packets type is randomly chosen} + arg {number=4}{call=--all-random}{display=All random packets}{type=boolflag}{default=false}{tooltip=Packet type for each packet is randomly chosen} + arg {number=5}{call=--type}{display=Type of packet}{type=selector}{tooltip=Type of packet to generate} + value {arg=5}{value=arp}{display=Address Resolution Protocol} + [...] + value {arg=5}{value=usb-linux}{display=Universal Serial Bus with Linux specific header} + +To capture: + + randpktdump --extcap-interface=randpkt --fifo=/tmp/randpkt.pcapng --capture + +NOTE: To stop capturing CTRL+C/kill/terminate the application. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4), xref:randpkt.html[randpkt](1) + +== NOTES + +*randpktdump* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Dario Lombardo <lomato[AT]gmail.com> diff --git a/doc/man_pages/rawshark.adoc b/doc/man_pages/rawshark.adoc new file mode 100644 index 00000000..5b52f034 --- /dev/null +++ b/doc/man_pages/rawshark.adoc @@ -0,0 +1,360 @@ +include::../attributes.adoc[] += rawshark(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +rawshark - Dump and analyze raw pcap data + +== SYNOPSIS + +[manarg] +*rawshark* +[ *-d* <encap:linktype>|<proto:protoname> ] +[ *-F* <field to display> ] +[ *-l* ] +[ *-m* <bytes> ] +[ *-o* <preference setting> ] ... +[ *-p* ] +[ *-r* <pipe>|- ] +[ *-R* <read (display) filter> ] +[ *-s* ] +[ *-S* <field format> ] +[ *options* ] + +[manarg] +*rawshark* +*-h|--help* + +[manarg] +*rawshark* +*-v|--version* + +== DESCRIPTION + +*Rawshark* reads a stream of packets from a file or pipe, and prints a line +describing its output, followed by a set of matching fields for each packet +on stdout. + +== INPUT + +Unlike *TShark*, *Rawshark* makes no assumptions about encapsulation or +input. The *-d* and *-r* flags must be specified in order for it to run. +One or more *-F* flags should be specified in order for the output to be +useful. The other flags listed above follow the same conventions as +*Wireshark* and *TShark*. + +*Rawshark* expects input records with the following format by default. This +matches the format of the packet header and packet data in a pcap-formatted +file on disk. + + struct rawshark_rec_s { + uint32_t ts_sec; /* Time stamp (seconds) */ + uint32_t ts_usec; /* Time stamp (microseconds) */ + uint32_t caplen; /* Length of the packet buffer */ + uint32_t len; /* "On the wire" length of the packet */ + uint8_t data[caplen]; /* Packet data */ + }; + +If *-p* is supplied *rawshark* expects the following format. This +matches the __struct pcap_pkthdr__ structure and packet data used in +libpcap, Npcap, or WinPcap. This structure's format is platform-dependent; the +size of the __tv_sec__ field in the __struct timeval__ structure could be +32 bits or 64 bits. For *rawshark* to work, the layout of the +structure in the input must match the layout of the structure in +*rawshark*. Note that this format will probably be the same as the +previous format if *rawshark* is a 32-bit program, but will not +necessarily be the same if *rawshark* is a 64-bit program. + + struct rawshark_rec_s { + struct timeval ts; /* Time stamp */ + uint32_t caplen; /* Length of the packet buffer */ + uint32_t len; /* "On the wire" length of the packet */ + uint8_t data[caplen]; /* Packet data */ + }; + +In either case, the endianness (byte ordering) of each integer must match the +system on which *rawshark* is running. + +== OUTPUT + +If one or more fields are specified via the *-F* flag, *Rawshark* prints +the number, field type, and display format for each field on the first line +as "packet number" 0. For each record, the packet number, matching fields, +and a "1" or "0" are printed to indicate if the field matched any supplied +display filter. A "-" is used to signal the end of a field description and +at the end of each packet line. For example, the flags *-F ip.src -F + dns.qry.type* might generate the following output: + + 0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX - + 1 1="1" 0="192.168.77.10" 1 - + 2 1="1" 0="192.168.77.250" 1 - + 3 0="192.168.77.10" 1 - + 4 0="74.125.19.104" 1 - + +Note that packets 1 and 2 are DNS queries, and 3 and 4 are not. Adding *-R "not dns"* still prints each line, but there's an indication +that packets 1 and 2 didn't pass the filter: + + 0 FT_IPv4 BASE_NONE - 1 FT_UINT16 BASE_HEX - + 1 1="1" 0="192.168.77.10" 0 - + 2 1="1" 0="192.168.77.250" 0 - + 3 0="192.168.77.10" 1 - + 4 0="74.125.19.104" 1 - + +Also note that the output may be in any order, and that multiple matching +fields might be displayed. + +== OPTIONS + +-d <encapsulation>:: ++ +-- +Specify how the packet data should be dissected. The encapsulation is of the +form __type:value__, where __type__ is one of: + +*encap*:__name__ Packet data should be dissected using the +libpcap/Npcap/WinPcap data link type (DLT) __name__, e.g. *encap:EN10MB* for +Ethernet. Names are converted using pcap_datalink_name_to_val(). +A complete list of DLTs can be found at +https://www.tcpdump.org/linktypes.html. + +*encap*:__number__ Packet data should be dissected using the +libpcap/Npcap/WinPcap LINKTYPE_ __number__, e.g. *encap:105* for raw IEEE +802.11 or *encap:101* for raw IP. + +*proto*:__protocol__ Packet data should be passed to the specified Wireshark +protocol dissector, e.g. *proto:http* for HTTP data. +-- + +-F <field to display>:: ++ +-- +Add the matching field to the output. Fields are any valid display filter +field. More than one *-F* flag may be specified, and each field can match +multiple times in a given packet. A single field may be specified per *-F* +flag. If you want to apply a display filter, use the *-R* flag. +-- + +-h|--help:: +Print the version number and options and exit. + +-l:: ++ +-- +Flush the standard output after the information for each packet is +printed. (This is not, strictly speaking, line-buffered if *-V* +was specified; however, it is the same as line-buffered if *-V* wasn't +specified, as only one line is printed for each packet, and, as *-l* is +normally used when piping a live capture to a program or script, so that +output for a packet shows up as soon as the packet is seen and +dissected, it should work just as well as true line-buffering. We do +this as a workaround for a deficiency in the Microsoft Visual C++ C +library.) + +This may be useful when piping the output of *TShark* to another +program, as it means that the program to which the output is piped will +see the dissected data for a packet as soon as *TShark* sees the +packet and generates that output, rather than seeing it only when the +standard output buffer containing that data fills up. +-- + +-m <memory limit bytes>:: +Limit rawshark's memory usage to the specified number of bytes. POSIX +(non-Windows) only. + +-o <preference>:<value>:: ++ +-- +Set a preference value, overriding the default value and any value read +from a preference file. The argument to the option is a string of the +form __prefname:value__, where __prefname__ is the name of the +preference (which is the same name that would appear in the preference +file), and __value__ is the value to which it should be set. +-- + +-p:: ++ +-- +Assume that packet data is preceded by a pcap_pkthdr struct as defined in +pcap.h. On some systems the size of the timestamp data will be different from +the data written to disk. On other systems they are identical and this flag has +no effect. +-- + +-r <pipe>|-:: ++ +-- +Read packet data from __input source__. It can be either the name of a FIFO +(named pipe) or ``-'' to read data from the standard input, and must have +the record format specified above. + +If you are sending data to rawshark from a parent process on Windows you +should not close rawshark's standard input handle prematurely, otherwise +the C runtime might trigger an exception. +-- + +-R|--read-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:: +Allows standard pcap files to be used as input, by skipping over the 24 +byte pcap file header. + +-S:: ++ +-- +Use the specified format string to print each field. The following formats +are supported: + +*%D* Field name or description, e.g. "Type" for dns.qry.type + +*%N* Base 10 numeric value of the field. + +*%S* String value of the field. + +For something similar to Wireshark's standard display ("Type: A (1)") you +could use *%D: %S (%N)*. +-- + +-v|--version:: +Print the full version information and exit. + +-Y|--display-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*. +-- + +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 *Rawshark* see the xref:wireshark-filter.html[wireshark-filter](4) manual page. + +include::files.adoc[tags=**;!gui] + +== ENVIRONMENT VARIABLES + +// Should this be moved to an include file? + +WIRESHARK_CONFIG_DIR:: ++ +-- +This environment variable overrides the location of personal +configuration files. On UNIX-compatible systems, such as Linux, macOS, +\*BSD, Solaris, and AIX, it defaults to __$XDG_CONFIG_HOME/wireshark__ +(or, if that directory doesn't exist but __$HOME/.wireshark__ does +exist, __$HOME/.wireshark__); this is typically +__$HOME/.config/wireshark__. On Windows, it defaults to +__%APPDATA%\Wireshark__ (or, if %APPDATA% isn't defined, +__%USERPROFILE%\Application Data\Wireshark__). Available since +Wireshark 3.0. +-- + +WIRESHARK_DEBUG_WMEM_OVERRIDE:: ++ +-- +Setting this environment variable forces the wmem framework to use the +specified allocator backend for *all* allocations, regardless of which +backend is normally specified by the code. This is mainly useful to developers +when testing or debugging. See __README.wmem__ in the source distribution for +details. +-- + +WIRESHARK_RUN_FROM_BUILD_DIRECTORY:: ++ +-- +This environment variable causes the plugins and other data files to be +loaded from the build directory (where the program was compiled) rather +than from the standard locations. It has no effect when the program in +question is running with root (or setuid) permissions on UNIX-compatible +systems, such as Linux, macOS, \*BSD, Solaris, and AIX. +-- + +WIRESHARK_DATA_DIR:: ++ +-- +This environment variable causes the various data files to be loaded from +a directory other than the standard locations. It has no effect when the +program in question is running with root (or setuid) permissions on +UNIX-compatible systems. +-- + +ERF_RECORDS_TO_CHECK:: ++ +-- +This environment variable controls the number of ERF records checked when +deciding if a file really is in the ERF format. Setting this environment +variable a number higher than the default (20) would make false positives +less likely. +-- + +IPFIX_RECORDS_TO_CHECK:: ++ +-- +This environment variable controls the number of IPFIX records checked when +deciding if a file really is in the IPFIX format. Setting this environment +variable a number higher than the default (20) would make false positives +less likely. +-- + +WIRESHARK_ABORT_ON_DISSECTOR_BUG:: ++ +-- +If this environment variable is set, *Rawshark* will call abort(3) +when a dissector bug is encountered. abort(3) will cause the program to +exit abnormally; if you are running *Rawshark* in a debugger, it +should halt in the debugger and allow inspection of the process, and, if +you are not running it in a debugger, it will, on some OSes, assuming +your environment is configured correctly, generate a core dump file. +This can be useful to developers attempting to troubleshoot a problem +with a protocol dissector. +-- + +WIRESHARK_ABORT_ON_TOO_MANY_ITEMS:: ++ +-- +If this environment variable is set, *Rawshark* will call abort(3) +if a dissector tries to add too many items to a tree (generally this +is an indication of the dissector not breaking out of a loop soon enough). +abort(3) will cause the program to exit abnormally; if you are running +*Rawshark* in a debugger, it should halt in the debugger and allow +inspection of the process, and, if you are not running it in a debugger, +it will, on some OSes, assuming your environment is configured correctly, +generate a core dump file. This can be useful to developers attempting to +troubleshoot a problem with a protocol dissector. +-- + +== SEE ALSO + +xref:wireshark-filter.html[wireshark-filter](4), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:editcap.html[editcap](1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:dumpcap.html[dumpcap](1), +xref:text2pcap.html[text2pcap](1), xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8) + +== NOTES + +This is the manual page for *Rawshark* {wireshark-version}. +*Rawshark* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +*Rawshark* uses the same packet dissection code that *Wireshark* does, as +well as using many other modules from *Wireshark*; see the list of authors +in the *Wireshark* man page for a list of authors of that code. + diff --git a/doc/man_pages/reordercap.adoc b/doc/man_pages/reordercap.adoc new file mode 100644 index 00000000..0d03b166 --- /dev/null +++ b/doc/man_pages/reordercap.adoc @@ -0,0 +1,84 @@ +include::../attributes.adoc[] += reordercap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +reordercap - Reorder input file by timestamp into output file + +== SYNOPSIS + +[manarg] +*reordercap* +[ *-n* ] +<__infile__> <__outfile__> + +[manarg] +*reordercap* +*-h|--help* + +[manarg] +*reordercap* +*-v|--version* + +== DESCRIPTION + +*Reordercap* is a program that reads an input capture file and rewrites the +frames to an output capture file, but with the frames sorted by increasing +timestamp. + +This functionality may be useful when capture files have been created by +combining frames from more than one well-synchronised source, but the +frames have not been combined in strict time order. + +*Reordercap* writes the output capture file in the same format as the input +capture file. + +*Reordercap* is able to detect, read and write the same capture files that +are supported by *Wireshark*. +The input file doesn't need a specific filename extension; the file +format and an optional gzip, zstd or lz4 compression will be automatically detected. +Near the beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or +https://www.wireshark.org/docs/man-pages/wireshark.html +is a detailed description of the way *Wireshark* handles this, which is +the same way *reordercap* handles this. + +== OPTIONS + +-h|--help:: +Print the version number and options and exit. + +-n:: +When the *-n* option is used, *reordercap* will not write out the output +file if it finds that the input file is already in order. + +-v|--version:: +Print the full version information and exit. + +include::diagnostic-options.adoc[] + +== SEE ALSO + +xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:editcap.html[editcap](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 *Reordercap* {wireshark-version}. +*Reordercap* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +It may make sense to move this functionality into *editcap*, or perhaps *mergecap*, in which case *reordercap* could be retired. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Martin Mathieson <martin.r.mathieson[AT]googlemail.com> + diff --git a/doc/man_pages/sdjournal.adoc b/doc/man_pages/sdjournal.adoc new file mode 100644 index 00000000..d8736704 --- /dev/null +++ b/doc/man_pages/sdjournal.adoc @@ -0,0 +1,132 @@ +include::../attributes.adoc[] += sdjournal(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +sdjournal - Provide an interface to capture systemd journal entries. + +== SYNOPSIS + +[manarg] +*sdjournal* +[ *--help* ] +[ *--version* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--start-from*=<entry count> ] + +== DESCRIPTION + +*sdjournal* is an extcap tool that allows one to capture systemd +journal entries. It can be used to correlate system events with +network traffic. + +Supported interfaces: + +1. sdjournal + +== OPTIONS + +--help:: +Print program arguments. + +--version:: +Print program version. + +--extcap-interfaces:: +List available interfaces. + +--extcap-interface=<interface>:: +Use specified interfaces. + +--extcap-dlts:: +List DLTs of specified interface. + +--extcap-config:: +List configuration options of specified interface. + +--capture:: +Start capturing from 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. + +--start-from=<entry count>:: ++ +-- +Start from the last <entry count> entries, similar to the +"-n" or "--lines" argument for the tail(1) command. Values prefixed +with a *+* sign start from the beginning of the journal, otherwise +the count starts from the end. The default value is 10. To include +all entries use *+0*. +-- + +== EXAMPLES + +To see program arguments: + + sdjournal --help + +To see program version: + + sdjournal --version + +To see interfaces: + + sdjournal --extcap-interfaces + +Only one interface (sdjournal) is supported. + +.Example output + interface {value=sdjournal}{display=systemd journal capture} + +To see interface DLTs: + + sdjournal --extcap-interface=sdjournal --extcap-dlts + +.Example output + dlt {number=147}{name=sdjournal}{display=USER0} + +To see interface configuration options: + + sdjournal --extcap-interface=sdjournal --extcap-config + +.Example output + arg {number=0}{call=--start-from}{display=Starting position}{type=string} + {tooltip=The journal starting position. Values with a leading "+" start from the beginning, similar to the "tail" command} + +To capture: + + sdjournal --extcap-interface=sdjournal --fifo=/tmp/sdjournal.pcap --capture + +To capture all entries since the system was booted: + + sdjournal --extcap-interface=sdjournal --fifo=/tmp/sdjournal.pcap --capture --start-from +0 + +NOTE: To stop capturing CTRL+C/kill/terminate the application. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4), xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](1) + +== NOTES + +*sdjournal* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Gerald Combs <gerald[AT]wireshark.org> diff --git a/doc/man_pages/sshdump.adoc b/doc/man_pages/sshdump.adoc new file mode 100644 index 00000000..562336c4 --- /dev/null +++ b/doc/man_pages/sshdump.adoc @@ -0,0 +1,313 @@ +include::../attributes.adoc[] += sshdump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +sshdump - Provide interfaces to capture from a remote host through SSH using a remote capture binary. + +== SYNOPSIS + +[manarg] +*sshdump* +[ *--help* ] +[ *--version* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--extcap-capture-filter*=<capture filter> ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--remote-host*=<IP address> ] +[ *--remote-port*=<TCP port> ] +[ *--remote-username*=<username> ] +[ *--remote-password*=<password> ] +[ *--sshkey*=<private key path> ] +[ *--sshkey-passphrase*=<private key passphrase> ] +[ *--proxycommand*=<SSH proxy command> ] +[ *--remote-interface*=<interface> ] +[ *--remote-capture-command-select*=<capture command selection> ] +[ *--remote-capture-command*=<capture command> ] +[ *--remote-priv*=<privilege elevation command selection> ] +[ *--remote-priv-user*=<privileged user name> ] +[ *--remote-noprom* ] +[ *--remote-filter*=<remote capture filter> ] +[ *--remote-count*=<number> ] + +[manarg] +*sshdump* +*--extcap-interfaces* + +[manarg] +*sshdump* +*--extcap-interface*=<interface> +*--extcap-dlts* + +[manarg] +*sshdump* +*--extcap-interface*=<interface> +*--extcap-config* + +[manarg] +*sshdump* +*--extcap-interface*=<interface> +*--fifo*=<path to file or pipe> +*--capture* +*--remote-host=myremotehost* +*--remote-port=22* +*--remote-username=user* +*--remote-interface=eth2* +*--remote-capture-command='tcpdump -U -i eth0 -w-'* + +== DESCRIPTION + +*Sshdump* is an extcap tool that allows one to run a remote capture +tool over a SSH connection. The requirement is that the capture +executable must have the capabilities to capture from the wanted +interface. + +The feature is functionally equivalent to run commands like + + $ ssh remoteuser@remotehost -p 22222 'tcpdump -U -i IFACE -w -' > FILE & + $ wireshark FILE + + $ ssh remoteuser@remotehost '/sbin/dumpcap -i IFACE -P -w - -f "not port 22"' > FILE & + $ wireshark FILE + + $ ssh somehost dumpcap -P -w - -f udp | tshark -i - + +Typically sshdump is not invoked directly. Instead it can be configured through +the Wireshark graphical user interface or its command line. The following will +start Wireshark and start capturing from host *remotehost*: + + $ wireshark '-oextcap.sshdump.remotehost:"remotehost"' -i sshdump -k + +To explicitly control the remote capture command: + + $ wireshark '-oextcap.sshdump.remotehost:"remotehost"' \ + '-oextcap.sshdump.remotecapturecommand:"tcpdump -i eth0 -Uw- not port 22"' \ + -i sshdump -k + +Supported interfaces: + +1. ssh + +== OPTIONS + +--help:: +Print program arguments. + +--version:: +Print program version. + +--extcap-interfaces:: +List available interfaces. + +--extcap-interface=<interface>:: +Use specified interfaces. + +--extcap-dlts:: +List DLTs of specified interface. + +--extcap-config:: +List configuration options of specified interface. + +--extcap-capture-filter=<capture filter>:: +The capture filter. It corresponds to the value provided via the *tshark -f* +option, and the Capture Filter field next to the interfaces list in the +Wireshark interface. + +--capture:: +Start capturing from 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. + +--remote-host=<remote host>:: +The address of the remote host for capture. + +--remote-port=<remote port>:: +The SSH port of the remote host. + +--remote-username=<username>:: +The username for SSH authentication. + +--remote-password=<password>:: +The password to use (if not ssh-agent and pubkey are used). WARNING: the +passwords are stored in plaintext and visible to all users on this system. It is +recommended to use keyfiles with a SSH agent. + +--sshkey=<SSH private key path>:: +The path to a private key for authentication. NOTE: Only OPENSSH key/value pair format is supported. + +--sshkey-passphrase=<SSH private key passphrase>:: +The passphrase for the private key for authentication. + +--proxycommand=<proxy command>:: +The command to use as proxy for the SSH connection. +--remote-interface=<remote interface>:: +The remote network interface to capture from. + +--remote-capture-command-select=<capture command-selection>:: ++ +-- +The selection of the build-in support for remote capture commands. Either *dumpcap* for a remote +capture command using dumpcap, *tcpdump* for a remote capture command using tcpdump, or *other*, +where the remote capture command is to be given with the *--remote-capture-command* option. + +Note that selecting dumpcap allows for specifying multiple capture interfaces as a whitespace +separated list, while tcpdump does not. +-- + +--remote-capture-command=<capture command>:: ++ +-- +A custom remote capture command that produces the remote stream that is shown in Wireshark. +The command must be able to produce a PCAP stream written to STDOUT. See below for more +examples. + +If using tcpdump, use the *-w-* option to ensure that packets are written to +standard output (stdout). Include the *-U* option to write packets as soon as +they are received. + +When specified, this command will be used as is, options such as the capture +filter (*--extcap-capture-filter*) will not be appended. +-- + +--remote-priv=<privilege elevation command selection>:: +The command to use to achieve privilege elevation to capture on the remote host. Either none, sudo or doas. + +--remote-priv-user=<privileged user name>:: +If a command is used to achieve privilege elevation to capture on the remote host this may require a user name. +If needed use this option to give that user name. + +--remote-filter=<capture filter>:: +The remote capture filter. It corresponds to the value provided via the *tshark -f* +option, and the Capture Filter field next to the interfaces list in the +Wireshark interface. + +--remote-count=<number>:: +The number of packets to capture. + +== EXAMPLES + +To see program arguments: + + sshdump --help + +To see program version: + + sshdump --version + +To see interfaces: + + sshdump --extcap-interfaces + +Only one interface (sshdump) is supported. + +.Example output + interface {value=sshdump}{display=SSH remote capture} + +To see interface DLTs: + + sshdump --extcap-interface=sshdump --extcap-dlts + +.Example output + dlt {number=147}{name=sshdump}{display=Remote capture dependent DLT} + +To see interface configuration options: + + sshdump --extcap-interface=sshdump --extcap-config + +.Example output + arg {number=0}{call=--remote-host}{display=Remote SSH server address}{type=string} + {tooltip=The remote SSH host. It can be both an IP address or a hostname}{required=true}{group=Server} + arg {number=1}{call=--remote-port}{display=Remote SSH server port}{type=unsigned}{default=22} + {tooltip=The remote SSH host port (1-65535)}{range=1,65535}{group=Server} + arg {number=2}{call=--remote-username}{display=Remote SSH server username}{type=string} + {tooltip=The remote SSH username. If not provided, the current user will be used}{group=Authentication} + arg {number=3}{call=--remote-password}{display=Remote SSH server password}{type=password} + {tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.}{group=Authentication} + arg {number=4}{call=--sshkey}{display=Path to SSH private key}{type=fileselect} + {tooltip=The path on the local filesystem of the private SSH key (OpenSSH format)}{mustexist=true}{group=Authentication} + arg {number=5}{call=--sshkey-passphrase}{display=SSH key passphrase}{type=password} + {tooltip=Passphrase to unlock the SSH private key}{group=Authentication} + arg {number=6}{call=--proxycommand}{display=ProxyCommand}{type=string} + {tooltip=The command to use as proxy for the SSH connection}{group=Authentication} + arg {number=7}{call=--remote-interface}{display=Remote interface}{type=string} + {tooltip=The remote network interface used for capture}{group=Capture} + arg {number=8}{call=--remote-capture-command-select}{display=Remote capture command selection}{type=radio} + {tooltip=The remote capture command to build a command line for}{group=Capture} + value {arg=8}{value=dumpcap}{display=dumpcap} + value {arg=8}{value=tcpdump}{display=tcpdump}{default=true} + value {arg=8}{value=other}{display=Other:} + arg {number=9}{call=--remote-capture-command}{display=Remote capture command}{type=string} + {tooltip=The remote command used to capture}{group=Capture} + arg {number=10}{call=--remote-priv}{display=Gain capture privilege on the remote machine}{type=radio} + {tooltip=Optionally prepend the capture command with sudo or doas on the remote machine}{group=Capture} + value {arg=10}{value=none}{display=none}{default=true} + value {arg=10}{value=sudo}{display=sudo} + value {arg=10}{value=doas -n}{display=doas} + arg {number=11}{call=--remote-priv-user}{display=Privileged user name for sudo or doas}{type=string} + {tooltip=User name of privileged user to execute the capture command on the remote machine}{group=Capture} + arg {number=12}{call=--remote-noprom}{display=No promiscuous mode}{type=boolflag} + {tooltip=Don't use promiscuous mode on the remote machine}{group=Capture} + arg {number=13}{call=--remote-filter}{display=Remote capture filter}{type=string} + {tooltip=The remote capture filter}{default=not ((host myhost) and port 22)}{group=Capture} + arg {number=14}{call=--remote-count}{display=Packets to capture}{type=unsigned}{default=0} + {tooltip=The number of remote packets to capture. (Default: inf)}{group=Capture} + arg {number=15}{call=--log-level}{display=Set the log level}{type=selector} + {tooltip=Set the log level}{required=false}{group=Debug} + value {arg=14}{value=message}{display=Message}{default=true} + value {arg=14}{value=info}{display=Info} + value {arg=14}{value=debug}{display=Debug} + value {arg=14}{value=noisy}{display=Noisy} + arg {number=16}{call=--log-file}{display=Use a file for logging}{type=fileselect} + {tooltip=Set a file where log messages are written}{required=false}{group=Debug} + + +To capture: + + sshdump --extcap-interface=sshdump --fifo=/tmp/ssh.pcap --capture --remote-host 192.168.1.10 + --remote-username user --remote-filter "not port 22" + +To use different capture binaries: + + sshdump --extcap-interface=sshdump --fifo=/tmp/ssh.pcap --capture --remote-host 192.168.1.10 + --remote-username user --remote-priv sudo --remote-capture-command-select tcpdump + --remote-interface eth0 --remote-noprom + + sshdump --extcap-interface=sshdump --fifo=/tmp/ssh.pcap --capture --remote-host 192.168.1.10 + --remote-capture-command='dumpcap -i eth0 -P -w -' + + sshdump --extcap-interface=sshdump --fifo=/tmp/ssh.pcap --capture --remote-host 192.168.1.10 + --remote-capture-command='sudo tcpdump -i eth0 -U -w -' + +NOTE: To stop capturing CTRL+C/kill/terminate the application. + +The sshdump binary can be renamed to support multiple instances. For instance if we want sshdump +to show up twice in wireshark (for instance to handle multiple profiles), we can copy sshdump to +sshdump-host1 and sshdump-host2. Each binary will show up an interface name same as the executable +name. Those executables not being "sshdump" will show up as "custom version" in the interface description. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4), xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](1) + +== NOTES + +*Sshdump* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Dario Lombardo <lomato[AT]gmail.com> diff --git a/doc/man_pages/text2pcap.adoc b/doc/man_pages/text2pcap.adoc new file mode 100644 index 00000000..9c2a8195 --- /dev/null +++ b/doc/man_pages/text2pcap.adoc @@ -0,0 +1,433 @@ +include::../attributes.adoc[] += text2pcap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +text2pcap - Generate a capture file from an ASCII hexdump of packets + +== SYNOPSIS + +[manarg] +*text2pcap* +[ *-a* ] +[ *-b* 2|8|16|64 ] +[ *-D* ] +[ *-e* <ethertype> ] +[ *-E* <encapsulation type> ] +[ *-F* <file format> ] +[ *-i* <proto> ] +[ *-l* <typenum> ] +[ *-N* <intf-name> ] +[ *-m* <max-packet> ] +[ *-o* hex|oct|dec|none ] +[ *-q* ] +[ *-r* <regex> ] +[ *-s* <srcport>,<destport>,<tag> ] +[ *-S* <srcport>,<destport>,<ppi> ] +[ *-t* <timefmt> ] +[ *-T* <srcport>,<destport> ] +[ *-u* <srcport>,<destport> ] +[ *-4* <srcip>,<destip> ] +[ *-6* <srcip>,<destip> ] +<__infile__>|- +<__outfile__>|- + +[manarg] +*text2pcap* +*-h|--help* + +[manarg] +*text2pcap* +*-v|--version* + +== DESCRIPTION + +*Text2pcap* is a program that reads in an ASCII hex dump and writes the +data described into a capture file. *text2pcap* can read hexdumps with +multiple packets in them, and build a capture file of multiple packets. +*Text2pcap* is also capable of generating dummy Ethernet, IP, and UDP, TCP +or SCTP headers, in order to build fully processable packet dumps from +hexdumps of application-level data only. + +*Text2pcap* 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, *text2pcap -F* provides a list of the available output +formats. By default, it writes the packets to __outfile__ in the *pcapng* +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 +spaces separating the bytes from each other. Hex digits can be upper +or lowercase. + +In normal operation, each line must begin with an offset describing the +position in the packet, followed a colon, space, or tab separating it from +the bytes. There is no limit on the width or number of bytes per line, but +lines with only hex bytes without a leading offset are ignored (in other words, +line breaks should not be inserted in long lines that wrap.) Offsets are more +than two digits; they are in hex by default, but can also be in octal or +decimal - see *-o*. Each packet must begin with offset zero, and an offset +zero indicates the beginning of a new packet. Offset values must be correct; +an unexpected value causes the current packet to be aborted and the next +packet start awaited. There is also a single packet mode with no offsets; +see *-o*. + +Packets may be preceded by a direction indicator ('I' or 'O') and/or a +timestamp if indicated by the command line (see *-D* and *-t*). If both are +present, the direction indicator precedes the timestamp. The format of the +timestamps is specified as a mandatory parameter to *-t*. If no timestamp is +parsed, in the case of the first packet the current system time is used, while +subsequent packets are written with timestamps one microsecond later than that +of the previous packet. + +Other text in the input data is ignored. Any text before the offset is +ignored, including email forwarding characters '>'. Any text on a line +after the bytes is ignored, e.g. an ASCII character dump (but see *-a* to +ensure that hex digits in the character dump are ignored). Any line where +the first non-whitespace character is a '#' will be ignored as a comment. +Any lines of text between the bytestring lines are considered preamble; +the beginning of the preamble is scanned for the direction indicator and +timestamp as mentioned above and otherwise ignored. + +Any line beginning with #TEXT2PCAP is a directive and options +can be inserted after this command to be processed by *text2pcap*. +Currently there are no directives implemented; in the future, these may +be used to give more fine grained control on the dump and the way it +should be processed e.g. timestamps, encapsulation type etc. + +In general, short of these restrictions, *text2pcap* is pretty liberal +about reading in hexdumps and has been tested with a variety of +mangled outputs (including being forwarded through email multiple +times, with limited line wrap etc.) + +Here is a sample dump that *text2pcap* can recognize, with optional +directional indicator and timestamp: + + I 2019-05-14T19:04:57Z + 000000 00 0e b6 00 00 02 00 0e b6 00 00 01 08 00 45 00 + 000010 00 28 00 00 00 00 ff 01 37 d1 c0 00 02 01 c0 00 + 000020 02 02 08 00 a6 2f 00 01 00 01 48 65 6c 6c 6f 20 + 000030 57 6f 72 6c 64 21 + 000036 + +*Text2pcap* is also capable of scanning a text input file using a custom Perl +compatible regular expression that matches a single packet. *text2pcap* +searches the given file (which must end with '\n') for non-overlapping non-empty +strings matching the regex. Named capturing subgroups, which must match +exactly once per packet, are used to identify fields to import. The following +fields are supported in regex mode, one mandatory and three optional: + + "data" Actual captured frame data to import + "time" Timestamp of packet + "dir" Direction of packet + "seqno" Arbitrary ID of packet + +The 'data' field is the captured data, which must be in a selected encoding: +hexadecimal (the default), octal, binary, or base64 and containing no +characters in the data field outside the encoding set besides whitespace. +The 'time' field is parsed according to the format in the *-t* parameter. +The first character of the 'dir' field is compared against a set of characters +corresponding to inbound and outbound that default to "iI<" for inbound and +"oO>" for outbound to assign a direction. The 'seqno' field is assumed to +be a positive integer base 10 used for an arbitrary ID. An optional field's +information will only be written if the field is present in the regex and if +the capture file format supports it. (E.g., the pcapng format supports all +three fields, but the pcap format only supports timestamps.) + +Here is a sample dump that the regex mode can process with the regex +'^(?<dir>[<>])\s(?<time>\d+:\d\d:\d\d.\d+)\s(?<data>[0-9a-fA-F]+)$' along +with timestamp format '%H:%M:%S.%f', directional indications of '<' and '>', +and hex encoding: + + > 0:00:00.265620 a130368b000000080060 + > 0:00:00.280836 a1216c8b00000000000089086b0b82020407 + < 0:00:00.295459 a2010800000000000000000800000000 + > 0:00:00.296982 a1303c8b00000008007088286b0bc1ffcbf0f9ff + > 0:00:00.305644 a121718b0000000000008ba86a0b8008 + < 0:00:00.319061 a2010900000000000000001000600000 + > 0:00:00.330937 a130428b00000008007589186b0bb9ffd9f0fdfa3eb4295e99f3aaffd2f005 + > 0:00:00.356037 a121788b0000000000008a18 + +The regex is compiled with multiline support, and it is recommended to use +the anchors '^' and '$' for best results. + +*Text2pcap* also allows the user to read in dumps of application-level +data and insert dummy L2, L3 and L4 headers before each packet. This allows +Wireshark or any other full-packet decoder to handle these dumps. +If the encapsulation type is Ethernet, the user can elect to insert Ethernet +headers, Ethernet and IP, or Ethernet, IP and UDP/TCP/SCTP headers before +each packet. The fake headers can also be used with the Raw IP, Raw IPv4, +or Raw IPv6 encapsulations, with the Ethernet header omitted. These +encapsulation options can be used in both hexdump mode and regex mode. + +When <__infile__> or <__outfile__> are '-', standard input or standard +output, respectively, are used. + +== OPTIONS + +-a:: ++ +-- +Enables ASCII text dump identification. It allows one to identify the start of +the ASCII text dump and not include it in the packet even if it looks like HEX. +This parameter has no effect in regex mode. + +*NOTE:* Do not enable it if the input file does not contain the ASCII text dump. +-- + +-b 2|8|16|64:: ++ +-- +Specify the base (radix) of the encoding of the packet data in regex mode. +The supported options are 2 (binary), 8 (octal), 16 (hexadecimal), and 64 +(base64 encoding), with hex as the default. This parameter has no effect +in hexdump mode. +-- + +-D:: ++ +-- +Indicates that the text before each input packet may start either with an I +or O indicating that the packet is inbound or outbound. If both this flag +and the __t__ flag are used, the directional indicator is expected before +the time code. +This parameter has no effect in regex mode, where the presence of the `<dir>` +capturing group determines whether direction indicators are expected. + +Direction indication is stored in the packet headers if the output format +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 <ethertype>:: ++ +-- +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. + +For IP packets, instead of generating a fake Ethernet header you can +also use __-E rawip__ or __-l 101__ to indicate raw IP encapsulation. +Note that raw IP encapsulation does not work for any non-IP Layer 3 packet +(e.g. ARP), whereas generating a dummy Ethernet header with __-e__ works +for any sort of L3 packet. +-- + +-E <encapsulation type>:: ++ +-- +Sets the packet encapsulation type of the output capture file. +*text2pcap -E* provides a list of the available types; note that not +all file formats support all encapsulation types. The default type is +ether (Ethernet). + +*NOTE:* This sets the encapsulation type of the output file, but does +not translate the packet headers or add additional headers. It is used +to specify the encapsulation that matches the input data. +-- + +-F <file format>:: ++ +-- +Sets the file format of the output capture file. *Text2pcap* can write +the file in several formats; *text2pcap -F* provides a list of the +available output formats. The default is the *pcapng* format. +-- + +-h|--help:: +Print the version number and options and exit. + +-i <proto>:: ++ +-- +Include dummy IP headers before each packet. Specify the IP protocol +for the packet in decimal. Use this option if your dump is the payload +of an IP packet (i.e. has complete L4 information) but does not have +an IP header with each packet. Note that an appropriate Ethernet header +is automatically included with each packet as well if the link-layer +type is Ethernet. +Example: __-i 46__ to specify an RSVP packet (IP protocol 46). See +https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml for +the complete list of assigned internet protocol numbers. +-- + +-l <typenum>:: ++ +-- +Sets the packet encapsulation type of the output capture file, using +pcap link-layer header type numbers. Default is Ethernet (1). +See https://www.tcpdump.org/linktypes.html for the complete list +of possible encapsulations. +Example: __-l 7__ for ARCNet packets encapsulated BSD-style. +-- + +-m <max-packet>:: ++ +-- +Set the maximum packet length, default is 262144. +Useful for testing various packet boundaries when only an application +level datastream is available. Example: + +__od -Ax -tx1 -v stream | text2pcap -m1460 -T1234,1234 - stream.pcap__ + +will convert from plain datastream format to a sequence of Ethernet +TCP packets. +-- + +-N <intf-name>:: +Specify a name for the interface included when writing a pcapng format file. + +-o hex|oct|dec|none:: ++ +-- +Specify the radix for the offsets (hex, octal, decimal, or none). Defaults to +hex. This corresponds to the `-A` option for __od__. This parameter has no +effect in regex mode. + +*NOTE:* With __-o none__, only one packet will be created, ignoring any +direction indicators or timestamps after the first byte along with any offsets. +-- + +-P <dissector>:: ++ +-- +Include an EXPORTED_PDU header before each packet. Specify, as a +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. +Without this option, if the Upper PDU export link layer type (252) is +selected the dissector defaults to "data". +-- + +-q:: +Don't display the summary of the options selected at the beginning, or the count of packets processed at the end. + +-r <regex>:: ++ +-- +Process the file in regex mode using __regex__ as described above. + +*NOTE:* The regex mode uses memory-mapped I/O and does not work on +streams that do not support seeking, like terminals and pipes. +-- + +-s <srcport>,<destport>,<tag>:: ++ +-- +Include dummy SCTP headers before each packet. Specify, in decimal, the +source and destination SCTP ports, and verification tag, for the packet. +Use this option if your dump is the SCTP payload of a packet but does +not include any SCTP, IP or Ethernet headers. Note that appropriate +Ethernet and IP headers are automatically also included with each +packet. A CRC32C checksum will be put into the SCTP header. +-- + +-S <srcport>,<destport>,<ppi>:: ++ +-- +Include dummy SCTP headers before each packet. Specify, in decimal, the +source and destination SCTP ports, and a verification tag of 0, for the +packet, and prepend a dummy SCTP DATA chunk header with a payload +protocol identifier if __ppi__. Use this option if your dump is the SCTP +payload of a packet but does not include any SCTP, IP or Ethernet +headers. Note that appropriate Ethernet and IP headers are +automatically included with each packet. A CRC32C checksum will be put +into the SCTP header. +-- + +-t <timefmt>:: ++ +-- +Treats the text before the packet as a date/time code; __timefmt__ is a +format string supported by strftime(3), supplemented with the field +descriptor '%f' for fractional seconds up to nanoseconds. +Example: The time "10:15:14.5476" has the format code "%H:%M:%S.%f" +The special format string __ISO__ indicates that the string should be +parsed according to the ISO-8601 specification. This parameter is used +in regex mode if and only if the `<time>` capturing group is present. + +*NOTE:* Date/time fields from the current date/time are +used as the default for unspecified fields. +-- + +-T <srcport>,<destport>:: ++ +-- +Include dummy TCP headers before each packet. Specify the source and +destination TCP ports for the packet in decimal. Use this option if +your dump is the TCP payload of a packet but does not include any TCP, +IP or Ethernet headers. Note that appropriate Ethernet and IP headers +are automatically also included with each packet. +Sequence numbers will start at 0. +-- + +-u <srcport>,<destport>:: ++ +-- +Include dummy UDP headers before each packet. Specify the source and +destination UDP ports for the packet in decimal. Use this option if +your dump is the UDP payload of a packet but does not include any UDP, +IP or Ethernet headers. Note that appropriate Ethernet and IP headers +are automatically also included with each packet. +Example: __-u1000,69__ to make the packets look like TFTP/UDP packets. +-- + +-v|--version:: +Print the full version information and exit. + +-4 <srcip>,<destip>:: ++ +-- +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. +-- + +-6 <srcip>,<destip>:: ++ +-- +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 + +od(1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:mergecap.html[mergecap](1), +xref:editcap.html[editcap](1), strftime(3), 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 *Text2pcap* {wireshark-version}. +*Text2pcap* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +== AUTHORS + +.Original Author +[%hardbreaks] +Ashok Narayanan <ashokn[AT]cisco.com> diff --git a/doc/man_pages/tshark.adoc b/doc/man_pages/tshark.adoc new file mode 100644 index 00000000..2893a7d3 --- /dev/null +++ b/doc/man_pages/tshark.adoc @@ -0,0 +1,2474 @@ +include::../attributes.adoc[] += tshark(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +tshark - Dump and analyze network traffic + +== SYNOPSIS + +[manarg] +*tshark* +[ *-i* <capture interface>|- ] +[ *-f* <capture filter> ] +[ *-2* ] +[ *-r* <infile> ] +[ *-w* <outfile>|- ] +[ *options* ] +[ <filter> ] + +[manarg] +*tshark* +*-G* [ <report type> ] +[ --elastic-mapping-filter <protocols> ] +[ *-C* <profile> ] + +[manarg] +*tshark* +*-h|--help* + +[manarg] +*tshark* +*-v|--version* + +== DESCRIPTION + +*TShark* is a network protocol analyzer. It lets you capture packet +data from a live network, or read packets from a previously saved +capture file, either printing a decoded form of those packets to the +standard output or writing the packets to a file. *TShark*'s native +capture file format is *pcapng* format, which is also the format used +by *Wireshark* and various other tools. + +Without any options set, *TShark* will work much like *tcpdump*. It +will use the pcap library to capture traffic from the first available +network interface and displays a summary line on the standard output for +each received packet. + +When run with the *-r* option, specifying a capture file from which to +read, *TShark* will again work much like *tcpdump*, reading packets +from the file and displaying a summary line on the standard output for +each packet read. *TShark* is able to detect, read and write the same +capture files that are supported by *Wireshark*. The input file +doesn't need a specific filename extension; the file format and an +optional gzip, 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 +*TShark* handles this. + +Compressed file support uses (and therefore requires) the zlib library. +If the zlib library is not present when compiling *TShark*, it will be +possible to compile it, but the resulting program will be unable to read +compressed files. 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 +preferences file (which are also the fields displayed in the packet list +pane in *Wireshark*), although if it's writing packets as it captures +them, rather than writing packets from a saved capture file, it won't +show the "frame number" field. If the *-V* option is specified, it +instead writes a view of the details of the packet, showing all the +fields of all protocols in the packet. If the *-O* option is +specified, it will only show the full details for the protocols +specified, and show only the top-level detail line for all other +protocols. Use the output of "*tshark -G protocols*" to find the +abbreviations of the protocols you can specify. If the *-P* option is +specified with either the *-V* or *-O* options, both the summary line +for the entire packet and the details will be displayed. + +Packet capturing is performed with the pcap library. That library +supports specifying a filter expression; packets that don't match that +filter are discarded. The *-f* option is used to specify a capture +filter. The syntax of a capture filter is defined by the pcap library; +this syntax is different from the display filter syntax described below, +and the filtering mechanism is limited in its abilities. + +Display filters in *TShark*, which allow you to select which packets are +to be decoded or written to a file, are very powerful; more fields are +filterable in *TShark* than in other protocol analyzers, and the syntax +you can use to create your filters is richer. As *TShark* progresses, +expect more and more protocol fields to be allowed in display filters. +Display filters use the same syntax as display and color filters in +*Wireshark*; a display filter is specified with the *-Y* option. + +Display filters can be specified when capturing or when reading from a +capture file. Note that capture filters are much more efficient +than display filters, and it may be more difficult for *TShark* to keep up +with a busy network if a display filter is specified for a live capture, so +you might be more likely to lose packets if you're using a display filter. + +A capture or display filter can either be specified with the *-f* or *-Y* +option, respectively, in which case the entire filter expression must be +specified as a single argument (which means that if it contains spaces, +it must be quoted), or can be specified with command-line arguments +after the option arguments, in which case all the arguments after the +filter arguments are treated as a filter expression. If the filter is +specified with command-line arguments after the option arguments, it's a +capture filter if a capture is being done (i.e., if no *-r* option was +specified) and a display filter if a capture file is being read (i.e., if a +*-r* option was specified). + +If the *-w* option is specified when capturing packets or reading from +a capture file, *TShark* does not display packets on the standard +output. Instead, it writes the packets to a capture file with the name +specified by the *-w* option. Note that display filters are currently +not supported when capturing and saving the captured packets. + +If you want to write the decoded form of packets to a file, run +*TShark* without the *-w* option, and redirect its standard output to +the file (do __not__ use the *-w* option). + +If you want the packets to be displayed to the standard output and also +saved to a file, specify the *-P* option in addition to the *-w* +option to have the summary line displayed, specify the *-V* option +in addition to the *-w* option to have the details of the packet +displayed, and specify the *-O* option, with a list of protocols, to +have the full details of the specified protocols and the top-level +detail line for all other protocols to be displayed. If the *-P* +option is used together with the *-V* or *-O* option, the summary line +will be displayed along with the detail lines. + +When writing packets to a file, *TShark*, by default, writes the file +in *pcapng* format, and writes all of the packets it sees to the output +file. The *-F* option can be used to specify the format in which to +write the file. 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 +captured and, if packet information isn't being displayed to the +terminal, writes a continuous count of packets captured to the standard +output. If the *-q* option is specified, neither the continuous count +nor the packet information will be displayed; instead, at the end of the +capture, a count of packets captured will be displayed. If the *-Q* +option is specified, neither the initial line, nor the packet +information, nor any packet counts will be displayed. If the *-q* or +*-Q* option is used, the *-P*, *-V*, or *-O* option can be used to +cause the corresponding output to be displayed even though other output +is suppressed. + +When reading packets, the *-q* and *-Q* option will suppress the +display of the packet summary or details; this would be used if *-z* +options are specified in order to display statistics, so that only the +statistics, not the packet information, is displayed. + +The *-G* option is a special mode that simply causes *TShark* +to dump one of several types of internal glossaries and then exit. + +== OPTIONS + +-2:: ++ +-- +Perform a two-pass analysis. This causes *TShark* to buffer output until the +entire first pass is done, but allows it to fill in fields that require future +knowledge, such as 'response in frame #' fields. Also permits reassembly +frame dependencies to be calculated correctly. 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>:: ++ +-- +Specify a criterion that specifies when *TShark* is to stop writing +to a capture file. The criterion is of the form __test:value__, +where __test__ is one of: + +*duration*:__value__ Stop writing to a capture file after __value__ seconds +have elapsed. Floating point values (e.g. 0.5) are allowed. + +*files*:__value__ Stop writing to capture files after __value__ number of files +were written. + +*filesize*:__value__ Stop writing to a capture file after it reaches a size of +__value__ kB. If this option is used together with the *-b* option, *TShark* +will stop writing to the current capture file and switch to the next one if +filesize is reached. When reading a capture file, *TShark* will stop reading +the file after the number of bytes read exceeds this number (the complete +packet will be read, so more bytes than this number may be read). Note that +the filesize is limited to a maximum value of 2 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. +This does not include any packets that do not pass the display filter, so it +may differ from *-c*<capture packet count>. +-- + +-A <user>:<password>:: ++ +-- +Specify a user and a password when *TShark* captures from a rpcap:// interface +where authentication is required. + +This option is available with libpcap with enabled remote support. +-- + +-b|--ring-buffer <capture ring buffer option>:: ++ +-- +Cause *TShark* to run in "multiple files" mode. In "multiple files" mode, +*TShark* will write to several capture files. When the first capture file +fills up, *TShark* will switch writing to the next file and so on. + +The created filenames are based on the filename given with the *-w* option, +the number of the file and on the creation date and time, +e.g. outfile_00001_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 *TShark* will discard the data in the first file and start +writing to that file and so on. If the __files__ option is not set, +new files filled up until one of the capture stop conditions match (or +until the disk is full). + +The criterion is of the form __key:value__, +where __key__ is one of: + +*duration*:__value__ switch to the next file after __value__ seconds have +elapsed, even if the current file is not completely filled up. Floating +point values (e.g. 0.5) are allowed. + +*files*:__value__ begin again with the first file after __value__ number of +files were written (form a ring buffer). This value must be less than 100000. +Caution should be used when using large numbers of files: some filesystems do +not handle many files in a single directory well. The *files* criterion +requires either *duration*, *interval* or *filesize* to be specified to +control when to go to the next file. It should be noted that each *-b* +parameter takes exactly one criterion; to specify two criterion, each must be +preceded by the *-b* option. + +*filesize*:__value__ switch to the next file after it reaches a size of +__value__ kB. Note that the filesize is limited to a maximum value of 2 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 +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 +__value__ is greater than 1, make start time part before running number part +(e.g. log_20210828164426_00001.pcap). The latter makes alphabetical sorting +order equal to creation time order, and keeps related multiple file sets in +same directory close to each other. + +Example: *tshark -b filesize:1000 -b files:5* results in a ring buffer of five +files of size one megabyte each. +-- + +-B|--buffer-size <capture buffer size>:: ++ +-- +Set capture buffer size (in MiB, default is 2 MiB). This is used by +the capture driver to buffer packet data until that data can be written +to disk. If you encounter packet drops while capturing, try to increase +this size. Note that, while *TShark* attempts to set the buffer size +to 2 MiB by default, and can be told to set it to a larger value, the +system or interface on which you're capturing might silently limit the +capture buffer size to a lower value or raise it to a higher value. + +This is available on UNIX-compatible systems, such as Linux, macOS, +\*BSD, Solaris, and AIX, with libpcap 1.0.0 or later, and on Windows. +It is not available on UNIX-compatible systems with earlier versions of +libpcap. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it sets the default capture buffer size. +If used after an *-i* option, it sets the capture buffer size for +the interface specified by the last *-i* option occurring before +this option. If the capture buffer size is not set specifically, +the default capture buffer size is used instead. +-- + +-c <capture packet count>:: ++ +-- +Set the maximum number of packets to read when capturing live +data. +If reading a capture file, set the maximum number of packets to read. +This includes any packets that do not pass the display filter, so it +may differ from *-a packets:*<capture packet count>. +-- + +-C <configuration profile>:: ++ +-- +Run with the given configuration profile. If used in conjucton with +--global-profile, then the global profile with the associated name +would be used. +-- + +-D|--list-interfaces:: ++ +-- +Print a list of the interfaces on which *TShark* can capture, and +exit. For each network interface, a number and an interface name, +possibly followed by a text description of the interface, is printed. +The interface name or the number can be supplied to the *-i* flag to +specify an interface on which to capture. The number can be useful on +Windows systems, where the interfaces have long names that usually +contain a GUID. +-- + +-e <field>:: ++ +-- +Add a field to the list of fields to display if *-T ek|fields|json|pdml* +is selected. This option can be used multiple times on the command line. +At least one field must be provided if the *-T fields* option is +selected. Column types may be used prefixed with "_ws.col." + +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. +Giving a protocol rather than a single field will print the protocol summary +(subtree label) from the packet details as a single field. +If the protocol summary contains only the protocol name +(e.g. "Hypertext Transfer Protocol") then the protocol filter name ("http") +will be printed. +-- + +-E <field print option>:: ++ +-- +Set an option controlling the printing of fields when *-T fields* is +selected. + +Options are: + +*bom=y|n* If *y*, prepend output with the UTF-8 byte order mark +(hexadecimal ef, bb, bf). Defaults to *n*. + +*header=y|n* If *y*, print a list of the field names given using *-e* +as the first line of the output; the field name will be separated using +the same character as the field values. Defaults to *n*. + +*separator=/t|/s|*<character> Set the separator character to +use for fields. If */t* tab will be used (this is the default), if +*/s*, a single space will be used. Otherwise any character that can be +accepted by the command line as part of the option may be used. + +*occurrence=f|l|a* Select which occurrence to use for fields that have +multiple occurrences. If *f* the first occurrence will be used, if *l* +the last occurrence will be used and if *a* all occurrences will be used +(this is the default). + +*aggregator=,|/s|*<character> Set the aggregator character to +use for fields that have multiple occurrences. If *,* a comma will be used +(this is the default), if */s*, a single space will be used. Otherwise +any character that can be accepted by the command line as part of the +option may be used. + +*quote=d|s|n* Set the quote character to use to surround fields. *d* +uses double-quotes, *s* single-quotes, *n* no quotes (the default). +If the quote character appears in a field value, it will be escaped +by being duplicated. + +*escape=y|n* If *y*, the whitespace control characters (tab, line feed, +carriage return, form feed, and vertical tab) backspace, and the +backslash will be replaced in field values by C-style escapes, e.g. +"\n" for line feed. If *n*, field value strings will be printed as-is. +Defaults to *y*. +-- + +-f <capture filter>:: ++ +-- +Set the capture filter expression. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it sets the default capture filter expression. +If used after an *-i* option, it sets the capture filter expression for +the interface specified by the last *-i* option occurring before +this option. If the capture filter expression is not set specifically, +the default capture filter expression is used if provided. + +Pre-defined capture filter names, as shown in the GUI menu item Capture->Capture +Filters, can be used by prefixing the argument with "predef:". +Example: *tshark -f "predef:MyPredefinedHostOnlyFilter"* +-- + +-F <file format>:: +Set the file format of the output capture file written using the *-w* +option. The output written with the *-w* option is raw packet data, not +text, so there is no *-F* option to request text output. The option *-F* +without a value will list the available formats. 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 +(meaning that the output file(s) can be read by other members of the calling +user's group). + +-G [ <report type> ]:: ++ +-- +The *-G* option will cause *TShark* to dump one of several types of glossaries +and then exit. If no glossary type is specified, then the *fields* report +will be generated by default; this is deprecated and a future version will +require the report type argument. The *-G* option must be the first option given. +Using the report type of *help* lists all the current report types. + +The available report types include: + +*column-formats* Dumps the column formats understood by *TShark*. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: format string (e.g. "%rD") +Field 2:: text description of format string (e.g. "Dest port (resolved)") + +*currentprefs* Dumps a copy of the current preferences file to stdout. + +*decodes* Dumps the "layer type"/"decode as" associations to stdout. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: layer type, e.g. "tcp.port" +Field 2:: selector in decimal +Field 3:: "decode as" name, e.g. "http" + +*defaultprefs* Dumps a default preferences file to stdout. + +*dissectors* Dumps a list of registered dissectors to stdout. There is +one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: dissector name +Field 2:: dissector description + +*dissector-tables* Dumps a list of dissector tables to stdout. There +is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: dissector table name, e.g. "tcp.port" +Field 2:: name used for the dissector table in the GUI +Field 3:: type (textual representation of the ftenum type, or "heuristic") +Field 4:: base for display (for integer types) +Field 5:: protocol name +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. + +*enterprises* Dumps the IANA Private Enterprise Number (PEN) table. + +*fieldcount* Dumps the number of header fields to stdout. + +*fields* Dumps the contents of the registration database to +stdout. An independent program can take this output and format it into nice +tables or HTML or whatever. There is one record per line. Each record is +either a protocol or a header field, differentiated by the first field. +The fields are tab-delimited. + +.Protocols +[horizontal] +Field 1:: 'P' +Field 2:: descriptive protocol name +Field 3:: protocol abbreviation + +.Header Fields +[horizontal] +Field 1:: 'F' +Field 2:: descriptive field name +Field 3:: field abbreviation +Field 4:: type (textual representation of the ftenum type) +Field 5:: parent protocol abbreviation +Field 6:: base for display (for integer types); "parent bitfield width" for FT_BOOLEAN +Field 7:: bitmask: format: hex: 0x.... +Field 8:: blurb describing field + +An optional search prefix argument can be given to +*fields*, in which case the output is limited to protocols and fields whose +abbreviation starts with the search prefix. + +.Search Output +[horizontal] +Field 1:: protocol or field abbreviation +Field 2:: descriptive protocol or field name + +*folders* Dumps various folders used by *TShark*. This is essentially the +same data reported in Wireshark's About | Folders tab. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: Folder type (e.g "Personal configuration:") +Field 2:: Folder location (e.g. "/home/vagrant/.config/wireshark/") + +*ftypes* Dumps the "ftypes" (fundamental types) understood by *TShark*. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: FTYPE (e.g "FT_IPv6") +Field 2:: text description of type (e.g. "IPv6 address") + +*heuristic-decodes* Dumps the heuristic decodes currently installed. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: heuristic dissector table name (e.g. "tcp") +Field 2:: name of heuristic decoder (e.g. "ucp") +Field 3:: heuristic enabled (e.g. "T" or "F") +Field 4:: heuristic enabled by default (e.g. "T" or "F") +Field 5:: heuristic short name (e.g. "ucp_tcp") +Field 6:: heuristic display name (e.g. "UCP over TCP") + +*help* Displays the available report types. + +*manuf* Dumps the MAC address lookup table in `manuf` format. + +*plugins* Dumps the plugins currently installed. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: plugin library/Lua script/extcap executable (e.g. "gryphon.so") +Field 2:: plugin version (e.g. 0.0.4) +Field 3:: plugin type ("dissector", "tap", "file type", etc.) +Field 4:: full path to plugin file + +*protocols* Dumps the protocols in the registration database to stdout. +An independent program can take this output and format it into nice tables +or HTML or whatever. There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: protocol name +Field 2:: protocol short name +Field 3:: protocol filter name +Field 4:: protocol enabled (e.g. "T" or "F") +Field 5:: protocol enabled by default (e.g. "T" or "F") +Field 6:: protocol can toggle (e.g. "T" or "F") + +*services* Dumps the TCP, UDP, and SCTP transport service (port) table. + +*values* Dumps the value_strings, range_strings or true/false strings +for fields that have them. There is one record per line. Fields are +tab-delimited. There are three types of records: Value String, Range +String and True/False String. The first field, 'V', 'R' or 'T', indicates +the type of record. + +.Value Strings +[horizontal] +Field 1:: 'V' +Field 2:: field abbreviation to which this value string corresponds +Field 3:: Integer value +Field 4:: String + +.Range Strings +[horizontal] +Field 1:: 'R' +Field 2:: field abbreviation to which this range string corresponds +Field 3:: Integer value: lower bound +Field 4:: Integer value: upper bound +Field 5:: String + +.True/False Strings +[horizontal] +Field 1:: 'T' +Field 2:: field abbreviation to which this true/false string corresponds +Field 3:: True String +Field 4:: False String +-- + +-h|--help:: +Print the version number and options and exit. + +-H <input hosts file>:: ++ +-- +Read a list of entries from a "hosts" file, which will then be written +to a capture file. Implies *-W n*. Can be called multiple times. + +The "hosts" file format is documented at +https://en.wikipedia.org/wiki/Hosts_(file). +-- + +-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 "*tshark +-D*" (described above); a number, as reported by "*tshark -D*", can also +be used. + +If no interface is specified, *TShark* searches the list of +interfaces, choosing the first non-loopback interface if there are any +non-loopback interfaces, and choosing the first loopback interface if +there are no non-loopback interfaces. If there are no interfaces at all, +*TShark* 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 *TShark* to attempt to connect to the +specified port on the specified host and read pcapng or pcap data. + +This option can occur multiple times. When capturing from multiple +interfaces, the capture file will be saved in pcapng format. +-- + +-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 <protocol match filter>:: ++ +-- +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 -T json -j "ip ip.flags http"* +-- + +-J <protocol match filter>:: ++ +-- +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 -T pdml -J "tcp http"* +-- + +-l:: ++ +-- +Flush the standard output after the information for each packet is +printed. (This is not, strictly speaking, line-buffered if *-V* +was specified; however, it is the same as line-buffered if *-V* wasn't +specified, as only one line is printed for each packet, and, as *-l* is +normally used when piping a live capture to a program or script, so that +output for a packet shows up as soon as the packet is seen and +dissected, it should work just as well as true line-buffering. We do +this as a workaround for a deficiency in the Microsoft Visual C++ C +library.) This 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 +see the dissected data for a packet as soon as *TShark* sees the +packet and generates that output, rather than seeing it only when the +standard output buffer containing that data fills up. +-- + +-L|--list-data-link-types:: +List the data link types supported by the interface and exit. The reported +link types can be used for the *-y* option. + +-o <preference>:<value>:: ++ +-- +Set a preference value, overriding the default value and any value read +from a preference file. The argument to the option is a string of the +form __prefname:value__, where __prefname__ is the name of the +preference (which is the same name that would appear in the preference +file), and __value__ is the value to which it should be set. +-- + +-O <protocols>:: ++ +-- +Similar to the *-V* option, but causes *TShark* to only show a +detailed view of the comma-separated list of __protocols__ specified, and +show only the top-level detail line for all other protocols, rather than +a detailed view of all protocols. Use the output of "*tshark -G + protocols*" to find the abbreviations of the protocols you can specify. +-- + +-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 *TShark* 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|--print:: ++ +-- +Decode and display the packet summary or details, even if writing raw +packet data using the *-w* option, and even if packet output is +otherwise suppressed with *-Q*. +-- + +-q:: ++ +-- +When capturing packets, don't display the continuous count of packets +captured that is normally shown when saving a capture to a file; +instead, just display, at the end of the capture, a count of packets +captured. 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). + +When reading a capture file, or when capturing and not saving to a file, +don't print packet information; this is useful if you're using a *-z* +option to calculate statistics and don't want the packet information +printed, just the statistics. +-- + +-Q:: ++ +-- +When capturing packets, don't display, on the standard error, the +initial message indicating on which interfaces the capture is being +done, the continuous count of packets captured shown when saving a +capture to a file, and the final message giving the count of packets +captured. Only true errors are displayed on the standard error. + +This outputs less than the *-q* option, so the interface name and total +packet count and the end of a capture are not sent to stderr. + +When reading a capture file, or when capturing and not saving to a file, +don't print packet information; this is useful if you're using a *-z* +option to calculate statistics and don't want the packet information +printed, just the statistics. +-- + +-r|--read-file <infile>:: ++ +-- +Read packet data from __infile__, can be any supported capture file format +(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>:: ++ +-- +Cause the specified filter (which uses the syntax of read/display filters, +rather than that of capture filters) to be applied during the first pass of +analysis. Packets not matching the filter are not considered for future +passes. Only makes sense with multiple passes, see *-2*. For regular filtering +on single-pass dissect see *-Y* instead. + +Note that forward-looking fields such as 'response in frame #' cannot be used +with this filter, since they will not have been calculated when this filter is +applied. +-- + +-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 <separator>:: +Set the line separator to be printed between packets. + +-T ek|fields|json|jsonraw|pdml|ps|psml|tabs|text:: ++ +-- +Set the format of the output when viewing decoded packet data. The +options are one of: + +*ek* Newline delimited JSON format for bulk import into Elasticsearch. +It can be used with *-j* or *-J* to specify +which protocols to include or with +*-x* to include raw hex-encoded packet data. +If *-P* is specified it will print the packet summary only, with both +*-P* and *-V* it will print the packet summary and packet details. +If neither *-P* or *-V* are used it will print the packet details only. +Example of usage to import data into Elasticsearch: + + tshark -T ek -j "http tcp ip" -P -V -x -r file.pcap > file.json + curl -H "Content-Type: application/x-ndjson" -XPOST http://elasticsearch:9200/_bulk --data-binary "@file.json" + +Elastic requires a mapping file to be loaded as template for packets-* +index in order to convert Wireshark types to elastic types. This file +can be auto-generated with the command "tshark -G elastic-mapping". Since +the mapping file can be huge, protocols can be selected by using the option +--elastic-mapping-filter: + + tshark -G elastic-mapping --elastic-mapping-filter ip,udp,dns + +*fields* The values of fields specified with the *-e* option, in a +form specified by the *-E* option. For example, + + tshark -T fields -E separator=, -E quote=d + +would generate comma-separated values (CSV) output suitable for importing +into your favorite spreadsheet program. + +*json* JSON file format. It can be used with *-j* or *-J* to specify +which protocols to include or with *-x* option to include +raw hex-encoded packet data. Example of usage: + + tshark -T json -r file.pcap + tshark -T json -j "http tcp ip" -x -r file.pcap + +*jsonraw* JSON file format including only raw hex-encoded packet data. +It can be used with *-j* or *-J* to specify which protocols to include. +Example of usage: + + tshark -T jsonraw -r file.pcap + tshark -T jsonraw -j "http tcp ip" -x -r file.pcap + +*pdml* Packet Details Markup Language, an XML-based format for the +details of a decoded packet. This information is equivalent to the +packet details printed with the *-V* option. Using the *--color* option +will add color attributes to *pdml* output. These attributes are +nonstandard. + +*ps* PostScript for a human-readable one-line summary of each of the +packets, or a multi-line view of the details of each of the packets, +depending on whether the *-V* option was specified. + +*psml* Packet Summary Markup Language, an XML-based format for the summary +information of a decoded packet. This information is equivalent to the +information shown in the one-line summary printed by default. +Using the *--color* option will add color attributes to *pdml* output. These +attributes are nonstandard. + +*tabs* Similar to the default *text* report except the human-readable one-line +summary of each packet will include an ASCII horizontal tab (0x09) character +as a delimiter between each column. + +*text* Text of a human-readable one-line summary of each of the packets, or a +multi-line view of the details of each of the packets, depending on +whether the *-V* option was specified. This is the default. +-- + +--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__. +-- + +-U <tap name>:: ++ +-- +PDUs export, exports PDUs from infile to outfile according to the tap +name given. Use *-Y* to filter. + +Enter an empty tap name "" or a tap name of ? to get a list of available +names. +-- + +-v|--version:: +Print the full version information and exit. + +-V:: +Cause *TShark* to print a view of the packet details. + +-w <outfile> | -:: ++ +-- +Write raw packet data to __outfile__ or to the standard output if +__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* +option for this. +-- + +-W <file format option>:: ++ +-- +Save extra information in the file if the format supports it. For +example, + + tshark -F pcapng -W n + +will save host name resolution records along with captured packets. + +Future versions of *TShark* may automatically change the capture format +to *pcapng* as needed. + +The argument is a string that may contain the following letter: + +*n* write network address resolution information (pcapng only) +-- + +-x:: +Cause *TShark* to print a hex and ASCII dump of the packet data +after printing the summary and/or details, if either are also being displayed. + +--hexdump <hexoption>:: ++ +-- +Cause *TShark* to print a hex and ASCII dump of the packet data +with the ability to select which data sources to dump and how to +format or exclude the ASCII dump text. + +This option can be used multiple times where the data source *<hexoption>* +is *all* or *frames* and the ASCII dump text *<hexoption>* is *ascii*, +*delimit*, *noascii*. + + Example: tshark ... --hexdump frames --hexdump delimit ... + +*all*:: + +Enable hexdump, generate hexdump blocks for all data sources associated +with each frame. Used to negate earlier use of `--hexdump frames`. +The *-x* option displays all data sources by default. + +*frames*:: + +Enable hexdump, generate hexdump blocks only for the frame data. Use +this option to exclude, from hexdump output, any hexdump blocks for +secondary data sources such as 'Bitstring tvb', 'Reassembled TCP', +'De-chunked entity body', etc. + +*ascii*:: + +Enable hexdump, with undelimited ASCII dump text. Used to negate earlier +use of `--hexdump delimit` or `--hexdump noascii`. The *-x* option +displays undelimited ASCII dump text by default. + +*delimit*:: + +Enable hexdump with the ASCII dump text delimited with '|' characters. +This is useful to unambiguously determine the last of the hex byte text +and start of the ASCII dump text. + +*noascii*:: + +Enable hexdump without printing any ASCII dump text. + +*help*:: + +Display *--hexdump* specific help then exit. + +The use of *--hexdump <hexoption>* is particularly useful to generate output +that can be used to create a pcap or pcapng file from a capture file type such +as Microsoft NetMon 2.x which *TShark* and *Wireshark* can read but can not +directly do a "Save as" nor export packets from. + +Examples: + +Generate hexdump output, with only the frame data source, with delimited ASCII +dump text, with each frame hex block preceded by a human readable timestamp that +is directly usable by the *text2pcap* utility: + + tshark ... --hexdump frames --hexdump delimit \ + -P -t ad -o gui.column.format:"Time","%t" \ + | text2pcap -n -t '%F %T.%f' - MYNEWPCAPNG + +Generate hexdump output, with only the frame data source, with no ASCII dump text, +with each frame hex block preceded by an epoch timestamp that is directly +usable by the *text2pcap* utility: + + tshark ... --hexdump frames --hexdump noascii \ + -P -t e -o gui.column.format:"Time","%t" \ + | text2pcap -n -t %s.%f - MYNEWPCAPNG +-- + +-X <eXtension options>:: ++ +-- +Specify an option to be passed to a *TShark* module. The eXtension option +is in the form __extension_key:value__, where __extension_key__ can be: + +*lua_script*:__lua_script_filename__ tells *TShark* to load the given script in +addition to the default Lua scripts. + +**lua_script**__num__:__argument__ tells *TShark* 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 *TShark* to use the given file format to +read in the file (the file given in the *-r* command option). Providing no +__file_format__ argument, or an invalid one, will produce a list of available +file formats to use. For example, + + tshark -r rtcp_broken.pcapng -X read_format:"MIME Files Format" -V + +will display the internal file structure and allow access to the +`file-pcapng` fields. +-- + +-y|--linktype <capture link type>:: ++ +-- +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>:: ++ +-- +Cause the specified filter (which uses the syntax of read/display filters, +rather than that of capture filters) to be applied before printing a +decoded form of packets or writing packets to a file. Packets matching the +filter are printed or written to file; packets that the matching packets +depend upon (e.g., fragments), are not printed but are written to file; +packets not matching the filter nor depended upon are discarded rather +than being printed or written. + +Use this instead of *-R* for filtering using single-pass analysis. If doing +two-pass analysis (see *-2*) then only packets matching the read filter (if there +is one) will be checked against this filter. +-- + +-M <auto session reset>:: ++ +-- +Automatically reset internal session when reached to specified number of packets. +For example, + + tshark -M 100000 + +will reset session every 100000 packets. + +This feature does not support *-2* two-pass analysis +-- + +-z <statistics>:: ++ +-- +Get *TShark* to collect various types of statistics and display the +result after finishing reading the capture file. Use the *-q* option +if you're reading a capture file and only want the statistics printed, +not any per-packet information. + +Statistics are calculated independently of the normal per-packet output, +unaffected by the main display filter. However, most have their own +optional __filter__ parameter, and only packets that match that filter (and +any capture filter or read filter) will be used in the calculations. + +Note that the *-z proto* option is different - it doesn't cause +statistics to be gathered and printed when the capture is complete, it +modifies the regular packet summary output to include the values of +fields specified with the option. Therefore you must not use the *-q* +option, as that option would suppress the printing of the regular packet +summary output, and must also not use the *-V* option, as that would +cause packet detail information rather than packet summary information +to be printed. + +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* ancp,tree[,__filter__]:: +Calculate statistics on Access Node Control Protocol message types +and adjacency packet codes. + +*-z* ansi_a,bsmap[,__filter__]:: +Count the number of ANSI A-I/F BSMAP messages of each type. + +*-z* ansi_a,dtap[,__filter__]:: +Count the number of ANSI A-I/F DTAP messages of each type. + +*-z* ansi_map[,__filter__]:: +Count the number of ANSI MAP messages of each type, and calculate the +total number of bytes and average bytes of each message type. + +*-z* asap,stat[,__filter__]:: +Calculate statistics on Aggregate Service Access Protocol (ASAP). +For each ASAP message type, displays the number, rate, and share among +all ASAP message types of both packets and bytes, and the first and last +time that it is seen. + +*-z* bacapp_instanceid,tree[,__filter__]:: +Calculate statistics on BACnet APDUs, collated by instance ID. +Displayed information includes source and destination address and +service type. + +*-z* bacapp_ip,tree[,__filter__]:: +Calculate statistics on BACnet APDUs, collated by source and destination +address. Displayed information includes service type, object ID, and +instance ID. + +*-z* bacapp_objectid,tree[,__filter__]:: +Calculate statistics on BACnet APDUs, collated by object ID. +Displayed information includes source and destination address, +service type, and instance ID. + +*-z* bacapp_service,tree[,__filter__]:: +Calculate statistics on BACnet APDUs, collated by service type. +Displayed information includes source and destination address, +object ID, and instance ID. + +*-z* calcappprotocol,stat[,__filter__]:: +Calculate statistics on the Calculation Application Protocol of +Reliable Server Pooling. For each message type, displays the number, +rate, and share among all message types of both packets and bytes, +and the first and last time that it is seen. + +*-z* camel,counter[,__filter__]:: +Count the number of CAMEL messages for each opcode. + +*-z* camel,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for CAMEL. +Data collected is number of request messages with corresponding response +of each CAMEL message type, along with the minimum, maximum, and average +response time. + +*-z* collectd,tree[,__filter__]:: +Calculate statistics for collectd. The gathered statistics are the number +of collectd packets and the total number of value segments, along with the +host, plugin, and type of the values. + +*-z* componentstatusprotocol,stat[,__filter__]:: +Calculate statistics on the Calculation Status Protocol of Reliable +Server Pooling. For each message type, displays the number, rate +and share among all message types of both packets and bytes, and the +first and last time that it is seen. + +*-z* conv,__type__[,__filter__]:: ++ +-- +Create a table that lists all conversations that could be seen in the +capture. __type__ specifies the conversation endpoint type for which we +want to generate the statistics; currently the supported ones are: + + "bluetooth" Bluetooth addresses + "dccp" DCCP/IP socket pairs Both IPv4 and IPv6 are supported + "eth" Ethernet addresses + "fc" Fibre Channel addresses + "fddi" FDDI addresses + "ip" IPv4 addresses + "ipv6" IPv6 addresses + "ipx" IPX addresses + "jxta" JXTA message addresses + "mptcp" Multipath TCP connections + "ncp" NCP connections + "rsvp" RSVP connections + "sctp" SCTP/IP socket pairs Both IPv4 and IPv6 are supported + "sll" Linux "cooked mode" capture addresses + "tcp" TCP/IP socket pairs Both IPv4 and IPv6 are supported + "tr" Token Ring addresses + "udp" UDP/IP socket pairs Both IPv4 and IPv6 are supported + "usb" USB addresses + "wlan" IEEE 802.11 addresses + "wpan" IEEE 802.15.4 addresses + "zbee_nwk" ZigBee Network Layer addresses + +The table is presented with one line for each conversation which displays +the number of frames/bytes in each direction, the total number of +frames/bytes, relative start time and duration. +The table is sorted according to the total number of frames. +-- + +*-z* credentials:: +Collect credentials (username/passwords) from packets. The report includes +the packet number, the protocol that had that credential, the username and +the password. For protocols just using one single field as authentication, +this is provided as a password and a placeholder in place of the user. +Currently implemented protocols include FTP, HTTP, IMAP, POP, and SMTP. + +*-z* dcerpc,srt,__uuid__,__major__.__minor__[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for DCERPC interface __uuid__, +version __major__.__minor__. +Data collected is the number of calls for each procedure, MinSRT, MaxSRT +and AvgSRT. + +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. + +Example: [.nowrap]#*-z dcerpc,srt,12345778-1234-abcd-ef00-0123456789ac,1.0,ip.addr==1.2.3.4*# will collect SAMR +SRT statistics for a specific host. +-- + +*-z* dests,tree[,__filter__]:: +Calculate statistics on IPv4 destination addresses and the protocols +and ports appearing on each address. + +*-z* dhcp,stat[,__filter__]:: +Show DHCP (BOOTP) statistics. + +*-z* diameter,avp[,__cmd.code__,__field__,__field__,__...__]:: ++ +-- +This option enables extraction of most important diameter fields from large +capture files. Exactly one text line for each diameter message with matched +*diameter.cmd.code* will be printed. + +Empty diameter command code or +'*'+ can be specified to match any *diameter.cmd.code* + +Example: *-z diameter,avp* extract default field set from diameter messages. + +Example: *-z diameter,avp,280* extract default field set from diameter DWR messages. + +Example: *-z diameter,avp,272* extract default field set from diameter CC messages. + +Extract most important fields from diameter CC messages: + +*tshark -r file.cap.gz -q -z diameter,avp,272,CC-Request-Type,CC-Request-Number,Session-Id,Subscription-Id-Data,Rating-Group,Result-Code* + +Following fields will be printed out for each diameter message: + + "frame" Frame number. + "time" Unix time of the frame arrival. + "src" Source address. + "srcport" Source port. + "dst" Destination address. + "dstport" Destination port. + "proto" Constant string 'diameter', which can be used for post processing of tshark output. E.g. grep/sed/awk. + "msgnr" seq. number of diameter message within the frame. E.g. '2' for the third diameter message in the same frame. + "is_request" '0' if message is a request, '1' if message is an answer. + "cmd" diameter.cmd_code, E.g. '272' for credit control messages. + "req_frame" Number of frame where matched request was found or '0'. + "ans_frame" Number of frame where matched answer was found or '0'. + "resp_time" response time in seconds, '0' in case if matched Request/Answer is not found in trace. E.g. in the begin or end of capture. + +*-z diameter,avp* option is much faster than *-V -T text* or *-T pdml* options. + +*-z diameter,avp* option is more powerful than *-T field* and *-z proto,colinfo* options. + +Multiple diameter messages in one frame are supported. + +Several fields with same name within one diameter message are supported, e.g. +__diameter.Subscription-Id-Data__ or __diameter.Rating-Group__. + +Note: *tshark -q* option is recommended to suppress default *TShark* output. +-- + +*-z* diameter,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for Diameter. +Data collected is number of request and response pairs of each Diameter +command code, Minimum SRT, Maximum SRT, Average SRT, and Sum SRT. +Currently no statistics are gathered on unpaired messages. + +*-z* dns,tree[,__filter__]:: +Create a summary of the captured DNS packets. General information are collected +such as qtype and qclass distribution. For some data (as qname length or DNS +payload) max, min and average values are also displayed. + +*-z* endpoints,__type__[,__filter__]:: ++ +-- +Create a table that lists all endpoints that could be seen in the +capture. __type__ specifies the endpoint type for which we +want to generate the statistics; currently the supported ones are: + + "bluetooth" Bluetooth addresses + "dccp" DCCP/IP socket pairs Both IPv4 and IPv6 are supported + "eth" Ethernet addresses + "fc" Fibre Channel addresses + "fddi" FDDI addresses + "ip" IPv4 addresses + "ipv6" IPv6 addresses + "ipx" IPX addresses + "jxta" JXTA message addresses + "mptcp" Multipath TCP connections + "ncp" NCP connections + "rsvp" RSVP connections + "sctp" SCTP/IP socket pairs Both IPv4 and IPv6 are supported + "sll" Linux "cooked mode" capture addresses + "tcp" TCP/IP socket pairs Both IPv4 and IPv6 are supported + "tr" Token Ring addresses + "udp" UDP/IP socket pairs Both IPv4 and IPv6 are supported + "usb" USB addresses + "wlan" IEEE 802.11 addresses + "wpan" IEEE 802.15.4 addresses + "zbee_nwk" ZigBee Network Layer addresses + +The table is presented with one line for each endpoint which displays +the total number of packets/bytes and the number of packets/bytes in +each direction. +The table is sorted according to the total number of packets. +-- + +*-z* enrp,stat[,__filter__]:: +Calculate statistics on Endpoint Handlespace Redundancy Protocol (ENRP). +For each message type, displays the number, rate, and share among +all message types of both packets and bytes, and the first and last +time that it is seen. + +*-z* expert[__,error|,warn|,note|,chat|,comment__][,__filter__]:: ++ +-- +Collects information about all expert info, and will display them in order, +grouped by severity. + +Example: *-z expert,sip* will show expert items of all severity for frames that +match the sip protocol. + +This option can be used multiple times on the command line. + +Example: *-z "expert,note,tcp"* will only collect expert items for frames that +include the tcp protocol, with a severity of note or higher. +-- + +*-z* f1ap,tree[,__filter__]:: +Calculate the distribution of F1AP packets, grouped by packet types. + +*-z* f5_tmm_dist,tree[,__filter__]:: +Calculate the F5 Ethernet trailer Traffic Management Microkernel distribution. +Displayed information is the number of packets and bytes, grouped by the TMM +slot and number, whether packets are ingress or egress, and whether there is +a flow ID and virtual server name, a flow ID without virtual server name, or +no flow ID, along with total for all packets with F5 trailers. + +*-z* f5_virt_dist,tree[,__filter__]:: +Calculate F5 Ethernet trailer Virtual Server distribution. +Displayed information is the number of packets and bytes, grouped by the +virtual server name if it exists, or by whether there is a flow ID or not +if there is no virtual server name, as well as totals for all packets with +F5 trailers. + +*-z* fc,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for GTP. +Data collected is the number of request/response pairs, minimum SRT, +maximum SRT, average SRT, and sum SRT for each value of the Type field +(next protocol). No statistics are gathered on unpaired messages. + +*-z* flow,__name__,__mode__[,__filter__]:: ++ +-- +Displays the flow of data between two nodes. Output is the same as ASCII format +saved from GUI. + +__name__ specifies the flow name. It can be one of: + + any All frames + icmp ICMP + icmpv6 ICMPv6 + lbm_uim UIM + tcp TCP + +__mode__ specifies the address type. It can be one of: + + standard Any address + network Network address + +Example: *-z flow,tcp,network* will show data flow for all TCP frames +-- + +*-z* follow,__prot__,__mode__,__filter__[,__range__]:: ++ +-- +Displays the contents of a TCP or UDP stream between two nodes. The data +sent by the second node is prefixed with a tab to differentiate it from the +data sent by the first node. + +__prot__ specifies the transport protocol. It can be one of: + + tcp TCP + udp UDP + dccp DCCP + tls TLS or SSL + http HTTP streams + http2 HTTP/2 streams + quic QUIC streams + +NOTE: While the usage help presents sip as an option, the proper +stream filters are not implemented so SIP calls cannot be followed +in *TShark*, only in *Wireshark*. + +__mode__ specifies the output mode. It can be one of: + + ascii ASCII output with dots for non-printable characters + ebcdic EBCDIC output with dots for non-printable characters + hex Hexadecimal and ASCII data with offsets + raw Hexadecimal data + utf-8 UTF-8 output with REPLACEMENT CHARACTERs for invalid sequences + yaml YAML format + +Since the output in *ascii*, *ebcdic*, or *utf-8* mode may contain newlines, +each section of output is preceded by its length in bytes plus a newline. +(Note that for *utf-8* this is not UTF-8 characters, and may be different +than the length as transmitted due to the substitution of replacement +characters for invalid sequences.) + +__filter__ specifies the stream to be displayed. There are three formats: + + ip-addr0:port0,ip-addr1:port1 + stream-index + stream-index,substream-index + +The first format specifies IP addresses and TCP, UDP, or DCCP port pairs. +(TCP ports are used for TLS, HTTP, and HTTP2; QUIC does not support address +and port matching because of connection migration.) + +The second format specifies stream indices, and is used for TCP, UDP, DCCP, +TLS, and HTTP. (TLS and HTTP use TCP stream indices.) + +The third format, specifying streams and substreams, is used for HTTP/2 and +QUIC due to their use of multiplexing. (TCP stream and HTTP/2 stream indices +for HTTP/2, QUIC connection number and stream ID for QUIC.) + +__range__ optionally specifies which "chunks" of the stream should be displayed. + +Example: *-z "follow,tcp,hex,1"* will display the contents of the second TCP +stream (the first is stream 0) in "hex" format. + + =================================================================== + Follow: tcp,hex + Filter: tcp.stream eq 1 + Node 0: 200.57.7.197:32891 + Node 1: 200.57.7.198:2906 + 00000000 00 00 00 22 00 00 00 07 00 0a 85 02 07 e9 00 02 ...".... ........ + 00000010 07 e9 06 0f 00 0d 00 04 00 00 00 01 00 03 00 06 ........ ........ + 00000020 1f 00 06 04 00 00 ...... + 00000000 00 01 00 00 .... + 00000026 00 02 00 00 + +Example: *-z "follow,tcp,ascii,200.57.7.197:32891,200.57.7.198:2906"* will +display the contents of a TCP stream between 200.57.7.197 port 32891 and +200.57.7.98 port 2906. + + =================================================================== + Follow: tcp,ascii + Filter: (omitted for readability) + Node 0: 200.57.7.197:32891 + Node 1: 200.57.7.198:2906 + 38 + ..."..... + ................ + 4 + .... + +Example: *-z "follow,http2,hex,0,1"* will display the contents of a HTTP/2 +stream on the first TCP session (index 0) with HTTP/2 Stream ID 1. + + =================================================================== + Follow: http2,hex + Filter: tcp.stream eq 0 and http2.streamid eq 1 + Node 0: 172.16.5.1:49178 + Node 1: 172.16.5.10:8443 + 00000000 00 00 2c 01 05 00 00 00 01 82 04 8b 63 c1 ac 2a ..,..... ....c..* + 00000010 27 1d 9d 57 ae a9 bf 87 41 8c 0b a2 5c 2e 2e da '..W.... A...\... + 00000020 e1 05 c7 9a 69 9f 7a 88 25 b6 50 c3 ab b6 25 c3 ....i.z. %.P...%. + 00000030 53 03 2a 2f 2a S.*/* + 00000000 00 00 22 01 04 00 00 00 01 88 5f 87 35 23 98 ac .."..... .._.5#.. + 00000010 57 54 df 61 96 c3 61 be 94 03 8a 61 2c 6a 08 2f WT.a..a. ...a,j./ + 00000020 34 a0 5b b8 21 5c 0b ea 62 d1 bf 4.[.!\.. b.. + 0000002B 00 40 00 00 00 00 00 00 01 89 50 4e 47 0d 0a 1a .@...... ..PNG... + +-- + +*-z* fractalgeneratorprotocol,stat[,__filter__]:: ++ +-- +Calculate statistics on the Fractal Generator Protocol of Reliable +Server Pooling. For each message type, displays the number, rate +and share among all message types of both packets and bytes, and the +first and last time that it is seen. +-- + +*-z* gsm_a:: ++ +-- +Count the number of GSM A-I/F messages of each type within the following +categories: BSSMAP, DTAP Mobility Management, DTAP Radio Resource +Management, DTAP Call Control, DTAP GPRS Mobility Management, DTAP SMS +messages, DTAP GPRS Session Management, DTAP Supplementary Services, DTAP +Special Conformance Testing Functions, and SACCH Radio Resource Management. + +Unlike the individual statistics for each category that follow, this only +prints a line for each message type that appears, instead of including lines +for message types with a count of zero. +-- + +*-z* gsm_a,__category__[,__filter__]:: ++ +-- +Count the number of messages of each type in GSM A-I/F __category__, which +can be one of: + + bssmap BSSMAP + dtap_cc DTAP Call Control + dtap_gmm DTAP GPRS Mobility Management + dtap_mm DTAP Mobility Management + dtap_rr DTAP Radio Resource Management + dtap_sacch SACCH Radio Resource Management + dtap_sm DTAP GPRS Session Management + dtap_sms DTAP Short Message Service + dtap_ss DTAP Supplementary Services + dtap_tp DTAP Special Conformance Testing Functions +-- + +*-z* gsm_map,operation[,__filter__]:: +Calculate statistics on GSM MAP. For each op code, the total number of +invokes and results, along with the average and total bytes for invokes +and results separately and combined is displayed. + +*-z* gtp,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for GTP. +Data collected is the number of calls, minimum SRT, maximum SRT, average +SRT, and sum SRT for certain commands. Currently no statistics are gathered +on unpaired messages. + +*-z* gtpv2,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for GTP. +Data collected is the number of calls, minimum SRT, maximum SRT, average +SRT, and sum SRT for certain commands. Currently no statistics are gathered +on unpaired messages. + +*-z* h225,counter[,__filter__]:: ++ +-- +Count ITU-T H.225 messages and their reasons. In the first column you get a +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*. + +Example: use *-z "h225,counter,ip.addr==1.2.3.4"* to only collect stats for +H.225 packets exchanged by the host at IP address 1.2.3.4 . + +This option can be used multiple times on the command line. +-- + +*-z* h225_ras,rtd[,__filter__]:: ++ +-- +Collect requests/response RTD (Response Time Delay) data for ITU-T H.225 RAS. +Data collected is number of calls of each ITU-T H.225 RAS Message Type, +Minimum RTD, Maximum RTD, Average RTD, Minimum in Frame, and Maximum in Frame. +You will also get the number of Open Requests (Unresponded Requests), +Discarded Responses (Responses without matching request) and Duplicate Messages. + +Example: *tshark -z h225_ras,rtd* + +This option can be used multiple times on the command line. + +Example: *-z "h225_ras,rtd,ip.addr==1.2.3.4"* will only collect stats for +ITU-T H.225 RAS packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* hart_ip,tree[,__filter__]:: +Calculate statistics on HART-IP packets, grouping by message types and +message IDs within types. + +*-z* hosts[,ip][,ipv4][,ipv6]:: ++ +-- +Dump any collected resolved IPv4 and/or IPv6 addresses in "hosts" format. +Both IPv4 and IPv6 addresses are dumped by default. "ip" argument will dump +only IPv4 addresses. + +Addresses are collected from a number of sources, including standard "hosts" +files and captured traffic. Resolution must be enabled, e.g. through the +*-n* option. +-- + +*-z* hpfeeds,tree[,__filter__]:: +Calculate statistics for HPFEEDS traffic such as publish per channel, and opcode +distribution. + +*-z* http,stat[,__filter__]:: +Count the HTTP response status codes and the HTTP request methods. + +*-z* http,tree[,__filter__]:: +Calculate the HTTP packet distribution. Displayed values are the +response status codes and request methods. + +*-z* http_req,tree[,__filter__]:: +Calculate the HTTP requests by server. Displayed values are the +server name and the URI path. + +*-z* http_seq,tree[,__filter__]:: +Calculate the HTTP request sequence statistics, which correlate +referring URIs with request URIs. + +*-z* http_srv,tree[,__filter__]:: +Calculate the HTTP requests and responses by server. For the HTTP +requests, displayed values are the server IP address and server +hostname. For the HTTP responses, displayed values are the server +IP address and status. + +*-z* http2,tree[,__filter__]:: +Calculate the HTTP/2 packet distribution. Displayed values are the +frame types. + +*-z* icmp,srt[,__filter__]:: ++ +-- +Compute total ICMP echo requests, replies, loss, and percent loss, as well as +minimum, maximum, mean, median and sample standard deviation SRT statistics +typical of what ping provides. + +Example: [.nowrap]#*-z icmp,srt,ip.src==1.2.3.4*# will collect ICMP SRT statistics +for ICMP echo request packets originating from a specific host. + +This option can be used multiple times on the command line. +-- + +*-z* icmpv6,srt[,__filter__]:: ++ +-- +Compute total ICMPv6 echo requests, replies, loss, and percent loss, as well as +minimum, maximum, mean, median and sample standard deviation SRT statistics +typical of what ping provides. + +Example: [.nowrap]#*-z icmpv6,srt,ipv6.src==fe80::1*# will collect ICMPv6 SRT statistics +for ICMPv6 echo request packets originating from a specific host. + +This option can be used multiple times on the command line. +-- + +*-z* io,phs[,__filter__]:: ++ +-- +Create Protocol Hierarchy Statistics listing both number of packets and bytes. + +This option can be used multiple times on the command line. +-- + +*-z* io,stat,__interval__[,__filter__][,__filter__][,__filter__]...:: ++ +-- +Collect packet/bytes statistics for the capture in intervals of +__interval__ seconds. __Interval__ can be specified either as a whole or +fractional second and can be specified with microsecond (us) resolution. +If __interval__ is 0, the statistics will be calculated over all packets. + +If one or more __filters__ are specified statistics will be calculated for +all filters and presented with one column of statistics for each filter. + +This option can be used multiple times on the command line. + +Example: *-z io,stat,1,ip.addr==1.2.3.4* will generate 1 second +statistics for all traffic to/from host 1.2.3.4. + +Example: *-z "io,stat,0.001,smb&&ip.addr==1.2.3.4"* will generate 1ms +statistics for all SMB packets to/from host 1.2.3.4. + +The examples above all use the standard syntax for generating statistics +which only calculates the number of packets and bytes in each interval. + +*io,stat* can also do much more statistics and calculate COUNT(), SUM(), +MIN(), MAX(), AVG() and LOAD() using a slightly different filter syntax: +-- + +-z io,stat,__interval__,"COUNT|SUM|MIN|MAX|AVG|LOAD(__field__)__filter__":: ++ +-- +NOTE: One important thing to note here is that the filter is not optional +and that the field that the calculation is based on MUST be part of the filter +string or the calculation will fail. + +So: *-z io,stat,0.010,AVG(smb.time)* does not work. Use *-z + io,stat,0.010,AVG(smb.time)smb.time* instead. Also be aware that a field +can exist multiple times inside the same packet and will then be counted +multiple times in those packets. + +NOTE: A second important thing to note is that the system setting for +decimal separator must be set to "."! If it is set to "," the statistics +will not be displayed per filter. + +**COUNT** - Calculates the number of times that the +field __name__ (not its value) appears per interval in the filtered packet list. +''__field__'' can be any display filter name. + +Example: *-z io,stat,0.010,"COUNT(smb.sid)smb.sid"* + +This will count the total number of SIDs seen in each 10ms interval. + +**SUM** - Unlike COUNT, the __values__ of the +specified field are summed per time interval. +''__field__'' can only be a named integer, float, double or relative time field. + +Example: *tshark -z io,stat,0.010,"SUM(frame.len)frame.len"* + +Reports the total number of bytes that were transmitted bidirectionally in +all the packets within a 10 millisecond interval. + +**MIN/MAX/AVG** - The minimum, maximum, or average field value +in each interval is calculated. The specified field must be a named integer, +float, double or relative time field. For relative time fields, the output is +presented in seconds with six decimal digits of precision rounded to the nearest +microsecond. + +In the following example, the time of the first Read_AndX call, the last Read_AndX +response values are displayed and the minimum, maximum, and average Read response times +(SRTs) are calculated. NOTE: If the DOS command shell line continuation character, ''^'' +is used, each line cannot end in a comma so it is placed at the beginning of each +continuation line: + + tshark -o tcp.desegment_tcp_streams:FALSE -n -q -r smb_reads.cap -z io,stat,0, + "MIN(frame.time_relative)frame.time_relative and smb.cmd==0x2e and smb.flags.response==0", + "MAX(frame.time_relative)frame.time_relative and smb.cmd==0x2e and smb.flags.response==1", + "MIN(smb.time)smb.time and smb.cmd==0x2e", + "MAX(smb.time)smb.time and smb.cmd==0x2e", + "AVG(smb.time)smb.time and smb.cmd==0x2e" + + ====================================================================================================== + IO Statistics + Column #0: MIN(frame.time_relative)frame.time_relative and smb.cmd==0x2e and smb.flags.response==0 + Column #1: MAX(frame.time_relative)frame.time_relative and smb.cmd==0x2e and smb.flags.response==1 + Column #2: MIN(smb.time)smb.time and smb.cmd==0x2e + Column #3: MAX(smb.time)smb.time and smb.cmd==0x2e + Column #4: AVG(smb.time)smb.time and smb.cmd==0x2e + | Column #0 | Column #1 | Column #2 | Column #3 | Column #4 | + Time | MIN | MAX | MIN | MAX | AVG | + 000.000- 0.000000 7.704054 0.000072 0.005539 0.000295 + ====================================================================================================== + +The following command displays the average SMB Read response PDU size, the +total number of read PDU bytes, the average SMB Write request PDU size, and +the total number of bytes transferred in SMB Write PDUs: + + tshark -n -q -r smb_reads_writes.cap -z io,stat,0, + "AVG(smb.file.rw.length)smb.file.rw.length and smb.cmd==0x2e and smb.response_to", + "SUM(smb.file.rw.length)smb.file.rw.length and smb.cmd==0x2e and smb.response_to", + "AVG(smb.file.rw.length)smb.file.rw.length and smb.cmd==0x2f and not smb.response_to", + "SUM(smb.file.rw.length)smb.file.rw.length and smb.cmd==0x2f and not smb.response_to" + + ===================================================================================== + IO Statistics + Column #0: AVG(smb.file.rw.length)smb.file.rw.length and smb.cmd==0x2e and smb.response_to + Column #1: SUM(smb.file.rw.length)smb.file.rw.length and smb.cmd==0x2e and smb.response_to + Column #2: AVG(smb.file.rw.length)smb.file.rw.length and smb.cmd==0x2f and not smb.response_to + Column #3: SUM(smb.file.rw.length)smb.file.rw.length and smb.cmd==0x2f and not smb.response_to + | Column #0 | Column #1 | Column #2 | Column #3 | + Time | AVG | SUM | AVG | SUM | + 000.000- 30018 28067522 72 3240 + ===================================================================================== + +**LOAD** - The LOAD/Queue-Depth +in each interval is calculated. The specified field must be a relative time field that represents a response time. For example smb.time. +For each interval the Queue-Depth for the specified protocol is calculated. + +The following command displays the average SMB LOAD. +A value of 1.0 represents one I/O in flight. + + tshark -n -q -r smb_reads_writes.cap + -z "io,stat,0.001,LOAD(smb.time)smb.time" + + ============================================================================ + IO Statistics + Interval: 0.001000 secs + Column #0: LOAD(smb.time)smb.time + | Column #0 | + Time | LOAD | + 0000.000000-0000.001000 1.000000 + 0000.001000-0000.002000 0.741000 + 0000.002000-0000.003000 0.000000 + 0000.003000-0000.004000 1.000000 + +**FRAMES | BYTES**[()__filter__] - Displays the total number of frames or bytes. +The filter field is optional but if included it must be prepended with ''()''. + +The following command displays five columns: the total number of frames and bytes +(transferred bidirectionally) using a single comma, the same two stats using the FRAMES and BYTES +subcommands, the total number of frames containing at least one SMB Read response, and +the total number of bytes transmitted to the client (unidirectionally) at IP address 10.1.0.64. + + tshark -o tcp.desegment_tcp_streams:FALSE -n -q -r smb_reads.cap -z io,stat,0,,FRAMES,BYTES, + "FRAMES()smb.cmd==0x2e and smb.response_to","BYTES()ip.dst==10.1.0.64" + + ======================================================================================================================= + IO Statistics + Column #0: + Column #1: FRAMES + Column #2: BYTES + Column #3: FRAMES()smb.cmd==0x2e and smb.response_to + Column #4: BYTES()ip.dst==10.1.0.64 + | Column #0 | Column #1 | Column #2 | Column #3 | Column #4 | + Time | Frames | Bytes | FRAMES | BYTES | FRAMES | BYTES | + 000.000- 33576 29721685 33576 29721685 870 29004801 + ======================================================================================================================= +-- + +*-z* ip_hosts,tree[,__filter__]:: +Calculate statistics on IPv4 addresses, with source and destination addresses +all grouped together. + +*-z* ip_srcdst,tree[,__filter__]:: +Calculate statistics on IPv4 addresses, with source and destination addresses +separated into separate categories. + +*-z* ip_ttl,tree[,__filter__]:: +Calculate statistics on the time to live (TTL) values that occur for each +IPv4 source address. + +*-z* ip6_dests,tree[,__filter__]:: +Calculate statistics on IPv6 destination addresses and the protocols +and ports appearing on each address. + +*-z* ip6_hosts,tree[,__filter__]:: +Calculate statistics on IPv6 addresses, with source and destination addresses +all grouped together. + +*-z* ip6_ptype,tree[,__filter__]:: +Calculate statistics on port types that occur on IPv6 packets. + +*-z* ip6_srcdst,tree[,__filter__]:: +Calculate statistics on IPv6 addresses, with source and destination addresses +separated into separate categories. + +*-z* ip6_hop,tree[,__filter__]:: +Calculate statistics on the hop limits that occur for each IPv6 source address. + +*-z* isup_msg,tree[,__filter__]:: +Calculate statistics on ISUP messages. Displayed information is message +types and direction (originating point code and destination point code.) + +*-z* lbmr_queue_ads_queue,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays queue +advertisements collated by queue name and then source addresses and port. + +*-z* lbmr_queue_ads_source,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays queue +advertisements collated by source address and then queue and port. + +*-z* lbmr_queue_queries_queue,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays queue +queries collated by queue name and then receiver addresses. + +*-z* lbmr_queue_queries_receiver,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays queue +queries collated by receiver address and then queue. + +*-z* lbmr_topic_ads_source,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +advertisements collated by source address and then topic name and +source string. + +*-z* lbmr_topic_ads_topic,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +advertisements collated by topic name and then source address and +source string. + +*-z* lbmr_topic_ads_transport,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +advertisements collated by source string and then topic name. + +*-z* lbmr_topic_queries_pattern,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +queries collated by pattern and then receiver address. + +*-z* lbmr_topic_queries_pattern_receiver,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +queries collated by receiver address and then pattern. + +*-z* lbmr_topic_queries_receiver,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +queries collated by receiver address and then topic name. + +*-z* lbmr_topic_queries_topic,tree[,__filter__]:: +Calculate statistics on LBM Topic Resolution Packets. Displays topic +queries collated by topic name and then receiver address. + +*-z* mac-3gpp,stat[,__filter__]:: ++ +-- +This option will activate a counter for LTE 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-3gpp,stat*. + +This option can be used multiple times on the command line. + +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__]:: ++ +-- +Collect requests/response RTD (Response Time Delay) data for MEGACO. +(This is similar to *-z smb,srt*). Data collected is the number of calls +for each known MEGACO Type, MinRTD, MaxRTD and AvgRTD. +Additionally you get the number of duplicate requests/responses, +unresponded requests, responses, which don't match with any request. +Example: *-z megaco,rtd*. + +Example: *-z "megaco,rtd,ip.addr==1.2.3.4"* will only collect stats for +MEGACO packets exchanged by the host at IP address 1.2.3.4 . + +This option can be used multiple times on the command line. +-- + +*-z* mgcp,rtd[,__filter__]:: ++ +-- +Collect requests/response RTD (Response Time Delay) data for MGCP. +(This is similar to *-z smb,srt*). Data collected is the number of calls +for each known MGCP Type, MinRTD, MaxRTD and AvgRTD. +Additionally you get the number of duplicate requests/responses, +unresponded requests, responses, which don't match with any request. +Example: *-z mgcp,rtd*. + +This option can be used multiple times on the command line. + +Example: *-z "mgcp,rtd,ip.addr==1.2.3.4"* will only collect stats for +MGCP packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* mtp3,msus[,__filter__]:: +Calculate statistics on MTP3 MSUs. For each combination of originating +point code, destination point code, and service indicator, calculates +the total number of MSUs, the total bytes, and the average bytes per MSU. + +*-z* ncp,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for Netware +Core Protocol. Minimum SRT, maximum SRT, average SRT, and sum SRT is +displayed for request/response pairs, organized by group, function and +subfunction, and verb. No statistics are gathered on unpaired messages. + +*-z* osmux,tree[,__filter__]:: +Calculate statistics for the OSmux voice/signaling multiplex protocol. +Displays the total number of OSmux packets, and displays for each stream +the number of packets, number of packets with the RTP market bit set, +number of AMR frames, jitter analysis, and sequence number analysis. + +*-z* pfcp,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for PFCP. +Data collected is the number of calls, minimum SRT, maximum SRT, average +SRT, and sum SRT for certain commands. Currently no statistics are gathered +on unpaired messages. + +*-z* pingpongprotocol,stat[,__filter__]:: +Calculate statistics on the Ping Pong Protocol of Reliable +Server Pooling. For each message type, displays the number, rate +and share among all message types of both packets and bytes, and the +first and last time that it is seen. + +*-z* plen,tree[,__filter__]:: +Calculate statistics on packet lengths. Packets are grouped into buckets +that grow exponentially with powers of two. + +*-z* proto,colinfo,__filter__,__field__:: ++ +-- +Append all __field__ values for the packet to the Info column of the +one-line summary output. +This feature can be used to append arbitrary fields to the Info column +in addition to the normal content of that column. +__field__ is the display-filter name of a field which value should be placed +in the Info column. +__filter__ is a filter string that controls for which packets the field value +will be presented in the info column. __field__ will only be presented in the +Info column for the packets which match __filter__. + +NOTE: In order for *TShark* to be able to extract the __field__ value +from the packet, __field__ MUST be part of the __filter__ string. If not, +*TShark* will not be able to extract its value. + +For a simple example to add the "nfs.fh.hash" field to the Info column +for all packets containing the "nfs.fh.hash" field, use + +*-z proto,colinfo,nfs.fh.hash,nfs.fh.hash* + +To put "nfs.fh.hash" in the Info column but only for packets coming from +host 1.2.3.4 use: + +*-z "proto,colinfo,nfs.fh.hash && ip.src==1.2.3.4,nfs.fh.hash"* + +This option can be used multiple times on the command line. +-- + +*-z* ptype,tree[,__filter__]:: +Calculate statistics on port types that occur on IPv4 packets. + +*-z* radius,rtd[,__filter__]:: +Collect requests/response RTD (Response Time Delay) data for RADIUS. +The data collected for each RADIUS code is the number of calls, +Minimum RTD, Maximum RTD, Average RTD, Minimum in Frame, and Maximum in Frame, +along with the number of Open Requests (Unresponded Requests), Discarded +Responses (Responses without matching request) and Duplicate Messages. + +*-z* rlc-3gpp,stat[,__filter__]:: ++ +-- +This option will activate a counter for LTE 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-3gpp,stat*. + +This option can be used multiple times on the command line. + +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:: ++ +-- +Collect call/reply SRT data for all known ONC-RPC programs/versions. +Data collected is number of calls for each protocol/version, MinSRT, +MaxSRT and AvgSRT. +This option can only be used once on the command line. +-- + +*-z* rpc,srt,__program__,__version__[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for __program__/__version__. +Data collected is the number of calls for each procedure, MinSRT, MaxSRT, +AvgSRT, and the total time taken for each procedure. + +Example: *tshark -z rpc,srt,100003,3* will collect data for NFS v3. + +This option can be used multiple times on the command line. + +Example: *-z rpc,srt,100003,3,nfs.fh.hash==0x12345678* will collect NFS v3 +SRT statistics for a specific file. +-- + +*-z* rtp,streams:: +Collect statistics for all RTP streams and calculate max. delta, max. and +mean jitter and packet loss percentages. + +*-z* rtsp,stat[,__filter__]:: +Count the RTSP response status codes and the RSTP request methods. + +*-z* rtsp,tree[,__filter__]:: +Calculate the RTSP packet distribution. Displayed values are the +response status codes and request methods. + +*-z* sametime,tree[,__filter__]:: +Calculate statistics on SAMETIME messages. Displayed values are the +messages type, send type, and user status. + +*-z* scsi,srt,__cmdset__[,__filter__]:: ++ +-- +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. + +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* sctp,stat:: +Activate a counter for SCTP chunks. In addition to the total number of +SCTP packets, for each source and destination address and port combination +the number of chunks of the most common types (DATA, SACK, HEARTBEAT, +HEARTBEAT ACK, INIT, INIT ACK, COOKIE ECHO, COOKIE ACK, ABORT, and ERROR) +are displayed. + +*-z* sip,stat[,__filter__]:: ++ +-- +This option will activate a counter for SIP messages. You will get the number +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. + +Example: *-z "sip,stat,ip.addr==1.2.3.4"* will only collect stats for +SIP packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* smb,sids:: ++ +-- +When this feature is used *TShark* will print a report with all the +discovered SID and account name mappings. Only those SIDs where the +account name is known will be presented in the table. + +For this feature to work you will need to either to enable +"Edit/Preferences/Protocols/SMB/Snoop SID to name mappings" in the +preferences or you can override the preferences by specifying +[.nowrap]#*-o "smb.sid_name_snooping:TRUE"*# on the *TShark* command line. + +The current method used by *TShark* to find the SID->name mapping +is relatively restricted with a hope of future expansion. +-- + +*-z* smb,srt[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for SMB. Data collected +is 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 its 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. + +Example: *-z "smb,srt,ip.addr==1.2.3.4"* will only collect stats for +SMB packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* smb2,srt[,__filter__]:: +Collect call/reply SRT (Service Response Time) data for SMB versions 2 and 3. +The data collected for each normal command type is the number of calls, +MinSRT, MaxSRT, AvgSRT, and SumSRT. No data is collected on cancel or +oplock break requests, or on unpaired commands. Only the first response to +a given request is used; retransmissions are not included in the calculation. + +*-z* smpp_commands,tree[,__filter__]:: +Calculate the SMPP command distribution. Displayed values are +command IDs for both requests and responses, and status for responses. + +*-z* snmp,srt[,__filter__]:: +Collect call/reply SRT (Service Response Time) data for SNMP. The data +collected for each PDU type is the number of request/response pairs, +MinSRT, MaxSRT, AvgSRT, and SumSRT. No data is collected on unpaired +messages. + +*-z* someip_messages,tree[,__filter__]:: +Create statistic of SOME/IP messages. Messages are counted and displayed +as Messages grouped by sender/receiver. + +*-z* someipsd_entries,tree[,__filter__]:: +Create statistic of SOME/IP-SD entries. Entries are counted and displayed +as Entries grouped by sender/receiver. + +*-z* sv:: +Print out the time since the start of the capture and sample count for each +IEC 61850 Sampled Values packet. + +*-z* ucp_messages,tree[,__filter__]:: +Calculate the message distribution of UCP packets. Displayed values are +operation types for both operations and results, and whether results are +positive or negative, with error codes displayed for negative results. + +*-z* wsp,stat[,__filter__]:: +Count the PDU types and the status codes of reply packets for WSP packets. + +--capture-comment <comment>:: ++ +-- +Add a capture comment to the output file, if supported by the output +file format. + +This option may be specified multiple times. Note that Wireshark +currently only displays the first comment of a capture file. +-- + +--list-time-stamp-types:: +List time stamp types supported for the interface. If no time stamp type can be +set, no time stamp types are listed. + +--time-stamp-type <type>:: +Change the interface's timestamp method. + +--update-interval <interval>:: +Set the length of time in milliseconds between new packet reports during +a capture. Also sets the granularity of file duration conditions. +The default value is 100ms. + +--color:: +Enable coloring of packets according to standard Wireshark color +filters. On Windows colors are limited to the standard console +character attribute colors. Other platforms require a terminal that +handles 24-bit "true color" terminal escape sequences. See +{wireshark-wiki-url}ColoringRules for more information on +configuring color filters. + +--no-duplicate-keys:: +If a key appears multiple times in an object, only write it a single time with +as value a json array containing all the separate values. (Only works with +*-T json*) + +--elastic-mapping-filter <protocol>,<protocol>,...:: ++ +-- +When generating the ElasticSearch mapping file, only put the specified protocols +in it, to avoid a huge mapping file that can choke some software (such as Kibana). +The option takes a list of wanted protocol abbreviations, separated by comma. + +Example: ip,udp,dns puts only those three protocols in the mapping file. +-- + +--export-objects <protocol>,<destdir>:: ++ +-- +Export all objects within a protocol into directory *destdir*. The available +values for *protocol* can be listed with *--export-objects help*. + +The objects are directly saved in the given directory. Filenames are dependent +on the dissector, but typically it is named after the basename of a file. +Duplicate files are not overwritten, instead an increasing number is appended +before the file extension. + +This interface is subject to change, adding the possibility to filter on files. +-- + +--print-timers:: +Output JSON containing elapsed times for each pass tshark does to process a capture +file and the sum elapsed time for all passes. The per-pass output contains the total +elapsed time and aggregate counters for per-packet operations (dissection and filtering). + +--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[] + +== 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. + +== 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. + +include::files.adoc[tags=**;!gui] + +== OUTPUT + +*TShark* uses UTF-8 to represent strings internally. In some cases the +output might not be valid. For example, a dissector might generate +invalid UTF-8 character sequences. Programs reading *TShark* output +should expect UTF-8 and be prepared for invalid output. + +If *TShark* detects that it is writing to a TTY on a UNIX-compatible +system, such as Linux, macOS, \*BSD, Solaris, and AIX, and the locale +does not support UTF-8, output will be re-encoded to match the current +locale. + +If *TShark* detects that it is writing to the console on Windows, +dissection output will be encoded as UTF-16LE. Other output will be +UTF-8. If extended characters don't display properly in your terminal +you might try setting your console code page to UTF-8 (*chcp 65001*) +and using a modern terminal application if possible. + +== 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, *TShark* will call abort(3) +when a dissector bug is encountered. abort(3) will cause the program to +exit abnormally; if you are running *TShark* in a debugger, it +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, *TShark* will call abort(3) +if a dissector tries to add too many items to a tree (generally this +is an indication of the dissector not breaking out of a loop soon enough). +abort(3) will cause the program to exit abnormally; if you are running +*TShark* 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_LOG_LEVEL:: +This environment variable controls the verbosity of diagnostic messages to +the console. From less verbose to most verbose levels can be `critical`, +`warning`, `message`, `info`, `debug` or `noisy`. Levels above the +current level are also active. Levels `critical` and `error` are always +active. + +WIRESHARK_LOG_FATAL:: +Sets the fatal log level. Fatal log levels cause the program to abort. +This level can be set to `Error`, `critical` or `warning`. `Error` is +always fatal and is the default. + +WIRESHARK_LOG_DOMAINS:: +This environment variable selects which log domains are active. The filter is +given as a case-insensitive comma separated list. If set only the included +domains will be enabled. The default domain is always considered to be enabled. +Domain filter lists can be preceded by '!' to invert the sense of the match. + +WIRESHARK_LOG_DEBUG:: +List of domains with `debug` log level. This sets the level of the provided +log domains and takes precedence over the active domains filter. If preceded +by '!' this disables the `debug` level instead. + +WIRESHARK_LOG_NOISY:: +Same as above but for `noisy` log level instead. + +== SEE ALSO + +xref:wireshark-filter.html[wireshark-filter](4), xref:wireshark.html[wireshark](1), xref:editcap.html[editcap](1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:dumpcap.html[dumpcap](1), +xref:text2pcap.html[text2pcap](1), xref:mergecap.html[mergecap](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 *TShark* {wireshark-version}. +*TShark* is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +*TShark* uses the same packet dissection code that *Wireshark* does, +as well as using many other modules from *Wireshark*; see the list of +authors in the *Wireshark* man page for a list of authors of that code. diff --git a/doc/man_pages/udpdump.adoc b/doc/man_pages/udpdump.adoc new file mode 100644 index 00000000..37b5934c --- /dev/null +++ b/doc/man_pages/udpdump.adoc @@ -0,0 +1,121 @@ +include::../attributes.adoc[] += udpdump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +udpdump - Provide a UDP receiver that gets packets from network devices (like Aruba routers) and exports them in PCAP format. + +== SYNOPSIS + +[manarg] +*udpdump* +[ *--help* ] +[ *--version* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--port*=<port> ] +[ *--payload*=<type> ] + +== DESCRIPTION + +*udpdump* is a extcap tool that provides a UDP receiver that listens for exported datagrams coming from +any source (like Aruba routers) and exports them in PCAP format. This provides the user two basic +functionalities: the first one is to have a listener that prevents the localhost to send back an ICMP +port-unreachable packet. The second one is to strip out the lower layers (layer 2, IP, UDP) that are useless +(are used just as export vector). The format of the exported datagrams are EXPORTED_PDU, as specified in +https://gitlab.com/wireshark/wireshark/-/raw/master/epan/exported_pdu.h + +== OPTIONS + +--help:: +Print program arguments. + +--version:: +Print program version. + +--extcap-interfaces:: +List available interfaces. + +--extcap-interface=<interface>:: +Use specified interfaces. + +--extcap-dlts:: +List DLTs of specified interface. + +--extcap-config:: +List configuration options of specified interface. + +--capture:: +Start capturing from specified interface save saved it in place specified by --fifo. + +--fifo=<path to file or pipe>:: +Save captured packet to file or send it through pipe. + +--port=<port>:: +Set the listener port. Port 5555 is the default. + +--payload=<type>:: +Set the payload of the exported PDU. Default: data. + +== EXAMPLES + +To see program arguments: + + udpdump --help + +To see program version: + + udpdump --version + +To see interfaces: + + udpdump --extcap-interfaces + +.Example output + interface {value=udpdump}{display=UDP Listener remote capture} + +To see interface DLTs: + + udpdump --extcap-interface=udpdump --extcap-dlts + +.Example output + dlt {number=252}{name=udpdump}{display=Exported PDUs} + +To see interface configuration options: + + udpdump --extcap-interface=udpdump --extcap-config + +.Example output + arg {number=0}{call=--port}{display=Listen port}{type=unsigned}{range=1,65535}{default=5555}{tooltip=The port the receiver listens on} + +To capture: + + udpdump --extcap-interface=randpkt --fifo=/tmp/randpkt.pcapng --capture + +NOTE: To stop capturing CTRL+C/kill/terminate the application. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4) + +== NOTES + +*udpdump* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Dario Lombardo <lomato[AT]gmail.com> diff --git a/doc/man_pages/wifidump.adoc b/doc/man_pages/wifidump.adoc new file mode 100644 index 00000000..d23ee092 --- /dev/null +++ b/doc/man_pages/wifidump.adoc @@ -0,0 +1,229 @@ +include::../attributes.adoc[] += wifidump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +wifidump - Provides an interface to capture Wi-Fi frames from a remote host through SSH. + +== SYNOPSIS + +[manarg] +*wifidump* +[ *--help* ] +[ *--version* ] +[ *--extcap-interfaces* ] +[ *--extcap-dlts* ] +[ *--extcap-interface*=<interface> ] +[ *--extcap-config* ] +[ *--extcap-capture-filter*=<capture filter> ] +[ *--capture* ] +[ *--fifo*=<path to file or pipe> ] +[ *--remote-host*=<IP address> ] +[ *--remote-port*=<TCP port> ] +[ *--remote-username*=<username> ] +[ *--remote-password*=<password> ] +[ *--sshkey*=<public key path> ] +[ *--remote-interface*=<interface> ] +[ *--remote-channel-frequency*=<channel frequency> ] +[ *--remote-channel-width*=<channel width> ] + +[manarg] +*wifidump* +*--extcap-interfaces* + +[manarg] +*wifidump* +*--extcap-interface*=<interface> +*--extcap-dlts* + +[manarg] +*wifidump* +*--extcap-interface*=<interface> +*--extcap-config* + +[manarg] +*wifidump* +*--extcap-interface*=<interface> +*--fifo*=<path to file or pipe> +*--capture* +*--remote-host=myremotehost* +*--remote-port=22* +*--remote-username=user* +*--remote-interface=eth2* +*--remote-channel-frequency=5180* +*--remote-channel-width=40* + +== DESCRIPTION + +*Wifidump* is an extcap tool that allows you to capture Wi-Fi traffic from a +remote host over an SSH connection using *tcpdump*. The requirement to capture Wi-Fi +frames is that the remote host must have the necessary binaries to manage and put +the wanted interface into monitor mode. Such binaries include: *ip*, *iw*, and +*iwconfig*. Also, because using monitor mode and managing the Wi-Fi interface requires +root privileges, the system must be configured to allow the wanted user to run +these binaries using sudo without entering a password. + +Typically wifidump is not invoked directly. Instead it can be configured through +the Wireshark graphical user interface or its command line. The following will +start Wireshark and start capturing from host *remotehost*: + + $ wireshark '-oextcap.wifidump.remotehost:remotehost' -i wifidump -k + +To explicitly control the remote capture command: + + $ wireshark '-oextcap.wifidump.remotehost:remotehost' \ + '-oextcap.wifidump.remotechannelfrequency:5180' \ + '-oextcap.wifidump.remotechannelwidth:40' \ + -i wifidump -k + +Supported interfaces: + +1. wifidump + +== OPTIONS + +--help:: +Print program arguments. + +--version:: +Print program version. + +--extcap-interfaces:: +List available interfaces. + +--extcap-interface=<interface>:: +Use specified interfaces. + +--extcap-dlts:: +List DLTs of specified interface. + +--extcap-config:: +List configuration options of specified interface. + +--capture:: +Start capturing from 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. + +--remote-host=<remote host>:: +The address of the remote host for capture. + +--remote-port=<remote port>:: +The SSH port of the remote host. + +--remote-username=<username>:: +The username for ssh authentication. + +--remote-password=<password>:: +The password to use (if not ssh-agent and pubkey are used). WARNING: the +passwords are stored in plaintext and visible to all users on this system. It is +recommended to use keyfiles with a SSH agent. + +--sshkey=<SSH private key path>:: +The path to a private key for authentication. + +--remote-interface=<remote interface>:: +The remote network interface to capture from. + +--remote-channel-frequency=<channel frequency>:: +The remote channel frequency in MHz. + +--remote-channel-width=<channel width>:: +The remote channel width in MHz. + +--extcap-capture-filter=<capture filter>:: +The capture filter. It corresponds to the value provided via the *tshark -f* +option, and the Capture Filter field next to the interfaces list in the +Wireshark interface. + +== EXAMPLES + +To see program arguments: + + wifidump --help + +To see program version: + + wifidump --version + +To see interfaces: + + wifidump --extcap-interfaces + +Only one interface (wifidump) is supported. + +.Example output + interface {value=wifidump}{display=Wi-Fi remote capture} + +To see interface DLTs: + + wifidump --extcap-interface=wifidump --extcap-dlts + +.Example output + dlt {number=147}{name=wifidump}{display=Remote capture dependent DLT} + +To see interface configuration options: + + wifidump --extcap-interface=wifidump --extcap-config + +.Example output + arg {number=0}{call=--remote-host}{display=Remote SSH server address}{type=string} + {tooltip=The remote SSH host. It can be both an IP address or a hostname}{required=true}{group=Server} + arg {number=1}{call=--remote-port}{display=Remote SSH server port}{type=unsigned} + {tooltip=The remote SSH host port (1-65535)}{range=1,65535}{group=Server} + arg {number=2}{call=--remote-username}{display=Remote SSH server username}{type=string} + {tooltip=The remote SSH username. If not provided, the current user will be used}{group=Authentication} + arg {number=3}{call=--remote-password}{display=Remote SSH server password}{type=password} + {tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.}{group=Authentication} + arg {number=4}{call=--sshkey}{display=Path to SSH private key}{type=fileselect} + {tooltip=The path on the local filesystem of the private ssh key}{mustexist=true}{group=Authentication} + arg {number=5}{call=--sshkey-passphrase}{display=SSH key passphrase}{type=password} + {tooltip=Passphrase to unlock the SSH private key}{group=Authentication} + arg {number=6}{call=--remote-interface}{display=Remote interface}{type=string} + {tooltip=The remote network interface used to capture}{default=auto}{group=Capture} + arg {number=7}{call=--remote-channel-frequency}{display=Remote channel}{type=selector} + {tooltip=The remote channel used to capture}{group=Capture} + arg {number=8}{call=--remote-channel-width}{display=Remote channel width}{type=selector} + {tooltip=The remote channel width used to capture}{group=Capture} + arg {number=9}{call=--remote-filter}{display=Remote capture filter}{type=string} + {tooltip=The remote capture filter}{group=Capture} + arg {number=10}{call=--remote-count}{display=Packets to capture}{type=unsigned} + {tooltip=The number of remote packets to capture.}{group=Capture} + arg {number=11}{call=--log-level}{display=Set the log level}{type=selector} + {tooltip=Set the log level}{required=false}{group=Debug} + arg {number=12}{call=--log-file}{display=Use a file for logging}{type=fileselect} + {tooltip=Set a file where log messages are written}{required=false}{group=Debug} + +To capture: + + wifidump --extcap-interface=wifidump --fifo=/tmp/wifidump.pcap --capture --remote-host 192.168.1.10 --remote-username user --remote-channel-frequency 5180 --remote-channel-width 40 + +NOTE: To stop capturing CTRL+C/kill/terminate application. + +The wifidump binary can be renamed to support multiple instances. For instance if we want wifidump +to show up twice in wireshark (for instance to handle multiple profiles), we can copy wifidump to +wifidump-host1 and wifidump-host2. Each binary will show up an interface name same as the executable +name. Those executables not being "wifidump" will show up as "custom version" in the interface description. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:extcap.html[extcap](4), xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](1) + +== NOTES + +*Wifidump* is part of the *Wireshark* distribution. The latest version +of *Wireshark* can be found at https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. + +== AUTHORS + +.Original Author +[%hardbreaks] +Adrian Granados <adrian[AT]intuitibits.com> diff --git a/doc/man_pages/wireshark-filter.adoc b/doc/man_pages/wireshark-filter.adoc new file mode 100644 index 00000000..2de71423 --- /dev/null +++ b/doc/man_pages/wireshark-filter.adoc @@ -0,0 +1,761 @@ +include::../attributes.adoc[] += wireshark-filter(4) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: {css_dir}/{stylesheet} + +== NAME + +wireshark-filter - Wireshark display filter syntax and reference + +== SYNOPSIS + +*wireshark* [other options] +[.nowrap]#[ *-Y* "display filter expression" | *--display-filter* "display filter expression" ]# + +*tshark* [other options] +[.nowrap]#[ *-Y* "display filter expression" | *--display-filter* "display filter expression" ]# + +== DESCRIPTION + +*Wireshark* and *TShark* share a powerful filter engine that helps remove +the noise from a packet trace and lets you see only the packets that interest +you. If a packet meets the requirements expressed in your filter, then it +is displayed in the list of packets. Display filters let you compare the +fields within a protocol against a specific value, compare fields against +fields, and check the existence of specified fields or protocols. + +Filters are also used by other features such as statistics generation and +packet list colorization (the latter is only available to *Wireshark*). This +manual page describes their syntax. A comprehensive reference of filter fields +can be found within Wireshark and in the display filter reference at +https://www.wireshark.org/docs/dfref/. + +== FILTER SYNTAX + +=== Check whether a field or protocol exists + +The simplest filter allows you to check for the existence of a protocol or +field. If you want to see all packets which contain the IP protocol, the +filter would be "ip" (without the quotation marks). To see all packets +that contain a Token-Ring RIF field, use "tr.rif". + +Whenever a protocol or field appears as the argument of a function in a filter, +an exists operator for that protocol or field implicitly appears. + +=== Values and operators + +Each field has a value, and that value can be used in operations with +comparable values (which may be literals, other fields, or function results). +The value of a field is not necessarily what appears in the *Wireshark* +display or *TShark* output. For example, a protocol is semantically +equivalent to the sequence of bytes that it spans, not its displayed text +in the protocol tree. + +=== Comparison operators + +The comparison operators can be expressed either through English-like +abbreviations or through C-like symbols: + + eq, == Equal + ne, != Not Equal + gt, > Greater Than + lt, < Less Than + ge, >= Greater than or Equal to + le, <= Less than or Equal to + +The ordering depends on the value type in the usual way (e.g., lexicographic +for strings and arithmetic for integers.) A field may appear more than once +in a given frame. In that case equality can be strict (all fields must match +the condition) or not (any field must match the condition). The inequality is +the logical negation of equality. The following table contains all equality +operators, their aliases and meaning: + + eq, any_eq, == Any field must be equal + ne, all_ne, != All fields must be not equal + all_eq, === All fields must be equal + any_ne, !== Any fields must be not equal + +The operators "any" or "all" can be used with any comparison operator to make +the test match any or all fields: + + all tcp.port > 1024 + + any ip.addr != 1.1.1.1 + +The "any" and "all" modifiers take precedence over comparison operators such +as "===" and "any_eq". + +=== Search and match operators + +Additional operators exist expressed only in English, not C-like syntax: + + contains Does the protocol, field or slice contain a value + matches, ~ Does the string match the given case-insensitive + Perl-compatible regular expression + +The "contains" operator allows a filter to search for a sequence of +characters, expressed as a string, or bytes, expressed as a byte array. +The type of the left hand side of the "contains" operator must be comparable to +that of the right hand side after any implicit or explicit conversions. + +For example, to search for a given HTTP +URL in a capture, the following filter can be used: + + http contains "https://www.wireshark.org" + +The "contains" operator cannot be used on atomic fields, +such as numbers or IP addresses. + +The "matches" or "~" operator allows a filter to apply to a specified +Perl-compatible regular expression (PCRE2). The regular expression must +be a double quoted string. The left hand side of the "matches" operator +must be a string, which can be a non-stringlike field implicitly or +explicitly converted to a string. Matches are case-insensitive by default. +For example, to search for a given WAP WSP User-Agent, you can write: + + wsp.header.user_agent matches "cldc" + +This would match "cldc", "CLDC", "cLdC" or any other combination of upper +and lower case letters. + +You can force case sensitivity using + + wsp.header.user_agent matches "(?-i)cldc" + +This is an example of PCRE2's *(?*+option+*)* construct. *(?-i)* performs a +case-sensitive pattern match but other options can be specified as well. More +information can be found in the +pcre2pattern(3)|https://www.pcre.org/current/doc/html/pcre2pattern.html man page. + +=== Functions + +The filter language has the following functions: + + upper(string-field) - converts a string field to uppercase + lower(string-field) - converts a string field to lowercase + 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 + +upper() and lower() are useful for performing case-insensitive string +comparisons. For example: + + upper(ncp.nds_stream_name) contains "MACRO" + lower(mount.dump.hostname) == "angel" + +string() converts a field value to a string, suitable for use with operators like +"matches" or "contains". Integer fields are converted to their decimal representation. +It can be used with IP/Ethernet addresses (as well as others), but not with string or +byte fields. For example: + + string(frame.number) matches "[13579]$" + +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: +// `tshark -G ftypes | sed -e 's/.*\t/ /' | sort -f -u`, then fix up by hand + + ASN.1 object identifier, plain or relative + AX.25 address + Boolean + Byte sequence + Character string + Character, 1 byte + Date and time + Ethernet or other MAC address + EUI64 address + Fibre Channel WWN + Floating point, single or double precision + Frame number + Globally Unique Identifier + IEEE-11073 floating point, 16 or 32 bits + IPv4 address + IPv6 address + IPX network number + Label + OSI System-ID + Protocol + Signed integer, 1, 2, 3, 4, or 8 bytes + Time offset + Unsigned integer, 1, 2, 3, 4, or 8 bytes + VINES address + +An integer may be expressed in decimal, octal, hexadecimal or binary notation, +or as a C-style character constant. The following seven display filters +are equivalent: + + frame.len > 10 + frame.len > 012 + frame.len > 0xa + frame.len > 0b1010 + frame.len > '\n' + frame.len > '\x0a' + frame.len > '\012' + +Boolean values are either true or false. In a display filter expression +testing the value of a Boolean field, true is expressed as the word `true` +(case-insensitive) or any non-zero number. False is expressed as +`false` (case-insensitive) or the number zero. For example, a token-ring packet's +source route field is Boolean. To find any source-routed packets, a display +filter would be any of the following: + + tr.sr == 1 + tr.sr == true + tr.sr == TRUE + +Non source-routed packets can be found with: + + tr.sr == 0 + tr.sr == false + tr.sr == FALSE + +Ethernet addresses and byte arrays are represented by hex +digits. The hex digits may be separated by colons, periods, or hyphens: + + eth.dst eq ff:ff:ff:ff:ff:ff + aim.data == 0.1.0.d + fddi.src == aa-aa-aa-aa-aa-aa + echo.data == 7a + +IPv4 addresses can be represented in either dotted decimal notation or +by using the hostname: + + ip.src == 192.168.1.1 + ip.dst eq www.mit.edu + +IPv4 addresses can be compared with the same logical relations as numbers: +eq, ne, gt, ge, lt, and le. The IPv4 address is stored in host order, +so you do not have to worry about the endianness of an IPv4 address +when using it in a display filter. + +Classless Inter-Domain Routing (CIDR) notation can be used to test if an +IPv4 address is in a certain subnet. For example, this display filter +will find all packets in the 129.111 network: + + ip.addr == 129.111.0.0/16 + +Remember, the number after the slash represents the number of bits used +to represent the network. CIDR notation can also be used with +hostnames, as in this example of finding IP addresses on the same +network as 'sneezy' (requires that 'sneezy' resolve to an IP address for filter to be valid): + + ip.addr eq sneezy/24 + +The CIDR notation can only be used on IP addresses or hostnames, not in +variable names. So, a display filter like "ip.src/24 == ip.dst/24" is +not valid (yet). + +Transaction and other IDs are often represented by unsigned 16 or 32 bit integers +and formatted as a hexadecimal string with "0x" prefix: + + (dhcp.id == 0xfe089c15) || (ip.id == 0x0373) + +Strings are enclosed in double quotes: + + http.request.method == "POST" + +Inside double quotes, you may use a backslash to embed a double quote +or an arbitrary byte represented in either octal or hexadecimal. + + browser.comment == "An embedded \" double-quote" + +Use of hexadecimal to look for "HEAD": + + http.request.method == "\x48EAD" + +Use of octal to look for "HEAD": + + http.request.method == "\110EAD" + +This means that you must escape backslashes with backslashes inside +double quotes. + + smb.path contains "\\\\SERVER\\SHARE" + +looks for \\SERVER\SHARE in "smb.path". This may be more conveniently written +as + + smb.path contains r"\\SERVER\SHARE" + +String literals prefixed with 'r' are called "raw strings". Such strings treat +backslash as a literal character. Double quotes may still be escaped with +backslash but note that backslashes are always preserved in the result. + +The following table lists all escape sequences supported with strings +and character constants: + + \' single quote + \" double quote + \\ backslash + \a audible bell + \b backspace + \f form feed + \n line feed + \r carriage return + \t horizontal tab + \v vertical tab + \NNN arbitrary octal value + \xNN arbitrary hexadecimal value + \uNNNN Unicode codepoint U+NNNN + \UNNNNNNNN Unicode codepoint U+NNNNNNNN + +Date and time values can be given in ISO 8601 format or using a legacy +month-year-time format: + + "2020-07-04T12:34:56" + "Sep 26, 2004 23:18:04.954975" + +The 'T' separator in ISO 8601 can be omitted. The timezone can be given +as "Z" or an offset from UTC. + +When not using ISO 8601 the timezone can be given as the strings "UTC", "GMT" +or "UT" for UTC or also given as an offset from UTC, plus some North American and Nautical/Military +designations (https://man.netbsd.org/strptime.3[see the specification for %z in strptime(3)]). +Note that arbitrary timezone names are not supported however. + +If the timezone is omitted then date and time values are interpreted as local time. + +=== The slice operator + +You can take a slice of a field if the field base type is a text string or a +byte array (the base type of most network address fields is bytes). +For example, you can filter on the vendor portion of an ethernet address +(the first three bytes) like this: + + eth.src[0:3] == 00:00:83 + +Another example is: + + http.content_type[0:4] == "text" + +You can use the slice operator on a protocol name, too. +The "frame" protocol can be useful, encompassing all the data captured +by *Wireshark* or *TShark*. + + token[0:5] ne 0.0.0.1.1 + llc[0] eq aa + frame[100-199] contains "wireshark" + +The following syntax governs slices: + + [i:j] i = start_offset, j = length + [i-j] i = start_offset, j = end_offset, inclusive. + [i] i = start_offset, length = 1 + [:j] start_offset = 0, length = j + [i:] start_offset = i, end_offset = end_of_field + +Slice indexes are zero-based. +Offsets can be negative, in which case they indicate the +offset from the *end* of the field. The last byte of the field is at offset +-1, the last but one byte is at offset -2, and so on. +Here's how to check the last four bytes of a frame: + + frame[-4:4] == 0.1.2.3 + +or + + frame[-4:] == 0.1.2.3 + +As mentioned above the slice operator can be used on string and byte fields +and will respectively produce string or byte slices. String slices are +indexed on UTF-8 codepoint boundaries (i.e: internationalized characters), +so the following comparison is true: + + "touché"[5] == "é" + +The example above generates an error because the compiler rejects constant +expressions but is otherwise syntactically correct and exemplifies the +behaviour of string slices. + +To obtain a byte slice of the same string the raw (@) operator can be used: + + @"touché"[5-6] == c3:a9 + +A slice can always be compared against either a string or a byte sequence. + +Slices can be combined. You can concatenate them using the comma operator: + + ftp[1,3-5,9:] == 01:03:04:05:09:0a:0b + +This concatenates offset 1, offsets 3-5, and offset 9 to the end of the ftp +data. + +=== The layer operator + +A field can be restricted to a certain layer in the protocol stack using the +layer operator (#), followed by a decimal number: + + ip.addr#2 == 192.168.30.40 + +matches only the inner (second) layer in the packet. +Layers use simple stacking semantics and protocol layers are counted sequentially starting from 1. +For example, in a packet that contains two IPv4 headers, the outer (first) source address can be matched with "ip.src#1" and the inner (second) source address can be matched with "ip.src#2". + +For more complicated ranges the same syntax used with slices is valid: + + tcp.port#[2-4] + +means layers number 2, 3 or 4 inclusive. The hash symbol is required to +distinguish a layer range from a slice. + +=== The at operator + +By prefixing the field name with an at sign (@) the comparison is done against +the raw packet data for the field. + +A character string must be decoded from a source encoding during dissection. +If there are decoding errors the resulting string will usually contain +replacement characters: + +[subs="replacements"] +---- +browser.comment == "string is ����" +---- + +The at operator allows testing the raw undecoded data: + + @browser.comment == 73:74:72:69:6e:67:20:69:73:20:aa:aa:aa:aa + +The syntactical rules for a bytes field type apply to the second example. + +=== The membership operator + +A field may be checked for matches against a set of values simply with the +membership operator. For instance, you may find traffic on common HTTP/HTTPS +ports with the following filter: + + tcp.port in {80,443,8080} + +as opposed to the more verbose: + + tcp.port == 80 or tcp.port == 443 or tcp.port == 8080 + +To find HTTP requests using the HEAD or GET methods: + + http.request.method in {"HEAD", "GET"} + +The set of values can also contain ranges: + + tcp.port in {443, 4430..4434} + ip.addr in {10.0.0.5 .. 10.0.0.9, 192.168.1.1..192.168.1.9} + frame.time_delta in {10 .. 10.5} + +=== Implicit type conversions + +Fields which are sequences of bytes, including protocols, are implicitly +converted to strings for comparisons against (double quoted) literal strings +and raw strings. + +So, for instance, the following filters are equivalent: + + tcp.payload contains "GET" + tcp.payload contains 47.45.54 + +As noted above, a slice can also be compared in either way: + + frame[60:2] gt 50.51 + frame[60:2] gt "PQ" + +The inverse does not occur; stringlike fields are not implicitly converted to +byte arrays. (Some operators allow stringlike fields to be compared with +unquoted literals, which are then treated as strings; this is deprecated in +general and specifically disallowed by the "matches" operator. +Literal strings should be double quoted for clarity.) + +A hex integer that is 0xff or less (which means it fits inside one byte) +can be implicitly converted to a byte string. This is not allowed for +hex integers greater than one byte, because then one would need to specify +the endianness of the multi-byte integer. Also, this is not allowed for +decimal or octal numbers, since they would be confused with the hex numbers +that make up byte string literals. Nevertheless, single-byte hex integers +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: + + 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. + +When testing for TCP SYN packets, you can write: + + tcp.flags & 0x02 + +That expression will match all packets that contain a "tcp.flags" field +with the 0x02 bit, i.e. the SYN bit, set. + +To match locally administered unicast ethernet addresses you can use: + + eth.addr[0] & 0x0f == 2 + +When using slices, the bit mask must be specified as a byte string, and it must +have the same number of bytes as the slice itself, as in: + + ip[42:2] & 40:ff + +=== Arithmetic operators + +Arithmetic expressions are supported with the usual operators: + + + Addition + - Subtraction + * Multiplication + / 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: + + udp.dstport >= udp.srcport + 1 + +It is possible to group arithmetic expressions using curly brackets (parenthesis +will not work for this): + + tcp.dstport >= 4 * {tcp.srcport + 3} + +Do not confuse this usage of curly brackets with set membership. + +An unfortunate quirk in the filter syntax is that the subtraction operator +must be preceded by a space character, so "A-B" must be written as "A -B" +or "A - B". + +=== Protocol field references + +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. + +=== Logical expressions + +Tests can be combined using logical expressions. +These too are expressible in C-like syntax or with English-like +abbreviations. The following table lists the logical operators from +highest to lowest precedence: + + not, ! Logical NOT (right-associative) + and, && Logical AND (left-associative) + xor, ^^ Logical XOR (left-associative) + or, || Logical OR (left-associative) + +The evaluation is always performed left to right. Expressions can be grouped +by parentheses as well. The expression "A and B or not C or D and not E or F" +is read: + + (A and B) or (not C) or (D and (not E)) or F + +It's usually better to be explicit about grouping using parenthesis. +The following are all valid display filter expressions: + + tcp.port == 80 and ip.src == 192.168.2.1 + not llc + http and frame[100-199] contains "wireshark" + (ipx.src.net == 0xbad && ipx.src.node == 0.0.0.0.0.1) || ip + +Remember that whenever a protocol or field name occurs in an expression, the +"exists" operator is implicitly called. The "exists" operator has the highest +priority. This means that the first filter expression must be read as "show me +the packets for which tcp.port exists and equals 80, and ip.src exists and +equals 192.168.2.1". The second filter expression means "show me the packets +where not exists llc", or in other words "where llc does not exist" and hence +will match all packets that do not contain the llc protocol. +The third filter expression includes the constraint that offset 199 in the +frame exists, in other words the length of the frame is at least 200. + +Because each comparison has an implicit exists test for field values care must +be taken when using the display filter to remove noise from +the packet trace. If, for example, you want to filter out all IP +multicast packets to address 224.1.2.3, then using: + + ip.dst ne 224.1.2.3 + +may be too restrictive. This is the same as writing: + + ip.dst and ip.dst ne 224.1.2.3 + +The filter selects only frames that have the "ip.dst" field. Any +other frames, including all non-IP packets, will not be displayed. To +display the non-IP packets as well, you can use one of the following +two expressions: + + not ip.dst or ip.dst ne 224.1.2.3 + not ip.dst eq 224.1.2.3 + +The first filter uses "not ip.dst" to include all non-IP packets and then +lets "ip.dst ne 224.1.2.3" filter out the unwanted IP packets. The +second filter also negates the implicit existence test and so is +a shorter way to write the first. + +== FILTER FIELD REFERENCE + +The entire list of display filters is too large to list here. You can +can find references and examples at the following locations: + +* The online Display Filter Reference: https://www.wireshark.org/docs/dfref/ + +* __View:Internals:Supported Protocols__ in Wireshark + +* `tshark -G fields` on the command line + +* The Wireshark wiki: {wireshark-wiki-url}DisplayFilters + +== NOTES + +The *xref:wireshark-filter.html[wireshark-filter](4)* manpage is part of the *Wireshark* distribution. +The latest version of *Wireshark* can be found at +https://www.wireshark.org. + +Regular expressions in the "matches" operator are provided by the PCRE2 library. +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, {wireshark-wiki-url}CaptureFilters +for a description of capture filters. + +Display Filters are also described in the link:{wireshark-users-guide-url}ChWorkBuildDisplayFilterSection.html[Wireshark User's Guide]. + +== SEE ALSO + +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:editcap.html[editcap](1), xref:https://www.tcpdump.org/manpages/pcap.3pcap.html[pcap](3), xref:https://www.tcpdump.org/manpages/pcap-filter.7.html[pcap-filter](7) or xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](8) if it +doesn't exist. + +== AUTHORS + +See the list of authors in the *Wireshark* man page for a list of authors of +that code. 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}. |