diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-10 20:34:10 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-10 20:34:10 +0000 |
| commit | e4ba6dbc3f1e76890b22773807ea37fe8fa2b1bc (patch) | |
| tree | 68cb5ef9081156392f1dd62a00c6ccc1451b93df /doc | |
| parent | Initial commit. (diff) | |
| download | wireshark-e4ba6dbc3f1e76890b22773807ea37fe8fa2b1bc.tar.xz wireshark-e4ba6dbc3f1e76890b22773807ea37fe8fa2b1bc.zip | |
Adding upstream version 4.2.2.upstream/4.2.2
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc')
55 files changed, 21601 insertions, 0 deletions
diff --git a/doc/CMakeLists-PROTOABBREV.txt b/doc/CMakeLists-PROTOABBREV.txt new file mode 100644 index 0000000..f8a62b9 --- /dev/null +++ b/doc/CMakeLists-PROTOABBREV.txt @@ -0,0 +1,71 @@ +# CMakeLists.txt +# +# Wireshark - Network traffic analyzer +# Copyright YEARS, YOUR_NAME <YOUR_EMAIL_ADDRESS> +# +# SPDX-License-Identifier: LICENSE +# + +include(WiresharkPlugin) + +# Plugin name and version info (major minor micro extra) +set_module_info(PROTOABBREV 0 0 1 0) + +set(DISSECTOR_SRC + # Source files that directly dissect data + packet-PROTOABBREV.c +) + +set(DISSECTOR_SUPPORT_SRC + # Source files that provide additional routines +) + +set(PLUGIN_FILES + plugin.c + ${DISSECTOR_SRC} + ${DISSECTOR_SUPPORT_SRC} +) + +set_source_files_properties( + ${PLUGIN_FILES} + PROPERTIES + COMPILE_FLAGS "${WERROR_COMMON_FLAGS}" +) + +register_plugin_files(plugin.c + plugin + ${DISSECTOR_SRC} + ${DISSECTOR_SUPPORT_SRC} +) + +add_wireshark_plugin_library(PROTOABBREV epan) + +target_link_libraries(PROTOABBREV epan) + +install_plugin(PROTOABBREV epan) + +file(GLOB DISSECTOR_HEADERS RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" "*.h") +CHECKAPI( + NAME + PROTOABBREV + SWITCHES + --group dissectors-prohibited + --group dissectors-restricted + SOURCES + ${DISSECTOR_SRC} + ${DISSECTOR_SUPPORT_SRC} + ${DISSECTOR_HEADERS} +) + +# +# Editor modelines - https://www.wireshark.org/tools/modelines.html +# +# Local variables: +# c-basic-offset: 8 +# tab-width: 8 +# indent-tabs-mode: t +# End: +# +# vi: set shiftwidth=8 tabstop=8 noexpandtab: +# :indentSize=8:tabSize=8:noTabs=false: +# diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000..674554f --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,175 @@ +# CMakeLists.txt +# +# Wireshark - Network traffic analyzer +# By Gerald Combs <gerald@wireshark.org> +# Copyright 1998 Gerald Combs +# +# SPDX-License-Identifier: GPL-2.0-or-later +# + +find_package( Asciidoctor 1.5 ) + +set(MAN1_SOURCE_FILES) +set(MAN4_SOURCE_FILES) +set(MAN1_INSTALL_FILES) +set(MAN4_INSTALL_FILES) +set(HTML_INSTALL_FILES) + +macro (ADD_MAN_PAGE _page_name _man_section) + if(ASCIIDOCTOR_FOUND) + list(APPEND HTML_INSTALL_FILES ${CMAKE_CURRENT_BINARY_DIR}/${_page_name}.html) + + if (${_man_section} EQUAL 1) + list(APPEND MAN1_SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/${_page_name}.adoc) + list(APPEND MAN1_INSTALL_FILES ${CMAKE_CURRENT_BINARY_DIR}/${_page_name}.${_man_section}) + elseif (${_man_section} EQUAL 4) + list(APPEND MAN4_SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/${_page_name}.adoc) + list(APPEND MAN4_INSTALL_FILES ${CMAKE_CURRENT_BINARY_DIR}/${_page_name}.${_man_section}) + else() + message(FATAL_ERROR "Unsupported manual page section ${_man_section} for ${_page_name}") + endif() + endif() +endmacro() + +ADD_MAN_PAGE(wireshark 1) +ADD_MAN_PAGE(androiddump 1) +ADD_MAN_PAGE(capinfos 1) +ADD_MAN_PAGE(captype 1) +ADD_MAN_PAGE(ciscodump 1) +ADD_MAN_PAGE(dumpcap 1) +ADD_MAN_PAGE(editcap 1) +ADD_MAN_PAGE(mergecap 1) +ADD_MAN_PAGE(randpkt 1) +ADD_MAN_PAGE(randpktdump 1) +ADD_MAN_PAGE(etwdump 1) +ADD_MAN_PAGE(rawshark 1) +ADD_MAN_PAGE(reordercap 1) +ADD_MAN_PAGE(sshdump 1) +ADD_MAN_PAGE(text2pcap 1) +ADD_MAN_PAGE(tshark 1) +ADD_MAN_PAGE(falcodump 1) +ADD_MAN_PAGE(udpdump 1) +ADD_MAN_PAGE(wifidump 1) + +ADD_MAN_PAGE(extcap 4) +ADD_MAN_PAGE(wireshark-filter 4) + +if(BUILD_dpauxmon AND HAVE_LIBNL3) + ADD_MAN_PAGE(dpauxmon 1) +endif() + +if(BUILD_sdjournal AND SYSTEMD_FOUND) + ADD_MAN_PAGE(sdjournal 1) +endif() + +if(MAXMINDDB_FOUND) + ADD_MAN_PAGE(mmdbresolve 1) +endif() + +if (BUILD_corbaidl2wrs) + ADD_MAN_PAGE(idl2wrs 1) +endif() + +if (BUILD_xxx2deb) + ADD_MAN_PAGE(asn2deb 1) + ADD_MAN_PAGE(idl2deb 1) +endif() + +set(WIRESHARK_BUNDLE_RESOURCE_SHARE_MAN1_FILES ${MAN1_INSTALL_FILES} PARENT_SCOPE) +set(WIRESHARK_BUNDLE_RESOURCE_SHARE_MAN4_FILES ${MAN4_INSTALL_FILES} PARENT_SCOPE) +# XXX We need a Logray-specific man page list, which might overlap with Wireshark's. +# Just install everything for now. +set(LOGRAY_BUNDLE_RESOURCE_SHARE_MAN1_FILES ${WIRESHARK_BUNDLE_RESOURCE_SHARE_MAN1_FILES} PARENT_SCOPE) +set(LOGRAY_BUNDLE_RESOURCE_SHARE_MAN4_FILES ${WIRESHARK_BUNDLE_RESOURCE_SHARE_MAN4_FILES} PARENT_SCOPE) + +set(MAN_INCLUDES diagnostic-options.adoc dissection-options.adoc) + +if(ASCIIDOCTOR_FOUND) + ASCIIDOCTOR2ROFFMAN(1 ${MAN1_SOURCE_FILES}) + ASCIIDOCTOR2ROFFMAN(4 ${MAN4_SOURCE_FILES}) + ASCIIDOCTOR2HTMLMAN(${MAN1_SOURCE_FILES} ${MAN4_SOURCE_FILES}) + + add_custom_target(manpages DEPENDS + ${MAN1_INSTALL_FILES} + ${MAN4_INSTALL_FILES} + ) + set_target_properties(manpages PROPERTIES FOLDER "Documentation") +endif() + +if(ASCIIDOCTOR_FOUND) + ASCIIDOCTOR2HTML(release-notes.adoc) + ASCIIDOCTOR2TXT(release-notes.adoc) + + list(APPEND HTML_INSTALL_FILES "${CMAKE_CURRENT_BINARY_DIR}/release-notes.html") + + add_custom_target(release_notes_html + DEPENDS + ${CMAKE_CURRENT_BINARY_DIR}/release-notes.html + ) + set_target_properties(release_notes_html PROPERTIES FOLDER "Documentation") + add_custom_target(release_notes_txt + DEPENDS + ${CMAKE_CURRENT_BINARY_DIR}/release-notes.txt + ) + set_target_properties(release_notes_txt PROPERTIES FOLDER "Documentation") + add_custom_target(release_notes + DEPENDS + release_notes_html + release_notes_txt + ) + set_target_properties(release_notes PROPERTIES FOLDER "Documentation") + + add_custom_target(news + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_BINARY_DIR}/release-notes.txt + ${CMAKE_SOURCE_DIR}/NEWS + DEPENDS + release_notes_txt + ) + set_target_properties(news PROPERTIES FOLDER "Documentation") +endif() + +add_custom_target( + docs ALL + DEPENDS + ${MAN1_INSTALL_FILES} + ${MAN4_INSTALL_FILES} + ${HTML_INSTALL_FILES} +) +set_target_properties(docs PROPERTIES FOLDER "Documentation") + +if(ASCIIDOCTOR_FOUND) + install( + FILES + ${MAN1_INSTALL_FILES} + DESTINATION + ${CMAKE_INSTALL_MANDIR}/man1 + ) + + install( + FILES + ${MAN4_INSTALL_FILES} + DESTINATION + ${CMAKE_INSTALL_MANDIR}/man4 + ) +endif() + +install( + FILES + ${HTML_INSTALL_FILES} + DESTINATION + ${CMAKE_INSTALL_DOCDIR} +) + +# +# Editor modelines - https://www.wireshark.org/tools/modelines.html +# +# Local variables: +# c-basic-offset: 8 +# tab-width: 8 +# indent-tabs-mode: t +# End: +# +# vi: set shiftwidth=8 tabstop=8 noexpandtab: +# :indentSize=8:tabSize=8:noTabs=false: +# diff --git a/doc/README.capture b/doc/README.capture new file mode 100644 index 0000000..9191316 --- /dev/null +++ b/doc/README.capture @@ -0,0 +1,138 @@ +This document is an attempt, to bring some light to the things done, when +packet capturing is performed. There might be things missing, and others +maybe wrong :-( The following will concentrate a bit on the Windows +port of Wireshark. + + +XXX: when ongoing file reorganization will be completed, the following +two lists maybe won't be needed any longer! + +libpcap related source files: +----------------------------- +capture-pcap-util.c +capture-pcap-util.h +capture-pcap-util-int.h +capture-pcap-util-unix.c +capture-wpcap.c +capture-wpcap.h + +Capture related source files: +----------------------------- +capture.c +capture.h +capture_loop.c +capture_loop.h +capture_opts.c +capture_sync.c +capture_ui_utils.c +capture_ui_utils.h + + +Capture driver +-------------- +Wireshark doesn't have direct access to the capture hardware. Instead of this, +it uses the Libpcap/Winpcap library to capture data from network cards. + +On Win32, in capture-wpcap.c the function load_wpcap_module() is called +to load the wpcap.dll. This dll includes all functions needed for +packet capturing. + + + +Capture File +------------ +There are some kinds of targets to put the capture data into: + +-temporary file +-user specified "single" capture file +-user specified "ringbuffer" capture file + +Which kind of file is used depends on the user settings. In principle there +is no difference in handling these files, so if not otherwise notified, +it will be called the capture file. + +The capture file is stored, using the wiretap library. + + +Overview +-------- +Capturing is done using a two task model: the currently running (parent) +process will spawn a child process to do the real capture work, namely +controlling libpcap. This two task model is used because it's necessary +to split the capturing process (which should avoid packet drop) from the parent +process which might need significant time to display the data. + +When a capture is started, the parent builds a "command line" and creates a +new child process with it. A pipe from the child to the parent is created +which is used to transfer control messages. + +The child will init libpcap and send the parent a "new capture file is used" +control message through the pipe. + +The child cyclically takes the packet data from libpcap and saves it to disk. +From time to time it will send the parent a "new packets" control message. + +If the parent process receives this "new packets" message and the option +"Update list of packets in real time" is used, it will read the packet data +from the file, dissect and display it. + + +If the user wants to stop the capture, this can be done in two ways: by +menu/toolbar of the parent process or the Stop button of the child processes +dialog box (which obviously cannot be used it this dialog is hidden). + +The Stop button will stop the capture itself, close the control pipe and then +closes itself. The parent will detect this and stop its part of the capture. + +If the menu/toolbar is used, the parent will send a break signal to the child +which will lead to the same sequence as described above. + +Win32 only: as the windows implementation of signals simply doesn't work, +another pipe from the parent to the child is used to send a "close capture" +message instead of a signal. + + +Start capture +------------- +A capture is started, by specifying to start the capture at the command line, +trigger the OK button in the "Capture Options" dialog box and some more. The +capture start is actually done by calling the capture_start() function in +capture.c. + + +Capture child (Loop) +-------------------- +The capture child will open the target capture file, prepare pcap things, +init stop conditions, init the capture statistic dialog (if not hidden) and +start a loop which is running until the flag ld.go is false. + +Inside this loop, + +-Qt main things are updated +-pcap_dispatch(capture_pcap_cb) is called +-the capture stop conditions are checked (ld.go is set to false to finish) +-update the capture statistic dialog (if not hidden) + +While this loop is running, the pcap_dispatch() will call capture_pcap_cb() +for every packet captured. Inside this, the packet data is converted into +wtap (wiretap) format and saved to file. Beside saving, it is trying to +do some basic dissecting (for the statistic window), by calling the +appropriate capture_xxx function. + +When the user triggered a capture stop or one of the capture stop conditions +matched, the ld.go flag is set to false, and the loop will stop shortly after. + + +Capture parent +-------------- +In the capture parent the cap_pipe_input_cb() function is called "cyclically" +(unix:waiting for pipe, win32:timer,1000ms) to read data from the pipe and show +it on the main screen. While the capture is in progress, no other capture file +can be opened. + + +Updating +-------- +The actual packet capturing inside the libpcap is done using its own task. +Catching and processing the packet data from the libpcap is done using the +pcap_dispatch() function. diff --git a/doc/README.design b/doc/README.design new file mode 100644 index 0000000..e35cbd0 --- /dev/null +++ b/doc/README.design @@ -0,0 +1,57 @@ +Unfortunately, the closest thing to a design document is the +"README.developer" document in the "doc" directory of the Wireshark +source tree; however, although that's useful for people adding new +protocol dissectors to Wireshark, it doesn't describe the operations of +the "core" of Wireshark. + +We have no document describing that; however, a quick summary of the +part of the code you'd probably be working with is: + + for every capture file that Wireshark has open, there's a + "capture_file" structure - Wireshark currently supports only one + open capture file at a time, and that structure is named + "cfile" (see the "file.h" header file); + + that structure has a member "plist", which points to a + "frame_data" structure - every link-layer frame that Wireshark + has read in has a "frame_data" structure (see the + "epan/packet.h" header file), the "plist" member of "cfile" + points to the first frame, and each frame has a "next" member + that points to the next frame in the capture (or is null for the + last frame); + + each "frame_data" struct has: + + a pointer to the next frame (null for the last frame); + + a pointer to the previous frame (null for the first + frame); + + information such as the ordinal number of the frame in + the capture, the time stamps for the capture, the size + of the packet data in bytes, the size of the frame in + bytes (which might not equal the size of the packet data + if, for example, the program capturing the packets + captured no more than the first N bytes of the capture, + for some value of N); + + the byte offset in the capture file where the frame's + data is located. + +See the "print_packets()" routine in "file.c" for an example of a +routine that goes through all the packets in the capture; the loop does + + for (fdata = cf->plist; fdata != NULL; fdata = fdata->next) { + + update a progress bar (because it could take a + significant period of time to process all packets); + + read the packet data if the packet is to be printed; + + print the packet; + + } + +The "wtap_seek_read()" call reads the packet data into memory; the +"epan_dissect_new()" call "dissects" that data, building a tree +structure for the fields in the packet. diff --git a/doc/README.developer b/doc/README.developer new file mode 100644 index 0000000..6d6ede9 --- /dev/null +++ b/doc/README.developer @@ -0,0 +1,995 @@ +This file is a HOWTO for Wireshark developers. It describes general development +and coding practices for contributing to Wireshark no matter which part of +Wireshark you want to work on. + +To learn how to write a dissector, read this first, then read the file +README.dissector. + +This file is compiled to give in depth information on Wireshark. +It is by no means all inclusive and complete. Please feel free to discuss on +the developer mailing list or upload merge requests to gitlab. + +0. Prerequisites. + +Before starting to develop a new dissector, a "running" Wireshark build +environment is required - there's no such thing as a standalone "dissector +build toolkit". + +How to setup such an environment is platform dependent; detailed +information about these steps can be found in the "Developer's Guide" +(available from: https://www.wireshark.org) and in the INSTALL and +README.md files of the sources root dir. + +0.1. General README files. + +You'll find additional information in the following README files: + +- doc/README.capture - the capture engine internals +- doc/README.design - Wireshark software design - incomplete +- doc/README.developer - this file +- doc/README.dissector - How to dissect a packet +- doc/README.display_filter - Display Filter Engine +- doc/README.idl2wrs - CORBA IDL converter +- doc/README.regression - regression testing of WS and TS +- doc/README.stats_tree - a tree statistics counting specific packets +- doc/README.tapping - "tap" a dissector to get protocol specific events +- doc/README.vagrant - how to create a development VM using vagrant +- doc/README.wslua - working with LUA +- doc/README.xml-output - how to work with the PDML exported output +- wiretap/README.developer - how to add additional capture file types to + Wiretap + +0.2. Dissector related README files. + +You'll find additional dissector related information in the file +README.dissector as well as the following README files: + +- doc/README.heuristic - what are heuristic dissectors and how to write + them +- doc/README.plugins - how to "pluginize" a dissector +- doc/README.request_response_tracking - how to track req./resp. times and such +- doc/README.wmem - how to obtain "memory leak free" memory + +0.3 Contributors + +James Coe <jammer[AT]cin.net> +Gilbert Ramirez <gram[AT]alumni.rice.edu> +Jeff Foster <jfoste[AT]woodward.com> +Olivier Abad <oabad[AT]cybercable.fr> +Laurent Deniel <laurent.deniel[AT]free.fr> +Gerald Combs <gerald[AT]wireshark.org> +Guy Harris <guy[AT]alum.mit.edu> +Ulf Lamping <ulf.lamping[AT]web.de> + +1. Portability. + +Wireshark runs on many platforms, and can be compiled with a number of +different compilers; here are some rules for writing code that will work +on multiple platforms. + +Building Wireshark requires a compiler that supports C11. This includes +reasonably recent versions of GCC and clang. Microsoft Visual Studio supports +C11 from Visual Studio 2019 version 16.8 and later. Support requires an updated +Universal C Runtime (UCRT) and Windows SDK version to work properly with the +conforming preprocessor. The minimum SDK version is 10.0.20348.0 (version 2104). + +The C11 has some optional parts that are not a requirement to build Wireshark. +In particular the following optional C11 features must NOT be used: + - Variable length arrays + - Bounds-checking interfaces (Annex K) + +We don't allow them because their value is questionable and requiring them +would exclude a lot of compilers and runtimes that we wish to support. + +Don't initialize global or static variables (variables with static +storage duration) in their declaration with non-constant values. This is not +permitted in C. E.g., if "i" is a static or global +variable, don't declare "i" as + + uint32_t i = somearray[2]; + +outside a function, or as + + static uint32_t i = somearray[2]; + +inside or outside a function, declare it as just + + uint32_t i; + +or + + static uint32_t i; + +and later, in code, initialize it with + + i = somearray[2]; + +instead. Initializations of variables with automatic storage duration - +i.e., local variables - with non-constant values is permitted, so, +within a function + + uint32_t i = somearray[2]; + +is allowed. + +Don't use zero-length arrays as structure members, use flexible array members +instead. + +Don't use "uchar", "u_char", "ushort", "u_short", "uint", "u_int", +"ulong", "u_long" or "boolean"; they aren't defined on all platforms. + +GLib typedefs have historically been used extensively throughout the +codebase (gchar, guint8, gint16, etc). We are moving towards the fixed +width integers provided in C since C99. These are defined in <stdint.h>, +which is included in <wireshark.h>. You should choose stdint types when +possible, but realise that until we can fully migrate our APIs, in many +situations the GLib types still make sense. + +If you want an 8-bit unsigned quantity, use "uint8_t"; if you want an +8-bit character value with the 8th bit not interpreted as a sign bit, +use "unsigned char"; if you want a 16-bit unsigned quantity, use "uint16_t"; +if you want a 32-bit unsigned quantity, use "uint32_t"; and if you want +an "int-sized" unsigned quantity, use "unsigned"; if you want a boolean, +use "bool" (defined in <stdbool.h>). You don't need to explicitly include +these headers; they are included in <wireshark.h>. Use that instead. + +To print fixed width integers you must use the macros provided in <inttypes.h>. + + uint32_t var; + printf("var = " PRIu32 "\n", var); + +Don't use "long" to mean "signed 32-bit integer", and don't use +"unsigned long" to mean "unsigned 32-bit integer"; "long"s are 64 bits +long on many platforms. Use "int32_t" for signed 32-bit integers and use +"uint32_t" for unsigned 32-bit integers. + +Don't use "long" to mean "signed 64-bit integer" and don't use "unsigned +long" to mean "unsigned 64-bit integer"; "long"s are 32 bits long on +many other platforms. Don't use "long long" or "unsigned long long", +either, as not all platforms support them; use "int64_t" or "uint64_t", +which will be defined as the appropriate types for 64-bit signed and +unsigned integers. + +On LLP64 data model systems (notably 64-bit Windows), "int" and "long" +are 32 bits while "size_t" and "ptrdiff_t" are 64 bits. This means that +the following will generate a compiler warning: + + int i; + i = strlen("hello, sailor"); /* Compiler warning */ + +Normally, you'd just make "i" a size_t. However, many GLib and Wireshark +functions won't accept a size_t on LLP64: + + size_t i; + char greeting[] = "hello, sailor"; + unsigned byte_after_greet; + + i = strlen(greeting); + byte_after_greet = tvb_get_guint8(tvb, i); /* Compiler warning */ + +Try to use the appropriate data type when you can. When you can't, you +will have to cast to a compatible data type, e.g. + + size_t i; + char greeting[] = "hello, sailor"; + uint8_t byte_after_greet; + + i = strlen(greeting); + byte_after_greet = tvb_get_guint8(tvb, (int) i); /* OK */ + +or + + int i; + char greeting[] = "hello, sailor"; + uint8_t byte_after_greet; + + i = (int) strlen(greeting); + byte_after_greet = tvb_get_guint8(tvb, i); /* OK */ + +See http://www.unix.org/version2/whatsnew/lp64_wp.html for more +information on the sizes of common types in different data models. + +A lot of legacy code still uses GLib types and I/O replacement API. These +should be gradually transitioned to use the standard interfaces provided in +C11. Sometimes it may be necessary to use an unsavory cast or two or abuse +a macro to bridge the two codebases during the transition. Such is life, +use your judgement and do the best possible under the circumstances. + +Avoid GLib synonyms like gchar and gint and especially don't +use gpointer and gconstpointer, unless you are writing GLib callbacks +and trying to match their signature exactly. These just obscure the +code and gconstpointer in particular is just semantically weird and poor style. + +When printing or displaying the values of 64-bit integral data types, +don't use "%lld", "%llu", "%llx", or "%llo" - not all platforms +support "%ll" for printing 64-bit integral data types. Instead use +the macros in <inttypes.h>, for example: + + proto_tree_add_uint64_format_value(tree, hf_uint64, tvb, offset, len, + val, "%" PRIu64, val); + +For GLib routines, and only those, you can choose whichever format style +you prefer: + + uint64_t val = UINT64_C(1); + char *str1 = g_string_printf("%" G_GUINT64_FORMAT, val); + char *str2 = g_string_printf("%" PRIu64, val); + +These format macros will be the same modulo any GLib bugs. + +When specifying an integral constant that doesn't fit in 32 bits, don't +use "LL" at the end of the constant - not all compilers use "LL" for +that. Instead, put the constant in a call to the "INT64_C()" or "UINT64_C()" +macro, e.g. + + INT64_C(-11644473600), UINT64_C(11644473600) + +rather than + + -11644473600LL, 11644473600ULL + +Don't assume that you can scan through a va_list initialized by va_start +more than once without closing it with va_end and re-initializing it with +va_start. This applies even if you're not scanning through it yourself, +but are calling a routine that scans through it, such as vfprintf() or +one of the routines in Wireshark that takes a format and a va_list as an +argument. You must do + + va_start(ap, format); + call_routine1(xxx, format, ap); + va_end(ap); + va_start(ap, format); + call_routine2(xxx, format, ap); + va_end(ap); + +rather than + + va_start(ap, format); + call_routine1(xxx, format, ap); + call_routine2(xxx, format, ap); + va_end(ap); + +Don't use a label without a statement following it. For example, +something such as + + if (...) { + + ... + + done: + } + +will not work with all compilers - you have to do + + if (...) { + + ... + + done: + ; + } + +with some statement, even if it's a null statement, after the label. +Preferably don't do it at all. + +Don't use "bzero()", "bcopy()", or "bcmp()"; instead, use the ANSI C +routines + + "memset()" (with zero as the second argument, so that it sets + all the bytes to zero); + + "memcpy()" or "memmove()" (note that the first and second + arguments to "memcpy()" are in the reverse order to the + arguments to "bcopy()"; note also that "bcopy()" is typically + guaranteed to work on overlapping memory regions, while + "memcpy()" isn't, so if you may be copying from one region to a + region that overlaps it, use "memmove()", not "memcpy()" - but + "memcpy()" might be faster as a result of not guaranteeing + correct operation on overlapping memory regions); + + and "memcmp()" (note that "memcmp()" returns 0, 1, or -1, doing + an ordered comparison, rather than just returning 0 for "equal" + and 1 for "not equal", as "bcmp()" does). + +Not all platforms necessarily have "bzero()"/"bcopy()"/"bcmp()", and +those that do might not declare them in the header file on which they're +declared on your platform. + +Don't use "index()" or "rindex()"; instead, use the ANSI C equivalents, +"strchr()" and "strrchr()". Not all platforms necessarily have +"index()" or "rindex()", and those that do might not declare them in the +header file on which they're declared on your platform. + +Don't use "tvb_get_ptr()". If you must use it, keep in mind that the pointer +returned by a call to "tvb_get_ptr()" is not guaranteed to be aligned on any +particular byte boundary; this means that you cannot safely cast it to any +data type other than a pointer to "char", "unsigned char", "guint8", or other +one-byte data types. Casting a pointer returned by tvb_get_ptr() into any +multi-byte data type or structure may cause crashes on some platforms (even +if it does not crash on x86-based PCs). Even if such mis-aligned accesses +don't crash on your platform they will be slower than properly aligned +accesses would be. Furthermore, the data in a packet is not necessarily in +the byte order of the machine on which Wireshark is running. Use the tvbuff +routines to extract individual items from the packet, or, better yet, use +"proto_tree_add_item()" and let it extract the items for you. + +Don't use structures that overlay packet data, or into which you copy +packet data; the C programming language does not guarantee any +particular alignment of fields within a structure, and even the +extensions that try to guarantee that are compiler-specific and not +necessarily supported by all compilers used to build Wireshark. Using +bitfields in those structures is even worse; the order of bitfields +is not guaranteed. + +Don't use "ntohs()", "ntohl()", "htons()", or "htonl()"; the header +files required to define or declare them differ between platforms, and +you might be able to get away with not including the appropriate header +file on your platform but that might not work on other platforms. +Instead, use "g_ntohs()", "g_ntohl()", "g_htons()", and "g_htonl()"; +those are declared by <glib.h>, and you'll need to include that anyway, +as Wireshark header files that all dissectors must include use stuff from +<glib.h>. + +Don't fetch a little-endian value using "tvb_get_ntohs() or +"tvb_get_ntohl()" and then using "g_ntohs()", "g_htons()", "g_ntohl()", +or "g_htonl()" on the resulting value - the g_ routines in question +convert between network byte order (big-endian) and *host* byte order, +not *little-endian* byte order; not all machines on which Wireshark runs +are little-endian, even though PCs are. Fetch those values using +"tvb_get_letohs()" and "tvb_get_letohl()". + +Do not use "open()", "rename()", "mkdir()", "stat()", "unlink()", "remove()", +"fopen()", "freopen()" directly. Instead use "ws_open()", "ws_rename()", +"ws_mkdir()", "ws_stat()", "ws_unlink()", "ws_remove()", "ws_fopen()", +"ws_freopen()": these wrapper functions change the path and file name from +UTF-8 to UTF-16 on Windows allowing the functions to work correctly when the +path or file name contain non-ASCII characters. + +Also, use ws_read(), ws_write(), ws_lseek(), ws_dup(), ws_fstat(), and +ws_fdopen(), rather than read(), write(), lseek(), dup(), fstat(), and +fdopen() on descriptors returned by ws_open(). + +Those functions are declared in <wsutil/file_util.h>; include that +header in any code that uses any of those routines. + +When opening a file with "ws_fopen()", "ws_freopen()", or "ws_fdopen()", if +the file contains ASCII text, use "r", "w", "a", and so on as the open mode +- but if it contains binary data, use "rb", "wb", and so on. On +Windows, if a file is opened in a text mode, writing a byte with the +value of octal 12 (newline) to the file causes two bytes, one with the +value octal 15 (carriage return) and one with the value octal 12, to be +written to the file, and causes bytes with the value octal 15 to be +discarded when reading the file (to translate between C's UNIX-style +lines that end with newline and Windows' DEC-style lines that end with +carriage return/line feed). + +In addition, that also means that when opening or creating a binary +file, you must use "ws_open()" (with O_CREAT and possibly O_TRUNC if the +file is to be created if it doesn't exist), and OR in the O_BINARY flag, +even on UN*X - O_BINARY is defined by <wsutil/file_util.h> as 0 on UN*X. + +Do not include <unistd.h>, <fcntl.h>, or <io.h> to declare any of the +routines listed as replaced by routines in <wsutil/file_util.h>; +instead, just include <wsutil/file_util.h>. + +If you need the declarations of other functions defined by <unistd.h>, +don't include it without protecting it with + + #ifdef HAVE_UNISTD_H + + ... + + #endif + +Don't use forward declarations of static arrays without a specified size +in a fashion such as this: + + static const value_string foo_vals[]; + + ... + + static const value_string foo_vals[] = { + { 0, "Red" }, + { 1, "Green" }, + { 2, "Blue" }, + { 0, NULL } + }; + +as some compilers will reject the first of those statements. Instead, +initialize the array at the point at which it's first declared, so that +the size is known. + +For #define names and enum member names, prefix the names with a tag so +as to avoid collisions with other names - this might be more of an issue +on Windows, as it appears to #define names such as DELETE and +OPTIONAL. + +Don't use the "positional parameters" extension that many UNIX printf's +implement, e.g.: + + snprintf(add_string, 30, " - (%1$d) (0x%1$04x)", value); + +as not all UNIX printf's implement it, and Windows printf doesn't appear +to implement it. Use something like + + snprintf(add_string, 30, " - (%d) (0x%04x)", value, value); + +instead. + +Don't use + + case N ... M: + +as that's not supported by all compilers. + +Prefer the C99 output functions from <stdio.h> instead of their GLib +replacements (note that positional format parameters are not part of C99). +In the past we used to recommend using g_snprintf() and g_vsnprintf() +instead but since Visual Studio 2015 native C99 implementations are +available on all platforms we support. These are optimized better than +the gnulib (GLib) implementation and on hot codepaths that can be a +noticeable difference in execution speed. + +tmpnam() -> mkstemp() +tmpnam is insecure and should not be used any more. Wireshark brings its +own mkstemp implementation for use on platforms that lack mkstemp. +Note: mkstemp does not accept NULL as a parameter. + +Wireshark requires minimum versions of each of the libraries it uses, in +particular GLib 2.54.0 and Qt 5.12.0 or newer. If you require a mechanism +that is available only in a newer version of a library then use its +version detection macros, e.g. "#if GLIB_CHECK_VERSION(...)" and "#if +QT_VERSION_CHECK(...)" to conditionally compile code using that +mechanism. + +When different code must be used on UN*X and Win32, use a #if or #ifdef +that tests _WIN32, not WIN32. Try to write code portably whenever +possible, however; note that there are some routines in Wireshark with +platform-dependent implementations and platform-independent APIs, such +as the routines in epan/filesystem.c, allowing the code that calls it to +be written portably without #ifdefs. + +We support building on Windows using MinGW-w64 (experimental) so be mindful +of the difference between an #ifdef on _WIN32 and _MSC_VER. The first tests +if the platform is some version of Windows and also applies to MinGW. The +latter tests if the toolchain is Microsoft Visual Studio. Sometimes you need +one or the other, depending on whether the condition applies to all Windows +compilers or only Microsoft's compiler. Use #ifdef __MINGW32__ to test for +a MinGW toolchain, including MinGW-w64. The same concern applies to CMake +code. Depending on the particular situation you may need to use if(WIN32) or +if(MSVC) or if(MINGW). + +Wireshark uses Libgcrypt as general-purpose crypto library. Some Wireshark +specific extensions are defined in wsutil/wsgcrypt.h. You might want to +include that file instead. + +2. String handling + +Do not use functions such as strcat() or strcpy(). +A lot of work has been done to remove the existing calls to these functions and +we do not want any new callers of these functions. + +Instead use snprintf() since that function will if used correctly prevent +buffer overflows for large strings. + +Be sure that all pointers passed to %s specifiers in format strings are non- +NULL. Some implementations will automatically replace NULL pointers with the +string "(NULL)", but most will not. + +When using a buffer to create a string, do not use a buffer stored on the stack. +I.e. do not use a buffer declared as + + char buffer[1024]; + +instead allocate a buffer dynamically using the string-specific or plain wmem +routines (see README.wmem) such as + + wmem_strbuf_t *strbuf; + strbuf = wmem_strbuf_new(pinfo->pool, ""); + wmem_strbuf_append_printf(strbuf, ... + +or + + char *buffer=NULL; + ... + #define MAX_BUFFER 1024 + buffer=wmem_alloc(pinfo->pool, MAX_BUFFER); + buffer[0]='\0'; + ... + snprintf(buffer, MAX_BUFFER, ... + +This avoids the stack from being corrupted in case there is a bug in your code +that accidentally writes beyond the end of the buffer. + + +If you write a routine that will create and return a pointer to a filled in +string and if that buffer will not be further processed or appended to after +the routine returns (except being added to the proto tree), +do not preallocate the buffer to fill in and pass as a parameter instead +pass a pointer to a pointer to the function and return a pointer to a +wmem-allocated buffer that will be automatically freed. (see README.wmem) + +I.e. do not write code such as + static void + foo_to_str(char *string, ... ){ + <fill in string> + } + ... + char buffer[1024]; + ... + foo_to_str(buffer, ... + proto_tree_add_string(... buffer ... + +instead write the code as + static void + foo_to_str(char **buffer, ... + #define MAX_BUFFER x + *buffer=wmem_alloc(pinfo->pool, MAX_BUFFER); + <fill in *buffer> + } + ... + char *buffer; + ... + foo_to_str(&buffer, ... + proto_tree_add_string(... *buffer ... + +Use wmem_ allocated buffers. They are very fast and nice. These buffers are all +automatically free()d when the dissection of the current packet ends so you +don't have to worry about free()ing them explicitly in order to not leak memory. +Please read README.wmem. + +Source files can use UTF-8 encoding, but characters outside the ASCII +range should be used sparingly. It should be safe to use non-ASCII +characters in comments and strings, but some compilers (such as GCC +versions prior to 10) may not support extended identifiers very well. +There is also no guarantee that a developer's text editor will interpret +the characters the way you intend them to be interpreted. + +The majority of Wireshark encodes strings as UTF-8. The main exception +is the code that uses the Qt API, which uses UTF-16. Console output is +UTF-8, but as with the source code extended characters should be used +sparingly since some consoles (most notably Windows' cmd.exe) have +limited support for UTF-8. + +3. Robustness. + +Wireshark is not guaranteed to read only network traces that contain correctly- +formed packets. Wireshark is commonly used to track down networking +problems, and the problems might be due to a buggy protocol implementation +sending out bad packets. + +Therefore, code does not only have to be able to handle +correctly-formed packets without, for example, crashing or looping +infinitely, they also have to be able to handle *incorrectly*-formed +packets without crashing or looping infinitely. + +Here are some suggestions for making code more robust in the face +of incorrectly-formed packets: + +Do *NOT* use "ws_assert()" or "ws_assert_not_reached()" with input data in dissectors. +*NO* value in a packet's data should be considered "wrong" in the sense +that it's a problem with the dissector if found; if it cannot do +anything else with a particular value from a packet's data, the +dissector should put into the protocol tree an indication that the +value is invalid, and should return. The "expert" mechanism should be +used for that purpose. + +Use assertions to catch logic errors in your program. A failed assertion +indicates a bug in the code. Use ws_assert() instead of g_assert() to +test a logic condition. Note that ws_assert() can be removed at compile +time. Therefore assertions should not have any side-effects, +otherwise the program may behave inconsistently. + +Use ws_assert_not_reached() instead of g_assert_not_reached() for +unreachable error conditions. For example if (and only if) you know +'myvar' can only have the values 1 and 2 do: + switch(myvar) { + case 1: + (...) + break; + case 2: + (...) + break; + default: + ws_assert_not_reached(); + break; + } + +For dissectors use DISSECTOR_ASSERT() and DISSECTOR_ASSERT_NOT_REACHED() +instead, with the same caveats as above. + +You should continue to use g_assert_true(), g_assert_cmpstr(), etc for +"test code", such as unit testing. These assertions are always active. +See the GLib Testing API documentation for the details on each of those +functions. + +If there is a case where you are checking not for an invalid data item +in the packet, but for a bug in the dissector (for example, an +assumption being made at a particular point in the code about the +internal state of the dissector), use the DISSECTOR_ASSERT macro for +that purpose; this will put into the protocol tree an indication that +the dissector has a bug in it, and will not crash the application. + +If you are allocating a chunk of memory to contain data from a packet, +or to contain information derived from data in a packet, and the size of +the chunk of memory is derived from a size field in the packet, make +sure all the data is present in the packet before allocating the buffer. +Doing so means that: + + 1) Wireshark won't leak that chunk of memory if an attempt to + fetch data not present in the packet throws an exception. + +and + + 2) it won't crash trying to allocate an absurdly-large chunk of + memory if the size field has a bogus large value. + +If you're fetching into such a chunk of memory a sequence of bytes from +the buffer, and the sequence has a specified size, you can use +"tvb_memdup()", which will check whether the entire sequence is present +before allocating a buffer for it. + +Otherwise, you can check whether the data is present by using +"tvb_ensure_bytes_exist()" although this frequently is not needed: the +TVB-accessor routines can handle requests to read data beyond the end of +the TVB (by throwing an exception which will either mark the frame as +truncated--not all the data was captured--or as malformed). + +If you're fetching a string only to add it to the tree, you should +generally be using "proto_tree_add_item()" instead. If you also need +the string, you can use the variant "proto_tree_add_item_ret_string()" +or "proto_tree_add_item_ret_string_and_length()" forms. + +If you must fetch it from the tvbuff, and the string has a specified +size and known encoding, you can use "tvb_get_string_enc()" for most +encodings, which will check whether the entire string is present before +allocating a buffer for the string, will put a trailing '\0' at the end +of the buffer, and will also check for invalid characters in the supplied +encoding and convert the string to UTF-8. The "tvb_get_*_string()" set of +functions is available as well, and must be used for some encodings, +primarily non byte aligned ones. If the string has a known encoding and +is null terminated, the "stringz" variants can be used. (Note that these +functions are called with memory allocators, and if called with a NULL +allocator you are required to free the string when finished with it.) + +If the string has a known encoding but requires token parsing or other +text manipulation to determine the offset and size, do so by calling +tvb_*() functions on the tvbuff that perform bounds checking if possible. +Only extract the bytes into a newly allocated buffer to extract a string +if absolutely necessary. If you do so, then you *must* ensure that the +string is valid UTF-8 when passing it to a libwireshark API function +such as proto_tree_add_string(). (Cf. 7.5: Unicode and string encoding +best practices.) + +Conversion to UTF-8 can produce a string with a length longer than +that of the string in the original packet data; this includes strings +encoded in ASCII or UTF-8 itself if they have invalid character sequences +that are replaced with the 3 byte UTF-8 REPLACEMENT CHARACTER. Truncating +a valid UTF-8 string to an arbitrary number of bytes does not guarantee +that the result is a valid UTF-8 string, because a multibyte character +might span the boundary. + +Note also that you should only fetch string data into a fixed-length +buffer if the code ensures that no more bytes than will fit into the +buffer are fetched ("the protocol ensures" isn't good enough, as +protocol specifications can't ensure only packets that conform to the +specification will be transmitted or that only packets for the protocol +in question will be interpreted as packets for that protocol by +Wireshark). + +If you have gotten a pointer using "tvb_get_ptr()" (which you should not +have: you should seriously consider a better alternative to this function), +you must make sure that you do not refer to any data past the length passed +as the last argument to "tvb_get_ptr()"; while the various "tvb_get" +routines perform bounds checking and throw an exception if you refer to data +not available in the tvbuff, direct references through a pointer gotten from +"tvb_get_ptr()" do not do any bounds checking. + +If you have a loop that dissects a sequence of items, each of which has +a length field, with the offset in the tvbuff advanced by the length of +the item, then, if the length field is the total length of the item, and +thus can be zero, you *MUST* check for a zero-length item and abort the +loop if you see one. Otherwise, a zero-length item could cause the +dissector to loop infinitely. You should also check that the offset, +after having the length added to it, is greater than the offset before +the length was added to it, if the length field is greater than 24 bits +long, so that, if the length value is *very* large and adding it to the +offset causes an overflow, that overflow is detected. + +If you have a + + for (i = {start}; i < {end}; i++) + +loop, make sure that the type of the loop index variable is large enough +to hold the maximum {end} value plus 1; otherwise, the loop index +variable can overflow before it ever reaches its maximum value. In +particular, be very careful when using int8_t, uint8_t, int16_t, or uint16_t +(or the deprecated Glib synonyms gint8, guint8, gint16, or guint16) +variables as loop indices; you almost always want to use an "int"/"gint" +or "unsigned"/"guint" as the loop index rather than a shorter type. + +If you are fetching a length field from the buffer, corresponding to the +length of a portion of the packet, and subtracting from that length a +value corresponding to the length of, for example, a header in the +packet portion in question, *ALWAYS* check that the value of the length +field is greater than or equal to the length you're subtracting from it, +and report an error in the packet and stop dissecting the packet if it's +less than the length you're subtracting from it. Otherwise, the +resulting length value will be negative, which will either cause errors +in the dissector or routines called by the dissector, or, if the value +is interpreted as an unsigned integer, will cause the value to be +interpreted as a very large positive value. + +Any tvbuff offset that is added to as processing is done on a packet +should be stored in a 32-bit variable, such as an "int"; if you store it +in an 8-bit or 16-bit variable, you run the risk of the variable +overflowing. + +sprintf() -> snprintf() +Prevent yourself from using the sprintf() function, as it does not test the +length of the given output buffer and might be writing into unintended memory +areas. This function is one of the main causes of security problems like buffer +exploits and many other bugs that are very hard to find. It's much better to +use the snprintf() function declared by <stdio.h> instead. + +You should test your dissector against incorrectly-formed packets. This +can be done using the randpkt and editcap utilities that come with the +Wireshark distribution. Testing using randpkt can be done by generating +output at the same layer as your protocol, and forcing Wireshark/TShark +to decode it as your protocol, e.g. if your protocol sits on top of UDP: + + randpkt -c 50000 -t dns randpkt.pcap + tshark -nVr randpkt.pcap -d udp.port==53,<myproto> + +Testing using editcap can be done using preexisting capture files and the +"-E" flag, which introduces errors in a capture file. E.g.: + + editcap -E 0.03 infile.pcap outfile.pcap + tshark -nVr outfile.pcap + +tools/fuzz-test.sh is available to help automate these tests. + +4. Name convention. + +Wireshark uses the underscore_convention rather than the InterCapConvention for +function names, so new code should probably use underscores rather than +intercaps for functions and variable names. This is especially important if you +are writing code that will be called from outside your code. We are just +trying to keep things consistent for other developers. + +C symbols exported from libraries shipped with Wireshark should start with a +prefix that helps avoiding name collision with public symbols from other shared +libraries. The current suggested prefixes for newly added symbols are +ws_, wslua_, wmem_ and wtap_. + +5. White space convention. + +Most of the C and C++ files in Wireshark use 4-space or 2-space indentation. +When creating new files you are you are strongly encouraged to use 4-space +indentation for source code in order to ensure consistency between files. + +Please avoid using tab expansions different from 8 column widths, as not all +text editors in use by the developers support this. For a detailed discussion +of tabs, spaces, and indentation, see + + http://www.jwz.org/doc/tabs-vs-spaces.html + +We use EditorConfig (http://editorconfig.org) files to provide formatting +hints. Most editors and IDEs support EditorConfig, either directly or via +a plugin. If yours requires a plugin we encourage you to install it. Our +default EditorConfig indentation style for C and C++ files is 4 spaces. + +Many files also have a short comment (modelines) on the indentation logic at +the end of the file. This was required in the past but has been superseded by +EditorConfig. See + + https://www.wireshark.org/tools/modelines.html + +for more information. + +Please do not leave trailing whitespace (spaces/tabs) on lines. + +Quite a bit of our source code has varying indentation styles. When editing an +existing file, try following the existing indentation logic. If you wish to +convert a file to 4 space indentation, please do so in its own commit and be +sure to remove its .editorconfig entry so that the default setting takes +effect. + +6. Compiler warnings + +You should write code that is free of compiler warnings. Such warnings will +often indicate questionable code and sometimes even real bugs, so it's best +to avoid warnings at all. + +The compiler flags in the Makefiles are set to "treat warnings as errors", +so your code won't even compile when warnings occur. + +7. General observations about architecture + +7.1 The global header "wireshark.h" + +You should include the global header <wireshark.h> in your code. However +there are some things to keep in mind when using it and especially +if you are considering modifying it. + +** wireshark.h needs to be minimal: for efficiency reasons, to reduce the +error surface and because every time this header changes everything must be +rebuilt. Consider carefully if another header/module should be included +globally with every project file and exported as public header. + +** No configuration: configuration is specific to the build environment +and target machine. wireshark.h must not depend on that. + +** Only wireshark system headers allowed: plugins use this header and +cannot depend on any header (even indirectly) that is not installed on the +target system. + +** Only global definitions allowed: for example it is acceptable to include +'wsutil' headers in wireshark.h because every component of Wireshark is allowed +to depend on wsutil. wiretap is not acceptable because we cannot introduce +dependencies on wiretap globally (and wireshark.h must be usable everywhere). + +7.2 Best practices using headers + +C files can be categorized in three types: source files, private headers and +public headers. + +A module "foobar" can have only a private header, only a public header, or +both. If it's only one it is named "foobar.h" in both cases. If it is both they +are named "foobar-int.h" and "foobar.h" respectively. + +In general the order of #include's for a C module source files (foobar.c), +assuming foobar implements any kind of interface should be: + + #include "config.h" + #define WS_LOG_DOMAIN "mydomain" + #include "foobar-int.h" + + followed by <system headers> + followed by <wireshark public headers> + followed by <wireshark private headers> + +For header files (private and public) config.h must NOT be included. A public +header file (foobar.h) looks like this: + + #ifndef __FOOBAR_H__ + #define __FOOBAR_H__ + #include <wireshark.h> + followed by <system headers> + followed by <wireshark public headers> + + #ifdef __cplusplus + extern "C" { + #endif + (declarations) + #ifdef __cplusplus + } + #endif + #endif /* FOOBAR_H */ + +A private header (foobar-int.h) is the public header plus the declarations +with private scope: + + #ifndef __FOOBAR_INT_H__ + #define __FOOBAR_INT_H__ + #include "foobar.h" + followed by <system headers> + followed by <wireshark public headers> + followed by <wireshark private headers> + (etc.) + +Again if there are only public or private declarations the name foobar-int.h +is not used. The macro symbol WS_LOG_DOMAIN can be defined in source files or +private headers as long as it comes before wireshark.h. + +7.3 Wireshark internal and external API policy + +Wireshark has several APIs. We need to distinguish between internal +Wireshark library APIs and external Wireshark APIs. Wireshark the project is +composed of many different programs and these executable binaries use a number +of internal libraries to share code efficiently. These internal shared +libraries need to be installed on the system to run the programs (wireshark, +tshark, etc). + +A library's public API includes the symbols exported by the DSO (wsutil, +libwireshark, etc). The internal API is made available in the shared libraries +and exists to support the goals of the project. It is public from the point +of view of Wireshark programs (client users of the internal API). The +external API exists to support plugins (client users of the external API) +and is a loosely defined subset of the internal API plus any infrastructure +required to support a plugin system. Note that these two uses of shared +libraries coexist with a lot of overlap, but are nevertheless distinct. + +The internal (public) API is not considered to be stable and will regularly +change as a normal part of development to support new features, remove cruft, +and whatever else is necessary to make the project sustainable and ease the +burden on developers. There is less freedom to change something that could +break a lot of plugins but this is also acceptable (with cause). + +The plugin ABI policy is to be compatible only between micro releases (also +called patch releases). That means we try to make it unnecessary to recompile +plugins with each micro release (on a best-effort basis). For major.minor +releases it is explicitly required to recompile plugins. There is no stable +ABI contract of any kind in that case. + +Keep in mind that APIs can exist in different scopes and levels of abstraction. +Don't get stuck thinking the words public/private have a very specific +meaning, like being decorated or not with WS_DLL_PUBLIC, although that is a +big part of it usually. + +Also the Wireshark developers have historically tried to keep the Lua API +very stable and provide strong backward-compatibility guarantees. Under this +policy moving from Lua 5.2 is unlikely to happen in the foreseeable future. + +7.4 libwireshark is not a single monolithic entity + +One day we might conceivably wish to load dissectors on demand and do other +more sophisticated kinds of unit test. Plus other scenarios not immediately +obvious. For this to be possible it is important that the code in epan/ does +not depend on code in epan/dissectors, i.e it is possible to compile epan +without linking with dissector code. It helps to view dissectors as clients +of an API provided by epan (libwireshark being constituted by two distinct +components "epan" and "dissectors" bundled together, plus other bits and +pieces). The reverse is not* true; epan should not be the client of an API +provided by dissectors. + +The main way this separation of concerns is achieved is by using runtime +registration interfaces in epan for dissectors, preferences, etc. that are +dynamic and do not have any dissector routines hard coded. Naturally this +is also an essential component of a plugin system (libwireshark has plugins +for taps, dissectors and an experimental interface to augment dissection with +new extension languages). + +7.5 Unicode and string encoding best practices + +Wireshark strings are always encoded in UTF-8 internally, regardless of the +platform where it is running. The C datatype used is "pointer to char" and this +is assumed to point to a valid UTF-8 string. Sometimes older code uses char to +point to opaque byte strings but this archaic usage should be avoided. A better +data type for that is uint8_t. + +Every untrusted string needs to be validated for correct and error-free UTF-8 +encoding, or converted from the source encoding to UTF-8. This should be done +at the periphery of the code. This means converting input during dissection or +when reading input generally. To reiterate: all the Wireshark APIs expect to +receive valid UTF-8 strings. These include proto_tree_add_string(), +proto_item_append_text() and col_append_fstr() just to name a few. + +If a dissector uses standard API functions to handle strings, such as +proto_tree_add_item() with an FT_STRING header field type, the API will +transparently handle the conversion from the source encoding to UTF-8 and +nothing else needs to be done to ensure valid string input. + +If your dissector does text manipulation, token parsing and such and generally +extracts text strings from the TVBuff or tries to do line oriented input from +TVBuffs it *must* make sure it passes only valid UTF-8 to libwireshark APIs. +This should be done using tvb_get_string_enc() to extract a string from a TVbuff +or get_utf_8_string() to validate a string after it has been constructed. + +The Qt API uses UTF-16 for its QString class; when converting between a +QString and a pointer to char, functions that convert to or from UTF-8 +encoded pointers to char (or QByteArrays) such as toUtf8() should be used, +not toLocal8Bit() or toLatin1(). + +8. Miscellaneous notes + +Each commit in your branch corresponds to a different VCSVERSION string +automatically defined in the header 'vcs_version.h' during the build. If you happen +to find it convenient to disable this feature it can be done using: + + touch .git/wireshark-disable-versioning + +i.e., the file 'wireshark-disable-versioning' must exist in the git repo dir. + +/* + * Editor modelines - https://www.wireshark.org/tools/modelines.html + * + * Local variables: + * c-basic-offset: 4 + * tab-width: 8 + * indent-tabs-mode: nil + * End: + * + * vi: set shiftwidth=4 tabstop=8 expandtab: + * :indentSize=4:tabSize=8:noTabs=true: + */ diff --git a/doc/README.display_filter b/doc/README.display_filter new file mode 100644 index 0000000..ab4d74d --- /dev/null +++ b/doc/README.display_filter @@ -0,0 +1,586 @@ +(This is a consolidation of documentation written by stig, sahlberg, and gram) + +What is the display filter system? +================================== +The display filter system allows the user to select packets by testing +for values in the proto_tree that Wireshark constructs for that packet. +Every proto_item in the proto_tree has an 'abbrev' field +and a 'type' field, which tells the display filter engine the name +of the field and its type (what values it can hold). + +For example, this is the definition of the ip.proto field from packet-ip.c: + +{ &hf_ip_proto, + { "Protocol", "ip.proto", FT_UINT8, BASE_DEC | BASE_EXT_STRING, + &ipproto_val_ext, 0x0, NULL, HFILL }}, + +This definition says that "ip.proto" is the display-filter name for +this field, and that its field-type is FT_UINT8. + +The display filter system has 3 major parts to it: + + 1. A type system (field types, or "ftypes") + 2. A parser, to convert a user's query to an internal representation + 3. An engine that uses the internal representation to select packets. + + +code: +epan/dfilter/* - the display filter engine, including + scanner, parser, syntax-tree semantics checker, DFVM bytecode + generator, and DFVM engine. +epan/ftypes/* - the definitions of the various FT_* field types. +epan/proto.c - proto_tree-related routines + + +The field type system +===================== +The field type system is stored in epan/ftypes. + +The proto_tree system #includes ftypes.h, which gives it the ftenum +definition, which is the enum of all possible ftypes: + +/* field types */ +enum ftenum { + FT_NONE, /* used for text labels with no value */ + FT_PROTOCOL, + FT_BOOLEAN, + FT_CHAR, /* 1-octet character as 0-255 */ + FT_UINT8, + FT_UINT16, + FT_UINT24, /* really a UINT32, but displayed as 6 hex-digits if FD_HEX*/ + FT_UINT32, + FT_UINT40, /* really a UINT64, but displayed as 10 hex-digits if FD_HEX*/ + FT_UINT48, /* really a UINT64, but displayed as 12 hex-digits if FD_HEX*/ + FT_UINT56, /* really a UINT64, but displayed as 14 hex-digits if FD_HEX*/ + FT_UINT64, + etc., etc. +} + +It also provides the definition of fvalue_t, the struct that holds the *value* +that corresponds to the type. Each proto_item (proto_node) holds an fvalue_t +due to having a field_info struct (defined in proto.h). + +The fvalue_t is mostly just a gigantic union of possible C-language types +(as opposed to FT_* types): + +typedef struct _fvalue_t { + ftype_t *ftype; + union { + /* Put a few basic types in here */ + uint32_t uinteger; + int32_t sinteger; + uint64_t uinteger64; + int64_t sinteger64; + double floating; + wmem_strbuf_t *strbuf; + GByteArray *bytes; + ipv4_addr_and_mask ipv4; + ipv6_addr_and_prefix ipv6; + e_guid_t guid; + nstime_t time; + protocol_value_t protocol; + uint16_t sfloat_ieee_11073; + uint32_t float_ieee_11073; + } value; +} fvalue_t; + + +Defining a field type +--------------------- +The ftype system itself is designed to be modular, so that new field types +can be added when necessary. + +Each field type must implement an ftype_t structure, defined in +ftypes-int.h. This is the way a field type is registered with the ftype engine. + +If you take a look at ftype-integer.c, you will see that it provides +an ftype_register_integers() function, that fills in many such ftype_t +structs. It creates one for each integer type: FT_UINT8, FT_UINT16, +FT_UINT32, etc. + +The ftype_t struct defines the things needed for the ftype: + + * its ftenum value + * a string representation of the FT name ("FT_UINT8") + * how much data it consumes in the packet + * how to store that value in an fvalue_t: new(), free(), + various value-related functions + * how to compare that value against another + * how to slice that value (strings and byte ranges can be sliced) + +Using an fvalue_t +----------------- +Once the value of a field is stored in an fvalue_t (stored in +each proto_item via field_info), it's easy to use those values, +thanks to the various fvalue_*() functions defined in ftypes.h. + +Functions like fvalue_get(), fvalue_eq(), etc., are all generic +interfaces to get information about the field's value. They work +on any field type because of the ftype_t struct, which is the lookup +table that the field-type engine uses to work with any field type. + +The display filter parser +========================= +The display filter parser (along with the comparison engine) +is stored in epan/dfilter. + +The scanner/parser pair read the string representing the display filter +and convert it into a very simple syntax tree. The syntax tree is very +simple in that it is possible that many of the nodes contain unparsed +chunks of text from the display filter. + +There are four phases to parsing a user's request: + + 1. Scanning the string for dfilter syntax + 2. Parsing the keywords according to the dfilter grammar, into a + syntax tree + 3. Doing a semantic check of the nodes in that syntax tree + 4. Converting the syntax tree into a series of DFVM byte codes + +The dfilter_compile() function, in epan/dfilter/dfilter.c, +runs these 4 phases. The end result is a dfwork_t object (dfw), that +can be passed to dfilter_apply() to actually run the display filter +against a set of proto_trees. + + +Scanning the display filter string +---------------------------------- +epan/dfilter/scanner.l is the lex scanner for finding keywords +in the user's display filter string. + +Its operation is simple. It finds the special function and comparison +operators ("==", "!=", "eq", "ne", etc.), it finds slice operations +( "[0:1]" ), quoted strings, IP addresses, numbers, and any other "special" +keywords or string types. + +Anything it doesn't know how to handle is passed to the grammar parser +as an unparsed string (TOKEN_UNPARSED). This includes field names. The +scanner does not interpret any protocol field names at all. + +The scanner has to return a token type (TOKEN_*, and in many cases, +a value. The value will be an stnode_t struct, which is a syntax +tree node object. Since the final storage of the parse will +be in a syntax tree, it is convenient for the scanner to fill in +syntax tree nodes with values when it can. + +The stnode_t definition is in epan/dfilter/syntax-tree.h + + +Parsing the keywords according to the dfilter grammar +----------------------------------------------------- +The grammar parser is implemented with the 'lemon' tool, +rather than the traditional yacc or bison grammar parser, +as lemon grammars were found to be easier to work with. The +lemon parser specification (epan/dfilter/grammar.lemon) is +much easier to read than its bison counterpart would be, +thanks to lemon's feature of being able to name fields, rather +then using numbers ($1, $2, etc.) + +The lemon tool is located in tools/lemon in the Wireshark +distribution. + +An on-line introduction to lemon is available at: + +http://www.sqlite.org/src/doc/trunk/doc/lemon.html + +The grammar specifies which type of constructs are possible +within the dfilter language ("dfilter-lang") + +An "expression" in dfilter-lang can be a relational test or a logical test. + +A relational test compares a value against another, which is usually +a field (or a slice of a field) against some static value, like: + + ip.proto == 1 + eth.dst != ff:ff:ff:ff:ff:ff + +A logical test combines other expressions with "and", "or", and "not". + +At the end of the grammatical parsing, the dfw object will +have a valid syntax tree, pointed at by dfw->st_root. + +If there is an error in the syntax, the parser will call dfilter_fail() +with an appropriate error message, which the UI will need to report +to the user. + +The syntax tree system +---------------------- +The syntax tree is created as a result of running the lemon-based +grammar parser on the scanned tokens. The syntax tree code +is in epan/dfilter/syntax-tree* and epan/dfilter/sttype-*. It too +uses a set of code modules that implement different syntax node types, +similar to how the field-type system registers a set of ftypes +with a central engine. + +Each node (stnode_t) in the syntax tree has a type (sttype). +These sttypes are very much related to ftypes (field types), but there +is not a one-to-one correspondence. The syntax tree nodes are slightly +higher-level abstractions. The root node of the syntax tree is the main +test or comparison being done. + +Semantic Check +-------------- +After the parsing is done and a syntax tree is available, the +code in semcheck.c does a semantic check of what is in the syntax +tree. + +The semantics of the simple syntax tree are checked to make sure that +the fields that are being compared are being compared to appropriate +values. For example, if a field is an integer, it can't be compared to +a string, unless a value_string has been defined for that field. + +During the process of checking the semantics, the simple syntax tree is +fleshed out and no longer contains nodes with unparsed information. The +syntax tree is no longer in its simple form, but in its complete form. + +For example, if the dfilter is slicing a field and comparing +against a set of bytes, semcheck.c has to check that the field +in question can indeed be sliced. + +Or, can a field be compared against a certain type of value (string, +integer, float, IPv4 address, etc.) + +The semcheck code also makes adjustments to the syntax tree +when it needs to. The parser sometimes stores raw, unparsed strings +in the syntax tree, and semcheck has to convert them to +certain types. For example, the display filter may contain +a value_string string (the "enum" type that protocols can use +to define the possible textual descriptions of numeric fields), and +semcheck will convert that value_string string into the correct +integer value. + +Truth be told, the semcheck.c code is a bit disorganized, and could +be re-designed & re-written. + +DFVM Byte Codes +--------------- +The syntax tree is analyzed to create a sequence of bytecodes in the +"DFVM" language. "DFVM" stands for Display Filter Virtual Machine. The +DFVM is similar in spirit, but not in definition, to the BPF VM that +libpcap uses to analyze packets. + +A virtual bytecode is created and used so that the actual process of +filtering packets will be fast. That is, it should be faster to process +a list of VM bytecodes than to attempt to filter packets directly from +the syntax tree. (heh... no measurement has been made to support this +supposition) + +The DFVM opcodes are defined in epan/dfilter/dfvm.h (dfvm_opcode_t). +Similar to how the BPF opcode system works in libpcap, there is a +limited set of opcodes. They operate by loading values from the +proto_tree into registers, loading pre-defined values into +registers, and comparing them. The opcodes are checked in sequence, and +there are only 2 branching opcodes: IF_TRUE_GOTO and IF_FALSE_GOTO. +Both of these can only branch forwards, and never backwards. In this way +sets of DFVM instructions will never get into an infinite loop. + +The epan/dfilter/gencode.c code converts the syntax tree +into a set of dfvm instructions. + +The constants that are in the DFVM instructions (the constant +values that the user is checking against) are pre-loaded +into registers via the dfvm_init_const() call, and stored +in the dfilter_t structure for when the display filter is +actually applied. + + +DFVM Engine +=========== +Once the DFVM bytecode has been produced, it's a simple matter of +running the DFVM engine against the proto_tree from the packet +dissection, using the DFVM bytecodes as instructions. If the DFVM +bytecode is known before packet dissection occurs, the +proto_tree-related code can be "primed" to store away pointers to +field_info structures that are interesting to the display filter. This +makes lookup of those field_info structures during the filtering process +faster. + +The dfilter_apply() function runs a single pre-compiled +display filter against a single proto_tree function, and returns +true or false, meaning that the filter matched or not. + +That function calls dfvm_apply(), which runs across the DFVM +instructions, loading protocol field values into DFVM registers +and doing the comparisons. + +There is a top-level Makefile target called 'dftest' which +builds a 'dftest' executable that will print out the DFVM +bytecode for any display filter given on the command-line. +To build it, run: + +$ make dftest + +To use it, give it the display filter on the command-line: + +$ ./dftest 'ip.addr == 127.0.0.1' +Filter: ip.addr == 127.0.0.1 + +Constants: +00000 PUT_FVALUE 127.0.0.1 <FT_IPv4> -> reg#1 + +Instructions: +00000 READ_TREE ip.addr -> reg#0 +00001 IF-FALSE-GOTO 3 +00002 ANY_EQ reg#0 == reg#1 +00003 RETURN + + +The output shows the original display filter, then the opcodes +that put constant values into registers. The registers are +numbered, and are shown in the output as "reg#n", where 'n' is the +identifying number. + +Then the instructions are shown. These are the instructions +which are run for each proto_tree. + +This is what happens in this example: + +00000 READ_TREE ip.addr -> reg#0 + +Any ip.addr fields in the proto_tree are loaded into register 0. Yes, +multiple values can be loaded into a single register. As a result +of this READ_TREE, the accumulator will hold true or false, indicating +if any field's value was loaded, or not. + +00001 IF-FALSE-GOTO 3 + +If the load failed because there were no ip.addr fields +in the proto_tree, then we jump to instruction 3. + +00002 ANY_EQ reg#0 == reg#1 + +This checks to see if any of the fields in register 1 +(which has the pre-loaded constant value of 127.0.0.1) are equal +to any of the fields in register 0 (which are all of the ip.addr +fields in the proto tree). The resulting value in the +accumulator will be true if any of the fields match, or false +if none match. + +00003 RETURN + +This returns the accumulator's value, either true or false. + +In addition to dftest, there is also a unit-test script for the +display filter engine - test/suite_dfilter/dfiltertest.py. +It makes use of tshark to run specific display filters against +specific captures in test/captures. See the "Wireshark Tests" chapter +in the Wireshark Developer’s Guide. + + + +Display Filter Functions +======================== +You define a display filter function by adding an entry to +the df_functions table in epan/dfilter/dfunctions.c. The record struct +is defined in dfunctions.h, and shown here: + +typedef struct { + char *name; + DFFuncType function; + ftenum_t retval_ftype; + unsigned min_nargs; + unsigned max_nargs; + DFSemCheckType semcheck_param_function; +} df_func_def_t; + +name - the name of the function; this is how the user will call your + function in the display filter language + +function - this is the run-time processing of your function. + +retval_ftype - what type of FT_* type does your function return? + +min_nargs - minimum number of arguments your function accepts +max_nargs - maximum number of arguments your function accepts + +semcheck_param_function - called during the semantic check of the + display filter string. + +DFFuncType function +------------------- +typedef bool (*DFFuncType)(GList *arg1list, GList *arg2list, GList **retval); + +The return value of your function is a bool; true if processing went fine, +or false if there was some sort of exception. + +For now, display filter functions can accept a maximum of 2 arguments. +The "arg1list" parameter is the GList for the first argument. The +'arg2list" parameter is the GList for the second argument. All arguments +to display filter functions are lists. This is because in the display +filter language a protocol field may have multiple instances. For example, +a field like "ip.addr" will exist more than once in a single frame. So +when the user invokes this display filter: + + somefunc(ip.addr) == true + +even though "ip.addr" is a single argument, the "somefunc" function will +receive a GList of *all* the values of "ip.addr" in the frame. + +Similarly, the return value of the function needs to be a GList, since all +values in the display filter language are lists. The GList** retval argument +is passed to your function so you can set the pointer to your return value. + +DFSemCheckType +-------------- +typedef void (*DFSemCheckType)(dfwork_t *dfw, int param_num, stnode_t *st_node); + +For each parameter in the syntax tree, this function will be called. +"param_num" will indicate the number of the parameter, starting with 0. +The "stnode_t" is the syntax-tree node representing that parameter. +If everything is okay with the value of that stnode_t, your function +does nothing --- it merely returns. If something is wrong, however, +it should call dfilter_fail(dfw,...) and THROW a TypeError exception. + + +Example: add an 'in' display filter operation +============================================= + +This example has been discussed on ethereal-dev in April 2004. +[Ethereal-dev] Need for an 'in' dfilter operator? +(https://www.wireshark.org/lists/ethereal-dev/200404/msg00372.html) +It illustrates how a more complex operation can be added to the display filter language. + +Question: + + If I want to add an 'in' display filter operation, I need to define + several things. This can happen in different ways. For instance, + every value from the "in" value collection will result in a test. + There are 2 options here, either a test for a single value: + + (x in {a b c}) + + or a test for a value in a given range: + + (x in {a ... z}) + + or even a combination of both. The former example can be reduced to: + + ((x == a) or (x == b) or (x == c)) + + while the latter can be reduced to + + ((x >= MIN(a, z)) and (x <= MAX(a, z))) + + I understand that I can replace "x in {" with the following steps: + first store x in the "in" test buffer, then add "(" to the display + filter expression internally. + + Similarly I can replace the closing brace "}" with the following + steps: release x from the "in" test buffer and then add ")" + to the display filter expression internally. + + How could I do this? + +Answer: + + This could be done in grammar.lemon. The grammar would produce + syntax tree nodes, combining them with "or", when it is given + tokens that represent the "in" syntax. + + It could also be done later in the process, maybe in + semcheck.c. But if you can do it earlier, in grammar.lemon, + then you shouldn't have to worry about modifying anything in + semcheck.c, as the syntax tree that is passed to semcheck.c + won't contain any new type of operators... just lots of nodes + combined with "or". + +How to add an operator FOO to the display filter language? +========================================================== + +Go to wireshark/epan/dfilter/ + +Edit grammar.lemon and add the operator. Add the operator FOO and the +test logic (defining TEST_OP_FOO). + +Edit scanner.l and add the operator name(s) hence defining +TOKEN_TEST_FOO. Also update the simple() or add the new operand's code. + +Edit sttype-test.h and add the TEST_OP_FOO to the list of test operations. + +Edit sttype-test.c and add TEST_OP_FOO to the num_operands() method. + +Edit gencode.c, add TEST_OP_FOO in the gen_test() method by defining +ANY_FOO. + +Edit dfvm.h and add ANY_FOO to the enum dfvm_opcode_t structure. + +Edit dfvm.c and add ANY_FOO to dfvm_dump() (for the dftest display filter +test binary), to dfvm_apply() hence defining the methods fvalue_foo(). + +Edit semcheck.c and look at the check_relation_XXX() methods if they +still apply to the foo operator; if not, amend the code. Start from the +check_test() method to discover the logic. + +Go to wireshark/epan/ftypes/ + +Edit ftypes.h and declare the fvalue_foo(), ftype_can_foo() and +fvalue_foo() methods. Add the cmp_foo() method to the struct _ftype_t. + +This is the first time that a make in wireshark/epan/dfilter/ can +succeed. If it fails, then some code in the previously edited files must +be corrected. + +Edit ftypes.c and define the fvalue_foo() method with its associated +logic. Define also the ftype_can_foo() and fvalue_foo() methods. + +Edit all ftype-*.c files and add the required fvalue_foo() methods. + +This is the point where you should be able to compile without errors in +wireshark/epan/ftypes/. If not, first fix the errors. + +Go to wireshark/epan/ and run make. If this one succeeds, then we're +almost done as no errors should occur here. + +Go to wireshark/ and run make. One thing to do is make dftest and see +if you can construct valid display filters with your new operator. Or +you may want to move directly to the generation of Wireshark. + +Also look at ui/qt/display_filter_expression_dialog.cpp and the display +filter expression generator. + +How to add a new test to the test suite +======================================= + +All display filter tests are located in test/suite_dfilter. +You can add a test to an existing file or create a new file. + +Each new test class must define "trace_file", which names +a capture file in "test/captures". All the tests +run in that class will use that one capture file. + +There are 2 fixtures you can use for testing: + +checkDFilterCount(dfilter, expected_count) + + This will run the display filter through tshark, on the + file named by "trace_file", and assert that the + number of resulting packets equals "expected_count". This + also asserts that tshark does not fail; success with zero + matches is not the same as failure to compile the display + filter string. + +checkDFilterFail(dfilter, error) + + This will run dftest with the display filter, and check + that it fails with a given error message. This is useful + when expecting display filter syntax errors to be caught. + +To execute tests: + +# Run all dfilter tests +$ test/test.py suite_dfilter + +# Run all tests from group_tvb.py: +$ test/test.py suite_dfilter.group_tvb + +# For faster, parallel tests, install the "pytest-xdist" first +# (for example, using "pip install pytest-xdist"), then: +$ pytest -nauto test -k suite_dfilter + +# Run all tests from group_tvb.py, in parallel: +$ pytest -nauto test -k case_tvb + +# Run a single test from group_tvb.py, case_tvb.test_slice_4: +$ pytest test -k "case_tvb and test_slice_4" + +See also https://www.wireshark.org/docs/wsdg_html_chunked/ChapterTests.html diff --git a/doc/README.dissector b/doc/README.dissector new file mode 100644 index 0000000..464bba4 --- /dev/null +++ b/doc/README.dissector @@ -0,0 +1,3723 @@ +This file is a HOWTO for Wireshark developers interested in writing or working +on Wireshark protocol dissectors. It describes expected code patterns and the +use of some of the important functions and variables. + +This file is compiled to give in depth information on Wireshark. +It is by no means all inclusive and complete. Please feel free to discuss on +the developer mailing list or upload merge requests to gitlab. +If you haven't read README.developer, read that first! + +0. Prerequisites. + +Before starting to develop a new dissector, a "running" Wireshark build +environment is required - there's no such thing as a standalone "dissector +build toolkit". + +How to setup such an environment is platform dependent; detailed +information about these steps can be found in the "Developer's Guide" +(available from: https://www.wireshark.org) and in the INSTALL and +README.md files of the sources root dir. + +0.1. Dissector related README files. + +You'll find additional dissector related information in the following README +files: + +- doc/README.heuristic - what are heuristic dissectors and how to write them +- doc/README.plugins - how to "pluginize" a dissector +- doc/README.request_response_tracking - how to track req./resp. times and such +- doc/README.wmem - how to obtain "memory leak free" memory + +0.2 Contributors + +James Coe <jammer[AT]cin.net> +Gilbert Ramirez <gram[AT]alumni.rice.edu> +Jeff Foster <jfoste[AT]woodward.com> +Olivier Abad <oabad[AT]cybercable.fr> +Laurent Deniel <laurent.deniel[AT]free.fr> +Gerald Combs <gerald[AT]wireshark.org> +Guy Harris <guy[AT]alum.mit.edu> +Ulf Lamping <ulf.lamping[AT]web.de> +Barbu Paul - Gheorghe <barbu.paul.gheorghe[AT]gmail.com> + +1. Setting up your protocol dissector code. + +This section provides skeleton code for a protocol dissector. It also explains +the basic functions needed to enter values in the traffic summary columns, +add to the protocol tree, and work with registered header fields. + +1.1 Skeleton code. + +Wireshark requires certain things when setting up a protocol dissector. +We provide basic skeleton code for a dissector that you can copy to a new file +and fill in. Your dissector should follow the naming convention of "packet-" +followed by the abbreviated name for the protocol. It is recommended that where +possible you keep to the IANA abbreviated name for the protocol, if there is +one, or a commonly-used abbreviation for the protocol, if any. + +The skeleton code lives in the file "packet-PROTOABBREV.c" in the same source +directory as this README. + +If instead of using the skeleton you base your dissector on an existing real +dissector, please put a little note in the copyright header indicating which +dissector you started with. + +Usually, you will put your newly created dissector file into the directory +epan/dissectors/, just like all the other packet-*.c files already in there. + +Also, please add your dissector file to the corresponding makefiles, +described in section "1.8 Editing CMakeLists.txt to add your dissector" below. + +Dissectors that use the dissector registration API to register with a lower +level protocol (this is the vast majority) don't need to define a prototype in +their .h file. For other dissectors the main dissector routine should have a +prototype in a header file whose name is "packet-", followed by the abbreviated +name for the protocol, followed by ".h"; any dissector file that calls your +dissector should be changed to include that file. + +You may not need to include all the headers listed in the skeleton, and you may +need to include additional headers. + +1.2 Explanation of needed substitutions in code skeleton. + +In the skeleton sample code the following strings should be substituted with +your information. + +YOUR_NAME Your name, of course. You do want credit, don't you? + It's the only payment you will receive.... +YOUR_EMAIL_ADDRESS Keep those cards and letters coming. +PROTONAME The name of the protocol; this is displayed in the + top-level protocol tree item for that protocol. +PROTOSHORTNAME An abbreviated name for the protocol; this is displayed + in the "Preferences" dialog box if your dissector has + any preferences, in the dialog box of enabled protocols, + and in the dialog box for filter fields when constructing + a filter expression. +PROTOFILTERNAME A name for the protocol for use in filter expressions; + it may contain only letters, digits, hyphens, underscores and + periods. Names should use lower case only. (Support for + upper/mixed case may be removed in the future.) +PROTOABBREV An abbreviation for the protocol; this is used in code and + must be a valid C identifier. Additionally it should follow + any applicable C style guidelines. It is usually the same as + PROTOFILTERNAME with all lower-case letters and + non-alphanumerics replaced with underscores. +LICENSE The license this dissector is under. Please use a SPDX License + identifier. +YEARS The years the above license is valid for. +FIELDNAME The displayed name for the header field. +FIELDFILTERNAME A name for the header field for use in filter expressions; + it may contain only letters, digits, hyphens, underscores and + periods. It must start with PROTOFILTERNAME followed by a dot. + Names should use lower case only. (Support for upper/mixed case + may be removed in the future.) +FIELDABBREV An abbreviation for the header field; this is used in code and + must be a valid C identifier. Additionally it should follow + any applicable C style guidelines. It is usually the same as + FIELDFILTERNAME with all lower-case letters and + non-alphanumerics replaced with underscores. +FIELDTYPE FT_NONE, FT_BOOLEAN, FT_CHAR, FT_UINT8, FT_UINT16, FT_UINT24, + FT_UINT32, FT_UINT40, FT_UINT48, FT_UINT56, FT_UINT64, + FT_INT8, FT_INT16, FT_INT24, FT_INT32, FT_INT40, FT_INT48, + FT_INT56, FT_INT64, FT_IEEE_11073_SFLOAT, FT_IEEE_11073_FLOAT, + FT_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME, FT_RELATIVE_TIME, + FT_STRING, FT_STRINGZ, FT_STRINGZPAD, FT_STRINGZTRUNC, + FT_UINT_STRING, FT_ETHER, FT_BYTES, FT_UINT_BYTES, FT_IPv4, + FT_IPv6, FT_IPXNET, FT_FRAMENUM, FT_PROTOCOL, FT_EUI64, FT_GUID, + FT_OID, FT_REL_OID, FT_AX25, FT_VINES, FT_SYSTEM_ID, FT_FCWWN +FIELDDISPLAY --For FT_UINT{8,16,24,32,40,48,56,64} and + FT_INT{8,16,24,32,40,48,56,64): + + BASE_DEC, BASE_HEX, BASE_OCT, BASE_DEC_HEX, BASE_HEX_DEC, + BASE_CUSTOM, or BASE_NONE, possibly ORed with + BASE_RANGE_STRING, BASE_EXT_STRING, BASE_VAL64_STRING, + BASE_ALLOW_ZERO, BASE_UNIT_STRING, BASE_SPECIAL_VALS, + BASE_NO_DISPLAY_VALUE, BASE_SHOW_ASCII_PRINTABLE, or + BASE_SHOW_UTF_8_PRINTABLE + + BASE_NONE may be used with a non-NULL FIELDCONVERT when the + numeric value of the field itself is not of significance to + the user (for example, the number is a generated field). + When this is the case the numeric value is not shown to the + user in the protocol decode nor is it used when preparing + filters for the field in question. + + BASE_NO_DISPLAY_VALUE will just display the field name with + no value. It is intended for byte arrays (FT_BYTES or + FT_UINT_BYTES) or header fields above a subtree. The + value will still be filterable, just not displayed. + + --For FT_UINT16: + + BASE_PT_UDP, BASE_PT_TCP, BASE_PT_DCCP or BASE_PT_SCTP + + --For FT_UINT24: + + BASE_OUI + + --For FT_CHAR: + BASE_HEX, BASE_OCT, BASE_CUSTOM, or BASE_NONE, possibly + ORed with BASE_RANGE_STRING, BASE_EXT_STRING or + BASE_VAL64_STRING. + + BASE_NONE can be used in the same way as with FT_UINT8. + + --For FT_FLOAT, FT_DOUBLE: + BASE_NONE, BASE_DEC, BASE_HEX, BASE_EXP or BASE_CUSTOM. + + BASE_NONE uses BASE_DEC or BASE_EXP, similarly to the + %g double format for the printf() function. + + --For FT_ABSOLUTE_TIME: + + ABSOLUTE_TIME_LOCAL, ABSOLUTE_TIME_UTC, or + ABSOLUTE_TIME_DOY_UTC + + --For FT_BOOLEAN: + + if BITMASK is non-zero: + Number of bits in the field containing the FT_BOOLEAN + bitfield. + otherwise: + (must be) BASE_NONE + + --For FT_STRING, FT_STRINGZ and FT_UINT_STRING: + + (must be) BASE_NONE + + --For FT_BYTES and FT_UINT_BYTES: + + SEP_DOT, SEP_DASH, SEP_COLON, or SEP_SPACE to provide + a separator between bytes; BASE_NONE has no separator + between bytes. These can be ORed with BASE_ALLOW_ZERO, + BASE_SHOW_ASCII_PRINTABLE, or BASE_SHOW_UTF_8_PRINTABLE. + + BASE_ALLOW_ZERO displays <none> instead of <MISSING> + for a zero-sized byte array. + BASE_SHOW_ASCII_PRINTABLE will check whether the + field's value consists entirely of printable ASCII + characters and, if so, will display the field's value + as a string, in quotes. The value will still be + filterable as a byte value. + BASE_SHOW_UTF_8_PRINTABLE will check whether the + field's value is valid UTF-8 consisting entirely of + printable characters and, if so, will display the field's + value as a string, in quotes. The value will still be + filterable as a byte value. + + --For FT_IPv4: + + BASE_NETMASK - Used for IPv4 address that should never + attempted to be resolved (like netmasks) + otherwise: + (must be) BASE_NONE + + --For all other types: + + BASE_NONE +FIELDCONVERT VALS(x), VALS64(x), RVALS(x), TFS(x), CF_FUNC(x), NULL +BITMASK Used to mask a field not 8-bit aligned or with a size other + than a multiple of 8 bits +FIELDDESCR A brief description of the field, or NULL. [Please do not use ""]. + +If, for example, PROTONAME is "Internet Bogosity Discovery Protocol", +PROTOSHORTNAME would be "IBDP", and PROTOFILTERNAME would be "ibdp". Try to +conform with IANA names. + +1.2.1 Automatic substitution in code skeleton + +Instead of manual substitutions in the code skeleton, a tool to automate it can +be found under the tools directory. The script is called tools/generate-dissector.py +and takes all the needed options to generate a compilable dissector. Look at the +above fields to know how to set them. Some assumptions have been made in the +generation to shorten the list of required options. The script patches the +CMakeLists.txt file adding the new dissector in the proper list, alphabetically +sorted. + +1.3 The dissector and the data it receives. + + +1.3.1 Header file. + +This is only needed if the dissector doesn't use self-registration to +register itself with the lower level dissector, or if the protocol dissector +wants/needs to expose code to other subdissectors. + +The dissector must be declared exactly as follows in the file +packet-PROTOABBREV.h: + +int +dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree); + + +1.3.2 Extracting data from packets. + +NOTE: See the file /epan/tvbuff.h for more details. + +The "tvb" argument to a dissector points to a buffer containing the raw +data to be analyzed by the dissector; for example, for a protocol +running atop UDP, it contains the UDP payload (but not the UDP header, +or any protocol headers above it). A tvbuffer is an opaque data +structure, the internal data structures are hidden and the data must be +accessed via the tvbuffer accessors. + +The accessors are: + +Bit accessors for a maximum of 8-bits, 16-bits 32-bits and 64-bits: + +uint8_t tvb_get_bits8(tvbuff_t *tvb, int bit_offset, const int no_of_bits); +uint16_t tvb_get_bits16(tvbuff_t *tvb, unsigned bit_offset, const int no_of_bits, const unsigned encoding); +uint32_t tvb_get_bits32(tvbuff_t *tvb, unsigned bit_offset, const int no_of_bits, const unsigned encoding); +uint64_t tvb_get_bits64(tvbuff_t *tvb, unsigned bit_offset, const int no_of_bits, const unsigned encoding); + +Single-byte accessors for 8-bit unsigned integers (uint8_t) and 8-bit +signed integers (int8_t): + +uint8_t tvb_get_guint8(tvbuff_t *tvb, const int offset); +int8_t tvb_get_gint8(tvbuff_t *tvb, const int offset); + +Network-to-host-order accessors: + +16-bit unsigned (uint16_t) and signed (int16_t) integers: + +uint16_t tvb_get_ntohs(tvbuff_t *tvb, const int offset); +int16_t tvb_get_ntohis(tvbuff_t *tvb, const int offset); + +24-bit unsigned and signed integers: + +uint32_t tvb_get_ntoh24(tvbuff_t *tvb, const int offset); +int32_t tvb_get_ntohi24(tvbuff_t *tvb, const int offset); + +32-bit unsigned (uint32_t) and signed (int32_t) integers: + +uint32_t tvb_get_ntohl(tvbuff_t *tvb, const int offset); +int32_t tvb_get_ntohil(tvbuff_t *tvb, const int offset); + +40-bit unsigned and signed integers: + +uint64_t tvb_get_ntoh40(tvbuff_t *tvb, const int offset); +int64_t tvb_get_ntohi40(tvbuff_t *tvb, const int offset); + +48-bit unsigned and signed integers: + +uint64_t tvb_get_ntoh48(tvbuff_t *tvb, const int offset); +int64_t tvb_get_ntohi48(tvbuff_t *tvb, const int offset); + +56-bit unsigned and signed integers: + +uint64_t tvb_get_ntoh56(tvbuff_t *tvb, const int offset); +int64_t tvb_get_ntohi56(tvbuff_t *tvb, const int offset); + +64-bit unsigned (uint64_t) and signed (int64_t) integers: + +uint64_t tvb_get_ntoh64(tvbuff_t *tvb, const int offset); +int64_t tvb_get_ntohi64(tvbuff_t *tvb, const int offset); + +Single-precision and double-precision IEEE floating-point numbers: + +float tvb_get_ntohieee_float(tvbuff_t *tvb, const int offset); +double tvb_get_ntohieee_double(tvbuff_t *tvb, const int offset); + +Little-Endian-to-host-order accessors: + +16-bit unsigned (uint16_t) and signed (int16_t) integers: + +uint16_t tvb_get_letohs(tvbuff_t *tvb, const int offset); +int16_t tvb_get_letohis(tvbuff_t *tvb, const int offset); + +24-bit unsigned and signed integers: + +uint32_t tvb_get_letoh24(tvbuff_t *tvb, const int offset); +int32_t tvb_get_letohi24(tvbuff_t *tvb, const int offset); + +32-bit unsigned (uint32_t) and signed (int32_t) integers: + +uint32_t tvb_get_letohl(tvbuff_t *tvb, const int offset); +int32_t tvb_get_letohil(tvbuff_t *tvb, const int offset); + +40-bit unsigned and signed integers: + +uint64_t tvb_get_letoh40(tvbuff_t *tvb, const int offset); +int64_t tvb_get_letohi40(tvbuff_t *tvb, const int offset); + +48-bit unsigned and signed integers: + +uint64_t tvb_get_letoh48(tvbuff_t *tvb, const int offset); +int64_t tvb_get_letohi48(tvbuff_t *tvb, const int offset); + +56-bit unsigned and signed integers: + +uint64_t tvb_get_letoh56(tvbuff_t *tvb, const int offset); +int64_t tvb_get_letohi56(tvbuff_t *tvb, const int offset); + +64-bit unsigned (uint64_t) and signed (int64_t) integers: + +uint64_t tvb_get_letoh64(tvbuff_t *tvb, const int offset); +int64_t tvb_get_letohi64(tvbuff_t *tvb, const int offset); + +NOTE: Although each of the integer accessors above return types with +specific sizes, the returned values are subject to C's integer promotion +rules. It's often safer and more useful to use int or unsigned for 32-bit +and smaller types, and int64_t or uint64_t for 40-bit and larger types. +Just because a value occupied 16 bits on the wire or over the air +doesn't mean it will within Wireshark. + +Single-precision and double-precision IEEE floating-point numbers: + +float tvb_get_letohieee_float(tvbuff_t *tvb, const int offset); +double tvb_get_letohieee_double(tvbuff_t *tvb, const int offset); + +Encoding-to_host-order accessors: + +16-bit unsigned (uint16_t) and signed (int16_t) integers: + +uint16_t tvb_get_guint16(tvbuff_t *tvb, const int offset, const unsigned encoding); +int16_t tvb_get_gint16(tvbuff_t *tvb, const int offset, const unsigned encoding); + +24-bit unsigned and signed integers: + +uint32_t tvb_get_guint24(tvbuff_t *tvb, const int offset, const unsigned encoding); +int32_t tvb_get_gint24(tvbuff_t *tvb, const int offset, const unsigned encoding); + +32-bit unsigned (uint32_t) and signed (int32_t) integers: + +uint32_t tvb_get_guint32(tvbuff_t *tvb, const int offset, const unsigned encoding); +int32_t tvb_get_gint32(tvbuff_t *tvb, const int offset, const unsigned encoding); + +40-bit unsigned and signed integers: + +uint64_t tvb_get_guint40(tvbuff_t *tvb, const int offset, const unsigned encoding); +int64_t tvb_get_gint40(tvbuff_t *tvb, const int offset, const unsigned encoding); + +48-bit unsigned and signed integers: + +uint64_t tvb_get_guint48(tvbuff_t *tvb, const int offset, const unsigned encoding); +int64_t tvb_get_gint48(tvbuff_t *tvb, const int offset, const unsigned encoding); + +56-bit unsigned and signed integers: + +uint64_t tvb_get_guint56(tvbuff_t *tvb, const int offset, const unsigned encoding); +int64_t tvb_get_gint56(tvbuff_t *tvb, const int offset, const unsigned encoding); + +64-bit unsigned (uint64_t) and signed (int64_t) integers: + +uint64_t tvb_get_guint64(tvbuff_t *tvb, const int offset, const unsigned encoding); +int64_t tvb_get_gint64(tvbuff_t *tvb, const int offset, const unsigned encoding); + +Single-precision and double-precision IEEE floating-point numbers: + +float tvb_get_ieee_float(tvbuff_t *tvb, const int offset, const unsigned encoding); +double tvb_get_ieee_double(tvbuff_t *tvb, const int offset, const unsigned encoding); + +"encoding" should be ENC_BIG_ENDIAN for Network-to-host-order, +ENC_LITTLE_ENDIAN for Little-Endian-to-host-order, or ENC_HOST_ENDIAN +for host order. + +Accessors for IPv4 and IPv6 addresses: + +uint32_t tvb_get_ipv4(tvbuff_t *tvb, const int offset); +void tvb_get_ipv6(tvbuff_t *tvb, const int offset, ws_in6_addr *addr); + +NOTE: IPv4 addresses are not to be converted to host byte order before +being passed to "proto_tree_add_ipv4()". You should use "tvb_get_ipv4()" +to fetch them, not "tvb_get_ntohl()" *OR* "tvb_get_letohl()" - don't, +for example, try to use "tvb_get_ntohl()", find that it gives you the +wrong answer on the PC on which you're doing development, and try +"tvb_get_letohl()" instead, as "tvb_get_letohl()" will give the wrong +answer on big-endian machines. + +char *tvb_ip_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset) +char *tvb_ip6_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset) + +Returns a null-terminated buffer containing a string with IPv4 or IPv6 Address +from the specified tvbuff, starting at the specified offset. + +Accessors for GUID: + +void tvb_get_ntohguid(tvbuff_t *tvb, const int offset, e_guid_t *guid); +void tvb_get_letohguid(tvbuff_t *tvb, const int offset, e_guid_t *guid); +void tvb_get_guid(tvbuff_t *tvb, const int offset, e_guid_t *guid, const unsigned encoding); + +String accessors: + +uint8_t *tvb_get_string_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset, const int length, const unsigned encoding); + +Returns a null-terminated buffer allocated from the specified scope, containing +data from the specified tvbuff, starting at the specified offset, and containing +the specified length worth of characters. Reads data in the specified encoding +and produces UTF-8 in the buffer. See below for a list of input encoding values. + +The buffer is allocated in the given wmem scope (see README.wmem for more +information). + +uint8_t *tvb_get_stringz_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset, int *lengthp, const unsigned encoding); + +Returns a null-terminated buffer allocated from the specified scope, +containing data from the specified tvbuff, starting at the specified +offset, and containing all characters from the tvbuff up to and +including a terminating null character in the tvbuff. Reads data in the +specified encoding and produces UTF-8 in the buffer. See below for a +list of input encoding values. "*lengthp" will be set to the length of +the string, including the terminating null. + +The buffer is allocated in the given wmem scope (see README.wmem for more +information). + +int tvb_get_nstringz(tvbuff_t *tvb, const int offset, const unsigned bufsize, uint8_t* buffer); +int tvb_get_nstringz0(tvbuff_t *tvb, const int offset, const unsigned bufsize, uint8_t* buffer); + +Copies bufsize bytes, including the terminating NULL, to buffer. If a NULL +terminator is found before reaching bufsize, only the bytes up to and including +the NULL are copied. Returns the number of bytes copied (not including +terminating NULL), or -1 if the string was truncated in the buffer due to +not having reached the terminating NULL. In this case, the resulting +buffer is not NULL-terminated. +tvb_get_nstringz0() works like tvb_get_nstringz(), but never returns -1 since +the string is guaranteed to have a terminating NULL. If the string was truncated +when copied into buffer, a NULL is placed at the end of buffer to terminate it. + +char *tvb_get_ts_23_038_7bits_string(wmem_allocator_t *scope, tvbuff_t *tvb, + const int bit_offset, int no_of_chars); + +tvb_get_ts_23_038_7bits_string() returns a string of a given number of +characters and encoded according to 3GPP TS 23.038 7 bits alphabet. + +The buffer is allocated in the given wmem scope (see README.wmem for more +information). + +Byte Array Accessors: + +char *tvb_bytes_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset, const int len); + +Formats a bunch of data from a tvbuff as bytes, returning a pointer +to the string with the data formatted as two hex digits for each byte. +The string pointed to is stored in an "wmem_alloc'd" buffer which will be freed +depending on its scope (typically wmem_packet_scope which is freed after the frame). +The formatted string will contain the hex digits for at most the first 16 bytes of +the data. If len is greater than 16 bytes, a trailing "..." will be added to the string. + +char *tvb_bytes_to_str_punct(wmem_allocator_t *scope, tvbuff_t *tvb, + const int offset, const int len, const char punct); + +This function is similar to tvb_bytes_to_str(...) except that 'punct' is inserted +between the hex representation of each byte. + +GByteArray *tvb_get_string_bytes(tvbuff_t *tvb, const int offset, const int length, + const unsigned encoding, GByteArray* bytes, int *endoff) + +Given a tvbuff, an offset into the tvbuff, and a length that starts +at that offset (which may be -1 for "all the way to the end of the +tvbuff"), fetch the hex-decoded byte values of the tvbuff into the +passed-in 'bytes' array, based on the passed-in encoding. In other +words, convert from a hex-ascii string in tvbuff, into the supplied +GByteArray. + +char *tvb_bcd_dig_to_wmem_packet_str(tvbuff_t *tvb, const int offset, const int len, dgt_set_t *dgt, bool skip_first); + +Given a tvbuff, an offset into the tvbuff, and a length that starts +at that offset (which may be -1 for "all the way to the end of the +tvbuff"), fetch BCD encoded digits from a tvbuff starting from either +the low or high half byte, formatting the digits according to an input digit set, +if NUll a default digit set of 0-9 returning "?" for overdecadic digits will be used. +A pointer to the packet scope allocated string will be returned. +Note: a tvbuff content of 0xf is considered a 'filler' and will end the conversion. + +Copying memory: +void* tvb_memcpy(tvbuff_t *tvb, void* target, const int offset, size_t length); + +Copies into the specified target the specified length's worth of data +from the specified tvbuff, starting at the specified offset. + +void *tvb_memdup(wmem_allocator_t *scope, tvbuff_t *tvb, const int offset, size_t length); + +Returns a buffer containing a copy of the given TVB bytes. The buffer is +allocated in the given wmem scope (see README.wmem for more information). + +Pointer-retrieval: +/* WARNING! Don't use this function. There is almost always a better way. + * It's dangerous because once this pointer is given to the user, there's + * no guarantee that the user will honor the 'length' and not overstep the + * boundaries of the buffer. Also see the warning in the Portability section. + */ +const uint8_t* tvb_get_ptr(tvbuff_t *tvb, const int offset, const int length); + +Length query: +Get amount of captured data in the buffer (which is *NOT* necessarily the +length of the packet). You probably want tvb_reported_length instead: + + unsigned tvb_captured_length(const tvbuff_t *tvb); + +Get reported length of buffer: + + unsigned tvb_reported_length(const tvbuff_t *tvb); + + +1.4 Functions to handle columns in the traffic summary window. + +The topmost pane of the main window is a list of the packets in the +capture, possibly filtered by a display filter. + +Each line corresponds to a packet, and has one or more columns, as +configured by the user. + +Many of the columns are handled by code outside individual dissectors; +most dissectors need only specify the value to put in the "Protocol" and +"Info" columns. + +Columns are specified by COL_ values; the COL_ value for the "Protocol" +field, typically giving an abbreviated name for the protocol (but not +the all-lower-case abbreviation used elsewhere) is COL_PROTOCOL, and the +COL_ value for the "Info" field, giving a summary of the contents of the +packet for that protocol, is COL_INFO. + +The value for a column can be specified with one of several functions, +all of which take the 'fd' argument to the dissector as their first +argument, and the COL_ value for the column as their second argument. + +1.4.1 The col_set_str function. + +'col_set_str' takes a string as its third argument, and sets the value +for the column to that value. It assumes that the pointer passed to it +points to a string constant or a static "const" array, not to a +variable, as it doesn't copy the string, it merely saves the pointer +value; the argument can itself be a variable, as long as it always +points to a string constant or a static "const" array. + +It is more efficient than 'col_add_str' or 'col_add_fstr'; however, if +the dissector will be using 'col_append_str' or 'col_append_fstr" to +append more information to the column, the string will have to be copied +anyway, so it's best to use 'col_add_str' rather than 'col_set_str' in +that case. + +For example, to set the "Protocol" column +to "PROTOFILTERNAME": + + col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOFILTERNAME"); + + +1.4.2 The col_add_str function. + +'col_add_str' takes a string as its third argument, and sets the value +for the column to that value. It takes the same arguments as +'col_set_str', but copies the string, so that if the string is, for +example, an automatic variable that won't remain in scope when the +dissector returns, it's safe to use. + + +1.4.3 The col_add_fstr function. + +'col_add_fstr' takes a 'printf'-style format string as its third +argument, and 'printf'-style arguments corresponding to '%' format +items in that string as its subsequent arguments. For example, to set +the "Info" field to "<XXX> request, <N> bytes", where "reqtype" is a +string containing the type of the request in the packet and "n" is an +unsigned integer containing the number of bytes in the request: + + col_add_fstr(pinfo->cinfo, COL_INFO, "%s request, %u bytes", + reqtype, n); + +Don't use 'col_add_fstr' with a format argument of just "%s" - +'col_add_str', or possibly even 'col_set_str' if the string that matches +the "%s" is a static constant string, will do the same job more +efficiently. + + +1.4.4 The col_clear function. + +If the Info column will be filled with information from the packet, that +means that some data will be fetched from the packet before the Info +column is filled in. If the packet is so small that the data in +question cannot be fetched, the routines to fetch the data will throw an +exception (see the comment at the beginning about tvbuffers improving +the handling of short packets - the tvbuffers keep track of how much +data is in the packet, and throw an exception on an attempt to fetch +data past the end of the packet, so that the dissector won't process +bogus data), causing the Info column not to be filled in. + +This means that the Info column will have data for the previous +protocol, which would be confusing if, for example, the Protocol column +had data for this protocol. + +Therefore, before a dissector fetches any data whatsoever from the +packet (unless it's a heuristic dissector fetching data to determine +whether the packet is one that it should dissect, in which case it +should check, before fetching the data, whether there's any data to +fetch; if there isn't, it should return false), it should set the +Protocol column and the Info column. + +If the Protocol column will ultimately be set to, for example, a value +containing a protocol version number, with the version number being a +field in the packet, the dissector should, before fetching the version +number field or any other field from the packet, set it to a value +without a version number, using 'col_set_str', and should later set it +to a value with the version number after it's fetched the version +number. + +If the Info column will ultimately be set to a value containing +information from the packet, the dissector should, before fetching any +fields from the packet, clear the column using 'col_clear' (which is +more efficient than clearing it by calling 'col_set_str' or +'col_add_str' with a null string), and should later set it to the real +string after it's fetched the data to use when doing that. + + +1.4.5 The col_append_str function. + +Sometimes the value of a column, especially the "Info" column, can't be +conveniently constructed at a single point in the dissection process; +for example, it might contain small bits of information from many of the +fields in the packet. 'col_append_str' takes, as arguments, the same +arguments as 'col_add_str', but the string is appended to the end of the +current value for the column, rather than replacing the value for that +column. (Note that no blank separates the appended string from the +string to which it is appended; if you want a blank there, you must add +it yourself as part of the string being appended.) + + +1.4.6 The col_append_fstr function. + +'col_append_fstr' is to 'col_add_fstr' as 'col_append_str' is to +'col_add_str' - it takes, as arguments, the same arguments as +'col_add_fstr', but the formatted string is appended to the end of the +current value for the column, rather than replacing the value for that +column. + +1.4.7 The col_append_sep_str and col_append_sep_fstr functions. + +In specific situations the developer knows that a column's value will be +created in a stepwise manner, where the appended values are listed. Both +'col_append_sep_str' and 'col_append_sep_fstr' functions will add an item +separator between two consecutive items, and will not add the separator at the +beginning of the column. The remainder of the work both functions do is +identical to what 'col_append_str' and 'col_append_fstr' do. + +1.4.8 The col_set_fence and col_prepend_fence_fstr functions. + +Sometimes a dissector may be called multiple times for different PDUs in the +same frame (for example in the case of SCTP chunk bundling: several upper +layer data packets may be contained in one SCTP packet). If the upper layer +dissector calls 'col_set_str()' or 'col_clear()' on the Info column when it +begins dissecting each of those PDUs then when the frame is fully dissected +the Info column would contain only the string from the last PDU in the frame. +The 'col_set_fence' function erects a "fence" in the column that prevents +subsequent 'col_...' calls from clearing the data currently in that column. +For example, the SCTP dissector calls 'col_set_fence' on the Info column +after it has called any subdissectors for that chunk so that subdissectors +of any subsequent chunks may only append to the Info column. +'col_prepend_fence_fstr' prepends data before a fence (moving it if +necessary). It will create a fence at the end of the prepended data if the +fence does not already exist. + + +1.4.9 The col_set_time function. + +The 'col_set_time' function takes an nstime value as its third argument. +This nstime value is a relative value and will be added as such to the +column. The fourth argument is the filtername holding this value. This +way, rightclicking on the column makes it possible to build a filter +based on the time-value. + +For example: + + col_set_time(pinfo->cinfo, COL_REL_TIME, &ts, "s4607.ploc.time"); + + +1.5 Constructing the protocol tree. + +The middle pane of the main window, and the topmost pane of a packet +popup window, are constructed from the "protocol tree" for a packet. + +The protocol tree, or proto_tree, is a GNode, the N-way tree structure +available within GLIB. Of course the protocol dissectors don't care +what a proto_tree really is; they just pass the proto_tree pointer as an +argument to the routines which allow them to add items and new branches +to the tree. + +When a packet is selected in the packet-list pane, or a packet popup +window is created, a new logical protocol tree (proto_tree) is created. +The pointer to the proto_tree (in this case, 'protocol tree'), is passed +to the top-level protocol dissector, and then to all subsequent protocol +dissectors for that packet, and then the GUI tree is drawn via +proto_tree_draw(). + +The logical proto_tree needs to know detailed information about the protocols +and fields about which information will be collected from the dissection +routines. By strictly defining (or "typing") the data that can be attached to a +proto tree, searching and filtering becomes possible. This means that for +every protocol and field (which I also call "header fields", since they are +fields in the protocol headers) which might be attached to a tree, some +information is needed. + +Every dissector routine will need to register its protocols and fields +with the central protocol routines (in proto.c). At first I thought I +might keep all the protocol and field information about all the +dissectors in one file, but decentralization seemed like a better idea. +That one file would have gotten very large; one small change would have +required a re-compilation of the entire file. Also, by allowing +registration of protocols and fields at run-time, loadable modules of +protocol dissectors (perhaps even user-supplied) is feasible. + +To do this, each protocol should have a register routine, which will be +called when Wireshark starts. The code to call the register routines is +generated automatically; to arrange that a protocol's register routine +be called at startup: + + the file containing a dissector's "register" routine must be + added to "DISSECTOR_SRC" in "epan/dissectors/CMakeLists.txt"; + + the "register" routine must have a name of the form + "proto_register_XXX"; + + the "register" routine must take no argument, and return no + value; + + the "register" routine's name must appear in the source file + either at the beginning of the line, or preceded only by "void " + at the beginning of the line (that would typically be the + definition) - other white space shouldn't cause a problem, e.g.: + +void proto_register_XXX(void) { + + ... + +} + +and + +void +proto_register_XXX( void ) +{ + + ... + +} + + and so on should work. + +For every protocol or field that a dissector wants to register, a variable of +type int needs to be used to keep track of the protocol. The IDs are +needed for establishing parent/child relationships between protocols and +fields, as well as associating data with a particular field so that it +can be stored in the logical tree and displayed in the GUI protocol +tree. + +Some dissectors will need to create branches within their tree to help +organize header fields. These branches should be registered as header +fields. Only true protocols should be registered as protocols. This is +so that a display filter user interface knows how to distinguish +protocols from fields. + +A protocol is registered with the name of the protocol and its +abbreviation. + +Here is how the frame "protocol" is registered. + + int proto_frame; + + proto_frame = proto_register_protocol ( + /* name */ "Frame", + /* short name */ "Frame", + /* abbrev */ "frame" ); + +A header field is also registered with its name and abbreviation, but +information about its data type is needed. It helps to look at +the header_field_info struct to see what information is expected: + +struct header_field_info { + const char *name; + const char *abbrev; + enum ftenum type; + int display; + const void *strings; + uint64_t bitmask; + const char *blurb; + ..... +}; + +name (FIELDNAME) +---------------- +A string representing the name of the field. This is the name +that will appear in the graphical protocol tree. It must be a non-empty +string. + +abbrev (FIELDFILTERNAME) +-------------------- +A string with a filter name for the field. The name should start +with the filter name of the parent protocol followed by a period as a +separator. For example, the "src" field in an IP packet would have "ip.src" +as a filter name. It is acceptable to have multiple levels of periods if, +for example, you have fields in your protocol that are then subdivided into +subfields. For example, TRMAC has multiple error fields, so the names +follow this pattern: "trmac.errors.iso", "trmac.errors.noniso", etc. +It must be a non-empty string. + +type (FIELDTYPE) +---------------- +The type of value this field holds. The current field types are: + + FT_NONE No field type. Used for fields that + aren't given a value, and that can only + be tested for presence or absence; a + field that represents a data structure, + with a subtree below it containing + fields for the members of the structure, + or that represents an array with a + subtree below it containing fields for + the members of the array, might be an + FT_NONE field. + FT_PROTOCOL Used for protocols which will be placing + themselves as top-level items in the + "Packet Details" pane of the UI. + FT_BOOLEAN 0 means "false", any other value means + "true". + FT_FRAMENUM A frame number; if this is used, the "Go + To Corresponding Frame" menu item can + work on that field. + FT_CHAR An 8-bit ASCII character. It's treated similarly to an + FT_UINT8, but is displayed as a C-style character + constant. + FT_UINT8 An 8-bit unsigned integer. + FT_UINT16 A 16-bit unsigned integer. + FT_UINT24 A 24-bit unsigned integer. + FT_UINT32 A 32-bit unsigned integer. + FT_UINT40 A 40-bit unsigned integer. + FT_UINT48 A 48-bit unsigned integer. + FT_UINT56 A 56-bit unsigned integer. + FT_UINT64 A 64-bit unsigned integer. + FT_INT8 An 8-bit signed integer. + FT_INT16 A 16-bit signed integer. + FT_INT24 A 24-bit signed integer. + FT_INT32 A 32-bit signed integer. + FT_INT40 A 40-bit signed integer. + FT_INT48 A 48-bit signed integer. + FT_INT56 A 56-bit signed integer. + FT_INT64 A 64-bit signed integer. + FT_IEEE_11073_SFLOAT A 16-bit floating point number, consisting + of an 4-bit exponent and 12-bit mantissa. + FT_IEEE_11073_FLOAT A 32-bit floating point number, consisting + of an 8-bit exponent and 24-bit mantissa. + FT_FLOAT A single-precision floating point number. + FT_DOUBLE A double-precision floating point number. + FT_ABSOLUTE_TIME An absolute time from some fixed point in time, + displayed as the date, followed by the time, as + hours, minutes, and seconds with 9 digits after + the decimal point. + FT_RELATIVE_TIME Seconds (4 bytes) and nanoseconds (4 bytes) + of time relative to an arbitrary time. + displayed as seconds and 9 digits + after the decimal point. + FT_STRING A string of characters, not necessarily + NULL-terminated, but possibly NULL-padded. + This, and the other string-of-characters + types, are to be used for text strings, + not raw binary data. + FT_STRINGZ A NULL-terminated string of characters. + The string length is normally the length + given in the proto_tree_add_item() call. + However if the length given in the call + is -1, then the length used is that + returned by calling tvb_strsize(). + This should only be used if the string, + in the packet, is always terminated with + a NULL character, either because the length + isn't otherwise specified or because a + character count *and* a NULL terminator are + both used. + FT_STRINGZPAD A NULL-padded string of characters. + The length is given in the proto_tree_add_item() + call, but may be larger than the length of + the string, with extra bytes being NULL padding. + This is typically used for fixed-length fields + that contain a string value that might be shorter + than the fixed length. + FT_STRINGZTRUNC A NULL-truncated string of characters. + The length is given in the proto_tree_add_item() + call, but may be larger than the length of + the string, with a NULL character after the last + character of the string, and the remaining bytes + being padding with unspecified contents. This is + typically used for fixed-length fields that contain + a string value that might be shorter than the fixed + length. + FT_UINT_STRING A counted string of characters, consisting + of a count (represented as an integral value, + of width given in the proto_tree_add_item() + call) followed immediately by that number of + characters. + FT_ETHER A six octet string displayed in + Ethernet-address format. + FT_BYTES A string of bytes with arbitrary values; + used for raw binary data. + FT_UINT_BYTES A counted string of bytes, consisting + of a count (represented as an integral value, + of width given in the proto_tree_add_item() + call) followed immediately by that number of + arbitrary values; used for raw binary data. + FT_IPv4 A version 4 IP address (4 bytes) displayed + in dotted-quad IP address format (4 + decimal numbers separated by dots). + FT_IPv6 A version 6 IP address (16 bytes) displayed + in standard IPv6 address format. + FT_IPXNET An IPX address displayed in hex as a 6-byte + network number followed by a 6-byte station + address. + FT_GUID A Globally Unique Identifier + FT_OID An ASN.1 Object Identifier + FT_REL_OID An ASN.1 Relative Object Identifier + FT_EUI64 A EUI-64 Address + FT_AX25 A AX-25 Address + FT_VINES A Vines Address + FT_SYSTEM_ID An OSI System-ID + FT_FCWWN A Fibre Channel WWN Address + +Some of these field types are still not handled in the display filter +routines, but the most common ones are. The FT_UINT* variables all +represent unsigned integers, and the FT_INT* variables all represent +signed integers; the number on the end represent how many bits are used +to represent the number. + +Some constraints are imposed on the header fields depending on the type +(e.g. FT_BYTES) of the field. Fields of type FT_ABSOLUTE_TIME must use +'ABSOLUTE_TIME_{LOCAL,UTC,DOY_UTC}, NULL, 0x0' as values for the +'display, 'strings', and 'bitmask' fields, and all other non-integral +types (i.e.. types that are _not_ FT_INT* and FT_UINT*) must use +'BASE_NONE, NULL, 0x0' as values for the 'display', 'strings', 'bitmask' +fields. The reason is simply that the type itself implicitly defines the +nature of 'display', 'strings', 'bitmask'. + +display (FIELDDISPLAY) +---------------------- +The display field has a couple of overloaded uses. This is unfortunate, +but since we're using C as an application programming language, this sometimes +makes for cleaner programs. Right now I still think that overloading +this variable was okay. + +For integer fields (FT_UINT* and FT_INT*), this variable represents the +base in which you would like the value displayed. The acceptable bases +are: + + BASE_DEC, + BASE_HEX, + BASE_OCT, + BASE_DEC_HEX, + BASE_HEX_DEC, + BASE_CUSTOM + +BASE_DEC, BASE_HEX, and BASE_OCT are decimal, hexadecimal, and octal, +respectively. BASE_DEC_HEX and BASE_HEX_DEC display value in two bases +(the 1st representation followed by the 2nd in parenthesis). + +BASE_CUSTOM allows one to specify a callback function pointer that will +format the value. + +For 32-bit and smaller values, custom_fmt_func_t can be used to declare +the callback function pointer. Specifically, this is defined as: + + void func(char *, uint32_t); + +For values larger than 32-bits, custom_fmt_func_64_t can be used to declare +the callback function pointer. Specifically, this is defined as: + + void func(char *, uint64_t); + +The first argument is a pointer to a buffer of the ITEM_LABEL_LENGTH size +and the second argument is the value to be formatted. + +Both custom_fmt_func_t and custom_fmt_func_64_t are defined in epan/proto.h. + +For FT_UINT16 'display' can be used to select a transport layer protocol using one +of BASE_PT_UDP, BASE_PT_TCP, BASE_PT_DCCP or BASE_PT_SCTP. If transport name +resolution is enabled the port field label is displayed in decimal and as a well-known +service name (if one is available). + +For FT_BOOLEAN fields that are also bitfields (i.e., 'bitmask' is non-zero), +'display' is used specify a "field-width" (i.e., tell the proto_tree how +wide the parent bitfield is). (If the FT_BOOLEAN 'bitmask' is zero, then +'display' must be BASE_NONE). + +For integer fields a "field-width" is not needed since the type of +integer itself (FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, FT_UINT40, +FT_UINT48, FT_UINT56, FT_UINT64, etc) tells the proto_tree how wide the +parent bitfield is. The same is true of FT_CHAR, as it's an 8-bit +character. + +For FT_ABSOLUTE_TIME fields, 'display' is used to indicate whether the +time is to be displayed as a time in the time zone for the machine on +which Wireshark/TShark is running or as UTC and, for UTC, whether the +date should be displayed as "{monthname} {day_of_month}, {year}" or as +"{year/day_of_year}". + +Additionally, BASE_NONE is used for 'display' as a NULL-value. That is, for +non-integers other than FT_ABSOLUTE_TIME fields, and non-bitfield +FT_BOOLEANs, you'll want to use BASE_NONE in the 'display' field. You may +not use BASE_NONE for integers. + +It is possible that in the future we will record the endianness of +integers. If so, it is likely that we'll use a bitmask on the display field +so that integers would be represented as BEND|BASE_DEC or LEND|BASE_HEX. +But that has not happened yet; note that there are protocols for which +no endianness is specified, such as the X11 protocol and the DCE RPC +protocol, so it would not be possible to record the endianness of all +integral fields. + +strings (FIELDCONVERT) +---------------------- +-- value_string +Some integer fields, of type FT_UINT*, need labels to represent the true +value of a field. You could think of those fields as having an +enumerated data type, rather than an integral data type. + +A 'value_string' structure is a way to map values to strings. + + typedef struct _value_string { + uint32_t value; + char *strptr; + } value_string; + +For fields of that type, you would declare an array of "value_string"s: + + static const value_string valstringname[] = { + { INTVAL1, "Descriptive String 1" }, + { INTVAL2, "Descriptive String 2" }, + { 0, NULL } + }; + +(the last entry in the array must have a NULL 'strptr' value, to +indicate the end of the array). The 'strings' field would be set to +'VALS(valstringname)'. + +If the field has a numeric rather than an enumerated type, the 'strings' +field would be set to NULL. + +If BASE_SPECIAL_VALS is also applied to the display bitmask, then if the +numeric value of a field doesn't match any values in the value_string +then just the numeric value is displayed (i.e. no "Unknown"). This is +intended for use when the value_string only gives special names for +certain field values and values not in the value_string are expected. + +-- Extended value strings +You can also use an extended version of the value_string for faster lookups. +It requires a value_string array as input. +If all of a contiguous range of values from min to max are present in the array +in ascending order the value will be used as a direct index into a value_string array. + +If the values in the array are not contiguous (ie: there are "gaps"), but are +in ascending order a binary search will be used. + +Note: "gaps" in a value_string array can be filled with "empty" entries eg: +{value, "Unknown"} so that direct access to the array is possible. + +Note: the value_string array values are *unsigned*; IOW: -1 is greater than 0. + So: + { -2, -1, 1, 2 }; wrong: linear search will be used (note gap) + { 1, 2, -2, -1 }; correct: binary search will be used + + As a special case: + { -2, -1, 0, 1, 2 }; OK: direct(indexed) access will be used (note no gap) + +The init macro (see below) will perform a check on the value string the first +time it is used to determine which search algorithm fits and fall back to a +linear search if the value_string does not meet the criteria above. + +Use this macro to initialize the extended value_string at compile time: + +static value_string_ext valstringname_ext = VALUE_STRING_EXT_INIT(valstringname); + +Extended value strings can be created at run time by calling + value_string_ext_new(<ptr to value_string array>, + <total number of entries in the value_string_array>, /* include {0, NULL} entry */ + <value_string_name>); + +For hf[] array FT_(U)INT* fields that need a 'valstringname_ext' struct, the +'strings' field would be set to '&valstringname_ext'. Furthermore, the 'display' +field must be ORed with 'BASE_EXT_STRING' (e.g. BASE_DEC|BASE_EXT_STRING). + +-- val64_string + +val64_strings are like value_strings, except that the integer type +used is a uint64_t (instead of uint32_t). Instead of using the VALS() +macro for the 'strings' field in the header_field_info struct array, +'VALS64()' is used. + +BASE_SPECIAL_VALS can also be used for val64_string. + +-- val64_string_ext + +val64_string_ext is like value_string_ext, except that the integer type +used is a uint64_t (instead of uint32_t). + +Use this macro to initialize the extended val64_string at compile time: + +static val64_string_ext val64stringname_ext = VAL64_STRING_EXT_INIT(val64stringname); + +Extended val64 strings can be created at run time by calling + val64_string_ext_new(<ptr to val64_string array>, + <total number of entries in the val64_string_array>, /* include {0, NULL} entry */ + <val64_string_name>); + +For hf[] array FT_(U)INT* fields that need a 'val64stringname_ext' struct, the +'strings' field would be set to '&val64stringname_ext'. Furthermore, the 'display' +field must be ORed with both 'BASE_EXT_STRING' and 'BASE_VAL64_STRING' +(e.g. BASE_DEC|BASE_EXT_STRING|BASE_VAL64_STRING). + +-- Unit string +Some integer fields, of type FT_UINT* and float fields, of type FT_FLOAT +or FT_DOUBLE, need units of measurement to help convey the field value. + +A 'unit_name_string' structure is a way to add a unit suffix to a field. + + typedef struct unit_name_string { + char *singular; /* name to use for 1 unit */ + char *plural; /* name to use for < 1 or > 1 units */ + } unit_name_string; + +For fields with that unit name, you would declare a "unit_name_string": + + static const unit_name_string unitname[] = + { "single item name" , "multiple item name" }; + +(the second entry can be NULL if there is no plural form of the unit name. +This is typically the case when abbreviations are used instead of full words.) + +For hf[] array FT_(U)INT*, FT_FLOAT and FT_DOUBLE fields that need a +'unit_name_string' struct, the 'strings' field would be set to +'&unitname'. Furthermore, the 'display' field must be ORed +with 'BASE_UNIT_STRING' (e.g. BASE_DEC|BASE_UNIT_STRING). + +There are several "common" unit name structures already defined in +epan/unit_strings.h, e.g. 'units_second_seconds'. Dissector authors may choose +to add the unit name structure there rather than locally in a dissector. + +-- Ranges +If the field has a numeric type that might logically fit in ranges of values +one can use a range_string struct. + +Thus a 'range_string' structure is a way to map ranges to strings. + + typedef struct _range_string { + uint32_t value_min; + uint32_t value_max; + const char *strptr; + } range_string; + +For fields of that type, you would declare an array of "range_string"s: + + static const range_string rvalstringname[] = { + { INTVAL_MIN1, INTVALMAX1, "Descriptive String 1" }, + { INTVAL_MIN2, INTVALMAX2, "Descriptive String 2" }, + { 0, 0, NULL } + }; + +If INTVAL_MIN equals INTVAL_MAX for a given entry the range_string +behavior collapses to the one of value_string. Note that each range_string +within the array is tested in order, so any 'catch-all' entries need to come +after specific individual entries. + +For FT_(U)INT* fields that need a 'range_string' struct, the 'strings' field +would be set to 'RVALS(rvalstringname)'. Furthermore, 'display' field must be +ORed with 'BASE_RANGE_STRING' (e.g. BASE_DEC|BASE_RANGE_STRING). + +-- Booleans +FT_BOOLEANs have a default map of 0 = "False", 1 (or anything else) = "True". +Sometimes it is useful to change the labels for boolean values (e.g., +to "Yes"/"No", "Fast"/"Slow", etc.). For these mappings, a struct called +true_false_string is used. + + typedef struct true_false_string { + char *true_string; + char *false_string; + } true_false_string; + +For Boolean fields for which "False" and "True" aren't the desired +labels, you would declare a "true_false_string"s: + + static const true_false_string boolstringname = { + "String for True", + "String for False" + }; + +Its two fields are pointers to the string representing truth, and the +string representing falsehood. For FT_BOOLEAN fields that need a +'true_false_string' struct, the 'strings' field would be set to +'TFS(&boolstringname)'. + +If the Boolean field is to be displayed as "False" or "True", the +'strings' field would be set to NULL. + +Wireshark predefines a whole range of ready made "true_false_string"s +in tfs.h, included via packet.h. + +-- Custom +Custom fields (BASE_CUSTOM) should use CF_FUNC(&custom_format_func) for the +'strings' field. + +-- Frame numbers +FT_FRAMENUMs can use the 'strings' field to indicate their purpose by +setting the field to 'FRAMENUM_TYPE(x)', where x is one of the values of +the ft_framenum_type enum: + + FT_FRAMENUM_NONE + FT_FRAMENUM_REQUEST + FT_FRAMENUM_RESPONSE + FT_FRAMENUM_ACK + FT_FRAMENUM_DUP_ACK + FT_FRAMENUM_RETRANS_PREV + FT_FRAMENUM_RETRANS_NEXT + +The packet list uses the value to determine the related packet symbol to draw. +Note that 'strings' field NULL is equal to FRAMENUM_TYPE(FT_FRAMENUM_NONE). + +-- Note to plugin authors +Data cannot get exported from DLLs. For this reason plugin authors cannot use +existing fieldconvert strings (e.g. from existing dissectors or those from +epan/unit_strings.h). Plugins must define value_strings, unit_name_strings, +range_strings and true_false_strings locally. + +bitmask (BITMASK) +----------------- +If the field is a bitfield, then the bitmask is the mask which will +leave only the bits needed to make the field when ANDed with a value. +The proto_tree routines will calculate 'bitshift' automatically +from 'bitmask', by finding the rightmost set bit in the bitmask. +This shift is applied before applying string mapping functions or +filtering. + +If the field is not a bitfield, then bitmask should be set to 0. + +blurb (FIELDDESCR) +------------------ +This is a string giving a proper description of the field. It should be +at least one grammatically complete sentence, or NULL in which case the +name field is used. (Please do not use ""). + +It is meant to provide a more detailed description of the field than the +name alone provides. This information will be used in the man page, and +in a future GUI display-filter creation tool. We might also add tooltips +to the labels in the GUI protocol tree, in which case the blurb would +be used as the tooltip text. + + +1.5.1 Field Registration. + +Protocol registration is handled by creating an instance of the +header_field_info struct (or an array of such structs), and +calling the registration function along with the registration ID of +the protocol that is the parent of the fields. Here is a complete example: + + static int proto_eg = -1; + static int hf_field_a = -1; + static int hf_field_b = -1; + + static hf_register_info hf[] = { + + { &hf_field_a, + { "Field A", "proto.field_a", FT_UINT8, BASE_HEX, NULL, + 0xf0, "Field A represents Apples", HFILL }}, + + { &hf_field_b, + { "Field B", "proto.field_b", FT_UINT16, BASE_DEC, VALS(vs), + 0x0, "Field B represents Bananas", HFILL }} + }; + + proto_eg = proto_register_protocol("Example Protocol", + "PROTO", "proto"); + proto_register_field_array(proto_eg, hf, array_length(hf)); + +Be sure that your array of hf_register_info structs is declared 'static', +since the proto_register_field_array() function does not create a copy +of the information in the array... it uses that static copy of the +information that the compiler created inside your array. Here's the +layout of the hf_register_info struct: + +typedef struct hf_register_info { + int *p_id; /* pointer to parent variable */ + header_field_info hfinfo; +} hf_register_info; + +Also be sure to use the handy array_length() macro found in packet.h +to have the compiler compute the array length for you at compile time. + +If you don't have any fields to register, do *NOT* create a zero-length +"hf" array; not all compilers used to compile Wireshark support them. +Just omit the "hf" array, and the "proto_register_field_array()" call, +entirely. + +It is OK to have header fields with a different format be registered with +the same abbreviation. For instance, the following is valid: + + static hf_register_info hf[] = { + + { &hf_field_8bit, /* 8-bit version of proto.field */ + { "Field (8 bit)", "proto.field", FT_UINT8, BASE_DEC, NULL, + 0x00, "Field represents FOO", HFILL }}, + + { &hf_field_32bit, /* 32-bit version of proto.field */ + { "Field (32 bit)", "proto.field", FT_UINT32, BASE_DEC, NULL, + 0x00, "Field represents FOO", HFILL }} + }; + +This way a filter expression can match a header field, irrespective of the +representation of it in the specific protocol context. This is interesting +for protocols with variable-width header fields. + +Note that the formats used must all belong to the same group as defined below: +- FT_INT8, FT_INT16, FT_INT24 and FT_INT32 +- FT_CHAR, FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, FT_IPXNET and FT_FRAMENUM +- FT_INT40, FT_INT48, FT_INT56 and FT_INT64 +- FT_UINT40, FT_UINT48, FT_UINT56, FT_UINT64 and FT_EUI64 +- FT_ABSOLUTE_TIME and FT_RELATIVE_TIME +- FT_STRING, FT_STRINGZ, FT_UINT_STRING, FT_STRINGZPAD, and FT_STRINGZTRUNC +- FT_FLOAT, FT_DOUBLE, FT_IEEE_11073_SFLOAT and FT_IEEE_11073_FLOAT +- FT_BYTES, FT_UINT_BYTES, FT_ETHER, FT_AX25, FT_VINES and FT_FCWWN +- FT_OID, FT_REL_OID and FT_SYSTEM_ID + +Any field not in a grouping above should *NOT* be used in duplicate field +abbreviations. The current code does not prevent it, but someday in the future +it might. + +The HFILL macro at the end of the struct will set reasonable default values +for internally used fields. + +1.5.2 Adding Items and Values to the Protocol Tree. + +A protocol item is added to an existing protocol tree with one of a +handful of proto_XXX_DO_YYY() functions. + +Subtrees can be made with the proto_item_add_subtree() function: + + item = proto_tree_add_item(....); + new_tree = proto_item_add_subtree(item, tree_type); + +This will add a subtree under the item in question; a subtree can be +created under an item made by any of the "proto_tree_add_XXX" functions, +so that the tree can be given an arbitrary depth. + +Subtree types are integers, assigned by +"proto_register_subtree_array()". To register subtree types, pass an +array of pointers to "gint" variables to hold the subtree type values to +"proto_register_subtree_array()": + + static int ett_eg = -1; + static int ett_field_a = -1; + + static int *ett[] = { + &ett_eg, + &ett_field_a + }; + + proto_register_subtree_array(ett, array_length(ett)); + +in your "register" routine, just as you register the protocol and the +fields for that protocol. + +The ett_ variables identify particular type of subtree so that if you expand +one of them, Wireshark keeps track of that and, when you click on +another packet, it automatically opens all subtrees of that type. +If you close one of them, all subtrees of that type will be closed when +you move to another packet. + +There are many functions that the programmer can use to add either +protocol or field labels to the proto_tree, for example: + + proto_item* + proto_tree_add_item(tree, id, tvb, start, length, encoding); + + proto_item* + proto_tree_add_item_ret_int(tree, id, tvb, start, length, encoding, + *retval); + + proto_item* + proto_tree_add_subtree(tree, tvb, start, length, idx, tree_item, + text); + + proto_item * + proto_tree_add_int_format_value(tree, id, tvb, start, length, + value, format, ...); + + proto_item * + proto_tree_add_checksum(proto_tree *tree, tvbuff_t *tvb, const unsigned offset, + const int hf_checksum, const int hf_checksum_status, + struct expert_field* bad_checksum_expert, packet_info *pinfo, + uint32_t computed_checksum, const unsigned encoding, const unsigned flags); + + proto_item * + proto_tree_add_bitmask(tree, tvb, start, header, ett, fields, + encoding); + + proto_item * + proto_tree_add_bits_item(tree, id, tvb, bit_offset, no_of_bits, + encoding); + +The 'tree' argument is the tree to which the item is to be added. The +'tvb' argument is the tvbuff from which the item's value is being +extracted; the 'start' argument is the offset from the beginning of that +tvbuff of the item being added, and the 'length' argument is the length, +in bytes, of the item, bit_offset is the offset in bits and no_of_bits +is the length in bits. + +The length of some items cannot be determined until the item has been +dissected; to add such an item, add it with a length of -1, and, when the +dissection is complete, set the length with 'proto_item_set_len()': + + void + proto_item_set_len(ti, length); + +The "ti" argument is the value returned by the call that added the item +to the tree, and the "length" argument is the length of the item. + +All available protocol tree functions are declared in epan/proto.h, with +their documentation. The details of these functions and their parameters +are described below. + +proto_tree_add_item() +--------------------- +proto_tree_add_item is used when you wish to do no special formatting. +The item added to the GUI tree will contain the name (as passed in the +proto_register_*() function) and a value. The value will be fetched +from the tvbuff by proto_tree_add_item(), based on the type of the field +and the encoding of the value as specified by the "encoding" argument. + +For FT_NONE, FT_BYTES, FT_ETHER, FT_IPv6, FT_IPXNET, FT_OID, FT_REL_OID, +FT_AX25, FT_VINES, FT_SYSTEM_ID, FT_FCWWN fields, and 'protocol' fields +the encoding is not relevant; the 'encoding' argument should be +ENC_NA (Not Applicable). + +For FT_UINT_BYTES fields, the byte order of the count must be specified +as well as the 'encoding' for bytes which should be ENC_NA, +i.e. ENC_LITTLE_ENDIAN|ENC_NA + +For integral, floating-point, Boolean, FT_GUID, and FT_EUI64 fields, +the encoding specifies the byte order of the value; the 'encoding' +argument should be ENC_LITTLE_ENDIAN if the value is little-endian +and ENC_BIG_ENDIAN if it is big-endian. + +For FT_IPv4 fields, the encoding also specifies the byte order of the +value. In almost all cases, the encoding is in network byte order, +hence big-endian, but in at least one protocol dissected by Wireshark, +at least one IPv4 address is byte-swapped, so it's in little-endian +order. + +For string fields, the encoding specifies the character set used for the +string and the way individual code points in that character set are +encoded. For FT_UINT_STRING fields, the byte order of the count must be +specified. For UTF-16, UCS-2, and UCS-4, the byte order of the encoding +must be specified, and optionally ENC_BOM can also be indicated to detect +an initial BYTE ORDER MARK (the specified value is used if the field does +not begin with a BOM.) For counted UTF-16, UCS-2, and UCS-4 strings, the +byte order of the count and the characters in the string must be the same, +unless a BOM overrides the value for the characters. In other cases the +string encoding has no endianness or the endianness is implicitly specified +and nothing should be used. The character encodings that are currently +supported are: + + ENC_ASCII - ASCII (currently treated as UTF-8; in the future, + all bytes with the 8th bit set will be treated as + errors) + ENC_UTF_8 - UTF-8-encoded Unicode + ENC_UTF_16 - UTF-16-encoded Unicode, with surrogate pairs + ENC_UCS_2 - UCS-2-encoded subset of Unicode, with no surrogate pairs + and thus no code points above 0xFFFF + ENC_UCS_4 - UCS-4-encoded Unicode (aka UTF-32) + ENC_WINDOWS_1250 - Windows-1250 code page + ENC_WINDOWS_1251 - Windows-1251 code page + ENC_WINDOWS_1252 - Windows-1252 code page + ENC_ISO_646_BASIC - ISO 646 "basic code table" + ENC_ISO_8859_1 - ISO 8859-1 + ENC_ISO_8859_2 - ISO 8859-2 + ENC_ISO_8859_3 - ISO 8859-3 + ENC_ISO_8859_4 - ISO 8859-4 + ENC_ISO_8859_5 - ISO 8859-5 + ENC_ISO_8859_6 - ISO 8859-6 + ENC_ISO_8859_7 - ISO 8859-7 + ENC_ISO_8859_8 - ISO 8859-8 + ENC_ISO_8859_9 - ISO 8859-9 + ENC_ISO_8859_10 - ISO 8859-10 + ENC_ISO_8859_11 - ISO 8859-11 + ENC_ISO_8859_13 - ISO 8859-13 + ENC_ISO_8859_14 - ISO 8859-14 + ENC_ISO_8859_15 - ISO 8859-15 + ENC_ISO_8859_16 - ISO 8859-16 + ENC_3GPP_TS_23_038_7BITS - GSM 7 bits alphabet as described + in 3GPP TS 23.038 + ENC_3GPP_TS_23_038_7BITS_UNPACKED - GSM 7 bits alphabet where each + 7 bit character occupies a distinct octet + ENC_ETSI_TS_102_221_ANNEX_A - Coding scheme for SIM cards with GSM 7 bit + alphabet, UCS-2 characters, or a mixture of the two as described + in ETSI TS 102 221 Annex A + ENC_EBCDIC - EBCDIC + ENC_EBCDIC_CP037 - EBCDIC code page 037 + ENC_EBCDIC_CP500 - EBCDIC code page 500 + ENC_MAC_ROMAN - MAC ROMAN + ENC_CP437 - DOS code page 437 + ENC_CP855 - DOS code page 855 + ENC_CP866 - DOS code page 866 + ENC_ASCII_7BITS - 7 bits ASCII + ENC_T61 - ITU T.61 + ENC_BCD_DIGITS_0_9 - packed BCD (one digit per nibble), digits 0-9 + ENC_KEYPAD_ABC_TBCD - keypad-with-a/b/c "telephony packed BCD" = 0-9, *, #, a, b, c + ENC_KEYPAD_BC_TBCD - keypad-with-B/C "telephony packed BCD" = 0-9, B, C, *, # + ENC_GB18030 - GB 18030 + ENC_EUC_KR - EUC-KR + ENC_DECT_STANDARD_8BITS - DECT standard 8 bit character set as defined in + ETSI EN 300 175-5 + ENC_DECT_STANDARD_4BITS_TBCD - DECT standard 4 bit character set "telephony + packet BCD" = 0-9, 0xb = SPACE + +Other encodings will be added in the future. + +For FT_ABSOLUTE_TIME fields, the encoding specifies the form in which +the time stamp is specified, as well as its byte order. The time stamp +encodings that are currently supported are: + + ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4 + bytes are seconds and the next 4 bytes are nanoseconds; for 12 + bytes, the first 8 bytes are seconds and the next 4 bytes are + nanoseconds; for 16 bytes, the first 8 bytes are seconds and + the next 8 bytes are nanoseconds. The seconds are seconds + since the UN*X epoch (1970-01-01 00:00:00 UTC). (I.e., a UN*X + struct timespec with a 4-byte or 8-byte time_t or a structure + with an 8-byte time_t and an 8-byte nanoseconds field.) + + ENC_TIME_NTP - 8 bytes; the first 4 bytes are seconds since the NTP + epoch (1900-01-01 00:00:00 GMT) and the next 4 bytes are 1/2^32's of + a second since that second. (I.e., a 64-bit count of 1/2^32's of a + second since the NTP epoch, with the upper 32 bits first and the + lower 32 bits second, even when little-endian.) + + ENC_TIME_TOD - 8 bytes, as a count of microseconds since the System/3x0 + and z/Architecture epoch (1900-01-01 00:00:00 GMT). + + ENC_TIME_RTPS - 8 bytes; the first 4 bytes are seconds since the UN*X + epoch and the next 4 bytes are 1/2^32's of a second since that + second. (I.e., it's the offspring of a mating between UN*X time and + NTP time). It's used by the Object Management Group's Real-Time + Publish-Subscribe Wire Protocol for the Data Distribution Service. + + ENC_TIME_SECS_USECS - 8 bytes; the first 4 bytes are seconds since the + UN*X epoch and the next 4 bytes are microseconds since that + second. (I.e., a UN*X struct timeval with a 4-byte time_t.) + + ENC_TIME_SECS - 4 to 8 bytes, representing a value in seconds since + the UN*X epoch. + + ENC_TIME_MSECS - 6 to 8 bytes, representing a value in milliseconds + since the UN*X epoch. + + ENC_TIME_USECS - 8 bytes, representing a value in microseconds since + the UN*X epoch. + + ENC_TIME_NSECS - 8 bytes, representing a value in nanoseconds since + the UN*X epoch. + + ENC_TIME_SECS_NTP - 4 bytes, representing a count of seconds since + the NTP epoch. + + ENC_TIME_RFC_3971 - 8 bytes, representing a count of 1/64ths of a + second since the UN*X epoch; see section 5.3.1 "Timestamp Option" + in RFC 3971. + + ENC_TIME_MSEC_NTP - 4-8 bytes, representing a count of milliseconds since + the NTP epoch. + + ENC_TIME_MIP6 - 8 bytes; the first 48 bits are seconds since the UN*X epoch + and the remaining 16 bits indicate the number of 1/65536's of a second + since that second. + + ENC_TIME_CLASSIC_MAC_OS_SECS - 4-8 bytes, representing a count of seconds + since January 1, 1904, 00:00:00 UTC. + +For FT_RELATIVE_TIME fields, the encoding specifies the form in which +the time stamp is specified, as well as its byte order. The time stamp +encodings that are currently supported are: + + ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4 + bytes are seconds and the next 4 bytes are nanoseconds; for 12 + bytes, the first 8 bytes are seconds and the next 4 bytes are + nanoseconds; for 16 bytes, the first 8 bytes are seconds and + the next 8 bytes are nanoseconds. + + ENC_TIME_SECS_USECS - 8 bytes; the first 4 bytes are seconds and the + next 4 bytes are microseconds. + + ENC_TIME_SECS - 4 to 8 bytes, representing a value in seconds. + + ENC_TIME_MSECS - 6 to 8 bytes, representing a value in milliseconds. + + ENC_TIME_USECS - 8 bytes, representing a value in microseconds. + + ENC_TIME_NSECS - 8 bytes, representing a value in nanoseconds. + +For other types, there is no support for proto_tree_add_item(). + +Now that definitions of fields have detailed information about bitfield +fields, you can use proto_tree_add_item() with no extra processing to +add bitfield values to your tree. Here's an example. Take the Format +Identifier (FID) field in the Transmission Header (TH) portion of the SNA +protocol. The FID is the high nibble of the first byte of the TH. The +FID would be registered like this: + + name = "Format Identifier" + abbrev = "sna.th.fid" + type = FT_UINT8 + display = BASE_HEX + strings = sna_th_fid_vals + bitmask = 0xf0 + +The bitmask contains the value which would leave only the FID if bitwise-ANDed +against the parent field, the first byte of the TH. + +The code to add the FID to the tree would be; + + proto_tree_add_item(bf_tree, hf_sna_th_fid, tvb, offset, 1, + ENC_BIG_ENDIAN); + +The definition of the field already has the information about bitmasking +and bitshifting, so it does the work of masking and shifting for us! +This also means that you no longer have to create value_string structs +with the values bitshifted. The value_string for FID looks like this, +even though the FID value is actually contained in the high nibble. +(You'd expect the values to be 0x0, 0x10, 0x20, etc.) + +/* Format Identifier */ +static const value_string sna_th_fid_vals[] = { + { 0x0, "SNA device <--> Non-SNA Device" }, + { 0x1, "Subarea Node <--> Subarea Node" }, + { 0x2, "Subarea Node <--> PU2" }, + { 0x3, "Subarea Node or SNA host <--> Subarea Node" }, + { 0x4, "?" }, + { 0x5, "?" }, + { 0xf, "Adjacent Subarea Nodes" }, + { 0, NULL } +}; + +The final implication of this is that display filters work the way you'd +naturally expect them to. You'd type "sna.th.fid == 0xf" to find Adjacent +Subarea Nodes. The user does not have to shift the value of the FID to +the high nibble of the byte ("sna.th.fid == 0xf0") as was necessary +in the past. + +proto_tree_add_item_ret_XXX() +------------------------------ +proto_tree_add_item_ret_XXX is used when you want the displayed value returned +for further processing only integer and unsigned integer types up to 32 bits are +supported usage of proper FT_ is checked. + +proto_tree_add_XXX_item() +--------------------- +proto_tree_add_XXX_item is used when you wish to do no special formatting, +but also either wish for the retrieved value from the tvbuff to be handed +back (to avoid doing tvb_get_...), and/or wish to have the value be decoded +from the tvbuff in a string-encoded format. + +The item added to the GUI tree will contain the name (as passed in the +proto_register_*() function) and a value. The value will be fetched +from the tvbuff, based on the type of the XXX name and the encoding of +the value as specified by the "encoding" argument. + +This function retrieves the value even if the passed-in tree param is NULL, +so that it can be used by dissectors at all times to both get the value +and set the tree item to it. + +Like other proto_tree_add functions, if there is a tree and the value cannot +be decoded from the tvbuff, then an expert info error is reported. For string +encoding, this means that a failure to decode the hex value from the string +results in an expert info error being added to the tree. + +For string-decoding, the passed-in encoding argument needs to specify the +string encoding (e.g., ENC_ASCII, ENC_UTF_8) as well as the format. For +some XXX types, the format is constrained - for example for the encoding format +for proto_tree_add_time_item() can only be one of the ENC_ISO_8601_* ones +or ENC_IMF_DATE_TIME. For proto_tree_add_bytes_item() it can only +be ENC_STR_HEX bit-or'ed with one or more of the ENC_SEP_* separator types. + +proto_tree_add_protocol_format() +-------------------------------- +proto_tree_add_protocol_format is used to add the top-level item for the +protocol when the dissector routine wants complete control over how the +field and value will be represented on the GUI tree. The ID value for +the protocol is passed in as the "id" argument; the rest of the +arguments are a "printf"-style format and any arguments for that format. +The caller must include the name of the protocol in the format; it is +not added automatically as in proto_tree_add_item(). + +proto_tree_add_none_format() +---------------------------- +proto_tree_add_none_format is used to add an item of type FT_NONE. +The caller must include the name of the field in the format; it is +not added automatically as in proto_tree_add_item(). + +proto_tree_add_bytes() +proto_tree_add_time() +proto_tree_add_ipxnet() +proto_tree_add_ipv4() +proto_tree_add_ipv6() +proto_tree_add_ether() +proto_tree_add_string() +proto_tree_add_boolean() +proto_tree_add_float() +proto_tree_add_double() +proto_tree_add_uint() +proto_tree_add_uint64() +proto_tree_add_int() +proto_tree_add_int64() +proto_tree_add_guid() +proto_tree_add_oid() +proto_tree_add_eui64() +------------------------ +These routines are used to add items to the protocol tree if either: + + the value of the item to be added isn't just extracted from the + packet data, but is computed from data in the packet; + + the value was fetched into a variable. + +The 'value' argument has the value to be added to the tree. + +NOTE: in all cases where the 'value' argument is a pointer, a copy is +made of the object pointed to; if you have dynamically allocated a +buffer for the object, that buffer will not be freed when the protocol +tree is freed - you must free the buffer yourself when you don't need it +any more. + +For proto_tree_add_bytes(), the 'value_ptr' argument is a pointer to a +sequence of bytes. + + +proto_tree_add_bytes_with_length() is similar to proto_tree_add_bytes, +except that the length is not derived from the tvb length. Instead, +the displayed data size is controlled by 'ptr_length'. + +For proto_tree_add_bytes_format() and proto_tree_add_bytes_format_value(), the +'value_ptr' argument is a pointer to a sequence of bytes or NULL if the bytes +should be taken from the given TVB using the given offset and length. + +For proto_tree_add_time(), the 'value_ptr' argument is a pointer to an +"nstime_t", which is a structure containing the time to be added; it has +'secs' and 'nsecs' members, giving the integral part and the fractional +part of a time in units of seconds, with 'nsecs' being the number of +nanoseconds. For absolute times, "secs" is a UNIX-style seconds since +January 1, 1970, 00:00:00 GMT value. + +For proto_tree_add_ipxnet(), the 'value' argument is a 32-bit IPX +network address. + +For proto_tree_add_ipv4(), the 'value' argument is a 32-bit IPv4 +address, in network byte order. + +For proto_tree_add_ipv6(), the 'value_ptr' argument is a pointer to a +128-bit IPv6 address. + +For proto_tree_add_ether(), the 'value_ptr' argument is a pointer to a +48-bit MAC address. + +For proto_tree_add_string(), the 'value_ptr' argument is a pointer to a +text string; this string must be NULL terminated even if the string in the +TVB is not (as may be the case with FT_STRINGs). + +For proto_tree_add_boolean(), the 'value' argument is a 32-bit integer. +It is masked and shifted as defined by the field info after which zero +means "false", and non-zero means "true". + +For proto_tree_add_float(), the 'value' argument is a 'float' in the +host's floating-point format. + +For proto_tree_add_double(), the 'value' argument is a 'double' in the +host's floating-point format. + +For proto_tree_add_uint(), the 'value' argument is a 32-bit unsigned +integer value, in host byte order. (This routine cannot be used to add +64-bit integers.) + +For proto_tree_add_uint64(), the 'value' argument is a 64-bit unsigned +integer value, in host byte order. + +For proto_tree_add_int(), the 'value' argument is a 32-bit signed +integer value, in host byte order. (This routine cannot be used to add +64-bit integers.) + +For proto_tree_add_int64(), the 'value' argument is a 64-bit signed +integer value, in host byte order. + +For proto_tree_add_guid(), the 'value_ptr' argument is a pointer to an +e_guid_t structure. + +For proto_tree_add_oid(), the 'value_ptr' argument is a pointer to an +ASN.1 Object Identifier. + +For proto_tree_add_eui64(), the 'value' argument is a 64-bit integer +value + +proto_tree_add_bytes_format() +proto_tree_add_time_format() +proto_tree_add_ipxnet_format() +proto_tree_add_ipv4_format() +proto_tree_add_ipv6_format() +proto_tree_add_ether_format() +proto_tree_add_string_format() +proto_tree_add_boolean_format() +proto_tree_add_float_format() +proto_tree_add_double_format() +proto_tree_add_uint_format() +proto_tree_add_uint64_format() +proto_tree_add_int_format() +proto_tree_add_int64_format() +proto_tree_add_guid_format() +proto_tree_add_oid_format() +proto_tree_add_eui64_format() +---------------------------- +These routines are used to add items to the protocol tree when the +dissector routine wants complete control over how the field and value +will be represented on the GUI tree. The argument giving the value is +the same as the corresponding proto_tree_add_XXX() function; the rest of +the arguments are a "printf"-style format and any arguments for that +format. The caller must include the name of the field in the format; it +is not added automatically as in the proto_tree_add_XXX() functions. + +proto_tree_add_bytes_format_value() +proto_tree_add_time_format_value() +proto_tree_add_ipxnet_format_value() +proto_tree_add_ipv4_format_value() +proto_tree_add_ipv6_format_value() +proto_tree_add_ether_format_value() +proto_tree_add_string_format_value() +proto_tree_add_boolean_format_value() +proto_tree_add_float_format_value() +proto_tree_add_double_format_value() +proto_tree_add_uint_format_value() +proto_tree_add_uint64_format_value() +proto_tree_add_int_format_value() +proto_tree_add_int64_format_value() +proto_tree_add_guid_format_value() +proto_tree_add_oid_format_value() +proto_tree_add_eui64_format_value() +------------------------------------ + +These routines are used to add items to the protocol tree when the +dissector routine wants complete control over how the value will be +represented on the GUI tree. The argument giving the value is the same +as the corresponding proto_tree_add_XXX() function; the rest of the +arguments are a "printf"-style format and any arguments for that format. +With these routines, unlike the proto_tree_add_XXX_format() routines, +the name of the field is added automatically as in the +proto_tree_add_XXX() functions; only the value is added with the format. +One use case for this would be to add a unit of measurement string to +the value of the field, however using BASE_UNIT_STRING in the hf_ +definition is now preferred. + +proto_tree_add_checksum() +---------------------------- +proto_tree_add_checksum is used to add a checksum field. The hf field +provided must be the correct size of the checksum (FT_UINT, FT_UINT16, +FT_UINT32, etc). Additional parameters are there to provide "status" +and expert info depending on whether the checksum matches the provided +value. The "status" and expert info can be used in cases except +where PROTO_CHECKSUM_NO_FLAGS is used. + +proto_tree_add_subtree() +--------------------- +proto_tree_add_subtree() is used to add a label to the GUI tree and create +a subtree for other fields. It will contain no value, so it is not searchable +in the display filter process. + +This should only be used for items with subtrees, which may not +have values themselves - the items in the subtree are the ones with values. + +For a subtree, the label on the subtree might reflect some of the items +in the subtree. This means the label can't be set until at least some +of the items in the subtree have been dissected. To do this, use +'proto_item_set_text()' or 'proto_item_append_text()': + + void + proto_item_set_text(proto_item *ti, ...); + + void + proto_item_append_text(proto_item *ti, ...); + +'proto_item_set_text()' takes as an argument the proto_item value returned by +one of the parameters in 'proto_tree_add_subtree()', a 'printf'-style format +string, and a set of arguments corresponding to '%' format items in that string, +and replaces the text for the item created by 'proto_tree_add_subtree()' with the result +of applying the arguments to the format string. + +'proto_item_append_text()' is similar, but it appends to the text for +the item the result of applying the arguments to the format string. + +For example, early in the dissection, one might do: + + subtree = proto_tree_add_subtree(tree, tvb, offset, length, ett, &ti, <label>); + +and later do + + proto_item_set_text(ti, "%s: %s", type, value); + +after the "type" and "value" fields have been extracted and dissected. +<label> would be a label giving what information about the subtree is +available without dissecting any of the data in the subtree. + +Note that an exception might be thrown when trying to extract the values of +the items used to set the label, if not all the bytes of the item are +available. Thus, one should create the item with text that is as +meaningful as possible, and set it or append additional information to +it as the values needed to supply that information are extracted. + +proto_tree_add_subtree_format() +---------------------------- +This is like proto_tree_add_subtree(), but uses printf-style arguments to +create the label; it is used to allow routines that take a printf-like +variable-length list of arguments to add a text item to the protocol +tree. + +proto_tree_add_bits_item() +-------------------------- +Adds a number of bits to the protocol tree which does not have to be byte +aligned. The offset and length is in bits. +Output format: + +..10 1010 10.. .... "value" (formatted as FT_ indicates). + +proto_tree_add_bits_ret_val() +----------------------------- +Works in the same way but also returns the value of the read bits. + +proto_tree_add_split_bits_item_ret_val() +----------------------------------- +Similar, but is used for items that are made of 2 or more smaller sets of bits (crumbs) +which are not contiguous, but are concatenated to form the actual value. The size of +the crumbs and the order of assembly are specified in an array of crumb_spec structures. + +proto_tree_add_split_bits_crumb() +--------------------------------- +Helper function for the above, to add text for each crumb as it is encountered. + +proto_tree_add_ts_23_038_7bits_item() +------------------------------------- +Adds a string of a given number of characters and encoded according to 3GPP TS 23.038 7 bits +alphabet. + +proto_tree_add_bitmask() et al. +------------------------------- +These functions provide easy to use and convenient dissection of many types of common +bitmasks into individual fields. + +header is an integer type and must be of type FT_[U]INT{8|16|24|32||40|48|56|64} and +represents the entire dissectable width of the bitmask. + +'header' and 'ett' are the hf fields and ett field respectively to create an +expansion that covers the bytes of the bitmask. + +'fields' is a NULL terminated array of pointers to hf fields representing +the individual subfields of the bitmask. These fields must either be integers +(usually of the same byte width as 'header') or of the type FT_BOOLEAN. +Each of the entries in 'fields' will be dissected as an item under the +'header' expansion and also IF the field is a boolean and IF it is set to 1, +then the name of that boolean field will be printed on the 'header' expansion +line. For integer type subfields that have a value_string defined, the +matched string from that value_string will be printed on the expansion line +as well. + +Example: (from the SCSI dissector) + static int hf_scsi_inq_peripheral = -1; + static int hf_scsi_inq_qualifier = -1; + static int hf_scsi_inq_devtype = -1; + ... + static int ett_scsi_inq_peripheral = -1; + ... + static int * const peripheral_fields[] = { + &hf_scsi_inq_qualifier, + &hf_scsi_inq_devtype, + NULL + }; + ... + /* Qualifier and DeviceType */ + proto_tree_add_bitmask(tree, tvb, offset, hf_scsi_inq_peripheral, + ett_scsi_inq_peripheral, peripheral_fields, ENC_BIG_ENDIAN); + offset+=1; + ... + { &hf_scsi_inq_peripheral, + {"Peripheral", "scsi.inquiry.peripheral", FT_UINT8, BASE_HEX, + NULL, 0, NULL, HFILL}}, + { &hf_scsi_inq_qualifier, + {"Qualifier", "scsi.inquiry.qualifier", FT_UINT8, BASE_HEX, + VALS (scsi_qualifier_val), 0xE0, NULL, HFILL}}, + { &hf_scsi_inq_devtype, + {"Device Type", "scsi.inquiry.devtype", FT_UINT8, BASE_HEX, + VALS (scsi_devtype_val), SCSI_DEV_BITS, NULL, HFILL}}, + ... + +Which provides very pretty dissection of this one byte bitmask. + + Peripheral: 0x05, Qualifier: Device type is connected to logical unit, Device Type: CD-ROM + 000. .... = Qualifier: Device type is connected to logical unit (0x00) + ...0 0101 = Device Type: CD-ROM (0x05) + +The proto_tree_add_bitmask_text() function is an extended version of +the proto_tree_add_bitmask() function. In addition, it allows to: +- Provide a leading text (e.g. "Flags: ") that will appear before + the comma-separated list of field values +- Provide a fallback text (e.g. "None") that will be appended if + no fields warranted a change to the top-level title. +- Using flags, specify which fields will affect the top-level title. + +There are the following flags defined: + + BMT_NO_APPEND - the title is taken "as-is" from the 'name' argument. + BMT_NO_INT - only boolean flags are added to the title. + BMT_NO_FALSE - boolean flags are only added to the title if they are set. + BMT_NO_TFS - only add flag name to the title, do not use true_false_string + +The proto_tree_add_bitmask_with_flags() function is an extended version +of the proto_tree_add_bitmask() function. It allows using flags to specify +which fields will affect the top-level title. The flags are the +same BMT_NO_* flags as used in the proto_tree_add_bitmask_text() function. + +The proto_tree_add_bitmask() behavior can be obtained by providing +both 'name' and 'fallback' arguments as NULL, and a flags of +(BMT_NO_FALSE|BMT_NO_TFS). + +The proto_tree_add_bitmask_len() function is intended for protocols where +bitmask length is permitted to vary, so a length is specified explicitly +along with the bitmask value. USB Video "bmControl" and "bControlSize" +fields follow this pattern. The primary intent of this is "forward +compatibility," enabling an interpreter coded for version M of a structure +to comprehend fields in version N of the structure, where N > M and +bControlSize increases from version M to version N. + +proto_tree_add_bitmask_len() is an extended version of proto_tree_add_bitmask() +that uses an explicitly specified (rather than inferred) length to control +dissection. Because of this, it may encounter two cases that +proto_tree_add_bitmask() and proto_tree_add_bitmask_text() may not: +- A length that exceeds that of the 'header' and bitmask subfields. + In this case the least-significant bytes of the bitmask are dissected. + An expert warning is generated in this case, because the dissection code + likely needs to be updated for a new revision of the protocol. +- A length that is shorter than that of the 'header' and bitmask subfields. + In this case, subfields whose data is fully present are dissected, + and other subfields are not. No warning is generated in this case, + because the dissection code is likely for a later revision of the protocol + than the packet it was called to interpret. + + +proto_item_set_generated() +-------------------------- +proto_item_set_generated is used to mark fields as not being read from the +captured data directly, but inferred from one or more values. + +One of the primary uses of this is the presentation of verification of +checksums. Every IP packet has a checksum line, which can present the result +of the checksum verification, if enabled in the preferences. The result is +presented as a subtree, where the result is enclosed in square brackets +indicating a generated field. + + Header checksum: 0x3d42 [correct] + [Checksum Status: Good (1)] + +proto_item_set_hidden() +----------------------- +proto_item_set_hidden is used to hide fields, which have already been added +to the tree, from being visible in the displayed tree. + +NOTE that creating hidden fields is actually quite a bad idea from a UI design +perspective because the user (someone who did not write nor has ever seen the +code) has no way of knowing that hidden fields are there to be filtered on +thus defeating the whole purpose of putting them there. A Better Way might +be to add the fields (that might otherwise be hidden) to a subtree where they +won't be seen unless the user opens the subtree--but they can be found if the +user wants. + +One use for hidden fields (which would be better implemented using visible +fields in a subtree) follows: The caller may want a value to be +included in a tree so that the packet can be filtered on this field, but +the representation of that field in the tree is not appropriate. An +example is the token-ring routing information field (RIF). The best way +to show the RIF in a GUI is by a sequence of ring and bridge numbers. +Rings are 3-digit hex numbers, and bridges are single hex digits: + + RIF: 001-A-013-9-C0F-B-555 + +In the case of RIF, the programmer should use a field with no value and +use proto_tree_add_none_format() to build the above representation. The +programmer can then add the ring and bridge values, one-by-one, with +proto_tree_add_item() and hide them with proto_item_set_hidden() so that the +user can then filter on or search for a particular ring or bridge. Here's a +skeleton of how the programmer might code this. + + char *rif; + rif = create_rif_string(...); + + proto_tree_add_none_format(tree, hf_tr_rif_label, ..., "RIF: %s", rif); + + for(i = 0; i < num_rings; i++) { + proto_item *pi; + + pi = proto_tree_add_item(tree, hf_tr_rif_ring, ..., + ENC_BIG_ENDIAN); + proto_item_set_hidden(pi); + } + for(i = 0; i < num_rings - 1; i++) { + proto_item *pi; + + pi = proto_tree_add_item(tree, hf_tr_rif_bridge, ..., + ENC_BIG_ENDIAN); + proto_item_set_hidden(pi); + } + +The logical tree has these items: + + hf_tr_rif_label, text="RIF: 001-A-013-9-C0F-B-555", value = NONE + hf_tr_rif_ring, hidden, value=0x001 + hf_tr_rif_bridge, hidden, value=0xA + hf_tr_rif_ring, hidden, value=0x013 + hf_tr_rif_bridge, hidden, value=0x9 + hf_tr_rif_ring, hidden, value=0xC0F + hf_tr_rif_bridge, hidden, value=0xB + hf_tr_rif_ring, hidden, value=0x555 + +GUI or print code will not display the hidden fields, but a display +filter or "packet grep" routine will still see the values. The possible +filter is then possible: + + tr.rif_ring eq 0x013 + +proto_item_set_url +------------------ +proto_item_set_url is used to mark fields as containing a URL. This can only +be done with fields of type FT_STRING(Z). If these fields are presented they +are underlined, as could be done in a browser. These fields are sensitive to +clicks as well, launching the configured browser with this URL as parameter. + +1.6 Utility routines. + +1.6.1 val_to_str, val_to_str_const, try_val_to_str and try_val_to_str_idx + +A dissector may need to convert a value to a string, using a +'value_string' structure, by hand, rather than by declaring a field with +an associated 'value_string' structure; this might be used, for example, +to generate a COL_INFO line for a frame. + +val_to_str() handles the most common case: + + const char* + val_to_str(uint32_t val, const value_string *vs, const char *fmt) + +If the value 'val' is found in the 'value_string' table pointed to by +'vs', 'val_to_str' will return the corresponding string; otherwise, it +will use 'fmt' as an 'sprintf'-style format, with 'val' as an argument, +to generate a string, and will return a pointer to that string. +You can use it in a call to generate a COL_INFO line for a frame such as + + col_add_fstr(COL_INFO, ", %s", val_to_str(val, table, "Unknown %d")); + +If you don't need to display 'val' in your fmt string, you can use +val_to_str_const() which just takes a string constant instead and returns it +unmodified when 'val' isn't found. + +If you need to handle the failure case in some custom way, try_val_to_str() +will return NULL if val isn't found: + + const char* + try_val_to_str(uint32_t val, const value_string *vs) + +Note that, you must check whether 'try_val_to_str()' returns NULL, and arrange +that its return value not be dereferenced if it's NULL. 'try_val_to_str_idx()' +behaves similarly, except it also returns an index into the value_string array, +or -1 if 'val' was not found. + +The *_ext functions are "extended" versions of those already described. They +should be used for large value-string arrays which contain many entries. They +implement value to string conversions which will do either a direct access or +a binary search of the value string array if possible. See +"Extended Value Strings" under section 1.6 "Constructing the protocol tree" for +more information. + +See epan/value_string.h for detailed information on the various value_string +functions. + +To handle 64-bit values, there are an equivalent set of functions. These are: + + const char * + val64_to_str(const uint64_t val, const val64_string *vs, const char *fmt) + + const char * + val64_to_str_const(const uint64_t val, const val64_string *vs, const char *unknown_str); + + const char * + try_val64_to_str(const uint64_t val, const val64_string *vs); + + const char * + try_val64_to_str_idx(const uint64_t val, const val64_string *vs, int *idx); + + +1.6.2 rval_to_str, try_rval_to_str and try_rval_to_str_idx + +A dissector may need to convert a range of values to a string, using a +'range_string' structure. + +Most of the same functions exist as with regular value_strings (see section +1.6.1) except with the names 'rval' instead of 'val'. + + +1.7 Calling Other Dissectors. + +As each dissector completes its portion of the protocol analysis, it +is expected to create a new tvbuff of type TVBUFF_SUBSET which +contains the payload portion of the protocol (that is, the bytes +that are relevant to the next dissector). + +To create a new TVBUFF_SUBSET that begins at a specified offset in a +parent tvbuff, and runs to the end of the parent tvbuff, the routine +tvbuff_new_subset_remaining() is used: + + next_tvb = tvb_new_subset_remaining(tvb, offset); + +Where: + tvb is the tvbuff that the dissector has been working on. It + can be a tvbuff of any type. + + next_tvb is the new TVBUFF_SUBSET. + + offset is the byte offset of 'tvb' at which the new tvbuff + should start. The first byte is the byte at offset 0. + +To create a new TVBUFF_SUBSET that begins at a specified offset in a +parent tvbuff, with a specified number of bytes in the payload, the +routine tvbuff_new_subset_length() is used: + + next_tvb = tvb_new_subset_length(tvb, offset, reported_length); + +Where: + tvb is the tvbuff that the dissector has been working on. It + can be a tvbuff of any type. + + next_tvb is the new TVBUFF_SUBSET. + + offset is the byte offset of 'tvb' at which the new tvbuff + should start. The first byte is the byte at offset 0. + + reported_length is the number of bytes that the current protocol + says should be in the payload. + +In the few cases where the number of bytes available in the new subset +must be explicitly specified, rather than being calculated based on the +number of bytes in the payload, the routine tvb_new_subset_length_caplen() +is used: + + next_tvb = tvb_new_subset_length_caplen(tvb, offset, length, reported_length); + +Where: + tvb is the tvbuff that the dissector has been working on. It + can be a tvbuff of any type. + + next_tvb is the new TVBUFF_SUBSET. + + offset is the byte offset of 'tvb' at which the new tvbuff + should start. The first byte is the byte at offset 0. + + length is the number of bytes in the new TVBUFF_SUBSET. A length + argument of -1 says to use as many bytes as are available in + 'tvb'. + + reported_length is the number of bytes that the current protocol + says should be in the payload. A reported_length of -1 says that + the protocol doesn't say anything about the size of its payload. + +To call a dissector you need to get the handle of the dissector using +find_dissector(), passing it the string name of the dissector. The setting +of the handle is usually done once at startup during the proto_reg_handoff +function within the calling dissector. + +1.7.1 Dissector Tables + +Another way to call a subdissector is to setup a dissector table. A dissector +table is a list of subdissectors grouped by a common identifier (integer or +string) in a dissector. Subdissectors will register themselves with the dissector +table using their unique identifier using one of the following APIs: + + void dissector_add_uint(const char *abbrev, const uint32_t pattern, + dissector_handle_t handle); + + void dissector_add_uint_range(const char *abbrev, struct epan_range *range, + dissector_handle_t handle); + + void dissector_add_string(const char *name, const char *pattern, + dissector_handle_t handle); + + void dissector_add_for_decode_as(const char *name, + dissector_handle_t handle); + + dissector_add_for_decode_as doesn't add a unique identifier in the dissector + table, but it lets the user add it from the command line or, in Wireshark, + through the "Decode As" UI. + +Then when the dissector hits the common identifier field, it will use one of the +following APIs to invoke the subdissector: + + int dissector_try_uint(dissector_table_t sub_dissectors, + const uint32_t uint_val, tvbuff_t *tvb, packet_info *pinfo, + proto_tree *tree); + + int dissector_try_uint_new(dissector_table_t sub_dissectors, + const uint32_t uint_val, tvbuff_t *tvb, packet_info *pinfo, + proto_tree *tree, const bool add_proto_name, void *data); + + int dissector_try_string(dissector_table_t sub_dissectors, const char *string, + tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data); + +These pass a subset of the remaining packet (typically the rest of the +packet) for the dissector table to determine which subdissector is called. +This allows dissection of a packet to be expanded outside of dissector without +having to modify the dissector directly. + + +1.8 Editing CMakeLists.txt to add your dissector. + +To arrange that your dissector will be built as part of Wireshark, you +must add the name of the source file for your dissector to the DISSECTOR_SRC +section of epan/dissectors/CMakeLists.txt + + +1.9 Using the git source code tree. + + See <https://www.wireshark.org/develop.html> + + +1.10 Submitting code for your new dissector. + + See <https://www.wireshark.org/docs/wsdg_html_chunked/ChSrcContribute.html> + and <https://gitlab.com/wireshark/wireshark/-/wikis/Development/SubmittingPatches>. + + - VERIFY that your dissector code does not use prohibited or deprecated APIs + as follows: + perl <wireshark_root>/tools/checkAPIs.pl <source-filename(s)> + + - VERIFY that your dissector code does not contain any header field related + problems: + perl <wireshark_root>/tools/checkhf.pl <source-filename(s)> + + - VERIFY that your dissector code does not contain any display filter related + problems: + perl <wireshark_root>/tools/checkfiltername.pl <source-filename(s)> + + - CHECK your dissector with CppCheck (http://cppcheck.sourceforge.net/) using + Wireshark's customized configuration. This is particularly important on + Windows, since Microsoft's compiler warnings are quite thin: + ./tools/cppcheck/cppcheck.sh <source-filename(s)> + + - TEST YOUR DISSECTOR BEFORE SUBMITTING IT. + Use fuzz-test.sh and/or randpkt against your dissector. These are + described at <https://gitlab.com/wireshark/wireshark/-/wikis/FuzzTesting>. + + - Subscribe to <mailto:wireshark-dev[AT]wireshark.org> by sending an email to + <mailto:wireshark-dev-request[AT]wireshark.org?body="help"> or visiting + <https://www.wireshark.org/lists/>. + + - 'git diff' to verify all your changes look good. + + - 'git add' all the files you changed. + + - 'git commit' to commit (locally) your changes. First line of commit message + should be a summary of the changes followed by an empty line and a more + verbose description. + + - 'git push downstream HEAD' to push the changes to GitLab. (This assumes + that you have a remote named "downstream" that points to a fork of + https://gitlab.com/wireshark/wireshark.) + + - Create a Wiki page on the protocol at <https://gitlab.com/wireshark/editor-wiki>. + (You'll need to request access to https://gitlab.com/wireshark/wiki-editors.) + A template is provided so it is easy to setup in a consistent style. + See: <https://gitlab.com/wireshark/wireshark/-/wikis/HowToEdit> + and <https://gitlab.com/wireshark/wireshark/-/wikis/ProtocolReference> + + - If possible, add sample capture files to the sample captures page at + <https://gitlab.com/wireshark/wireshark/-/wikis/SampleCaptures>. These + files are used by the automated build system for fuzz testing. + + - If you don't think the wiki is the right place for your sample capture, + submit a bug report to the Wireshark issue database, found at + <https://gitlab.com/wireshark/wireshark/-/issues>, qualified as an + enhancement and attach your sample capture there. Normally a new + dissector won't be accepted without a sample capture! If you open a + bug be sure to cross-link your GitLab merge request. + +2. Advanced dissector topics. + +2.1 Introduction. + +Some of the advanced features are being worked on constantly. When using them +it is wise to check the relevant header and source files for additional details. + +2.2 Following "conversations". + +In Wireshark a conversation is defined as a series of data packets between two +address:port combinations. A conversation is not sensitive to the direction of +the packet. The same conversation will be returned for a packet bound from +ServerA:1000 to ClientA:2000 and the packet from ClientA:2000 to ServerA:1000. + +2.2.1 Conversation Routines + +There are nine routines that you will use to work with a conversation: +conversation_new, conversation_new_full, find_conversation, +find_conversation_full, find_or_create_conversation, +conversation_add_proto_data, conversation_get_proto_data, +conversation_delete_proto_data, and conversation_set_dissector. + +2.2.1.1 The conversation_init function. + +This is an internal routine for the conversation code. As such you +will not have to call this routine. Just be aware that this routine is +called at the start of each capture and before the packets are filtered +with a display filter. The routine will destroy all stored +conversations. This routine does NOT clean up any data pointers that are +passed in the conversation_add_proto_data 'data' variable. You are +responsible for this clean up if you pass a malloc'ed pointer +in this variable. + +See item 2.2.1.5 for more information about use of the 'data' pointer. + + +2.2.1.2 The conversation_new function. + +This routine will create a new conversation based upon two address/port +pairs. If you want to associate with the conversation a pointer to a +private data structure you must use the conversation_add_proto_data +function. The ctype variable is used to differentiate between +conversations over different protocols, i.e. TCP and UDP. The options +variable is used to define a conversation that will accept any destination +address and/or port. Set options = 0 if the destination port and address +are known when conversation_new is called. See section 2.4 for more +information on usage of the options parameter. + +The conversation_new prototype: + conversation_t *conversation_new(uint32_t setup_frame, address *addr1, + address *addr2, conversation_type ctype, uint32_t port1, uint32_t port2, + unsigned options); + +Where: + uint32_t setup_frame = The lowest numbered frame for this conversation + address* addr1 = first data packet address + address* addr2 = second data packet address + conversation_type ctype = conversation type, defined in conversation.h + uint32_t port1 = first data packet port + uint32_t port2 = second data packet port + unsigned options = conversation options, NO_ADDR2 and/or NO_PORT2 + +setup_frame indicates the first frame for this conversation, and is used to +distinguish multiple conversations with the same addr1/port1 and addr2/port2 +pair that occur within the same capture session. + +"addr1" and "port1" are the first address/port pair; "addr2" and "port2" +are the second address/port pair. A conversation doesn't have source +and destination address/port pairs - packets in a conversation go in +both directions - so "addr1"/"port1" may be the source or destination +address/port pair; "addr2"/"port2" would be the other pair. + +If NO_ADDR2 is specified, the conversation is set up so that a +conversation lookup will match only the "addr1" address; if NO_PORT2 is +specified, the conversation is set up so that a conversation lookup will +match only the "port1" port; if both are specified, i.e. +NO_ADDR2|NO_PORT2, the conversation is set up so that the lookup will +match only the "addr1"/"port1" address/port pair. This can be used if a +packet indicates that, later in the capture, a conversation will be +created using certain addresses and ports, in the case where the packet +doesn't specify the addresses and ports of both sides. + +2.2.1.3 The conversation_new_full function. + +This routine will create a new conversation based upon an arbitrary +lists of elements. Elements can be addresses, strings, unsigned +integers, or unsigned 64-bit integers. Unlike conversation_new, element +lists are matched strictly; wildcards aren't (yet) supported. + +The conversation_new_full prototype: + conversation_t *conversation_new_full(const uint32_t setup_frame, + conversation_element_t *elements); + +Where: + uint32_t setup_frame = The lowest numbered frame for + this conversation + conversation_element_t *elements = An array of data types and + values which identify this conversation. The array MUST be + terminated with a CE_ENDPOINT element. + +2.2.1.4 The find_conversation function. + +Call this routine to look up a conversation. If no conversation is found, +the routine will return a NULL value. + +The find_conversation prototype: + + conversation_t *find_conversation(uint32_t frame_num, address *addr_a, + address *addr_b, conversation_type ctype, uint32_t port_a, uint32_t port_b, + unsigned options); + +Where: + uint32_t frame_num = a frame number to match + address* addr_a = first address + address* addr_b = second address + conversation_type ctype = conversation type + uint32_t port_a = first data packet port + uint32_t port_b = second data packet port + unsigned options = conversation options, NO_ADDR_B and/or NO_PORT_B + +frame_num is a frame number to match. The conversation returned is where + (frame_num >= conversation->setup_frame + && frame_num < conversation->next->setup_frame) +Suppose there are a total of 3 conversations (A, B, and C) that match +addr_a/port_a and addr_b/port_b, where the setup_frame used in +conversation_new() for A, B and C are 10, 50, and 100 respectively. The +frame_num passed in find_conversation is compared to the setup_frame of each +conversation. So if (frame_num >= 10 && frame_num < 50), conversation A is +returned. If (frame_num >= 50 && frame_num < 100), conversation B is returned. +If (frame_num >= 100) conversation C is returned. + +"addr_a" and "port_a" are the first address/port pair; "addr_b" and +"port_b" are the second address/port pair. Again, as a conversation +doesn't have source and destination address/port pairs, so +"addr_a"/"port_a" may be the source or destination address/port pair; +"addr_b"/"port_b" would be the other pair. The search will match the +"a" address/port pair against both the "1" and "2" address/port pairs, +and match the "b" address/port pair against both the "2" and "1" +address/port pairs; you don't have to worry about which side the "a" or +"b" pairs correspond to. + +If the NO_ADDR_B flag was specified to "find_conversation()", the +"addr_b" address will be treated as matching any "wildcarded" address; +if the NO_PORT_B flag was specified, the "port_b" port will be treated +as matching any "wildcarded" port. If both flags are specified, i.e. +NO_ADDR_B|NO_PORT_B, the "addr_b" address will be treated as matching +any "wildcarded" address and the "port_b" port will be treated as +matching any "wildcarded" port. + +2.2.1.5 The find_conversation_full function. + +Call this routine to look up a conversation based on an element list. If +no conversation is found, the routine will return a NULL value. + +The find_conversation_full prototype: + + conversation_t *find_conversation_full(uint32_t frame_num, + conversation_element_t *elements); + +Where: + uint32_t setup_frame = The lowest numbered frame for + this conversation + conversation_element_t *elements = An array of data types and + values which identify this conversation. The array MUST be + terminated with a CE_ENDPOINT element. + +2.2.1.6 The find_conversation_pinfo function. + +This convenience function will find an existing conversation (by calling +find_conversation()) + +The find_conversation_pinfo prototype: + + extern conversation_t *find_conversation_pinfo(packet_info *pinfo, + const unsigned options); + +Where: + packet_info *pinfo = the packet_info structure + const unsigned options = conversation options, NO_ADDR_B and/or NO_PORT_B + +The frame number and the addresses necessary for find_conversation() are +taken from the addresses and ports in the pinfo structure, +pinfo->conv_addr_port_endpoints if pinfo->use_conv_addr_port_endpoints is set, +or pinfo->conv_elements if it is set. + +2.2.1.7 The find_or_create_conversation function. + +This convenience function will find an existing conversation (by calling +find_conversation()) and, if a conversation does not already exist, create a +new conversation by calling conversation_new(). + +The find_or_create_conversation prototype: + + extern conversation_t *find_or_create_conversation(packet_info *pinfo); + +Where: + packet_info *pinfo = the packet_info structure + +The frame number and the addresses necessary for find_conversation() and +conversation_new() are taken from the pinfo structure (as is commonly done) +and no 'options' are used. + +2.2.1.8 The conversation_add_proto_data function. + +Once you have created a conversation with conversation_new, you can +associate data with it using this function. + +The conversation_add_proto_data prototype: + + void conversation_add_proto_data(conversation_t *conv, int proto, + void *proto_data); + +Where: + conversation_t *conv = the conversation in question + int proto = registered protocol number + void *data = dissector data structure + +"conversation" is the value returned by conversation_new. "proto" is a +unique protocol number created with proto_register_protocol. Protocols +are typically registered in the proto_register_XXXX section of your +dissector. "data" is a pointer to the data you wish to associate with the +conversation. "data" usually points to "wmem_alloc'd" memory; the +memory will be automatically freed each time a new dissection begins +and thus need not be managed (freed) by the dissector. +Using the protocol number allows several dissectors to +associate data with a given conversation. + + +2.2.1.9 The conversation_get_proto_data function. + +After you have located a conversation with find_conversation, you can use +this function to retrieve any data associated with it. + +The conversation_get_proto_data prototype: + + void *conversation_get_proto_data(conversation_t *conv, int proto); + +Where: + conversation_t *conv = the conversation in question + int proto = registered protocol number + +"conversation" is the conversation created with conversation_new. "proto" +is a unique protocol number created with proto_register_protocol, +typically in the proto_register_XXXX portion of a dissector. The function +returns a pointer to the data requested, or NULL if no data was found. + + +2.2.1.10 The conversation_delete_proto_data function. + +After you are finished with a conversation, you can remove your association +with this function. Please note that ONLY the conversation entry is +removed. If you have allocated any memory for your data (other than with wmem_alloc), + you must free it as well. + +The conversation_delete_proto_data prototype: + + void conversation_delete_proto_data(conversation_t *conv, int proto); + +Where: + conversation_t *conv = the conversation in question + int proto = registered protocol number + +"conversation" is the conversation created with conversation_new. "proto" +is a unique protocol number created with proto_register_protocol, +typically in the proto_register_XXXX portion of a dissector. + +2.2.1.11 The conversation_set_dissector function + +This function sets the protocol dissector to be invoked whenever +conversation parameters (addresses, port_types, ports, etc) are matched +during the dissection of a packet. + +The conversation_set_dissector prototype: + + void conversation_set_dissector(conversation_t *conversation, const dissector_handle_t handle); + +Where: + conversation_t *conv = the conversation in question + const dissector_handle_t handle = the dissector handle. + + +2.2.2 Using timestamps relative to the conversation + +There is a framework to calculate timestamps relative to the start of the +conversation. First of all the timestamp of the first packet that has been +seen in the conversation must be kept in the protocol data to be able +to calculate the timestamp of the current packet relative to the start +of the conversation. The timestamp of the last packet that was seen in the +conversation should also be kept in the protocol data. This way the +delta time between the current packet and the previous packet in the +conversation can be calculated. + +So add the following items to the struct that is used for the protocol data: + + nstime_t ts_first; + nstime_t ts_prev; + +The ts_prev value should only be set during the first run through the +packets (ie PINFO_FD_VISITED(pinfo) is false). + +Next step is to use the per-packet information (described in section 2.5) +to keep the calculated delta timestamp, as it can only be calculated +on the first run through the packets. This is because a packet can be +selected in random order once the whole file has been read. + +After calculating the conversation timestamps, it is time to put them in +the appropriate columns with the function 'col_set_time' (described in +section 1.5.9). The column used for relative timestamps is: + +COL_REL_TIME, /* Delta time to last frame in conversation */ + +Last but not least, there MUST be a preference in each dissector that +uses conversation timestamps that makes it possible to enable and +disable the calculation of conversation timestamps. The main argument +for this is that a higher level conversation is able to overwrite +the values of lower level conversations in these two columns. Being +able to actively select which protocols may overwrite the conversation +timestamp columns gives the user the power to control these columns. +(A second reason is that conversation timestamps use the per-packet +data structure which uses additional memory, which should be avoided +if these timestamps are not needed) + +Have a look at the differences to packet-tcp.[ch] in SVN 22966 and +SVN 23058 to see the implementation of conversation timestamps for +the tcp-dissector. + + +2.2.3 The example conversation code using wmem_file_scope memory. + +For a conversation between two IP addresses and ports you can use this as an +example. This example uses wmem_alloc() with wmem_file_scope() to allocate +memory and stores the data pointer in the conversation 'data' variable. + +/************************ Global values ************************/ + +/* define your structure here */ +typedef struct { + +} my_entry_t; + +/* Registered protocol number */ +static int my_proto = -1; + +/********************* in the dissector routine *********************/ + +/* the local variables in the dissector */ + +conversation_t *conversation; +my_entry_t *data_ptr; + + +/* look up the conversation */ + +conversation = find_conversation(pinfo->num, &pinfo->src, &pinfo->dst, + conversation_pt_to_conversation_type(pinfo->ptype), + pinfo->srcport, pinfo->destport, 0); + +/* if conversation found get the data pointer that you stored */ +if (conversation) + data_ptr = (my_entry_t*)conversation_get_proto_data(conversation, my_proto); +else { + + /* new conversation create local data structure */ + + data_ptr = wmem_alloc(wmem_file_scope(), sizeof(my_entry_t)); + + /*** add your code here to setup the new data structure ***/ + + /* create the conversation with your data pointer */ + + conversation = conversation_new(pinfo->num, &pinfo->src, &pinfo->dst, + conversation_pt_to_conversation_type(pinfo->ptype), + pinfo->srcport, pinfo->destport, 0); + conversation_add_proto_data(conversation, my_proto, (void *)data_ptr); +} + +/* at this point the conversation data is ready */ + +/***************** in the protocol register routine *****************/ + +my_proto = proto_register_protocol("My Protocol", "My Protocol", "my_proto"); + + +2.2.4 An example conversation code that starts at a specific frame number. + +Sometimes a dissector has determined that a new conversation is needed that +starts at a specific frame number, when a capture session encompasses multiple +conversation that reuse the same src/dest ip/port pairs. You can use the +conversation->setup_frame returned by find_conversation with +pinfo->num to determine whether or not there already exists a conversation +that starts at the specific frame number. + +/* in the dissector routine */ + + conversation = find_conversation(pinfo->num, &pinfo->src, &pinfo->dst, + conversation_pt_to_conversation_type(pinfo->ptype), + pinfo->srcport, pinfo->destport, 0); + if (conversation == NULL || (conversation->setup_frame != pinfo->num)) { + /* It's not part of any conversation or the returned + * conversation->setup_frame doesn't match the current frame + * create a new one. + */ + conversation = conversation_new(pinfo->num, &pinfo->src, &pinfo->dst, + conversation_pt_to_conversation_type(pinfo->ptype), + pinfo->srcport, pinfo->destport, 0); + } + + +2.2.5 The example conversation code using conversation index field. + +Sometimes the conversation isn't enough to define a unique data storage +value for the network traffic. For example if you are storing information +about requests carried in a conversation, the request may have an +identifier that is used to define the request. In this case the +conversation and the identifier are required to find the data storage +pointer. You can use the conversation data structure index value to +uniquely define the conversation. + +See packet-afs.c for an example of how to use the conversation index. In +this dissector multiple requests are sent in the same conversation. To store +information for each request the dissector has an internal hash table based +upon the conversation index and values inside the request packets. + + + /* in the dissector routine */ + + /* to find a request value, first lookup conversation to get index */ + /* then used the conversation index, and request data to find data */ + /* in the local hash table */ + + conversation = find_or_create_conversation(pinfo); + + request_key.conversation = conversation->index; + request_key.service = pntoh16(&rxh->serviceId); + request_key.callnumber = pntoh32(&rxh->callNumber); + + request_val = (struct afs_request_val *)g_hash_table_lookup( + afs_request_hash, &request_key); + + /* only allocate a new hash element when it's a request */ + opcode = 0; + if (!request_val && !reply) + { + new_request_key = wmem_alloc(wmem_file_scope(), sizeof(struct afs_request_key)); + *new_request_key = request_key; + + request_val = wmem_alloc(wmem_file_scope(), sizeof(struct afs_request_val)); + request_val -> opcode = pntoh32(&afsh->opcode); + opcode = request_val->opcode; + + g_hash_table_insert(afs_request_hash, new_request_key, + request_val); + } + + + +2.3 Dynamic conversation dissector registration. + + +NOTE: This sections assumes that all information is available to + create a complete conversation, source port/address and + destination port/address. If either the destination port or + address is known, see section 2.4 Dynamic server port dissector + registration. + +For protocols that negotiate a secondary port connection, for example +packet-msproxy.c, a conversation can install a dissector to handle +the secondary protocol dissection. After the conversation is created +for the negotiated ports use the conversation_set_dissector to define +the dissection routine. +Before we create these conversations or assign a dissector to them we should +first check that the conversation does not already exist and if it exists +whether it is registered to our protocol or not. +We should do this because it is uncommon but it does happen that multiple +different protocols can use the same socketpair during different stages of +an application cycle. By keeping track of the frame number a conversation +was started in Wireshark can still tell these different protocols apart. + +The second argument to conversation_set_dissector is a dissector handle, +which is created with a call to create_dissector_handle, +register_dissector, or register_dissector_with_description. + +register_dissector_with_description takes as arguments a string giving a name +for the dissector, a string with a human-readable summary of the dissector, a +pointer to the dissector function, and a protocol ID as returned by +proto_register_protocol. + +register_dissector takes as arguments a string giving a name for the +dissector, a pointer to the dissector function, and a protocol ID +as returned by proto_register_protocol. + +create_dissector_handle takes as arguments a pointer to the dissector +function and a protocol ID as returned by proto_register_protocol. +It is recommended to use one of the above two functions instead of this one, +since they allow the dissector to be referenced by name from the command line, +by other dissectors via calls to find_dissector, etc. + +The protocol ID is the ID for the protocol dissected by the function. +The function will not be called if the protocol has been disabled by the +user; instead, the data for the protocol will be dissected as raw data. + +An example - + +/* the handle for the dynamic dissector * +static dissector_handle_t sub_dissector_handle; + +/* prototype for the dynamic dissector */ +static void sub_dissector(tvbuff_t *tvb, packet_info *pinfo, + proto_tree *tree); + +/* in the main protocol dissector, where the next dissector is setup */ + +/* if conversation has a data field, create it and load structure */ + +/* First check if a conversation already exists for this + socketpair +*/ + conversation = find_conversation(pinfo->num, + &pinfo->src, &pinfo->dst, conversation_type, + src_port, dst_port, 0); + +/* If there is no such conversation, or if there is one but for + someone else's protocol then we just create a new conversation + and assign our protocol to it. +*/ + if ( (conversation == NULL) || + (conversation->dissector_handle != sub_dissector_handle) ) { + new_conv_info = wmem_alloc(wmem_file_scope(), sizeof(struct _new_conv_info)); + new_conv_info->data1 = value1; + +/* create the conversation for the dynamic port */ + conversation = conversation_new(pinfo->num, + &pinfo->src, &pinfo->dst, protocol, + src_port, dst_port, new_conv_info, 0); + +/* set the dissector for the new conversation */ + conversation_set_dissector(conversation, sub_dissector_handle); + } + ... + +void +proto_register_PROTOABBREV(void) +{ + ... + + sub_dissector_handle = register_dissector("PROTOABBREV", sub_dissector, + proto); + + ... +} + +2.4 Dynamic server port dissector registration. + +NOTE: While this example used both NO_ADDR2 and NO_PORT2 to create a +conversation with only one port and address set, this isn't a +requirement. Either the second port or the second address can be set +when the conversation is created. + +For protocols that define a server address and port for a secondary +protocol, a conversation can be used to link a protocol dissector to +the server port and address. The key is to create the new +conversation with the second address and port set to the "accept +any" values. + +Some server applications can use the same port for different protocols during +different stages of a transaction. For example it might initially use SNMP +to perform some discovery and later switch to use TFTP using the same port. +In order to handle this properly we must first check whether such a +conversation already exists or not and if it exists we also check whether the +registered dissector_handle for that conversation is "our" dissector or not. +If not we create a new conversation on top of the previous one and set this new +conversation to use our protocol. +Since Wireshark keeps track of the frame number where a conversation started +wireshark will still be able to keep the packets apart even though they do use +the same socketpair. + (See packet-tftp.c and packet-snmp.c for examples of this) + +There are two support routines that will allow the second port and/or +address to be set later. + +conversation_set_port2( conversation_t *conv, uint32_t port); +conversation_set_addr2( conversation_t *conv, address addr); + +These routines will change the second address or port for the +conversation. So, the server port conversation will be converted into a +more complete conversation definition. Don't use these routines if you +want to create a conversation between the server and client and retain the +server port definition, you must create a new conversation. + + +An example - + +/* the handle for the dynamic dissector * +static dissector_handle_t sub_dissector_handle; + + ... + +/* in the main protocol dissector, where the next dissector is setup */ + +/* if conversation has a data field, create it and load structure */ + + new_conv_info = wmem_alloc(wmem_file_scope(), sizeof(struct _new_conv_info)); + new_conv_info->data1 = value1; + +/* create the conversation for the dynamic server address and port */ +/* NOTE: The second address and port values don't matter because the */ +/* NO_ADDR2 and NO_PORT2 options are set. */ + +/* First check if a conversation already exists for this + IP/protocol/port +*/ + conversation = find_conversation(pinfo->num, + &server_src_addr, 0, protocol, + server_src_port, 0, NO_ADDR2 | NO_PORT_B); +/* If there is no such conversation, or if there is one but for + someone else's protocol then we just create a new conversation + and assign our protocol to it. +*/ + if ( (conversation == NULL) || + (conversation->dissector_handle != sub_dissector_handle) ) { + conversation = conversation_new(pinfo->num, + &server_src_addr, 0, conversation_type, + server_src_port, 0, new_conv_info, NO_ADDR2 | NO_PORT2); + +/* set the dissector for the new conversation */ + conversation_set_dissector(conversation, sub_dissector_handle); + } + +2.5 Per-packet information. + +Information can be stored for each data packet that is processed by the +dissector. The information is added with the p_add_proto_data function and +retrieved with the p_get_proto_data function. The data pointers passed into +the p_add_proto_data are not managed by the proto_data routines, however the +data pointer memory scope must match that of the scope parameter. +The two most common use cases for p_add_proto_data/p_get_proto_data are for +persistent data about the packet for the lifetime of the capture (file scope) +and to exchange data between dissectors across a single packet (packet scope). +It is also used to provide packet data for Decode As dialog (packet scope). + +These functions are declared in <epan/proto_data.h>. + +void +p_add_proto_data(wmem_allocator_t *scope, packet_info *pinfo, int proto, uint32_t key, void *proto_data) +void * +p_get_proto_data(wmem_allocator_t *scope, packet_info *pinfo, int proto, uint32_t key) + +Where: + scope - Lifetime of the data to be stored, typically wmem_file_scope() + or pinfo->pool (packet scope). Must match scope of data + allocated. + pinfo - The packet info pointer. + proto - Protocol id returned by the proto_register_protocol call + during initialization + key - key associated with 'proto_data' + proto_data - pointer to the dissector data. + + +2.6 User Preferences. + +If the dissector has user options, there is support for adding these preferences +to a configuration dialog. + +You must register the module with the preferences routine with - + + module_t *prefs_register_protocol(proto_id, void (*apply_cb)(void)) + or + module_t *prefs_register_protocol_subtree(const char *subtree, int id, + void (*apply_cb)(void)); + + +Where: proto_id - the value returned by "proto_register_protocol()" when + the protocol was registered. + apply_cb - Callback routine that is called when preferences are + applied. It may be NULL, which inhibits the callback. + subtree - grouping preferences tree node name (several protocols can + be grouped under one preferences subtree) + +Then you can register the fields that can be configured by the user with these +routines - + + /* Register a preference with an unsigned integral value. */ + void prefs_register_uint_preference(module_t *module, const char *name, + const char *title, const char *description, unsigned base, unsigned *var); + + /* Register a preference with an Boolean value. */ + void prefs_register_bool_preference(module_t *module, const char *name, + const char *title, const char *description, bool *var); + + /* Register a preference with an enumerated value. */ + void prefs_register_enum_preference(module_t *module, const char *name, + const char *title, const char *description, int *var, + const enum_val_t *enumvals, bool radio_buttons) + + /* Register a preference with a character-string value. */ + void prefs_register_string_preference(module_t *module, const char *name, + const char *title, const char *description, char **var) + + /* Register a preference with a password (a character-string) value. */ + /* The value is hold during runtime, only in memory. It is never written to disk */ + void prefs_register_password_preference(module_t *module, const char *name, + const char *title, const char *description, char **var) + + /* Register a preference with a file name (string) value. + * File name preferences are basically like string preferences + * except that the GUI gives the user the ability to browse for the + * file. Set for_writing true to show a Save dialog instead of normal Open. + */ + void prefs_register_filename_preference(module_t *module, const char *name, + const char *title, const char *description, char **var, + bool for_writing) + + /* Register a preference with a range of unsigned integers (e.g., + * "1-20,30-40"). + */ + void prefs_register_range_preference(module_t *module, const char *name, + const char *title, const char *description, range_t *var, + uint32_t max_value) + +Where: module - Returned by the prefs_register_protocol routine + name - This is appended to the name of the protocol, with a + "." between them, to construct a name that identifies + the field in the preference file; the name itself + should not include the protocol name, as the name in + the preference file will already have it. Make sure that + only lower-case ASCII letters, numbers, underscores and + dots appear in the preference name. + title - Field title in the preferences dialog + description - Comments added to the preference file above the + preference value and shown as tooltip in the GUI, or NULL + var - pointer to the storage location that is updated when the + field is changed in the preference dialog box. Note that + with string preferences the given pointer is overwritten + with a pointer to a new copy of the string during the + preference registration. The passed-in string may be + freed, but you must keep another pointer to the string + in order to free it. + base - Base that the unsigned integer is expected to be in, + see strtoul(3). + enumvals - an array of enum_val_t structures. This must be + NULL-terminated; the members of that structure are: + + a short name, to be used with the "-o" flag - it + should not contain spaces or upper-case letters, + so that it's easier to put in a command line; + + a description, which is used in the GUI (and + which, for compatibility reasons, is currently + what's written to the preferences file) - it can + contain spaces, capital letters, punctuation, + etc.; + + the numerical value corresponding to that name + and description + radio_buttons - true if the field is to be displayed in the + preferences dialog as a set of radio buttons, + false if it is to be displayed as an option + menu + max_value - The maximum allowed value for a range (0 is the minimum). + +These functions are declared in <epan/prefs.h>. + +An example from packet-rtpproxy.c - + + proto_rtpproxy = proto_register_protocol ( "Sippy RTPproxy Protocol", "RTPproxy", "rtpproxy"); + + ... + + rtpproxy_module = prefs_register_protocol(proto_rtpproxy, proto_reg_handoff_rtpproxy); + + prefs_register_bool_preference(rtpproxy_module, "establish_conversation", + "Establish Media Conversation", + "Specifies that RTP/RTCP/T.38/MSRP/etc streams are decoded based " + "upon port numbers found in RTPproxy answers", + &rtpproxy_establish_conversation); + + prefs_register_uint_preference(rtpproxy_module, "reply.timeout", + "RTPproxy reply timeout", /* Title */ + "Maximum timeout value in waiting for reply from RTPProxy (in milliseconds).", /* Descr */ + 10, + &rtpproxy_timeout); + +This will create preferences "rtpproxy.establish_conversation" and +"rtpproxy.reply.timeout", the first of which is an Boolean and the +second of which is a unsigned integer. + +Note that a warning will pop up if you've saved such preference to the +preference file and you subsequently take the code out. The way to make +a preference obsolete is to register it as such: + +/* Register a preference that used to be supported but no longer is. */ + void prefs_register_obsolete_preference(module_t *module, + const char *name); + +2.7 Reassembly/desegmentation for protocols running atop TCP. + +There are two main ways of reassembling a Protocol Data Unit (PDU) which +spans across multiple TCP segments. The first approach is simpler, but +assumes you are running atop of TCP when this occurs (but your dissector +might run atop of UDP, too, for example), and that your PDUs consist of a +fixed amount of data that includes enough information to determine the PDU +length, possibly followed by additional data. The second method is more +generic but requires more code and is less efficient. + +2.7.1 Using tcp_dissect_pdus(). + +For the first method, you register two different dissection methods, one +for the TCP case, and one for the other cases. It is a good idea to +also have a dissect_PROTO_common function which will parse the generic +content that you can find in all PDUs which is called from +dissect_PROTO_tcp when the reassembly is complete and from +dissect_PROTO_udp (or dissect_PROTO_other). + +To register the distinct dissector functions, consider the following +example, stolen from packet-hartip.c: + + #include "packet-tcp.h" + + dissector_handle_t hartip_tcp_handle; + dissector_handle_t hartip_udp_handle; + + hartip_udp_handle = register_dissector_with_description("hart_ip", "HART-IP over UDP", dissect_hartip_udp, proto_hartip); + hartip_tcp_handle = register_dissector_with_description("hart_ip.tcp", "HART-IP over TCP", dissect_hartip_tcp, proto_hartip); + + dissector_add_uint_with_preference("udp.port", HARTIP_PORT, hartip_udp_handle); + dissector_add_uint_with_preference("tcp.port", HARTIP_PORT, hartip_tcp_handle); + +The dissect_hartip_udp function does very little work and calls +dissect_hartip_common, while dissect_hartip_tcp calls tcp_dissect_pdus with a +reference to a callback which will be called with reassembled data: + + static int + dissect_hartip_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, + void *data) + { + if (!tvb_bytes_exist(tvb, 0, HARTIP_HEADER_LENGTH)) + return 0; + + tcp_dissect_pdus(tvb, pinfo, tree, hartip_desegment, HARTIP_HEADER_LENGTH, + get_dissect_hartip_len, dissect_hartip_pdu, data); + return tvb_reported_length(tvb); + } + +(The dissect_hartip_pdu function acts similarly to dissect_hartip_udp.) +The arguments to tcp_dissect_pdus are: + + the tvbuff pointer, packet_info pointer, and proto_tree pointer + passed to the dissector; + + a bool flag indicating whether desegmentation is enabled for + your protocol; + + the number of bytes of PDU data required to determine the length + of the PDU; + + a routine that takes as arguments a packet_info pointer, a tvbuff + pointer and an offset value representing the offset into the tvbuff + at which a PDU begins, and a void pointer for user data, and should + return the total length of the PDU in bytes (or 0 if more bytes are + needed to determine the message length). + The routine must not throw exceptions (it is guaranteed that the + number of bytes specified by the previous argument to + tcp_dissect_pdus is available, but more data might not be available, + so don't refer to any data past that); + + a new_dissector_t routine to dissect the pdu that's passed a tvbuff + pointer, packet_info pointer, proto_tree pointer and a void pointer for + user data, with the tvbuff containing a possibly-reassembled PDU. (The + "reported_length" of the tvbuff will be the length of the PDU); + + a void pointer to user data that is passed to the length-determining + routine, and the dissector routine referenced in the previous parameter. + +2.7.2 Modifying the pinfo struct. + +The second reassembly mode is preferred when the dissector cannot determine +how many bytes it will need to read in order to determine the size of a PDU. +It may also be useful if your dissector needs to support reassembly from +protocols other than TCP. + +Your dissect_PROTO will initially be passed a tvbuff containing the payload of +the first packet. It should dissect as much data as it can, noting that it may +contain more than one complete PDU. If the end of the provided tvbuff coincides +with the end of a PDU then all is well and your dissector can just return as +normal. (If it is a new-style dissector, it should return the number of bytes +successfully processed.) + +If the dissector discovers that the end of the tvbuff does /not/ coincide with +the end of a PDU, (ie, there is half of a PDU at the end of the tvbuff), it can +indicate this to the parent dissector, by updating the pinfo struct. The +desegment_offset field is the offset in the tvbuff at which the dissector will +continue processing when next called. The desegment_len field should contain +the estimated number of additional bytes required for completing the PDU. Next +time your dissect_PROTO is called, it will be passed a tvbuff composed of the +end of the data from the previous tvbuff together with desegment_len more bytes. + +If the dissector cannot tell how many more bytes it will need, it should set +desegment_len=DESEGMENT_ONE_MORE_SEGMENT; it will then be called again as soon +as any more data becomes available. Dissectors should set the desegment_len to a +reasonable value when possible rather than always setting +DESEGMENT_ONE_MORE_SEGMENT as it will generally be more efficient. Also, you +*must not* set desegment_len=1 in this case, in the hope that you can change +your mind later: once you return a positive value from desegment_len, your PDU +boundary is set in stone. + +static hf_register_info hf[] = { + {&hf_cstring, + {"C String", "c.string", FT_STRING, BASE_NONE, NULL, 0x0, + NULL, HFILL} + } + }; + +/** +* Dissect a buffer containing ASCII C strings. +* +* @param tvb The buffer to dissect. +* @param pinfo Packet Info. +* @param tree The protocol tree. +* @param data Optional data parameter given by parent dissector. +**/ +static int dissect_cstr(tvbuff_t * tvb, packet_info * pinfo, proto_tree * tree, void *data _U_) +{ + unsigned offset = 0; + while(offset < tvb_reported_length(tvb)) { + int available = tvb_reported_length_remaining(tvb, offset); + int len = tvb_strnlen(tvb, offset, available); + + if( -1 == len ) { + /* we ran out of data: ask for more */ + pinfo->desegment_offset = offset; + pinfo->desegment_len = DESEGMENT_ONE_MORE_SEGMENT; + return (offset + available); + } + + col_set_str(pinfo->cinfo, COL_INFO, "C String"); + + len += 1; /* Add one for the '\0' */ + + if (tree) { + proto_tree_add_item(tree, hf_cstring, tvb, offset, len, ENC_ASCII); + } + offset += (unsigned)len; + } + + /* if we get here, then the end of the tvb coincided with the end of a + string. Happy days. */ + return tvb_captured_length(tvb); +} + +This simple dissector will repeatedly return DESEGMENT_ONE_MORE_SEGMENT +requesting more data until the tvbuff contains a complete C string. The C string +will then be added to the protocol tree. Note that there may be more +than one complete C string in the tvbuff, so the dissection is done in a +loop. + +2.8 Using udp_dissect_pdus(). + +As noted in section 2.7.1, TCP has an API to dissect its PDU that can handle +a PDU spread across multiple packets or multiple PDUs spread across a single +packet. This section describes a similar mechanism for UDP, but is only +applicable for one or more PDUs in a single packet. If a protocol runs on top +of TCP as well as UDP, a common PDU dissection function can be created for both. + +To register the distinct dissector functions, consider the following +example using UDP and TCP dissection, stolen from packet-dnp.c: + + #include "packet-tcp.h" + #include "packet-udp.h" + + dissector_handle_t dnp3_tcp_handle; + dissector_handle_t dnp3_udp_handle; + + dnp3_tcp_handle = register_dissector("dnp3.tcp", dissect_dnp3_tcp, proto_dnp3); + dnp3_udp_handle = register_dissector("dnp3.udp", dissect_dnp3_udp, proto_dnp3); + + dissector_add_uint_with_preference("tcp.port", TCP_PORT_DNP, dnp3_tcp_handle); + dissector_add_uint_with_preference("udp.port", UDP_PORT_DNP, dnp3_udp_handle); + +Both dissect_dnp3_tcp and dissect_dnp3_udp call tcp_dissect_pdus and +udp_dissect_pdus respectively, with a reference to the same callbacks which +are called to handle PDU data. + + static int + dissect_dnp3_udp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data) + { + return udp_dissect_pdus(tvb, pinfo, tree, DNP_HDR_LEN, dnp3_udp_check_header, + get_dnp3_message_len, dissect_dnp3_message, data); + } + + static int + dissect_dnp3_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data) + { + if (!check_dnp3_header(tvb, false)) { + return 0; + } + + tcp_dissect_pdus(tvb, pinfo, tree, true, DNP_HDR_LEN, + get_dnp3_message_len, dissect_dnp3_message, data); + + return tvb_captured_length(tvb); + } + +(udp_dissect_pdus has an option of a heuristic check function within it while +tcp_dissect_pdus does not, so it's done outside) + +The arguments to udp_dissect_pdus are: + + the tvbuff pointer, packet_info pointer, and proto_tree pointer + passed to the dissector; + + the number of bytes of PDU data required to determine the length + of the PDU; + + an optional routine (passing NULL is okay) that takes as arguments a + packet_info pointer, a tvbuff pointer and an offset value representing the + offset into the tvbuff at which a PDU begins, and a void pointer for user + data, and should return true if the packet belongs to the dissector. + The routine must not throw exceptions (it is guaranteed that the + number of bytes specified by the previous argument to + udp_dissect_pdus is available, but more data might not be available, + so don't refer to any data past that); + + a routine that takes as arguments a packet_info pointer, a tvbuff + pointer and an offset value representing the offset into the tvbuff + at which a PDU begins, and a void pointer for user data, and should + return the total length of the PDU in bytes. If return value is 0, + it's treated the same as a failed heuristic. + The routine must not throw exceptions (it is guaranteed that the + number of bytes specified by the previous argument to + tcp_dissect_pdus is available, but more data might not be available, + so don't refer to any data past that); + + a new_dissector_t routine to dissect the pdu that's passed a tvbuff + pointer, packet_info pointer, proto_tree pointer and a void pointer for + user data, with the tvbuff containing a possibly-reassembled PDU. (The + "reported_length" of the tvbuff will be the length of the PDU); + + a void pointer to user data that is passed to the length-determining + routine, and the dissector routine referenced in the previous parameter. + +2.9 PINOs (Protocols in name only) + +For the typical dissector there is a 1-1 relationship between it and its +protocol. However, there are times when a protocol needs multiple "names" +because it has multiple dissection functions going into the same dissector +table. The multiple names removes confusion when picking dissection through +Decode As functionality. + +Once the "main" protocol name has been created through proto_register_protocol, +additional "pinos" can be created with proto_register_protocol_in_name_only. +These pinos have all of the naming conventions of a protocol, but are stored +separately as to remove confusion from real protocols. "pinos" the main +protocol's properties for things like enable/disable. i.e. If the "main" +protocol has been disabled, all of its pinos will be disabled as well. +Pinos should not have any fields registered with them or heuristic tables +associated with them. + +Another use case for pinos is when a protocol contains a TLV design and it +wants to create a dissector table to handle dissection of the "V". Dissector +tables require a "protocol", but the dissection functions for that table +typically aren't a protocol. In this case proto_register_protocol_in_name_only +creates the necessary placeholder for the dissector table. In addition, because +a dissector table exists, "V"s of the TLVs can be dissected outside of the +original dissector file. + +2.10 Creating Decode As functionality. + +While the Decode As functionality is available through the GUI, the underlying +functionality is controlled by dissectors themselves. To create Decode As +functionality for a dissector, two things are required: + 1. A dissector table + 2. A series of structures to assist the GUI in how to present the dissector + table data. + +Consider the following example using IP dissection, stolen from packet-ip.c: + + static build_valid_func ip_da_build_value[1] = {ip_value}; + static decode_as_value_t ip_da_values = {ip_prompt, 1, ip_da_build_value}; + static decode_as_t ip_da = {"ip", "ip.proto", 1, 0, &ip_da_values, NULL, NULL, + decode_as_default_populate_list, decode_as_default_reset, decode_as_default_change, NULL}; + ... + ip_dissector_table = register_dissector_table("ip.proto", "IP protocol", ip_proto, FT_UINT8, BASE_DEC); + ... + register_decode_as(&ip_da); + +ip_da_build_value contains all of the function pointers (typically just 1) that +can be used to retrieve the value(s) that go into the dissector table. This is +usually data saved by the dissector during packet dissector with an API like +p_add_proto_data and retrieved in the "value" function with p_get_proto_data. + +ip_da_values contains all of the function pointers (typically just 1) that +provide the text explaining the name and use of the value field that will +be passed to the dissector table to change the dissection output. + +ip_da pulls everything together including the dissector (protocol) name, the +"layer type" of the dissector, the dissector table name, the function pointer +values as well as handlers for populating, applying and resetting the changes +to the dissector table through Decode As GUI functionality. For dissector +tables that are an integer or string type, the provided "default" handling +functions shown in the example should suffice. + +All entries into a dissector table that use Decode As must have a unique +protocol ID. If a protocol wants multiple entries into a dissector table, +a pino should be used (see section 2.9) + +2.11 ptvcursors. + +The ptvcursor API allows a simpler approach to writing dissectors for +simple protocols. The ptvcursor API works best for protocols whose fields +are static and whose format does not depend on the value of other fields. +However, even if only a portion of your protocol is statically defined, +then that portion could make use of ptvcursors. + +The ptvcursor API lets you extract data from a tvbuff, and add it to a +protocol tree in one step. It also keeps track of the position in the +tvbuff so that you can extract data again without having to compute any +offsets --- hence the "cursor" name of the API. + +The three steps for a simple protocol are: + 1. Create a new ptvcursor with ptvcursor_new() + 2. Add fields with multiple calls of ptvcursor_add() + 3. Delete the ptvcursor with ptvcursor_free() + +ptvcursor offers the possibility to add subtrees in the tree as well. It can be +done in very simple steps : + 1. Create a new subtree with ptvcursor_push_subtree(). The old subtree is + pushed in a stack and the new subtree will be used by ptvcursor. + 2. Add fields with multiple calls of ptvcursor_add(). The fields will be + added in the new subtree created at the previous step. + 3. Pop the previous subtree with ptvcursor_pop_subtree(). The previous + subtree is again used by ptvcursor. +Note that at the end of the parsing of a packet you must have popped each +subtree you pushed. If it's not the case, the dissector will generate an error. + +To use the ptvcursor API, include the "ptvcursor.h" file. The PGM dissector +is an example of how to use it. You don't need to look at it as a guide; +instead, the API description here should be good enough. + +2.11.1 ptvcursor API. + +ptvcursor_t* +ptvcursor_new(proto_tree* tree, tvbuff_t* tvb, int offset) + This creates a new ptvcursor_t object for iterating over a tvbuff. +You must call this and use this ptvcursor_t object so you can use the +ptvcursor API. + +proto_item* +ptvcursor_add(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding) + This will extract 'length' bytes from the tvbuff and place it in +the proto_tree as field 'hf', which is a registered header_field. The +pointer to the proto_item that is created is passed back to you. Internally, +the ptvcursor advances its cursor so the next call to ptvcursor_add +starts where this call finished. The 'encoding' parameter is relevant for +certain type of fields (See above under proto_tree_add_item()). + +proto_item* +ptvcursor_add_ret_uint(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, uint32_t *retval); + Like ptvcursor_add, but returns uint value retrieved + +proto_item* +ptvcursor_add_ret_int(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, int32_t *retval); + Like ptvcursor_add, but returns int value retrieved + +proto_item* +ptvcursor_add_ret_string(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, wmem_allocator_t *scope, const uint8_t **retval); + Like ptvcursor_add, but returns string retrieved + +proto_item* +ptvcursor_add_ret_boolean(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding, bool *retval); + Like ptvcursor_add, but returns boolean value retrieved + +proto_item* +ptvcursor_add_no_advance(ptvcursor_t* ptvc, int hf, int length, const unsigned encoding) + Like ptvcursor_add, but does not advance the internal cursor. + +void +ptvcursor_advance(ptvcursor_t* ptvc, int length) + Advances the internal cursor without adding anything to the proto_tree. + +void +ptvcursor_free(ptvcursor_t* ptvc) + Frees the memory associated with the ptvcursor. You must call this +after your dissection with the ptvcursor API is completed. + + +proto_tree* +ptvcursor_push_subtree(ptvcursor_t* ptvc, proto_item* it, int ett_subtree) + Pushes the current subtree in the tree stack of the cursor, creates a new +one and sets this one as the working tree. + +void +ptvcursor_pop_subtree(ptvcursor_t* ptvc); + Pops a subtree in the tree stack of the cursor + +proto_tree* +ptvcursor_add_with_subtree(ptvcursor_t* ptvc, int hfindex, int length, + const unsigned encoding, int ett_subtree); + Adds an item to the tree and creates a subtree. +If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH. +In this case, at the next pop, the item length will be equal to the advancement +of the cursor since the creation of the subtree. + +proto_tree* +ptvcursor_add_text_with_subtree(ptvcursor_t* ptvc, int length, + int ett_subtree, const char* format, ...); + Add a text node to the tree and create a subtree. +If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH. +In this case, at the next pop, the item length will be equal to the advancement +of the cursor since the creation of the subtree. + +2.11.2 Miscellaneous functions. + +tvbuff_t* +ptvcursor_tvbuff(ptvcursor_t* ptvc) + Returns the tvbuff associated with the ptvcursor. + +int +ptvcursor_current_offset(ptvcursor_t* ptvc) + Returns the current offset. + +proto_tree* +ptvcursor_tree(ptvcursor_t* ptvc) + Returns the proto_tree associated with the ptvcursor. + +void +ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree *tree) + Sets a new proto_tree for the ptvcursor. + +proto_tree* +ptvcursor_set_subtree(ptvcursor_t* ptvc, proto_item* it, int ett_subtree); + Creates a subtree and adds it to the cursor as the working tree but does +not save the old working tree. + +2.12 Optimizations + +A protocol dissector may be called in 2 different ways - with, or +without a non-null "tree" argument. + +If the proto_tree argument is null, Wireshark does not need to use +the protocol tree information from your dissector, and therefore is +passing the dissector a null "tree" argument so that it doesn't +need to do work necessary to build the protocol tree. + +In the interest of speed, if "tree" is NULL, avoid building a +protocol tree and adding stuff to it, or even looking at any packet +data needed only if you're building the protocol tree, if possible. + +Note, however, that you must fill in column information, create +conversations, reassemble packets, do calls to "expert" functions, +build any other persistent state needed for dissection, and call +subdissectors regardless of whether "tree" is NULL or not. + +This might be inconvenient to do without doing most of the +dissection work; the routines for adding items to the protocol tree +can be passed a null protocol tree pointer, in which case they'll +return a null item pointer, and "proto_item_add_subtree()" returns +a null tree pointer if passed a null item pointer, so, if you're +careful not to dereference any null tree or item pointers, you can +accomplish this by doing all the dissection work. This might not +be as efficient as skipping that work if you're not building a +protocol tree, but if the code would have a lot of tests whether +"tree" is null if you skipped that work, you might still be better +off just doing all that work regardless of whether "tree" is null +or not. + +Note also that there is no guarantee, the first time the dissector is +called, whether "tree" will be null or not; your dissector must work +correctly, building or updating whatever state information is +necessary, in either case. + +/* + * Editor modelines - https://www.wireshark.org/tools/modelines.html + * + * Local variables: + * c-basic-offset: 4 + * tab-width: 8 + * indent-tabs-mode: nil + * End: + * + * vi: set shiftwidth=4 tabstop=8 expandtab: + * :indentSize=4:tabSize=8:noTabs=true: + */ diff --git a/doc/README.heuristic b/doc/README.heuristic new file mode 100644 index 0000000..08e9464 --- /dev/null +++ b/doc/README.heuristic @@ -0,0 +1,244 @@ +This file is a HOWTO for Wireshark developers. It describes how Wireshark +heuristic protocol dissectors work and how to write them. + +This file is compiled to give in depth information on Wireshark. +It is by no means all inclusive and complete. Please feel free to send +remarks and patches to the developer mailing list. + + +Prerequisites +------------- +As this file is an addition to README.dissector, it is essential to read +and understand that document first. + + +Why heuristic dissectors? +------------------------- +When Wireshark "receives" a packet, it has to find the right dissector to +start decoding the packet data. Often this can be done by known conventions, +e.g. the Ethernet type 0x0800 means "IP on top of Ethernet" - an easy and +reliable match for Wireshark. + +Unfortunately, these conventions are not always available, or (accidentally +or knowingly) some protocols don't care about those conventions and "reuse" +existing "magic numbers / tokens". + +For example TCP defines port 80 only for the use of HTTP traffic. But, this +convention doesn't prevent anyone from using TCP port 80 for some different +protocol, or on the other hand using HTTP on a port number different than 80. + +To solve this problem, Wireshark introduced the so called heuristic dissector +mechanism to try to deal with these problems. + + +How Wireshark uses heuristic dissectors? +---------------------------------------- +While Wireshark starts, heuristic dissectors (HD) register themselves slightly +different than "normal" dissectors, e.g. a HD can ask for any TCP packet, as +it *may* contain interesting packet data for this dissector. In reality more +than one HD will exist for e.g. TCP packet data. + +So if Wireshark has to decode TCP packet data, it will first try to find a +dissector registered directly for the TCP port used in that packet. If it +finds such a registered dissector it will just hand over the packet data to it. + +In case there is no such "normal" dissector, WS will hand over the packet data +to the first matching HD. Now the HD will look into the data and decide if that +data looks like something the dissector "is interested in". The return value +signals WS if the HD processed the data (so WS can stop working on that packet) +or if the heuristic didn't match (so WS tries the next HD until one matches - +or the data simply can't be processed). + +Note that it is possible to configure WS through preference settings so that it +hands off a packet to the heuristic dissectors before the "normal" dissectors +are called. This allows the HD the chance to receive packets and process them +differently than they otherwise would be. Of course if no HD is interested in +the packet, then the packet will ultimately get handed off to the "normal" +dissector as if the HD wasn't involved at all. As of this writing, +16 dissectors (including DCCP, SCTP, TCP, TIPC and UDP) provide this capability +via their "Try heuristic sub-dissectors first" preference, but most of them have +this option disabled by default. + +Once a packet for a particular "connection" has been identified as belonging +to a particular protocol, Wireshark must then be set up to always directly +call the dissector for that protocol. This removes the overhead of having +to identify each packet of the connection heuristically. + + +How do these heuristics work? +----------------------------- +It's difficult to give a general answer here. The usual heuristic works as follows: + +A HD looks into the first few packet bytes and searches for common patterns that +are specific to the protocol in question. Most protocols starts with a +specific header, so a specific pattern may look like (synthetic example): + +1) first byte must be 0x42 +2) second byte is a type field and can only contain values between 0x20 - 0x33 +3) third byte is a flag field, where the lower 4 bits always contain the value 0 +4) fourth and fifth bytes contain a 16 bit length field, where the value can't + be larger than 10000 bytes + +So the heuristic dissector will check incoming packet data for all of the +4 above conditions, and only if all of the four conditions are true there is a +good chance that the packet really contains the expected protocol - and the +dissector continues to decode the packet data. If one condition fails, it's +very certainly not the protocol in question and the dissector returns to WS +immediately "this is not my protocol" - maybe some other heuristic dissector +is interested! + +Obviously, this is *not* 100% bullet proof, but it's the best WS can offer to +its users here - and improving the heuristic is always possible if it turns out +that it's not good enough to distinguish between two given protocols. + +Note: The heuristic code in a dissector *must not* cause an exception + (before returning false) as this will prevent following + heuristic dissector handoffs. In practice, this normally means + that a test must be done to verify that the required data is + available in the tvb before fetching from the tvb. (See the + example below). + + +Heuristic Code Example +---------------------- +You can find a lot of code examples in the Wireshark sources, e.g.: +grep -l heur_dissector_add epan/dissectors/*.c +returns 236 files (December 2021). + +For the above example criteria, the following code example might do the work +(combine this with the dissector skeleton in README.developer): + +XXX - please note: The following code examples were not tried in reality, +please report problems to the dev-list! + +-------------------------------------------------------------------------------------------- + +static dissector_handle_t PROTOABBREV_tcp_handle; +static dissector_handle_t PROTOABBREV_pdu_handle; + +/* Heuristics test */ +static bool +test_PROTOABBREV(packet_info *pinfo _U_, tvbuff_t *tvb, int offset _U_, void *data _U_) +{ + /* 0) Verify needed bytes available in tvb so tvb_get...() doesn't cause exception. + if (tvb_captured_length(tvb) < 5) + return false; + + /* 1) first byte must be 0x42 */ + if ( tvb_get_guint8(tvb, 0) != 0x42 ) + return false; + + /* 2) second byte is a type field and only can contain values between 0x20-0x33 */ + if ( tvb_get_guint8(tvb, 1) < 0x20 || tvb_get_guint8(tvb, 1) > 0x33 ) + return false; + + /* 3) third byte is a flag field, where the lower 4 bits always contain the value 0 */ + if ( tvb_get_guint8(tvb, 2) & 0x0f ) + return false; + + /* 4) fourth and fifth bytes contains a 16 bit length field, where the value can't be longer than 10000 bytes */ + /* Assumes network byte order */ + if ( tvb_get_ntohs(tvb, 3) > 10000 ) + return false; + + /* Assume it's your packet ... */ + return true; +} + +/* Dissect the complete PROTOABBREV pdu */ +static int +dissect_PROTOABBREV_pdu(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data _U_) +{ + /* Dissection ... */ + + return tvb_reported_length(tvb); +} + +/* For tcp_dissect_pdus() */ +static unsigned +get_PROTOABBREV_len(packet_info *pinfo _U_, tvbuff_t *tvb, int offset, void *data _U_) +{ + return (unsigned) tvb_get_ntohs(tvb, offset+3); +} + +static int +dissect_PROTOABBREV_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data) +{ + tcp_dissect_pdus(tvb, pinfo, tree, true, 5, + get_PROTOABBREV_len, dissect_PROTOABBREV_pdu, data); + return tvb_reported_length(tvb); +} + +static bool +dissect_PROTOABBREV_heur_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data) +{ + if (!test_PROTOABBREV(pinfo, tvb, 0, data)) + return false; + + /* specify that dissect_PROTOABBREV is to be called directly from now on for + * packets for this "connection" ... but only do this if your heuristic sits directly + * on top of (was called by) a dissector which established a conversation for the + * protocol "port type". In other words: only directly over TCP, UDP, DCCP, ... + * otherwise you'll be overriding the dissector that called your heuristic dissector. + */ + conversation = find_or_create_conversation(pinfo); + conversation_set_dissector(conversation, PROTOABBREV_tcp_handle); + + /* and do the dissection */ + dissect_PROTOABBREV_tcp(tvb, pinfo, tree, data); + + return (true); +} + +static int +dissect_PROTOABBREV_udp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data) +{ + udp_dissect_pdus(tvb, pinfo, tree, true, 5, NULL, + get_PROTOABBREV_len, dissect_PROTOABBREV_pdu, data); + return tvb_reported_length(tvb); +} + +static bool +dissect_PROTOABBREV_heur_udp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data) +{ +... + /* and do the dissection */ + return (udp_dissect_pdus(tvb, pinfo, tree, true, 5, test_PROTOABBREV, + get_PROTOABBREV_len, dissect_PROTOABBREV_pdu, data) != 0); +} + +void +proto_reg_handoff_PROTOABBREV(void) +{ + PROTOABBREV_tcp_handle = create_dissector_handle(dissect_PROTOABBREV_tcp, + proto_PROTOABBREV); + PROTOABBREV_pdu_handle = create_dissector_handle(dissect_PROTOABBREV_pdu, + proto_PROTOABBREV); + + /* register as heuristic dissector for both TCP and UDP */ + heur_dissector_add("tcp", dissect_PROTOABBREV_heur_tcp, "PROTOABBREV over TCP", + "PROTOABBREV_tcp", proto_PROTOABBREV, HEURISTIC_ENABLE); + heur_dissector_add("udp", dissect_PROTOABBREV_heur_udp, "PROTOABBREV over UDP", + "PROTOABBREV_udp", proto_PROTOABBREV, HEURISTIC_ENABLE); + +#ifdef OPTIONAL + /* It's possible to write a dissector to be a dual heuristic/normal dissector */ + /* by also registering the dissector "normally". */ + dissector_add_uint("ip.proto", IP_PROTO_PROTOABBREV, PROTOABBREV_pdu_handle); +#endif +} + + +Please note, that registering a heuristic dissector is only possible for a +small variety of protocols. In most cases a heuristic is not needed, and +adding the support would only add unused code to the dissector. + +TCP and UDP are prominent examples that support HDs, as there seems to be a +tendency to re-use known port numbers for new protocols. But TCP and UDP are +not the only dissectors that provide support for HDs. You can find more +examples by searching the Wireshark sources as follows: +grep -l register_heur_dissector_list epan/dissectors/packet-*.c + +There are a small number of cases where heuristic dissectors have been added +for formats that were specifically created for use with Wireshark (e.g. +LTE and NR L2 MAC, RLC and PDCP dissectors). diff --git a/doc/README.idl2wrs b/doc/README.idl2wrs new file mode 100644 index 0000000..77596cb --- /dev/null +++ b/doc/README.idl2wrs @@ -0,0 +1,144 @@ +Copyright (C) 2001 Frank Singleton <frank.singleton@ericsson.com> + + +What is it ? +============ + +As you have probably guessed from the name, "idl2wrs" takes a +user specified IDL file and attempts to build a dissector that +can decode the IDL traffic over GIOP. The resulting file is +"C" code that should compile okay as a Wireshark dissector. + +idl2wrs basically parses the data struct given to it by +the omniidl compiler, and using the GIOP API available in packet-giop.[ch], +generates get_CDR_xxx calls to decode the CORBA traffic on the wire. + +It consists of 4 main files. + +README.idl2wrs - This document +wireshark_be.py - The main compiler backend +wireshark_gen.py - A helper class that generates the C code. +idl2wrs - A simple shell script wrapper that the end user should + use to generate the dissector from the IDL file(s). + +Why did you do this ? +===================== + +It is important to understand how CORBA traffic looks +like over GIOP/IIOP, and to help build a tool that can assist +in troubleshooting CORBA interworking. This was especially the +case after seeing a lot of discussions about how particular +IDL types are represented inside an octet stream. + +I have also had comments/feedback that this tool would be good for say +a CORBA class when teaching students how CORBA traffic looks like +"on the wire". + +It is also COOL to work on a great Open Source project such as +the case with "Wireshark" (https://www.wireshark.org) + + +How to use idl2wrs +================== + +To use the idl2wrs to generate Wireshark dissectors, you +need the following. + + +1. Python must be installed + https://python.org/ + +2. omniidl from the omniORB package must be available. + http://omniorb.sourceforge.net/ + +3. Of course you need Wireshark installed to compile the + code and tweak it if required. idl2wrs is part of the + standard Wireshark distribution. + + +Procedure +========= + +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-idl.c + + You may wish to comment out the register_giop_user_module() code + and that will leave you with heuristic dissection. + + +If you don't want to use the shell script wrapper, then try +steps 3 or 4 instead. + +3. To write the C code to stdout. + + Usage: omniidl -p ./ -b wireshark_be <your_file.idl> + + eg: omniidl -p ./ -b wireshark_be echo.idl + + +4. To write to a file, just redirect the output. + + omniidl -p ./ -b wireshark_be echo.idl > packet-test-idl.c + + You may wish to comment out the register_giop_user_module() code + and that will leave you with heuristic dissection. + + +5. Copy the resulting C code to your Wireshark src directory, edit the + following file to include the packet-test-idl.c + + cp packet-test-idl.c /dir/where/wireshark/lives/epan/dissectors/ + cp /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt.example \ + /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt + nano /dir/where/wireshark/lives/epan/dissectors/CMakeLists.txt + + +6. Run CMake + + cmake /dir/where/wireshark/lives + + +7. Compile the code + + make + + +8. Good Luck !! + + +TODO +==== + +1. Exception code not generated (yet), but can be added manually. +2. Enums not converted to symbolic values (yet), but can be added manually. +3. Add command line options, etc. +4. More I am sure :-) + + +Limitations +=========== + +See TODO list inside packet-giop.c + + +Notes +===== + +1. The "-p ./" option passed to omniidl indicates that the wireshark_be.py + and wireshark_gen.py are residing in the current directory. This may need + tweaking if you place these files somewhere else. + +2. If it complains about being unable to find some modules (eg tempfile.py), + you may want to check if PYTHONPATH is set correctly. + On my Linux box, it is PYTHONPATH=/usr/lib/python1.5/ + +Frank Singleton. + diff --git a/doc/README.plugins b/doc/README.plugins new file mode 100644 index 0000000..d7e9fa8 --- /dev/null +++ b/doc/README.plugins @@ -0,0 +1,424 @@ +0. Plugins + +There are a multitude of plugin options available in Wireshark that allow to +extend its functionality without changing the source code itself. Using the +available APIs gives you the means to do this. + +Currently plugin APIs are available for dissectors (epan), capture file types +(wiretap) and media decoders (codecs). This README focuses primarily on +dissector plugins; most of the descriptions are applicable to the other plugin +types as well. + +1. Dissector plugins + +Writing a "plugin" dissector is not very different from writing a standard +one. In fact all of the functions described in README.dissector can be +used in the plugins exactly as they are used in standard dissectors. + +(Note, however, that not all OSes on which Wireshark runs can support +plugins.) + +If you've chosen "foo" as the name of your plugin (typically, that would +be a short name for your protocol, in all lower case), the following +instructions tell you how to implement it as a plugin. All occurrences +of "foo" below should be replaced by the name of your plugin. + +2. The directory for the plugin, and its files + +The plugin should be placed in a new plugins/epan/foo directory which should +contain at least the following files: + +CMakeLists.txt +README + +The README can be brief but it should provide essential information relevant +to developers and users. Optionally AUTHORS and ChangeLog files can be added. +Optionally you can add your own plugin.rc.in. + +And of course the source and header files for your dissector. + +Examples of these files can be found in plugins/epan/gryphon. + +2.1 CMakeLists.txt + +For your plugins/epan/foo/CMakeLists.txt file, see the corresponding file in +plugins/epan/gryphon. Replace all occurrences of "gryphon" in those files +with "foo" and add your source files to the DISSECTOR_SRC variable. + +2.2 plugin.rc.in + +Your plugins/epan/foo/plugin.rc.in is the Windows resource template file used +to add the plugin specific information as resources to the DLL. +If not provided the plugins/plugin.rc.in file will be used. + +3. Changes to existing Wireshark files + +There are two ways to add your plugin dissector to the build, as a custom +extension or as a permanent addition. The custom extension is easy to +configure, but won't be used for inclusion in the distribution if that's +your goal. Setting up the permanent addition is somewhat more involved. + +3.1 Custom extension + +For CMake builds, either pass the custom plugin dir on the CMake generation +step command line: + +CMake ... -DCUSTOM_PLUGIN_SRC_DIR="plugins/epan/foo" + +or copy the top-level file CMakeListsCustom.txt.example to CMakeListsCustom.txt +(also in the top-level source dir) and edit so that CUSTOM_PLUGIN_SRC_DIR is +set() to the relative path of your plugin, e.g. + +set(CUSTOM_PLUGIN_SRC_DIR plugins/epan/foo) + +and re-run the CMake generation step. + +To build the plugin, run your normal Wireshark build step. + +If you want to add the plugin to your own Windows installer add a text +file named custom_plugins.txt to the packaging/nsis directory, with a +"File" statement for NSIS: + +File "${STAGING_DIR}\plugins\${MAJOR_VERSION}.${MINOR_VERSION}\epan\foo.dll" + +3.2 Permanent addition + +In order to be able to permanently add a plugin take the following steps. +You will need to change the following files: + CMakeLists.txt + packaging/nsis/wireshark.nsi + +You might also want to search your Wireshark development directory for +occurrences of an existing plugin name, in case this document is out of +date with the current directory structure. For example, + + grep -rl gryphon . + +could be used from a shell prompt. + +3.2.1 Changes to CMakeLists.txt + +Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS: + +if(ENABLE_PLUGINS) + ... + set(PLUGIN_SRC_DIRS + ... + plugins/epan/ethercat + plugins/epan/foo + plugins/epan/gryphon + plugins/epan/irda + ... + +3.2.2 Changes to the installers + +If you want to include your plugin in an installer you have to add lines +in the NSIS installer wireshark.nsi file. + +3.2.2.1 Changes to packaging/nsis/wireshark.nsi + +Add the relative path of your plugin DLL (in alphabetical order) to the +list of "File" statements in the "Dissector Plugins" section: + +File "${STAGING_DIR}\plugins\${MAJOR_VERSION}.${MINOR_VERSION}\epan\ethercat.dll" +File "${STAGING_DIR}\plugins\${MAJOR_VERSION}.${MINOR_VERSION}\epan\foo.dll" +File "${STAGING_DIR}\plugins\${MAJOR_VERSION}.${MINOR_VERSION}\epan\gryphon.dll" +File "${STAGING_DIR}\plugins\${MAJOR_VERSION}.${MINOR_VERSION}\epan\irda.dll" + +3.2.2.2 Other installers + +The PortableApps installer copies plugins from the build directory +and should not require configuration. + +4. Development and plugins on Unix + +Plugins make some aspects of development easier and some harder. + +The first thing is that you'll have to run cmake once more to setup your +build environment. + +The good news is that if you are working on a single plugin then you will +find recompiling the plugin MUCH faster than recompiling a dissector and +then linking it back into Wireshark. Use "make plugins" to compile just +your plugins. + +The bad news is that Wireshark will not use the plugins unless the plugins +are installed in one of the places it expects them to find. + +One way of dealing with this problem is to set an environment variable +when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1. + +Another way to deal with this problem is to set up a working root for +wireshark, say in $HOME/build/root and build Wireshark to install +there + +cmake -D CMAKE_INSTALL_PREFIX=${HOME}/build/root && make install + +then subsequent rebuilds/installs of your plugin can be accomplished +by going to the plugins/foo directory and running + +make install + +5. Update "old style" plugins + +5.1 How to update an "old style" plugin (since Wireshark 2.5) + +Plugins need exactly four visible symbols: plugin_version, plugin_want_major, +plugin_want_minor and plugin_register. Each plugin is either a codec plugin, +libwiretap plugin or libwireshark plugin and the library will call +"plugin_register" after loading the plugin. "plugin_register" in turn calls all +the hooks necessary to enable the plugin. So if you had two function like so: + + WS_DLL_PUBLIC void plugin_register(void); + WS_DLL_PUBLIC void plugin_reg_handoff(void); + + void plugin_register(void) {...}; + void plugin_reg_handoff(void) {...}; + +You'll have to rewrite it as: + + WS_DLL_PUBLIC void plugin_register(void); + + static void proto_register_foo(void) {...}; + static void proto_reg_handoff_foo(void) {...}; + + void plugin_register(void) + { + static proto_plugin plugin_foo; + + plugin_foo.register_protoinfo = proto_register_foo; + plugin_foo.register_handoff = proto_reg_handoff_foo; + proto_register_plugin(&plugin_foo); + } + +See doc/plugins.example for an example. + +5.2 How to update an "old style" plugin (using plugin_register and + plugin_reg_handoff functions). + +The plugin registration has changed with the extension of the build +scripts. These now generate the additional code needed for plugin +encapsulation in plugin.c. When using the new style build scripts, +strips the parts outlined below: + + o Remove the following include statements: + + #include <gmodule.h> + #include "moduleinfo.h" + + o Removed the definition: + + #ifndef ENABLE_STATIC + WS_DLL_PUBLIC_DEF char version[] = VERSION; + #endif + + o Move relevant code from the blocks and delete these functions: + + #ifndef ENABLE_STATIC + plugin_reg_handoff() + .... + #endif + + #ifndef ENABLE_STATIC + plugin_register() + .... + #endif + +This will leave a clean dissector source file without plugin specifics. + +5.3 How to update an "old style" plugin (using plugin_init function) + +The plugin registering has changed between 0.10.9 and 0.10.10; everyone +is encouraged to update their plugins as outlined below: + + o Remove following include statements from all plugin sources: + + #include "plugins/plugin_api.h" + #include "plugins/plugin_api_defs.h" + + o Remove the init function. + +6 How to plugin related interface options + +To demonstrate the functionality of the plugin interface options, a +demonstration plugin exists (pluginifdemo). To build it using cmake, the +build option ENABLE_PLUGIN_IFDEMO has to be enabled. + +6.1 Implement a plugin GUI menu + +A plugin (as well as built-in dissectors) may implement a menu within +Wireshark to be used to trigger options, start tools, open Websites, ... + +This menu structure is built using the plugin_if.h interface and its +corresponding functions. + +The menu items all call a callback provided by the plugin, which takes +a pointer to the menuitem entry as data. This pointer may be used to +provide userdata to each entry. The pointer must utilize WS_DLL_PUBLIC_DEF +and has the following structure: + + WS_DLL_PUBLIC_DEF void + menu_cb(ext_menubar_gui_type gui_type, void *gui_data, + void *user_data _U_) + { + ... Do something ... + } + +The menu entries themselves are generated with the following code structure: + + ext_menu_t * ext_menu, *os_menu = NULL; + + ext_menu = ext_menubar_register_menu ( + <your_proto_item>, "Some Menu Entry", true ); + ext_menubar_add_entry(ext_menu, "Test Entry 1", + "This is a tooltip", menu_cb, <user_data>); + ext_menubar_add_entry(ext_menu, "Test Entry 2", + NULL, menu_cb, <user_data>); + + os_menu = ext_menubar_add_submenu(ext_menu, "Sub Menu" ); + ext_menubar_add_entry(os_menu, "Test Entry A", + NULL, menu_cb, <user_data>); + ext_menubar_add_entry(os_menu, "Test Entry B", + NULL, menu_cb, <user_data>); + +For a more detailed information, please refer to plugin_if.h + +6.2 Implement interactions with the main interface + +Due to memory constraints on most platforms, plugin functionality cannot be +called directly from a DLL context. Instead special functions will be used, +which will implement certain options for plugins to utilize. + +The following methods exist so far: + + /* Applies the given filter string as display filter */ + WS_DLL_PUBLIC void plugin_if_apply_filter + (const char * filter_string, bool force); + + /* Saves the given preference to the main preference storage */ + WS_DLL_PUBLIC void plugin_if_save_preference + (const char * pref_module, const char * pref_key, const char * pref_value); + + /* Jumps to the given frame number */ + WS_DLL_PUBLIC void plugin_if_goto_frame(uint32_t framenr); + +6.3 Implement a plugin specific toolbar + +A toolbar may be registered which allows implementing an interactive user +interaction with the main application. The toolbar is generated using the following +code: + + ext_toolbar_t * tb = ext_toolbar_register_toolbar("Plugin Interface Demo Toolbar"); + +This registers a toolbar, which will be shown underneath "View->Additional Toolbars" in +the main menu, as well as the popup action window when right-clicking on any other tool- +or menubar. + +It behaves identically to the existing toolbars and can be hidden as well as defined to +appear specific to selected profiles. The name with which it is being shown is the given +name in this function call. + +6.3.1 Register elements for the toolbar + +To add items to the toolbar, 4 different types of elements do exist. + + * BOOLEAN - a checkbox to select / unselect + * BUTTON - a button to click + * STRING - a text field with validation options + * SELECTOR - a dropdown selection field + +To add an element to the toolbar, the following function is being used: + + ext_toolbar_add_entry( ext_toolbar_t * parent, ext_toolbar_item_t type, const char *label, + const char *defvalue, const char *tooltip, bool capture_only, GList * value_list, + bool is_required, const char * regex, ext_toolbar_action_cb callback, void *user_data) + + parent_bar - the parent toolbar for this entry, to be registered by ext_toolbar_register_toolbar + name - the entry name (the internal used one) for the item, used to send updates to the element + label - the entry label (the displayed name) for the item, visible to the user + defvalue - the default value for the toolbar element + - EXT_TOOLBAR_BOOLEAN - 1 is for a checked element, 0 is unchecked + - EXT_TOOLBAR_STRING - Text already entered upon initial display + tooltip - a tooltip to be displayed on mouse-over + capture_only - entry is only active, if a capture is active + callback - the action which will be invoked after the item is activated + value_list - a non-null list of values created by ext_toolbar_add_val(), if the item type + is EXT_TOOLBAR_SELECTOR + valid_regex - a validation regular expression for EXT_TOOLBAR_STRING + is_required - a zero entry for EXT_TOOLBAR_STRING is not allowed + user_data - a user defined pointer, which will be added to the toolbar callback + +In case of the toolbar type EXT_TOOLBAR_SELECTOR a value list has to be provided. This list +is generated using ext_toolbar_add_val(): + + GList * entries = 0; + entries = ext_toolbar_add_val(entries, "1", "ABCD", false ); + entries = ext_toolbar_add_val(entries, "2", "EFG", false ); + entries = ext_toolbar_add_val(entries, "3", "HIJ", true ); + entries = ext_toolbar_add_val(entries, "4", "KLM", false ); + +6.3.2 Callback for activation of an item + +If an item has been activated, the provided callback is being triggered. + + void toolbar_cb(void *toolbar_item, void *item_data, void *user_data) + +For EXT_TOOLBAR_BUTTON the callback is triggered upon a click on the button, for +EXT_TOOLBAR_BOOLEAN and EXT_TOOLBAR_SELECTOR the callback is triggered with every change +of the selection. + +For EXT_TOOLBAR_STRING either the return key has to be hit or the apply button pressed. + +The parameters of the callback are defined as follows: + + toolbar_item - an element of the type ext_toolbar_t * representing the item that has been + activated + item_data - the data of the item during activation. The content depends on the item type: + - EXT_TOOLBAR_BUTTON - the entry is null + - EXT_TOOLBAR_BOOLEAN - the entry is 0 if the checkbox is unchecked and 1 if it is checked + - EXT_TOOLBAR_STRING - a string representing the context of the textbox. Only valid strings + are being passed, it can be safely assumed, that an applied regular expression has + been checked. + - EXT_TOOLBAR_SELECTOR - the value of the selected entry + user_data - the data provided during element registration + +6.3.3 Sending updates to the toolbar items + +A plugin may send updates to the toolbar entry, using one of the following methods. The parameter +silent defines, if the registered toolbar callback is triggered by the update or not. + + void ext_toolbar_update_value(ext_toolbar_t * entry, void *data, bool silent) + + - EXT_TOOLBAR_BUTTON, EXT_TOOLBAR_STRING - the displayed text (on the button or in the textbox) + are being changed, in that case data is expected to be a string + - EXT_TOOLBAR_BOOLEAN - the checkbox value is being changed, to either 0 or 1, in both cases + data is expected to be an integer sent by GINT_TO_POINTER(n) + - EXT_TOOLBAR_SELECTOR - the display text to be changed. If no element exists with this text, + nothing will happen + + void ext_toolbar_update_data(ext_toolbar_t * entry, void *data, bool silent) + + - EXT_TOOLBAR_SELECTOR - change the value list to the one provided with data. Attention! this + does not change the list stored within the item just the one in the displayed combobox + + void ext_toolbar_update_data_by_index(ext_toolbar_t * entry, void *data, void *value, + bool silent) + + - EXT_TOOLBAR_SELECTOR - change the display text for the entry with the provided value. Both + data and value must be char * pointer. + + +---------------- + +Ed Warnicke <hagbard@physics.rutgers.edu> +Guy Harris <guy@alum.mit.edu> + +Derived and expanded from the plugin section of README.developers +which was originally written by + +James Coe <jammer@cin.net> +Gilbert Ramirez <gram@alumni.rice.edu> +Jeff Foster <jfoste@woodward.com> +Olivier Abad <oabad@cybercable.fr> +Laurent Deniel <laurent.deniel@free.fr> +Jaap Keuter <jaap.keuter@xs4all.nl> diff --git a/doc/README.regression b/doc/README.regression new file mode 100644 index 0000000..2f2b5cd --- /dev/null +++ b/doc/README.regression @@ -0,0 +1,76 @@ +# +# Wireshark/TShark Regression Testing +# +# This is a sample Makefile for regression testing of the +# Wireshark engine. These tests use that uses 'tshark -V' to analyze all +# the frames of a capture file. +# +# You should probably rename this file as 'Makefile' in a separate directory +# set aside for the sole purpose of regression testing. Two text files will +# be created for each capture file you test, so expect to have lots of files. +# +# Set TSHARK, CAPTURE_DIR, and CAPTURE_FILES to values appropriate for +# your system. Run 'make' to create the initial datasets. Type 'make accept' +# to accept those files as the reference set. +# +# After you make changes to TShark, run 'make regress'. This will re-run +# the tests and compare them against the accepted reference set of data. +# The comparison, which is just an invocation of 'diff -u' for the output +# of each trace file, will be put into a file called 'regress'. Examine +# this file for any changes that you did or did not expect. +# +# If you have introduced a change to TShark that shows up in the tests, but +# it is a valid change, run 'make accept' to accept those new data as your +# reference set. +# +# Commands: +# +# 'make' Creates tests +# 'make regress' Checks tests against accepted reference test results +# Report is put in file 'regress' +# 'make accept' Accept current tests; make them the reference test results +# 'make clean' Cleans any tests (but not references!) + +TSHARK=/home/gram/prj/wireshark/debug/linux-ix86/tshark + +CAPTURE_DIR=/home/gram/prj/sniff + +CAPTURE_FILES=\ + dhcp-g.tr1 \ + genbroad.snoop \ + ipv6-ripng.gz \ + ipx.pcap \ + pcmjh03.tr1 \ + strange.iptrace \ + teardrop.toshiba.gz \ + zlip-1.pcap \ + zlip-2.pcap \ + zlip-3.pcap + +######################################## No need to modify below this line + +TESTS = $(CAPTURE_FILES:=.tether) +REFERENCES = $(TESTS:.tether=.ref) + +all: $(TESTS) + +clean: + rm -f $(TESTS) + +%.tether : $(CAPTURE_DIR)/% $(TSHARK) + $(TSHARK) -V -n -r $< > $@ + +accept: $(REFERENCES) + +%.ref : %.tether + mv $< $@ + +regress: $(TESTS) + @echo "Regression Report" > regress + @date >> regress + @echo "BOF------------------------------------" >> regress + @for file in $(CAPTURE_FILES); do \ + echo Checking regression of $$file ; \ + diff -u $${file}.ref $${file}.tether >> regress ; \ + done + @echo "EOF------------------------------------" >> regress diff --git a/doc/README.request_response_tracking b/doc/README.request_response_tracking new file mode 100644 index 0000000..9660a62 --- /dev/null +++ b/doc/README.request_response_tracking @@ -0,0 +1,171 @@ +1. Introduction + +It is often useful to enhance dissectors for request/response style protocols +to match requests with responses. +This allows you to display useful information in the decode tree such as which +requests are matched to which response and the response time for individual +transactions. + +This is also useful if you want to pass some data from the request onto the +dissection of the actual response. The RPC dissector for example does +something like this to pass the actual command opcode from the request onto +the response dissector since the opcode itself is not part of the response +packet and without the opcode we would not know how to decode the data. + +It is also useful when you need to track information on a per conversation +basis such as when some parameters are negotiated during a login phase of the +protocol and when these parameters affect how future commands on that session +are to be decoded. The iSCSI dissector does something similar to that to track +which sessions that HeaderDigest is activated for and which ones it is not. + +2. Implementation + +The example below shows how simple this is to add to the dissector IF: +1. there is something like a transaction id in the header, +2. it is very unlikely that the transaction identifier is reused for the + same conversation. + +The example is taken from the PANA dissector: + +First we need to include the definitions for conversations. + + #include <epan/conversation.h> + +Then we also need a few header fields to show the relations between request +and response as well as the response time. + + static int hf_pana_response_in = -1; + static int hf_pana_response_to = -1; + static int hf_pana_response_time = -1; + +We need a structure that holds all the information we need to remember +between the request and the responses. One such structure will be allocated +for each unique transaction. +In the example we only keep the frame numbers of the request and the response +as well as the timestamp for the request. +But since this structure is persistent and also a unique one is allocated for +each request/response pair, this is a good place to store other additional +data you may want to keep track of from a request to a response. + + typedef struct _pana_transaction_t { + uint32_t req_frame; + uint32_t rep_frame; + nstime_t req_time; + } pana_transaction_t; + +We also need a structure that holds persistent information for each +conversation. A conversation is identified by SRC/DST address, protocol and +SRC/DST port, see README.dissector, section 2.2. +In this case we only want to have a hash table to track the actual +transactions that occur for this unique conversation. +Some protocols negotiate session parameters during a login phase and those +parameters may affect how later commands on the same session is to be decoded, +this would be a good place to store that additional info you may want to keep +around. + + typedef struct _pana_conv_info_t { + wmem_map_t *pdus; + } pana_conv_info_t; + +Finally for the meat of it, add the conversation and tracking code to the +actual dissector. + + ... + uint32_t seq_num; + conversation_t *conversation; + pana_conv_info_t *pana_info; + pana_transaction_t *pana_trans; + + ... + /* Get the transaction identifier */ + seq_num = tvb_get_ntohl(tvb, 8); + ... + + /* + * We need to track some state for this protocol on a per conversation + * basis so we can do neat things like request/response tracking + */ + conversation = find_or_create_conversation(pinfo); + + /* + * Do we already have a state structure for this conv + */ + pana_info = (pana_conv_info_t *)conversation_get_proto_data(conversation, proto_pana); + if (!pana_info) { + /* + * No. Attach that information to the conversation, and add + * it to the list of information structures. + */ + pana_info = wmem_new(wmem_file_scope(), pana_conv_info_t); + pana_info->pdus=wmem_map_new(wmem_file_scope(), g_direct_hash, g_direct_equal); + + conversation_add_proto_data(conversation, proto_pana, pana_info); + } + if (!PINFO_FD_VISITED(pinfo)) { + if (flags&PANA_FLAG_R) { + /* This is a request */ + pana_trans=wmem_new(wmem_file_scope(), pana_transaction_t); + pana_trans->req_frame = pinfo->num; + pana_trans->rep_frame = 0; + pana_trans->req_time = pinfo->fd->abs_ts; + wmem_map_insert(pana_info->pdus, GUINT_TO_POINTER(seq_num), (void *)pana_trans); + } else { + pana_trans=(pana_transaction_t *)wmem_map_lookup(pana_info->pdus, GUINT_TO_POINTER(seq_num)); + if (pana_trans) { + pana_trans->rep_frame = pinfo->num; + } + } + } else { + pana_trans=(pana_transaction_t *)wmem_map_lookup(pana_info->pdus, GUINT_TO_POINTER(seq_num)); + } + if (!pana_trans) { + /* create a "fake" pana_trans structure */ + pana_trans=wmem_new(pinfo->pool, pana_transaction_t); + pana_trans->req_frame = 0; + pana_trans->rep_frame = 0; + pana_trans->req_time = pinfo->fd->abs_ts; + } + + /* print state tracking in the tree */ + if (flags&PANA_FLAG_R) { + /* This is a request */ + if (pana_trans->rep_frame) { + proto_item *it; + + it = proto_tree_add_uint(pana_tree, hf_pana_response_in, + tvb, 0, 0, pana_trans->rep_frame); + proto_item_set_generated(it); + } + } else { + /* This is a reply */ + if (pana_trans->req_frame) { + proto_item *it; + nstime_t ns; + + it = proto_tree_add_uint(pana_tree, hf_pana_response_to, + tvb, 0, 0, pana_trans->req_frame); + proto_item_set_generated(it); + + nstime_delta(&ns, &pinfo->fd->abs_ts, &pana_trans->req_time); + it = proto_tree_add_time(pana_tree, hf_pana_response_time, tvb, 0, 0, &ns); + proto_item_set_generated(it); + } + } + +Then we just need to declare the hf fields we used. + + { &hf_pana_response_in, + { "Response In", "pana.response_in", + FT_FRAMENUM, BASE_NONE, FRAMENUM_TYPE(FT_FRAMENUM_RESPONSE), 0x0, + "The response to this PANA request is in this frame", HFILL } + }, + { &hf_pana_response_to, + { "Request In", "pana.response_to", + FT_FRAMENUM, BASE_NONE, FRAMENUM_TYPE(FT_FRAMENUM_REQUEST), 0x0, + "This is a response to the PANA request in this frame", HFILL } + }, + { &hf_pana_response_time, + { "Response Time", "pana.response_time", + FT_RELATIVE_TIME, BASE_NONE, NULL, 0x0, + "The time between the Call and the Reply", HFILL } + }, diff --git a/doc/README.stats_tree b/doc/README.stats_tree new file mode 100644 index 0000000..1b7e69e --- /dev/null +++ b/doc/README.stats_tree @@ -0,0 +1,238 @@ +tapping with stats_tree + +Let's suppose that you want to write a tap only to keep counters, and you +don't want to get involved with GUI programming or maybe you'd like to make +it a plugin. A stats_tree might be the way to go. The stats_tree module takes +care of the representation (GUI for Wireshark and text for TShark) of the +tap data. So there's very little code to write to make a tap listener usable +from both Wireshark and TShark. + +First, you should add the TAP to the dissector in question as described in +README.tapping . + +Once the dissector in question is "tapped" you have to write the stats tree +code which is made of three parts: + +The init callback routine: + which will be executed before any packet is passed to the tap. Here you + should create the "static" nodes of your tree. As well as initialize your + data. + +The (per)packet callback routine: + As the tap_packet callback is going to be called for every packet, it + should be used to increment the counters. + +The cleanup callback: + It is called at the destruction of the stats_tree and might be used to + free .... + +Other than that the stats_tree should be registered. + +If you want to make it a plugin, stats_tree_register() should be called by +plugin_register_tap_listener() read README.plugins for other information +regarding Wireshark plugins. + +If you want it as part of the dissector stats_tree_register() can be called +either by proto_register_xxx() or if you prefer by proto_reg_handoff_xxx(). + + +A small example of a very basic stats_tree plugin follows. + +----- example stats_tree plugin ------ +/* udpterm_stats_tree.c + * A small example of stats_tree plugin that counts udp packets by termination + * 2005, Luis E. G. Ontanon + * + * Wireshark - Network traffic analyzer + * By Gerald Combs <gerald@wireshark.org> + * Copyright 1998 Gerald Combs + * + * SPDX-License-Identifier: GPL-2.0-or-later + */ + +#include "config.h" + +#include <gmodule.h> + +#include <epan/stats_tree.h> +#include <epan/dissectors/udp.h> + +static int st_udp_term; +static char* st_str_udp_term = "UDP terminations"; + +/* this one initializes the tree, creating the root nodes */ +extern void udp_term_stats_tree_init(stats_tree* st) { + /* we create a node under which we'll add every termination */ + st_udp_term = stats_tree_create_node(st, st_str_udp_term, 0, STAT_DT_INT, true); +} + +/* this one will be called with every udp packet */ +extern tap_packet_status +udp_term_stats_tree_packet(stats_tree *st, /* st as it was passed to us */ + packet_info *pinfo, /* we'll fetch the addresses from here */ + epan_dissect_t *edt _U_, /* unused */ + const void *p) /* we'll use this to fetch the ports */ +{ + static uint8_t str[128]; + e_udphdr* udphdr = (e_udphdr*) p; + + /* we increment by one (tick) the root node */ + tick_stat_node(st, st_str_udp_term, 0, false); + + /* we then tick a node for this src_addr:src_port + if the node doesn't exists it will be created */ + snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_src),udphdr->sport); + tick_stat_node(st, str, st_udp_term, false); + + /* same thing for dst */ + snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_dst),udphdr->dport); + tick_stat_node(st, str, st_udp_term, false); + + return 1; +} + +WS_DLL_PUBLIC_DEF const char version[] = "0.0"; + +WS_DLL_PUBLIC_DEF void plugin_register_tap_listener(void) { + + stats_tree_register_plugin("udp", /* the proto we are going to "tap" */ + "udp_terms", /* the abbreviation for this tree (to be used as -z udp_terms,tree) */ + st_str_udp_term, /* the name of the menu and window (use "/" for sub menus)*/ + 0, /* tap listener flags for per-packet callback */ + udp_term_stats_tree_packet, /* the per packet callback */ + udp_term_stats_tree_init, /* the init callback */ + NULL ); /* the cleanup callback (in this case there isn't) */ + +} + +----- END ------ + +the stats_tree API +================== + every stats_tree callback has a stats_tree* parameter (st), stats_tree is an obscure + data structure which should be passed to the api functions. + +stats_tree_register(tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb); + registers a new stats tree with default group REGISTER_STAT_GROUP_UNSORTED + +stats_tree_register_plugin(tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb); + registers a new stats tree from a plugin with the default group + +stats_tree_register_with_group(tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb, stat_group); + registers a new stats tree under a particular stat group + +stats_tree_parent_id_by_name( st, parent_name) + returns the id of a candidate parent node given its name + + +Node functions +============== + +All the functions that operate on nodes return a parent_id + +stats_tree_create_node(st, name, parent_id, datatype, with_children) + Creates a node in the tree (to be used in the in init_cb) + name: the name of the new node + parent_id: the id of the parent_node (NULL for root) + datatype: datatype of the new node, STAT_DT_INT or STAT_DT_FLOAT. The only + methods implemented for floats are averages. + with_children: true if this node will have "dynamically created" children + (i.e. it will be a candidate parent) + + +stats_tree_create_node_by_pname(st, name, parent_name, datatype, with_children); + As before but creates a node using its parent's name + + +stats_tree_create_range_node(st, name, parent_id, ...) +stats_tree_create_range_node_string(st, name, parent_id, num_str_ranges, str_ranges) +stats_tree_range_node_with_pname(st, name, parent_name, ...) + Creates a node in the tree, that will contain a ranges list. + example: + stats_tree_create_range_node(st,name,parent_id, + "-99","100-199","200-299","300-399","400-", NULL); + +stats_tree_tick_range(st, name, parent_id, value_in_range); +stats_tree_tick_range_by_pname(st, name, parent_name, value_in_range) + Increases by one the ranged node and the sub node to whose range the value belongs + + +stats_tree_create_pivot(st, name, parent_id); +stats_tree_create_pivot_by_pname(st, name, parent_name); + Creates a "pivot node" + +stats_tree_tick_pivot(st, pivot_id, pivoted_string); + Each time a pivot node will be ticked it will get increased, and, it will + increase (or create) the children named as pivoted_string + +the following will either increase or create a node (with value 1) when called + +tick_stat_node(st, name, parent_id, with_children) +increases by one a stat_node + +increase_stat_node(st, name, parent_id, with_children, value) +increases by value a stat_node + +set_stat_node(st, name, parent_id, with_children, value) +sets the value of a stat_node + +zero_stat_node(st, name, parent_id, with_children) +resets to zero a stat_node + +Averages work by tracking both the number of items added to node (the ticking +action) and the value of each item added to the node. This is done +automatically for ranged nodes; for other node types you need to call one of +the functions below to associate item values with each tick. + +avg_stat_node_add_value_notick(st, name, parent_id, with_children, value) +avg_stat_node_add_value_int(st, name, parent_id, with_children, value) +avg_stat_node_add_value_float(st, name, parent_id, with_children, value) + +The difference between the above functions is whether the item count is +increased or not. To properly compute the average you need to either call +avg_stat_node_add_value or avg_stat_node_add_value_notick combined +tick_stat_node. The later sequence allows for plug-ins which are compatible +with older Wireshark versions which ignores avg_stat_node_add_value because +it does not understand the command. This would result in 0 counts for all +nodes. It is preferred to use avg_stat_node_add_value if you are not writing +a plug-in. + +avg_stat_node_add_value_int is used the same way as tick_stat_node with the +exception that you now specify an additional value associated with the tick. + +avg_stat_node_add_value_float is used to compute averages of floats, for nodes +with the STAT_DT_FLOAT datatype. + +Do not mix increase_stat_node, set_stat_node or zero_stat_node +with avg_stat_node_add_value_int as this will lead to incorrect results for the +average value. + +stats_tree now also support setting flags per node to control the behaviour +of these nodes. This can be done using the stat_node_set_flags and +stat_node_clear_flags functions. Currently these flags are defined: + + ST_FLG_DEF_NOEXPAND: By default the top-level nodes in a tree are + automatically expanded in the GUI. Setting this flag on + such a node prevents the node from automatically + expanding. + ST_FLG_SORT_TOP: Nodes with this flag is sorted separately from nodes + without this flag (in effect partitioning tree into a top + and bottom half. Each half is sorted normally. Top always + appear first :) + +The same node manipulations can also be performed via generic functions: + +stats_tree_manip_node_int(mode, st, name, parent_id, with_children, value); +stats_tree_manip_node_float(mode, st, name, parent_id, with_children, value); + +mode is an enum with the following set of values: + MN_INCREASE + MN_SET + MN_AVERAGE + MN_AVERAGE_NOTICK + MN_SET_FLAGS + MN_CLEAR_FLAGS + +You can find more examples of these in $srcdir/plugins/epan/stats_tree/pinfo_stats_tree.c + +Luis E. G. Ontanon. diff --git a/doc/README.tapping b/doc/README.tapping new file mode 100644 index 0000000..4fcb638 --- /dev/null +++ b/doc/README.tapping @@ -0,0 +1,244 @@ +The TAP system in Wireshark is a powerful and flexible mechanism to get event +driven notification on packets matching certain protocols and/or filters. +In order to use the tapping system, very little knowledge of Wireshark +internals is required. + +As examples on how to use the tap system see the implementation of +tap-rpcprogs.c (tshark version) +ui/qt/rpc_service_response_time_dialog.cpp (wireshark version) + +If all you need is to keep some counters, there's the stats_tree API, +which offers a simple way to make a GUI and tshark tap-listener; see +README.stats_tree. However, keep reading, as you'll need much of what's +in this document. + +The tap system consists of two parts: +1, code in the actual dissectors to allow tapping data from that particular +protocol dissector, and +2, event driven code in an extension such as tap-rpcstat.c that registers +a tap listener and processes received data. + +So you want to hack together a tap application? + +TAP +=== +First you must decide which protocol you are interested in writing a tap +application for and check if that protocol has already got a tap installed +in it. +If it already has a tap device installed then you don't have to do anything. +If not, then you have to add a tap but don't worry, this is extremely easy to +do and is done in four easy steps; +(see packet-rpc.c and search for tap for an example) + +1, We need tap.h so just add '#include <epan/tap.h>' (preceded by packet.h) to +the includes. + +2, We need a tap handler so just add 'static int <protocol>_tap = -1;' + +3, Down in proto_register_<protocol>() you need to add +'<protocol>_tap = register_tap("<protocol>");' + +4, In the actual dissector for that protocol, after any child dissectors +have returned, just add 'tap_queue_packet(<protocol>_tap, pinfo, <pointer>);' + +<pointer> is used if the tap has any special additional data to provide to the +tap listeners. What this points to is dependent on the protocol that is tapped, +or if there is no useful extra data to provide, just specify NULL. For +packet-rpc.c what we specify there is the persistent structure 'rpc_call' which +contains lots of useful information from the rpc layer that a listener might +need. + + + +TAP LISTENER +============ +(see tap-rpcprogs.c as an example) +Interfacing your application is not that much harder either. +Only 4 callbacks and two functions. + +The two functions to start or stop tapping are + +register_tap_listener(const char *tapname, void *tapdata, const char *fstring, + unsigned flags, + void (*reset)(void *tapdata), + tap_packet_status (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data), + void (*draw)(void *tapdata), + void (*finish)(void *tapdata)); + +This function is used to register an instance of a tap application +to the tap system. + +remove_tap_listener(void *tapdata); + +This function is used to deregister and stop a tap listener. + +The parameters have the following meanings: + +*tapname +is the name of the tap we want to listen to. I.e. the name used in +step 3 above. + +*tapdata +is the instance identifier. The tap system uses the value of this +pointer to distinguish between different instances of a tap. +Just make sure that it is unique by letting it be the pointer to a struct +holding all state variables. If you want to allow multiple concurrent +instances, just put ALL state variables inside a struct allocated by +g_new() and use that pointer. +(tap-rpcstat.c use this technique to allow multiple simultaneous instances) + +*fstring +is a pointer to a filter string. +If this is NULL, then the tap system will provide ALL packets passing the +tapped protocol to your listener. +If you specify a filter string here the tap system will first try +to apply this string to the packet and then only pass those packets that +matched the filter to your listener. +The syntax for the filter string is identical to normal display filters. + +NOTE: Specifying filter strings will have a significant performance impact +on your application and Wireshark. If possible it is MUCH better to take +unfiltered data and just filter it yourself in the packet-callback than +to specify a filter string. +ONLY use a filter string if no other option exist. + +flags +is a set of flags for the tap listener. The flags that can be set are: + + TL_REQUIRES_PROTO_TREE + + set if your tap listener "packet" routine requires a protocol + tree to be built. It will require a protocol tree to be + built if either + + 1) it looks at the protocol tree in edt->tree + + or + + 2) the tap-specific data passed to it is constructed only if + the protocol tree is being built. + + TL_REQUIRES_COLUMNS + + set if your tap listener "packet" routine requires the column + strings to be constructed. + + TL_REQUIRES_ERROR_PACKET + + set if your tap listener should be updated even when pinfo->flags.in_error_pkt is set + e.g. if it is inside an ICMP unreachable packet + + If no flags are needed, use TL_REQUIRES_NOTHING. + +void (*reset)(void *tapdata) +This callback is called whenever Wireshark wants to inform your +listener that it is about to start [re]reading a capture file or a new capture +from an interface and that your application should reset any state it has +in the *tapdata instance. + +tap_packet_status (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data) +This callback is used whenever a new packet has arrived at the tap and that +it has passed the filter (if there was a filter). +The *data structure type is specific to each tap. +This function returns a tap_packet_status enum and it should return + TAP_PACKET_REDRAW, if the data in the packet caused state to be updated + (and thus a redraw of the window would later be required) + TAP_PACKET_DONT_REDRAW, if we don't need to redraw the window + TAP_PACKET_FAILED, if the tap failed and shouldn't be called again + in this pass (for example, if it's writing to a file and gets + an I/O error) +NOTE: that (*packet) should be as fast and efficient as possible. Use this +function ONLY to store data for later and do the CPU-intensive processing +or GUI updates down in (*draw) instead. + + +void (*draw)(void *tapdata) +This callback is used when Wireshark wants your application to redraw its +output. It will usually not be called unless your application has received +new data through the (*packet) callback. +On some ports of Wireshark (Qt) (*draw) will be called asynchronously +from a separate thread up to once every 2-3 seconds. +On other ports it might only be called once when the capture is finished +or the file has been [re]read completely. + +void (*finish)(void *tapdata) +This callback is called when your listener is removed. + + +So, create four callbacks: +1, reset to reset the state variables in the structure passed to it. +2, packet to update these state variables. +3, draw to take these state variables and draw them on the screen. +4, finish to free all state variables. + +then just make Wireshark call register_tap_listener() when you want to tap +and call remove_tap_listener() when you are finished. + + +WHEN DO TAP LISTENERS GET CALLED? +=================================== +Tap listeners are only called when Wireshark reads a new capture for +the first time or whenever Wireshark needs to rescan/redissect +the capture. +Redissection occurs when you apply a new display filter or if you +change and Save/Apply a preference setting that might affect how +packets are dissected. +After each individual packet has been completely dissected and all +dissectors have returned, all the tap listeners that have been flagged +to receive tap data during the dissection of the frame will be called in +sequence. +The order in which the tap listeners will be called is not defined. +Not until all tap listeners for the frame has been called and returned +will Wireshark continue to dissect the next packet. +This is why it is important to make the *_packet() callbacks execute as +quickly as possible, else we create an extra delay until the next packet +is dissected. + +Keep in mind though: for some protocols, such as IP, the protocol can +appear multiple times in different layers inside the same packet. +For example, IP encapsulated over IP which will call the ip dissector +twice for the same packet. +IF the tap is going to return private data using the last parameter to +tap_queue_packet() and IF the protocol can appear multiple times inside the +same packet, you will have to make sure that each instance of +tap_queue_packet() is using its own instance of private struct variable +so they don't overwrite each other. + +See packet-ip.c which has a simple solution to the problem. It creates +a unique instance of the IP header using wmem_alloc(). +Previous versions used a static struct of 4 instances of the IP header +struct and cycled through them each time the dissector was called. (4 +was just a number taken out of the blue but it should be enough for most +cases.) This would fail if there were more than 4 IP headers in the same +packet, but that was unlikely. + + +TIPS +==== +Of course, there is nothing that forces you to make (*draw) draw stuff +on the screen. +You can hand register_tap_listener() NULL for (*draw), (*reset) and (*finish) +(well also for (*packet) but that would be a very boring extension). + +Perhaps you want an extension that will execute a certain command +every time it sees a certain packet? +Well, try this : + tap_packet_status packet(void *tapdata,...) { + ... + system("mail ..."); + return TAP_PACKET_DONT_REDRAW; + } + + register_tap_listener("tcp", struct, "tcp.port==57", NULL, packet, NULL, NULL); + + Let struct contain an email address? + Then you have something simple that will make Wireshark send an email + out automagically for each and every time it dissects + a packet containing TCP traffic to port 57. + Please put in some rate limitation if you do this. + + Let struct contain a command line and make (*packet) execute it? + The possibilities are rather large. + +See tap.c as well. It contains lots of comments and descriptions on the tap +system. diff --git a/doc/README.vagrant b/doc/README.vagrant new file mode 100644 index 0000000..88ff1a8 --- /dev/null +++ b/doc/README.vagrant @@ -0,0 +1,86 @@ +1. Introduction + +Vagrant is a virtual machine management program that makes it trivial to build +and configure reproducible virtual machines. Wireshark's source code includes +a Vagrantfile which can be used to set up a complete development environments +in a virtual machine, including all necessary compilers, dependent libraries, +and tools like valgrind. + +Using vagrant can greatly simplify the creation of a Linux build environment +for new developers, at the cost of running your builds in a virtual machine, +thus with reduced performance. + +2. Installation + +The Vagrantfile included in Wireshark's source directory is configured to use +VirtualBox as the backing virtual machine technology provider. You must first +install VirtualBox from https://www.virtualbox.org/. + +Now install vagrant itself from https://www.vagrantup.com/. + +Please note that vagrant is a CLI command and should typically be installed in +your host system's $PATH. To better understand what vagrant is doing you may +want to review vagrant's `Getting Started` web pages. + +3. Setup + +By default vagrant looks for the file name Vagrantfile in the current +directory. Wireshark's Vagrantfile is located in the root of the Wireshark +source folder. + +Once both VirtualBox and vagrant are installed, setting up an Ubuntu Wireshark +development VM is as simple as running `vagrant up ubuntu`. + +The first time that the `vagrant up` command is executed vagrant will initiate +the download of a specific VM image (what they call a box) from HashiCorp's +Atlas box catalog. Once the box is downloaded a VM will be instantiated and +powered-on. + +Use the command `vagrant status` to determine the state of the VMs. + +The command `vagrant provision` will run any provisioning tasks defined in the +Vagrantfile. Wireshark's Vagrantfile is configured to provision the machine +and build the project using vagrant_build.sh. + +The vagrant_build.sh script sets up a cmake +build environment which includes creating a ~/build folder initialized for an +out-of-tree cmake build and then triggering a build. + +4. Usage + +Running `vagrant ssh ubuntu` from the Wireshark source directory will log you +into Ubuntu VM as the userid vagrant. + +The Ubuntu VM's build folder is located in ~/build. The Ubuntu VM's source +folder is actually the source folder from the host system mounted as +/home/vagrant/wireshark. Any changes made in the VM's ~/wireshark folder are +reflected in the host system's Wireshark source folder and vice-versa. + +Installing the vagrant-vbguest plugin is strongly recommended to get synced +folders working on all boxes and other niceties. You can install it with the +command `vagrant plugin install vagrant-vbguest`. + +Once logged into the VM issue the command `cd ~/build` followed by `make` to +trigger a new wireshark build based on whatever is in your host system's source +tree (the VM's ~/wireshark folder). + +The various Wireshark applications can be run from the ~/build folder of the +VM with commands such as `./run/wireshark`, `./run/tshark`, etc. + +To run the Wireshark GUI you will need an X server and the X authority file +utility (xauth) installed in the guest. For Ubuntu use `apt-get install xauth`, +Fedora use `dnf install xorg-x11-xauth`. + +If you are using macOS ({Mac} OS X) as the host system then you would likely +use XQuartz as your X server. XQuartz can be downloaded from +https://www.xquartz.org/. + +The VM can be shutdown or suspended from the host system with the +commands `vagrant halt` and `vagrant suspend` respectively. In either case the +VM can be brought back up with the command `vagrant up`. + +5. Using Vagrant with multiple VMs +Wireshark's Vagrantfile is configured with more than one box so most vagrant +commands, those that apply to machines, need to be provided with the machine +name. You can list all machines and their state with the `vagrant status` +command. diff --git a/doc/README.wmem b/doc/README.wmem new file mode 100644 index 0000000..8473a23 --- /dev/null +++ b/doc/README.wmem @@ -0,0 +1,402 @@ +1. Introduction + +The 'wmem' memory manager is Wireshark's memory management framework, replacing +the old 'emem' framework which was removed in Wireshark 2.0. + +In order to make memory management easier and to reduce the probability of +memory leaks, Wireshark provides its own memory management API. This API is +implemented inside wsutil/wmem/ and provides memory pools and functions that make +it easy to manage memory even in the face of exceptions (which many dissector +functions can raise). Memory scopes for dissection are defined in epan/wmem_scopes.h. + +Correct use of these functions will make your code faster, and greatly reduce +the chances that it will leak memory in exceptional cases. + +Wmem was originally conceived in this email to the wireshark-dev mailing list: +https://www.wireshark.org/lists/wireshark-dev/201210/msg00178.html + +2. Usage for Consumers + +If you're writing a dissector, or other "userspace" code, then using wmem +should be very similar to using malloc or g_malloc or whatever else you're used +to. All you need to do is include the header (epan/wmem_scopes.h) and optionally +get a handle to a memory pool (if you want to *create* a memory pool, see the +section "3. Usage for Producers" below). + +A memory pool is an opaque pointer to an object of type wmem_allocator_t, and +it is the very first parameter passed to almost every call you make to wmem. +Other than that parameter (and the fact that functions are prefixed wmem_) +usage is very similar to glib and other utility libraries. For example: + + wmem_alloc(myPool, 20); + +allocates 20 bytes in the pool pointed to by myPool. + +2.1 Memory Pool Lifetimes + +Every memory pool should have a defined lifetime, or scope, after which all the +memory in that pool is unconditionally freed. When you choose to allocate memory +in a pool, you *must* be aware of its lifetime: if the lifetime is shorter than +you need, your code will contain use-after-free bugs; if the lifetime is longer +than you need, your code may contain undetectable memory leaks. In either case, +the risks outweigh the benefits. + +If no pool exists whose lifetime matches the lifetime of your memory, you have +two options: create a new pool (see section 3 of this document) or use the NULL +pool. Any function that takes a pointer to a wmem_allocator_t can also be passed +NULL instead, in which case the memory is managed manually (just like malloc or +g_malloc). Memory allocated like this *must* be manually passed to wmem_free() +in order to prevent memory leaks (however these memory leaks will at least show +up in valgrind). Note that passing wmem_allocated memory directly to free() +or g_free() is not safe; the backing type of manually managed memory may be +changed without warning. + +2.2 Wireshark Global Pools + +Dissectors that include the wmem_scopes.h header file will have three pools available +to them automatically: pinfo->pool, wmem_file_scope() and +wmem_epan_scope(); there is also a wmem_packet_scope() for cases when the +`pinfo` argument is not accessible, but pinfo->pool should be preferred. + +The pinfo pool is scoped to the dissection of each packet, meaning that any +memory allocated in it will be automatically freed at the end of the current +packet. The file pool is similarly scoped to the dissection of each file, +meaning that any memory allocated in it will be automatically freed when the +current capture file is closed. + +NB: Using these pools outside of the appropriate scope (e.g. using the file + pool when there isn't a file open) will throw an assertion. + See the comment in epan/wmem_scopes.c for details. + +The epan pool is scoped to the library's lifetime - memory allocated in it is +not freed until epan_cleanup() is called, which is typically but not necessarily +at the very end of the program. + +2.3 The Pinfo Pool + +Certain allocations (such as AT_STRINGZ address allocations and anything that +might end up being passed to add_new_data_source) need their memory to stick +around a little longer than the usual packet scope - basically until the +next packet is dissected. This is, in fact, the scope of Wireshark's pinfo +structure, so the pinfo struct has a 'pool' member which is a wmem pool scoped +to the lifetime of the pinfo struct. + +2.4 API + +Full documentation for each function (parameters, return values, behaviours) +lives (or will live) in Doxygen-format in the header files for those functions. +This is just an overview of which header files you should be looking at. + +2.4.1 Core API + +wmem_core.h + - Basic memory management functions (wmem_alloc, wmem_realloc, wmem_free). + +2.4.2 Strings + +wmem_strutl.h + - Utility functions for manipulating null-terminated C-style strings. + Functions like strdup and strdup_printf. + +wmem_strbuf.h + - A managed string object implementation, similar to std::string in C++ or + GString from Glib. + +2.4.3 Container Data Structures + +wmem_array.h + - A growable array (AKA vector) implementation. + +wmem_list.h + - A doubly-linked list implementation. + +wmem_map.h + - A hash map (AKA hash table) implementation. + +wmem_multimap.h + - A hash multimap (map that can store multiple values with the same key) + implementation. + +wmem_queue.h + - A queue implementation (first-in, first-out). + +wmem_stack.h + - A stack implementation (last-in, first-out). + +wmem_tree.h + - A balanced binary tree (red-black tree) implementation. + +2.4.4 Miscellaneous Utilities + +wmem_miscutl.h + - Misc. utility functions like memdup. + +2.5 Callbacks + +WARNING: You probably don't actually need these; use them only when you're + sure you understand the dangers. + +Sometimes (though hopefully rarely) it may be necessary to store data in a wmem +pool that requires additional cleanup before it is freed. For example, perhaps +you have a pointer to a file-handle that needs to be closed. In this case, you +can register a callback with the wmem_register_callback function +declared in wmem_user_cb.h. Every time the memory in a pool is freed, all +registered cleanup functions are called first. + +Note that callback calling order is not defined, you cannot rely on a +certain callback being called before or after another. + +WARNING: Manually freeing or moving memory (with wmem_free or wmem_realloc) + will NOT trigger any callbacks. It is an error to call either of + those functions on memory if you have a callback registered to deal + with the contents of that memory. + +3. Usage for Producers + +NB: If you're just writing a dissector, you probably don't need to read + this section. + +One of the problems with the old emem framework was that there were basically +two allocator backends (glib and mmap) that were all mixed together in a mess +of if statements, environment variables and #ifdefs. In wmem the different +allocator backends are cleanly separated out, and it's up to the owner of the +pool to pick one. + +3.1 Available Allocator Back-Ends + +Each available allocator type has a corresponding entry in the +wmem_allocator_type_t enumeration defined in wmem_core.h. See the doxygen +comments in that header file for details on each type. + +3.2 Creating a Pool + +To create a pool, include the regular wmem header and call the +wmem_allocator_new() function with the appropriate type value. +For example: + + #include <wsutil/wmem/wmem.h> + + wmem_allocator_t *myPool; + myPool = wmem_allocator_new(WMEM_ALLOCATOR_SIMPLE); + +From here on in, you don't need to remember which type of allocator you used +(although allocator authors are welcome to expose additional allocator-specific +helper functions in their headers). The "myPool" variable can be passed around +and used as normal in allocation requests as described in section 2 of this +document. + +3.3 Destroying a Pool + +Regardless of which allocator you used to create a pool, it can be destroyed +with a call to the function wmem_destroy_allocator(). For example: + + #include <wsutil/wmem/wmem.h> + + wmem_allocator_t *myPool; + + myPool = wmem_allocator_new(WMEM_ALLOCATOR_SIMPLE); + + /* Allocate some memory in myPool ... */ + + wmem_destroy_allocator(myPool); + +Destroying a pool will free all the memory allocated in it. + +3.4 Reusing a Pool + +It is possible to free all the memory in a pool without destroying it, +allowing it to be reused later. Depending on the type of allocator, doing this +(by calling wmem_free_all()) can be significantly cheaper than fully destroying +and recreating the pool. This method is therefore recommended, especially when +the pool would otherwise be scoped to a single iteration of a loop. For example: + + #include <wsutil/wmem/wmem.h> + + wmem_allocator_t *myPool; + + myPool = wmem_allocator_new(WMEM_ALLOCATOR_SIMPLE); + for (...) { + + /* Allocate some memory in myPool ... */ + + /* Free the memory, faster than destroying and recreating + the pool each time through the loop. */ + wmem_free_all(myPool); + } + wmem_destroy_allocator(myPool); + +4. Internal Design + +Despite being written in Wireshark's standard C90, wmem follows a fairly +object-oriented design pattern. Although efficiency is always a concern, the +primary goals in writing wmem were maintainability and preventing memory +leaks. + +4.1 struct _wmem_allocator_t + +The heart of wmem is the _wmem_allocator_t structure defined in the +wmem_allocator.h header file. This structure uses C function pointers to +implement a common object-oriented design pattern known as an interface (also +known as an abstract class to those who are more familiar with C++). + +Different allocator implementations can provide exactly the same interface by +assigning their own functions to the members of an instance of the structure. +The structure has eight members in three groups. + +4.1.1 Implementation Details + + - private_data + - type + +The private_data pointer is a void pointer that the allocator implementation can +use to store whatever internal structures it needs. A pointer to private_data is +passed to almost all of the other functions that the allocator implementation +must define. + +The type field is an enumeration of type wmem_allocator_type_t (see +section 3.1). Its value is set by the wmem_allocator_new() function, not +by the implementation-specific constructor. This field should be considered +read-only by the allocator implementation. + +4.1.2 Consumer Functions + + - walloc() + - wfree() + - wrealloc() + +These function pointers should be set to functions with semantics obviously +similar to their standard-library namesakes. Each one takes an extra parameter +that is a copy of the allocator's private_data pointer. + +Note that wrealloc() and wfree() are not expected to be called directly by user +code in most cases - they are primarily optimizations for use by data +structures that wmem might want to implement (it's inefficient, for example, to +implement a dynamically sized array without some form of realloc). + +Also note that allocators do not have to handle NULL pointers or 0-length +requests in any way - those checks are done in an allocator-agnostic way +higher up in wmem. Allocator authors can assume that all incoming pointers +(to wrealloc and wfree) are non-NULL, and that all incoming lengths (to walloc +and wrealloc) are non-0. + +4.1.3 Producer/Manager Functions + + - free_all() + - gc() + - cleanup() + +All of these functions take only one parameter, which is the allocator's +private_data pointer. + +The free_all() function should free all the memory currently allocated in the +pool. Note that this is not necessarily exactly the same as calling free() +on all the allocated blocks - free_all() is allowed to do additional cleanup +or to make use of optimizations not available when freeing one block at a time. + +The gc() function should do whatever it can to reduce excess memory usage in +the dissector by returning unused blocks to the OS, optimizing internal data +structures, etc. + +The cleanup() function should do any final cleanup and free any and all memory. +It is basically the equivalent of a destructor function. For simplicity, wmem +is guaranteed to call free_all() immediately before calling this function. There +is no such guarantee that gc() has (ever) been called. + +4.2 Pool-Agnostic API + +One of the issues with emem was that the API (including the public data +structures) required wrapper functions for each scope implemented. Even +if there was a stack implementation in emem, it wasn't necessarily available +for use with file-scope memory unless someone took the time to write se_stack_ +wrapper functions for the interface. + +In wmem, all public APIs take the pool as the first argument, so that they can +be written once and used with any available memory pool. Data structures like +wmem's stack implementation only take the pool when created - the provided +pointer is stored internally with the data structure, and subsequent calls +(like push and pop) will take the stack itself instead of the pool. + +4.3 Debugging + +The primary debugging control for wmem is the WIRESHARK_DEBUG_WMEM_OVERRIDE +environment variable. If set, this value forces all calls to +wmem_allocator_new() to return the same type of allocator, regardless of which +type is requested normally by the code. It currently has four valid values: + + - The value "simple" forces the use of WMEM_ALLOCATOR_SIMPLE. The valgrind + script currently sets this value, since the simple allocator is the only + one whose memory allocations are trackable properly by valgrind. + + - The value "strict" forces the use of WMEM_ALLOCATOR_STRICT. The fuzz-test + script currently sets this value, since the goal when fuzz-testing is to find + as many errors as possible. + + - The value "block" forces the use of WMEM_ALLOCATOR_BLOCK. This is not + currently used by any scripts, but is useful for stress-testing the block + allocator. + + - The value "block_fast" forces the use of WMEM_ALLOCATOR_BLOCK_FAST. This is + not currently used by any scripts, but is useful for stress-testing the fast + block allocator. + +Note that regardless of the value of this variable, it will always be safe to +call allocator-specific helpers functions. They are required to be safe no-ops +if the allocator argument is of the wrong type. + +4.4 Testing + +There is a simple test suite for wmem that lives in the file wmem_test.c and +should get automatically built into the binary 'wmem_test' when building +Wireshark. It contains at least basic tests for all existing functionality. +The suite is run automatically by the build-bots via the shell script +test/test.py which calls out to test/suite_unittests.py. + +New features added to wmem (allocators, data structures, utility +functions, etc.) MUST also have tests added to this suite. + +The test suite could potentially use a clean-up by someone more +intimately familiar with Glib's testing framework, but it does the job. + +5. A Note on Performance + +Because of my own bad judgment, there is the persistent idea floating around +that wmem is somehow magically faster than other allocators in the general case. +This is false. + +First, wmem supports multiple different allocator backends (see sections 3 and 4 +of this document), so it is confusing and misleading to try and compare the +performance of "wmem" in general with another system anyways. + +Second, any modern system-provided malloc already has a very clever and +efficient allocator algorithm that makes use of blocks, arenas and all sorts of +other fancy tricks. Trying to be faster than libc's allocator is generally a +waste of time unless you have a specific allocation pattern to optimize for. + +Third, while there were historically arguments to be made for putting something +in front of the kernel to reduce the number of context-switches, modern libc +implementations should already do that. Making a dynamic library call is still +marginally more expensive than calling a locally-defined linker-optimized +function, but it's a difference too small to care about. + +With all that said, it is true that *some* of wmem's allocators can be +substantially faster than your standard libc malloc, in *some* use cases: + - The BLOCK and BLOCK_FAST allocators both provide very efficient free_all + operations, which can be many orders of magnitude faster than calling free() + on each individual allocation. + - The BLOCK_FAST allocator in particular is optimized for Wireshark's packet + scope pool. It has an extremely short, well-defined lifetime, and a very + regular pattern of allocations; I was able to use that knowledge to beat libc + rather handily, *in that specific use case*. + +/* + * Editor modelines - https://www.wireshark.org/tools/modelines.html + * + * Local variables: + * c-basic-offset: 4 + * tab-width: 8 + * indent-tabs-mode: nil + * End: + * + * vi: set shiftwidth=4 tabstop=8 expandtab: + * :indentSize=4:tabSize=8:noTabs=true: + */ diff --git a/doc/README.wslua b/doc/README.wslua new file mode 100644 index 0000000..c26dcf9 --- /dev/null +++ b/doc/README.wslua @@ -0,0 +1,549 @@ +README.wslua + +This is a HOWTO for adding support for new Lua hooks/functions/abilities in +Wireshark. If you see any errors or have any improvements, submit patches - +free software is a community effort.... + +This is NOT a guide for how to write Lua plugins - that's documented already +on the Wireshark webpages. + +Contributors to this README: +Hadriel Kaplan <hadrielk[AT]yahoo.com> + +============================================================================== + +Overview: + +The way Wireshark exposes functions for Lua is generally based on a +callback/event model, letting Lua plugins register their custom Lua functions +into event callbacks. C-based "objects" are exposed as Lua tables with +typical Lua USERDATA pointer dispatching, plain C-functions are registered as +such in Lua, and C-based enums/variables are registered into Lua as table +key=value (usually... though rarely they're registered as array indexed +values). All of that is very typical for applications that expose things +into a Lua scripting environment. + +The details that make it a little different are (1) the process by which the +code is bound/registered into Lua, and (2) the API documentation generator. +Wireshark uses C-macros liberally, both for the usual reasons as well as for +the binding generator and documentation generator scripts. The macros are +described within this document. + +The API documentation is auto-generated from a Python script called 'make- +wsluarm.py', which searches C-files for the known macros and generates +appropriate AsciiDoc documentation from them. This includes using the C +comments after the macros for the API document info. + +Likewise, another script called 'make-reg.py' generates the C-files +'register_wslua.c' and 'declare_wslua.h', based on the C-macros it searches +for in existing source files. The code this script auto-generates is +what actually registers some classes/functions into Lua - you don't have to +write your own registration functions to get your new functions/classes into +Lua tables. (you can do so, but it's not advisable) + +Both of the scripts above are given the C-source files to search through +by the make process, generated from the lists in epan/wslua/CMakeLists.txt. +Naturally if you add new source files, you need to add them to the list in +epan/wslua/CMakeLists.txt. You also have to add the module name into +docbook/user-guide.xml and docbook/wsluarm.xml, and the source files into +docbook/CMakeLists.txt, to get it to be generated in the user guide. + +Due to those documentation and registration scripts, you MUST follow some very +specific conventions in the functions you write to expose C-side code to Lua, +as described in this document. + +Naming conventions/rules: + +Class/object names must be UpperCamelCase, no numbers/underscores. +Function and method names must be lower_underscore_case, no numbers. +Constants/enums must be ALLCAPS, and can have numbers. + +The above rules are more than merely conventions - the scripts which +auto-generate stuff use regex patterns that require the naming syntax to be +followed. + +============================================================================== + +Documenting things for the API docs: + +As explained previously, the API documentation is auto-generated from a +Python script called 'make-wsluarm.py', which searches C-files for the known +macros and generates appropriate HTML documentation from them. This includes +using the C-comments after the macros for the API document info. The comments +are extremely important, because the API documentation is what most Lua script +authors will see - do *not* expect them to go looking through the C-source code +to figure things out. + +Please make sure to at least use the '@since' version notification markup +in your comments, to let users know when the new class/function/etc. you +created became available. + +Because documentation is so important, the make-wsluarm.py script supports +specific markup syntax in comments, and converts them to XML and ultimately +into the various documentation formats. The markup syntax is documented in +the top comments in make-wsluarm.py, but are repeated here as well: + - two (or more) line breaks in comments result in separate paragraphs + - all '&' are converted into their entity names, except inside urls + - all '<', and '>' are converted into their entity names everywhere + - any word(s) wrapped in one star, e.g., *foo bar*, become italics + - any word(s) wrapped in two stars, e.g., **foo bar**, become bold + - any word(s) wrapped in backticks, e.g., `foo bar`, become bold (for now) + - any word(s) wrapped in two backticks, e.g., ``foo bar``, become one backtick + - any "[[url]]" becomes an XML ulink with the url as both the url and text + - any "[[url|text]]" becomes an XML ulink with the url as the url and text as text + - any indent with a single leading star '*' followed by space is a bulleted list item + reducing indent or having an extra linebreak stops the list + - any indent with a leading digits-dot followed by space, i.e. "1. ", is a numbered list item + reducing indent or having an extra linebreak stops the list + - supports meta-tagged info inside comment descriptions as follows: + * a line starting with "@note" or "Note:" becomes an XML note line + * a line starting with "@warning" or "Warning:" becomes an XML warning line + * a line starting with "@version" or "@since" becomes a "Since:" line + * a line starting with "@code" and ending with "@endcode" becomes an + XML programlisting block, with no indenting/parsing within the block + The above '@' commands are based on Doxygen commands + + +============================================================================== + +Some implementation details: + +Creating new C-classes for Lua: + +Explaining the Lua class/object model and how it's bound to C-code functions +and data types is beyond the scope of this document; if you don't already know +how that works, I suggest you start reading lua-users.org's wiki, and +lua.org's free reference manual. + +Wireshark generally uses a model close to the typical binding +model: 'registering' class methods and metamethods, pushing objects into Lua +by applying the class' metatable to the USERDATA, etc. This latter part is +mostly handled for you by the C-macro's created by WSLUA_CLASS_DEFINE, such as +push/check, described later in this document. + +The actual way methods are dispatched is a little different from normal Lua +bindings, because attributes are supported as well (see next section). The +details won't be covered in this document - they're documented in the code +itself in: wslua_internals.c above the wslua_reg_attributes function. + +Registering a class requires you to write some code: a WSLUA_METHODS table, +a WSLUA_META table, and a registration function. The WSLUA_METHODS table is an +array of luaL_Reg structs, which map a string name that will be the function's +name in Lua, to a C-function pointer which is the C-function to be invoked by +Lua when the user calls the name. Instead of defining this array of structs +explicitly using strings and function names, you should use the WSLUA_METHODS +macro name for the array, and use WSLUA_CLASS_FNREG macro for each entry. +The WSLUA_META table follows the same behavior, with the WSLUA_CLASS_MTREG +macro for each entry. Make sure your C-function names use two underscores +instead of one (for instance, ClassName__tostring). + +Once you've created the appropriate array tables, define a registration +function named 'ClassName_register', where 'ClassName'is your class name, the +same one used in WSLUA_CLASS_DEFINE. The make-reg.py script will search +your file for WSLUA_CLASS_DEFINE, and it generates a register_wslua.c which +will call your ClassName_register function during Wireshark initialization. +Define a wslua_class structure which describes the class and register this in +your ClassName_register function using one of: + - wslua_register_classinstance_meta to create a metatable which allows + instances of a class to have methods and attributes. C code can create such + instances by setting the metatable on userdata, the class itself is not + directly visible in the Lua scope. + - wslua_register_class to additionally expose a class with static functions + that is also directly visible in the Lua global scope. +Also, you should read the 'Memory management model' section later in this +document. + +Class member variable attributes (getters/setters): + +The current implementation does not follow a single/common class-variable +attribute accessor model for the Lua API: some class member values are +populated/retrieved when a table field attribute is used that triggers the +__index or __newindex metamethods, and others are accessed through explicit +getter/setter method functions. In other words from a Lua code perspective +some class object variables are retrieves as 'foo = myObj.var', while others +are done as 'foo = myObj.getVar()'. + +From the C-side code perspective, some classes register no real method +functions but just have attributes (and use the WSLUA_ATTRIBUTE documentation +model for them). For example the FieldInfo class in wslua_field.c does this. +Other classes provide access to member variable through getter/setter method +functions (and thus use the WSLUA_METHOD documentation model). For example +the TvbRange class in wslua_tvb.c does this. Using the latter model of having +a getter/setter method function allows one to pass multiple arguments, whereas +the former __index/__newindex metamethod model does not. Both models are +fairly common in Lua APIs, although having a mixture of both in the same API +probably isn't. There is even a third model in use: pre-loading the member +fields of the class table with the values, instead of waiting for the Lua +script to access a particular one to retrieve it; for example the Listener tap +extractors table is pre-populated (see files 'wslua_listener.c' and 'taps' +which through the make-taps.py Python3 script creates 'taps_wslua.c'). The +downside of that approach is the performance impact, filling fields the Lua +script may never access. Lastly, the Field, FieldInfo, and Tvb's ByteArray +type each provide a __call metamethod as an accessor - I strongly suggest you +do NOT do that, as it's not a common model and will confuse people since it +doesn't follow the model of the other classes in Wireshark. + +Attributes are handled internally like this: + + -- invoked on myObj.myAttribute + function myObj.__metatable:__index(key) + if "getter for key exists" then + return getter(self) + elseif "method for key exists" then + -- ensures that myObj.myMethod() works + return method + else + error("no such property error message") + end + end + -- invoked on myObj.myAttribute = 1 + function myObj.__metatable:__newindex(key, value) + if "setter for key exists" then + return setter(self, value) + else + error("no such property error message") + end + end + +To add getters/setters in C, initialize the "attrs" member of the wslua_class +structure. This should contain an array table similar to the WSLUA_METHODS and +WSLUA_META tables, except using the macro name WSLUA_ATTRIBUTES. Inside this +array, each entry should use one of the following macros: WSLUA_ATTRIBUTE_ROREG, +WSLUA_ATTRIBUTE_WOREG, or WSLUA_ATTRIBUTE_RWREG. Those provide the hooks for +a getter-only, setter-only, or both getter and setter function. The functions +themselves need to follow a naming scheme of ClassName_get_attributename(), +or ClassName_set_attributename(), for the respective getter vs. setter function. +Trivial getters/setters have macros provided to make this automatic, for things +such as getting numbers, strings, etc. The macros are in wslua.h. For example, +the WSLUA_ATTRIBUTE_NAMED_BOOLEAN_GETTER(Foo,bar,choo) macro creates a getter +function to get the boolean value of the Class Foo's choo member variable, as +the Lua attribute named 'bar'. + +Callback function registration: + +For some callbacks, there are register_* Lua global functions, which take a +user-defined Lua function name as the argument - the one to be hooked into +that event. Unlike in most Lua APIs, there's a unique register_foo() function +for each event type, instead of a single register() with the event as an +argument. For example there's a register_postdissector() function. In some +cases the Lua functions are invoked based on a pre-defined function-name model +instead of explicit register_foo(), whereby a C-object looks for a defined +member variable in the Registry that represents a Lua function created by the +plugin. This would be the case if the Lua plugin had defined a pre-defined +member key of its object's table in Lua, for that purpose. For example if the +Lua plugin sets the 'reset' member of the Listener object table to a function, +then Wireshark creates a Registry entry for that Lua function, and executes +that Lua function when the Listener resets. (see the example Listener Lua +script in the online docs) That model is only useful if the object can only be +owned by one plugin so only one function is ever hooked, obviously, and thus +only if it's created by the Lua plugin (e.g., Listener.new()). + +Creating new Listener tap types: + +The Listener object is one of the more complicated ones. When the Lua script +creates a Listener (using Listener.new()), the code creates and returns a tap +object. The type of tap is based on the passed-in argument to Listener.new(), +and it creates a Lua table of the tap member variables. That happens in +taps_wslua.c, which is an auto-generated file from make-taps.py. That Python3 +script reads from a file called 'taps.ini', which identifies every struct name +(and associated enum name) that should be exposed as a tap type. The Python3 +script then generates the taps_wslua.c to push those whenever the Listener +calls for a tap; and it also generates a taps.tx file documenting them all. +So to add a new type, add the info to the taps file (or uncomment an existing +one), and make sure every member of the tap struct you're exposing is of a +type that make-taps.py has in its Python "types" and "comments" dictionaries. + +Note on Lua versions: + +Wireshark supports both Lua 5.1 and 5.2, which are defined as LUA_VERSION_NUM +values 501 and 502 respectively. When exposing things into Lua, make sure to +use ifdef wrappers for things which changed between the versions of Lua. See +this for details: http://www.lua.org/manual/5.2/manual.html#8.3 + +============================================================================== + +Defined Macros for Lua-API C-files: + +WSLUA_MODULE - this isn't actually used in real C-code, but rather only +appears in C-comments at the top of .c files. That's because it's purely used +for documentation, and it makes a new section in the API documentation. + +For example, this appears near the top of the wslua_gui.c file: + + /* WSLUA_MODULE Gui GUI support */ + +That makes the API documentation have a section titled 'GUI support' (it's +currently section 11.7 in the API docs). It does NOT mean there's any Lua +table named 'Gui' (in fact there isn't). It's just for documentation. +If you look at the documentation, you'll see there is 'ProgDlg', 'TextWindow', +etc. in that 'GUI support' section. That's because both ProgDlg and +TextWindow are defined in that same wslua_gui.c file using the +'WSLUA_CLASS_DEFINE' macro. (see description of that later) make-wsluarm.py +created those in the same documentation section because they're in the same c +file as that WSLUA_MODULE comment. You'll also note the documentation +includes a sub-section for 'Non Method Functions', which it auto-generated +from anything with a 'WSLUA_FUNCTION' macro (as opposed to class member +functions, which use the 'WSLUA_METHOD' and 'WSLUA_CONSTRUCTOR' macros). Also, +to make new wslua files generate documentation, it is not sufficient to just +add this macro to a new file and add the file to the CMakeLists.txt; you also +have to add the module name into docbook/user-guide.xml, and docbook/wsluarm.xml. + + +WSLUA_CONTINUE_MODULE - like WSLUA_MODULE, except used at the top of a .c file +to continue defining classes/functions/etc. within a previously declared module +in a previous file (i.e., one that used WSLUA_MODULE). The module name must match +the original one, and the .c file must be listed after the original one in the +CMakeLists.txt lists in the docbook directory. + + +WSLUA_ATTRIBUTE - this is another documentation-only "macro", only used within +comments. It makes the API docs generate documentation for a member variable +of a class, i.e. a key of a Lua table that is not called as a function in Lua, +but rather just retrieved or set. The 'WSLUA_ATTRIBUTE' token is followed by +a 'RO', 'WO', or 'RW' token, for Read-Only, Write-Only, or Read-Write. (ie, +whether the variable can be retrieved, written to, or both) This read/write +mode indication gets put into the API documentation. After that comes the name +of the attribute, which must be the class name followed by the specific +attribute name. + +Example: + + /* WSLUA_ATTRIBUTE Pinfo_rel_ts RO Number of seconds passed since beginning of capture */ + + + +WSLUA_FUNCTION - this is used for any global Lua function (functions put into +the global table) you want to expose, but not for object-style methods (that's +the 'WSLUA_METHOD' macro), nor static functions within an object (that's +WSLUA_CONSTRUCTOR). Unlike many of the macros here, the function name must +begin with 'wslua_'. Everything after that prefix will be the name of the +function in Lua. You can ONLY use lower-case letters and the underscore +character in this function name. For example 'WSLUA_FUNCTION +wslua_get_foo(lua_State* L)' will become a Lua function named 'get_foo'. +Documentation for it will also be automatically generated, as it is for the +other macros. Although from a Lua perspective it is a global function (not in +any class' table), the documentation will append it to the documentation page +of the module/file its source code is in, in a "Non Method Functions" section. +Descriptive text about the function must be located after the '{' and optional +whitespace, within a '\*' '*\' comment block on one line. + +Example: + + WSLUA_FUNCTION wslua_gui_enabled(lua_State* L) { /* Checks whether the GUI facility is enabled. */ + lua_pushboolean(L,GPOINTER_TO_INT(ops && ops->add_button)); + WSLUA_RETURN(1); /* A boolean: true if it is enabled, false if it isn't. */ + } + + +WSLUA_CLASS_DEFINE - this is used to define/create a new Lua class type (i.e., +table with methods). A Class name must begin with an uppercase letter, +followed by any upper or lower case letters but not underscores; in other +words, UpperCamelCase without numbers. The macro is expanded to create a +bunch of helper functions - see wslua.h. Documentation for it will also be +automatically generated, as it is for the other macros. + +Example: + + WSLUA_CLASS_DEFINE(ProgDlg,NOP,NOP); /* Manages a progress bar dialog. */ + + +WSLUA_CONSTRUCTOR - this is used to define a function of a class that is a +static function rather than a per-object method; i.e., from a Lua perspective +the function is called as 'myObj.func()' instead of 'myObj:func()'. From a +C-code perspective the code generated by make-reg.py does not treat this +differently than a WSLUA_METHOD, the only real difference being that the code +you write within the function won't be checking the object instance as the +first passed-in argument on the Lua-API stack. But from a documentation +perspective this macro correctly documents the usage using a '.' period rather +than ':' colon. This can also be used within comments, but then it's +'_WSLUA_CONSTRUCTOR_'. The name of the function must use the Class name +first, followed by underscore, and then the specific lower_underscore name +that will end up being the name of the function in Lua. + +Example: + + WSLUA_CONSTRUCTOR Dissector_get (lua_State *L) { + /* Obtains a dissector reference by name */ + #define WSLUA_ARG_Dissector_get_NAME 1 /* The name of the dissector */ + const char* name = luaL_checkstring(L,WSLUA_ARG_Dissector_get_NAME); + Dissector d; + + if (!name) + WSLUA_ARG_ERROR(Dissector_get,NAME,"must be a string"); + + if ((d = find_dissector(name))) { + pushDissector(L, d); + WSLUA_RETURN(1); /* The Dissector reference */ + } else + WSLUA_ARG_ERROR(Dissector_get,NAME,"No such dissector"); + } + + +WSLUA_METHOD - this is used for object-style class method definitions. The +documentation will use the colon syntax, and it will be called as +'myObj:func()' in Lua, so your function needs to check the first argument of +the stack for the object pointer. Two helper functions are automatically made +for this purpose, from the macro expansion of WSLUA_CLASS_DEFINE, of the +signatures 'MyObj toMyObj(lua_State* L, int idx)' and 'MyObj +checkMyObj(lua_State* L, int idx)'. They do the same thing, but the former +generates a Lua Error on failure, while the latter does not. + +Example: + + WSLUA_METHOD Listener_remove(lua_State* L) { + /* Removes a tap listener */ + Listener tap = checkListener(L,1); + if (!tap) return 0; + remove_tap_listener(tap); + return 0; + } + + +WSLUA_METAMETHOD - this is used for defining object metamethods (ie, Lua +metatable functions). The documentation will describe these as well, although +currently it doesn't specify they're metamethods but rather makes them appear +as regular object methods. The name of it must be the class name followed by +*two* underscores, or else it will not appear in the documentation. + +Example: + + WSLUA_METAMETHOD NSTime__eq(lua_State* L) { /* Compares two NSTimes */ + NSTime time1 = checkNSTime(L,1); + NSTime time2 = checkNSTime(L,2); + bool result = false; + + if (!time1 || !time2) + WSLUA_ERROR(FieldInfo__eq,"Data source must be the same for both fields"); + + if (nstime_cmp(time1, time2) == 0) + result = true; + + lua_pushboolean(L,result); + + return 1; + } + + +WSLUA_ARG_ - the prefix used in a #define statement, for a required +function/method argument (ie, one without a default value). It is defined to +an integer representing the index slot number of the Lua stack it will be at, +when calling the appropriate lua_check/lua_opt routine to get it from the +stack. The make_wsluarm.py Python script will generate API documentation with +this argument name for the function/method, removing the 'WSLUA_ARG_' prefix. +The name following the 'WSLUA_ARG_' prefix must be the same name as the +function it's an argument for, followed by an underscore and then an ALLCAPS +argument name (including numbers is ok). Although this last part is in +ALLCAPS, it is documented in lowercase. The argument name itself is +meaningless since it does not exist in Lua or C code. + +Example: see the example in WSLUA_CONSTRUCTOR above, where +WSLUA_ARG_Dissector_get_NAME is used. + + +WSLUA_OPTARG_ - the prefix used in a #define statement, for an optional +function/method argument (ie, one with a default value). It is defined to an +integer representing the index slot number of the Lua stack it will be at, +when calling the appropriate lua_check/lua_opt routine to get it from the +stack. The make_wsluarm.py Python script will generate API documentation with +this argument name for the function/method, removing the 'WSLUA_OPTARG_' +prefix. The rules for the name of the argument after the prefix are the same +as for 'WSLUA_ARG_' above. + +Example: + + #define WSLUA_OPTARG_Dumper_new_FILETYPE 2 /* The type of the file to be created */ + + +WSLUA_MOREARGS - a documentation-only macro used to document that more +arguments are expected/supported. This is useful when the number of +arguments is not fixed, i.e., a vararg model. The macro is followed by the +name of the function it's an argument for (without the 'wslua_' prefix if the +function is a WSLUA_FUNCTION type), and then followed by descriptive text. + +Example: + + WSLUA_FUNCTION wslua_critical( lua_State* L ) { /* Will add a log entry with critical severity*/ + /* WSLUA_MOREARGS critical objects to be printed */ + wslua_log(L,G_LOG_LEVEL_CRITICAL); + return 0; + } + + +WSLUA_RETURN - a macro with parentheses containing the number of return +values, meaning the number of items pushed back to Lua. Lua supports multiple +return values, although Wireshark usually just returns 0 or 1 value. The +argument can be an integer or a variable of the integer, and is not actually +documented. The API documentation will use the comments after this macro for +the return description. This macro can also be within comments, but is then +'_WSLUA_RETURNS_'. + +Example: + + WSLUA_RETURN(1); /* The ethernet pseudoheader */ + + +WSLUA_ERROR - this C macro takes arguments, and expands to call luaL_error() +using them, and returns 0. The arguments it takes is the full function name +and a string describing the error. For documentation, it uses the string +argument and displays it with the function it's associated to. + +Example: + if (!wtap_dump_can_write_encap(filetype, encap)) + WSLUA_ERROR(Dumper_new,"Not every filetype handles every encap"); + + +WSLUA_ARG_ERROR - this is a pure C macro and does not generate any +documentation. It is used for errors in type/value of function/method +arguments. + +Example: see the example in thr WSLUA_CONSTRUCTOR above. + + +============================================================================== + +Memory management model: + +Lua uses a garbage collection model, which for all intents and purposes can +collect garbage at any time once an item is no longer referenced by something +in Lua. When C-malloc'ed values are pushed into Lua, the Lua library has to +let you decide whether to try to free them or not. This is done through the +'__gc' metamethod, so every Wireshark class created by WSLUA_CLASS_DEFINE must +implement a metamethod function to handle this. The name of the function must +be 'ClassName__gc', where 'ClassName' is the same name as the class. Even if +you decide to do nothing, you still have to define the function or it will +fail to compile - as of this writing, which changed it to do so, in order to +make the programmer think about it and not forget. + +The thing to think about is the lifetime of the object/value. If C-code +controls/manages the object after pushing it into Lua, then C-code MUST NOT +free it until it knows Lua has garbage collected it, which is only known by +the __gc metamethod being invoked. Otherwise you run the risk of the Lua +script trying to use it later, which will dereference a pointer to something +that has been free'd, and crash. There are known ways to avoid this, but +those ways are not currently used in Wireshark's Lua API implementation; +except Tvb and TvbRange do implement a simple model of reference counting to +protect against this. + +If possible/reasonable, the best model is to malloc the object when you push +it into Lua, usually in a class function (not method) named 'new', and then +free it in the __gc metamethod. But if that's not reasonable, then the next +best model is to have a boolean member of the class called something like +'expired', which is set to true if the C-code decides it is dead/no-longer- +useful, and then have every Lua-to-C accessor method for that class type check +that boolean before trying to use it, and have the __gc metamethod set +expired=true or free it if it's already expired by C-side code; and vice-versa +for the C-side code. + +In some cases the class is exposed with a specific method to free/remove it, +typically called 'remove'; the Listener class does this, for example. When +the Lua script calls myListener:remove(), the C-code for that class method +free's the Listener that was malloc'ed previously in Listener.new(). The +Listener__gc() metamethod does not do anything, since it's hopefully already +been free'd. The downside with this approach is if the script never calls +remove(), then it leaks memory; and if the script ever tries to use the +Listener userdata object after it called remove(), then Wireshark crashes. Of +course either case would be a Lua script programming error, and easily +fixable, so it's not a huge deal. + +============================================================================== + diff --git a/doc/README.xml-output b/doc/README.xml-output new file mode 100644 index 0000000..1ab5f3f --- /dev/null +++ b/doc/README.xml-output @@ -0,0 +1,253 @@ +Protocol Dissection in XML Format +================================= +Copyright (c) 2003 by Gilbert Ramirez <gram@alumni.rice.edu> + +Wireshark has the ability to export its protocol dissection in an +XML format, tshark has similar functionality by using the "-Tpdml" +option. + +The XML that Wireshark produces follows the Packet Details Markup +Language (PDML) specified by the group at the Politecnico Di Torino +working on Analyzer. The specification was found at: + +http://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm + +That URL is not working anymore, but a copy can be found at the Internet +Archive: + +https://web.archive.org/web/20050305174853/http://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm + +This is similar to the NetPDL language specification: + +http://www.nbee.org/doku.php?id=netpdl:index + +The domain registration there has also expired, but an Internet Archive +copy is also available at: + +https://web.archive.org/web/20160305211810/http://nbee.org/doku.php?id=netpdl:index + +A related XML format, the Packet Summary Markup Language (PSML), is +also defined by the Analyzer group to provide packet summary information. +The PSML format is not documented in a publicly-available HTML document, +but its format is simple. Wireshark can export this format too, and +tshark can produce it with the "-Tpsml" option. + +PDML +==== +The PDML that Wireshark produces is known not to be loadable into Analyzer. +It causes Analyzer to crash. As such, the PDML that Wireshark produces +is labeled with a version number of "0", which means that the PDML does +not fully follow the PDML spec. Furthermore, a creator attribute in the +"<pdml>" tag gives the version number of wireshark/tshark that produced the +PDML. + +In that way, as the PDML produced by Wireshark matures, but still does not +meet the PDML spec, scripts can make intelligent decisions about how to +best parse the PDML, based on the "creator" attribute. + +A PDML file is delimited by a "<pdml>" tag. +A PDML file contains multiple packets, denoted by the "<packet>" tag. +A packet will contain multiple protocols, denoted by the "<proto>" tag. +A protocol might contain one or more fields, denoted by the "<field>" tag. + +A pseudo-protocol named "geninfo" is produced, as is required by the PDML +spec, and exported as the first protocol after the opening "<packet>" tag. +Its information comes from wireshark's "frame" protocol, which serves +the similar purpose of storing packet meta-data. Both "geninfo" and +"frame" protocols are provided in the PDML output. + +The "<pdml>" tag +================ +Example: + <pdml version="0" creator="wireshark/0.9.17"> + +The creator is "wireshark" (i.e., the "wireshark" engine. It will always say +"wireshark", not "tshark") version 0.9.17. + + +The "<proto>" tag +================= +"<proto>" tags can have the following attributes: + + name - the display filter name for the protocol + showname - the label used to describe this protocol in the protocol + tree. This is usually the descriptive name of the protocol, + but it can be modified by dissectors to include more data + (tcp can do this) + pos - the starting offset within the packet data where this + protocol starts + size - the number of octets in the packet data that this protocol + covers. + +The "<field>" tag +================= +"<field>" tags can have the following attributes: + + name - the display filter name for the field + showname - the label used to describe this field in the protocol + tree. This is usually the descriptive name of the protocol, + followed by some representation of the value. + pos - the starting offset within the packet data where this + field starts + size - the number of octets in the packet data that this field + covers. + value - the actual packet data, in hex, that this field covers + show - the representation of the packet data ('value') as it would + appear in a display filter. + + +Deviations from the PDML standard +================================= +Various dissectors parse packets in a way that does not fit all the assumptions +in the PDML specification. In some cases Wireshark adjusts the output to match +the spec more closely, but exceptions exist. + +Some dissectors sometimes place text into the protocol tree, without using +a field with a field-name. Those appear in PDML as "<field>" tags with no +'name' attribute, but with a 'show' attribute giving that text. + +Some dissectors place field items at the top level instead of inside a +protocol. In these cases, in the PDML output the field items are placed +inside a fake "<proto>" element named "fake-field-wrapper" in order to +maximize compliance. + +Many dissectors label the undissected payload of a protocol as belonging +to a "data" protocol, and the "data" protocol often resides inside +that last protocol dissected. In the PDML, the "data" protocol becomes +a "data" field, placed exactly where the "data" protocol is in Wireshark's +protocol tree. So, if Wireshark would normally show: + ++-- Frame +| ++-- Ethernet +| ++-- IP +| ++-- TCP +| ++-- HTTP + | + +-- Data + +In PDML, the "Data" protocol would become another field under HTTP: + +<packet> + <proto name="frame"> + ... + </proto> + + <proto name="eth"> + ... + </proto> + + <proto name="ip"> + ... + </proto> + + <proto name="tcp"> + ... + </proto> + + <proto name="http"> + ... + <field name="data" value="........."/> + </proto> +</packet> + +In cases where the "data" protocol appears at the top level, it is +still converted to a field, and placed inside the "fake-field-wrapper" +protocol, just as any other top level field. + +Similarly, expert info items in Wireshark belong to an internal protocol +named "_ws.expert", which is likewise converted into a "<field>" element +of that name. + +Some dissectors also place subdissected protocols in a subtree instead of +at the top level. Unlike with the "data" protocol, the PDML output does +_not_ change these protocols to fields, but rather outputs them as "<proto>" +elements. This results in well-formed XML that does, however, violate the +PDML spec, as "<proto>" elements should only appear as direct children of +"<packet>" elements, with only "<field>" elements nested therein. + +Note that packet tag may have nonstandard color attributes, "foreground" and "background" + + +tools/WiresharkXML.py +==================== +This is a python module which provides some infrastructure for +Python developers who wish to parse PDML. It is designed to read +a PDML file and call a user's callback function every time a packet +is constructed from the protocols and fields for a single packet. + +The python user should import the module, define a callback function +which accepts one argument, and call the parse_fh function: + +------------------------------------------------------------ +import WiresharkXML + +def my_callback(packet): + # do something + +# If the PDML is stored in a file, you can: +fh = open(xml_filename) +WiresharkXML.parse_fh(fh, my_callback) + +# or, if the PDML is contained within a string, you can: +WiresharkXML.parse_string(my_string, my_callback) + +# Now that the script has the packet data, do something. +------------------------------------------------------------ + +The object that is passed to the callback function is an +WiresharkXML.Packet object, which corresponds to a single packet. +WiresharkXML Provides 3 classes, each of which corresponds to a PDML tag: + + Packet - "<packet>" tag + Protocol - "<proto>" tag + Field - "<field>" tag + +Each of these classes has accessors which will return the defined attributes: + + get_name() + get_showname() + get_pos() + get_size() + get_value() + get_show() + +Protocols and fields can contain other fields. Thus, the Protocol and +Field class have a "children" member, which is a simple list of the +Field objects, if any, that are contained. The "children" list can be +directly accessed by code using the object. The "children" list will be +empty if this Protocol or Field contains no Fields. + +Furthermore, the Packet class is a sub-class of the PacketList class. +The PacketList class provides methods to look for protocols and fields. +The term "item" is used when the item being looked for can be +a protocol or a field: + + item_exists(name) - checks if an item exists in the PacketList + get_items(name) - returns a PacketList of all matching items + + +General Notes +============= +Generally, parsing XML is slow. If you're writing a script to parse +the PDML output of tshark, pass a read filter with "-R" to tshark to +try to reduce as much as possible the number of packets coming out of tshark. +The less your script has to process, the faster it will be. + +tools/msnchat +============= +tools/msnchat is a sample Python program that uses WiresharkXML to parse +PDML. Given one or more capture files, it runs tshark on each of them, +providing a read filter to reduce tshark's output. It finds MSN Chat +conversations in the capture file and produces nice HTML showing the +conversations. It has only been tested with capture files containing +non-simultaneous chat sessions, but was written to more-or-less handle any +number of simultaneous chat sessions. + +pdml2html.xsl +============= +pdml2html.xsl is a XSLT file to convert PDML files into HTML. +See https://gitlab.com/wireshark/wireshark/-/wikis/PDML for more details. diff --git a/doc/androiddump.adoc b/doc/androiddump.adoc new file mode 100644 index 0000000..d68a3a3 --- /dev/null +++ b/doc/androiddump.adoc @@ -0,0 +1,256 @@ +include::../docbook/attributes.adoc[] += androiddump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/asn2deb.adoc b/doc/asn2deb.adoc new file mode 100644 index 0000000..db97652 --- /dev/null +++ b/doc/asn2deb.adoc @@ -0,0 +1,84 @@ +include::../docbook/attributes.adoc[] += asn2deb(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/capinfos.adoc b/doc/capinfos.adoc new file mode 100644 index 0000000..4dec813 --- /dev/null +++ b/doc/capinfos.adoc @@ -0,0 +1,390 @@ +include::../docbook/attributes.adoc[] += capinfos(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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 start time of the capture. *Capinfos* considers +the earliest timestamp seen to be the start time, so the +first packet in the capture is not necessarily the earliest - +if packets exist "out-of-order", time-wise, in the capture, +*Capinfos* detects this. + +-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 end time of the capture. *Capinfos* considers +the latest timestamp seen to be the end time, so the +last packet in the capture is not necessarily the latest - +if packets exist "out-of-order", time-wise, in the capture, +*Capinfos* detects this. + +-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 start and end times 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/captype.adoc b/doc/captype.adoc new file mode 100644 index 0000000..11eb6bf --- /dev/null +++ b/doc/captype.adoc @@ -0,0 +1,73 @@ +include::../docbook/attributes.adoc[] += captype(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/ciscodump.adoc b/doc/ciscodump.adoc new file mode 100644 index 0000000..b721b28 --- /dev/null +++ b/doc/ciscodump.adoc @@ -0,0 +1,324 @@ +include::../docbook/attributes.adoc[] += ciscodump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/diagnostic-options.adoc b/doc/diagnostic-options.adoc new file mode 100644 index 0000000..1500168 --- /dev/null +++ b/doc/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/dissection-options.adoc b/doc/dissection-options.adoc new file mode 100644 index 0000000..5c55a76 --- /dev/null +++ b/doc/dissection-options.adoc @@ -0,0 +1,185 @@ +== 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. + +*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/dpauxmon.adoc b/doc/dpauxmon.adoc new file mode 100644 index 0000000..cf98cec --- /dev/null +++ b/doc/dpauxmon.adoc @@ -0,0 +1,142 @@ +include::../docbook/attributes.adoc[] += dpauxmon(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/dumpcap.adoc b/doc/dumpcap.adoc new file mode 100644 index 0000000..672599b --- /dev/null +++ b/doc/dumpcap.adoc @@ -0,0 +1,473 @@ +include::../docbook/attributes.adoc[] += dumpcap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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> ] +[ *-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* ] +[ *-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. +When the *-P* option is specified, the output file is written in the +*pcap* format. + +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 GiB. + +*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_20230714120117.pcapng, +outfile_00002_20230714120523.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 GiB. + +*interval*:__value__ switch to the next file when the time is an exact +multiple of __value__ seconds. For example, use 3600 to switch to a new file +every hour on the hour. + +*packets*:__value__ switch to the next file after it contains __value__ +packets. + +*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. +-- + +-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. + +-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. + +-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). +-- + +-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/editcap.adoc b/doc/editcap.adoc new file mode 100644 index 0000000..20fadc1 --- /dev/null +++ b/doc/editcap.adoc @@ -0,0 +1,628 @@ +include::../docbook/attributes.adoc[] += editcap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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* +*-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. + +== 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: + +__tls__ TLS Key Log as described at https://developer.mozilla.org/NSS_Key_Log_Format + +__wg__ WireGuard Key Log, see https://gitlab.com/wireshark/wireshark/-/wikis/WireGuard#key-log-format + +This option may be specified multiple times. The available options for +<secrets type> can be listed with *--inject-secrets help*. +-- + +--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. +-- + +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/etwdump.adoc b/doc/etwdump.adoc new file mode 100644 index 0000000..b1070d3 --- /dev/null +++ b/doc/etwdump.adoc @@ -0,0 +1,124 @@ +include::../docbook/attributes.adoc[] += etwdump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/extcap.adoc b/doc/extcap.adoc new file mode 100644 index 0000000..511a59c --- /dev/null +++ b/doc/extcap.adoc @@ -0,0 +1,145 @@ +include::../docbook/attributes.adoc[] += extcap(4) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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 directory. 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/extcap_example.py b/doc/extcap_example.py new file mode 100755 index 0000000..8c4a6b6 --- /dev/null +++ b/doc/extcap_example.py @@ -0,0 +1,544 @@ +#!/usr/bin/env python3 + +# Copyright 2014 Roland Knall <rknall [AT] gmail.com> +# +# Wireshark - Network traffic analyzer +# By Gerald Combs <gerald@wireshark.org> +# Copyright 1998 Gerald Combs +# +# SPDX-License-Identifier: GPL-2.0-or-later +# + +""" +This is a generic example, which produces pcap packages every n seconds, and +is configurable via extcap options. + +@note +{ +To use this script on Windows, please generate an extcap_example.bat inside +the extcap folder, with the following content: + +------- +@echo off +C:\Windows\py.exe C:\Path\to\extcap_example.py %* +------- + +Windows is not able to execute Python scripts directly, which also goes for all +other script-based formats beside VBScript +} + +""" + +from __future__ import print_function + +import sys +import re +import argparse +import time +import struct +import array +from threading import Thread + +ERROR_USAGE = 0 +ERROR_ARG = 1 +ERROR_INTERFACE = 2 +ERROR_FIFO = 3 +ERROR_DELAY = 4 + +CTRL_CMD_INITIALIZED = 0 +CTRL_CMD_SET = 1 +CTRL_CMD_ADD = 2 +CTRL_CMD_REMOVE = 3 +CTRL_CMD_ENABLE = 4 +CTRL_CMD_DISABLE = 5 +CTRL_CMD_STATUSBAR = 6 +CTRL_CMD_INFORMATION = 7 +CTRL_CMD_WARNING = 8 +CTRL_CMD_ERROR = 9 + +CTRL_ARG_MESSAGE = 0 +CTRL_ARG_DELAY = 1 +CTRL_ARG_VERIFY = 2 +CTRL_ARG_BUTTON = 3 +CTRL_ARG_HELP = 4 +CTRL_ARG_RESTORE = 5 +CTRL_ARG_LOGGER = 6 +CTRL_ARG_NONE = 255 + +initialized = False +message = '' +delay = 0.0 +verify = False +button = False +button_disabled = False + +""" +This code has been taken from http://stackoverflow.com/questions/5943249/python-argparse-and-controlling-overriding-the-exit-status-code - originally developed by Rob Cowie http://stackoverflow.com/users/46690/rob-cowie +""" +class ArgumentParser(argparse.ArgumentParser): + def _get_action_from_name(self, name): + """Given a name, get the Action instance registered with this parser. + If only it were made available in the ArgumentError object. It is + passed as its first arg... + """ + container = self._actions + if name is None: + return None + for action in container: + if '/'.join(action.option_strings) == name: + return action + elif action.metavar == name: + return action + elif action.dest == name: + return action + + def error(self, message): + exc = sys.exc_info()[1] + if exc: + exc.argument = self._get_action_from_name(exc.argument_name) + raise exc + super(ArgumentParser, self).error(message) + +#### EXTCAP FUNCTIONALITY + +"""@brief Extcap configuration +This method prints the extcap configuration, which will be picked up by the +interface in Wireshark to present a interface specific configuration for +this extcap plugin +""" +def extcap_config(interface, option): + args = [] + values = [] + multi_values = [] + + args.append((0, '--delay', 'Time delay', 'Time delay between packages', 'integer', '{range=1,15}{default=5}')) + args.append((1, '--message', 'Message', 'Package message content', 'string', '{required=true}{placeholder=Please enter a message here ...}')) + args.append((2, '--verify', 'Verify', 'Verify package content', 'boolflag', '{default=yes}')) + args.append((3, '--remote', 'Remote Channel', 'Remote Channel Selector', 'selector', '{reload=true}{placeholder=Load interfaces ...}')) + args.append((4, '--fake_ip', 'Fake IP Address', 'Use this ip address as sender', 'string', '{save=false}{validation=\\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\b}')) + args.append((5, '--ltest', 'Long Test', 'Long Test Value', 'long', '{default=123123123123123123}{group=Numeric Values}')) + args.append((6, '--d1test', 'Double 1 Test', 'Long Test Value', 'double', '{default=123.456}{group=Numeric Values}')) + args.append((7, '--d2test', 'Double 2 Test', 'Long Test Value', 'double', '{default= 123,456}{group=Numeric Values}')) + args.append((8, '--password', 'Password', 'Package message password', 'password', '')) + args.append((9, '--ts', 'Start Time', 'Capture start time', 'timestamp', '{group=Time / Log}')) + args.append((10, '--logfile', 'Log File Test', 'The Log File Test', 'fileselect', '{group=Time / Log}')) + args.append((11, '--radio', 'Radio Test', 'Radio Test Value', 'radio', '{group=Selection}')) + args.append((12, '--multi', 'MultiCheck Test', 'MultiCheck Test Value', 'multicheck', '{group=Selection}')) + + if option == "remote": + values.append((3, "if1", "Remote Interface 1", "false")) + values.append((3, "if2", "Remote Interface 2", "true")) + values.append((3, "if3", "Remote Interface 3", "false")) + values.append((3, "if4", "Remote Interface 4", "false")) + + if option == "radio": + values.append((11, "r1", "Radio Option 1", "false")) + values.append((11, "r2", "Radio Option 2", "false")) + values.append((11, "r3", "Radio Option 3", "true")) + + + if len(option) <= 0: + for arg in args: + print("arg {number=%d}{call=%s}{display=%s}{tooltip=%s}{type=%s}%s" % arg) + + values.append((3, "if1", "Remote1", "true")) + values.append((3, "if2", "Remote2", "false")) + + values.append((11, "r1", "Radio1", "false")) + values.append((11, "r2", "Radio2", "true")) + + if len(option) <= 0: + multi_values.append(((12, "m1", "Checkable Parent 1", "false", "true"), None)) + multi_values.append(((12, "m1c1", "Checkable Child 1", "false", "true"), "m1")) + multi_values.append(((12, "m1c1g1", "Uncheckable Grandchild", "false", "false"), "m1c1")) + multi_values.append(((12, "m1c2", "Checkable Child 2", "false", "true"), "m1")) + multi_values.append(((12, "m2", "Checkable Parent 2", "false", "true"), None)) + multi_values.append(((12, "m2c1", "Checkable Child 1", "false", "true"), "m2")) + multi_values.append(((12, "m2c1g1", "Checkable Grandchild", "false", "true"), "m2c1")) + multi_values.append(((12, "m2c2", "Uncheckable Child 2", "false", "false"), "m2")) + multi_values.append(((12, "m2c2g1", "Uncheckable Grandchild", "false", "false"), "m2c2")) + + for value in values: + print("value {arg=%d}{value=%s}{display=%s}{default=%s}" % value) + + for (value, parent) in multi_values: + sentence = "value {arg=%d}{value=%s}{display=%s}{default=%s}{enabled=%s}" % value + extra = "{parent=%s}" % parent if parent else "" + print("".join((sentence, extra))) + + +def extcap_version(): + print("extcap {version=1.0}{help=https://www.wireshark.org}{display=Example extcap interface}") + +def extcap_interfaces(): + print("extcap {version=1.0}{help=https://www.wireshark.org}{display=Example extcap interface}") + print("interface {value=example1}{display=Example interface 1 for extcap}") + print("interface {value=example2}{display=Example interface 2 for extcap}") + print("control {number=%d}{type=string}{display=Message}{tooltip=Package message content. Must start with a capital letter.}{placeholder=Enter package message content here ...}{validation=^[A-Z]+}" % CTRL_ARG_MESSAGE) + print("control {number=%d}{type=selector}{display=Time delay}{tooltip=Time delay between packages}" % CTRL_ARG_DELAY) + print("control {number=%d}{type=boolean}{display=Verify}{default=true}{tooltip=Verify package content}" % CTRL_ARG_VERIFY) + print("control {number=%d}{type=button}{display=Turn on}{tooltip=Turn on or off}" % CTRL_ARG_BUTTON) + print("control {number=%d}{type=button}{role=help}{display=Help}{tooltip=Show help}" % CTRL_ARG_HELP) + print("control {number=%d}{type=button}{role=restore}{display=Restore}{tooltip=Restore default values}" % CTRL_ARG_RESTORE) + print("control {number=%d}{type=button}{role=logger}{display=Log}{tooltip=Show capture log}" % CTRL_ARG_LOGGER) + print("value {control=%d}{value=1}{display=1}" % CTRL_ARG_DELAY) + print("value {control=%d}{value=2}{display=2}" % CTRL_ARG_DELAY) + print("value {control=%d}{value=3}{display=3}" % CTRL_ARG_DELAY) + print("value {control=%d}{value=4}{display=4}" % CTRL_ARG_DELAY) + print("value {control=%d}{value=5}{display=5}{default=true}" % CTRL_ARG_DELAY) + print("value {control=%d}{value=60}{display=60}" % CTRL_ARG_DELAY) + + +def extcap_dlts(interface): + if interface == '1': + print("dlt {number=147}{name=USER0}{display=Demo Implementation for Extcap}") + elif interface == '2': + print("dlt {number=148}{name=USER1}{display=Demo Implementation for Extcap}") + +def validate_capture_filter(capture_filter): + if capture_filter != "filter" and capture_filter != "valid": + print("Illegal capture filter") + +""" + +### FAKE DATA GENERATOR + +Extcap capture routine + This routine simulates a capture by any kind of user defined device. The parameters + are user specified and must be handled by the extcap. + + The data captured inside this routine is fake, so change this routine to present + your own input data, or call your own capture program via Popen for example. See + + for more details. + +""" +def unsigned(n): + return int(n) & 0xFFFFFFFF + +def pcap_fake_header(): + + header = bytearray() + header += struct.pack('<L', int('a1b2c3d4', 16)) + header += struct.pack('<H', unsigned(2)) # Pcap Major Version + header += struct.pack('<H', unsigned(4)) # Pcap Minor Version + header += struct.pack('<I', int(0)) # Timezone + header += struct.pack('<I', int(0)) # Accuracy of timestamps + header += struct.pack('<L', int('0000ffff', 16)) # Max Length of capture frame + header += struct.pack('<L', unsigned(1)) # Ethernet + return header + +# Calculates and returns the IP checksum based on the given IP Header +def ip_checksum(iph): + #split into bytes + words = splitN(''.join(iph.split()), 4) # TODO splitN() func undefined, this code will fail + csum = 0 + for word in words: + csum += int(word, base=16) + csum += (csum >> 16) + csum = csum & 0xFFFF ^ 0xFFFF + return csum + +iterateCounter = 0 + +def pcap_fake_package(message, fake_ip): + global iterateCounter + pcap = bytearray() + #length = 14 bytes [ eth ] + 20 bytes [ ip ] + messagelength + + caplength = len(message) + 14 + 20 + timestamp = int(time.time()) + + pcap += struct.pack('<L', unsigned(timestamp)) # timestamp seconds + pcap += struct.pack('<L', 0x00) # timestamp nanoseconds + pcap += struct.pack('<L', unsigned(caplength)) # length captured + pcap += struct.pack('<L', unsigned(caplength)) # length in frame + +# ETH + destValue = '2900' + srcValue = '3400' + if (iterateCounter % 2 == 0): + x = srcValue + srcValue = destValue + destValue = x + + pcap += struct.pack('h', int(destValue, 16)) # dest mac + pcap += struct.pack('h', int(destValue, 16)) # dest mac + pcap += struct.pack('h', int(destValue, 16)) # dest mac + pcap += struct.pack('h', int(srcValue, 16)) # source mac + pcap += struct.pack('h', int(srcValue, 16)) # source mac + pcap += struct.pack('h', int(srcValue, 16)) # source mac + pcap += struct.pack('<h', unsigned(8)) # protocol (ip) + iterateCounter += 1 + +# IP + pcap += struct.pack('b', int('45', 16)) # IP version + pcap += struct.pack('b', int('0', 16)) # + pcap += struct.pack('>H', unsigned(len(message)+20)) # length of data + payload + pcap += struct.pack('<H', int('0', 16)) # Identification + pcap += struct.pack('b', int('40', 16)) # Don't fragment + pcap += struct.pack('b', int('0', 16)) # Fragment Offset + pcap += struct.pack('b', int('40', 16)) + pcap += struct.pack('B', 0xFE) # Protocol (2 = unspecified) + pcap += struct.pack('<H', int('0000', 16)) # Checksum + + parts = fake_ip.split('.') + ipadr = (int(parts[0]) << 24) + (int(parts[1]) << 16) + (int(parts[2]) << 8) + int(parts[3]) + pcap += struct.pack('>L', ipadr) # Source IP + pcap += struct.pack('>L', int('7F000001', 16)) # Dest IP + + pcap += message + + return pcap + +def control_read(fn): + try: + header = fn.read(6) + sp, _, length, arg, typ = struct.unpack('>sBHBB', header) + if length > 2: + payload = fn.read(length - 2).decode('utf-8', 'replace') + else: + payload = '' + return arg, typ, payload + except Exception: + return None, None, None + +def control_read_thread(control_in, fn_out): + global initialized, message, delay, verify, button, button_disabled + with open(control_in, 'rb', 0) as fn: + arg = 0 + while arg is not None: + arg, typ, payload = control_read(fn) + log = '' + if typ == CTRL_CMD_INITIALIZED: + initialized = True + elif arg == CTRL_ARG_MESSAGE: + message = payload + log = "Message = " + payload + elif arg == CTRL_ARG_DELAY: + delay = float(payload) + log = "Time delay = " + payload + elif arg == CTRL_ARG_VERIFY: + # Only read this after initialized + if initialized: + verify = (payload[0] != '\0') + log = "Verify = " + str(verify) + control_write(fn_out, CTRL_ARG_NONE, CTRL_CMD_STATUSBAR, "Verify changed") + elif arg == CTRL_ARG_BUTTON: + control_write(fn_out, CTRL_ARG_BUTTON, CTRL_CMD_DISABLE, "") + button_disabled = True + if button: + control_write(fn_out, CTRL_ARG_BUTTON, CTRL_CMD_SET, "Turn on") + button = False + log = "Button turned off" + else: + control_write(fn_out, CTRL_ARG_BUTTON, CTRL_CMD_SET, "Turn off") + button = True + log = "Button turned on" + + if len(log) > 0: + control_write(fn_out, CTRL_ARG_LOGGER, CTRL_CMD_ADD, log + "\n") + +def control_write(fn, arg, typ, payload): + packet = bytearray() + packet += struct.pack('>sBHBB', b'T', 0, len(payload) + 2, arg, typ) + if sys.version_info[0] >= 3 and isinstance(payload, str): + packet += payload.encode('utf-8') + else: + packet += payload + fn.write(packet) + +def control_write_defaults(fn_out): + global initialized, message, delay, verify + + while not initialized: + time.sleep(.1) # Wait for initial control values + + # Write startup configuration to Toolbar controls + control_write(fn_out, CTRL_ARG_MESSAGE, CTRL_CMD_SET, message) + control_write(fn_out, CTRL_ARG_DELAY, CTRL_CMD_SET, str(int(delay))) + control_write(fn_out, CTRL_ARG_VERIFY, CTRL_CMD_SET, struct.pack('B', verify)) + + for i in range(1, 16): + item = '%d\x00%d sec' % (i, i) + control_write(fn_out, CTRL_ARG_DELAY, CTRL_CMD_ADD, item) + + control_write(fn_out, CTRL_ARG_DELAY, CTRL_CMD_REMOVE, str(60)) + +def extcap_capture(interface, fifo, control_in, control_out, in_delay, in_verify, in_message, remote, fake_ip): + global message, delay, verify, button_disabled + delay = in_delay if in_delay != 0 else 5 + message = in_message + verify = in_verify + counter = 1 + fn_out = None + + data = """Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor + incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nost + rud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis + aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugi + at nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culp + a qui officia deserunt mollit anim id est laborum. """ + + with open(fifo, 'wb', 0) as fh: + fh.write(pcap_fake_header()) + + if control_out is not None: + fn_out = open(control_out, 'wb', 0) + control_write(fn_out, CTRL_ARG_LOGGER, CTRL_CMD_SET, "Log started at " + time.strftime("%c") + "\n") + + if control_in is not None: + # Start reading thread + thread = Thread(target=control_read_thread, args=(control_in, fn_out)) + thread.start() + + if fn_out is not None: + control_write_defaults(fn_out) + + dataPackage = int(0) + dataTotal = int(len(data) / 20) + 1 + + while True: + if fn_out is not None: + log = "Received packet #" + str(counter) + "\n" + control_write(fn_out, CTRL_ARG_LOGGER, CTRL_CMD_ADD, log) + counter = counter + 1 + + if button_disabled: + control_write(fn_out, CTRL_ARG_BUTTON, CTRL_CMD_ENABLE, "") + control_write(fn_out, CTRL_ARG_NONE, CTRL_CMD_INFORMATION, "Turn action finished.") + button_disabled = False + + if (dataPackage * 20 > len(data)): + dataPackage = 0 + dataSub = data[dataPackage * 20:(dataPackage + 1) * 20] + dataPackage += 1 + + out = ("%c%s%c%c%c%s%c%s%c" % (len(remote), remote.strip(), dataPackage, dataTotal, len(dataSub), dataSub.strip(), len(message), message.strip(), verify)).encode("utf8") + fh.write(pcap_fake_package(out, fake_ip)) + time.sleep(delay) + + thread.join() + if fn_out is not None: + fn_out.close() + +def extcap_close_fifo(fifo): + # This is apparently needed to workaround an issue on Windows/macOS + # where the message cannot be read. (really?) + fh = open(fifo, 'wb', 0) + fh.close() + +#### + +def usage(): + print("Usage: %s <--extcap-interfaces | --extcap-dlts | --extcap-interface | --extcap-config | --capture | --extcap-capture-filter | --fifo>" % sys.argv[0] ) + +if __name__ == '__main__': + interface = "" + option = "" + + # Capture options + delay = 0 + message = "" + fake_ip = "" + ts = 0 + + parser = ArgumentParser( + prog="Extcap Example", + description="Extcap example program for Python" + ) + + # Extcap Arguments + parser.add_argument("--capture", help="Start the capture routine", action="store_true" ) + parser.add_argument("--extcap-interfaces", help="Provide a list of interfaces to capture from", action="store_true") + parser.add_argument("--extcap-interface", help="Provide the interface to capture from") + parser.add_argument("--extcap-dlts", help="Provide a list of dlts for the given interface", action="store_true") + parser.add_argument("--extcap-config", help="Provide a list of configurations for the given interface", action="store_true") + parser.add_argument("--extcap-capture-filter", help="Used together with capture to provide a capture filter") + parser.add_argument("--fifo", help="Use together with capture to provide the fifo to dump data to") + parser.add_argument("--extcap-control-in", help="Used to get control messages from toolbar") + parser.add_argument("--extcap-control-out", help="Used to send control messages to toolbar") + parser.add_argument("--extcap-version", help="Shows the version of this utility", nargs='?', default="") + parser.add_argument("--extcap-reload-option", help="Reload elements for the given option") + + # Interface Arguments + parser.add_argument("--verify", help="Demonstrates a verification bool flag", action="store_true" ) + parser.add_argument("--delay", help="Demonstrates an integer variable", type=int, default=0, choices=[0, 1, 2, 3, 4, 5, 6] ) + parser.add_argument("--remote", help="Demonstrates a selector choice", default="if1", choices=["if1", "if2", "if3", "if4"] ) + parser.add_argument("--message", help="Demonstrates string variable", nargs='?', default="" ) + parser.add_argument("--fake_ip", help="Add a fake sender IP address", nargs='?', default="127.0.0.1" ) + parser.add_argument("--ts", help="Capture start time", action="store_true" ) + + try: + args, unknown = parser.parse_known_args() + except argparse.ArgumentError as exc: + print("%s: %s" % (exc.argument.dest, exc.message), file=sys.stderr) + fifo_found = 0 + fifo = "" + for arg in sys.argv: + if arg == "--fifo" or arg == "--extcap-fifo": + fifo_found = 1 + elif fifo_found == 1: + fifo = arg + break + extcap_close_fifo(fifo) + sys.exit(ERROR_ARG) + + if len(sys.argv) <= 1: + parser.exit("No arguments given!") + + if args.extcap_version and not args.extcap_interfaces: + extcap_version() + sys.exit(0) + + if not args.extcap_interfaces and args.extcap_interface is None: + parser.exit("An interface must be provided or the selection must be displayed") + if args.extcap_capture_filter and not args.capture: + validate_capture_filter(args.extcap_capture_filter) + sys.exit(0) + + if args.extcap_interfaces or args.extcap_interface is None: + extcap_interfaces() + sys.exit(0) + + if len(unknown) > 1: + print("Extcap Example %d unknown arguments given" % len(unknown)) + + m = re.match('example(\d+)', args.extcap_interface) + if not m: + sys.exit(ERROR_INTERFACE) + interface = m.group(1) + + message = args.message + if args.message is None or len(args.message) == 0: + message = "Extcap Test" + + fake_ip = args.fake_ip + if args.fake_ip is None or len(args.fake_ip) < 7 or len(args.fake_ip.split('.')) != 4: + fake_ip = "127.0.0.1" + + ts = args.ts + + if args.extcap_reload_option and len(args.extcap_reload_option) > 0: + option = args.extcap_reload_option + + if args.extcap_config: + extcap_config(interface, option) + elif args.extcap_dlts: + extcap_dlts(interface) + elif args.capture: + if args.fifo is None: + sys.exit(ERROR_FIFO) + # The following code demonstrates error management with extcap + if args.delay > 5: + print("Value for delay [%d] too high" % args.delay, file=sys.stderr) + extcap_close_fifo(args.fifo) + sys.exit(ERROR_DELAY) + + try: + extcap_capture(interface, args.fifo, args.extcap_control_in, args.extcap_control_out, args.delay, args.verify, message, args.remote, fake_ip) + except KeyboardInterrupt: + pass + else: + usage() + sys.exit(ERROR_USAGE) diff --git a/doc/falcodump.adoc b/doc/falcodump.adoc new file mode 100644 index 0000000..cecca01 --- /dev/null +++ b/doc/falcodump.adoc @@ -0,0 +1,145 @@ +include::../docbook/attributes.adoc[] += falcodump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{stylesheet} + +== NAME + +falcodump - Dump log data to a file using a Falco source plugin. + +== SYNOPSIS + +[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> ] + +== 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. + +== PLUGINS + +=== cloudtrail (AWS CloudTrail) + +CloudTrail sources can be S3 buckets or SQS queue URLs. S3 bucket URLs have the form + +s3://__bucket_name__/AWSLogs/__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. + +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. + +== 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 + +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/http3.md b/doc/http3.md new file mode 100644 index 0000000..9fc1085 --- /dev/null +++ b/doc/http3.md @@ -0,0 +1,103 @@ + +# Supported features +The HTTP3 dissector is a work in progress. + +At the moment, the following aspects of HTTP3 are supported: +- Diseciton of different HTTP3 stream types +- Dissection of different HTTP3 frame types +- Dissection of HTTP header fields +- Dissection of QPACK instructions + +In addition, the dissector suports decoding of the HTTP3 +header fields. This ability requires `nghttp3` third-party library. + +## High-level overview +The HTTP3 dissector is invoked by the QUIC dissector. + +The essential call tree: +- `dissect_http3` + Main entry point. Depending on the stream type, invokes one of the following: + - `dissect_http3_uni_stream` + Processes unidirectional streams, including the control streams, + the QPACK encoder/decoder streams, and the HTTP3 server push streams. + NOTE: the HTTP3 server push streams support is rudimental. + - `dissect_http3_qpack_enc` + Dissects the QPACK encoder stream. + If Wireshark was built with the optional `nghttp3` library, + this function is also responsible on updating the state + of the QPACK decoder. + - `dissect_http3_frame` + Processed HTTP3 frames from the client-initiated bidirectional stream. + Determines the frame type, and dispatches the call to one of the + sub-dissectors: + - `dissect_http3_data` + Dissects the `HTTP3_DATA` frames. + - `dissect_http3_headers` + Dissects the `HTTP3_HEADER` frames. + If Wireshark was built with the optional `nghttp3` library, + this function attempts to decode the header fields, using + the QPACK decoder. + - `dissect_http3_settings` + Dissects the `HTTP3_SETTINGS` frames. + +### Overview of the HTTP3 header dissection +The QPACK implementation from `nghttp3` requires a separate QPACK decoder instance +for every HTTP3 connection. The different HTTP3 streams that constitute a single +HTTP3 conneciton are sharing the same QPACK decoder instance. + +The HTTP3 dissector interacts with the QPACK decoder in 2 ways: +- On the reception of QPACK encoder data (which is delivered on a dedicated unidirectional stream), + the dissector updates the connection's decoder instance. +- On the reception of compressed HTTP3 headers, the dissector uses the connection's decoder + to uncompress the HTTP headers. + +If decompression succeeds, the dissector adds tree items to the packet tree. Otherwise, +the dissector adds expert info items. + +The decompression can fail due to several reasons: +- If the instruction count required by the compressed HTTP3 headers + exceeds the maximal instruction count that the QPACK decoder is aware of, + the decoding becomes "blocked". This situation can occure when the QUIC packets + that carry the QPACK encoder instructions are dropped/reordered. +- If the state of the decoder becomes invalid, which may happen when a "garbage" + data is received on the QUIC stream. +- Lastly, the decoding can fail if the underlying QUIC desegmentation is + not working correctly. + +### Overview of HTTP3 data frames dissection +The higher-level dissectors that could use HTTP3 (e.g. WebTransport) need to be able +to access the contents of a single HTTP3 stream as a contiguous span of data. + +For that purpose, the HTTP3 dissector is defining a custom conversation finder. +See functions `http3_find_inner_conversation` and `http3_reset_inner_conversation`. + +## Essential data structures +### File-level state +#### `HTTP3_CONN_INFO_MAP` +The `HTTP3_CONN_INFO_MAP` contains session-level information for every HTTP3 connection +in a PCAP file. This map is lazily allocated, and is cleared upon exiting the file scope. + +### HTTP3 header caches +The dissector attempts to conserve memory, by avoding allocating memory for +duplicate header names/values. Instead, the dissector keeps the decoded names/values +in two caches: `HTTP3_HEADER_CACHE` and `HTTP3_HEADER_DEF_CACHE`. The former stores +the decoded HTTP3 header values, and the latter stores the decoded HTTP3 header names. + +### Connection-level state +#### `http3_session_info_t` +The `http3_session_info_t` keeps the state of the QPACK decoder. Every HTTP3 connection +corresponds to a single session. In the future, the session may be shared between multiple +connections, to support connection migration or multipath HTTP3. +At the moment, there are no shared sessions. + +### Stream-level state +#### `http3_stream_info_t` +The `http3_stream_info_t` keeps the information about the individual HTTP3 streams, +as well as mapping to the underlying QUIC streams. + +### Frame-level state +#### `http3_header_field_t` +The `http3_header_field_t` keeps the information about a single HTTP header. +It contains both the encoded and the decoded representation of the header. +The actual decoded strings are stored in `HTTP3_HEADER_CACHE`/`HTTP3_HEADER_DEF_CACHE`; +the individual `http3_header_field_t` instances contain pointers to the strings.
\ No newline at end of file diff --git a/doc/idl2deb.adoc b/doc/idl2deb.adoc new file mode 100644 index 0000000..146672f --- /dev/null +++ b/doc/idl2deb.adoc @@ -0,0 +1,82 @@ +include::../docbook/attributes.adoc[] += idl2deb(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/idl2wrs.adoc b/doc/idl2wrs.adoc new file mode 100644 index 0000000..c046c53 --- /dev/null +++ b/doc/idl2wrs.adoc @@ -0,0 +1,100 @@ +include::../docbook/attributes.adoc[] += idl2wrs(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/mergecap.adoc b/doc/mergecap.adoc new file mode 100644 index 0000000..a5c9a6c --- /dev/null +++ b/doc/mergecap.adoc @@ -0,0 +1,207 @@ +include::../docbook/attributes.adoc[] += mergecap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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. +This setting is mandatory. + +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/mmdbresolve.adoc b/doc/mmdbresolve.adoc new file mode 100644 index 0000000..4b88040 --- /dev/null +++ b/doc/mmdbresolve.adoc @@ -0,0 +1,71 @@ +include::../docbook/attributes.adoc[] += mmdbresolve(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/packet-PROTOABBREV.c b/doc/packet-PROTOABBREV.c new file mode 100644 index 0000000..6a2ce71 --- /dev/null +++ b/doc/packet-PROTOABBREV.c @@ -0,0 +1,380 @@ +/* packet-PROTOABBREV.c + * Routines for PROTONAME dissection + * Copyright YEARS, YOUR_NAME <YOUR_EMAIL_ADDRESS> + * + * Wireshark - Network traffic analyzer + * By Gerald Combs <gerald@wireshark.org> + * Copyright 1998 Gerald Combs + * + * SPDX-License-Identifier: LICENSE + */ + +/* + * (A short description of the protocol including links to specifications, + * detailed documentation, etc.) + */ + +#include "config.h" +/* Define the name for the logging domain (try to avoid collisions with existing domains) */ +#define WS_LOG_DOMAIN "PROTOABBREV" + +/* Global header providing a minimum base set of required macros and APIs */ +#include <wireshark.h> + +#if 0 +/* "System" includes used only as needed */ +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +... +#endif + +#include <epan/packet.h> /* Required dissection API header */ +#include <epan/expert.h> /* Include only as needed */ +#include <epan/prefs.h> /* Include only as needed */ + +#if 0 +/* IF AND ONLY IF your protocol dissector exposes code to other dissectors + * (which most dissectors don't need to do) then the 'public' prototypes and + * data structures can go in the header file packet-PROTOABBREV.h. If not, then + * a header file is not needed at all and this #include statement can be + * removed. */ +#include "packet-PROTOABBREV.h" +#endif + +/* Some protocols may need code from other dissectors, as here for + * ssl_dissector_add() + */ +#include "packet-tls.h" + +/* Prototypes */ +/* (Required to prevent [-Wmissing-prototypes] warnings */ +void proto_reg_handoff_PROTOABBREV(void); +void proto_register_PROTOABBREV(void); + +/* Initialize the protocol and registered fields */ +static int proto_PROTOABBREV = -1; +static int hf_FIELDABBREV = -1; +static expert_field ei_PROTOABBREV_EXPERTABBREV = EI_INIT; + +static dissector_handle_t PROTOABBREV_handle; +static dissector_handle_t PROTOABBREV_tls_handle; + +/* Global sample preference ("controls" display of numbers) */ +static bool pref_hex = false; +/* Global sample port preference - real port preferences should generally + * default to "" (for a range) or 0 (for a single uint) unless there is an + * IANA-registered (or equivalent) port for your protocol. */ +#define PROTOABBREV_TLS_PORT 5678 +static unsigned tls_port_pref = PROTOABBREV_TLS_PORT; + +#define PROTOABBREV_TCP_PORTS "1234" +static range_t *tcp_port_range = PROTOABBREV_TCP_PORTS; + +/* Initialize the subtree pointers */ +static int ett_PROTOABBREV = -1; + +/* A sample #define of the minimum length (in bytes) of the protocol data. + * If data is received with fewer than this many bytes it is rejected by + * the current dissector. */ +#define PROTOABBREV_MIN_LENGTH 8 + +/* Code to actually dissect the packets */ +static int +dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, + void *data _U_) +{ + /* Set up structures needed to add the protocol subtree and manage it */ + proto_item *ti, *expert_ti; + proto_tree *PROTOABBREV_tree; + /* Other misc. local variables. */ + unsigned offset = 0; + int len = 0; + + /*** HEURISTICS ***/ + + /* First, if at all possible, do some heuristics to check if the packet + * cannot possibly belong to your protocol. This is especially important + * for protocols directly on top of TCP or UDP where port collisions are + * common place (e.g., even though your protocol uses a well known port, + * someone else may set up, for example, a web server on that port which, + * if someone analyzed that web server's traffic in Wireshark, would result + * in Wireshark handing an HTTP packet to your dissector). + * + * For example: + */ + + /* Check that the packet is long enough for it to belong to us. */ + if (tvb_reported_length(tvb) < PROTOABBREV_MIN_LENGTH) + return 0; + + /* Check that there's enough data present to run the heuristics. If there + * isn't, reject the packet; it will probably be dissected as data and if + * the user wants it dissected despite it being short they can use the + * "Decode-As" functionality. If your heuristic needs to look very deep into + * the packet you may not want to require *all* data to be present, but you + * should ensure that the heuristic does not access beyond the captured + * length of the packet regardless. */ + if (tvb_captured_length(tvb) < MAX_NEEDED_FOR_HEURISTICS) + return 0; + + /* Fetch some values from the packet header using tvb_get_*(). If these + * values are not valid/possible in your protocol then return 0 to give + * some other dissector a chance to dissect it. */ + if ( TEST_HEURISTICS_FAIL ) + return 0; + + /*** COLUMN DATA ***/ + + /* There are two normal columns to fill in: the 'Protocol' column which + * is narrow and generally just contains the constant string 'PROTOABBREV', + * and the 'Info' column which can be much wider and contain misc. summary + * information (for example, the port number for TCP packets). + * + * If you are setting the column to a constant string, use "col_set_str()", + * as it's more efficient than the other "col_set_XXX()" calls. + * + * If + * - you may be appending to the column later OR + * - you have constructed the string locally OR + * - the string was returned from a call to val_to_str() + * then use "col_add_str()" instead, as that takes a copy of the string. + * + * The function "col_add_fstr()" can be used instead of "col_add_str()"; it + * takes "printf()"-like arguments. Don't use "col_add_fstr()" with a format + * string of "%s" - just use "col_add_str()" or "col_set_str()", as it's + * more efficient than "col_add_fstr()". + * + * For full details see section 1.4 of README.dissector. + */ + + /* Set the Protocol column to the constant string of PROTOABBREV */ + col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV"); + +#if 0 + /* If you will be fetching any data from the packet before filling in + * the Info column, clear that column first in case the calls to fetch + * data from the packet throw an exception so that the Info column doesn't + * contain data left over from the previous dissector: */ + col_clear(pinfo->cinfo, COL_INFO); +#endif + + /* Some protocols need to be parsed differently for packets sent to the + * registered (server) port versus packets sent from the server port + * to an ephemeral client port. + */ + if (value_is_in_range(tcp_port_range, pinfo->destport)) { + col_set_str(pinfo->cinfo, COL_INFO, "XXX Request"); + } else { + col_set_str(pinfo->cinfo, COL_INFO, "XXX Reply"); + } + + /*** PROTOCOL TREE ***/ + + /* Now we will create a sub-tree for our protocol and start adding fields + * to display under that sub-tree. Most of the time the only functions you + * will need are proto_tree_add_item() and proto_item_add_subtree(). + * + * NOTE: The offset and length values in the call to proto_tree_add_item() + * define what data bytes to highlight in the hex display window when the + * line in the protocol tree display corresponding to that item is selected. + * + * Supplying a length of -1 tells Wireshark to highlight all data from the + * offset to the end of the packet. + */ + + /* create display subtree for the protocol */ + ti = proto_tree_add_item(tree, proto_PROTOABBREV, tvb, 0, -1, ENC_NA); + + PROTOABBREV_tree = proto_item_add_subtree(ti, ett_PROTOABBREV); + + /* Add an item to the subtree, see section 1.5 of README.dissector for more + * information. */ + expert_ti = proto_tree_add_item(PROTOABBREV_tree, hf_FIELDABBREV, tvb, + offset, len, ENC_xxx); + offset += len; + /* Some fields or situations may require "expert" analysis that can be + * specifically highlighted. */ + if ( TEST_EXPERT_condition ) + /* value of hf_FIELDABBREV isn't what's expected */ + expert_add_info(pinfo, expert_ti, &ei_PROTOABBREV_EXPERTABBREV); + + /* Continue adding tree items to process the packet here... */ + + /* If this protocol has a sub-dissector call it here, see section 1.8 of + * README.dissector for more information. */ + + /* Return the amount of data this dissector was able to dissect (which may + * or may not be the total captured packet as we return here). */ + return tvb_captured_length(tvb); +} + +/* Register the protocol with Wireshark. + * + * This format is required because a script is used to build the C function that + * calls all the protocol registration. + */ +void +proto_register_PROTOABBREV(void) +{ + module_t *PROTOABBREV_module; + expert_module_t *expert_PROTOABBREV; + + /* Setup list of header fields See Section 1.5 of README.dissector for + * details. */ + static hf_register_info hf[] = { + { &hf_FIELDABBREV, + { "FIELDNAME", "FIELDFILTERNAME", + FT_FIELDTYPE, FIELDDISPLAY, FIELDCONVERT, BITMASK, + "FIELDDESCR", HFILL } + } + }; + + /* Setup protocol subtree array */ + static int *ett[] = { + &ett_PROTOABBREV + }; + + /* Setup protocol expert items */ + static ei_register_info ei[] = { + { &ei_PROTOABBREV_EXPERTABBREV, + { "PROTOABBREV.EXPERTABBREV", PI_GROUP, PI_SEVERITY, + "EXPERTDESCR", EXPFILL } + } + }; + + /* Register the protocol name and description */ + proto_PROTOABBREV = proto_register_protocol("PROTONAME", "PROTOSHORTNAME", "PROTOFILTERNAME"); + + /* Required function calls to register the header fields and subtrees */ + proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf)); + proto_register_subtree_array(ett, array_length(ett)); + + /* Required function calls to register expert items */ + expert_PROTOABBREV = expert_register_protocol(proto_PROTOABBREV); + expert_register_field_array(expert_PROTOABBREV, ei, array_length(ei)); + + /* Use register_dissector() here so that the dissector can be + * found by name by other protocols, by Lua, by Export PDU, + * by custom User DLT dissection, etc. Some protocols may require + * multiple uniquely named dissectors that behave differently + * depending on the caller, e.g. over TCP directly vs over TLS. + */ + PROTOABBREV_handle = register_dissector("PROTOABBREV", dissect_PROTOABBREV, + proto_PROTOABBREV); + + PROTOABBREV_tls_handle = register_dissector("PROTOABBREV.tls", + dissect_PROTOABBREV_tls, proto_PROTOABBREV); + + /* Register a preferences module (see section 2.6 of README.dissector + * for more details). Registration of a prefs callback is not required + * if there are no preferences that affect protocol registration (an example + * of a preference that would affect registration is a port preference). + * If the prefs callback is not needed, use NULL instead of + * proto_reg_handoff_PROTOABBREV in the following. + */ + PROTOABBREV_module = prefs_register_protocol(proto_PROTOABBREV, + proto_reg_handoff_PROTOABBREV); + + /* Register a preferences module under the preferences subtree. + * Only use this function instead of prefs_register_protocol (above) if you + * want to group preferences of several protocols under one preferences + * subtree. + * + * Argument subtree identifies grouping tree node name, several subnodes can + * be specified using slash '/' (e.g. "OSI/X.500" - protocol preferences + * will be accessible under Protocols->OSI->X.500-><PROTOSHORTNAME> + * preferences node. + */ + PROTOABBREV_module = prefs_register_protocol_subtree(const char *subtree, + proto_PROTOABBREV, proto_reg_handoff_PROTOABBREV); + + /* Register a simple example preference */ + prefs_register_bool_preference(PROTOABBREV_module, "show_hex", + "Display numbers in Hex", + "Enable to display numerical values in hexadecimal.", + &pref_hex); + + /* Register an example port preference */ + prefs_register_uint_preference(PROTOABBREV_module, "tls.port", "PROTOABBREV TLS Port", + " PROTOABBREV TLS port if other than the default", + 10, &tls_port_pref); + +} + +/* If this dissector uses sub-dissector registration add a registration routine. + * This exact format is required because a script is used to find these + * routines and create the code that calls these routines. + * + * If this function is registered as a prefs callback (see + * prefs_register_protocol above) this function is also called by Wireshark's + * preferences manager whenever "Apply" or "OK" are pressed. In that case, it + * should accommodate being called more than once by use of the static + * 'initialized' variable included below. + * + * This form of the reg_handoff function is used if you perform registration + * functions which are dependent upon prefs. See below this function for a + * simpler form which can be used if there are no prefs-dependent registration + * functions. + */ +void +proto_reg_handoff_PROTOABBREV(void) +{ + static bool initialized = false; + static int current_tls_port_pref; + + if (!initialized) { + /* Simple port preferences like TCP can be registered as automatic + * Decode As preferences. + */ + dissector_add_uint_range_with_preference("tcp.port", PROTOABBREV_TCP_PORTS, PROTOABBREV_handle); + + initialized = true; + } else { + /* If you perform registration functions which are dependent upon + * prefs then you should de-register everything which was associated + * with the previous settings and re-register using the new prefs + * settings here. In general this means you need to keep track of + * the value the preference had at the time you registered, which + * can be saved using local statics in this function (proto_reg_handoff). + */ + ssl_dissector_delete(current_tls_port_pref, PROTOABBREV_tls_handle); + } + + /* Some port preferences, like TLS, are more complicated and cannot + * be done with auto preferences, because the TCP dissector has to call + * TLS for the particular port as well as TLS calling this dissector. + */ + ssl_dissector_add(tls_port_pref, PROTOABBREV_tls_handle); + current_tls_port = tls_port_pref; + /* Some protocols dissect packets going to the server port differently + * than packets coming from the server port. The current Decode As + * value can be retrieved here. Note that auto preferences are always + * a range, even if registered with dissector_add_uint_with_preference. + */ + tcp_port_range = prefs_get_range_value("PROTOABBREV", "tcp.port"); +} + +#if 0 + +/* Simpler form of proto_reg_handoff_PROTOABBREV which can be used if there are + * no prefs-dependent registration function calls. */ +void +proto_reg_handoff_PROTOABBREV(void) +{ + dissector_add_uint_range_with_preference("tcp.port", PROTOABBREV_TCP_PORTS, PROTOABBREV_handle); +} +#endif + +/* + * Editor modelines - https://www.wireshark.org/tools/modelines.html + * + * Local variables: + * c-basic-offset: 4 + * tab-width: 8 + * indent-tabs-mode: nil + * End: + * + * vi: set shiftwidth=4 tabstop=8 expandtab: + * :indentSize=4:tabSize=8:noTabs=true: + */ diff --git a/doc/plugins.example/CMakeLists.txt b/doc/plugins.example/CMakeLists.txt new file mode 100644 index 0000000..26e3ad2 --- /dev/null +++ b/doc/plugins.example/CMakeLists.txt @@ -0,0 +1,74 @@ +# CMakeLists.txt +# +# Wireshark - Network traffic analyzer +# By Gerald Combs <gerald@wireshark.org> +# Copyright 1998 Gerald Combs +# +# SPDX-License-Identifier: GPL-2.0-or-later +# + +cmake_minimum_required(VERSION 3.12) +cmake_policy(SET CMP0048 NEW) + +project(Hello VERSION 0.0.1 DESCRIPTION "Wireshark Hello Plugin" LANGUAGES C) + +find_package(Wireshark CONFIG REQUIRED) + +if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT) + set(CMAKE_INSTALL_PREFIX "${Wireshark_INSTALL_PREFIX}" + CACHE PATH "Installation prefix" FORCE + ) +endif() + +if(NOT Wireshark_PLUGINS_ENABLED) + message(WARNING "Wireshark was compiled without support for plugins") +endif() + +# External plugins must define HAVE_SSIZE_T for the plugin toolchain. +include(CheckTypeSize) +check_type_size("ssize_t" SSIZE_T) + +set(CMAKE_C_VISIBILITY_PRESET hidden) +if(CMAKE_COMPILER_IS_GNUCC) + set(CMAKE_C_FLAGS "-Wall -Wextra ${CMAKE_C_FLAGS}") +endif() + +add_compile_definitions( + VERSION=\"${PROJECT_VERSION}\" + $<$<BOOL:${HAVE_SSIZE_T}>:HAVE_SSIZE_T> +) + +add_library(hello MODULE hello.c) +set_target_properties(hello PROPERTIES PREFIX "" DEFINE_SYMBOL "") +target_link_libraries(hello epan) + +# This is the normal installation target to CMAKE_INSTALL_PREFIX. It is relocatable +# using DESTDIR or cmake --install. By default CMAKE_INSTALL_PREFIX should be configured +# correctly for Wireshark's system installation prefix. +install(TARGETS hello + LIBRARY DESTINATION "${Wireshark_PLUGIN_LIBDIR}/epan" NAMELINK_SKIP +) + +# This custom target installs the plugin to the plugin dir in WiresharkConfig.cmake. +# It does not use CMAKE_INSTALL_PREFIX. +add_custom_target(copy_plugin + COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_FILE:hello> "${Wireshark_PLUGIN_INSTALL_DIR}/epan" + COMMENT "Installing plugin to: ${Wireshark_PLUGIN_INSTALL_DIR}/epan" +) + +string(TOLOWER "${PROJECT_NAME}-${PROJECT_VERSION}" _pkgname) + +add_custom_target(package_prep + COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/${_pkgname} + COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/README $<TARGET_FILE:hello> ${CMAKE_BINARY_DIR}/${_pkgname} +) + +add_custom_target(package + COMMAND ${CMAKE_COMMAND} -E tar czf ${CMAKE_BINARY_DIR}/${_pkgname}.tar.gz --format=gnutar -- ${CMAKE_BINARY_DIR}/${_pkgname} +) +add_dependencies(package package_prep) + +add_custom_target(package_zip + COMMAND ${CMAKE_COMMAND} -E tar cf ${CMAKE_BINARY_DIR}/${_pkgname}.zip --format=zip -- ${CMAKE_BINARY_DIR}/${_pkgname} +) +add_dependencies(package_zip package_prep) diff --git a/doc/plugins.example/README b/doc/plugins.example/README new file mode 100644 index 0000000..27d6f48 --- /dev/null +++ b/doc/plugins.example/README @@ -0,0 +1,35 @@ + +This is an example of how to build a Wireshark plugin out-of-tree. This +is an alternative, more recent way to build Wireshark binary plugins, +than the one in 'README.plugins', that describes in detail how to +include a new plugin into the project source tree (here called in-tree +build). Building a plugin out-of-tree doesn't require rebuilding the whole +Wireshark source tree every time. + +You always need to rebuild plugins for each major.minor Wireshark version. +Binary compatibility is never guaranteed between those releases and Wireshark +will explicitly check for which version the plugin was built and refuse +to load it otherwise. + +Note that the out-of-tree method builds the plugin using CMake's Config-file +mechanism[1] for configuration. In other words the plugin build system uses +the Wireshark headers that were installed on the system using "make install" +or equivalent (as configured from WiresharkConfig.cmake). This is not the same +as an in-tree build. + +You should of course adapt this trivial example to your own needs. + +To build/install the plugin: + +$ mkdir build && cd build +$ cmake .. +$ make +$ sudo make install + +If your WiresharkConfig.cmake file is not in one of the standard cmake search +paths you will have to tell cmake where to find it. You can do so using +CMAKE_PREFIX_PATH, for example: + +$ cmake -DCMAKE_PREFIX_PATH="/opt/wireshark" .. + +[1]https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#config-file-packages diff --git a/doc/plugins.example/hello.c b/doc/plugins.example/hello.c new file mode 100644 index 0000000..7a252c8 --- /dev/null +++ b/doc/plugins.example/hello.c @@ -0,0 +1,58 @@ +/* hello.c + * + * Wireshark - Network traffic analyzer + * By Gerald Combs <gerald@wireshark.org> + * Copyright 1998 Gerald Combs + * + * SPDX-License-Identifier: GPL-2.0-or-later + */ + +#define WS_BUILD_DLL +#include <wireshark.h> +#include <epan/packet.h> +#include <epan/proto.h> + +#ifndef VERSION +#define VERSION "0.0.0" +#endif + +WS_DLL_PUBLIC_DEF const char plugin_version[] = VERSION; +WS_DLL_PUBLIC_DEF const int plugin_want_major = WIRESHARK_VERSION_MAJOR; +WS_DLL_PUBLIC_DEF const int plugin_want_minor = WIRESHARK_VERSION_MINOR; + +WS_DLL_PUBLIC void plugin_register(void); + + +static int proto_hello = -1; +static dissector_handle_t handle_hello; + +static int +dissect_hello(tvbuff_t *tvb, packet_info *pinfo _U_, proto_tree *tree, void *data _U_) +{ + proto_tree_add_protocol_format(tree, proto_hello, tvb, 0, -1, "This is Hello version %s, a Wireshark postdissector plugin prototype", plugin_version); + return tvb_captured_length(tvb); +} + +static void +proto_register_hello(void) +{ + proto_hello = proto_register_protocol("Wireshark Hello Plugin", "Hello WS", "hello_ws"); + handle_hello = create_dissector_handle(dissect_hello, proto_hello); + register_postdissector(handle_hello); +} + +static void +proto_reg_handoff_hello(void) +{ + /* empty */ +} + +void +plugin_register(void) +{ + static proto_plugin plug; + + plug.register_protoinfo = proto_register_hello; + plug.register_handoff = proto_reg_handoff_hello; /* or NULL */ + proto_register_plugin(&plug); +} diff --git a/doc/randpkt.adoc b/doc/randpkt.adoc new file mode 100644 index 0000000..97104b7 --- /dev/null +++ b/doc/randpkt.adoc @@ -0,0 +1,147 @@ +include::../docbook/attributes.adoc[] += randpkt(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/randpkt.txt b/doc/randpkt.txt new file mode 100644 index 0000000..0062f10 --- /dev/null +++ b/doc/randpkt.txt @@ -0,0 +1,95 @@ +Random Packet Generator +----------------------- +randpkt is a small utility creates a libpcap trace file full of random packets. +You can control the number of packets, the maximum size of each packet, +and the type of each packet. It is not build by default, but you +can create it in the top-level Wireshark directory by typing: + +make randpkt + +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. + +Run 'randpkt' with no options to see the usage statement. As of the +writing of this text, the usage is: + +Usage: randpkt [-b maxbytes] [-c count] [-t type] filename + +The usage statement produced by randpkt will list the legal types. + +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. + +To add a new packet type to randpkt, you must add information +in the following locations. + +1) Add the packet type name to the enum of produceable packets: + + /* Types of produceable packets */ + enum { + PKT_ARP, + PKT_ETHERNET, + PKT_FDDI, + PKT_LLC, + PKT_TR + }; + + +2) Type in the bytes from your sample packet + + /* Ethernet, indicating ARP */ + uint8_t pkt_arp[] = { + 0xff, 0xff, 0xff, 0xff, + 0xff, 0xff, 0x00, 0x00, + 0x32, 0x25, 0x0f, 0xff, + 0x08, 0x06 + }; + + +3) Add a record to the 'examples' array. The fields are + 1. Abbreviation (for use in '-t' command line argument) + 2. Full name (for use in usage statement) + 3. Enum type + 4. Array holding sample packet + 5. Wiretap encapsulation type of datalink layer in your + sample packet + 6. Length of sample packet. Use the handy array_length() + macro to avoid counting the bytes yourself. + + + pkt_example examples[] = { + { "arp", + "Address Resolution Protocol", + PKT_ARP, + pkt_arp, + WTAP_ENCAP_ETHERNET, + array_length(pkt_arp) }, + + { "eth", + "Ethernet", + PKT_ETHERNET, + NULL, + WTAP_ENCAP_ETHERNET, + 0 }, + }; + +Note that packets that designate only their datalink type have no sample +arrays, since the only thing that needs to be set is the datalink type, +which is a field in the libpcap frame record; it's not a part of the +packet itself. + +Enjoy! diff --git a/doc/randpktdump.adoc b/doc/randpktdump.adoc new file mode 100644 index 0000000..3e13a77 --- /dev/null +++ b/doc/randpktdump.adoc @@ -0,0 +1,142 @@ +include::../docbook/attributes.adoc[] += randpktdump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/rawshark.adoc b/doc/rawshark.adoc new file mode 100644 index 0000000..9a28eda --- /dev/null +++ b/doc/rawshark.adoc @@ -0,0 +1,551 @@ +include::../docbook/attributes.adoc[] += rawshark(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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 (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. +-- + +-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. + +include::dissection-options.adoc[tags=!tshark;!decode_as] + +include::diagnostic-options.adoc[] + +== READ FILTER SYNTAX + +For a complete table of protocol and protocol fields that are filterable +in *TShark* see the xref:wireshark-filter.html[wireshark-filter](4) manual page. + +== FILES + +These files contains various *Wireshark* configuration values. + +Preferences:: ++ +-- +The __preferences__ files contain global (system-wide) and personal +preference settings. If the system-wide preference file exists, it is +read first, overriding the default settings. If the personal preferences +file exists, it is read next, overriding any previous values. Note: If +the command line option *-o* is used (possibly more than once), it will +in turn override values from the preferences files. + +The preferences settings are in the form __prefname:value__, +one per line, +where __prefname__ is the name of the preference +and __value__ is the value to +which it should be set; white space is allowed between *:* and +__value__. A preference setting can be continued on subsequent lines by +indenting the continuation lines with white space. A *#* character +starts a comment that runs to the end of the line: + + # Capture in promiscuous mode? + # TRUE or FALSE (case-insensitive). + capture.prom_mode: TRUE + +The global preferences file is looked for in the __wireshark__ directory +under the __share__ subdirectory of the main installation directory. On +macOS, this would typically be +__/Application/Wireshark.app/Contents/Resources/share__; on other +UNIX-compatible systems, such as Linux, \*BSD, Solaris, and AIX, this +would typically be __/usr/share/wireshark/preferences__ for +system-installed packages and __/usr/local/share/wireshark/preferences__ +for locally-installed packages; on Windows, this would typically be +__C:\Program Files\Wireshark\preferences__. + +On UNIX-compatible systems, the personal preferences file is looked for +in __$XDG_CONFIG_HOME/wireshark/preferences__, (or, if +__$XDG_CONFIG_HOME/wireshark__ does not exist while __$HOME/.wireshark__ +does exist, __$HOME/.wireshark/preferences__); this is typically +__$HOME/.config/wireshark/preferences__. On Windows, +the personal preferences file is looked for in +__%APPDATA%\Wireshark\preferences__ (or, if %APPDATA% isn't defined, +__%USERPROFILE%\Application Data\Wireshark\preferences__). +-- + +Disabled (Enabled) Protocols:: ++ +-- +The __disabled_protos__ files contain system-wide and personal lists of +protocols that have been disabled, so that their dissectors are never +called. The files contain protocol names, one per line, where the +protocol name is the same name that would be used in a display filter +for the protocol: + + http + tcp # a comment + +The global __disabled_protos__ file uses the same directory as the global +preferences file. + +The personal __disabled_protos__ file uses the same directory as the +personal preferences file. +-- + +Name Resolution (hosts):: ++ +-- +If the personal __hosts__ file exists, it is +used to resolve IPv4 and IPv6 addresses before any other +attempts are made to resolve them. The file has the standard __hosts__ +file syntax; each line contains one IP address and name, separated by +whitespace. The same directory as for the personal preferences file is +used. + +Capture filter name resolution is handled by libpcap on UNIX-compatible +systems, such as Linux, macOS, \*BSD, Solaris, and AIX, and by Npcap or +WinPcap on Windows. As such the Wireshark personal __hosts__ file will +not be consulted for capture filter name resolution. +-- + +Name Resolution (subnets):: ++ +-- +If an IPv4 address cannot be translated via name resolution (no exact +match is found) then a partial match is attempted via the __subnets__ file. + +Each line of this file consists of an IPv4 address, a subnet mask length +separated only by a / and a name separated by whitespace. While the address +must be a full IPv4 address, any values beyond the mask length are subsequently +ignored. + +An example is: + +# Comments must be prepended by the # sign! +192.168.0.0/24 ws_test_network + +A partially matched name will be printed as "subnet-name.remaining-address". +For example, "192.168.0.1" under the subnet above would be printed as +"ws_test_network.1"; if the mask length above had been 16 rather than 24, the +printed address would be ``ws_test_network.0.1". +-- + +Name Resolution (ethers):: ++ +-- +The __ethers__ files are consulted to correlate 6-byte hardware addresses to +names. First the personal __ethers__ file is tried and if an address is not +found there the global __ethers__ file is tried next. + +Each line contains one hardware address and name, separated by +whitespace. The digits of the hardware address are separated by colons +(:), dashes (-) or periods (.). The same separator character must be +used consistently in an address. The following three lines are valid +lines of an __ethers__ file: + + ff:ff:ff:ff:ff:ff Broadcast + c0-00-ff-ff-ff-ff TR_broadcast + 00.00.00.00.00.00 Zero_broadcast + +The global __ethers__ file is looked for in the __/etc__ directory on +UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX, +and in the main installation directory (for example, __C:\Program +Files\Wireshark__) on Windows systems. + +The personal __ethers__ file is looked for in the same directory as the personal +preferences file. + +Capture filter name resolution is handled by libpcap on UNIX-compatible +systems and Npcap or WinPcap on Windows. As such the Wireshark personal +__ethers__ file will not be consulted for capture filter name resolution. +-- + +Name Resolution (manuf):: ++ +-- +The __manuf__ file is used to match the 3-byte vendor portion of a 6-byte +hardware address with the manufacturer's name; it can also contain well-known +MAC addresses and address ranges specified with a netmask. The format of the +file is the same as the __ethers__ files, except that entries of the form: + + 00:00:0C Cisco + +can be provided, with the 3-byte OUI and the name for a vendor, and +entries such as: + + 00-00-0C-07-AC/40 All-HSRP-routers + +can be specified, with a MAC address and a mask indicating how many bits +of the address must match. The above entry, for example, has 40 +significant bits, or 5 bytes, and would match addresses from +00-00-0C-07-AC-00 through 00-00-0C-07-AC-FF. The mask need not be a +multiple of 8. + +The __manuf__ file is looked for in the same directory as the global +preferences file. +-- + +Name Resolution (services):: ++ +-- +The __services__ file is used to translate port numbers into names. + +The file has the standard __services__ file syntax; each line contains one +(service) name and one transport identifier separated by white space. The +transport identifier includes one port number and one transport protocol name +(typically tcp, udp, or sctp) separated by a /. + +An example is: + + mydns 5045/udp # My own Domain Name Server + mydns 5045/tcp # My own Domain Name Server +-- + +Name Resolution (ipxnets):: ++ +-- +The __ipxnets__ files are used to correlate 4-byte IPX network numbers to +names. First the global __ipxnets__ file is tried and if that address is not +found there the personal one is tried next. + +The format is the same as the __ethers__ +file, except that each address is four bytes instead of six. +Additionally, the address can be represented as a single hexadecimal +number, as is more common in the IPX world, rather than four hex octets. +For example, these four lines are valid lines of an __ipxnets__ file: + + C0.A8.2C.00 HR + c0-a8-1c-00 CEO + 00:00:BE:EF IT_Server1 + 110f FileServer3 + +The global __ipxnets__ file is looked for in the __/etc__ directory on +UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX, +and in the main installation directory (for example, __C:\Program +Files\Wireshark__) on Windows systems. + +The personal __ipxnets__ file is looked for in the same directory as the +personal preferences file. +-- + +== 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/release-notes.adoc b/doc/release-notes.adoc new file mode 100644 index 0000000..b735d99 --- /dev/null +++ b/doc/release-notes.adoc @@ -0,0 +1,147 @@ +include::../docbook/attributes.adoc[] +:stylesheet: ws.css +:linkcss: +:copycss: {stylesheet} + += Wireshark {wireshark-version} Release Notes +// Asciidoctor Syntax Quick Reference: +// https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ + +== What is Wireshark? + +Wireshark is the world’s most popular network protocol analyzer. +It is used for troubleshooting, analysis, development and education. + +Wireshark is hosted by the Wireshark Foundation, a nonprofit which promotes protocol analysis educaton. +Wireshark and the foundation depend on your contributions in order to do their work. +If you or your employer would like to contribute or become a sponsor, please visit https://wiresharkfoundation.org[wiresharkfoundation.org]. + +== What’s New + +=== Bug Fixes + +This release fixes a software update issue on Windows which causes Wireshark to hang if you are upgrading from version 4.2.0 or 4.2.1. +If you are experiencing this issue you will need to https://www.wireshark.org/download.html[download and install] Wireshark 4.2.2 or later. + +// The following vulnerabilities have been fixed: + +// * wssalink:2024-06[] +// Foo dissector {crash,infinite loop,memory leak}. +// wsbuglink:xxx[]. +// cveidlink:2024-xxx[]. +// Fixed in master: xxx +// Fixed in release-4.2: xxx +// Fixed in release-4.0: xxx +// Fixed in release-3.6: xxx +// CVSS AV:L/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H +// CWE-125 + +The following bugs have been fixed: + +//* wsbuglink:5000[] +//* wsbuglink:6000[Wireshark bug] +//* cveidlink:2014-2486[] +//* Wireshark grabs your ID at 3 am, goes to Waffle House, and insults people. + +* sharkd is not installed by the Windows installer. wsbuglink:19556[]. +* Fuzz job crash output: fuzz-2024-01-01-7740.pcap. wsbuglink:19558[]. +* Can't open a snoop file from the Open dialog box unless I select \"All files\" as the file type. wsbuglink:19565[]. +* Add s4607 dissector to \"decode as\" wsbuglink:19566[]. +* Updater for 4.2.1 hangs. wsbuglink:19568[]. + +=== New and Updated Features + +There are no new or updated features in this release. + +// === Removed Features and Support + +// === Removed Dissectors + +// === New File Format Decoding Support + + +=== New Protocol Support + +There are no new protocols in this release. + +=== Updated Protocol Support + +// Add one protocol per line between the -- delimiters. +// ag -A1 '(define PSNAME|proto_register_protocol[^_])' $(git diff --name-only v4.2.2.. | ag packet- | sort -u) +[commaize] +-- +RSVP +RTPS +STANAG 4607 +-- + +=== New and Updated Capture File Support + +There is no new or updated capture file support in this release. +// Add one file type per line between the -- delimiters. +// [commaize] +// -- +// -- + +// === New and Updated Capture Interfaces support + +// === New and Updated Codec support + +// === Major API Changes + +== Prior Versions + +This document only describes the changes introduced in Wireshark {wireshark-version}. +You can find release notes for prior versions at the following locations: + +* https://www.wireshark.org/docs/relnotes/wireshark-4.2.1.html[Wireshark 4.2.1] +* https://www.wireshark.org/docs/relnotes/wireshark-4.2.0.html[Wireshark 4.2.0] + +== Getting Wireshark + +Wireshark source code and installation packages are available from +https://www.wireshark.org/download.html. + +=== Vendor-supplied Packages + +Most Linux and Unix vendors supply their own Wireshark packages. +You can usually install or upgrade Wireshark using the package management system specific to that platform. +A list of third-party packages can be found on the +https://www.wireshark.org/download.html[download page] +on the Wireshark web site. + +== File Locations + +Wireshark and TShark look in several different locations for preference files, plugins, SNMP MIBS, and RADIUS dictionaries. +These locations vary from platform to platform. +You can use menu:Help[About Wireshark,Folders] or `tshark -G folders` to find the default locations on your system. + +== Getting Help + +The User’s Guide, manual pages and various other documentation can be found at +https://www.wireshark.org/docs/ + +Community support is available on +https://ask.wireshark.org/[Wireshark’s Q&A site] +and on the wireshark-users mailing list. +Subscription information and archives for all of Wireshark’s mailing lists can be found on +https://www.wireshark.org/lists/[the web site]. + +Bugs and feature requests can be reported on +https://gitlab.com/wireshark/wireshark/-/issues[the issue tracker]. + +You can learn protocol analysis and meet Wireshark’s developers at +https://sharkfest.wireshark.org[SharkFest]. + +// Official Wireshark training and certification are available from +// https://www.wiresharktraining.com/[Wireshark University]. + +== How You Can Help + +The Wireshark Foundation helps as many people as possible understand their networks as much as possible. +You can find out more and donate at https://wiresharkfoundation.org[wiresharkfoundation.org]. + +== Frequently Asked Questions + +A complete FAQ is available on the +https://www.wireshark.org/faq.html[Wireshark web site]. diff --git a/doc/reordercap.adoc b/doc/reordercap.adoc new file mode 100644 index 0000000..fd57b0a --- /dev/null +++ b/doc/reordercap.adoc @@ -0,0 +1,84 @@ +include::../docbook/attributes.adoc[] += reordercap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/sdjournal.adoc b/doc/sdjournal.adoc new file mode 100644 index 0000000..bf9a368 --- /dev/null +++ b/doc/sdjournal.adoc @@ -0,0 +1,132 @@ +include::../docbook/attributes.adoc[] += sdjournal(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/sshdump.adoc b/doc/sshdump.adoc new file mode 100644 index 0000000..8acacd1 --- /dev/null +++ b/doc/sshdump.adoc @@ -0,0 +1,313 @@ +include::../docbook/attributes.adoc[] += sshdump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/text2pcap.adoc b/doc/text2pcap.adoc new file mode 100644 index 0000000..ab89474 --- /dev/null +++ b/doc/text2pcap.adoc @@ -0,0 +1,421 @@ +include::../docbook/attributes.adoc[] += text2pcap(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{stylesheet} + +== NAME + +text2pcap - Generate a capture file from an ASCII hexdump of packets + +== SYNOPSIS + +[manarg] +*text2pcap* +[ *-a* ] +[ *-b* 2|8|16|64 ] +[ *-D* ] +[ *-e* <l3pid> ] +[ *-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. + +*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 <l3pid>:: ++ +-- +Include a dummy Ethernet header before each packet. Specify the L3PID +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 dest and source address. +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 dest and source address. +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. +-- + +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/tshark.adoc b/doc/tshark.adoc new file mode 100644 index 0000000..6f086d6 --- /dev/null +++ b/doc/tshark.adoc @@ -0,0 +1,2613 @@ +include::../docbook/attributes.adoc[] += tshark(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{stylesheet} + +== NAME + +tshark - Dump and analyze network traffic + +== SYNOPSIS + +[manarg] +*tshark* +[ *-i* <capture interface>|- ] +[ *-f* <capture filter> ] +[ *-2* ] +[ *-r* <infile> ] +[ *-w* <outfile>|- ] +[ *options* ] +[ <filter> ] + +[manarg] +*tshark* +*-G* [ <report type> ] [ --elastic-mapping-filter <protocols> ] + +[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, zstd or lz4 compression will be automatically detected. Near the +beginning of the DESCRIPTION section of xref:wireshark.html[wireshark](1) or +https://www.wireshark.org/docs/man-pages/wireshark.html is a detailed +description of the way *Wireshark* handles this, which is the same way +*TShark* handles this. + +Compressed file support uses (and therefore requires) the zlib library. +If the zlib library is not present when compiling *TShark*, it will be +possible to compile it, but the resulting program will be unable to read +compressed files. + +When displaying packets on the standard output, *TShark* writes, by +default, a summary line containing the fields specified by the +preferences file (which are also the fields displayed in the packet list +pane in *Wireshark*), although if it's writing packets as it captures +them, rather than writing packets from a saved capture file, it won't +show the "frame number" field. If the *-V* option is specified, it +instead writes a view of the details of the packet, showing all the +fields of all protocols in the packet. If the *-O* option is +specified, it will only show the full details for the protocols +specified, and show only the top-level detail line for all other +protocols. Use the output of "*tshark -G protocols*" to find the +abbreviations of the protocols you can specify. If the *-P* option is +specified with either the *-V* or *-O* options, both the summary line +for the entire packet and the details will be displayed. + +Packet capturing is performed with the pcap library. That library +supports specifying a filter expression; packets that don't match that +filter are discarded. The *-f* option is used to specify a capture +filter. The syntax of a capture filter is defined by the pcap library; +this syntax is different from the display filter syntax described below, +and the filtering mechanism is limited in its abilities. + +Display filters in *TShark*, which allow you to select which packets are +to be decoded or written to a file, are very powerful; more fields are +filterable in *TShark* than in other protocol analyzers, and the syntax +you can use to create your filters is richer. As *TShark* progresses, +expect more and more protocol fields to be allowed in display filters. +Display filters use the same syntax as display and color filters in +*Wireshark*; a display filter is specified with the *-Y* option. + +Display filters can be specified when capturing or when reading from a +capture file. Note that capture filters are much more efficient +than display filters, and it may be more difficult for *TShark* to keep up +with a busy network if a display filter is specified for a live capture, so +you might be more likely to lose packets if you're using a display filter. + +A capture or display filter can either be specified with the *-f* or *-Y* +option, respectively, in which case the entire filter expression must be +specified as a single argument (which means that if it contains spaces, +it must be quoted), or can be specified with command-line arguments +after the option arguments, in which case all the arguments after the +filter arguments are treated as a filter expression. If the filter is +specified with command-line arguments after the option arguments, it's a +capture filter if a capture is being done (i.e., if no *-r* option was +specified) and a display filter if a capture file is being read (i.e., if a +*-r* option was specified). + +If the *-w* option is specified when capturing packets or reading from +a capture file, *TShark* does not display packets on the standard +output. Instead, it writes the packets to a capture file with the name +specified by the *-w* option. Note that display filters are currently +not supported when capturing and saving the captured packets. + +If you want to write the decoded form of packets to a file, run +*TShark* without the *-w* option, and redirect its standard output to +the file (do __not__ use the *-w* option). + +If you want the packets to be displayed to the standard output and also +saved to a file, specify the *-P* option in addition to the *-w* +option to have the summary line displayed, specify the *-V* option +in addition to the *-w* option to have the details of the packet +displayed, and specify the *-O* option, with a list of protocols, to +have the full details of the specified protocols and the top-level +detail line for all other protocols to be displayed. If the *-P* +option is used together with the *-V* or *-O* option, the summary line +will be displayed along with the detail lines. + +When writing packets to a file, *TShark*, by default, writes the file +in *pcapng* format, and writes all of the packets it sees to the output +file. The *-F* option can be used to specify the format in which to +write the file. This list of available file formats is displayed by the +*-F* option without a value. However, you can't specify a file format +for a live capture. + +When capturing packets, *TShark* writes to the standard error an +initial line listing the interfaces from which packets are being +captured and, if packet information isn't being displayed to the +terminal, writes a continuous count of packets captured to the standard +output. If the *-q* option is specified, neither the continuous count +nor the packet information will be displayed; instead, at the end of the +capture, a count of packets captured will be displayed. If the *-Q* +option is specified, neither the initial line, nor the packet +information, nor any packet counts will be displayed. If the *-q* or +*-Q* option is used, the *-P*, *-V*, or *-O* option can be used to +cause the corresponding output to be displayed even though other output +is suppressed. + +When reading packets, the *-q* and *-Q* option will suppress the +display of the packet summary or details; this would be used if *-z* +options are specified in order to display statistics, so that only the +statistics, not the packet information, is displayed. + +The *-G* option is a special mode that simply causes *TShark* +to dump one of several types of internal glossaries and then exit. + +== OPTIONS + +-2:: ++ +-- +Perform a two-pass analysis. This causes *TShark* to buffer output until the +entire first pass is done, but allows it to fill in fields that require future +knowledge, such as 'response in frame #' fields. Also permits reassembly +frame dependencies to be calculated correctly. +-- + +-a|--autostop <capture autostop condition>:: ++ +-- +Specify a criterion that specifies when *TShark* is to stop writing +to a capture file. The criterion is of the form __test:value__, +where __test__ is one of: + +*duration*:__value__ Stop writing to a capture file after __value__ seconds +have elapsed. Floating point values (e.g. 0.5) are allowed. + +*files*:__value__ Stop writing to capture files after __value__ number of files +were written. + +*filesize*:__value__ Stop writing to a capture file after it reaches a size of +__value__ kB. If this option is used together with the *-b* option, *TShark* +will stop writing to the current capture file and switch to the next one if +filesize is reached. When reading a capture file, *TShark* will stop reading +the file after the number of bytes read exceeds this number (the complete +packet will be read, so more bytes than this number may be read). Note that +the filesize is limited to a maximum value of 2 GiB. + +*packets*:__value__ switch to the next file after it contains __value__ +packets. +This does not include any packets that do not pass the display filter, so it +may differ from *-c*<capture packet count>. +-- + +-A <user>:<password>:: ++ +-- +Specify a user and a password when *TShark* captures from a rpcap:// interface +where authentication is required. + +This option is available with libpcap with enabled remote support. +-- + +-b|--ring-buffer <capture ring buffer option>:: ++ +-- +Cause *TShark* to run in "multiple files" mode. In "multiple files" mode, +*TShark* will write to several capture files. When the first capture file +fills up, *TShark* will switch writing to the next file and so on. + +The created filenames are based on the filename given with the *-w* option, +the number of the file and on the creation date and time, +e.g. outfile_00001_20230714120117.pcap, outfile_00002_20230714120523.pcap, ... + +With the __files__ option it's also possible to form a "ring buffer". +This will fill up new files until the number of files specified, +at which point *TShark* will discard the data in the first file and start +writing to that file and so on. If the __files__ option is not set, +new files filled up until one of the capture stop conditions match (or +until the disk is full). + +The criterion is of the form __key:value__, +where __key__ is one of: + +*duration*:__value__ switch to the next file after __value__ seconds have +elapsed, even if the current file is not completely filled up. Floating +point values (e.g. 0.5) are allowed. + +*files*:__value__ begin again with the first file after __value__ number of +files were written (form a ring buffer). This value must be less than 100000. +Caution should be used when using large numbers of files: some filesystems do +not handle many files in a single directory well. The *files* criterion +requires either *duration*, *interval* or *filesize* to be specified to +control when to go to the next file. It should be noted that each *-b* +parameter takes exactly one criterion; to specify two criterion, each must be +preceded by the *-b* option. + +*filesize*:__value__ switch to the next file after it reaches a size of +__value__ kB. Note that the filesize is limited to a maximum value of 2 GiB. + +*interval*:__value__ switch to the next file when the time is an exact +multiple of __value__ seconds. For example, use 3600 to switch to a new file +every hour on the hour. + +*packets*:__value__ switch to the next file after it contains __value__ +packets. + +*nametimenum*:__value__ Choose between two save filename templates. If +__value__ is 1, make running file number part before start time part; this is +the original and default behaviour (e.g. log_00001_20230714164426.pcap). If +__value__ is greater than 1, make start time part before running number part +(e.g. log_20210828164426_00001.pcap). The latter makes alphabetical sorting +order equal to creation time order, and keeps related multiple file sets in +same directory close to each other. + +Example: *tshark -b filesize:1000 -b files:5* results in a ring buffer of five +files of size one megabyte each. +-- + +-B|--buffer-size <capture buffer size>:: ++ +-- +Set capture buffer size (in MiB, default is 2 MiB). This is used by +the capture driver to buffer packet data until that data can be written +to disk. If you encounter packet drops while capturing, try to increase +this size. Note that, while *TShark* attempts to set the buffer size +to 2 MiB by default, and can be told to set it to a larger value, the +system or interface on which you're capturing might silently limit the +capture buffer size to a lower value or raise it to a higher value. + +This is available on UNIX-compatible systems, such as Linux, macOS, +\*BSD, Solaris, and AIX, with libpcap 1.0.0 or later, and on Windows. +It is not available on UNIX-compatible systems with earlier versions of +libpcap. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it sets the default capture buffer size. +If used after an *-i* option, it sets the capture buffer size for +the interface specified by the last *-i* option occurring before +this option. If the capture buffer size is not set specifically, +the default capture buffer size is used instead. +-- + +-c <capture packet count>:: ++ +-- +Set the maximum number of packets to read when capturing live +data. +If reading a capture file, set the maximum number of packets to read. +This includes any packets that do not pass the display filter, so it +may differ from *-a packets:*<capture packet count>. +-- + +-C <configuration profile>:: ++ +-- +Run with the given configuration profile. +-- + +-D|--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 -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). + +*escape=y|n* If *y*, the whitespace control characters (tab, line feed, +carriage return, form feed, and vertical tab) and backspace will be +replaced in field values by C-style escapes, e.g. "\n" for line feed. +If *n*, field value strings will be printed as-is. Defaults to *y*. +-- + +-f <capture filter>:: ++ +-- +Set the capture filter expression. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it sets the default capture filter expression. +If used after an *-i* option, it sets the capture filter expression for +the interface specified by the last *-i* option occurring before +this option. If the capture filter expression is not set specifically, +the default capture filter expression is used if provided. + +Pre-defined capture filter names, as shown in the GUI menu item Capture->Capture +Filters, can be used by prefixing the argument with "predef:". +Example: *tshark -f "predef:MyPredefinedHostOnlyFilter"* +-- + +-F <file format>:: +Set the file format of the output capture file written using the *-w* +option. The output written with the *-w* option is raw packet data, not +text, so there is no *-F* option to request text output. The option *-F* +without a value will list the available formats. + +-g:: +This option causes the output file(s) to be created with group-read permission +(meaning that the output file(s) can be read by other members of the calling +user's group). + +-G [ <report type> ]:: ++ +-- +The *-G* option will cause *TShark* to dump one of several types of glossaries +and then exit. If no specific glossary type is specified, then the *fields* +report will be generated by default. +Using the report type of *help* lists all the current report types. + +The available report types include: + +*column-formats* Dumps the column formats understood by *TShark*. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: format string (e.g. "%rD") +Field 2:: text description of format string (e.g. "Dest port (resolved)") + +*currentprefs* Dumps a copy of the current preferences file to stdout. + +*decodes* Dumps the "layer type"/"decode as" associations to stdout. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: layer type, e.g. "tcp.port" +Field 2:: selector in decimal +Field 3:: "decode as" name, e.g. "http" + +*defaultprefs* Dumps a default preferences file to stdout. + +*dissectors* Dumps a list of registered dissectors to stdout. There is +one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: dissector name +Field 2:: dissector description + +*dissector-tables* Dumps a list of dissector tables to stdout. There +is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: dissector table name, e.g. "tcp.port" +Field 2:: name used for the dissector table in the GUI +Field 3:: type (textual representation of the ftenum type) +Field 4:: base for display (for integer types) +Field 5:: protocol name +Field 6:: "decode as" support + +*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:: underlying dissector (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 -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 -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 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 gzipped files). It is possible to use named pipes or stdin (-) +here but only with certain (not compressed) capture file formats (in +particular: those that can be read without seeking backwards). +-- + +-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 '-'. + +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-lte,stat[,__filter__]:: ++ +-- +This option will activate a counter for LTE MAC messages. You will get +information about the maximum number of UEs/TTI, common messages and +various counters for each UE that appears in the log. + +Example: *tshark -z mac-lte,stat*. + +This option can be used multiple times on the command line. + +Example: *-z "mac-lte,stat,mac-lte.rnti>3000"* will only collect stats for +UEs with an assigned RNTI whose value is more than 3000. +-- + +*-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* 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-lte,stat[,__filter__]:: ++ +-- +This option will activate a counter for LTE RLC messages. You will get +information about common messages and various counters for each UE that appears +in the log. + +Example: *tshark -z rlc-lte,stat*. + +This option can be used multiple times on the command line. + +Example: *-z "rlc-lte,stat,rlc-lte.ueid>3000"* will only collect stats for +UEs with a UEId of more than 3000. +-- + +*-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 +https://gitlab.com/wireshark/wireshark/-/wikis/ColoringRules for more information on +configuring color filters. + +--no-duplicate-keys:: +If a key appears multiple times in an object, only write it a single time with +as value a json array containing all the separate values. (Only works with +*-T json*) + +--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). + +include::dissection-options.adoc[tag=!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, https://gitlab.com/wireshark/wireshark/-/wikis/CaptureFilters. + +== READ FILTER SYNTAX + +For a complete table of protocol and protocol fields that are filterable +in *TShark* see the xref:wireshark-filter.html[wireshark-filter](4) manual page. + +== FILES + +These files contains various *Wireshark* configuration values. + +Preferences:: ++ +-- +The __preferences__ files contain global (system-wide) and personal +preference settings. If the system-wide preference file exists, it is +read first, overriding the default settings. If the personal preferences +file exists, it is read next, overriding any previous values. Note: If +the command line option *-o* is used (possibly more than once), it will +in turn override values from the preferences files. + +The preferences settings are in the form __prefname:value__, +one per line, +where __prefname__ is the name of the preference +and __value__ is the value to +which it should be set; white space is allowed between *:* and +__value__. A preference setting can be continued on subsequent lines by +indenting the continuation lines with white space. A *#* character +starts a comment that runs to the end of the line: + + # Capture in promiscuous mode? + # TRUE or FALSE (case-insensitive). + capture.prom_mode: TRUE + +The global preferences file is looked for in the __wireshark__ directory +under the __share__ subdirectory of the main installation directory. On +macOS, this would typically be +__/Application/Wireshark.app/Contents/Resources/share__; on other +UNIX-compatible systems, such as Linux, \*BSD, Solaris, and AIX, this +would typically be __/usr/share/wireshark/preferences__ for +system-installed packages and __/usr/local/share/wireshark/preferences__ +for locally-installed packages; on Windows, this would typically be +__C:\Program Files\Wireshark\preferences__. + +On UNIX-compatible systems, the personal preferences file is looked for +in __$XDG_CONFIG_HOME/wireshark/preferences__, (or, if +__$XDG_CONFIG_HOME/wireshark__ does not exist while __$HOME/.wireshark__ +does exist, __$HOME/.wireshark/preferences__); this is typically +__$HOME/.config/wireshark/preferences__. On Windows, +the personal preferences file is looked for in +__%APPDATA%\Wireshark\preferences__ (or, if %APPDATA% isn't defined, +__%USERPROFILE%\Application Data\Wireshark\preferences__). +-- + +Disabled (Enabled) Protocols:: ++ +-- +The __disabled_protos__ files contain system-wide and personal lists of +protocols that have been disabled, so that their dissectors are never +called. The files contain protocol names, one per line, where the +protocol name is the same name that would be used in a display filter +for the protocol: + + http + tcp # a comment + +The global __disabled_protos__ file uses the same directory as the global +preferences file. + +The personal __disabled_protos__ file uses the same directory as the +personal preferences file. +-- + +Name Resolution (hosts):: ++ +-- +If the personal __hosts__ file exists, it is +used to resolve IPv4 and IPv6 addresses before any other +attempts are made to resolve them. The file has the standard __hosts__ +file syntax; each line contains one IP address and name, separated by +whitespace. The same directory as for the personal preferences file is +used. + +Capture filter name resolution is handled by libpcap on UNIX-compatible +systems, such as Linux, macOS, \*BSD, Solaris, and AIX, and by Npcap or +WinPcap on Windows. As such the Wireshark personal __hosts__ file will +not be consulted for capture filter name resolution. +-- + +Name Resolution (subnets):: ++ +-- +If an IPv4 address cannot be translated via name resolution (no exact +match is found) then a partial match is attempted via the __subnets__ file. + +Each line of this file consists of an IPv4 address, a subnet mask length +separated only by a / and a name separated by whitespace. While the address +must be a full IPv4 address, any values beyond the mask length are subsequently +ignored. + +An example is: + +# Comments must be prepended by the # sign! +192.168.0.0/24 ws_test_network + +A partially matched name will be printed as "subnet-name.remaining-address". +For example, "192.168.0.1" under the subnet above would be printed as +"ws_test_network.1"; if the mask length above had been 16 rather than 24, the +printed address would be ``ws_test_network.0.1". +-- + +Name Resolution (ethers):: ++ +-- +The __ethers__ files are consulted to correlate 6-byte hardware addresses to +names. First the personal __ethers__ file is tried and if an address is not +found there the global __ethers__ file is tried next. + +Each line contains one hardware address and name, separated by +whitespace. The digits of the hardware address are separated by colons +(:), dashes (-) or periods (.). The same separator character must be +used consistently in an address. The following three lines are valid +lines of an __ethers__ file: + + ff:ff:ff:ff:ff:ff Broadcast + c0-00-ff-ff-ff-ff TR_broadcast + 00.00.00.00.00.00 Zero_broadcast + +The global __ethers__ file is looked for in the __/etc__ directory on +UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX, +and in the main installation directory (for example, __C:\Program +Files\Wireshark__) on Windows systems. + +The personal __ethers__ file is looked for in the same directory as the personal +preferences file. + +Capture filter name resolution is handled by libpcap on UNIX-compatible +systems and Npcap or WinPcap on Windows. As such the Wireshark personal +__ethers__ file will not be consulted for capture filter name resolution. +-- + +Name Resolution (manuf):: ++ +-- +The __manuf__ file is used to match the 3-byte vendor portion of a 6-byte +hardware address with the manufacturer's name; it can also contain well-known +MAC addresses and address ranges specified with a netmask. The format of the +file is the same as the __ethers__ files, except that entries of the form: + + 00:00:0C Cisco + +can be provided, with the 3-byte OUI and the name for a vendor, and +entries such as: + + 00-00-0C-07-AC/40 All-HSRP-routers + +can be specified, with a MAC address and a mask indicating how many bits +of the address must match. The above entry, for example, has 40 +significant bits, or 5 bytes, and would match addresses from +00-00-0C-07-AC-00 through 00-00-0C-07-AC-FF. The mask need not be a +multiple of 8. + +The __manuf__ file is looked for in the same directory as the global +preferences file. +-- + +Name Resolution (services):: ++ +-- +The __services__ file is used to translate port numbers into names. + +The file has the standard __services__ file syntax; each line contains one +(service) name and one transport identifier separated by white space. The +transport identifier includes one port number and one transport protocol name +(typically tcp, udp, or sctp) separated by a /. + +An example is: + + mydns 5045/udp # My own Domain Name Server + mydns 5045/tcp # My own Domain Name Server +-- + +Name Resolution (ipxnets):: ++ +-- +The __ipxnets__ files are used to correlate 4-byte IPX network numbers to +names. First the global __ipxnets__ file is tried and if that address is not +found there the personal one is tried next. + +The format is the same as the __ethers__ +file, except that each address is four bytes instead of six. +Additionally, the address can be represented as a single hexadecimal +number, as is more common in the IPX world, rather than four hex octets. +For example, these four lines are valid lines of an __ipxnets__ file: + + C0.A8.2C.00 HR + c0-a8-1c-00 CEO + 00:00:BE:EF IT_Server1 + 110f FileServer3 + +The global __ipxnets__ file is looked for in the __/etc__ directory on +UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX, +and in the main installation directory (for example, __C:\Program +Files\Wireshark__) on Windows systems. + +The personal __ipxnets__ file is looked for in the same directory as the +personal preferences file. +-- + +== 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/udpdump.adoc b/doc/udpdump.adoc new file mode 100644 index 0000000..8739ab6 --- /dev/null +++ b/doc/udpdump.adoc @@ -0,0 +1,121 @@ +include::../docbook/attributes.adoc[] += udpdump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/wifidump.adoc b/doc/wifidump.adoc new file mode 100644 index 0000000..e202d05 --- /dev/null +++ b/doc/wifidump.adoc @@ -0,0 +1,229 @@ +include::../docbook/attributes.adoc[] += wifidump(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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/wireshark-filter.adoc b/doc/wireshark-filter.adoc new file mode 100644 index 0000000..3e8a7b8 --- /dev/null +++ b/doc/wireshark-filter.adoc @@ -0,0 +1,648 @@ +include::../docbook/attributes.adoc[] += wireshark-filter(4) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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 + 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. + +max() and min() take any number of arguments and returns one value, respectively +the largest/smallest. The arguments must all have the same type. + +=== 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 + +=== Bitwise operators + +It is also possible to define tests with bitwise operations. Currently the +following bitwise operator is supported: + + 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) + +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} 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 + +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: https://gitlab.com/wireshark/wireshark/-/wikis/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, https://gitlab.com/wireshark/wireshark/-/wikis/CaptureFilters +for a description of capture filters. + +Display Filters are also described in the User's Guide: +https://www.wireshark.org/docs/wsug_html_chunked/ChWorkBuildDisplayFilterSection.html + +== 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/wireshark.adoc b/doc/wireshark.adoc new file mode 100644 index 0000000..ca34f54 --- /dev/null +++ b/doc/wireshark.adoc @@ -0,0 +1,2735 @@ +include::../docbook/attributes.adoc[] += wireshark(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{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. *Wireshark* recognizes this directly from +the file; the '.gz' 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 GiB. + +*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_20230714120117.pcap, outfile_00002_20230714120523.pcap, ... + +With the __files__ option it's also possible to form a "ring buffer". +This will fill up new files until the number of files specified, +at which point *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 GiB. + +*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"* +-- + +--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 gzipped files). It's not possible to use named pipes or stdin +here! 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[tag=!tshark] + +include::diagnostic-options.adoc[] + +== INTERFACE + +=== MENU ITEMS + +menu:File[Open]:: + +menu:File[Open Recent]:: + +menu:File[Merge]:: +Merge another capture file to the currently loaded one. The __File:Merge__ +dialog box allows the merge "Prepended", "Chronologically" or "Appended", +relative to the already loaded one. + +menu:File[Close]:: +Open or close a capture file. The __File:Open__ dialog box +allows a filter to be specified; when the capture file is read, the +filter is applied to all packets read from the file, and packets not +matching the filter are discarded. The __File:Open Recent__ is a submenu +and will show a list of previously opened files. + +menu:File[Save]:: + +menu:File[Save As]:: +Save the current capture, or the packets currently displayed from that +capture, to a file. Check boxes let you select whether to save all +packets, or just those that have passed the current display filter and/or +those that are currently marked, and an option menu lets you select (from +a list of file formats in which at particular capture, or the packets +currently displayed from that capture, can be saved), a file format in +which to save it. + +menu:File[File Set,List Files]:: +Show a dialog box that lists all files of the file set matching the currently +loaded file. A file set is a compound of files resulting from a capture using +the "multiple files" / "ringbuffer" mode, recognizable by the filename pattern, +e.g.: Filename_00001_20230714101530.pcap. + +menu:File[File Set,Next File]:: + +menu:File[File Set,Previous File]:: +If the currently loaded file is part of a file set (see above), open the +next / previous file in that set. + +menu:File[Export]:: +Export captured data into an external format. Note: the data cannot be +imported back into Wireshark, so be sure to keep the capture file. + +menu:File[Print]:: +Print packet data from the current capture. You can select the range of +packets to be printed (which packets are printed), and the output format of +each packet (how each packet is printed). The output format will be similar +to the displayed values, so a summary line, the packet details view, and/or +the hex dump of the packet can be printed. + +menu:File[Quit]:: +Exit the application. + +menu:Edit[Copy,Description]:: +Copies the description of the selected field in the protocol tree to the clipboard. + +menu:Edit[Copy,Fieldname]:: +Copies the fieldname of the selected field in the protocol tree to the clipboard. + +menu:Edit[Copy,Value]:: +Copies the value of the selected field in the protocol tree to the clipboard. + +menu:Edit[Copy,As Filter]:: ++ +-- +Create a display filter based on the data currently highlighted in the +packet details and copy that filter to the clipboard. + +If that data is a field that can be tested in a display filter +expression, the display filter will test that field; otherwise, the +display filter will be based on the absolute offset within the packet. +Therefore it could be unreliable if the packet contains protocols with +variable-length headers, such as a source-routed token-ring packet. +-- + +menu:Edit[Find Packet]:: ++ +-- +Search forward or backward, starting with the currently selected packet +(or the most recently selected packet, if no packet is selected). Search +criteria can be a display filter expression, a string of hexadecimal +digits, or a text string. + +When searching for a text string, you can search the packet data, or you +can search the text in the Info column in the packet list pane or in the +packet details pane. + +Hexadecimal digits can be separated by colons, periods, or dashes. +Text string searches can be ASCII or Unicode (or both), and may be +case insensitive. +-- + +menu:Edit[Find Next]:: + +menu:Edit[Find Previous]:: +Search forward / backward for a packet matching the filter from the previous +search, starting with the currently selected packet (or the most recently +selected packet, if no packet is selected). + +menu:Edit[Mark Packet (toggle)]:: +Mark (or unmark if currently marked) the selected packet. The field +"frame.marked" is set for packets that are marked, so that, for example, +a display filters can be used to display only marked packets, and so that +the /"Edit:Find Packet" dialog can be used to find the next or previous +marked packet. + +menu:Edit[Find Next Mark]:: + +menu:Edit[Find Previous Mark]:: +Find next or previous marked packet. + +menu:Edit[Mark All Packets]:: + +menu:Edit[Unmark All Packets]:: +Mark or unmark all packets that are currently displayed. + +menu:Edit[Time Reference,Set Time Reference (toggle)]:: ++ +-- +Set (or unset if currently set) the selected packet as a Time Reference packet. +When a packet is set as a Time Reference packet, the timestamps in the packet +list pane will be replaced with the string "*REF*". +The relative time timestamp in later packets will then be calculated relative +to the timestamp of this Time Reference packet and not the first packet in +the capture. + +Packets that have been selected as Time Reference packets will always be +displayed in the packet list pane. Display filters will not affect or +hide these packets. + +If there is a column displayed for "Cumulative Bytes" this counter will +be reset at every Time Reference packet. +-- + +menu:Edit[Time Reference,Find Next]:: + +menu:Edit[Time Reference,Find Previous]:: +Search forward or backward for a time referenced packet. + +menu:Edit[Configuration Profiles]:: +Manage configuration profiles to be able to use more than one set of preferences and configurations. + +menu:Edit[Preferences]:: +Set the GUI, capture, and protocol options (see /Preferences dialog below). + +menu:View[Main Toolbar]:: + +menu:View[Filter Toolbar]:: + +menu:View[Statusbar]:: +Show or hide the main window controls. + +menu:View[Packet List]:: + +menu:View[Packet Details]:: + +menu:View[Packet Bytes]:: +Show or hide the main window panes. + +menu:View[Time Display Format]:: +Set the format of the packet timestamp displayed in the packet list window. + +menu:View[Name Resolution,Resolve Name]:: +Try to resolve a name for the currently selected item. + +menu:View[Name Resolution,Enable for ... Layer]:: +Enable or disable translation of addresses to names in the display. + +menu:View[Colorize Packet List]:: +Enable or disable the coloring rules. +Disabling will improve performance. + +menu:View[Auto Scroll in Live Capture]:: +Enable or disable the automatic scrolling of the packet list while a live capture is in progress. + +menu:View[Zoom In]:: + +menu:View[Zoom Out]:: +Zoom into or out of the main window data (by changing the font size). + +menu:View[Normal Size]:: +Reset the zoom level back to normal font size. + +menu:View[Resize All Columns]:: +Resize all columns to best fit the current packet display. + +menu:View[Expand / Collapse Subtrees]:: +Expand or collapse the currently selected item and its subtrees in the packet details. + +menu:View[Expand All]:: + +menu:View[Collapse All]:: +Expand or Collapse all branches of the packet details. + +menu:View[Colorize Conversation]:: +Select a color for a conversation. + +menu:View[Reset Coloring 1-10]:: +Reset a color for a conversation. + +menu:View[Coloring Rules]:: +Change the foreground and background colors of the packet information in +the list of packets, based upon display filters. The list of display +filters is applied to each packet sequentially. After the first display +filter matches a packet, any additional display filters in the list are +ignored. Therefore, if you are filtering on the existence of protocols, +you should list the higher-level protocols first, and the lower-level +protocols last. + +How Colorization Works:: ++ +-- +Packets are colored according to a list of color filters. Each filter +consists of a name, a filter expression and a coloration. A packet is +colored according to the first filter that it matches. Color filter +expressions use exactly the same syntax as display filter expressions. + +When Wireshark starts, the color filters are loaded from: + +1. The user's personal color filters file or, if that does not exist, +2. The global color filters file. + +If neither of these exist then the packets will not be colored. +-- + +menu:View[Show Packet In New Window]:: +Create a new window containing a packet details view and a hex dump +window of the currently selected packet; this window will continue to +display that packet's details and data even if another packet is +selected. + +menu:View[Reload]:: +Reload a capture file. Same as __File:Close__ and __File:Open__ the same file again. + +menu:Go[Back]:: +Go back in previously visited packets history. + +menu:Go[Forward]:: +Go forward in previously visited packets history. + +menu:Go[Go To Packet]:: +Go to a particular numbered packet. + +menu:Go[Go To Corresponding Packet]:: +If a field in the packet details pane containing a packet number is +selected, go to the packet number specified by that field. (This works +only if the dissector that put that entry into the packet details put it +into the details as a filterable field rather than just as text.) This +can be used, for example, to go to the packet for the request +corresponding to a reply, or the reply corresponding to a request, if +that packet number has been put into the packet details. + +menu:Go[Previous Packet]:: + +menu:Go[Next Packet]:: + +menu:Go[First Packet]:: + +menu:Go[Last Packet]:: +Go to the previous, next, first, or last packet in the capture. + +menu:Go[Previous Packet In Conversation]:: + +menu:Go[Next Packet In Conversation]:: +Go to the previous or next packet of the TCP, UDP or IP conversation. + +menu:Capture[Interfaces]:: +Shows a dialog box with all currently known interfaces and displaying the +current network traffic amount. Capture sessions can be started from here. +Beware: keeping this box open results in high system load! + +menu:Capture[Options]:: +Initiate a live packet capture (see /"Capture Options Dialog" +below). If no filename is specified, a temporary file will be created +to hold the capture. Temporary files are written in the directory listed +in menu:Help[About Wireshark > Folders]. This location can be chosen with the +command line option *--temp-dir*, or by setting the environment variable +TMPDIR (on UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, +and AIX) or TEMP (on Windows) before starting **Wireshark**. + +menu:Capture[Start]:: +Start a live packet capture with the previously selected options. This won't +open the options dialog box, and can be convenient for repeatedly capturing +with the same options. + +menu:Capture[Stop]:: +Stop a running live capture. + +menu:Capture[Restart]:: +While a live capture is running, stop it and restart with the same options +again. This can be convenient to remove irrelevant packets, if no valuable +packets were captured so far. + +menu:Capture[Capture Filters]:: +Edit the saved list of capture filters, allowing filters to be added, changed, or deleted. + +menu:Analyze[Display Filters]:: +Edit the saved list of display filters, allowing filters to be added, changed, or deleted. + +menu:Analyze[Display Filter Macros]:: +Create shortcuts for complex macros. + +menu:Analyze[Apply as Filter]:: ++ +-- +Create a display filter based on the data currently highlighted in the +packet details and apply the filter. + +If that data is a field that can be tested in a display filter +expression, the display filter will test that field; otherwise, the +display filter will be based on the absolute offset within the packet. +Therefore it could be unreliable if the packet contains protocols with +variable-length headers, such as a source-routed token-ring packet. + +The *Selected* option creates a display filter that tests for a match +of the data; the *Not Selected* option creates a display filter that +tests for a non-match of the data. The *And Selected*, *Or Selected*, +*And Not Selected*, and *Or Not Selected* options add to the end of +the display filter in the strip at the top (or bottom) an AND or OR +operator followed by the new display filter expression. +-- + +menu:Analyze[Prepare as Filter]:: ++ +-- +Create a display filter based on the data currently highlighted in the +packet details. The filter strip at the top (or bottom) is updated but +it is not yet applied. +-- + +menu:Analyze[Enabled Protocols]:: ++ +-- +Allow protocol dissection to be enabled or disabled for a specific +protocol. Individual protocols can be enabled or disabled by clicking +on them in the list or by highlighting them and pressing the space bar. +The entire list can be enabled, disabled, or inverted using the buttons +below the list. + +When a protocol is disabled, dissection in a particular packet stops +when that protocol is reached, and Wireshark moves on to the next packet. +Any higher-layer protocols that would otherwise have been processed will +not be displayed. For example, disabling TCP will prevent the dissection +and display of TCP, HTTP, SMTP, Telnet, and any other protocol exclusively +dependent on TCP. + +The list of protocols can be saved, so that Wireshark will start up with +the protocols in that list disabled. +-- + +menu:Analyze[Decode As]:: +If you have a packet selected, present a dialog allowing you to change +which dissectors are used to decode this packet. The dialog has one +panel each for the link layer, network layer and transport layer +protocol/port numbers, and will allow each of these to be changed +independently. For example, if the selected packet is a TCP packet to +port 12345, using this dialog you can instruct Wireshark to decode all +packets to or from that TCP port as HTTP packets. + +menu:Analyze[User Specified Decodes]:: +Create a new window showing whether any protocol ID to dissector +mappings have been changed by the user. This window also allows the +user to reset all decodes to their default values. + +menu:Analyze[Follow TCP Stream]:: ++ +-- +If you have a TCP packet selected, display the contents of the data +stream for the TCP connection to which that packet belongs, as text, in +a separate window, and leave the list of packets in a filtered state, +with only those packets that are part of that TCP connection being +displayed. You can revert to your old view by pressing ENTER in the +display filter text box, thereby invoking your old display filter (or +resetting it back to no display filter). + +The window in which the data stream is displayed lets you select: + +* whether to display the entire conversation, or one or the other side of +it; + +* whether the data being displayed is to be treated as ASCII or EBCDIC +text or as raw hex data; + +and lets you print what's currently being displayed, using the same +print options that are used for the __File:Print Packet__ menu item, or +save it as text to a file. +-- + +menu:Analyze[Follow UDP Stream]:: + +menu:Analyze[Follow TLS Stream]:: +Similar to Analyze:Follow TCP Stream. + +menu:Analyze[Expert Info]:: + +menu:Analyze[Expert Info Composite]:: +Show anomalies found by Wireshark in a capture file. + +menu:Analyze[Conversation Filter]:: + +menu:Statistics[Summary]:: +Show summary information about the capture, including elapsed time, +packet counts, byte counts, and the like. If a display filter is in +effect, summary information will be shown about the capture and about +the packets currently being displayed. + +menu:Statistics[Protocol Hierarchy]:: +Show the number of packets, and the number of bytes in those packets, +for each protocol in the trace. It organizes the protocols in the same +hierarchy in which they were found in the trace. Besides counting the +packets in which the protocol exists, a count is also made for packets +in which the protocol is the last protocol in the stack. These +last-protocol counts show you how many packets (and the byte count +associated with those packets) *ended* in a particular protocol. In +the table, they are listed under "End Packets" and "End Bytes". + +menu:Statistics[Conversations]:: +Lists of conversations; selectable by protocol. +See Statistics:Conversation List below. + +menu:Statistics[End Points]:: +List of End Point Addresses by protocol with packets, bytes, and other counts. + +menu:Statistics[Packet Lengths]:: +Grouped counts of packet lengths (0-19 bytes, 20-39 bytes, ...) + +menu:Statistics[I/O Graphs]:: ++ +-- +Open a window where up to 5 graphs in different colors can be displayed +to indicate number of packets or number of bytes per second for all packets +matching the specified filter. +By default only one graph will be displayed showing number of packets per second. + +The top part of the window contains the graphs and scales for the X and +Y axis. If the graph is too long to fit inside the window there is a +horizontal scrollbar below the drawing area that can scroll the graphs +to the left or the right. The horizontal axis displays the time into +the capture and the vertical axis will display the measured quantity at +that time. + +Below the drawing area and the scrollbar are the controls. On the +bottom left there will be five similar sets of controls to control each +individual graph such as "Display:<button>" which button will toggle +that individual graph on/off. If <button> is ticked, the graph will be +displayed. "Color:<color>" which is just a button to show which color +will be used to draw that graph. Finally "Filter:<filter-text>" which +can be used to specify a display filter for that particular graph. + +If filter-text is empty then all packets will be used to calculate the +quantity for that graph. If filter-text is specified only those packets +that match that display filter will be considered in the calculation of +quantity. + +To the right of the 5 graph controls there are four menus to control +global aspects of the draw area and graphs. The "Unit:" menu is used to +control what to measure; "packets/tick", "bytes/tick" or "advanced..." + +packets/tick will measure the number of packets matching the (if +specified) display filter for the graph in each measurement interval. + +bytes/tick will measure the total number of bytes in all packets matching +the (if specified) display filter for the graph in each measurement +interval. + +advanced... see below + +"Tick interval:" specifies what measurement intervals to use. The +default is 1 second and means that the data will be counted over 1 +second intervals. + +"Pixels per tick:" specifies how many pixels wide each measurement +interval will be in the drawing area. The default is 5 pixels per tick. + +"Y-scale:" controls the max value for the y-axis. Default value is +"auto" which means that *Wireshark* will try to adjust the maxvalue +automatically. + +"advanced..." If Unit:advanced... is selected the window will display +two more controls for each of the five graphs. One control will be a +menu where the type of calculation can be selected from +SUM,COUNT,MAX,MIN,AVG and LOAD, and one control, textbox, where the name of a +single display filter field can be specified. + +The following restrictions apply to type and field combinations: + +SUM: available for all types of integers and will calculate the SUM of +all occurrences of this field in the measurement interval. Note that +some field can occur multiple times in the same packet and then all +instances will be summed up. Example: 'tcp.len' which will count the +amount of payload data transferred across TCP in each interval. + +COUNT: available for all field types. This will COUNT the number of times +certain field occurs in each interval. Note that some fields +may occur multiple times in each packet and if that is the case +then each instance will be counted independently and COUNT +will be greater than the number of packets. + +MAX: available for all integer and relative time fields. This will calculate +the max seen integer/time value seen for the field during the interval. +Example: 'smb.time' which will plot the maximum SMB response time. + +MIN: available for all integer and relative time fields. This will calculate +the min seen integer/time value seen for the field during the interval. +Example: 'smb.time' which will plot the minimum SMB response time. + +AVG: available for all integer and relative time fields.This will +calculate the average seen integer/time value seen for the field during +the interval. Example: 'smb.time' which will plot the average SMB +response time. + +LOAD: available only for relative time fields (response times). + +Example of advanced: +Display how NFS response time MAX/MIN/AVG changes over time: + +Set first graph to: + + filter:nfs&&rpc.time + Calc:MAX rpc.time + +Set second graph to + + filter:nfs&&rpc.time + Calc:AVG rpc.time + +Set third graph to + + filter:nfs&&rpc.time + Calc:MIN rpc.time + +Example of advanced: +Display how the average packet size from host a.b.c.d changes over time. + +Set first graph to + + filter:ip.addr==a.b.c.d&&frame.pkt_len + Calc:AVG frame.pkt_len + +LOAD: +The LOAD io-stat type is very different from anything you have ever seen +before! While the response times themselves as plotted by MIN,MAX,AVG are +indications on the Server load (which affects the Server response time), +the LOAD measurement measures the Client LOAD. +What this measures is how much workload the client generates, +i.e. how fast will the client issue new commands when the previous ones +completed. +i.e. the level of concurrency the client can maintain. +The higher the number, the more and faster is the client issuing new +commands. When the LOAD goes down, it may be due to client load making +the client slower in issuing new commands (there may be other reasons as +well, maybe the client just doesn't have any commands it wants to issue +right then). + +Load is measured in concurrency/number of overlapping i/o and the value +1000 means there is a constant load of one i/o. + +In each tick interval the amount of overlap is measured. +See the graph below containing three commands: +Below the graph are the LOAD values for each interval that would be calculated. + + | | | | | | | | | + | | | | | | | | | + | | o=====* | | | | | | + | | | | | | | | | + | o========* | o============* | | | + | | | | | | | | | + --------------------------------------------------> Time + 500 1500 500 750 1000 500 0 0 +-- + +menu:Statistics[Conversation List]:: ++ +-- +This option will open a new window that displays a list of all +conversations between two endpoints. The list has one row for each +unique conversation and displays total number of packets/bytes seen as +well as number of packets/bytes in each direction. + +By default the list is sorted according to the number of packets but by +clicking on the column header; it is possible to re-sort the list in +ascending or descending order by any column. + +By first selecting a conversation by clicking on it and then using the +right mouse button (on those platforms that have a right +mouse button) Wireshark will display a popup menu offering several different +filter operations to apply to the capture. + +These statistics windows can also be invoked from the Wireshark command +line using the *-z conv* argument. +-- + +menu:Statistics[Service Response Time]:: ++ +-- + +* AFP + +* CAMEL + +* DCE-RPC + +Open a window to display Service Response Time statistics for an +arbitrary DCE-RPC program +interface and display *Procedure*, *Number of Calls*, *Minimum SRT*, +*Maximum SRT* and *Average SRT* for all procedures for that +program/version. These windows opened will update in semi-real time to +reflect changes when doing live captures or when reading new capture +files into *Wireshark*. + +This dialog will also allow an optional filter string to be used. +If an optional filter string is used only such DCE-RPC request/response pairs +that match that filter will be used to calculate the statistics. If no filter +string is specified all request/response pairs will be used. + +* Diameter + +* Fibre Channel + +Open a window to display Service Response Time statistics for Fibre Channel +and display *FC Type*, *Number of Calls*, *Minimum SRT*, +*Maximum SRT* and *Average SRT* for all FC types. +These windows opened will update in semi-real time to +reflect changes when doing live captures or when reading new capture +files into *Wireshark*. +The Service Response Time is calculated as the time delta between the +First packet of the exchange and the Last packet of the exchange. + +This dialog will also allow an optional filter string to be used. +If an optional filter string is used only such FC first/last exchange pairs +that match that filter will be used to calculate the statistics. If no filter +string is specified all request/response pairs will be used. + +* GTP + +* H.225 RAS + +Collect requests/response SRT (Service Response Time) data for ITU-T H.225 RAS. +Data collected is *number of calls* for each known 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. +These windows opened will update in semi-real time to reflect changes when +doing live captures or when reading new capture files into *Wireshark*. + +You can apply an optional filter string in a dialog box, before starting +the calculation. The statistics will only be calculated +on those calls matching that filter. + +* LDAP + +* MEGACO + +* MGCP + +Collect requests/response SRT (Service Response Time) data for MGCP. +Data collected is *number of calls* for each known MGCP Type, +*Minimum SRT*, *Maximum SRT*, *Average SRT*, *Minimum in Packet*, and *Maximum in Packet*. +These windows opened will update in semi-real time to reflect changes when +doing live captures or when reading new capture files into *Wireshark*. + +You can apply an optional filter string in a dialog box, before starting +the calculation. The statistics will only be calculated +on those calls matching that filter. + +* NCP + +* ONC-RPC + +Open a window to display statistics for an arbitrary ONC-RPC program interface +and display *Procedure*, *Number of Calls*, *Minimum SRT*, *Maximum SRT* and *Average SRT* for all procedures for that program/version. +These windows opened will update in semi-real time to reflect changes when +doing live captures or when reading new capture files into *Wireshark*. + +This dialog will also allow an optional filter string to be used. +If an optional filter string is used only such ONC-RPC request/response pairs +that match that filter will be used to calculate the statistics. If no filter +string is specified all request/response pairs will be used. + +By first selecting a conversation by clicking on it and then using the +right mouse button (on those platforms that have a right +mouse button) Wireshark will display a popup menu offering several different +filter operations to apply to the capture. + +* RADIUS + +* SCSI + +* SMB + +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. + +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. + +You can apply an optional filter string in a dialog box, before starting +the calculation. The stats will only be calculated +on those calls matching that filter. + +By first selecting a conversation by clicking on it and then using the +right mouse button (on those platforms that have a right +mouse button) Wireshark will display a popup menu offering several different +filter operations to apply to the capture. + +* SMB2 +-- + +menu:Statistics[BOOTP-DHCP]:: +Show DHCP statistics. + +menu:Statistics[Compare]:: +Compare two capture files. + +menu:Statistics[Flow Graph]:: +Show protocol flows. + +menu:Statistics[HTTP]:: +HTTP Load Distribution, Packet Counter & Requests. + +menu:Statistics[IP Addresses]:: +Count, Rate, and Percent by IP Address. + +menu:Statistics[IP Destinations]:: +Count, Rate, and Percent by IP Address, protocol, and port. + +menu:Statistics[IP Protocol Types]:: +Count, Rate, and Percent by IP Protocol Types. + +menu:Statistics[ONC-RPC Programs]:: +This dialog will open a window showing aggregated SRT statistics for all ONC-RPC Programs/versions that exist in the capture file. + +menu:Statistics[TCP Stream Graph]:: +Show Round Trip, Throughput, Time-Sequence (Stevens), or Time-Sequence (tcptrace) graphs. + +menu:Statistics[UDP Multicast streams]:: +Multicast Streams counts, rates, and other statistics by source and destination address and port pairs. + +menu:Statistics[WLAN Traffic]:: +WLAN Traffic Statistics. + +menu:Telephony[ITU-T H.225]:: ++ +-- +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 will be displayed +in the second column. +This window opened will update in semi-real time to reflect changes when +doing live captures or when reading new capture files into *Wireshark*. + +You can apply an optional filter string in a dialog box, before starting +the counter. The statistics will only be calculated +on those calls matching that filter. +-- + +menu:Telephony[SIP]:: ++ +-- +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). + +This window opened will update in semi-real time to reflect changes when +doing live captures or when reading new capture files into *Wireshark*. + +You can apply an optional filter string in a dialog box, before starting +the counter. The statistics will only be calculated +on those calls matching that filter. +-- + +menu:Tools[Firewall ACL Rules]:: +Generate firewall rules for a selected packet. + +menu:Help[Contents]:: +Display the User's Guide. + +menu:Help[Supported Protocols]:: +List of supported protocols and display filter protocol fields. + +menu:Help[Manual Pages]:: +Display locally installed HTML versions of these manual pages in a web browser. + +menu:Help[Wireshark Online]:: +Various links to online resources to be open in a web browser, like https://www.wireshark.org. + +menu:Help[About Wireshark]:: +See various information about Wireshark (see /About dialog below), like the version, the folders used, the available plugins, ... + +=== WINDOWS + +Main Window:: ++ +-- +The main window contains the usual things like the menu, some toolbars, the +main area and a statusbar. The main area is split into three panes, you can +resize each pane using a "thumb" at the right end of each divider line. + +The main window is much more flexible than before. The layout of the main +window can be customized by the __Layout__ page in the dialog box popped +up by __Edit:Preferences__, the following will describe the layout with the +default settings. +-- + +Main Toolbar:: +Some menu items are available for quick access here. There is no way to +customize the items in the toolbar, however the toolbar can be hidden by +__View:Main Toolbar__. + +Filter Toolbar:: ++ +-- +A display filter can be entered into the filter toolbar. +A filter for HTTP, HTTPS, and DNS traffic might look like this: + + tcp.port in {80 443 53} + +Selecting the __Filter:__ button lets you choose from a list of named +filters that you can optionally save. Pressing the Return or Enter +keys, or selecting the __Apply__ button, will cause the filter to be +applied to the current list of packets. Selecting the __Reset__ button +clears the display filter so that all packets are displayed (again). + +There is no way to customize the items in the toolbar, however the toolbar +can be hidden by __View:Filter Toolbar__. +-- + +Packet List Pane:: ++ +-- +The top pane contains the list of network packets that you can scroll +through and select. By default, the packet number, packet timestamp, +source and destination addresses, protocol, and description are +displayed for each packet; the __Columns__ page in the dialog box popped +up by __Edit:Preferences__ lets you change this (although, unfortunately, +you currently have to save the preferences, and exit and restart +Wireshark, for those changes to take effect). + +If you click on the heading for a column, the display will be sorted by +that column; clicking on the heading again will reverse the sort order +for that column. + +An effort is made to display information as high up the protocol stack +as possible, e.g. IP addresses are displayed for IP packets, but the +MAC layer address is displayed for unknown packet types. + +The right mouse button can be used to pop up a menu of operations. + +The middle mouse button can be used to mark a packet. +-- + +Packet Details Pane:: +The middle pane contains a display of the details of the +currently-selected packet. The display shows each field and its value +in each protocol header in the stack. The right mouse button can be +used to pop up a menu of operations. + +Packet Bytes Pane:: ++ +-- +The lowest pane contains a hex and ASCII dump of the actual packet data. +Selecting a field in the packet details highlights the corresponding +bytes in this section. + +The right mouse button can be used to pop up a menu of operations. +-- + +Statusbar:: ++ +-- +The statusbar is divided into three parts, on the left some context dependent +things are shown, like information about the loaded file, in the center the +number of packets are displayed, and on the right the current configuration +profile. + +The statusbar can be hidden by __View:Statusbar__. +-- + +Preferences:: +Adjust the behavior of *Wireshark*. + +User Interface Preferences:: +Modify the UI to your own personal tastes. + +Selection Bars:: +The selection bar in the packet list and packet details can have either +a "browse" or "select" behavior. If the selection bar has a "browse" +behavior, the arrow keys will move an outline of the selection bar, +allowing you to browse the rest of the list or details without changing +the selection until you press the space bar. If the selection bar has a +"select" behavior, the arrow keys will move the selection bar and change +the selection to the new item in the packet list or packet details. + +Save Window Position:: +If this item is selected, the position of the main Wireshark window will +be saved when Wireshark exits, and used when Wireshark is started again. + +Save Window Size:: +If this item is selected, the size of the main Wireshark window will +be saved when Wireshark exits, and used when Wireshark is started again. + +Save Window Maximized state:: +If this item is selected the maximize state of the main Wireshark window +will be saved when Wireshark exists, and used when Wireshark is started again. + +File Open Dialog Behavior:: +This item allows the user to select how Wireshark handles the listing +of the "File Open" Dialog when opening trace files. "Remember Last +Directory" causes Wireshark to automatically position the dialog in the +directory of the most recently opened file, even between launches of Wireshark. +"Always Open in Directory" allows the user to define a persistent directory +that the dialog will always default to. + +Directory:: +Allows the user to specify a persistent File Open directory. Trailing +slashes or backslashes will automatically be added. + +File Open Preview timeout:: +This items allows the user to define how much time is spend reading the +capture file to present preview data in the File Open dialog. + +Open Recent maximum list entries:: +The File menu supports a recent file list. This items allows the user to +specify how many files are kept track of in this list. + +Ask for unsaved capture files:: +When closing a capture file or Wireshark itself if the file isn't saved yet +the user is presented the option to save the file when this item is set. + +Wrap during find:: +This items determines the behavior when reaching the beginning or the end +of a capture file. When set the search wraps around and continues, otherwise +it stops. + +Settings dialogs show a save button:: +This item determines if the various dialogs sport an explicit Save button +or that save is implicit in OK / Apply. + +Web browser command:: +This entry specifies the command line to launch a web browser. It is used +to access online content, like the Wiki and user guide. Use '%s' to place +the request URL in the command line. + +Layout Preferences:: +The __Layout__ page lets you specify the general layout of the main window. +You can choose from six different layouts and fill the three panes with the +contents you like. + +Scrollbars:: +The vertical scrollbars in the three panes can be set to be either on +the left or the right. + +Alternating row colors:: + +Hex Display:: +The highlight method in the hex dump display for the selected protocol +item can be set to use either inverse video, or bold characters. + +Toolbar style:: + +Filter toolbar placement:: + +Custom window title:: + +Column Preferences:: ++ +-- +The __Columns__ page lets you specify the number, title, and format +of each column in the packet list. + +The __Column title__ entry is used to specify the title of the column +displayed at the top of the packet list. The type of data that the column +displays can be specified using the __Column format__ option menu. +The row of buttons on the left perform the following actions: +-- + +New:: +Adds a new column to the list. + +Delete:: +Deletes the currently selected list item. + +Up / Down:: +Moves the selected list item up or down one position. + +Font Preferences:: +The __Font__ page lets you select the font to be used for most text. + +Color Preferences:: +The __Colors__ page can be used to change the color of the text +displayed in the TCP stream window and for marked packets. To change a color, +simply select an attribute from the "Set:" menu and use the color selector to +get the desired color. The new text colors are displayed as a sample text. + +Capture Preferences:: ++ +-- +The __Capture__ page lets you specify various parameters for capturing +live packet data; these are used the first time a capture is started. + +The __Interface:__ combo box lets you specify the interface from which to +capture packet data, or the name of a FIFO from which to get the packet +data. + +The __Data link type:__ option menu lets you, for some interfaces, select +the data link header you want to see on the packets you capture. For +example, in some OSes and with some versions of libpcap, you can choose, +on an 802.11 interface, whether the packets should appear as Ethernet +packets (with a fake Ethernet header) or as 802.11 packets. + +The __Limit each packet to ... bytes__ check box lets you set the +snapshot length to use when capturing live data; turn on the check box, +and then set the number of bytes to use as the snapshot length. + +The __Filter:__ text entry lets you set a capture filter expression to be +used when capturing. + +If any of the environment variables SSH_CONNECTION, SSH_CLIENT, +REMOTEHOST, DISPLAY, or SESSIONNAME are set, Wireshark will create a +default capture filter that excludes traffic from the hosts and ports +defined in those variables. + +The __Capture packets in promiscuous mode__ check box lets you specify +whether to put the interface in promiscuous mode when capturing. + +The __Update list of packets in real time__ check box lets you specify +that the display should be updated as packets are seen. +-- + +Name Resolution Preferences:: ++ +-- +The __Enable MAC name resolution__, __Enable network name resolution__ and +__Enable transport name resolution__ check boxes let you specify whether +MAC addresses, network addresses, and transport-layer port numbers +should be translated to names. + +The __Enable concurrent DNS name resolution__ allows Wireshark to send out +multiple name resolution requests and not wait for the result before +continuing dissection. This speeds up dissection with network name +resolution but initially may miss resolutions. The number of concurrent +requests can be set here as well. + +__SMI paths__ + +__SMI modules__ +-- + +RTP Player Preferences:: +This page allows you to select the number of channels visible in the +RTP player window. It determines the height of the window, more channels +are possible and visible by means of a scroll bar. + +Protocol Preferences:: +There are also pages for various protocols that Wireshark dissects, +controlling the way Wireshark handles those protocols. + +Edit Capture Filter List:: + +Edit Display Filter List:: + +Capture Filter:: + +Display Filter:: + +Read Filter:: + +Search Filter:: ++ +-- +The __Edit Capture Filter List__ dialog lets you create, modify, and +delete capture filters, and the __Edit Display Filter List__ dialog lets +you create, modify, and delete display filters. + +The __Capture Filter__ dialog lets you do all of the editing operations +listed, and also lets you choose or construct a filter to be used when +capturing packets. + +The __Display Filter__ dialog lets you do all of the editing operations +listed, and also lets you choose or construct a filter to be used to +filter the current capture being viewed. + +The __Read Filter__ dialog lets you do all of the editing operations +listed, and also lets you choose or construct a filter to be used to +as a read filter for a capture file you open. + +The __Search Filter__ dialog lets you do all of the editing operations +listed, and also lets you choose or construct a filter expression to be +used in a find operation. + +In all of those dialogs, the __Filter name__ entry specifies a +descriptive name for a filter, e.g. *Web and DNS traffic*. The +__Filter string__ entry is the text that actually describes the filtering +action to take, as described above.The dialog buttons perform the +following actions: +-- + +New:: +If there is text in the two entry boxes, creates a new associated list item. + +Edit:: +Modifies the currently selected list item to match what's in the entry boxes. + +Delete:: +Deletes the currently selected list item. + +Add Expression...:: ++ +-- +For display filter expressions, pops up a dialog box to allow you to +construct a filter expression to test a particular field; it offers +lists of field names, and, when appropriate, lists from which to select +tests to perform on the field and values with which to compare it. In +that dialog box, the OK button will cause the filter expression you +constructed to be entered into the __Filter string__ entry at the current +cursor position. +-- + +OK:: ++ +-- +In the __Capture Filter__ dialog, closes the dialog box and makes the +filter in the __Filter string__ entry the filter in the __Capture + Preferences__ dialog. In the __Display Filter__ dialog, closes the dialog +box and makes the filter in the __Filter string__ entry the current +display filter, and applies it to the current capture. In the __Read + Filter__ dialog, closes the dialog box and makes the filter in the +__Filter string__ entry the filter in the __Open Capture File__ dialog. +In the __Search Filter__ dialog, closes the dialog box and makes the +filter in the __Filter string__ entry the filter in the __Find Packet__ +dialog. +-- + +Apply:: +Makes the filter in the __Filter string__ entry the current display filter, and applies it to the current capture. + +Save:: +If the list of filters being edited is the list of +capture filters, saves the current filter list to the personal capture +filters file, and if the list of filters being edited is the list of +display filters, saves the current filter list to the personal display +filters file. + +Close:: +Closes the dialog without doing anything with the filter in the __Filter string__ entry. + +The Color Filters Dialog:: +This dialog displays a list of color filters and allows it to be modified. + +THE FILTER LIST:: +Single rows may be selected by clicking. Multiple rows may be selected +by using the ctrl and shift keys in combination with the mouse button. + +NEW:: +Adds a new filter at the bottom of the list and opens the Edit Color +Filter dialog box. You will have to alter the filter expression at +least before the filter will be accepted. The format of color filter +expressions is identical to that of display filters. The new filter is +selected, so it may immediately be moved up and down, deleted or edited. +To avoid confusion all filters are unselected before the new filter is +created. + +EDIT:: +Opens the Edit Color Filter dialog box for the selected filter. (If this +button is disabled you may have more than one filter selected, making it +ambiguous which is to be edited.) + +ENABLE:: +Enables the selected color filter(s). + +DISABLE:: +Disables the selected color filter(s). + +DELETE:: +Deletes the selected color filter(s). + +EXPORT:: +Allows you to choose a file in which to save the current list of color +filters. You may also choose to save only the selected filters. A +button is provided to save the filters in the global color filters file +(you must have sufficient permissions to write this file, of course). + +IMPORT:: +Allows you to choose a file containing color filters which are then +added to the bottom of the current list. All the added filters are +selected, so they may be moved to the correct position in the list as a +group. To avoid confusion, all filters are unselected before the new +filters are imported. A button is provided to load the filters from the +global color filters file. + +CLEAR:: +Deletes your personal color filters file, reloads the global color filters file, if any, and closes the dialog. + +UP:: +Moves the selected filter(s) up the list, making it more likely that they will be used to color packets. + +DOWN:: +Moves the selected filter(s) down the list, making it less likely that they will be used to color packets. + +OK:: +Closes the dialog and uses the color filters as they stand. + +APPLY:: +Colors the packets according to the current list of color filters, but does not close the dialog. + +SAVE:: +Saves the current list of color filters in your personal color filters +file. Unless you do this they will not be used the next time you start +Wireshark. + +CLOSE:: +Closes the dialog without changing the coloration of the packets. Note +that changes you have made to the current list of color filters are not +undone. + +Capture Options Dialog:: ++ +-- +The __Capture Options Dialog__ lets you specify various parameters for +capturing live packet data. + +The __Interface:__ field lets you specify the interface from which to +capture packet data or a command from which to get the packet data via a +pipe. + +The __Link layer header type:__ field lets you specify the interfaces link +layer header type. This field is usually disabled, as most interface have +only one header type. + +The __Capture packets in promiscuous mode__ check box lets you specify +whether the interface should be put into promiscuous mode when +capturing. + +The __Limit each packet to ... bytes__ check box and field lets you +specify a maximum number of bytes per packet to capture and save; if the +check box is not checked, the limit will be 262144 bytes. + +The __Capture Filter:__ entry lets you specify the capture filter using a +tcpdump-style filter string as described above. + +The __File:__ entry lets you specify the file into which captured packets +should be saved, as in the __Printer Options__ dialog above. If not +specified, the captured packets will be saved in a temporary file; you +can save those packets to a file with the __File:Save As__ menu item. + +The __Use multiple files__ check box lets you specify that the capture +should be done in "multiple files" mode. This option is disabled, if the +__Update list of packets in real time__ option is checked. + +The __Next file every ... megabyte(s)__ check box and fields lets +you specify that a switch to a next file should be done +if the specified filesize is reached. You can also select the appropriate +unit, but beware that the filesize has a maximum of 2 GiB. +The check box is forced to be checked, as "multiple files" mode requires a +file size to be specified. + +The __Next file every ... minute(s)__ check box and fields lets +you specify that the switch to a next file should be done after the specified +time has elapsed, even if the specified capture size is not reached. + +The __Ring buffer with ... files__ field lets you specify the number +of files of a ring buffer. This feature will capture into the first file +again, after the specified number of files have been used. + +The __Stop capture after ... files__ field lets you specify the number +of capture files used, until the capture is stopped. + +The __Stop capture after ... packet(s)__ check box and field let +you specify that Wireshark should stop capturing after having captured +some number of packets; if the check box is not checked, Wireshark will +not stop capturing at some fixed number of captured packets. + +The __Stop capture after ... megabyte(s)__ check box and field lets +you specify that Wireshark should stop capturing after the file to which +captured packets are being saved grows as large as or larger than some +specified number of megabytes. If the check box is not checked, Wireshark +will not stop capturing at some capture file size (although the operating +system on which Wireshark is running, or the available disk space, may still +limit the maximum size of a capture file). This option is disabled, if +"multiple files" mode is used, + +The __Stop capture after ... second(s)__ check box and field let you +specify that Wireshark should stop capturing after it has been capturing +for some number of seconds; if the check box is not checked, Wireshark +will not stop capturing after some fixed time has elapsed. + +The __Update list of packets in real time__ check box lets you specify +whether the display should be updated as packets are captured and, if +you specify that, the __Automatic scrolling in live capture__ check box +lets you specify the packet list pane should automatically scroll to +show the most recently captured packets as new packets arrive. + +The __Enable MAC name resolution__, __Enable network name resolution__ and +__Enable transport name resolution__ check boxes let you specify whether +MAC addresses, network addresses, and transport-layer port numbers +should be translated to names. +-- + +About:: +The __About__ dialog lets you view various information about Wireshark. + +menu:About[Wireshark]:: +The __Wireshark__ page lets you view general information about Wireshark, +like the installed version, licensing information and such. + +menu:About[Authors]:: +The __Authors__ page shows the author and all contributors. + +menu:About[Folders]:: +The __Folders__ page lets you view the directory names where Wireshark is +searching its various configuration and other files. + +menu:About[Plugins]:: ++ +-- +The __Plugins__ page lets you view the dissector plugin modules +available on your system. + +The __Plugins List__ shows the name and version of each dissector plugin +module found on your system. + +On Unix-compatible systems, such as Linux, macOS, \*BSD, Solaris, and +AIX, the plugins are looked for in the following directories: the +__lib/wireshark/plugins/$VERSION__ directory under the main installation +directory (for example, __/usr/local/lib/wireshark/plugins/$VERSION__), +and then __$HOME/.wireshark/plugins__. + +On Windows systems, the plugins are looked for in the following +directories: __plugins\$VERSION__ directory under the main installation +directory (for example, __C:\Program Files\Wireshark\plugins\$VERSION__), +and then __%APPDATA%\Wireshark\plugins\$VERSION__ (or, if %APPDATA% isn't +defined, __%USERPROFILE%\Application Data\Wireshark\plugins\$VERSION__). + +$VERSION is the version number of the plugin interface, which +is typically the version number of Wireshark. 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 using the __Edit:Protocols__ dialog box, just as +protocols built into Wireshark are. +-- + +== 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. + +== 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. + +== FILES + +These files contains 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__). + +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. +-- + +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. +-- + +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 is not +displayed in the __Analyze:Enabled Protocols__ dialog box, and so cannot +be enabled by the user. + +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. + +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. +-- + +Name Resolution (hosts):: ++ +-- +If the personal __hosts__ file exists, it is +used to resolve IPv4 and IPv6 addresses before any other +attempts are made to resolve them. The file has the standard __hosts__ +file syntax; each line contains one IP address and name, separated by +whitespace. The same directory as for the personal preferences file is used. + +Capture filter name resolution is handled by libpcap on UNIX-compatible +systems, such as Linux, macOS, \*BSD, Solaris, and AIX, and 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 the same as the __ethers__ files, except that entries such as: + + 00:00:0C Cisco + +can be provided, with the 3-byte OUI and the name for a vendor, and +entries such as: + + 00-00-0C-07-AC/40 All-HSRP-routers + +can be specified, with a MAC address and a mask indicating how many bits +of the address must match. The above entry, for example, has 40 +significant bits, or 5 bytes, and would match addresses from +00-00-0C-07-AC-00 through 00-00-0C-07-AC-FF. The mask need not be a +multiple of 8. + +The __manuf__ file is looked for in the same directory as the global +preferences file. +-- + +Name Resolution (services):: ++ +-- +The __services__ file is used to translate port numbers into names. +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 +-- + +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. +-- + +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. +-- + +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:: +See above in the description of the About:Plugins page. + +== 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 +https://www.wireshark.org. + +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. |