diff options
Diffstat (limited to 'doc')
82 files changed, 13486 insertions, 10037 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index 768867f6a0..e9da6f07c8 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -4,7 +4,3 @@ *.html *.tmp wireshark.pod - -# Misc # -######## -AUTHORS-SHORT-FORMAT diff --git a/doc/CMakeLists-PROTOABBREV.txt b/doc/CMakeLists-PROTOABBREV.txt new file mode 100644 index 0000000000..f8a62b9eda --- /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 index 798c49ee20..a5996d2fdf 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -7,209 +7,178 @@ # SPDX-License-Identifier: GPL-2.0-or-later # -add_custom_command( - OUTPUT AUTHORS-SHORT - COMMAND ${PERL_EXECUTABLE} - ${CMAKE_CURRENT_SOURCE_DIR}/perlnoutf.pl - ${CMAKE_CURRENT_SOURCE_DIR}/make-authors-short.pl - < ${CMAKE_SOURCE_DIR}/AUTHORS - > ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT - DEPENDS - ${CMAKE_CURRENT_SOURCE_DIR}/perlnoutf.pl - ${CMAKE_CURRENT_SOURCE_DIR}/make-authors-short.pl - ${CMAKE_SOURCE_DIR}/AUTHORS -) - -add_custom_command( - OUTPUT AUTHORS-SHORT-FORMAT - COMMAND ${PERL_EXECUTABLE} - ${CMAKE_CURRENT_SOURCE_DIR}/perlnoutf.pl - ${CMAKE_CURRENT_SOURCE_DIR}/make-authors-format.pl - < ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT - > ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT-FORMAT - DEPENDS - ${CMAKE_CURRENT_SOURCE_DIR}/perlnoutf.pl - ${CMAKE_CURRENT_SOURCE_DIR}/make-authors-format.pl - ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT -) - -if(WIN32) - file(TO_NATIVE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/wireshark.pod.template WPT_WIN_PATH) - file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT-FORMAT ASF_WIN_PATH) - file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/wireshark.pod WP_WIN_PATH) - add_custom_command( - OUTPUT wireshark.pod - COMMAND copy /B ${WPT_WIN_PATH} + ${ASF_WIN_PATH} ${WP_WIN_PATH} - DEPENDS - ${CMAKE_CURRENT_SOURCE_DIR}/wireshark.pod.template - ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT-FORMAT - ) -else() - add_custom_command( - OUTPUT wireshark.pod - COMMAND cat - ${CMAKE_CURRENT_SOURCE_DIR}/wireshark.pod.template - ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT-FORMAT - > ${CMAKE_CURRENT_BINARY_DIR}/wireshark.pod - DEPENDS - ${CMAKE_CURRENT_SOURCE_DIR}/wireshark.pod.template - ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT-FORMAT - ) +find_package( Asciidoctor 1.5 ) + +function(set_doc_target_properties _target) + set_target_properties(${_target} PROPERTIES + FOLDER "Documentation" + EXCLUDE_FROM_DEFAULT_BUILD True + ) +endfunction() + +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() -pod2manhtml(${CMAKE_CURRENT_BINARY_DIR}/wireshark 1) - -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/androiddump 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/capinfos 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/captype 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/ciscodump 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/dftest 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/dumpcap 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/editcap 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/mergecap 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/randpkt 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/randpktdump 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/rawshark 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/reordercap 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/sshdump 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/text2pcap 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/tshark 1) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/udpdump 1) - -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/extcap 4) -pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/wireshark-filter 4) +if(BUILD_sdjournal AND SYSTEMD_FOUND) + ADD_MAN_PAGE(sdjournal 1) +endif() if(MAXMINDDB_FOUND) - pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/mmdbresolve 1) + ADD_MAN_PAGE(mmdbresolve 1) endif() if (BUILD_corbaidl2wrs) - pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/idl2wrs 1) + ADD_MAN_PAGE(idl2wrs 1) endif() + if (BUILD_xxx2deb) - pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/asn2deb 1) - pod2manhtml(${CMAKE_CURRENT_SOURCE_DIR}/idl2deb 1) + ADD_MAN_PAGE(asn2deb 1) + ADD_MAN_PAGE(idl2deb 1) endif() -set(MAN1_INSTALL_FILES - ${CMAKE_CURRENT_BINARY_DIR}/androiddump.1 - ${CMAKE_CURRENT_BINARY_DIR}/capinfos.1 - ${CMAKE_CURRENT_BINARY_DIR}/captype.1 - ${CMAKE_CURRENT_BINARY_DIR}/ciscodump.1 - ${CMAKE_CURRENT_BINARY_DIR}/ciscodump.1 - ${CMAKE_CURRENT_BINARY_DIR}/dftest.1 - ${CMAKE_CURRENT_BINARY_DIR}/dumpcap.1 - ${CMAKE_CURRENT_BINARY_DIR}/editcap.1 - ${CMAKE_CURRENT_BINARY_DIR}/mergecap.1 - ${CMAKE_CURRENT_BINARY_DIR}/randpkt.1 - ${CMAKE_CURRENT_BINARY_DIR}/randpktdump.1 - ${CMAKE_CURRENT_BINARY_DIR}/rawshark.1 - ${CMAKE_CURRENT_BINARY_DIR}/reordercap.1 - ${CMAKE_CURRENT_BINARY_DIR}/sshdump.1 - ${CMAKE_CURRENT_BINARY_DIR}/text2pcap.1 - ${CMAKE_CURRENT_BINARY_DIR}/tshark.1 - ${CMAKE_CURRENT_BINARY_DIR}/udpdump.1 - ${CMAKE_CURRENT_BINARY_DIR}/wireshark.1 -) +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) -if(MAXMINDDB_FOUND) - list(APPEND MAN1_INSTALL_FILES ${CMAKE_CURRENT_BINARY_DIR}/mmdbresolve.1) -endif() +set(MAN_INCLUDES diagnostic-options.adoc dissection-options.adoc) -if (BUILD_corbaidl2wrs) - list(APPEND MAN1_INSTALL_FILES ${CMAKE_CURRENT_BINARY_DIR}/idl2wrs.1) -endif() -if (BUILD_xxx2deb) - list(APPEND MAN1_INSTALL_FILES - ${CMAKE_CURRENT_BINARY_DIR}/asn2deb.1 - ${CMAKE_CURRENT_BINARY_DIR}/idl2deb.1 +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() -set(MAN4_INSTALL_FILES - ${CMAKE_CURRENT_BINARY_DIR}/extcap.4 - ${CMAKE_CURRENT_BINARY_DIR}/wireshark-filter.4 -) +if(ASCIIDOCTOR_FOUND) + ASCIIDOCTOR2HTML(release-notes.adoc) + ASCIIDOCTOR2TXT(release-notes.adoc) -set(BUNDLE_RESOURCE_SHARE_MAN1_FILES ${MAN1_INSTALL_FILES} PARENT_SCOPE) -set(BUNDLE_RESOURCE_SHARE_MAN4_FILES ${MAN4_INSTALL_FILES} PARENT_SCOPE) + list(APPEND HTML_INSTALL_FILES "${CMAKE_CURRENT_BINARY_DIR}/release-notes.html") -add_custom_target(manpages DEPENDS - ${MAN1_INSTALL_FILES} - ${MAN4_INSTALL_FILES} -) + 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") -set(HTML_INSTALL_FILES - ${CMAKE_CURRENT_BINARY_DIR}/androiddump.html - ${CMAKE_CURRENT_BINARY_DIR}/capinfos.html - ${CMAKE_CURRENT_BINARY_DIR}/captype.html - ${CMAKE_CURRENT_BINARY_DIR}/ciscodump.html - ${CMAKE_CURRENT_BINARY_DIR}/ciscodump.html - ${CMAKE_CURRENT_BINARY_DIR}/dftest.html - ${CMAKE_CURRENT_BINARY_DIR}/dumpcap.html - ${CMAKE_CURRENT_BINARY_DIR}/editcap.html - ${CMAKE_CURRENT_BINARY_DIR}/extcap.html - ${CMAKE_CURRENT_BINARY_DIR}/mergecap.html - ${CMAKE_CURRENT_BINARY_DIR}/randpkt.html - ${CMAKE_CURRENT_BINARY_DIR}/randpktdump.html - ${CMAKE_CURRENT_BINARY_DIR}/rawshark.html - ${CMAKE_CURRENT_BINARY_DIR}/reordercap.html - ${CMAKE_CURRENT_BINARY_DIR}/sshdump.html - ${CMAKE_CURRENT_BINARY_DIR}/text2pcap.html - ${CMAKE_CURRENT_BINARY_DIR}/tshark.html - ${CMAKE_CURRENT_BINARY_DIR}/udpdump.html - ${CMAKE_CURRENT_BINARY_DIR}/wireshark-filter.html - ${CMAKE_CURRENT_BINARY_DIR}/wireshark.html -) + 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") -if(MAXMINDDB_FOUND) - list(APPEND HTML_INSTALL_FILES ${CMAKE_CURRENT_BINARY_DIR}/mmdbresolve.html) -endif() + ASCIIDOCTOR2HTML(faq.adoc) + add_custom_target(faq_html DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/faq.html) + set_doc_target_properties(faq_html) -if (BUILD_corbaidl2wrs) - list(APPEND HTML_INSTALL_FILES ${CMAKE_CURRENT_BINARY_DIR}/idl2wrs.html) -endif() -if (BUILD_xxx2deb) - list(APPEND HTML_INSTALL_FILES - ${CMAKE_CURRENT_BINARY_DIR}/asn2deb.html - ${CMAKE_CURRENT_BINARY_DIR}/idl2deb.html - ) + add_custom_target(faq) + set_doc_target_properties(faq) + add_dependencies (faq faq_html) endif() + add_custom_target( docs ALL DEPENDS - ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT - ${CMAKE_CURRENT_BINARY_DIR}/AUTHORS-SHORT-FORMAT - ${MAN1_INSTALL_FILES} - ${MAN4_INSTALL_FILES} ${HTML_INSTALL_FILES} ) -set_target_properties(docs PROPERTIES FOLDER "Docs") +set_target_properties(docs PROPERTIES FOLDER "Documentation") -install( - FILES - ${MAN1_INSTALL_FILES} - DESTINATION - ${CMAKE_INSTALL_MANDIR}/man1 -) +if(ASCIIDOCTOR_FOUND) + add_dependencies(docs manpages) -install( - FILES - ${MAN4_INSTALL_FILES} - DESTINATION - ${CMAKE_INSTALL_MANDIR}/man4 -) + 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_DATADIR}/${CPACK_PACKAGE_NAME} + ${CMAKE_INSTALL_DOCDIR} ) # -# Editor modelines - http://www.wireshark.org/tools/modelines.html +# Editor modelines - https://www.wireshark.org/tools/modelines.html # # Local variables: # c-basic-offset: 8 diff --git a/doc/README.capture b/doc/README.capture index a453eecf71..9191316c56 100644 --- a/doc/README.capture +++ b/doc/README.capture @@ -15,8 +15,6 @@ capture-pcap-util-int.h capture-pcap-util-unix.c capture-wpcap.c capture-wpcap.h -capture_wpcap_packet.c -capture_wpcap_packet.h Capture related source files: ----------------------------- @@ -25,13 +23,9 @@ capture.h capture_loop.c capture_loop.h capture_opts.c -capture-stop-conditions.c -capture-stop-conditions.h capture_sync.c capture_ui_utils.c capture_ui_utils.h -conditions.c (XXX: is conditions generic or capture specific?) -conditions.h Capture driver @@ -39,7 +33,7 @@ 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 ws_module_open("wpcap.dll") is called +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. @@ -110,13 +104,13 @@ 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. +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) +-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() @@ -126,7 +120,7 @@ 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. +matched, the ld.go flag is set to false, and the loop will stop shortly after. Capture parent diff --git a/doc/README.developer b/doc/README.developer index 42f2d0e31a..b6ac8ea0de 100644 --- a/doc/README.developer +++ b/doc/README.developer @@ -6,8 +6,8 @@ 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 send -remarks and patches to the developer mailing list. +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. @@ -24,29 +24,31 @@ README.md files of the sources root dir. You'll find additional information in the following README files: -- README.capture - the capture engine internals -- README.design - Wireshark software design - incomplete -- README.developer - this file -- README.dissector - How to dissect a packet -- README.display_filter - Display Filter Engine -- README.idl2wrs - CORBA IDL converter -- README.packaging - how to distribute a software package containing WS -- README.regression - regression testing of WS and TS -- README.stats_tree - a tree statistics counting specific packets -- README.tapping - "tap" a dissector to get protocol specific events -- README.xml-output - how to work with the PDML exported output -- wiretap/README.developer - how to add additional capture file types to - Wiretap +- 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: -- README.heuristic - what are heuristic dissectors and how to write them -- README.plugins - how to "pluginize" a dissector -- README.request_response_tracking - how to track req./resp. times and such -- README.wmem - how to obtain "memory leak free" memory +- 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 @@ -65,39 +67,38 @@ 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. -In general, not all C99 features can be used since some C compilers used to -compile Wireshark, such as Microsoft's C compiler, don't support all C99 -features. The C99 features that can be used are: - - - flexible array members - - compound literals - - designated initializers - - "//" comments - - mixed declarations and code - - new block scopes for selection and iteration statements (that is, declaring - the type in a for-loop like: for (int i = 0; i < n; i++) ;) - - macros with a variable number of arguments (variadic macros) - - trailing comma in enum declarations - - inline functions (guaranteed only by use of glib.h) +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. Not -all compilers support this. E.g., if "i" is a static or global +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 - guint32 i = somearray[2]; + uint32_t i = somearray[2]; outside a function, or as - static guint32 i = somearray[2]; + static uint32_t i = somearray[2]; inside or outside a function, declare it as just - guint32 i; + uint32_t i; or - static guint32 i; + static uint32_t i; and later, in code, initialize it with @@ -107,44 +108,45 @@ instead. Initializations of variables with automatic storage duration - i.e., local variables - with non-constant values is permitted, so, within a function - guint32 i = somearray[2]; + uint32_t i = somearray[2]; is allowed. Don't use zero-length arrays as structure members, use flexible array members instead. -Don't use anonymous unions; not all compilers support them. -Example: - - typedef struct foo { - guint32 foo; - union { - guint32 foo_l; - guint16 foo_s; - } u; /* have a name here */ - } foo_t; - Don't use "uchar", "u_char", "ushort", "u_short", "uint", "u_int", "ulong", "u_long" or "boolean"; they aren't defined on all platforms. -If you want an 8-bit unsigned quantity, use "guint8"; if you want an + +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 "guchar"; if you want a 16-bit unsigned quantity, use "guint16"; -if you want a 32-bit unsigned quantity, use "guint32"; and if you want -an "int-sized" unsigned quantity, use "guint"; if you want a boolean, -use "gboolean". Use "%d", "%u", "%x", and "%o" to print those types; -don't use "%ld", "%lu", "%lx", or "%lo", as longs are 64 bits long on -many platforms, but "guint32" is 32 bits long. +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 "gint32" for signed 32-bit integers and use -"guint32" for unsigned 32-bit integers. +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 "gint64" or "guint64", +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. @@ -160,7 +162,7 @@ functions won't accept a size_t on LLP64: size_t i; char greeting[] = "hello, sailor"; - guint byte_after_greet; + unsigned byte_after_greet; i = strlen(greeting); byte_after_greet = tvb_get_guint8(tvb, i); /* Compiler warning */ @@ -170,38 +172,57 @@ will have to cast to a compatible data type, e.g. size_t i; char greeting[] = "hello, sailor"; - guint byte_after_greet; + uint8_t byte_after_greet; i = strlen(greeting); - byte_after_greet = tvb_get_guint8(tvb, (gint) i); /* OK */ + byte_after_greet = tvb_get_guint8(tvb, (int) i); /* OK */ or - gint i; + int i; char greeting[] = "hello, sailor"; - guint byte_after_greet; + uint8_t byte_after_greet; - i = (gint) strlen(greeting); + 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 +See https://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, for -GLib routines, and routines that use them, such as all the routines in -Wireshark that take format arguments, use G_GINT64_MODIFIER, for example: +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, "%" G_GINT64_MODIFIER "u", val); + 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 "G_GINT64_CONSTANT()" +that. Instead, put the constant in a call to the "INT64_C()" or "UINT64_C()" macro, e.g. - G_GINT64_CONSTANT(-11644473600), G_GUINT64_CONSTANT(11644473600) + INT64_C(-11644473600), UINT64_C(11644473600) rather than @@ -221,7 +242,8 @@ argument. You must do call_routine2(xxx, format, ap); va_end(ap); -rather +rather than + va_start(ap, format); call_routine1(xxx, format, ap); call_routine2(xxx, format, ap); @@ -248,6 +270,7 @@ will not work with all compilers - you have to do } 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 @@ -277,10 +300,10 @@ Don't use "index()" or "rindex()"; instead, use the ANSI C equivalents, "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 +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 +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 @@ -319,7 +342,7 @@ 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 -UTF8 to UTF16 on Windows allowing the functions to work correctly when the +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 @@ -381,15 +404,15 @@ 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 "numbered argument" feature that many UNIX printf's +Don't use the "positional parameters" extension that many UNIX printf's implement, e.g.: - g_snprintf(add_string, 30, " - (%1$d) (0x%1$04x)", value); + 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 - g_snprintf(add_string, 30, " - (%d) (0x%04x)", value, value); + snprintf(add_string, 30, " - (%d) (0x%04x)", value, value); instead. @@ -399,17 +422,21 @@ Don't use as that's not supported by all compilers. -snprintf() -> g_snprintf() -snprintf() is not available on all platforms, so it's a good idea to use the -g_snprintf() function declared by <glib.h> instead. +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 mininum versions of each of the libraries it uses, in -particular GLib 2.32.0 and Qt 5.2.0 or newer. If you require a mechanism +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 @@ -422,9 +449,19 @@ 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. -Wireshark uses Libgcrypt as general-purpose crypto library. To use it from -your dissector, do not include gcrypt.h directly, but use the wrapper file -wsutil/wsgcrypt.h instead. +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 @@ -432,7 +469,7 @@ 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 g_snprintf() since that function will if used correctly prevent +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- @@ -448,7 +485,7 @@ 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(wmem_packet_scope(), ""); + strbuf = wmem_strbuf_new(pinfo->pool, ""); wmem_strbuf_append_printf(strbuf, ... or @@ -456,10 +493,10 @@ or char *buffer=NULL; ... #define MAX_BUFFER 1024 - buffer=wmem_alloc(wmem_packet_scope(), MAX_BUFFER); + buffer=wmem_alloc(pinfo->pool, MAX_BUFFER); buffer[0]='\0'; ... - g_snprintf(buffer, MAX_BUFFER, ... + 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. @@ -487,7 +524,7 @@ instead write the code as static void foo_to_str(char **buffer, ... #define MAX_BUFFER x - *buffer=wmem_alloc(wmem_packet_scope(), MAX_BUFFER); + *buffer=wmem_alloc(pinfo->pool, MAX_BUFFER); <fill in *buffer> } ... @@ -501,16 +538,18 @@ 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. -Don't use non-ASCII characters in source files; not all compiler -environments will be using the same encoding for non-ASCII characters, -and at least one compiler (Microsoft's Visual C) will, in environments -with double-byte character encodings, such as many Asian environments, -fail if it sees a byte sequence in a source file that doesn't correspond -to a valid character. This causes source files using either an ISO -8859/n single-byte character encoding or UTF-8 to fail to compile. Even -if the compiler doesn't fail, there is no guarantee that the compiler, -or a developer's text editor, will interpret the characters the way you -intend them to be interpreted. +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. @@ -527,7 +566,7 @@ 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 "g_assert()" or "g_assert_not_reached()" in dissectors. +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 @@ -535,6 +574,35 @@ 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 @@ -556,22 +624,6 @@ 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 string from the buffer, -and the string has a specified size, you can use "tvb_get_*_string()", -which will check whether the entire string is present before allocating -a buffer for the string, and will also put a trailing '\0' at the end of -the buffer. - -If you're fetching into such a chunk of memory a 2-byte Unicode string -from the buffer, and the string has a specified size, you can use -"tvb_get_faked_unicode()", which will check whether the entire string -is present before allocating a buffer for the string, and will also -put a trailing '\0' at the end of the buffer. The resulting string will be -a sequence of single-byte characters; the only Unicode characters that -will be handled correctly are those in the ASCII range. (Wireshark's -ability to handle non-ASCII strings is limited; it needs to be -improved.) - 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 @@ -583,16 +635,47 @@ 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 there's no maximum length of string data to be fetched, -routines such as "tvb_get_*_string()" are safer, as they allocate a buffer -large enough to hold the string. (Note that some variants of this call -require you to free the string once you're finished with it.) +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), @@ -620,9 +703,10 @@ If you have a 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 gint8, guint8, gint16, or guint16 +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 int"/"guint" as the loop index rather than a shorter type. +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 @@ -641,12 +725,12 @@ 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() -> g_snprintf() +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 g_snprintf() function declared by <glib.h> instead. +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 @@ -663,7 +747,7 @@ Testing using editcap can be done using preexisting capture files and the editcap -E 0.03 infile.pcap outfile.pcap tshark -nVr outfile.pcap -The script fuzz-test.sh is available to help automate these tests. +tools/fuzz-test.sh is available to help automate these tests. 4. Name convention. @@ -680,43 +764,36 @@ 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 +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 + https://www.jwz.org/doc/tabs-vs-spaces.html -Most of the files in Wireshark tend to use 2-space or 4-space indentation. When -creating a new file you are free to choose an indentation logic but you are -encouraged to use 4-space indentation for C/C++ source to keep inconsistency -between files to a minimum. +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. -Each file should have a short comment (modelines) on the indentation logic at -the end of the file. See +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 guidance. - -A complementary and arguably better alternative to modelines is -EditorConfig (http://editorconfig.org). The default EditorConfig indentation -style is defined in the .editorconfig file placed on the root of the project -source code tree (4-space indentation for C). One advantage of following the -default style is that no additional EditorConfig settings are required for new -files. If your file does not follow this style please add a file-specific -setting overriding the default style to a separate .editorconfig configuration -file placed in the source file directory. - -Some IDEs and text editors have built-in EditorConfig support and many more -have plugins available (links at http://editorconfig.org). +for more information. Please do not leave trailing whitespace (spaces/tabs) on lines. -When editing an existing file, try following the existing indentation -logic and even if it very tempting, never ever use a restyler/reindenter -utility on an existing file. If you run across wildly varying -indentation styles within the same file, it might be helpful to send a -note to wireshark-dev for guidance. +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 @@ -727,10 +804,177 @@ 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. Miscellaneous notes +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. -Each commit in your branch corresponds to a different VCSVERSION string -automatically defined in the header 'version.h' during the build. If you happen +** 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 VCS_VERSION 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 diff --git a/doc/README.display_filter b/doc/README.display_filter index 4a1ca1cbf7..ab4d74d1a7 100644 --- a/doc/README.display_filter +++ b/doc/README.display_filter @@ -41,14 +41,18 @@ 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, /* TRUE and FALSE come from <glib.h> */ - FT_UINT8, - FT_UINT16, - FT_UINT24, /* really a UINT32, but displayed as3 hex-digits if FD_HEX*/ - FT_UINT32, - FT_UINT64, + 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. } @@ -60,28 +64,24 @@ 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 */ - guint32 uinteger; - gint32 sinteger; - guint64 integer64; - gdouble floating; - gchar *string; - guchar *ustring; - GByteArray *bytes; - ipv4_addr ipv4; - ipv6_addr ipv6; - e_guid_t guid; - nstime_t time; - tvbuff_t *tvb; - GRegex *re; - } value; - - /* The following is provided for private use - * by the fvalue. */ - gboolean fvalue_gboolean1; - + 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; @@ -90,8 +90,8 @@ 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, also defined in -ftypes.h. This is the way a field type is registered with the ftype engine. +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 @@ -153,7 +153,7 @@ 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 to grammar parser +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. @@ -207,7 +207,7 @@ 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/sttree-*. It too +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. @@ -215,26 +215,8 @@ 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 -high-level. For example, there is only a single INTEGER sttype, unlike -the ftype system that has a type for UINT64, UINT32, UINT16, UINT8, etc. - -typedef enum { - STTYPE_UNINITIALIZED, - STTYPE_TEST, - STTYPE_UNPARSED, - STTYPE_STRING, - STTYPE_FIELD, - STTYPE_FVALUE, - STTYPE_INTEGER, - STTYPE_RANGE, - STTYPE_FUNCTION, - STTYPE_SET, - STTYPE_NUM_TYPES -} sttype_id_t; - - -The root node of the syntax tree is the main test or comparison -being done. +higher-level abstractions. The root node of the syntax tree is the main +test or comparison being done. Semantic Check -------------- @@ -293,11 +275,11 @@ 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 dvfm instructions. +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 dvfm_init_const() call, and stored +into registers via the dfvm_init_const() call, and stored in the dfilter_t structure for when the display filter is actually applied. @@ -315,7 +297,7 @@ 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. +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 @@ -331,7 +313,7 @@ $ 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" +Filter: ip.addr == 127.0.0.1 Constants: 00000 PUT_FVALUE 127.0.0.1 <FT_IPv4> -> reg#1 @@ -357,7 +339,7 @@ This is what happens in this example: 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 +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 @@ -367,21 +349,22 @@ 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 0 +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 1 (which are all of the ip.addr +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 +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. +This returns the accumulator's value, either true or false. -In addition to dftest, there is also a tools/dfilter-test script -which is a unit-test script for the display filter engine. -It makes use of text2pcap and tshark to run specific display -filters against specific captures (embedded within dfilter-test). +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. @@ -395,8 +378,8 @@ typedef struct { char *name; DFFuncType function; ftenum_t retval_ftype; - guint min_nargs; - guint max_nargs; + unsigned min_nargs; + unsigned max_nargs; DFSemCheckType semcheck_param_function; } df_func_def_t; @@ -415,10 +398,10 @@ semcheck_param_function - called during the semantic check of the DFFuncType function ------------------- -typedef gboolean (*DFFuncType)(GList *arg1list, GList *arg2list, GList **retval); +typedef bool (*DFFuncType)(GList *arg1list, GList *arg2list, GList **retval); -The return value of your function is a gboolean; TRUE if processing went fine, -or FALSE if there was some sort of exception. +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 @@ -428,7 +411,7 @@ 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 + 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. @@ -439,21 +422,23 @@ is passed to your function so you can set the pointer to your return value. DFSemCheckType -------------- -typedef void (*DFSemCheckType)(int param_num, stnode_t *st_node); +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 THROW a TypeError exception. +it should call dfilter_fail(dfw,...) and THROW a TypeError exception. Example: add an 'in' display filter operation ============================================= -This example has been discussed on wireshark-dev in April 2004. It illustrates -how a more complex operation can be added to the display filter language. +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: @@ -553,23 +538,19 @@ 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 dfilter-test.py -======================================== -Note: dfilter-test.py requires Python 2.7 or newer (including Python 3) +How to add a new test to the test suite +======================================= -"tools/dfilter-test.py" is the main test script. It includes -the test from files in tools/dftestlib. You can add a test -to a file in tools/dftestlib, or you can create a new file -in tools/dftestlib. If you do add a new file, you must -import it (and the class it defines) in "tools/dfilter-test.py" +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 "tools/dftestfiles". All the tests +a capture file in "test/captures". All the tests run in that class will use that one capture file. -There are 2 methods you can use for testing: +There are 2 fixtures you can use for testing: -assertDfilter(dfilter_text, expected_count) +checkDFilterCount(dfilter, expected_count) This will run the display filter through tshark, on the file named by "trace_file", and assert that the @@ -578,35 +559,28 @@ assertDfilter(dfilter_text, expected_count) matches is not the same as failure to compile the display filter string. -assertDFilterFail(dfilter_text) - - This will run tshark with the display filter, and - asser that tshark fails. This is useful when expecting - display filter syntax errors to be caught. +checkDFilterFail(dfilter, error) -Then, simply run "dfilter-test.py". You can run the tests -in a single Test class by naming that -class on the -dfilter-test.py command-line, or even run a single -test by naming it. E.g., the following are all valid ways -of running dfilter-test.py: + 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. -# Run all tests -$ ./tools/dfilter-test.py +To execute tests: -# Run all tests in "testTVB" -$ ./tools/dfilter-test.py testTVB +# Run all dfilter tests +$ test/test.py suite_dfilter -# Run the the "test_contains_1" test from testTVB -$ ./tools/dfilter-test.py testTVB.test_contains_1 +# 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 tools/dfilter-test.py +$ pytest -nauto test -k suite_dfilter -# Run all tests in "testTVB", in parallel: -$ pytest -nauto tools/dfilter-test.py -k testTVB +# Run all tests from group_tvb.py, in parallel: +$ pytest -nauto test -k case_tvb -By default dfilter-test.py assumes that the "tshark" binary is located in the -current working directory. If that is not the case, set the environment variable -WS_BIN_PATH to correct directory. +# 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 index 1096588297..6241545ae2 100644 --- a/doc/README.dissector +++ b/doc/README.dissector @@ -3,9 +3,8 @@ 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 send -remarks and patches to the developer mailing list. - +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. @@ -24,10 +23,10 @@ README.md files of the sources root dir. You'll find additional dissector related information in the following README files: -- README.heuristic - what are heuristic dissectors and how to write them -- README.plugins - how to "pluginize" a dissector -- README.request_response_tracking - how to track req./resp. times and such -- README.wmem - how to obtain "memory leak free" memory +- 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 @@ -51,7 +50,7 @@ add to the protocol tree, and work with registered header fields. 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-" +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. @@ -84,7 +83,7 @@ need to include additional headers. 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? +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 @@ -94,28 +93,47 @@ PROTOSHORTNAME An abbreviated name for the protocol; this is displayed any preferences, in the dialog box of enabled protocols, and in the dialog box for filter fields when constructing a filter expression. -PROTOABBREV A name for the protocol for use in filter expressions; - it may contain only lower-case letters, digits, and hyphens, - underscores, and periods. +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. -FIELDABBREV The abbreviated name for the header field; it may contain - only letters, digits, hyphens, underscores, and periods. +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_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME, - FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_EUI64, + 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_GUID, FT_OID, - FT_REL_OID, FT_AX25, FT_VINES, FT_SYSTEM_ID, FT_FC, FT_FCWWN + 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 or - BASE_NO_DISPLAY_VALUE + 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 @@ -125,9 +143,9 @@ FIELDDISPLAY --For FT_UINT{8,16,24,32,40,48,56,64} and 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 - header fields above a subtree. The value will still be - filterable, just not displayed. + 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: @@ -144,6 +162,12 @@ FIELDDISPLAY --For FT_UINT{8,16,24,32,40,48,56,64} and 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 @@ -159,14 +183,27 @@ FIELDDISPLAY --For FT_UINT{8,16,24,32,40,48,56,64} and --For FT_STRING, FT_STRINGZ and FT_UINT_STRING: - STR_ASCII or STR_UNICODE + (must be) BASE_NONE - --For FT_BYTES: + --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 - BASE_ALLOW_ZERO displays <none> instead of <MISSING> for zero sized byte array + 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: @@ -184,9 +221,19 @@ BITMASK Used to mask a field not 8-bit aligned or with a size other 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 PROTOABBREV would be "ibdp". Try to +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. @@ -210,7 +257,7 @@ 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 +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. @@ -218,106 +265,182 @@ The accessors are: Bit accessors for a maximum of 8-bits, 16-bits 32-bits and 64-bits: -guint8 tvb_get_bits8(tvbuff_t *tvb, gint bit_offset, const gint no_of_bits); -guint16 tvb_get_bits16(tvbuff_t *tvb, guint bit_offset, const gint no_of_bits, const guint encoding); -guint32 tvb_get_bits32(tvbuff_t *tvb, guint bit_offset, const gint no_of_bits, const guint encoding); -guint64 tvb_get_bits64(tvbuff_t *tvb, guint bit_offset, const gint no_of_bits, const guint encoding); +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); -Single-byte accessor: +40-bit unsigned and signed integers: -guint8 tvb_get_guint8(tvbuff_t *tvb, const gint offset); +uint64_t tvb_get_letoh40(tvbuff_t *tvb, const int offset); +int64_t tvb_get_letohi40(tvbuff_t *tvb, const int offset); -Network-to-host-order accessors for 16-bit integers (guint16), 24-bit -integers, 32-bit integers (guint32), 40-bit integers, 48-bit integers, -56-bit integers and 64-bit integers (guint64): +48-bit unsigned and signed integers: -guint16 tvb_get_ntohs(tvbuff_t *tvb, const gint offset); -guint32 tvb_get_ntoh24(tvbuff_t *tvb, const gint offset); -guint32 tvb_get_ntohl(tvbuff_t *tvb, const gint offset); -guint64 tvb_get_ntoh40(tvbuff_t *tvb, const gint offset); -guint64 tvb_get_ntoh48(tvbuff_t *tvb, const gint offset); -guint64 tvb_get_ntoh56(tvbuff_t *tvb, const gint offset); -guint64 tvb_get_ntoh64(tvbuff_t *tvb, const gint offset); +uint64_t tvb_get_letoh48(tvbuff_t *tvb, const int offset); +int64_t tvb_get_letohi48(tvbuff_t *tvb, const int offset); -Network-to-host-order accessors for single-precision and -double-precision IEEE floating-point numbers: +56-bit unsigned and signed integers: -gfloat tvb_get_ntohieee_float(tvbuff_t *tvb, const gint offset); -gdouble tvb_get_ntohieee_double(tvbuff_t *tvb, const gint offset); +uint64_t tvb_get_letoh56(tvbuff_t *tvb, const int offset); +int64_t tvb_get_letohi56(tvbuff_t *tvb, const int offset); -Little-Endian-to-host-order accessors for 16-bit integers (guint16), -24-bit integers, 32-bit integers (guint32), 40-bit integers, 48-bit -integers, 56-bit integers, and 64-bit integers (guint64): +64-bit unsigned (uint64_t) and signed (int64_t) integers: -guint16 tvb_get_letohs(tvbuff_t *tvb, const gint offset); -guint32 tvb_get_letoh24(tvbuff_t *tvb, const gint offset); -guint32 tvb_get_letohl(tvbuff_t *tvb, const gint offset); -guint64 tvb_get_letoh40(tvbuff_t *tvb, const gint offset); -guint64 tvb_get_letoh48(tvbuff_t *tvb, const gint offset); -guint64 tvb_get_letoh56(tvbuff_t *tvb, const gint offset); -guint64 tvb_get_letoh64(tvbuff_t *tvb, const gint offset); +uint64_t tvb_get_letoh64(tvbuff_t *tvb, const int offset); +int64_t tvb_get_letohi64(tvbuff_t *tvb, const int offset); -Little-Endian-to-host-order accessors for single-precision and -double-precision IEEE floating-point numbers: +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. -gfloat tvb_get_letohieee_float(tvbuff_t *tvb, const gint offset); -gdouble tvb_get_letohieee_double(tvbuff_t *tvb, const gint offset); +Single-precision and double-precision IEEE floating-point numbers: -Encoding-to_host-order accessors for 16-bit integers (guint16), -24-bit integers, 32-bit integers (guint32), 40-bit integers, 48-bit -integers, 56-bit integers, and 64-bit integers (guint64): +float tvb_get_letohieee_float(tvbuff_t *tvb, const int offset); +double tvb_get_letohieee_double(tvbuff_t *tvb, const int offset); -guint16 tvb_get_guint16(tvbuff_t *tvb, const gint offset, const guint encoding); -guint32 tvb_get_guint24(tvbuff_t *tvb, const gint offset, const guint encoding); -guint32 tvb_get_guint32(tvbuff_t *tvb, const gint offset, const guint encoding); -guint64 tvb_get_guint40(tvbuff_t *tvb, const gint offset, const guint encoding); -gint64 tvb_get_gint40(tvbuff_t *tvb, const gint offset, const guint encoding); -guint64 tvb_get_guint48(tvbuff_t *tvb, const gint offset, const guint encoding); -gint64 tvb_get_gint48(tvbuff_t *tvb, const gint offset, const guint encoding); -guint64 tvb_get_guint56(tvbuff_t *tvb, const gint offset, const guint encoding); -gint64 tvb_get_gint56(tvbuff_t *tvb, const gint offset, const guint encoding); -guint64 tvb_get_guint64(tvbuff_t *tvb, const gint offset, const guint encoding); +Encoding-to_host-order accessors: -"encoding" should be ENC_BIG_ENDIAN for Network-to-host-order and ENC_LITTLE_ENDIAN -for Little-Endian-to-host-order. +16-bit unsigned (uint16_t) and signed (int16_t) integers: -Endian-to-host-order accessors for single-precision and -double-precision IEEE floating-point numbers: +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); -gfloat tvb_get_ieee_float(tvbuff_t *tvb, const gint offset, const guint encoding); -gdouble tvb_get_ieee_double(tvbuff_t *tvb, const gint offset, const guint encoding); +24-bit unsigned and signed integers: -Just as above, "encoding" should be ENC_BIG_ENDIAN for Network-to-host-order and -ENC_LITTLE_ENDIAN for Little-Endian-to-host-order. +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: -guint32 tvb_get_ipv4(tvbuff_t *tvb, const gint offset); -void tvb_get_ipv6(tvbuff_t *tvb, const gint offset, struct e_in6_addr *addr); +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()" +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. -gchar *tvb_ip_to_str(tvbuff_t *tvb, const gint offset) -gchar *tvb_ip6_to_str(tvbuff_t *tvb, const gint offset) +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 gint offset, e_guid_t *guid); -void tvb_get_letohguid(tvbuff_t *tvb, const gint offset, e_guid_t *guid); -void tvb_get_guid(tvbuff_t *tvb, const gint offset, e_guid_t *guid, const guint representation); +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: -guint8 *tvb_get_string_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, const gint length, const guint encoding); +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 @@ -327,35 +450,21 @@ 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). -guint8 *tvb_get_stringz_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, gint *lengthp, const guint encoding); +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 +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). -const guint8 *tvb_get_const_stringz(tvbuff_t *tvb, const gint offset, gint *lengthp); - -Returns a null-terminated const buffer containing data from the -specified tvbuff, starting at the specified offset, and containing all -bytes from the tvbuff up to and including a terminating null character -in the tvbuff. "*lengthp" will be set to the length of the string, -including the terminating null. - -You do not need to free() this buffer; it will happen automatically once -the next packet is dissected. This function is slightly more efficient -than the others because it does not allocate memory and copy the string, -but it does not do any mapping to UTF-8 or checks for valid octet -sequences. - -gint tvb_get_nstringz(tvbuff_t *tvb, const gint offset, const guint bufsize, guint8* buffer); -gint tvb_get_nstringz0(tvbuff_t *tvb, const gint offset, const guint bufsize, guint8* buffer); +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 @@ -367,8 +476,8 @@ 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. -gchar *tvb_get_ts_23_038_7bits_string(wmem_allocator_t *scope, - tvbuff_t *tvb, const gint bit_offset, gint no_of_chars); +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. @@ -378,22 +487,23 @@ information). Byte Array Accessors: -gchar *tvb_bytes_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, gint offset, gint len); +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). +depending on its scope (typically pinfo->pool 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. -gchar *tvb_bytes_to_str_punct(wmem_allocator_t *scope, tvbuff_t *tvb, gint offset, gint len, gchar punct); +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 gint offset, const gint length, - const guint encoding, GByteArray* bytes, gint *endoff) +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 @@ -402,7 +512,7 @@ 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. -gchar *tvb_bcd_dig_to_wmem_packet_str(tvbuff_t *tvb, const gint offset, const gint len, dgt_set_t *dgt, gboolean skip_first); +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 @@ -413,33 +523,33 @@ 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: -guint8* tvb_memcpy(tvbuff_t *tvb, guint8* target, gint offset, gint length); +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. -guint8* tvb_memdup(wmem_allocator_t *scope, tvbuff_t *tvb, gint offset, gint length); +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. +/* 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. + * boundaries of the buffer. Also see the warning in the Portability section. */ -guint8* tvb_get_ptr(tvbuff_t *tvb, gint offset, gint length); +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: - guint tvb_captured_length(const tvbuff_t *tvb); + unsigned tvb_captured_length(const tvbuff_t *tvb); Get reported length of buffer: - guint tvb_reported_length(const tvbuff_t *tvb); + unsigned tvb_reported_length(const tvbuff_t *tvb); 1.4 Functions to handle columns in the traffic summary window. @@ -467,7 +577,7 @@ 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 +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 @@ -480,15 +590,15 @@ 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 "PROTOABBREV": +to "PROTOFILTERNAME": - col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV"); + 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 +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. @@ -498,7 +608,7 @@ dissector returns, it's safe to use. '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 +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: @@ -516,7 +626,7 @@ efficiently. 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 +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 @@ -532,7 +642,7 @@ 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 +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 @@ -556,10 +666,10 @@ string after it's fetched the data to use when doing that. 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 +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 +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.) @@ -585,7 +695,7 @@ identical to what 'col_append_str' and 'col_append_fstr' do. 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 +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. @@ -595,7 +705,7 @@ 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 +necessary). It will create a fence at the end of the prepended data if the fence does not already exist. @@ -633,7 +743,7 @@ 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 +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. @@ -648,7 +758,7 @@ 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 +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: @@ -719,7 +829,7 @@ struct header_field_info { enum ftenum type; int display; const void *strings; - guint64 bitmask; + uint64_t bitmask; const char *blurb; ..... }; @@ -727,21 +837,19 @@ struct header_field_info { 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 +that will appear in the graphical protocol tree. It must be a non-empty string. -abbrev (FIELDABBREV) +abbrev (FIELDFILTERNAME) -------------------- -A string with an abbreviation of the field. The abbreviation should start -with the abbreviation 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 an abbreviation. It is acceptable to have multiple levels of periods if, +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 abbreviations +subfields. For example, TRMAC has multiple error fields, so the names follow this pattern: "trmac.errors.iso", "trmac.errors.noniso", etc. - -The abbreviation is the identifier used in a display filter. As such it -cannot be an empty string. +It must be a non-empty string. type (FIELDTYPE) ---------------- @@ -765,7 +873,7 @@ The type of value this field holds. The current field types are: 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_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. @@ -784,6 +892,10 @@ The type of value this field holds. The current field types are: 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, @@ -805,6 +917,28 @@ The type of value this field holds. The current field types are: 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() @@ -843,12 +977,12 @@ 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 +(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 +fields. The reason is simply that the type itself implicitly defines the nature of 'display', 'strings', 'bitmask'. display (FIELDDISPLAY) @@ -859,7 +993,7 @@ 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 +base in which you would like the value displayed. The acceptable bases are: BASE_DEC, @@ -879,12 +1013,12 @@ 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(gchar *, guint32); + 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(gchar *, guint64); + 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. @@ -904,7 +1038,7 @@ wide the parent bitfield is). (If the FT_BOOLEAN 'bitmask' is zero, then 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 +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 @@ -915,7 +1049,7 @@ date should be displayed as "{monthname} {day_of_month}, {year}" or as 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 +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 @@ -930,14 +1064,14 @@ 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 +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 { - guint32 value; - gchar *strptr; + uint32_t value; + char *strptr; } value_string; For fields of that type, you would declare an array of "value_string"s: @@ -949,7 +1083,7 @@ For fields of that type, you would declare an array of "value_string"s: }; (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 +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' @@ -957,7 +1091,7 @@ 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 +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. @@ -971,7 +1105,7 @@ 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 is possible. +{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: @@ -1001,12 +1135,31 @@ 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 guint64 (instead of guint32). Instead of using the VALS() +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. @@ -1026,15 +1179,15 @@ For fields with that unit name, you would declare a "unit_name_string": (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.) -There are several "common" unit name structures already defined in -epan/unit_strings.h. Dissector authors may choose to add the unit name -structure there rather than locally in a dissector. - -For hf[] array FT_(U)INT*, FT_FlOAT and FT_DOUBLE fields that need a +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 -'&units_second_seconds'. Furthermore, the 'display' field must be ORed +'&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. @@ -1042,9 +1195,9 @@ one can use a range_string struct. Thus a 'range_string' structure is a way to map ranges to strings. typedef struct _range_string { - guint32 value_min; - guint32 value_max; - const gchar *strptr; + 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: @@ -1056,7 +1209,10 @@ For fields of that type, you would declare an array of "range_string"s: }; If INTVAL_MIN equals INTVAL_MAX for a given entry the range_string -behavior collapses to the one of value_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). @@ -1064,7 +1220,7 @@ 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 +to "Yes"/"No", "Fast"/"Slow", etc.). For these mappings, a struct called true_false_string is used. typedef struct true_false_string { @@ -1081,7 +1237,7 @@ labels, you would declare a "true_false_string"s: }; Its two fields are pointers to the string representing truth, and the -string representing falsehood. For FT_BOOLEAN fields that need a +string representing falsehood. For FT_BOOLEAN fields that need a 'true_false_string' struct, the 'strings' field would be set to 'TFS(&boolstringname)'. @@ -1095,6 +1251,22 @@ in tfs.h, included via packet.h. 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 @@ -1114,7 +1286,7 @@ 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 +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 ""). @@ -1132,9 +1304,9 @@ 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 int proto_eg; + static int hf_field_a; + static int hf_field_b; static hf_register_info hf[] = { @@ -1194,8 +1366,8 @@ Note that the formats used must all belong to the same group as defined below: - 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 and FT_STRINGZPAD -- FT_FLOAT and FT_DOUBLE +- 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 @@ -1221,14 +1393,14 @@ 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 +"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 gint ett_eg = -1; - static gint ett_field_a = -1; + static int ett_eg; + static int ett_field_a; - static gint *ett[] = { + static int *ett[] = { &ett_eg, &ett_field_a }; @@ -1244,8 +1416,8 @@ 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 several functions that the programmer can use to add either -protocol or field labels to the proto_tree: +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); @@ -1255,288 +1427,28 @@ protocol or field labels to the proto_tree: *retval); proto_item* - proto_tree_add_item_ret_uint(tree, id, tvb, start, length, encoding, - *retval); - - proto_item* - proto_tree_add_item_ret_uint64(tree, id, tvb, start, length, encoding, - *retval); - - proto_item* - proto_tree_add_item_ret_boolean(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_subtree_format(tree, tvb, start, length, idx, tree_item, - format, ...); - - proto_item* - proto_tree_add_none_format(tree, id, tvb, start, length, format, ...); - - proto_item* - proto_tree_add_protocol_format(tree, id, tvb, start, length, - format, ...); - - proto_item * - proto_tree_add_bytes(tree, id, tvb, start, length, start_ptr); - - proto_item * - proto_tree_add_bytes_item(tree, id, tvb, start, length, encoding, - retval, endoff, err); - - proto_item * - proto_tree_add_bytes_format(tree, id, tvb, start, length, start_ptr, - format, ...); - - proto_item * - proto_tree_add_bytes_format_value(tree, id, tvb, start, length, - start_ptr, format, ...); - - proto_item * - proto_tree_add_bytes_with_length(tree, id, tvb, start, tvb_length, start_ptr, ptr_length); - - proto_item * - proto_tree_add_time(tree, id, tvb, start, length, value_ptr); - - proto_item * - proto_tree_add_time_item(tree, id, tvb, start, length, encoding, - retval, endoff, err); - - proto_item * - proto_tree_add_time_format(tree, id, tvb, start, length, value_ptr, - format, ...); - - proto_item * - proto_tree_add_time_format_value(tree, id, tvb, start, length, - value_ptr, format, ...); - - proto_item * - proto_tree_add_ipxnet(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_ipxnet_format(tree, id, tvb, start, length, value, - format, ...); - - proto_item * - proto_tree_add_ipxnet_format_value(tree, id, tvb, start, length, - value, format, ...); - - proto_item * - proto_tree_add_ipv4(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_ipv4_format(tree, id, tvb, start, length, value, - format, ...); - - proto_item * - proto_tree_add_ipv4_format_value(tree, id, tvb, start, length, - value, format, ...); - - proto_item * - proto_tree_add_ipv6(tree, id, tvb, start, length, value_ptr); - - proto_item * - proto_tree_add_ipv6_format(tree, id, tvb, start, length, value_ptr, - format, ...); - - proto_item * - proto_tree_add_ipv6_format_value(tree, id, tvb, start, length, - value_ptr, format, ...); - - proto_item * - proto_tree_add_ether(tree, id, tvb, start, length, value_ptr); - - proto_item * - proto_tree_add_ether_format(tree, id, tvb, start, length, value_ptr, - format, ...); - - proto_item * - proto_tree_add_ether_format_value(tree, id, tvb, start, length, - value_ptr, format, ...); - - proto_item * - proto_tree_add_guid(tree, id, tvb, start, length, value_ptr); - - proto_item * - proto_tree_add_guid_format(tree, id, tvb, start, length, value_ptr, - format, ...); - - proto_item * - proto_tree_add_guid_format_value(tree, id, tvb, start, length, - value_ptr, format, ...); - - proto_item * - proto_tree_add_oid(tree, id, tvb, start, length, value_ptr); - - proto_item * - proto_tree_add_oid_format(tree, id, tvb, start, length, value_ptr, - format, ...); - - proto_item * - proto_tree_add_oid_format_value(tree, id, tvb, start, length, - value_ptr, format, ...); - - proto_item * - proto_tree_add_string(tree, id, tvb, start, length, value_ptr); - - proto_item * - proto_tree_add_string_format(tree, id, tvb, start, length, value_ptr, - format, ...); - - proto_item * - proto_tree_add_string_format_value(tree, id, tvb, start, length, - value_ptr, format, ...); - - proto_item * - proto_tree_add_boolean(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_boolean_format(tree, id, tvb, start, length, value, - format, ...); - - proto_item * - proto_tree_add_boolean_format_value(tree, id, tvb, start, length, - value, format, ...); - - proto_item * - proto_tree_add_float(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_float_format(tree, id, tvb, start, length, value, - format, ...); - - proto_item * - proto_tree_add_float_format_value(tree, id, tvb, start, length, - value, format, ...); - - proto_item * - proto_tree_add_double(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_double_format(tree, id, tvb, start, length, value, - format, ...); - - proto_item * - proto_tree_add_double_format_value(tree, id, tvb, start, length, - value, format, ...); - - proto_item * - proto_tree_add_uint(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_uint_format(tree, id, tvb, start, length, value, - format, ...); - - proto_item * - proto_tree_add_uint_format_value(tree, id, tvb, start, length, - value, format, ...); - - proto_item * - proto_tree_add_uint64(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_uint64_format(tree, id, tvb, start, length, value, - format, ...); - - proto_item * - proto_tree_add_uint64_format_value(tree, id, tvb, start, length, - value, format, ...); - - proto_item * - proto_tree_add_int(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_int_format(tree, id, tvb, start, length, value, - format, ...); - proto_item * proto_tree_add_int_format_value(tree, id, tvb, start, length, value, format, ...); proto_item * - proto_tree_add_int64(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_int64_format(tree, id, tvb, start, length, value, - format, ...); - - proto_item * - proto_tree_add_int64_format_value(tree, id, tvb, start, length, - value, format, ...); - - proto_item * - proto_tree_add_eui64(tree, id, tvb, start, length, value); - - proto_item * - proto_tree_add_eui64_format(tree, id, tvb, start, length, value, - format, ...); - - proto_item * - proto_tree_add_eui64_format_value(tree, id, tvb, start, length, - value, format, ...); - - proto_item * - proto_tree_add_checksum(proto_tree *tree, tvbuff_t *tvb, const guint offset, - const int hf_checksum, const int hf_checksum_status, struct expert_field* bad_checksum_expert, - packet_info *pinfo, guint32 computed_checksum, const guint encoding, const guint flags); + 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_bitmask_len(tree, tvb, start, len, header, ett, fields, - encoding); - - proto_item * - proto_tree_add_bitmask_text(tree, tvb, offset, len, name, fallback, - ett, fields, encoding, flags); - - proto_item * - proto_tree_add_bitmask_with_flags(tree, tvb, offset, hf_hdr, ett, - fields, encoding, flags); - - proto_item* proto_tree_add_bits_item(tree, id, tvb, bit_offset, no_of_bits, encoding); - proto_item * - proto_tree_add_split_bits_item_ret_val(tree, hf_index, tvb, bit_offset, - crumb_spec, return_value); - - void - proto_tree_add_split_bits_crumb(tree, hf_index, tvb, bit_offset, - crumb_spec, crumb_index); - - proto_item * - proto_tree_add_bits_ret_val(tree, id, tvb, bit_offset, no_of_bits, - return_value, encoding); - - proto_item * - proto_tree_add_uint_bits_format_value(tree, id, tvb, bit_offset, - no_of_bits, value, format, ...); - - proto_item * - proto_tree_add_boolean_bits_format_value(tree, id, tvb, bit_offset, - no_of_bits, value, format, ...); - - proto_item * - proto_tree_add_int_bits_format_value(tree, id, tvb, bit_offset, - no_of_bits, value, format, ...); - - proto_item * - proto_tree_add_float_bits_format_value(tree, id, tvb, bit_offset, - no_of_bits, value, format, ...); - - proto_item * - proto_tree_add_ts_23_038_7bits_item(tree, hf_index, tvb, - bit_offset, no_of_chars); - -The 'tree' argument is the tree to which the item is to be added. The +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, @@ -1553,11 +1465,15 @@ dissection is complete, set the length with 'proto_item_set_len()': 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 +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. @@ -1576,19 +1492,23 @@ 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, +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 UCS-2 and UTF-16, the byte order of the encoding must be -specified (for counted UCS-2 and UTF-16 strings, the byte order of the -count and the 16-bit values in the string must be the same). In other -cases, ENC_NA should be used. The character encodings that are -currently supported 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 @@ -1597,8 +1517,11 @@ currently supported are: 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 + 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 @@ -1614,29 +1537,50 @@ currently supported are: ENC_ISO_8859_14 - ISO 8859-14 ENC_ISO_8859_15 - ISO 8859-15 ENC_ISO_8859_16 - ISO 8859-16 - ENC_WINDOWS_1250 - Windows-1250 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 CP437 + 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 +the time stamp is specified, as well as its byte order. The time stamp encodings that are currently supported are: - ENC_TIME_TIMESPEC - 8 bytes; the first 4 bytes are seconds since - the UN*X epoch (1970-01-01 00:00:00 UTC) and the next 4 bytes - are nanoseconds since that second. (I.e., a UN*X struct - timespec with a 4-byte time_t.) + 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 + 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.) @@ -1644,14 +1588,14 @@ encodings that are currently supported are: 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 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 + 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_TIMEVAL - 8 bytes; the first 4 bytes are seconds since the + 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.) + 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. @@ -1659,37 +1603,57 @@ encodings that are currently supported are: 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. (I.e., seconds since the NTP epoch.) + 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. (I.e., milliseconds since the NTP epoch.) + 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 +the time stamp is specified, as well as its byte order. The time stamp encodings that are currently supported are: - ENC_TIME_TIMESPEC - 8 bytes; the first 4 bytes are seconds and the - next 4 bytes are nanoseconds. + 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_TIMEVAL - 8 bytes; the first 4 bytes are seconds and the + 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 +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 +protocol. The FID is the high nibble of the first byte of the TH. The FID would be registered like this: name = "Format Identifier" @@ -1710,7 +1674,7 @@ The code to add the FID to the tree would be; 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, +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.) @@ -1735,7 +1699,7 @@ 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 futher processing only integer and unsigned integer types up to 32 bits are +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() @@ -1746,7 +1710,7 @@ 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 +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. @@ -1760,17 +1724,17 @@ 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 +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_RFC_822 or ENC_RFC_1123. For proto_tree_add_bytes_item() it can only +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 +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 @@ -1831,7 +1795,7 @@ 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 +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 @@ -1861,14 +1825,14 @@ 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 +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 +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 @@ -1903,10 +1867,10 @@ 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 +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 +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() @@ -1930,7 +1894,7 @@ 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 +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, @@ -1944,23 +1908,23 @@ 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" +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 +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 +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 +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 @@ -1992,7 +1956,7 @@ 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 +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. @@ -2018,7 +1982,7 @@ 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 +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() @@ -2047,18 +2011,18 @@ the individual subfields of the bitmask. These fields must either be integers 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 +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 hf_scsi_inq_peripheral; + static int hf_scsi_inq_qualifier; + static int hf_scsi_inq_devtype; ... - static gint ett_scsi_inq_peripheral = -1; + static int ett_scsi_inq_peripheral; ... - static const int *peripheral_fields[] = { + static int * const peripheral_fields[] = { &hf_scsi_inq_qualifier, &hf_scsi_inq_devtype, NULL @@ -2133,9 +2097,9 @@ proto_tree_add_bitmask() and proto_tree_add_bitmask_text() may not: than the packet it was called to interpret. -PROTO_ITEM_SET_GENERATED() +proto_item_set_generated() -------------------------- -PROTO_ITEM_SET_GENERATED is used to mark fields as not being read from the +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 @@ -2147,15 +2111,15 @@ indicating a generated field. Header checksum: 0x3d42 [correct] [Checksum Status: Good (1)] -PROTO_ITEM_SET_HIDDEN() +proto_item_set_hidden() ----------------------- -PROTO_ITEM_SET_HIDDEN is used to hide fields, which have already been added +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 +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. @@ -2163,8 +2127,8 @@ 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 +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: @@ -2173,7 +2137,7 @@ Rings are 3-digit hex numbers, and bridges are single hex digits: 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 +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. @@ -2187,14 +2151,14 @@ skeleton of how the programmer might code this. pi = proto_tree_add_item(tree, hf_tr_rif_ring, ..., ENC_BIG_ENDIAN); - PROTO_ITEM_SET_HIDDEN(pi); + 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); + proto_item_set_hidden(pi); } The logical tree has these items: @@ -2214,9 +2178,9 @@ filter is then possible: tr.rif_ring eq 0x013 -PROTO_ITEM_SET_URL +proto_item_set_url ------------------ -PROTO_ITEM_SET_URL is used to mark fields as containing a URL. This can only +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. @@ -2232,8 +2196,8 @@ to generate a COL_INFO line for a frame. val_to_str() handles the most common case: - const gchar* - val_to_str(guint32 val, const value_string *vs, const char *fmt) + 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 @@ -2250,8 +2214,8 @@ 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 gchar* - try_val_to_str(guint32 val, const value_string *vs) + 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()' @@ -2270,17 +2234,17 @@ functions. To handle 64-bit values, there are an equivalent set of functions. These are: - const gchar * - val64_to_str(const guint64 val, const val64_string *vs, const char *fmt) + const char * + val64_to_str(const uint64_t val, const val64_string *vs, const char *fmt) - const gchar * - val64_to_str_const(const guint64 val, const val64_string *vs, const char *unknown_str); + const char * + val64_to_str_const(const uint64_t val, const val64_string *vs, const char *unknown_str); - const gchar * - try_val64_to_str(const guint64 val, const val64_string *vs); + const char * + try_val64_to_str(const uint64_t val, const val64_string *vs); - const gchar * - try_val64_to_str_idx(const guint64 val, const val64_string *vs, gint *idx); + 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 @@ -2312,7 +2276,7 @@ Where: 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 0th byte. + 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 @@ -2327,7 +2291,7 @@ Where: 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 0th byte. + 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. @@ -2346,7 +2310,7 @@ Where: 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 0th byte. + 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 @@ -2357,7 +2321,7 @@ Where: 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 +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. @@ -2365,16 +2329,16 @@ function within the calling dissector. 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 +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 guint32 pattern, + 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 gchar *pattern, + void dissector_add_string(const char *name, const char *pattern, dissector_handle_t handle); void dissector_add_for_decode_as(const char *name, @@ -2384,18 +2348,18 @@ table using their unique identifier using one of the following APIs: 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 useone of the +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 guint32 uint_val, tvbuff_t *tvb, packet_info *pinfo, + 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 guint32 uint_val, tvbuff_t *tvb, packet_info *pinfo, - proto_tree *tree, const gboolean add_proto_name, void *data); + 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 gchar *string, + 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 @@ -2418,6 +2382,9 @@ section of epan/dissectors/CMakeLists.txt 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)> @@ -2436,8 +2403,8 @@ section of epan/dissectors/CMakeLists.txt ./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://wiki.wireshark.org/FuzzTesting>. + 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 @@ -2451,25 +2418,26 @@ section of epan/dissectors/CMakeLists.txt should be a summary of the changes followed by an empty line and a more verbose description. - - 'git push origin HEAD:refs/for/master' to push the changes to Gerrit. (If - you previously ran 'git config --add remote.origin.push HEAD:refs/for/master' - then only 'git push' is needed.) + - '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://wiki.wireshark.org>. + - 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://wiki.wireshark.org/HowToEdit> - and <https://wiki.wireshark.org/ProtocolReference> + 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://wiki.wireshark.org/SampleCaptures>. These files are used by - the automated build system for fuzz testing. + <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 bug database, found at - <https://bugs.wireshark.org>, 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 Gerrit - change and bug. + 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. @@ -2480,27 +2448,27 @@ 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 +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 seven routines that you will use to work with a conversation: -conversation_new, find_conversation, find_or_create_conversation, +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 +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 +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. @@ -2510,35 +2478,35 @@ 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 +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 ptype variable is used to differentiate between -conversations over different protocols, i.e. TCP and UDP. The options +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 know when conversation_new is called. See section 2.4 for more +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(guint32 setup_frame, address *addr1, - address *addr2, port_type ptype, guint32 port1, guint32 port2, - guint options); + conversation_t *conversation_new(uint32_t setup_frame, address *addr1, + address *addr2, conversation_type ctype, uint32_t port1, uint32_t port2, + unsigned options); Where: - guint32 setup_frame = The lowest numbered frame for this conversation - address* addr1 = first data packet address - address* addr2 = second data packet address - port_type ptype = port type, this is defined in packet.h - guint32 port1 = first data packet port - guint32 port2 = second data packet port - guint options = conversation options, NO_ADDR2 and/or NO_PORT2 + 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 +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. @@ -2548,30 +2516,48 @@ 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 +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 find_conversation function. +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, +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(guint32 frame_num, address *addr_a, - address *addr_b, port_type ptype, guint32 port_a, guint32 port_b, - guint options); + 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: - guint32 frame_num = a frame number to match - address* addr_a = first address - address* addr_b = second address - port_type ptype = port type - guint32 port_a = first data packet port - guint32 port_b = second data packet port - guint options = conversation options, NO_ADDR_B and/or NO_PORT_B + 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 @@ -2585,10 +2571,10 @@ 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 +"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 +"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 @@ -2597,27 +2583,48 @@ address/port pairs; you don't have to worry about which side the "a" or 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. +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.4 The find_conversation_pinfo function. +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); + extern conversation_t *find_conversation_pinfo(packet_info *pinfo, + const unsigned options); Where: - packet_info *pinfo = the packet_info structure + 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 pinfo structure (as is commonly done). +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.5 The find_or_create_conversation function. +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 @@ -2634,8 +2641,7 @@ 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.6 The conversation_add_proto_data function. +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. @@ -2650,18 +2656,18 @@ Where: 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 +"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 +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.7 The conversation_get_proto_data function. +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. @@ -2674,17 +2680,17 @@ Where: conversation_t *conv = the conversation in question int proto = registered protocol number -"conversation" is the conversation created with conversation_new. "proto" +"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 +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.8 The conversation_delete_proto_data function. +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), +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: @@ -2695,11 +2701,11 @@ Where: conversation_t *conv = the conversation in question int proto = registered protocol number -"conversation" is the conversation created with conversation_new. "proto" +"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.9 The conversation_set_dissector function +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 @@ -2763,7 +2769,7 @@ 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 +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 ************************/ @@ -2787,7 +2793,8 @@ my_entry_t *data_ptr; /* look up the conversation */ conversation = find_conversation(pinfo->num, &pinfo->src, &pinfo->dst, - pinfo->ptype, pinfo->srcport, pinfo->destport, 0); + conversation_pt_to_conversation_type(pinfo->ptype), + pinfo->srcport, pinfo->destport, 0); /* if conversation found get the data pointer that you stored */ if (conversation) @@ -2802,7 +2809,8 @@ else { /* create the conversation with your data pointer */ - conversation = conversation_new(pinfo->num, &pinfo->src, &pinfo->dst, pinfo->ptype, + 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); } @@ -2826,30 +2834,31 @@ that starts at the specific frame number. /* in the dissector routine */ conversation = find_conversation(pinfo->num, &pinfo->src, &pinfo->dst, - pinfo->ptype, pinfo->srcport, pinfo->destport, 0); + 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, pinfo->ptype, pinfo->srcport, pinfo->destport, - NULL, 0); + 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 +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 +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 +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. @@ -2891,13 +2900,13 @@ upon the conversation index and values inside the request packets. 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 + 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 +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 @@ -2906,16 +2915,26 @@ 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. +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 or -register_dissector. +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. -create_dissector_handle takes as arguments 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. +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 @@ -2938,7 +2957,7 @@ static void sub_dissector(tvbuff_t *tvb, packet_info *pinfo, socketpair */ conversation = find_conversation(pinfo->num, - &pinfo->src, &pinfo->dst, protocol, + &pinfo->src, &pinfo->dst, conversation_type, src_port, dst_port, 0); /* If there is no such conversation, or if there is one but for @@ -2965,7 +2984,7 @@ proto_register_PROTOABBREV(void) { ... - sub_dissector_handle = create_dissector_handle(sub_dissector, + sub_dissector_handle = register_dissector("PROTOABBREV", sub_dissector, proto); ... @@ -2975,12 +2994,12 @@ proto_register_PROTOABBREV(void) 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 +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 +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. @@ -2992,7 +3011,7 @@ 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 +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) @@ -3000,12 +3019,12 @@ the same socketpair. There are two support routines that will allow the second port and/or address to be set later. -conversation_set_port2( conversation_t *conv, guint32 port); +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 +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. @@ -3041,7 +3060,7 @@ static dissector_handle_t sub_dissector_handle; if ( (conversation == NULL) || (conversation->dissector_handle != sub_dissector_handle) ) { conversation = conversation_new(pinfo->num, - &server_src_addr, 0, protocol, + &server_src_addr, 0, conversation_type, server_src_port, 0, new_conv_info, NO_ADDR2 | NO_PORT2); /* set the dissector for the new conversation */ @@ -3051,8 +3070,8 @@ static dissector_handle_t 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 +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 @@ -3060,16 +3079,16 @@ 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 delcared in <epan/proto_data.h>. +These functions are declared in <epan/proto_data.h>. void -p_add_proto_data(wmem_allocator_t *scope, packet_info *pinfo, int proto, guint32 key, void *proto_data) +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, guint32 key) +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 + 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 @@ -3103,36 +3122,41 @@ 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, guint base, guint *var); + 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, gboolean *var); + 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, gint *var, - const enum_val_t *enumvals, gboolean radio_buttons) + 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. + * 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, - gboolean for_writing) + 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, - guint32 max_value) + 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 @@ -3146,15 +3170,15 @@ Where: module - Returned by the prefs_register_protocol routine 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 + 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 + 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 + 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 @@ -3169,9 +3193,9 @@ Where: module - Returned by the prefs_register_protocol routine the numerical value corresponding to that name and description - radio_buttons - TRUE if the field is to be displayed in the + 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 + false if it is to be displayed as an option menu max_value - The maximum allowed value for a range (0 is the minimum). @@ -3212,34 +3236,34 @@ a preference obsolete is to register it as such: 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 +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 +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 +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-dns.c: +example, stolen from packet-hartip.c: #include "packet-tcp.h" dissector_handle_t hartip_tcp_handle; dissector_handle_t hartip_udp_handle; - hartip_tcp_handle = create_dissector_handle(dissect_hartip_tcp, proto_hartip); - hartip_udp_handle = create_dissector_handle(dissect_hartip_udp, proto_hartip); + 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("udp.port", HARTIP_PORT, hartip_udp_handle); + 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 @@ -3264,7 +3288,7 @@ The arguments to tcp_dissect_pdus are: the tvbuff pointer, packet_info pointer, and proto_tree pointer passed to the dissector; - a gboolean flag indicating whether desegmentation is enabled for + a bool flag indicating whether desegmentation is enabled for your protocol; the number of bytes of PDU data required to determine the length @@ -3306,8 +3330,8 @@ 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 +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. @@ -3337,10 +3361,10 @@ static hf_register_info hf[] = { **/ static int dissect_cstr(tvbuff_t * tvb, packet_info * pinfo, proto_tree * tree, void *data _U_) { - guint offset = 0; + unsigned offset = 0; while(offset < tvb_reported_length(tvb)) { - gint available = tvb_reported_length_remaining(tvb, offset); - gint len = tvb_strnlen(tvb, offset, available); + 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 */ @@ -3354,10 +3378,9 @@ static int dissect_cstr(tvbuff_t * tvb, packet_info * pinfo, proto_tree * tree, len += 1; /* Add one for the '\0' */ if (tree) { - proto_tree_add_item(tree, hf_cstring, tvb, offset, len, - ENC_ASCII|ENC_NA); + proto_tree_add_item(tree, hf_cstring, tvb, offset, len, ENC_ASCII); } - offset += (guint)len; + offset += (unsigned)len; } /* if we get here, then the end of the tvb coincided with the end of a @@ -3375,7 +3398,7 @@ loop. 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 +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. @@ -3388,11 +3411,11 @@ example using UDP and TCP dissection, stolen from packet-dnp.c: dissector_handle_t dnp3_tcp_handle; dissector_handle_t dnp3_udp_handle; - dnp3_tcp_handle = create_dissector_handle(dissect_dnp3_tcp, proto_dnp3); - dnp3_udp_handle = create_dissector_handle(dissect_dnp3_udp, proto_dnp3); + 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("tcp.port", TCP_PORT_DNP, dnp3_tcp_handle); - dissector_add_uint("udp.port", UDP_PORT_DNP, dnp3_udp_handle); + 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 @@ -3408,11 +3431,11 @@ are called to handle PDU data. static int dissect_dnp3_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data) { - if (!check_dnp3_header(tvb, FALSE)) { + if (!check_dnp3_header(tvb, false)) { return 0; } - tcp_dissect_pdus(tvb, pinfo, tree, TRUE, DNP_HDR_LEN, + tcp_dissect_pdus(tvb, pinfo, tree, true, DNP_HDR_LEN, get_dnp3_message_len, dissect_dnp3_message, data); return tvb_captured_length(tvb); @@ -3432,7 +3455,7 @@ The arguments to udp_dissect_pdus are: 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. + 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, @@ -3458,17 +3481,17 @@ The arguments to udp_dissect_pdus are: 2.9 PINOs (Protocols in name only) -For the typical dissector there is a 1-1 relationship between it and it's -protocol. However, there are times when a protocol needs multiple "names" +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 muliple names removes confusion when picking dissection through +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" +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. @@ -3476,8 +3499,8 @@ 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 +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. @@ -3494,7 +3517,7 @@ 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", "Network", "ip.proto", 1, 0, &ip_da_values, NULL, NULL, + 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); @@ -3502,7 +3525,7 @@ Consider the following example using IP dissection, stolen from packet-ip.c: 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 +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. @@ -3512,8 +3535,8 @@ 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 reseting the changes -to the dissector table through Decode As GUI functionality. For dissector +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. @@ -3557,13 +3580,13 @@ instead, the API description here should be good enough. 2.11.1 ptvcursor API. ptvcursor_t* -ptvcursor_new(proto_tree* tree, tvbuff_t* tvb, gint offset) +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, gint length, const guint encoding) +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, @@ -3572,27 +3595,27 @@ 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, gint length, const guint encoding, guint32 *retval); - Like ptvcursor_add, but returns uint value retreived +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, gint length, const guint encoding, gint32 *retval); - Like ptvcursor_add, but returns int value retreived +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, gint length, const guint encoding, wmem_allocator_t *scope, const guint8 **retval); - Like ptvcursor_add, but returns string retreived +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, gint length, const guint encoding, gboolean *retval); - Like ptvcursor_add, but returns boolean value retreived +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, gint length, const guint encoding) +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, gint length) +ptvcursor_advance(ptvcursor_t* ptvc, int length) Advances the internal cursor without adding anything to the proto_tree. void @@ -3602,7 +3625,7 @@ after your dissection with the ptvcursor API is completed. proto_tree* -ptvcursor_push_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree) +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. @@ -3611,16 +3634,16 @@ 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, gint length, - const guint encoding, gint ett_subtree); +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, gint length, - gint ett_subtree, const char* format, ...); +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 @@ -3632,7 +3655,7 @@ tvbuff_t* ptvcursor_tvbuff(ptvcursor_t* ptvc) Returns the tvbuff associated with the ptvcursor. -gint +int ptvcursor_current_offset(ptvcursor_t* ptvc) Returns the current offset. @@ -3645,7 +3668,7 @@ 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, gint ett_subtree); +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. @@ -3674,7 +3697,7 @@ 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 +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 diff --git a/doc/README.extcap b/doc/README.extcap deleted file mode 100644 index 32340f6862..0000000000 --- a/doc/README.extcap +++ /dev/null @@ -1,428 +0,0 @@ -EXTCAP: DEVELOPER GUIDE -======================= - -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 app. - -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 USER: 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. - -THE CAPTURE PROCESS -=================== -The actual capture is run after a setup process that can be made manually by the -user or automatically by the GUI. All the steps performed are done for every extcap. - -Let's go through those steps. - -STEP1: the extcap is queried for its interfaces. - -extcapbin --extcap-interfaces - -This call must print the existing interfaces for this extcap and must return 0. -The output must conform to the grammar specified for extcap, and it is specified -in the doc/extcap.4 generated man page (in the build dir). - -Since Wireshark 2.9 this call is extended with --extcap-version x.x, which will -allways represent the calling wireshark's version information. This can be used -to change behavior depending on the wireshark version in question - -Example: - -$ extcapbin --extcap-interfaces --extcap-version 3.0 -extcap {version=1.0}{help=Some help url} -interface {value=example1}{display=Example interface 1 for extcap} -interface {value=example2}{display=Example interface 2 for extcap} - -The version for the extcap sentence (which may exist as often as wanted, but only -the last one will be used) will be used for displaying the version information of -the extcap interface in the about dialog of Wireshark (Qt only). - -The value for each interface will be used in subsequent calls as the interface name -IFACE. - -Using the help argument, an interface may provide a generic help url for the extcap -utility. - -STEP2: the extcap is queried for valid DLTs (Data Link Types) for all the -interfaces returned by the step 1. - -extcapbin --extcap-dlts --extcap-interface IFACE - -This call must print the valid DLTs for the interface specified. This call is -made for all the interfaces and must return 0. - -Example: - -$ extcapbin --extcap-interface IFACE --extcap-dlts -dlt {number=147}{name=USER1}{display=Demo Implementation for Extcap} - -A binary or script, which neither provides an interface list or a DLT list will -not show up in the extcap interfaces list. - - -STEP3: the extcap is queried for the configuration options for an interface. - -extcapbin --extcap-interface IFACE --extcap-config - -Each interface can have custom options that are valid for this interface only. -Those config options are specified on the command line when running the actual -capture. To allow an end-user to specify certain options, such options may be -provided using the extcap config argument. - -To share which options are available for an interface, the extcap responds to -the command --extcap-config, that shows all the available options (aka additional command -line options). - -Those options are automatically presented via a dialog to the user for the individual -interface. - -Example: - -$ extcapbin --extcap-interface IFACE --extcap-config -arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}{type=integer}{range=1,15}{required=true} -arg {number=1}{call=--message}{display=Message}{tooltip=Package message content}{placeholder=Please enter a message here ...}{type=string} -arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag} -arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector} -arg {number=4}{call=--server}{display=IP address for log server}{type=string}{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} -value {arg=3}{value=if1}{display=Remote1}{default=true} -value {arg=3}{value=if2}{display=Remote2}{default=false} - -Now the user can click on the options and change them. They are sent to the -extcap when the capture is launched. - -There are two kind of options available: - -* file, integer, string, boolean, boolflag - are value based options and each expect - a single value via the command-line call -* selector, checkbox - are selections and can be presented multiple times in the command - line. Both expect subsequent "value" items in the config list, with the corresponding - argument selected via arg - - -STEP4: the capture. Once the interfaces are listed and configuration is customized -by the user, the capture is run. - -extcapbin --extcap-interface IFACE [params] --capture [--extcap-capture-filter CFILTER] - --fifo FIFO - -To run the capture, the extcap must implement the --capture, --extcap-capture-filter -and --fifo option. -They are automatically added by wireshark that opens the fifo for reading. All -the other options are automatically added to run the capture. The extcap interface -is used like all other interfaces (meaning that capture on multiple interfaces, as -well as stopping and restarting the capture is supported). - - -ARGUMENTS -========== -The extcap interface provides the possibility for generating a GUI dialog to -set and adapt settings for the extcap binary. - -All options must provide a number, by which they are identified. No NUMBER may be -provided twice. Also all options must present the elements CALL and DISPLAY, where -call provides the arguments name on the command-line and display the name in the GUI. - -Additionally TOOLTIP and PLACEHOLDER may be provided, which will give the user an -explanation within the GUI, about what to enter into this field. - -These options do have types, for which the following types are being supported: - - * INTEGER, UNSIGNED, LONG, DOUBLE - this provides a field for entering a numeric value - of the given data type. A DEFAULT value may be provided, as well as a RANGE - - arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages} - {type=integer}{range=1,15}{default=0} - - * STRING - Let the user provide a string to the capture - - arg {number=1}{call=--server}{display=IP Address}{tooltip=IP Address for log server}{type=string}{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} - - - validation allows to provide a regular expression string, which is used to check - the user input for validity beyond normal data type or range checks. Back-slashes - must be escaped (as in \\b for \b) - - * PASSWORD - Let the user provide a masked string to the capture. Password strings are - not saved, when the extcap configuration is being saved - - arg {number=0}{call=--password}{display=The user password}{tooltip=The password for the connection}{type=password} - - * BOOLEAN,BOOLFLAG - this provides the possibility to set a true/false value. - BOOLFLAG values will only appear in the command-line if set to true, otherwise they - will not be added to the command-line call for the extcap interface - - arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag} - - * FILESELECT - Let the user provide a filepath to the capture. If MUSTEXIST is - being provided, the GUI checks if the file exists. - - arg {number=3}{call=--logfile}{display=Logfile}{tooltip=A file for log messages}{type=fileselect}{mustexist=false} - - * SELECTOR, RADIO, MULTICHECK - an optionfield, where the user may choose one or - more options from. If PARENT is provided for the value items, the option fields - for MULTICHECK and SELECTOR are being presented in a tree-like structure. SELECTOR - and RADIO values must present a default value, which will be the value provided to - the extcap binary for this argument - - arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector} - value {arg=3}{value=if1}{display=Remote1}{default=true} - value {arg=3}{value=if2}{display=Remote2}{default=false} - - RELOAD A SELECTOR - a selector may be reloaded from the configuration dialog of the - extcap application within wireshark. With the reload argument (defaults to false), the - entry can be marked as reloadable. - - arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}{reload=true}{placeholder=Load interfaces...} - - After this has been defined, the user will get a button displayed in the configuration - dialog for this extcap application, with the text "Load interfaces..." in this case, and - a generic "Reload" text if no text has been provided. - - The extcap utility is then called again with all filled out arguments and the additional - parameter "--extcap-reload-option <option_name>". It is expected to return a value section - for this option, as it would during normal configuration. The provided option list is - then presented as the selection, a previous selected option will be reselected if applicable. - -VALIDATION OF ARGUMENTS -======================= -Arguments may be set with "{required=true}" which enforces a value being provided, before -a capture can be started using the extcap options dialog. This is not being checked, if -the extcap is started via a simple double-click. The necessary fields are marked for the -customer, to ensure a visibility for the end customer of the required argument. - -Additionally text and number arguments may also be checked using a regular expression, -which is provided using the validation attribute (see example above). The syntax for -such a check is the same as for Qt RegExp classes. This feature is only active in the -Qt version of Wireshark. - - -TOOLBAR CONTROLS -================ -An extcap utility can provide configuration for controls to use in an interface toolbar. -This controls are bidirectional and can be used to control the extcap utility while -capturing. - -This is useful in scenarios where configuration can be done based on findings in the -capture process, setting temporary values or give other inputs without restarting the -current capture. - -Example: - -$ extcapbin --extcap-interfaces -extcap {version=1.0}{display=Example extcap interface} -interface {value=example1}{display=Example interface 1 for extcap} -interface {value=example2}{display=Example interface 2 for extcap} -control {number=0}{type=string}{display=Message}{tooltip=Package message content. Must start with a capital letter.}{validation=[A-Z]+}{required=true} -control {number=1}{type=selector}{display=Time delay}{tooltip=Time delay between packages} -control {number=2}{type=boolean}{display=Verify}{default=true}{tooltip=Verify package content} -control {number=3}{type=button}{display=Turn on}{tooltip=Turn on or off} -control {number=4}{type=button}{role=logger}{display=Log}{tooltip=Show capture log} -value {control=1}{value=1}{display=1 sec} -value {control=1}{value=2}{display=2 sec}{default=true} - -All controls will be presented as GUI elements in a toolbar specific to the extcap -utility. The extcap must not rely on using those controls (they are optional) because -of other capturing tools not using GUI (e.g. tshark, tfshark). - - -CONTROLS -======== -The controls are similar to the ARGUMENTS, but without the CALL element. All controls -may be given a default value at startup and most can be changed during capture, both -by the extcap and the user (depending on the type of control). - -All controls must provide a NUMBER, by which they are identified. No NUMBER may be -provided twice. Also all options must present the elements TYPE and DISPLAY, where -TYPE provides the type of control to add to the toolbar and DISPLAY the name in the GUI. - -Additionally TOOLTIP and PLACEHOLDER may be provided, which will give the user an -explanation within the GUI. - -All controls, except from the logger, help and restore buttons, may be disabled -(and enabled) in GUI by the extcap during capture. This can be because of set-once -operations, or operations which takes some time to complete. - -All control values which are changed by the user (not equal to the default value) will -be sent to the extcap utility when starting a capture. The extcap utility may choose -to discard initial values and set new values, depending on implementation. - -This TYPEs are defined as controls: - - * BOOLEAN - This provides a checkbox with the possibility to set a true/false value. - - The extcap utility can set a default value at startup, and can change (set) and receive - value changes while capturing. When starting a capture the GUI will send the value if - different from the default value. - - The payload is one byte with binary value 0 or 1. - - Valid Commands: Set value, Enable, Disable. - - * BUTTON - This provides a button with different ROLEs: - - ** CONTROL - This button will send a signal when pressed. - This is the default if no role is configured. - The button is only enabled when capturing. - - The extcap utility can set the button text at startup, and can change (set) the - button text and receive button press signals while capturing. The button is - disabled and the button text is restored to the default text when not capturing. - - The payload is either the button text or empty (signal). - - Valid Commands: Set value, Enable, Disable. - - ** LOGGER - This provides a logger mechanism where the extcap utility can send log - entries to be presented in a log window. This communication is unidirectional. - - The payload is the log entry, and should be ended with a newline. - Maximum length is 65535 bytes. - - Valid Commands: Set log entry, Add log entry. - - The Set command will clear the log before adding the entry. - - ** HELP - This button opens the help page, if configured. - This role has no controls and will not be used in communication. - - Valid Commands: NONE. - - ** RESTORE - This button will restore all control values to default. - This role has no controls and will not be used in communication. - The button is only enabled when not capturing. - - Valid Commands: NONE. - - * SELECTOR - This provides a combo box with fixed values which can be selected. - - The extcap utility can set default values at startup, and add and remove values and - receive change in value selection while capturing. When starting a capture the GUI - will send the value if different from the default value. - - The payload is a string with the value, and optionally a string with a display - value if this is different from the value. This two string values are separated - by a null character. - - Valid Commands: Set selected value, Add value, Remove value, Enable, Disable. - - If value is empty the Remove command will remove all entries. - - * STRING - This provides a text edit line with the possibility to set a string or any - value which can be represented in a string (integer, float, date, etc.). - - The extcap utility can set a default string value at startup, and can change (set) and - receive value changes while capturing. When starting a capture the GUI will send the - value if different from the default value. - - The payload is a string with the value. Maximum length is 32767 bytes. - - Valid Commands: Set value, Enable, Disable. - - The element VALIDATION allows to provide a regular expression string, which is used - to check the user input for validity beyond normal data type or range checks. - Back-slashes must be escaped (as in \\b for \b). - - -MESSAGES -======== -In addition to the controls it's possible to send a single message from the extcap -utility to the user. This message can be put in the status bar or displayed in a -information, warning or error dialog which must be accepted by the user. This message -does not use the NUMBER argument so this can have any value. - - -CONTROL PROTOCOL -================ -The protocol used to communicate over the control pipes has a fixed size header of -6 bytes and a payload with 0 - 65535 bytes. - -Control packet: - - +----+----+----+----+----+----+----+----+ - | Sync Pipe Indication (1 byte) | - +----+----+----+----+----+----+----+----+ - | Message Length | - | (3 bytes network order) | - +----+----+----+----+----+----+----+----+ - | Control Number (1 byte) | - +----+----+----+----+----+----+----+----+ - | Command (1 byte) | - +----+----+----+----+----+----+----+----+ - | Payload | - | (0 - 65535 bytes) | - +----+----+----+----+----+----+----+----+ - - Sync Pipe Indication: - The common sync pipe indication. This protocol uses the value 'T'. - - Message Length: - Payload length + 2 bytes for control number and command. - - Control Number: - Unique number to identify the control. This number also gives the order of - the controls in the interface toolbar. - - Command: Control type: - 0 = Initialized none - 1 = Set boolean / button / logger / selector / string - 2 = Add logger / selector - 3 = Remove selector - 4 = Enable boolean / button / selector / string - 5 = Disable boolean / button / selector / string - 6 = Statusbar message none - 7 = Information message none - 8 = Warning message none - 9 = Error message none - - Payload Length: - The length of the following payload. Maximum length is 65535 bytes. - -The Initialized command will be sent from the GUI to the extcap utility when all -user changed control values are sent after starting a capture. This is an indication -that the GUI is ready to receive control values. - -The GUI will only send Initialized and Set commands. The extcap utility shall not -send the Initialized command. - -Messages with unknown control number or command will be silently ignored. - - -DEVELOPMENT -=========== -To have extcap support, the specific extcap must be compiled. An example for -cmake compiling the extcap plugin androiddump is provided within wireshark. -The extcap subsystem and the bundled extcaps are compiled by default. - -Additionally there is an example python script available in doc/extcap_example.py. - -When developing a new extcap, it must be created under extcap/ directory and -added to the makefiles. Once compiled it will be under the extcap/ directory -in the build dir. - -If the current extcaps configuration is copied, the new extcap will need specific -configuration flags like --enable-<newextcap> or -DBUILD_<newextcap> - -Since this is a plugin, the developer must ensure that the extcap dir will be -loaded. To see which dir is loaded, they must open HELP->ABOUT->FOLDER and look -for "Extcap Path". If there is a system path (like /usr/local/lib/wireshark/extcap/) -the extcaps in the build dir are not loaded. To load them, wireshark must be -loaded with WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1. Now the "Extcap path" should -point to the extcap dir under your build environment. diff --git a/doc/README.heuristic b/doc/README.heuristic index af53b74535..08e9464fa1 100644 --- a/doc/README.heuristic +++ b/doc/README.heuristic @@ -54,13 +54,13 @@ 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, the DCCP, -SCTP, TCP, TIPC and UDP dissectors all provide this capability via their -"Try heuristic sub-dissectors first" preference, but none of them have this -option enabled by default. +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 should then be set up to always directly +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. @@ -92,9 +92,9 @@ 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 + (before returning false) as this will prevent following heuristic dissector handoffs. In practice, this normally means - that a test should be done to verify that the required data is + 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). @@ -103,7 +103,7 @@ 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 177 files (October 2015). +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): @@ -117,32 +117,32 @@ static dissector_handle_t PROTOABBREV_tcp_handle; static dissector_handle_t PROTOABBREV_pdu_handle; /* Heuristics test */ -static gboolean +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; + return false; /* 1) first byte must be 0x42 */ if ( tvb_get_guint8(tvb, 0) != 0x42 ) - return FALSE; + 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; + 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; + 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; + return false; /* Assume it's your packet ... */ - return TRUE; + return true; } /* Dissect the complete PROTOABBREV pdu */ @@ -155,25 +155,25 @@ dissect_PROTOABBREV_pdu(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, voi } /* For tcp_dissect_pdus() */ -static guint +static unsigned get_PROTOABBREV_len(packet_info *pinfo _U_, tvbuff_t *tvb, int offset, void *data _U_) { - return (guint) tvb_get_ntohs(tvb, offset+3); + 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, + tcp_dissect_pdus(tvb, pinfo, tree, true, 5, get_PROTOABBREV_len, dissect_PROTOABBREV_pdu, data); return tvb_reported_length(tvb); } -static gboolean +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; + 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 @@ -187,23 +187,23 @@ dissect_PROTOABBREV_heur_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree /* and do the dissection */ dissect_PROTOABBREV_tcp(tvb, pinfo, tree, data); - return (TRUE); + 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, + udp_dissect_pdus(tvb, pinfo, tree, true, 5, NULL, get_PROTOABBREV_len, dissect_PROTOABBREV_pdu, data); return tvb_reported_length(tvb); } -static gboolean +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, + return (udp_dissect_pdus(tvb, pinfo, tree, true, 5, test_PROTOABBREV, get_PROTOABBREV_len, dissect_PROTOABBREV_pdu, data) != 0); } @@ -238,3 +238,7 @@ 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 index 9d3e612c2f..77596cb339 100644 --- a/doc/README.idl2wrs +++ b/doc/README.idl2wrs @@ -7,7 +7,7 @@ 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. +"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], @@ -41,25 +41,25 @@ the case with "Wireshark" (https://www.wireshark.org) How to use idl2wrs ================== -To use the idl2wrs to generate wireshark dissectors, you +To use the idl2wrs to generate Wireshark dissectors, you need the following. 1. Python must be installed - http://python.org/ + 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 +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. +1. To write the C code to stdout. idl2wrs <your_file.idl> @@ -77,7 +77,7 @@ Procedure 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. +3. To write the C code to stdout. Usage: omniidl -p ./ -b wireshark_be <your_file.idl> @@ -92,20 +92,25 @@ steps 3 or 4 instead. and that will leave you with heuristic dissection. -5. Copy the resulting C code to your wireshark src directory, edit the - following files to include the packet-test-idl.c - +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/ - edit epan/dissectors/CMakeLists.txt + 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 configure +6. Run CMake + + cmake /dir/where/wireshark/lives - ./configure (or ./autogen.sh) 7. Compile the code make + 8. Good Luck !! @@ -131,9 +136,9 @@ Notes 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), +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/ + On my Linux box, it is PYTHONPATH=/usr/lib/python1.5/ Frank Singleton. diff --git a/doc/README.packaging b/doc/README.packaging deleted file mode 100644 index 86d443af64..0000000000 --- a/doc/README.packaging +++ /dev/null @@ -1,103 +0,0 @@ -The following guidelines should be followed by anyone distributing a software -package containing Wireshark: - -1. URLs. - -1.1. Wireshark web site. - -The Wireshark web site URL is https://www.wireshark.org/ . - -1.2. Wireshark releases. - -The canonical location for every Wireshark source release is - - https://www.wireshark.org/download/src/all-versions/, e.g. - - https://www.wireshark.org/download/src/all-versions/wireshark-2.6.5.tar.xz - -If your packaging system downloads a copy of the Wireshark sources, use -this location. Don't use https://www.wireshark.org/download/src. - -1.3. Artwork. - -Logo and icon artwork can be found in the "image" directory in the -distribution. This is available online at - - https://code.wireshark.org/review/gitweb?p=wireshark.git;a=tree;f=image;hb=HEAD - -2. Licensing. - -Wireshark is released under the GNU General Public License version 2 or -newer. Make sure your package complies with this license. - -3. Privileges. - -All function calls that require elevated privileges are in dumpcap. - -WIRESHARK CONTAINS OVER TWO MILLION LINES OF SOURCE CODE. DO NOT RUN -THEM AS ROOT. - -Warnings are displayed when Wireshark and TShark are run as root. - -There are several configure-time options on non-Windows systems that -affect the privileges a normal user needs to capture traffic and list -interfaces: - - -DDUMPCAP_INSTALL_OPTION=capabilities - Install dumpcap with cap_net_admin and cap_net_raw capabilities. - Linux only. - - -DDUMPCAP_INSTALL_OPTION=suid - Install dumpcap setuid root. - -These are necessary for non-root users to be able to capture on most -systems, e.g. on Linux or FreeBSD if the user doesn't have permissions -to access /dev/bpf*. Setcap installation is preferred over setuid on -Linux. If "-DDUMPCAP_INSTALL_OPTION=capabilities" is used it will -override any setuid settings. - -The "-DENABLE_CAP" option is only useful when dumpcap is installed -setuid. If it is enabled dumpcap will try to drop any setuid privileges -it may have while retaining the CAP_NET_ADMIN and CAP_NET_RAW -capabilities. It is enabled by default, if the Linux capabilities -library (on which it depends) is found. - -Note that enabling setcap or setuid installation allows packet capture -for ALL users on your system. If this is not desired, you can restrict -dumpcap execution to a specific group or user. The following two examples -show how to restrict access using setcap and setuid respectively: - -# groupadd -g packetcapture -# chmod 750 /usr/bin/dumpcap -# chgrp packetcapture /usr/bin/dumpcap -# setcap cap_net_raw,cap_net_admin+ep /usr/bin/dumpcap - -# groupadd -g packetcapture -# chgrp packetcapture /usr/bin/dumpcap -# chmod 4750 /usr/bin/dumpcap - -4. Customization. - -Custom version information can be added by creating a file called -"version.conf" and running "make-version.pl -p". See make-version.pl for -details. If your package contains significant changes we recommend that -you use this to differentiate it from official Wireshark releases. - -4.1. Source-level version detection. - -The Git version corresponding to each release is in version.h. It's -defined as a string. If you need a numeric definition, let us know. - -5. Trademarks. - -Wireshark and the "fin" logo are registered trademarks of the Wireshark -Foundation. - -6. Spelling. - -Wireshark is spelled with a capital "W", and with everything else lower -case. E.g., "WireShark" is incorrect. - - -If you have a question not addressed here, send it to -wireshark-dev@wireshark.org. diff --git a/doc/README.plugins b/doc/README.plugins index d39d244461..190621d9ae 100644 --- a/doc/README.plugins +++ b/doc/README.plugins @@ -4,10 +4,20 @@ 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. +Plugins have three distinct binary types: + * codec: These plugins are loaded by Wireshark to implement audio codecs + * wiretap: These plugins can implement various extensions to libwiretap + * epan: These plugins implement extensions to libwireshark + +Within each type we can differentiate by the features and APIs used. There +are the following functional types: + + * codec: is its own class of functionality, described above + * dissector (epan): implements new protocol dissectors + * tap listener (epan): implements statistics and other extensions using taps + * dfunction (epan): implements new display filter functions + * epan (epan): used to implement language bindings such as Lua + * file type (wiretap): implements support for reading new capture file types 1. Dissector plugins @@ -60,17 +70,6 @@ your goal. Setting up the permanent addition is somewhat more involved. 3.1 Custom extension -Go to the plugins directory and copy the Custom.m4.example and -Custom.make.example files to files of the same name but without the ".example" -suffix. Now you have two Custom files ready for building a plugin with the -name "foo". Replace the name if you so require. - -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\${VERSION_MAJOR}.${VERSION_MINOR}\epan\foo.dll" - For CMake builds, either pass the custom plugin dir on the CMake generation step command line: @@ -86,11 +85,16 @@ 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: - configure.ac CMakeLists.txt packaging/nsis/wireshark.nsi @@ -123,13 +127,13 @@ 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 alphbetical order) to the +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\${VERSION_MAJOR}.${VERSION_MINOR}\epan\ethercat.dll" -File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\foo.dll" -File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\gryphon.dll" -File "${STAGING_DIR}\plugins\${VERSION_MAJOR}.${VERSION_MINOR}\epan\irda.dll" +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 @@ -140,12 +144,12 @@ and should not require configuration. Plugins make some aspects of development easier and some harder. -The first thing is that you'll have to run autogen.sh and configure once -more to setup your build environment. +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 -C plugins" to compile just +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 @@ -155,100 +159,91 @@ 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 +wireshark, say in $HOME/build/root and build Wireshark to install there -./configure --prefix=${HOME}/build/root && make install +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 three visible symbols: plugin_version, plugin_release and -plugin_register. Each plugin is either a libwscodecs 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); +5. Plugin registration - void plugin_register(void) {...}; - void plugin_reg_handoff(void) {...}; +5.1 Registration API common to all plugin types -You'll have to rewrite it as: +You must include the plugin API header: - 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); - } +#include <wsutil/plugins.h> -See doc/plugins.example for an example. +First declare a struct with the plugin metadata fields: -5.2 How to update an "old style" plugin (using plugin_register and - plugin_reg_handoff functions). +static struct ws_module module = { + .flags = WS_PLUGIN_DESC_DISSECTOR, + .version = "X.Y.Z", + .spdx_id = "GPL-2.0-or-later", + .home_url = "Your-URL-here", + .blurb = "Short description for the functionality", + .register_cb = &plugin_register, +}; -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, -stips the parts outlined below: +The flags field is currently only used to categorize a plugin according to its +functionality, for display purposes. A plugin can implement more than one +functionality type within each binary type, although this is rare in practice. - o Remove the following include statements: +Version is a string and conventionally uses the format major.minor.micro, +although this isn't enforced. - #include <gmodule.h> - #include "moduleinfo.h" +The spdx_id field is the SPDX license ID for your plugin. - o Removed the definition: +Home URL should be a string where users can obtain the source code +and other detailed information about the plugin. - #ifndef ENABLE_STATIC - WS_DLL_PUBLIC_DEF gchar version[] = VERSION; - #endif +The blurb is a short description of what the plugin does. - o Move relevant code from the blocks and delete these functions: +The plugin registration callback implementation is specific for each plugin +type (see the various plugins bundled with Wireshark for examples). - #ifndef ENABLE_STATIC - plugin_reg_handoff() - .... - #endif +static void +plugin_register(void) +{ + /* Code to register the dissector, tap listener, etc. */ +} - #ifndef ENABLE_STATIC - plugin_register() - .... - #endif +Finally the plugin must use one of the following macros to register itself: -This will leave a clean dissector source file without plugin specifics. +WIRESHARK_PLUGIN_REGISTER_EPAN(&module, 0) +WIRESHARK_PLUGIN_REGISTER_WIRETAP(&module, 0) +WIRESHARK_PLUGIN_REGISTER_CODEC(&module, 0) -5.3 How to update an "old style" plugin (using plugin_init function) +As the name implies each plugin binary type has a specific registration +macro (but they all have the same arguments). The macro takes a pointer to +the struct ws_module as the first argument. The second argument is +unused only by codec plugins and explained in the next section. For all +other plugin types it is ignored and should be zero. -The plugin registering has changed between 0.10.9 and 0.10.10; everyone -is encouraged to update their plugins as outlined below: +5.2 The plugin minimum API level argument - o Remove following include statements from all plugin sources: +The ABI version test for equality is the main check for compatibility for +all plugin types but additionally the codec plugin API has an extra +check called the API level. The codec API is very small and changes very +infrequently. Codecs plugins that only use the API in wsutil/codecs.h should +declare a minimum API level required. If the API needs to be changed and that +can be done in a backward-compatible manner for the ABI/API then only the +maximum API level will be increased and the minimum API level can stay the same. - #include "plugins/plugin_api.h" - #include "plugins/plugin_api_defs.h" +This means the same plugin can still be loaded successfully without +recompilation using the older API (possibly with reduced functionality). - o Remove the init function. +This is currently experimental and may change in the future or be removed +entirely. 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_PLUGINIFDEMO has to be enabled. +build option ENABLE_PLUGIN_IFDEMO has to be enabled. 6.1 Implement a plugin GUI menu @@ -259,13 +254,13 @@ 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 ad data. This pointer may be used to +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, gpointer gui_data, - gpointer user_data _U_) + menu_cb(ext_menubar_gui_type gui_type, void *gui_data, + void *user_data _U_) { ... Do something ... } @@ -275,7 +270,7 @@ 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 ); + <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", @@ -299,14 +294,14 @@ 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, gboolean force); + (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(guint32 framenr); + WS_DLL_PUBLIC void plugin_if_goto_frame(uint32_t framenr); 6.3 Implement a plugin specific toolbar @@ -335,9 +330,9 @@ To add items to the toolbar, 4 different types of elements do exist. 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 gchar *label, - const gchar *defvalue, const gchar *tooltip, gboolean capture_only, GList * value_list, - gboolean is_required, const gchar * regex, ext_toolbar_action_cb callback, gpointer user_data) + 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 @@ -358,16 +353,16 @@ In case of the toolbar type EXT_TOOLBAR_SELECTOR a value list has to be provided 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 ); + 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(gpointer toolbar_item, gpointer item_data, gpointer user_data) + 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 @@ -393,7 +388,7 @@ The parameters of the callback are defined as follows: 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, gpointer data, gboolean silent) + 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 @@ -402,16 +397,16 @@ silent defines, if the registered toolbar callback is triggered by the update or - 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, gpointer data, gboolean silent) + 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, gpointer data, gpointer value, - gboolean silent) + 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 gchar * pointer. + data and value must be char * pointer. ---------------- diff --git a/doc/README.request_response_tracking b/doc/README.request_response_tracking index d29d78836c..562009465d 100644 --- a/doc/README.request_response_tracking +++ b/doc/README.request_response_tracking @@ -27,18 +27,16 @@ The example below shows how simple this is to add to the dissector IF: The example is taken from the PANA dissector: -First we need to include the definitions for conversations and memory -management. +First we need to include the definitions for conversations. #include <epan/conversation.h> - #include <epan/wmem/wmem.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; + static int hf_pana_response_in; + static int hf_pana_response_to; + static int hf_pana_response_time; 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 @@ -50,8 +48,8 @@ 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 { - guint32 req_frame; - guint32 rep_frame; + uint32_t req_frame; + uint32_t rep_frame; nstime_t req_time; } pana_transaction_t; @@ -73,7 +71,7 @@ Finally for the meat of it, add the conversation and tracking code to the actual dissector. ... - guint32 seq_num; + uint32_t seq_num; conversation_t *conversation; pana_conv_info_t *pana_info; pana_transaction_t *pana_trans; @@ -122,7 +120,7 @@ actual dissector. } if (!pana_trans) { /* create a "fake" pana_trans structure */ - pana_trans=wmem_new(wmem_packet_scope(), pana_transaction_t); + 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; @@ -136,7 +134,7 @@ actual dissector. it = proto_tree_add_uint(pana_tree, hf_pana_response_in, tvb, 0, 0, pana_trans->rep_frame); - PROTO_ITEM_SET_GENERATED(it); + proto_item_set_generated(it); } } else { /* This is a reply */ @@ -146,11 +144,11 @@ actual dissector. it = proto_tree_add_uint(pana_tree, hf_pana_response_to, tvb, 0, 0, pana_trans->req_frame); - PROTO_ITEM_SET_GENERATED(it); + 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); + proto_item_set_generated(it); } } diff --git a/doc/README.stats_tree b/doc/README.stats_tree index cb276f3897..9d303d3833 100644 --- a/doc/README.stats_tree +++ b/doc/README.stats_tree @@ -3,9 +3,9 @@ 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 +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. +from both Wireshark and TShark. First, you should add the TAP to the dissector in question as described in README.tapping . @@ -29,8 +29,8 @@ The cleanup callback: 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.plugin for other information -regarding wireshark plugins. +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(). @@ -58,39 +58,40 @@ A small example of a very basic stats_tree plugin follows. #include <epan/dissectors/udp.h> static int st_udp_term; -static gchar* st_str_udp_term = "UDP terminations"; +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, TRUE); + 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 int 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 */ +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 guint8 str[128]; + 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); + 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 */ - g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_src),udphdr->sport); - tick_stat_node(st, str, st_udp_term, FALSE); + 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 */ - g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_dst),udphdr->dport); - tick_stat_node(st, str, st_udp_term, FALSE); + 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 gchar version[] = "0.0"; +WS_DLL_PUBLIC_DEF const char version[] = "0.0"; WS_DLL_PUBLIC_DEF void plugin_register_tap_listener(void) { @@ -112,10 +113,13 @@ the stats_tree API 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 + 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 + registers a new stats tree from a plugin with the default group REGISTER_STAT_GROUP_UNSORTED + +stats_tree_set_group(st_config, stat_group); + changes the menu statistics group for a stats tree stats_tree_parent_id_by_name( st, parent_name) returns the id of a candidate parent node given its name @@ -126,15 +130,17 @@ Node functions All the functions that operate on nodes return a parent_id -stats_tree_create_node(st, name, parent_id, with_children) +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) - with_children: TRUE if this node will have "dynamically created" children + 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, with_children); +stats_tree_create_node_by_pname(st, name, parent_name, datatype, with_children); As before but creates a node using its parent's name @@ -146,8 +152,8 @@ stats_tree_range_node_with_pname(st, name, parent_name, ...) 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) +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 @@ -159,19 +165,18 @@ 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) +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) +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) +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) +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 @@ -179,23 +184,27 @@ 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(st,name,parent_id,with_children,value) +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 +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 is used the same way as tick_stat_node with the +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 as this will lead to incorrect results for the +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 @@ -204,11 +213,25 @@ 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. + 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 :) + 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 diff --git a/doc/README.tapping b/doc/README.tapping index 5c62a475f0..4fcb6389e4 100644 --- a/doc/README.tapping +++ b/doc/README.tapping @@ -1,11 +1,11 @@ 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 are required. +internals is required. As examples on how to use the tap system see the implementation of -tap-rpcstat.c (tshark version) -ui/qt/rpc_service_response_time_dialog.cpp (wireshark version) +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 @@ -18,11 +18,8 @@ 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 @@ -33,7 +30,7 @@ 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 "tap.h"' (preceded by packet.h) to +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;' @@ -46,7 +43,7 @@ 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 are no useful extra data to provide just specify NULL. For +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. @@ -55,27 +52,27 @@ need. TAP LISTENER ============ -(see tap-rpcstat.c as an example) +(see tap-rpcprogs.c as an example) Interfacing your application is not that much harder either. -Only 3 callbacks and two functions. - +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, - guint flags, + unsigned flags, void (*reset)(void *tapdata), - gboolean (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data), - void (*draw)(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)); -remove_tap_listener(void *tapdata); +This function is used to register an instance of a tap application +to the tap system. +remove_tap_listener(void *tapdata); -remove_tap_listener(void *tapdata) This function is used to deregister and stop a tap listener. -register_tap_listener() is used to register an instance of a tap application -to the tap system. +The parameters have the following meanings: *tapname is the name of the tap we want to listen to. I.e. the name used in @@ -87,7 +84,7 @@ 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_malloc() and use that pointer. +g_new() and use that pointer. (tap-rpcstat.c use this technique to allow multiple simultaneous instances) *fstring @@ -126,6 +123,11 @@ is a set of flags for the tap listener. The flags that can be set are: 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) @@ -134,14 +136,17 @@ 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. -gboolean (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data) +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 were a filter). +it has passed the filter (if there was a filter). The *data structure type is specific to each tap. -This function returns an gboolean and it should return - TRUE, if the data in the packet caused state to be updated +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) - FALSE, if we don't need to redraw the window. + 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. @@ -156,12 +161,15 @@ 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 three callbacks: +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. @@ -209,19 +217,19 @@ 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 both (*draw) and (*reset) +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 : - gboolean packet(void *tapdata,...) { + tap_packet_status packet(void *tapdata,...) { ... system("mail ..."); - return FALSE; + return TAP_PACKET_DONT_REDRAW; } - register_tap_listener("tcp", struct, "tcp.port==57", NULL, packet, NULL); + 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 @@ -232,8 +240,5 @@ Well, try this : Let struct contain a command line and make (*packet) execute it? The possibilities are rather large. - - -See tap-rpcstat.c for an example 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 index 1d2f0438a5..88ff1a8c97 100644 --- a/doc/README.vagrant +++ b/doc/README.vagrant @@ -2,9 +2,9 @@ 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 Ubuntu development -environment in a virtual machine, including all necessary compilers, dependent -libraries, and tools like valgrind. +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, @@ -29,48 +29,58 @@ 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` followed by -`vagrant provision`. +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 Ubuntu VM image (what they call a box) from -HashiCorp's Atlas box catalog. Once the box is downloaded an Unbuntu VM will -be instantiated and powered-on. +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 VM. +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 run two bash based -provisioning scripts, vagrant_provision.sh and vagrant_build.sh. These -provisoning scripts are executed on the Ubuntu VM system and not on the host -system. +Vagrantfile. Wireshark's Vagrantfile is configured to provision the machine +and build the project using vagrant_build.sh. -The vagrant_provision.sh script initiates several apt-get tasks to get the -Ubuntu VM reasonably up to date. The vagrant_build.sh script sets up a cmake +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` from the wireshark source directory will log you into -Ubuntu VM as the userid vagrant. +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 /vagrant. -Any changes made in the VM's /vagrant folder are reflected in the host system's -Wireshark source folder and visa-versa. +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 Ubuntu VM's /vagrant folder). +tree (the VM's ~/wireshark folder). The various Wireshark applications can be run from the ~/build folder of the -Ubuntu VM with commands such as `./run/wireshark`, `./run/tshark`, etc. +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/. -To run the Wireshark GUI you will typically need an X server. 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`. -The Ubuntu VM can be shutdown or suspended from the host system with the -commands `vagrant halt` and `vagrant suspend` repectively. In either case the -Ubuntu 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 index 79ec946df3..8473a23b5e 100644 --- a/doc/README.wmem +++ b/doc/README.wmem @@ -5,9 +5,9 @@ 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 epan/wmem/ and provides memory pools and functions that make +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). +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. @@ -19,7 +19,7 @@ https://www.wireshark.org/lists/wireshark-dev/201210/msg00178.html 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/wmem.h) and optionally +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). @@ -53,19 +53,20 @@ changed without warning. 2.2 Wireshark Global Pools -Dissectors that include the wmem header file will have three pools available -to them automatically: wmem_packet_scope(), wmem_file_scope() and -wmem_epan_scope(); +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 packet pool is scoped to the dissection of each packet, meaning that any +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 packet - pool when there isn't a packet being dissected) will throw an assertion. - See the comment in epan/wmem/wmem_scopes.c for details. +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 @@ -112,6 +113,10 @@ wmem_list.h 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). @@ -169,7 +174,7 @@ To create a pool, include the regular wmem header and call the wmem_allocator_new() function with the appropriate type value. For example: - #include "wmem/wmem.h" + #include <wsutil/wmem/wmem.h> wmem_allocator_t *myPool; myPool = wmem_allocator_new(WMEM_ALLOCATOR_SIMPLE); @@ -185,7 +190,7 @@ document. 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 "wmem/wmem.h" + #include <wsutil/wmem/wmem.h> wmem_allocator_t *myPool; @@ -205,7 +210,7 @@ allowing it to be reused later. Depending on the type of allocator, doing this 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 "wmem/wmem.h" + #include <wsutil/wmem/wmem.h> wmem_allocator_t *myPool; @@ -316,7 +321,7 @@ pointer is stored internally with the data structure, and subsequent calls 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 three valid values: +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 diff --git a/doc/README.wslua b/doc/README.wslua index 1bc10aead8..c26dcf9302 100644 --- a/doc/README.wslua +++ b/doc/README.wslua @@ -29,39 +29,25 @@ 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 Perl script called 'make- -wsluarm.pl', 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 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 Perl script called 'make-reg.pl' generates the C-files +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 Perl script auto-generates is +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 perl scripts above are given the C-source files to search through +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. -Another Perl script is used as well, called 'make-init-lua.pl', which -generates the init.lua script. A large part of it deals with exposing #define -values into the Lua global table, or sub-tables. Unfortunately not all of -them are put in sub-tables, which means the global Lua table is quite polluted -now. If you add new ones in here, please think of putting them in a subtable, -as they are for wtap, ftypes, and base. For example, there are several put in -as 'PI_' prefixed names, such as 'PI_SEVERITY_MASK = 15728640'. The fact they -all have a common 'PI_' prefix should be an indicator they can be put in a -table named PI, or PacketInfo. Just because C-code doesn't have namespaces, -doesn't mean Lua can't. This has now been fixed, and the PI_* names are now in -two separate subtables of a table named 'expert', as 'expert.group' and -'expert.severity' subtables. Follow that model in 'make-init-lua.pl'. - - 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. @@ -72,7 +58,7 @@ 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 Perl scripts which +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. @@ -81,7 +67,7 @@ followed. Documenting things for the API docs: As explained previously, the API documentation is auto-generated from a -Perl script called 'make-wsluarm.pl', which searches C-files for the known +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 @@ -92,10 +78,10 @@ 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.pl script supports +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.pl, but are repeated here as well: +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 @@ -153,7 +139,7 @@ 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.pl Perl script will search +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 @@ -190,7 +176,7 @@ 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.pl perl script creates 'taps_wslua.c'). The +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 @@ -258,15 +244,14 @@ 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.pl. That Perl -script reads from a file called 'taps', which identifies every struct name -(and associated enum name) that should be exposed as a tap type. The Perl +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.pl has in its Perl %types and %comments associative -arrays. +type that make-taps.py has in its Python "types" and "comments" dictionaries. Note on Lua versions: @@ -293,7 +278,7 @@ 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.pl +'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 @@ -365,7 +350,7 @@ Example: 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.pl does not treat this +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 @@ -380,7 +365,7 @@ 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 gchar* name = luaL_checkstring(L,WSLUA_ARG_Dissector_get_NAME); + const char* name = luaL_checkstring(L,WSLUA_ARG_Dissector_get_NAME); Dissector d; if (!name) @@ -425,13 +410,13 @@ Example: WSLUA_METAMETHOD NSTime__eq(lua_State* L) { /* Compares two NSTimes */ NSTime time1 = checkNSTime(L,1); NSTime time2 = checkNSTime(L,2); - gboolean result = FALSE; + 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; + result = true; lua_pushboolean(L,result); @@ -443,7 +428,7 @@ 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.pl Perl script will generate API documentation with +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 @@ -459,7 +444,7 @@ 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.pl Perl script will generate API documentation with +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. diff --git a/doc/README.xml-output b/doc/README.xml-output index b3011ae24c..1ab5f3f9c6 100644 --- a/doc/README.xml-output +++ b/doc/README.xml-output @@ -6,17 +6,14 @@ 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 +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 any more, but a copy can be found at: - -http://gd.tuwien.ac.at/.vhost/analyzer.polito.it/docs/dissectors/PDMLSpec.htm - -or at the internet archive: +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 @@ -24,25 +21,27 @@ 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. Some day it -may be added to tshark so that "-Tpsml" would produce PSML. - -One wonders if the "-T" option should read "-Txml" instead of "-Tpdml" -(and in the future, "-Tpsml"), but if tshark was required to produce -another XML-based format of its protocol dissection, then "-Txml" would -be ambiguous. +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 +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 +"<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. @@ -96,15 +95,27 @@ The "<field>" tag 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 usually resided 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: +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 | @@ -143,8 +154,24 @@ In PDML, the "Data" protocol would become another field under HTTP: </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 @@ -223,4 +250,4 @@ number of simultaneous chat sessions. pdml2html.xsl ============= pdml2html.xsl is a XSLT file to convert PDML files into HTML. -See https://wiki.wireshark.org/PDML for more details. +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 0000000000..39e199255b --- /dev/null +++ b/doc/androiddump.adoc @@ -0,0 +1,256 @@ +include::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/androiddump.pod b/doc/androiddump.pod deleted file mode 100644 index 4606d31ee2..0000000000 --- a/doc/androiddump.pod +++ /dev/null @@ -1,255 +0,0 @@ - -=head1 NAME - -androiddump - Provide interfaces to capture from Android devices - -=head1 SYNOPSIS - -B<androiddump> -S<[ B<--help> ]> -S<[ B<--version> ]> -S<[ B<--extcap-version> ]> -S<[ B<--debug> ]> -S<[ B<--extcap-interfaces> ]> -S<[ B<--extcap-dlts> ]> -S<[ B<--extcap-interface>=E<lt>interfaceE<gt> ]> -S<[ B<--extcap-config> ]> -S<[ B<--capture> ]> -S<[ B<--fifo>=E<lt>path to file or pipeE<gt> ]> -S<[ B<--adb-server-ip>=E<lt>IP addressE<gt> ]> -S<[ B<--adb-server-tcp-port>=E<lt>TCP portE<gt> ]> -S<[ B<--logcat-text>=E<lt>TRUE or FALSEE<gt> ]> -S<[ B<--bt-server-tcp-port>=E<lt>TCP portE<gt> ]> -S<[ B<--bt-forward-socket>=E<lt>TRUE or FALSEE<gt> ]> -S<[ B<--bt-local-ip>=E<lt>IP addressE<gt> ]> -S<[ B<--bt-local-tcp-port>=E<lt>TCP portE<gt> ]> - -B<androiddump> -S< B<--extcap-interfaces> > -S<[ B<--adb-server-ip>=E<lt>IP addressE<gt> ]> -S<[ B<--adb-server-tcp-port>=E<lt>TCP portE<gt> ]> - -B<androiddump> -S< B<--extcap-interface>=E<lt>interfaceE<gt> > -S<[ B<--extcap-dlts> ]> - -B<androiddump> -S< B<--extcap-interface>=E<lt>interfaceE<gt> > -S<[ B<--extcap-config> ]> - -B<androiddump> -S< B<--extcap-interface>=E<lt>interfaceE<gt> > -S< B<--fifo>=E<lt>path to file or pipeE<gt> > -S< B<--capture> > - -=head1 DESCRIPTION - -B<Androiddump> is a extcap tool that provide interfaces to capture from -Android device. There is only two requirements: - -1. You must have Android SDK and add it 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 Android devices. Some Android devices requires -on-screen authentication. - - -Supported interfaces: - -=over 4 - -=item 1. Logcat Main (binary [<=Jelly Bean] or text) - -=item 2. Logcat System (binary [<=Jelly Bean] or text) - -=item 3. Logcat Events (binary [<=Jelly Bean] or text) - -=item 4. Logcat Radio (binary [<=Jelly Bean] or text) - -=item 5. Logcat Crash (text; from Lollipop) - -=item 6. Bluetooth Hcidump [<=Jelly Bean] - -=item 7. Bluetooth Bluedroid External Parser [Kitkat] - -=item 8. Bluetooth BtsnoopNet [>=Lollipop] - -=item 9. WiFi tcpdump [need tcpdump on phone] - -=back - -Please note that it will work also for FirefoxOS or other Android-based stuffs. - -=head1 OPTIONS - -=over 4 - -=item --help - -Print program arguments. - -=item --version - -Print program version. - -=item --extcap-version - -Print extcapized version. - -=item --debug - -Print additional messages. - -=item --extcap-interfaces - -List available interfaces. - -=item --extcap-interface=E<lt>interfaceE<gt> - -Use specified interfaces. - -=item --extcap-dlts - -List DLTs of specified interface. - -=item --extcap-config - -List configuration options of specified interface. - -=item --capture - -Start capturing from specified interface save saved it in place specified by --fifo. - -=item --fifo=E<lt>path to file or pipeE<gt> - -Save captured packet to file or send it through pipe. - -=item --adb-server-ip=E<lt>IP addressE<gt> - -Use other then default (127.0.0.1) ADB daemon's IP address. - -=item --adb-server-tcp-port=E<lt>TCP portE<gt> - -Use other then default (5037) ADB daemon's TCP port. - -=item --logcat-text=E<lt>TRUE or FALSEE<gt> - -If TRUE then use text logcat rather then binary. This option has effect only on -Logcat interfaces. This have no effect from Lollipop where is no binary Logcat -available. - -Defaults to FALSE. - -=item --bt-server-tcp-port=E<lt>TCP portE<gt> - -Use other then default Bluetooth server TCP port on Android side. -On Lollipop defaults is 8872, earlier 4330. - -=item --bt-forward-socket=E<lt>TRUE or FALSEE<gt> - -If TRUE then socket from Android side is forwarded to host side. - -Defaults to FALSE. - -=item --bt-local-ip=E<lt>IP addressE<gt> - -Use other then default (127.0.0.1) IP address on host side for forwarded socket. - -=item --bt-local-tcp-port=E<lt>TCP portE<gt> - -Specify port to be used on host side for forwarded socket. - -=back - -=head1 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-wifi-tcpdump (Android WiFi) - 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 application. - -=head1 SEE ALSO - -wireshark(1), tshark(1), dumpcap(1), extcap(4) - -=head1 NOTES - -B<Androiddump> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - -------- ------ - Michal Labedzki <michal.labedzki[AT]tieto.com> - - - Contributors - ------------ - Roland Knall <rknall[AT]gmail.com> diff --git a/doc/asn2deb.adoc b/doc/asn2deb.adoc new file mode 100644 index 0000000000..c04e23badc --- /dev/null +++ b/doc/asn2deb.adoc @@ -0,0 +1,84 @@ +include::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/asn2deb.pod b/doc/asn2deb.pod deleted file mode 100644 index 0d88a95849..0000000000 --- a/doc/asn2deb.pod +++ /dev/null @@ -1,88 +0,0 @@ - -=head1 NAME - -asn2deb - Create a Debian package for BER monitoring from ASN.1 - -=head1 SYNOPSIS - -B<asn2deb> -S<[ B<-a> E<lt>ASN.1 fileE<gt> ]> -S<[ B<--asn>=E<lt>ASN.1 fileE<gt> ]> -S<[ B<-d> E<lt>optsE<gt> ]> -S<[ B<--dbopts>=E<lt>optsE<gt> ]> -S<[ B<-e> E<lt>addressE<gt> ]> -S<[ B<--email>=E<lt>addressE<gt> ]> -S<[ B<-h> ]> -S<[ B<--help> ]> -S<[ B<-n> E<lt>nameE<gt> ]> -S<[ B<--name>=E<lt>nameE<gt> ]> -S<[ B<-p> ]> -S<[ B<--preserve> ]> -S< [B<-v> ]> -S<[ B<--version> ]> - -=head1 DESCRIPTION - -This manual page documents briefly the B<asn2deb> command. B<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 analyser. -The type table is generated by the ASN.1 compiler B<snacc>. - -=head1 OPTIONS - -=over 4 - -=item -a E<lt>ASN.1 fileE<gt> --asn=E<lt>ASN.1 fileE<gt> - -ASN.1 file to use (mandatory). - -=item -d E<lt>optsE<gt> --dbopts=E<lt>optsE<gt> - -options for dpkg-buildpackage. - -=item -e E<lt>addressE<gt> --email=E<lt>addressE<gt> - -use e-mail address. - -=item -h --help - -print help and exit. - -=item -n E<lt>nameE<gt> --name=E<lt>nameE<gt> - -use user name. - -=item -p --preserve - -do not overwrite files. - -=item -v --version - -print version and exit. - -=back - -=head1 EXAMPLES - -/usr/bin/asn2deb -e me@foo.net -a bar.asn1 \-n "My Name" -d "-rfakeroot -uc -us"-d "-rfakeroot -uc -us" - -=head1 SEE ALSO - -A lot of tools are used, which you have to B<apt-get install>: wireshark-dev, python, cdbs, autotools-dev, debhelper, dpkg-dev, -snacc. - -=head1 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. - -=head1 AUTHOR - -B<W. Borgert> Author. - -=head1 COPYRIGHT - -Copyright (C) 2003, 2005 W. Borger diff --git a/doc/attributes.adoc b/doc/attributes.adoc new file mode 100644 index 0000000000..ded54845fe --- /dev/null +++ b/doc/attributes.adoc @@ -0,0 +1,107 @@ +// Common attributes + +:wireshark-version: 4.3.0 +:logray-version: 0.9.0 + +// Required for btn, kbd:, and menu: macros. +:experimental: + +// We want footers (which include page numbers) in our PDF output but +// not elsewhere, particularly in our man pages. +// We could use the "reproducible" attribute here, but it generates an +// empty black box. +ifndef::backend-pdf[] +:nofooter: +endif::[] + +// Create PA4 (210 × 280mm) pages: https://en.wikipedia.org/wiki/Paper_size#PA4_or_L4 +// This is the approximate intersection of A4 (210 × 297mm) and U.S. Letter +// (216 × 279mm). +:pdf-page-size: 210mm x 280mm + +// Include glyphs for up/down arrows +:pdf-theme: default-with-fallback-font + +// +// URLs +// + +// Wireshark top level URLs (sites) +:wireshark-main-url: https://www.wireshark.org/ +:wireshark-gitlab-project-url: https://gitlab.com/wireshark/wireshark +:wireshark-qa-url: https://ask.wireshark.org/ +:wireshark-foundation-url: https://wiresharkfoundation.org/ +:sharkfest-url: https://sharkfest.wireshark.org/ + +// Wireshark secondary URLs (pages) +:wireshark-bugs-url: {wireshark-gitlab-project-url}/-/issues +:wireshark-code-review-url: {wireshark-gitlab-project-url}/-/merge_requests +:wireshark-wiki-url: {wireshark-gitlab-project-url}/-/wikis/ +:wireshark-authors-url: {wireshark-main-url}about.html#authors +:wireshark-code-browse-url: {wireshark-gitlab-project-url}/-/tree/master +:wireshark-code-file-url: {wireshark-gitlab-project-url}/-/blob/master/ +:wireshark-commits-url: {wireshark-gitlab-project-url}/-/commits/master +:wireshark-merge-request-url: {wireshark-gitlab-project-url}/-/merge_requests +:wireshark-developers-guide-url: {wireshark-main-url}docs/wsdg_html_chunked/ +:wireshark-display-filter-reference-url: {wireshark-main-url}docs/dfref/ +:wireshark-download-url: {wireshark-main-url}download.html +:wireshark-faq-url: {wireshark-main-url}faq.html +:wireshark-git-anonhttp-url: https://gitlab.com/wireshark/wireshark.git +:wireshark-git-ssh-url: \git@gitlab.com:wireshark/wireshark.git +:wireshark-mailing-lists-url: {wireshark-main-url}lists/ +:wireshark-man-page-url: {wireshark-main-url}docs/man-pages/ +:wireshark-snapshots-url: {wireshark-main-url}download/automated/src/ +:wireshark-users-guide-url: {wireshark-main-url}docs/wsug_html_chunked/ +:wireshark-wiki-moin-import-url: {wireshark-wiki-url}uploads/__moin_import__/attachments/ + +// External URLs +:tcpdump-main-url: https://www.tcpdump.org/ +:pcap-filter-man-page-url: {tcpdump-main-url}manpages/pcap-filter.7.html +:tcpdump-man-page-url: {tcpdump-main-url}manpages/tcpdump.1.html + +:npcap-main-url: https://npcap.com/ +:npcap-development-url: https://github.com/nmap/npcap +:npcap-license-url: https://raw.githubusercontent.com/nmap/npcap/master/LICENSE +:vcpkg-main-url: https://github.com/Microsoft/vcpkg/ + +:sysfs-main-url: http://linux-diag.sourceforge.net/Sysfsutils.html +:wikipedia-main-url: https://en.wikipedia.org/wiki/ +:pcre2pattern-url: https://www.pcre.org/current/doc/html/pcre2pattern.html + +:greenwichmeantime-main-url: https://wwp.greenwichmeantime.com/ +:timeanddate-main-url: https://www.timeanddate.com/worldclock/ +:ntp-main-url: http://www.ntp.org/ + +:gplv2-url: https://www.gnu.org/licenses/gpl-2.0.html +:spdx-license-url: https://spdx.org/licenses/ + +// Email addresses +:at-separator: [AT] +:wireshark-dev-list-email: wireshark-dev{at-separator}wireshark.org +:wsdg-author-email: ulf.lamping{at-separator}web.de +:wsdg-author-email2: graham.bloice{at-separator}trihedral.com + +:wsug-author-email: ulf.lamping{at-separator}web.de +:wsug-author-email2: rsharpe{at-separator}ns.aus.com +:wsug-author-email3: hagbard{at-separator}physics.rutgers.edu +:wsug-author-email4: luis{at-separator}ontanon.org + +// +// Image formatting +// + +// "scaledwidth" only applies to PDF output +:pdf-scaledwidth: scaledwidth="85%" +:screenshot-attrs: scaledwidth="85%" +:medium-screenshot-attrs: scaledwidth="60%" +:small-screenshot-attrs: scaledwidth="35%" +:related-attrs: height=18 +// XXX height=22 results in content-height="22px" in the .fo file. Not sure +// how to make scaledwidth take precedence. +:statusbar-attrs: scaledwidth="85%",height=22 + +:multiplication: × +:underscore: _ +:cmd: ⌘ + +:missing: Not yet written. If you would like to fix this, see https://gitlab.com/wireshark/wireshark/-/wikis/Development/SubmittingPatches. diff --git a/doc/capinfos.pod b/doc/capinfos.adoc index 237ba5b37a..848013a11b 100644 --- a/doc/capinfos.pod +++ b/doc/capinfos.adoc @@ -1,53 +1,72 @@ +include::attributes.adoc[] += capinfos(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{stylesheet} -=head1 NAME +== NAME capinfos - Prints information about capture files -=head1 SYNOPSIS - -B<capinfos> -S<[ B<-a> ]> -S<[ B<-A> ]> -S<[ B<-b> ]> -S<[ B<-B> ]> -S<[ B<-c> ]> -S<[ B<-C> ]> -S<[ B<-d> ]> -S<[ B<-e> ]> -S<[ B<-E> ]> -S<[ B<-F> ]> -S<[ B<-h> ]> -S<[ B<-H> ]> -S<[ B<-i> ]> -S<[ B<-I> ]> -S<[ B<-k> ]> -S<[ B<-K> ]> -S<[ B<-l> ]> -S<[ B<-L> ]> -S<[ B<-m> ]> -S<[ B<-M> ]> -S<[ B<-N> ]> -S<[ B<-o> ]> -S<[ B<-q> ]> -S<[ B<-Q> ]> -S<[ B<-r> ]> -S<[ B<-R> ]> -S<[ B<-s> ]> -S<[ B<-S> ]> -S<[ B<-t> ]> -S<[ B<-T> ]> -S<[ B<-u> ]> -S<[ B<-v> ]> -S<[ B<-x> ]> -S<[ B<-y> ]> -S<[ B<-z> ]> -E<lt>I<infile>E<gt> -I<...> - -=head1 DESCRIPTION - -B<Capinfos> is a program that reads one or more capture files and -returns some or all available statistics (infos) of each E<lt>I<infile>E<gt> +== 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 @@ -57,41 +76,38 @@ 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, -B<Capinfos> will report all statistics available in "long" format. +*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. -B<Capinfos> is able to detect and read the same capture files that are -supported by B<Wireshark>. +*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 compression will be automatically detected. -Near the beginning of the DESCRIPTION section of wireshark(1) or -L<https://www.wireshark.org/docs/man-pages/wireshark.html> -is a detailed description of the way B<Wireshark> handles this, which is -the same way B<Capinfos> handles this. +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. -=head1 OPTIONS +== OPTIONS -=over 4 - -=item -a - -Displays the start time of the capture. B<Capinfos> considers +-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, -B<Capinfos> detects this. - -=item -A +*Capinfos* detects this. -Generate all infos. By default capinfos will display +-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. -=item -b - +-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 @@ -102,9 +118,9 @@ 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. +-- -=item -B - +-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 @@ -112,123 +128,128 @@ separated (delimited) from one another with a single ASCII TAB character. The TAB character is the default delimiter when -T style report is enabled. -=item -c - +-c:: Displays the number of packets in the capture file. -=item -C - +-C:: ++ +-- Cancel processing any additional files if and -when capinfos should fail to open an input file. -By default capinfos will attempt to open each and -every file name argument. +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 regardless -of whether the -C option is specified or not. -Upon exit, capinfos will return an error status +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. +-- -=item -d - +-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), -B<Capinfos> will consider the packet to have been 1514 bytes. +*Capinfos* will consider the packet to have been 1514 bytes. -=item -e +-D:: +Displays a count of the number of decryption secrets in the file. This information +is not available in table format. -Displays the end time of the capture. B<Capinfos> considers +-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, -B<Capinfos> detects this. - -=item -E +*Capinfos* detects this. +-E:: Displays the per-file encapsulation of the capture file. -=item -F - +-F:: Displays additional capture file information. -=item -h - -Prints the help listing and exits. - -=item -H +-h|--help:: +Print the version number and options and exit. -Displays the SHA256, RIPEMD160, and SHA1 hashes for the file. +-H:: +Displays the SHA256 and SHA1 hashes for the file. SHA1 output may be removed in the future. -=item -i - +-i:: Displays the average data rate, in bits/sec -=item -I - +-I:: Displays detailed capture file interface information. This information is not available in table format. -=item -k - +-k:: Displays the capture comment. For pcapng files, this is the comment from the section header block. -=item -K - +-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. +making it harder for a human or machine to easily parse the *Capinfos* output. Excluding capture comments can aid in post-processing of output. -=item -l - +-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. -=item -L - -Generate long report. Capinfos can generate two +-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. -=item -m - +-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. -=item -M - -Print raw (machine readable) numeric values in long reports. -By default capinfos prints human-readable values with SI -suffixes. Table reports (-T) always print raw values. +-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. -=item -N +-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 B<NOT> quoted. - -=item -o +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. -=item -q +-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 @@ -237,8 +258,7 @@ characters. This option (when used with the -m option) is useful for generating one type of CSV style file report. -=item -Q - +-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 @@ -247,70 +267,59 @@ characters. This option (when used with the -m option) is useful for generating the most common type of CSV style file report. -=item -r - +-r:: Do not generate header record. This option is only useful when generating a table style report (-T). -If this option is specified then B<no> header record will be +If this option is specified then *no* header record will be generated within the table report. -=item -R - +-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. -=item -s - +-s:: Displays the size of the file, in bytes. This reports the size of the capture file itself. -=item -S - +-S:: Display the start and end times as seconds since January -1, 1970. Handy for synchronizing dumps using B<editcap -t>. - -=item -t +1, 1970. Handy for synchronizing dumps using *editcap -t*. +-t:: Displays the capture type of the capture file. -=item -T - +-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 +database. *Capinfos* can build a tab delimited text file (the default) or several variations on Comma-separated values (CSV) files. -=item -u - +-u:: Displays the capture duration, in seconds. This is the difference in time between the earliest packet seen and latest packet seen. -=item -v - -Displays the tool's version and exits. - -=item -x +-v|--version:: +Print the full version information and exit. +-x:: Displays the average packet rate, in packets/sec -=item -y - +-y:: Displays the average data rate, in bytes/sec -=item -z - +-z:: Displays the average packet size, in bytes -=back +include::diagnostic-options.adoc[] -=head1 EXAMPLES +== EXAMPLES -To see a description of the capinfos options use: +To see a description of the options use: capinfos -h @@ -333,7 +342,6 @@ 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: @@ -342,7 +350,7 @@ count for all the pcap files in the current directory use: or - capinfos -TtEs *.pcap + capinfos -TtEc *.pcap Note: The ability to use of filename globbing characters are a feature of *nix style command shells. @@ -356,27 +364,27 @@ a text file called mycaptures.csv use: The resulting mycaptures.csv file can be easily imported into spreadsheet applications. -=head1 SEE ALSO - -pcap(3), wireshark(1), mergecap(1), editcap(1), tshark(1), -dumpcap(1), pcap-filter(7) or tcpdump(8) +== SEE ALSO -=head1 NOTES +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) -B<Capinfos> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. +== NOTES -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. +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. -=head1 AUTHORS +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. - Original Author - -------- ------ - Ian Schorr <ian[AT]ianschorr.com> +== AUTHORS +.Original Author +[%hardbreaks] +Ian Schorr <ian[AT]ianschorr.com> - Contributors - ------------ - Gerald Combs <gerald[AT]wireshark.org> - Jim Young <jyoung[AT]gsu.edu> +.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 0000000000..f8c8e985b7 --- /dev/null +++ b/doc/captype.adoc @@ -0,0 +1,73 @@ +include::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/captype.pod b/doc/captype.pod deleted file mode 100644 index d5ea7cd0bd..0000000000 --- a/doc/captype.pod +++ /dev/null @@ -1,49 +0,0 @@ - -=head1 NAME - -captype - Prints the types of capture files - -=head1 SYNOPSIS - -B<capinfos> -E<lt>I<infile>E<gt> -I<...> - -=head1 DESCRIPTION - -B<Captypes> is a program that opens one or more capture files and -prints the capture file type of each E<lt>I<infile>E<gt>. - -B<Capinfos> is able to detect and read the same capture files that are -supported by B<Wireshark>. -The input files don't need a specific filename extension; the file -format and an optional gzip compression will be automatically detected. -Near the beginning of the DESCRIPTION section of wireshark(1) or -L<https://www.wireshark.org/docs/man-pages/wireshark.html> -is a detailed description of the way B<Wireshark> handles this, which is -the same way B<Capinfos> handles this. - -=head1 SEE ALSO - -pcap(3), wireshark(1), mergecap(1), editcap(1), tshark(1), -dumpcap(1), capinfos(1), pcap-filter(7) or tcpdump(8) - -=head1 NOTES - -B<Captype> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - -------- ------ - Ian Schorr <ian[AT]ianschorr.com> - - - Contributors - ------------ - 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 0000000000..4a09c10f1d --- /dev/null +++ b/doc/ciscodump.adoc @@ -0,0 +1,324 @@ +include::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/ciscodump.pod b/doc/ciscodump.pod deleted file mode 100644 index f8fd1c2108..0000000000 --- a/doc/ciscodump.pod +++ /dev/null @@ -1,231 +0,0 @@ - -=head1 NAME - -ciscodump - Provide interfaces to capture from a remote Cisco router through SSH. - -=head1 SYNOPSIS - -B<ciscodump> -S<[ B<--help> ]> -S<[ B<--version> ]> -S<[ B<--extcap-interfaces> ]> -S<[ B<--extcap-dlts> ]> -S<[ B<--extcap-interface>=E<lt>interfaceE<gt> ]> -S<[ B<--extcap-config> ]> -S<[ B<--extcap-capture-filter>=E<lt>capture filterE<gt> ]> -S<[ B<--capture> ]> -S<[ B<--fifo>=E<lt>path to file or pipeE<gt> ]> -S<[ B<--remote-host>=E<lt>IP addressE<gt> ]> -S<[ B<--remote-port>=E<lt>TCP portE<gt> ]> -S<[ B<--remote-username>=E<lt>usernameE<gt> ]> -S<[ B<--remote-password>=E<lt>passwordE<gt> ]> -S<[ B<--remote-filter>=E<lt>filter<gt> ]> -S<[ B<--sshkey>=E<lt>public key path<gt> ]> -S<[ B<--remote-interface>=E<lt>interfaceE<gt> ]> - - -B<ciscodump> -S<B<--extcap-interfaces>> - -B<ciscodump> -S<B<--extcap-interface>=E<lt>interfaceE<gt>> -S<B<--extcap-dlts>> - -B<ciscodump> -S<B<--extcap-interface>=E<lt>interfaceE<gt>> -S<B<--extcap-config>> - -B<ciscodump> -S<B<--extcap-interface>=E<lt>interfaceE<gt>> -S<B<--fifo>=E<lt>path to file or pipeE<gt>> -S<B<--capture>> -S<B<--remote-host=remoterouter>> -S<B<--remote-port=22>> -S<B<--remote-username=user>> -S<B<--remote-interface>=E<lt>the router interfaceE<gt>> - -=head1 DESCRIPTION - -B<ciscodump> is an extcap tool that relys on Cisco EPC to allow a user to run a remote capture -on a Cisco router in a SSH connection. The minimum IOS version supporting this feature is 12.4(20)T. More details can be -found here: -http://www.cisco.com/c/en/us/products/collateral/ios-nx-os-software/ios-embedded-packet-capture/datasheet_c78-502727.html - -Supported interfaces: - -=over 4 - -=item 1. cisco - -=back - -=head1 OPTIONS - -=over 4 - -=item --help - -Print program arguments. - -=item --version - -Print program version. - -=item --extcap-interfaces - -List available interfaces. - -=item --extcap-interface=E<lt>interfaceE<gt> - -Use specified interfaces. - -=item --extcap-dlts - -List DLTs of specified interface. - -=item --extcap-config - -List configuration options of specified interface. - -=item --capture - -Start capturing from specified interface and save it in place specified by --fifo. - -=item --fifo=E<lt>path to file or pipeE<gt> - -Save captured packet to file or send it through pipe. - -=item --remote-host=E<lt>remote hostE<gt> - -The address of the remote host for capture. - -=item --remote-port=E<lt>remote portE<gt> - -The SSH port of the remote host. - -=item --remote-username=E<lt>usernameE<gt> - -The username for ssh authentication. - -=item --remote-password=E<lt>passwordE<gt> - -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. - -=item --remote-filter=E<lt>filterE<gt> - -The remote filter on the router. This is a capture filter that follows the Cisco IOS standards (http://www.cisco.com/c/en/us/support/docs/ip/access-lists/26448-ACLsamples.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: - - 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) - -=item --sshkey=E<lt>SSH private key pathE<gt> - -The path to a private key for authentication. - -=item --remote-interface=E<lt>remote interfaceE<gt> - -The remote network interface to capture from. - -=item --extcap-capture-filter=E<lt>capture filterE<gt> - -Unused (compatibility only). - -=back - -=head1 EXAMPLES - -To see program arguments: - - ciscodump --help - -To see program version: - - ciscodump --version - -To see interfaces: - - ciscodump --extcap-interfaces - -Only one interface (cisco) is supported. - - Output: - interface {value=cisco}{display=SSH remote capture} - -To see interface DLTs: - - ciscodump --extcap-interface=cisco --extcap-dlts - - Output: - dlt {number=147}{name=cisco}{display=Remote capture dependent DLT} - -To see interface configuration options: - - ciscodump --extcap-interface=cisco --extcap-config - - Output: - ciscodump --extcap-interface=cisco --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} - 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} - 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} - arg {number=3}{call=--remote-password}{display=Remote SSH server password}{type=string} - {tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.} - 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} - arg {number=5}{call--sshkey-passphrase}{display=SSH key passphrase} - {type=string}{tooltip=Passphrase to unlock the SSH private key} - arg {number=6}{call=--remote-interface}{display=Remote interface}{type=string} - {required=true}{tooltip=The remote network interface used for capture} - arg {number=7}{call=--remote-filter}{display=Remote capture filter}{type=string} - {default=(null)}{tooltip=The remote capture filter} - arg {number=8}{call=--remote-count}{display=Packets to capture}{type=unsigned}{required=true} - {tooltip=The number of remote packets to capture.} - - -To capture: - - ciscodump --extcap-interface cisco --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10 - --remote-username user --remote-interface gigabit0/0 - --remote-filter "permit ip host 192.168.1.1 any, permit ip any host 192.168.1.1" - -NOTE: Packet count is mandatory, hence the capture will start after this number. - -=head1 KNOWN ISSUES - -The configuration of the capture on the routers 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 router and manually clean the -configuration, removing both the capture point (WIRESHARK_CAPTURE_POINT), the capture buffer (WIRESHARK_CAPTURE_BUFFER) -and the capture filter (WIRESHARK_CAPTURE_FILTER). - -Another known issues is related to the number of captured packets (--remote-count). Due to the nature of the capture -buffer, ciscodump waits for the capture to complete and then issues the command to show it. It means that if the user -specifies a number of packets above the currently captured, the show command is never shown. Not only is the count of -the maximum number of captured packets, but it is also the _exact_ number of expected packets. - -=head1 SEE ALSO - -wireshark(1), tshark(1), dumpcap(1), extcap(4), sshdump(1) - -=head1 NOTES - -B<ciscodump> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - -------- ------ - Dario Lombardo <lomato[AT]gmail.com> diff --git a/doc/dftest.pod b/doc/dftest.pod deleted file mode 100644 index fab224732b..0000000000 --- a/doc/dftest.pod +++ /dev/null @@ -1,37 +0,0 @@ - -=head1 NAME - -dftest - Shows display filter byte-code, for debugging dfilter routines. - -=head1 SYNOPSIS - -B<dftest> -S<[ E<lt>filterE<gt> ]> - -=head1 DESCRIPTION - -B<dftest> is a simple tool which compiles a display filter and shows its bytecode. - -=head1 OPTIONS - -=over 4 - -=item filter - -The display filter expression. If needed it has to be quoted. - -=back - -=head1 EXAMPLES - -Show how the IP protocol is filtered: - - dftest ip - -Shows how frame 150 is filtered: - - dftest "frame.number == 150" - -=head1 SEE ALSO - -wireshark-filter(4) diff --git a/doc/diagnostic-options.adoc b/doc/diagnostic-options.adoc new file mode 100644 index 0000000000..1500168f1b --- /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 0000000000..5c55a76368 --- /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 0000000000..d091c76644 --- /dev/null +++ b/doc/dpauxmon.adoc @@ -0,0 +1,142 @@ +include::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/dpauxmon.pod b/doc/dpauxmon.pod deleted file mode 100644 index c486d1e503..0000000000 --- a/doc/dpauxmon.pod +++ /dev/null @@ -1,148 +0,0 @@ - -=head1 NAME - -dpauxmon - Provide interfaces to capture DisplayPort AUX channel data. - -=head1 SYNOPSIS - -B<dpauxmon> -S<[ B<--help> ]> -S<[ B<--version> ]> -S<[ B<--extcap-interfaces> ]> -S<[ B<--extcap-dlts> ]> -S<[ B<--extcap-interface>=E<lt>interfaceE<gt> ]> -S<[ B<--extcap-config> ]> -S<[ B<--extcap-capture-filter>=E<lt>capture filterE<gt> ]> -S<[ B<--capture> ]> -S<[ B<--fifo>=E<lt>path to file or pipeE<gt> ]> -S<[ B<--interface_id>=E<lt>Interface ID to captureE<gt> ]> - -B<dpauxmon> -S<B<--extcap-interfaces>> - -B<dpauxmon> -S<B<--extcap-interface>=E<lt>interfaceE<gt>> -S<B<--extcap-dlts>> - -B<dpauxmon> -S<B<--extcap-interface>=E<lt>interfaceE<gt>> -S<B<--extcap-config>> - -B<dpauxmon> -S<B<--extcap-interface>=E<lt>interfaceE<gt>> -S<B<--fifo>=E<lt>path to file or pipeE<gt>> -S<B<--capture>> -S<B<--interface_id=interface_id>> - -=head1 DESCRIPTION - -B<dpauxmon> is an extcap tool that can capture DisplayPort AUX channel data -from linux kernel drivers using the generic netlink interface. - -Supported interfaces: - -=over 4 - -=item 1. dpauxmon - -=back - -=head1 OPTIONS - -=over 4 - -=item --help - -Print program arguments. - -=item --version - -Print program version. - -=item --extcap-interfaces - -List available interfaces. - -=item --extcap-interface=E<lt>interfaceE<gt> - -Use specified interfaces. - -=item --extcap-dlts - -List DLTs of specified interface. - -=item --extcap-config - -List configuration options of specified interface. - -=item --capture - -Start capturing from specified interface and save it in place specified by --fifo. - -=item --fifo=E<lt>path to file or pipeE<gt> - -Save captured packet to file or send it through pipe. - -=item --interface_idt=E<lt>interface idE<gt> - -The interface for capture. - -=back - -=head1 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. - - Output: - interface {value=dpauxmon}{display=DisplayPort AUX channel capture} - -To see interface DLTs: - - dpauxmon --extcap-interface=dpauxmon --extcap-dlts - - Output: - dlt {number=275}{name=dpauxmon}{display=DisplayPort AUX channel monitor DLT} - -To see interface configuration options: - - dpauxmon --extcap-interface=dpauxmon --extcap-config - - 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 - -=head1 SEE ALSO - -wireshark(1), tshark(1), dumpcap(1), extcap(4) - -=head1 NOTES - -B<dpauxmon> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - -------- ------ - Dirk Eibach <dirk.eibach[AT]gdsys.cc> diff --git a/doc/dumpcap.adoc b/doc/dumpcap.adoc new file mode 100644 index 0000000000..49d8838e11 --- /dev/null +++ b/doc/dumpcap.adoc @@ -0,0 +1,473 @@ +include::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_20240714120117.pcapng, +outfile_00002_20240714120523.pcapng, ... + +With the __files__ option it's also possible to form a "ring buffer". +This will fill up new files until the number of files specified, +at which point *Dumpcap* will discard the data in the first file and start +writing to that file and so on. If the __files__ option is not set, +new files filled up until one of the capture stop conditions match (or +until the disk is full). + +The criterion is of the form __key:value__, +where __key__ is one of: + +*duration*:__value__ switch to the next file after __value__ seconds have +elapsed, even if the current file is not completely filled up. Floating +point values (e.g. 0.5) are allowed. + +*files*:__value__ begin again with the first file after __value__ number of +files were written (form a ring buffer). This value must be less than 100000. +Caution should be used when using large numbers of files: some filesystems do +not handle many files in a single directory well. The *files* criterion +requires either *duration*, *interval* or *filesize* to be specified to +control when to go to the next file. It should be noted that each *-b* +parameter takes exactly one criterion; to specify two criterion, each must be +preceded by the *-b* option. + +*filesize*:__value__ switch to the next file after it reaches a size of +__value__ kB. Note that the filesize is limited to a maximum value of 2 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/dumpcap.pod b/doc/dumpcap.pod deleted file mode 100644 index 4c38223ef9..0000000000 --- a/doc/dumpcap.pod +++ /dev/null @@ -1,391 +0,0 @@ - -=head1 NAME - -dumpcap - Dump network traffic - -=head1 SYNOPSIS - -B<dumpcap> -S<[ B<-a> E<lt>capture autostop conditionE<gt> ] ...> -S<[ B<-b> E<lt>capture ring buffer optionE<gt>] ...> -S<[ B<-B> E<lt>capture buffer sizeE<gt> ] > -S<[ B<-c> E<lt>capture packet countE<gt> ]> -S<[ B<-C> E<lt>byte limitE<gt> ]> -S<[ B<-d> ]> -S<[ B<-D> ]> -S<[ B<-f> E<lt>capture filterE<gt> ]> -S<[ B<-g> ]> -S<[ B<-h> ]> -S<[ B<-i> E<lt>capture interfaceE<gt>|rpcap://E<lt>hostE<gt>:E<lt>portE<gt>/E<lt>capture interfaceE<gt>|TCP@E<lt>hostE<gt>:E<lt>portE<gt>|- ]> -S<[ B<-I> ]> -S<[ B<-L> ]> -S<[ B<-M> ]> -S<[ B<-n> ]> -S<[ B<-N> E<lt>packet limitE<gt> ]> -S<[ B<-p> ]> -S<[ B<-P> ]> -S<[ B<-q> ]> -S<[ B<-s> E<lt>capture snaplenE<gt> ]> -S<[ B<-S> ]> -S<[ B<-t> ]> -S<[ B<-v> ]> -S<[ B<-w> E<lt>outfileE<gt> ]> -S<[ B<-y> E<lt>capture link typeE<gt> ]> -S<[ B<--capture-comment> E<lt>commentE<gt> ]> -S<[ B<--list-time-stamp-types> ]> -S<[ B<--time-stamp-type> E<lt>typeE<gt> ]> - -=head1 DESCRIPTION - -B<Dumpcap> is a network traffic dump tool. It lets you capture packet -data from a live network and write the packets to a file. B<Dumpcap>'s -default capture file format is B<pcapng> format. -When the B<-P> option is specified, the output file is written in the -B<pcap> format. - -Without any options set it will use the libpcap/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 -pcap file. - -If the B<-w> option is not specified, B<Dumpcap> writes to a newly -created pcap file with a randomly chosen name. -If the B<-w> option is specified, B<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. - -=head1 OPTIONS - -=over 4 - -=item -a E<lt>capture autostop conditionE<gt> - -Specify a criterion that specifies when B<Dumpcap> is to stop writing -to a capture file. The criterion is of the form I<test>B<:>I<value>, -where I<test> is one of: - -B<duration>:I<value> Stop writing to a capture file after I<value> seconds have -elapsed. - -B<filesize>:I<value> Stop writing to a capture file after it reaches a size of -I<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. - -B<files>:I<value> Stop writing to capture files after I<value> number of files -were written. - -=item -b E<lt>capture ring buffer optionE<gt> - -Cause B<Dumpcap> to run in "multiple files" mode. In "multiple files" mode, -B<Dumpcap> will write to several capture files. When the first capture file -fills up, B<Dumpcap> will switch writing to the next file and so on. - -The created filenames are based on the filename given with the B<-w> option, -the number of the file and on the creation date and time, -e.g. outfile_00001_20050604120117.pcap, outfile_00002_20050604120523.pcap, ... - -With the I<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 B<Dumpcap> will discard the data in the first file and start -writing to that file and so on. If the I<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 I<key>B<:>I<value>, -where I<key> is one of: - -B<duration>:I<value> switch to the next file after I<value> seconds have -elapsed, even if the current file is not completely filled up. - -B<interval>:I<value> switch to the next file when the time is an exact -multiple of I<value> seconds - -B<filesize>:I<value> switch to the next file after it reaches a size of -I<value> kB. Note that the filesize is limited to a maximum value of 2 GiB. - -B<files>:I<value> begin again with the first file after I<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 B<files> criterion -requires either B<duration>, B<interval> or B<filesize> to be specified to -control when to go to the next file. It should be noted that each B<-b> -parameter takes exactly one criterion; to specify two criterion, each must be -preceded by the B<-b> option. - -Example: B<-b filesize:1000 -b files:5> results in a ring buffer of five files -of size one megabyte each. - -=item -B E<lt>capture buffer sizeE<gt> - -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 B<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 systems with libpcap 1.0.0 or later and on -Windows. It is not available on UNIX systems with earlier versions of -libpcap. - -This option can occur multiple times. If used before the first -occurrence of the B<-i> option, it sets the default capture buffer size. -If used after an B<-i> option, it sets the capture buffer size for -the interface specified by the last B<-i> option occurring before -this option. If the capture buffer size is not set specifically, -the default capture buffer size is used instead. - -=item -c E<lt>capture packet countE<gt> - -Set the maximum number of packets to read when capturing live -data. - -=item -C E<lt>byte limitE<gt> - -Limit the amount of memory in bytes used for storing captured packets -in memory while processing it. -If used in combination with the B<-N> option, both limits will apply. -Setting this limit will enable the usage of the separate thread per interface. - -=item -d - -Dump the code generated for the capture filter in a human-readable form, -and exit. - -=item -D - -Print a list of the interfaces on which B<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 B<-i> option to specify an interface on which to capture. - -This can be useful on systems that don't have a command to list them -(UNIX systems lacking B<ifconfig -a> or Linux systems lacking -B<ip link show>). The number can be useful on Windows systems, where -the interface name might be a long name or a GUID. - -Note that "can capture" means that B<Dumpcap> was able to open -that device to do a live capture. Depending on your system you may need to -run dumpcap from an account with special privileges (for example, as root) -to be able to capture network traffic. -If "B<dumpcap -D>" is not run from such an account, it will not list -any interfaces. - -=item -f E<lt>capture filterE<gt> - -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 B<-i> option, it sets the default capture filter expression. -If used after an B<-i> option, it sets the capture filter expression for -the interface specified by the last B<-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: B<-f "predef:MyPredefinedHostOnlyFilter"> - -=item -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). - -=item -h - -Print the version and options and exits. - -=item -i E<lt>capture interfaceE<gt>|rpcap://E<lt>hostE<gt>:E<lt>portE<gt>/E<lt>capture interfaceE<gt>|TCP@E<lt>hostE<gt>:E<lt>portE<gt>|- - -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 -"B<dumpcap -D>" (described above); a number, as reported by -"B<dumpcap -D>", can also be used. If you're using UNIX, "B<netstat --i>" or "B<ifconfig -a>" might also work to list interface names, -although not all versions of UNIX support the B<-a> option to B<ifconfig>. - -If no interface is specified, B<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, -B<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. Data read from pipes must be in -standard pcap format. - -This option can occur multiple times. When capturing from multiple -interfaces, the capture file will be saved in pcapng format. - -Note: the Win32 version of B<Dumpcap> doesn't support capturing from -pipes or stdin! - -=item -I - -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 B<-i> option, it enables the monitor mode for all interfaces. -If used after an B<-i> option, it enables the monitor mode for -the interface specified by the last B<-i> option occurring before -this option. - -=item -L - -List the data link types supported by the interface and exit. The reported -link types can be used for the B<-y> option. - -=item -M - -When used with B<-D>, B<-L>, B<-S> or B<--list-time-stamp-types> print -machine-readable output. -The machine-readable output is intended to be read by B<Wireshark> and -B<TShark>; its format is subject to change from release to release. - -=item -n - -Save files as pcapng. This is the default. - -=item -N E<lt>packet limitE<gt> - -Limit the number of packets used for storing captured packets -in memory while processing it. -If used in combination with the B<-C> option, both limits will apply. -Setting this limit will enable the usage of the separate thread per interface. - -=item -p - -I<Don't> put the interface into promiscuous mode. Note that the -interface might be in promiscuous mode for some other reason; hence, -B<-p> cannot be used to ensure that the only traffic that is captured is -traffic sent to or from the machine on which B<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 B<-i> option, no interface will be put into the -promiscuous mode. -If used after an B<-i> option, the interface specified by the last B<-i> -option occurring before this option will not be put into the -promiscuous mode. - -=item -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. - -=item -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). - -=item -s E<lt>capture snaplenE<gt> - -Set the default snapshot length to use when capturing live data. -No more than I<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 B<-i> option, it sets the default snapshot length. -If used after an B<-i> option, it sets the snapshot length for -the interface specified by the last B<-i> option occurring before -this option. If the snapshot length is not set specifically, -the default snapshot length is used if provided. - -=item -S - -Print statistics for each interface once every second. - -=item -t - -Use a separate thread per interface. - -=item -v - -Print the version and exit. - -=item -w E<lt>outfileE<gt> - -Write raw packet data to I<outfile>. Use "-" for stdout. - -=item -y E<lt>capture link typeE<gt> - -Set the data link type to use while capturing packets. The values -reported by B<-L> are the values that can be used. - -This option can occur multiple times. If used before the first -occurrence of the B<-i> option, it sets the default capture link type. -If used after an B<-i> option, it sets the capture link type for -the interface specified by the last B<-i> option occurring before -this option. If the capture link type is not set specifically, -the default capture link type is used if provided. - -=item --capture-comment E<lt>commentE<gt> - -Add a capture comment to the output file. - -This option is only available if we output the captured packets to a -single file in pcapng format. Only one capture comment may be set per -output file. - -=item --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. - -=item --time-stamp-type E<lt>typeE<gt> - -Change the interface's timestamp method. - -=back - -=head1 CAPTURE FILTER SYNTAX - -See the manual page of pcap-filter(7) or, if that doesn't exist, tcpdump(8), -or, if that doesn't exist, L<https://wiki.wireshark.org/CaptureFilters>. - -=head1 SEE ALSO - -wireshark(1), tshark(1), editcap(1), mergecap(1), capinfos(1), pcap(3), -pcap-filter(7) or tcpdump(8) - -=head1 NOTES - -B<Dumpcap> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - -B<Dumpcap> is derived from the B<Wireshark> capturing engine code; -see the list of -authors in the B<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 0000000000..acd320d8f8 --- /dev/null +++ b/doc/editcap.adoc @@ -0,0 +1,628 @@ +include::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://udn.realityripple.com/docs/Mozilla/Projects/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/editcap.pod b/doc/editcap.pod deleted file mode 100644 index 0eff2c943d..0000000000 --- a/doc/editcap.pod +++ /dev/null @@ -1,440 +0,0 @@ - -=head1 NAME - -editcap - Edit and/or translate the format of capture files - -=head1 SYNOPSIS - -B<editcap> -S<[ B<-a> E<lt>frame:commentE<gt> ]> -S<[ B<-A> E<lt>start timeE<gt> ]> -S<[ B<-B> E<lt>stop timeE<gt> ]> -S<[ B<-c> E<lt>packets per fileE<gt> ]> -S<[ B<-C> [offset:]E<lt>choplenE<gt> ]> -S<[ B<-E> E<lt>error probabilityE<gt> ]> -S<[ B<-F> E<lt>file formatE<gt> ]> -S<[ B<-h> ]> -S<[ B<-i> E<lt>seconds per fileE<gt> ]> -S<[ B<-o> E<lt>change offsetE<gt> ]> -S<[ B<-L> ]> -S<[ B<-r> ]> -S<[ B<-s> E<lt>snaplenE<gt> ]> -S<[ B<-S> E<lt>strict time adjustmentE<gt> ]> -S<[ B<-t> E<lt>time adjustmentE<gt> ]> -S<[ B<-T> E<lt>encapsulation typeE<gt> ]> -S<[ B<-v> ]> -I<infile> -I<outfile> -S<[ I<packet#>[-I<packet#>] ... ]> - -B<editcap> -S< B<-d> > | -S< B<-D> E<lt>dup windowE<gt> > | -S< B<-w> E<lt>dup time windowE<gt> > -S<[ B<-v> ]> -S<[ B<-I> E<lt>bytes to ignoreE<gt> ]> -I<infile> -I<outfile> - -B<editcap> -S<[ B<-V> ]> - -=head1 DESCRIPTION - -B<Editcap> is a program that reads some or all of the captured packets from the -I<infile>, optionally converts them in various ways and writes the -resulting packets to the capture I<outfile> (or outfiles). - -By default, it reads all packets from the I<infile> and writes them to the -I<outfile> in pcap file format. - -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 I<start>-I<end>, referring to all packets from -I<start> to I<end>. By default the selected packets with those numbers will -I<not> be written to the capture file. If the B<-r> flag is specified, the -whole packet selection is reversed; in that case I<only> the selected packets -will be written to the capture file. - -B<Editcap> can also be used to remove duplicate packets. Several different -options (B<-d>, B<-D> and B<-w>) are used to control the packet window -or relative time window to be used for duplicate comparison. - -B<Editcap> can be used to assign comment strings to frame numbers. - -B<Editcap> is able to detect, read and write the same capture files that -are supported by B<Wireshark>. -The input file doesn't need a specific filename extension; the file -format and an optional gzip compression will be automatically detected. -Near the beginning of the DESCRIPTION section of wireshark(1) or -L<https://www.wireshark.org/docs/man-pages/wireshark.html> -is a detailed description of the way B<Wireshark> handles this, which is -the same way B<Editcap> handles this. - -B<Editcap> can write the file in several output formats. The B<-F> -flag can be used to specify the format in which to write the capture -file; B<editcap -F> provides a list of the available output formats. - -=head1 OPTIONS - -=over 4 - -=item -a E<lt>framenum:commentE<gt> - -For the specificed frame number, assign the given comment string. -Can be repeated for multiple frames. Quotes should be used with comment -strings that include spaces. - -=item -A E<lt>start timeE<gt> - -Saves only the packets whose timestamp is on or after start time. -The time is given in the following format YYYY-MM-DD HH:MM:SS - -=item -B E<lt>stop timeE<gt> - -Saves only the packets whose timestamp is before stop time. -The time is given in the following format YYYY-MM-DD HH:MM:SS - -=item -c E<lt>packets per fileE<gt> - -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 a suffix -nnnnn, starting with 00000. If 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. - -=item -C [offset:]E<lt>choplenE<gt> - -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. - -=item -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 B<-D 5>. - -=item -D E<lt>dup windowE<gt> - -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 B<-D 0> combined with the B<-v> option is useful -in that each packet's Packet number, Len and MD5 Hash will be printed -to standard out. 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 B<editcap>. - -=item -E E<lt>error probabilityE<gt> - -Sets the probability that bytes in the output file are randomly changed. -B<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. - -=item -F E<lt>file formatE<gt> - -Sets the file format of the output capture file. -B<Editcap> can write the file in several formats, B<editcap -F> -provides a list of the available output formats. The default -is the B<pcap> format. - -=item -h - -Prints the version and options and exits. - -=item -i E<lt>seconds per fileE<gt> - -Splits the packet output to different files based on uniform time intervals -using a maximum interval of <seconds per file> each. Each output file will -be created with a suffix -nnnnn, starting with 00000. If 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. - -=item -I E<lt>bytes to ignoreE<gt> - -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. - -=item -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 B<-L> is specified or not). See also B<-C <choplen>> and B<-s <snaplen>>. - -=item -o E<lt>change offsetE<gt> - -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. - -=item -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. - -=item -s E<lt>snaplenE<gt> - -Sets the snapshot length to use when writing the data. -If the B<-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). - -=item -S E<lt>strict time adjustmentE<gt> - -Time adjust selected packets to ensure strict chronological order. - -The <strict time adjustment> value represents relative seconds -specified as [-]I<seconds>[I<.fractional seconds>]. - -As the capture file is processed each packet's absolute time is -I<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 B<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 B<all> -packets will be adjusted to be equal to the timestamp value -of the previous packet plus the absolute value of the -<lt>strict time adjustment<gt> 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. - -=item -t E<lt>time adjustmentE<gt> - -Sets the time adjustment to use on selected packets. -If the B<-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 [-]I<seconds>[I<.fractional seconds>]. -For example, B<-t> 3600 advances the timestamp on selected packets by one -hour while B<-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. - -=item -T E<lt>encapsulation typeE<gt> - -Sets the packet encapsulation type of the output capture file. -If the B<-T> flag is used to specify an encapsulation type, the -encapsulation type of the output capture file will be forced to the -specified type. -B<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 'B<-T -fddi>' is specified). If you need to remove/add headers from/to a -packet, you will need od(1)/text2pcap(1). - -=item -v - -Causes B<editcap> to print verbose messages while it's working. - -Use of B<-v> with the de-duplication switches of B<-d>, B<-D> or B<-w> -will cause all MD5 hashes to be printed whether the packet is skipped -or not. - -=item -V - -Print the version and exit. - -=item -w E<lt>dup time windowE<gt> - -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 I<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 I<seconds>[I<.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 B<editcap>. - -NOTE: The B<-w> option assumes that the packets are in chronological order. -If the packets are NOT in chronological order then the B<-w> duplication -removal option may not identify some duplicates. - -=back - -=head1 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.pcap shortcapture.snoop - -To delete packet 1000 from the capture file use: - - editcap capture.pcap sans1000.pcap 1000 - -To limit a capture file to packets from number 200 to 750 (inclusive) use: - - editcap -r capture.pcap small.pcap 200-750 - -To get all packets from number 1-500 (inclusive) use: - - editcap -r capture.pcap first500.pcap 1-500 - -or - - editcap capture.pcap first500.pcap 501-9999999 - -To exclude packets 1, 5, 10 to 20 and 30 to 40 from the new file use: - - editcap capture.pcap exclude.pcap 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.pcap select.pcap 1 5 10-20 30-40 - -To remove duplicate packets seen within the prior four frames use: - - editcap -d capture.pcap dedup.pcap - -To remove duplicate packets seen within the prior 100 frames use: - - editcap -D 101 capture.pcap dedup.pcap - -To remove duplicate packets seen I<equal to or less than> 1/10th of a second: - - editcap -w 0.1 capture.pcap dedup.pcap - -To display the MD5 hash for all of the packets (and NOT generate any -real output file): - - editcap -v -D 0 capture.pcap /dev/null - -or on Windows systems - - editcap -v -D 0 capture.pcap NUL - -To advance the timestamps of each packet forward by 3.0827 seconds: - - editcap -t 3.0827 capture.pcap adjusted.pcap - -To ensure all timestamps are in strict chronological order: - - editcap -S 0 capture.pcap adjusted.pcap - -To introduce 5% random errors in a capture file use: - - editcap -E 0.05 capture.pcap capture_error.pcap - -To remove vlan tags from all packets within an Ethernet-encapsulated capture -file, use: - - editcap -L -C 12:4 capture_vlan.pcap capture_no_vlan.pcap - -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.pcap chopped.pcap - 2) editcap -C 5:10 -C 50:-20 capture.pcap chopped.pcap - 3) editcap -C -70:10 -C -25:-20 capture.pcap chopped.pcap - 4) editcap -C -70:10 -C 50:-20 capture.pcap chopped.pcap - 5) editcap -C 30:20 -C -60:-10 capture.pcap chopped.pcap - 6) editcap -C 30:20 -C 15:-10 capture.pcap chopped.pcap - 7) editcap -C -45:20 -C -60:-10 capture.pcap chopped.pcap - 8) editcap -C -45:20 -C 15:-10 capture.pcap chopped.pcap - -To add comment strings to the first 2 input frames, use: - - editcap -a "1:1st frame" -a 2:Second capture.pcap capture-comments.pcap - -=head1 SEE ALSO - -pcap(3), wireshark(1), tshark(1), mergecap(1), dumpcap(1), capinfos(1), -text2pcap(1), od(1), pcap-filter(7) or tcpdump(8) - -=head1 NOTES - -B<Editcap> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - -------- ------ - Richard Sharpe <sharpe[AT]ns.aus.com> - - - Contributors - ------------ - 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 0000000000..4798c54930 --- /dev/null +++ b/doc/etwdump.adoc @@ -0,0 +1,124 @@ +include::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.pod b/doc/extcap.adoc index 28ea798663..96aa1fa9d0 100644 --- a/doc/extcap.pod +++ b/doc/extcap.adoc @@ -1,15 +1,21 @@ +include::attributes.adoc[] += extcap(4) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{stylesheet} -=head1 NAME +== NAME extcap - The extcap interface -=head1 DESCRIPTION +== 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 +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 app. +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: @@ -17,74 +23,73 @@ Without extcap, a capture can always be achieved by directly writing to a captur wireshark dumpfile.pcap but the extcap interface allows for such a connection to be easily established and -configured using the wireshark GUI. +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. To go deeper -into the extcap utility development, please refer to README.extcap. +need to be executable without prefacing a script interpreter before the call. -WINDOWS USER: Because of restrictions directly calling the script may not always work. +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. -=head1 GRAMMAR ELEMENTS +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: - -=over 4 +== GRAMMAR ELEMENTS -=item arg (options) +Grammar elements: +arg (options):: argument for CLI calling -=item number - +number:: Reference # of argument for other values, display order -=item call - +call:: Literal argument to call (--call=...) -=item display - +display:: Displayed name -=item default - +default:: Default value, in proper form for type -=item range - +range:: Range of valid values for UI checking (min,max) in proper form -=item type - +type:: ++ +-- Argument type for UI filtering for raw, or UI type for selector: integer unsigned long (may include scientific / special notation) - float + 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) +-- -=item value (options) - +value (options):: ++ +-- Values for argument selection arg Argument # this value applies to +-- -=back - -=head1 EXAMPLES +== EXAMPLES Example 1: @@ -110,37 +115,31 @@ Example 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} -=head1 Security awareness - -=over 4 - -=item - Users running wireshark as root, we can't save you - -=item - Dumpcap retains suid/setgid and group+x permissions to allow users in wireshark group only - -=item - Third-party capture programs run w/ whatever privs they're installed with - -=item - If an attacker can write to a system binary directory, we're game over anyhow - -=item - Reference the folders tab in the wireshark->about information, to see from which directory extcap is being run +== Security Considerations -=back +- 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]. -=head1 SEE ALSO +== SEE ALSO -wireshark(1), tshark(1), dumpcap(1), androiddump(1), sshdump(1), randpktdump(1) +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) -=head1 NOTES +== NOTES -B<Extcap> is feature of B<Wireshark>. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. +*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: -L<https://www.wireshark.org/docs/man-pages>. +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 index 2080e48af9..e7af44b4d5 100755 --- a/doc/extcap_example.py +++ b/doc/extcap_example.py @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 # Copyright 2014 Roland Knall <rknall [AT] gmail.com> # @@ -9,7 +9,7 @@ # SPDX-License-Identifier: GPL-2.0-or-later # -""" +r""" This is a generic example, which produces pcap packages every n seconds, and is configurable via extcap options. @@ -20,25 +20,23 @@ the extcap folder, with the following content: ------- @echo off -<Path to python interpreter> <Path to script file> %* +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 formates beside VBScript +other script-based formats beside VBScript } """ from __future__ import print_function -import os import sys -import signal import re import argparse import time import struct -import binascii +import array from threading import Thread ERROR_USAGE = 0 @@ -81,7 +79,7 @@ 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 it's first arg... + passed as its first arg... """ container = self._actions if name is None: @@ -111,77 +109,91 @@ this extcap plugin def extcap_config(interface, option): args = [] 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 ): + 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) + 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((3, "if1", "Remote1", "true")) + values.append((3, "if2", "Remote2", "false")) - values.append ( (11, "r1", "Radio1", "false" ) ) - values.append ( (11, "r2", "Radio2", "true" ) ) + values.append((11, "r1", "Radio1", "false")) + values.append((11, "r2", "Radio2", "true")) - values.append ( (12, "m1", "MultiCheck1", "false" ) ) - values.append ( (12, "m2", "MultiCheck2", "false" ) ) + 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) + 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=http://www.wireshark.org}{display=Example extcap interface}") + print("extcap {version=1.0}{help=https://www.wireshark.org}{display=Example extcap interface}") def extcap_interfaces(): - print ("extcap {version=1.0}{help=http://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) + 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}") + 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": @@ -207,65 +219,76 @@ def unsigned(n): 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)) # Accurancy of timestamps - header += struct.pack('<L', int ('0000ffff', 16 )) # Max Length of capture frame - header += struct.pack('<L', unsigned(1)) # Ethernet + 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) - csum = 0; + 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 -def pcap_fake_package ( message, fake_ip ): +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 + 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 - pcap += struct.pack('h', 0 ) # source mac - pcap += struct.pack('h', 0 ) # source mac - pcap += struct.pack('h', 0 ) # source mac - pcap += struct.pack('h', 0 ) # dest mac - pcap += struct.pack('h', 0 ) # dest mac - pcap += struct.pack('h', 0 ) # dest mac - pcap += struct.pack('<h', unsigned(8 )) # protocol (ip) + 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 + 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 += struct.pack('>L', ipadr) # Source IP + pcap += struct.pack('>L', int('7F000001', 16)) # Dest IP pcap += message + return pcap def control_read(fn): @@ -273,18 +296,18 @@ def control_read(fn): header = fn.read(6) sp, _, length, arg, typ = struct.unpack('>sBHBB', header) if length > 2: - payload = fn.read(length - 2) + payload = fn.read(length - 2).decode('utf-8', 'replace') else: payload = '' return arg, typ, payload - except: + 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: + with open(control_in, 'rb', 0) as fn: arg = 0 - while arg != None: + while arg is not None: arg, typ, payload = control_read(fn) log = '' if typ == CTRL_CMD_INITIALIZED: @@ -304,7 +327,7 @@ def control_read_thread(control_in, fn_out): elif arg == CTRL_ARG_BUTTON: control_write(fn_out, CTRL_ARG_BUTTON, CTRL_CMD_DISABLE, "") button_disabled = True - if button == True: + if button: control_write(fn_out, CTRL_ARG_BUTTON, CTRL_CMD_SET, "Turn on") button = False log = "Button turned off" @@ -336,9 +359,8 @@ def control_write_defaults(fn_out): 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 = bytearray() - item += str(i) + struct.pack('B', 0) + str(i) + " sec" + 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)) @@ -351,50 +373,65 @@ def extcap_capture(interface, fifo, control_in, control_out, in_delay, in_verify counter = 1 fn_out = None - with open(fifo, 'wb', 0 ) as fh: - fh.write (pcap_fake_header()) + 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. """ - if control_out != None: + 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 != None: + if control_in is not None: # Start reading thread - thread = Thread(target = control_read_thread, args = (control_in, fn_out)) + thread = Thread(target=control_read_thread, args=(control_in, fn_out)) thread.start() - if fn_out != None: + 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 != None: + 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 == True: + 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 - out = ("%s|%04X%s|%s" % ( remote.strip(), len(message), message, verify )).encode("utf8") - fh.write (pcap_fake_package(out, fake_ip)) + 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 != None: + 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 = 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] ) + print("Usage: %s <--extcap-interfaces | --extcap-dlts | --extcap-interface | --extcap-config | --capture | --extcap-capture-filter | --fifo>" % sys.argv[0] ) if __name__ == '__main__': interface = "" @@ -408,7 +445,7 @@ if __name__ == '__main__': parser = ArgumentParser( prog="Extcap Example", - description="Extcap example program for python" + description="Extcap example program for Python" ) # Extcap Arguments @@ -429,60 +466,60 @@ if __name__ == '__main__': 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 adress", nargs='?', default="127.0.0.1" ) + 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) + 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") : + if arg == "--fifo" or arg == "--extcap-fifo": fifo_found = 1 - elif ( fifo_found == 1 ): + elif fifo_found == 1: fifo = arg break extcap_close_fifo(fifo) sys.exit(ERROR_ARG) - if ( len(sys.argv) <= 1 ): + if len(sys.argv) <= 1: parser.exit("No arguments given!") - if ( args.extcap_version and not args.extcap_interfaces ): + if args.extcap_version and not args.extcap_interfaces: extcap_version() sys.exit(0) - if ( args.extcap_interfaces == False and args.extcap_interface == None ): + 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 ): + if args.extcap_capture_filter and not args.capture: validate_capture_filter(args.extcap_capture_filter) sys.exit(0) - if ( args.extcap_interfaces == True or args.extcap_interface == None ): + 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) ) + if len(unknown) > 1: + print("Extcap Example %d unknown arguments given" % len(unknown)) - m = re.match ( 'example(\d+)', args.extcap_interface ) + m = re.match(r'example(\d+)', args.extcap_interface) if not m: sys.exit(ERROR_INTERFACE) interface = m.group(1) message = args.message - if ( args.message == None or len(args.message) == 0 ): + if args.message is None or len(args.message) == 0: message = "Extcap Test" fake_ip = args.fake_ip - if ( args.fake_ip == None or len(args.fake_ip) < 7 or len(args.fake_ip.split('.')) != 4 ): + 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 ): + if args.extcap_reload_option and len(args.extcap_reload_option) > 0: option = args.extcap_reload_option if args.extcap_config: diff --git a/doc/falcodump.adoc b/doc/falcodump.adoc new file mode 100644 index 0000000000..72bd06695b --- /dev/null +++ b/doc/falcodump.adoc @@ -0,0 +1,145 @@ +include::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/faq.adoc b/doc/faq.adoc new file mode 100644 index 0000000000..fb667ade41 --- /dev/null +++ b/doc/faq.adoc @@ -0,0 +1,1087 @@ +include::attributes.adoc[] +:stylesheet: ws.css +:linkcss: +:copycss: {stylesheet} +:toc: + += Wireshark Frequently Asked Questions + +== General Questions + +=== What is Wireshark? + +Wireshark® is a network protocol analyzer. It lets you capture and +interactively browse the traffic running on a computer network. It has a +rich and powerful feature set and is world's most popular tool of its +kind. It runs on most computing platforms including Windows, macOS, +Linux, and UNIX. Network professionals, security experts, developers, +and educators around the world use it regularly. It is freely available +as open source, and is released under the GNU General Public License +version 2. + +It is developed and maintained by a global team of protocol experts, +and it is an example of a +https://en.wikipedia.org/wiki/Disruptive_technology[disruptive +technology]. + +Wireshark used to be known as Ethereal®. See the next question for +details about the name change. If you're still using Ethereal, it is +strongly recommended that you upgrade to Wireshark as Ethereal is +unsupported and has known security vulnerabilities. + +For more information, please see the +https://www.wireshark.org/about.html[About Wireshark] page. + +[#wheretogethelp] +=== Where can I get help? + +Community support is available on the +https://ask.wireshark.org/[Q&A site] +and on the wireshark-users mailing list. +Subscription information and archives for all of Wireshark's mailing lists can be found at +https://www.wireshark.org/mailman/listinfo[https://www.wireshark.org/mailman/listinfo]. +// An IRC channel dedicated to Wireshark can be found at +// irc://irc.freenode.net/wireshark[irc://irc.freenode.net/wireshark]. + +=== What kind of shark is Wireshark? + +_carcharodon photoshopia_. + +=== How is Wireshark pronounced, spelled and capitalized? + +Wireshark is pronounced as the word _wire_ followed immediately by +the word _shark_. Exact pronunciation and emphasis may vary depending on +your locale (e.g. Arkansas). + +It's spelled with a capital _W_, followed by a lower-case _ireshark_. +It is not a CamelCase word, i.e., _WireShark_ is incorrect. + +=== How much does Wireshark cost? + +Wireshark is "free software"; you can download it without paying any +license fee. The version of Wireshark you download isn't a "demo" +version, with limitations not present in a "full" version; it _is_ the +full version. + +The license under which Wireshark is issued is +https://www.gnu.org/licenses/gpl-2.0.html[the GNU General Public License +version 2]. See +https://www.gnu.org/licenses/old-licenses/gpl-2.0-faq.html[the GNU GPL +FAQ] for some more information. + +=== But I just paid someone on eBay for a copy of Wireshark! Did I get ripped off? + +That depends. Did they provide any sort of value-added product or +service, such as installation support, installation media, training, +trace file analysis, or funky-colored shark-themed socks? Probably not. + +Wireshark is https://www.wireshark.org/download.html[available for +anyone to download, absolutely free, at any time]. Paying for a copy +implies that you should get something for your money. + +=== Can I use Wireshark commercially? + +Yes, if, for example, you mean "I work for a commercial organization; +can I use Wireshark to capture and analyze network traffic in our +company's networks or in our customer's networks?" + +If you mean "Can I use Wireshark as part of my commercial product?", +see link:#derived_work_gpl[the next entry in the FAQ]. + +=== Can I use Wireshark as part of my commercial product? + +As noted, Wireshark is licensed under +https://www.gnu.org/licenses/gpl-2.0.html[the GNU General Public +License, version 2]. The GPL imposes conditions on your use of GPL'ed +code in your own products; you cannot, for example, make a "derived +work" from Wireshark, by making modifications to it, and then sell the +resulting derived work and not allow recipients to give away the +resulting work. You must also make the changes you've made to the +Wireshark source available to all recipients of your modified version; +those changes must also be licensed under the terms of the GPL. See the +https://www.gnu.org/licenses/old-licenses/gpl-2.0-faq.html[GPL FAQ] for +more details; in particular, note the answer to +https://www.gnu.org/licenses/old-licenses/gpl-2.0-faq.html#GPLCommercially[the +question about modifying a GPLed program and selling it commercially], +and +https://www.gnu.org/licenses/old-licenses/gpl-2.0-faq.html#LinkingWithGPL[the +question about linking GPLed code with other code to make a proprietary +program]. + +You can combine a GPLed program such as Wireshark and a commercial +program as long as they communicate "at arm's length", as per +https://www.gnu.org/licenses/old-licenses/gpl-2.0-faq.html#GPLInProprietarySystem[this +item in the GPL FAQ]. + +We recommend keeping Wireshark and your product completely separate, +communicating over sockets or pipes. If you're loading any part of +Wireshark as a DLL, you're probably doing it wrong. + +=== Can you help me fill out this compliance form so that I can use Wireshark? + +// While we try to make sure that Wireshark is as easy as possible to obtain and use, please keep in mind that it’s developed by a team of volunteers and that filling out compliance forms is pretty far beyond the scope of what those volunteers do. + +Please contact the https://wiresharkfoundation.org[Wireshark Foundation] and they will be able to help you for a nominal fee. + +=== Can you sign this legal agreement so that I can use Wireshark? + +// As with the previous question, Wireshark is developed by a team of volunteers. +// Even if they were inclined to do so, they aren’t authorized to sign agreements on behalf of the project. + +Please contact the https://wiresharkfoundation.org[Wireshark Foundation] and they will be able to help you for a somewhat less nominal fee. + +=== What protocols are currently supported? + +There are currently hundreds of supported protocols and media. +Details can be found in the +https://www.wireshark.org/docs/man-pages/wireshark.html[wireshark(1)] +man page. + +=== Are there any plans to support {your favorite protocol}? + +Support for particular protocols is added to Wireshark as a result of +people contributing that support; no formal plans for adding support for +particular protocols in particular future releases exist. + +=== Can Wireshark read capture files from {your favorite network analyzer}? + +Support for particular capture file formats is added to Wireshark as +a result of people contributing that support; no formal plans for adding +support for particular capture file formats in particular future +releases exist. + +If a network analyzer writes out files in a format already supported by +Wireshark (e.g., in libpcap format), Wireshark may already be able to +read them, unless the analyzer has added its own proprietary extensions +to that format. + +If a network analyzer writes out files in its own format, or has added +proprietary extensions to another format, in order to make Wireshark +read captures from that network analyzer, we would either have to have a +specification for the file format, or the extensions, sufficient to give +us enough information to read the parts of the file relevant to +Wireshark, or would need at least one capture file in that format *AND* +a detailed textual analysis of the packets in that capture file (showing +packet time stamps, packet lengths, and the top-level packet header) in +order to reverse-engineer the file format. + +Note that there is no guarantee that we will be able to +reverse-engineer a capture file format. + +=== What devices can Wireshark use to capture packets? + +Wireshark can read live data from Ethernet, Token-Ring, FDDI, serial +(PPP and SLIP) (if the OS on which it's running allows Wireshark to do +so), 802.11 wireless LAN (if the OS on which it's running allows +Wireshark to do so), ATM connections (if the OS on which it's running +allows Wireshark to do so), and the "any" device supported on Linux by +recent versions of libpcap. + +See https://gitlab.com/wireshark/wireshark/-/wikis/CaptureSetup/NetworkMedia[the list of +supported capture media on various OSes] for details (several items in +there say "Unknown", which doesn't mean "Wireshark can't capture on +them", it means "we don't know whether it can capture on them"; we +expect that it will be able to capture on many of them, but we haven't +tried it ourselves - if you try one of those types and it works, please +update the wiki page accordingly. + +It can also read a variety of capture file formats, including: + +* pcap, used by libpcap, tcpdump and various other tools +* 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/Packet Grabber +captures +* RADCOM's WAN/LAN analyzer captures +* Viavi (previously Network Instruments) Observer captures +* Lucent/Ascend router debug output +* Toshiba's ISDN routers dump output +* captures from HP-UX nettl +* 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 text 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 (formerly Accellent) 5Views 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 +* Files from Aethra Telecommunications' PC108 software for their test +instruments +* Citrix NetScaler Trace files +* Android Logcat binary and text format logs +* Colasoft Capsa and Packet Builder 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 + +so that it can read traces from various network types, as captured by +other applications or equipment, even if it cannot itself capture on +those network types. + +=== Does Wireshark work on older versions of Windows such as Windows 7? + +Each major release branch of Wireshark supports the versions of Windows that are within their product lifecycle at the time of the “.0” release for that branch. +For example, Wireshark 3.2.0 was released in December 2019, shortly before Windows 7 reached the end of its extended support in January 2020. As a result, each of the Wireshark 3.2._x_ releases supports Windows 7, even after January 2020. +See the +link:https://www.wireshark.org/docs/wsug_html_chunked/ChIntroPlatforms.html[Microsoft Windows section of the User’s Guide] +and the +link:https://gitlab.com/wireshark/wireshark/-/wikis/Development/LifeCycle[End Of Life Planning section of the Release Life Cycle wiki page] +for more details. + +Npcap might not work well on Windows 8 and earlier, so you might want to install WinPcap instead. + +== Installing Wireshark + +=== I installed the Wireshark RPM (or other package); why did it install TShark but not Wireshark? + +Many distributions have separate Wireshark packages, one for non-GUI +components such as TShark, editcap, dumpcap, etc. and one for the GUI. +If this is the case on your system, there's probably a separate package +named “wireshark-qt”. Find it and install it. + +== Building Wireshark + +=== Why does building Wireshark fail due to missing headers (.h files)? + +If this is happening on Linux, it's likely due to missing development library packages. +For example, Debian and Ubuntu ship the GLib library in the libglib2.0-0 package, but ship its header files and other development assets in the libglib2.0-dev package. + +We maintain setup scripts (_*-setup.sh_) for many major distributions in the _tools_ directory of the Wireshark sources that can install the required development packages for you. + +== Crashes and other fatal errors + +=== I have an _XXX_ network card on my machine; if I try to capture on it, why does my machine crash or reset itself? + +This is almost certainly a problem with one or more of: + +* the operating system you're using; +* the device driver for the interface you're using; +* the libpcap/Npcap library and, if this is Windows, the Npcap device +driver; + +so: + +* if you are using Windows, see {npcap-main-url}[the Npcap support page] - check the "Patches, Bug Reports, Questions, Suggestions, +etc" section; +* if you are using some Linux distribution, some version of BSD, or some +other UNIX-flavored OS, you should report the problem to the company or +organization that produces the OS (in the case of a Linux distribution, +report the problem to whoever produces the distribution). + +=== Why does my machine crash or reset itself when I select "Start" from the "Capture" menu or select "Preferences" from the "Edit" menu? + +Both of those operations cause Wireshark to try to build a list of +the interfaces that it can open; it does so by getting a list of +interfaces and trying to open them. There is probably an OS, driver, or, +for Windows, Npcap bug that causes the system to crash when this +happens; see the previous question. + +== Capturing packets + +[#promiscsniff] +=== When I use Wireshark to capture packets, why do I see only packets to and from my machine, or not see all the traffic I'm expecting to see from or to the machine I'm trying to monitor? + +This might be because the interface on which you're capturing is +plugged into an Ethernet or Token Ring switch; on a switched network, +unicast traffic between two ports will not necessarily appear on other +ports - only broadcast and multicast traffic will be sent to all ports. + +Note that even if your machine is plugged into a hub, the "hub" may be +a switched hub, in which case you're still on a switched network. + +Note also that on the Linksys Web site, they say that their +auto-sensing hubs "broadcast the 10Mb packets to the port that operate +at 10Mb only and broadcast the 100Mb packets to the ports that operate +at 100Mb only", which would indicate that if you sniff on a 10Mb port, +you will not see traffic coming sent to a 100Mb port, and _vice versa_. +This problem has also been reported for Netgear dual-speed hubs, and may +exist for other "auto-sensing" or "dual-speed" hubs. + +Some switches have the ability to replicate all traffic on all ports to +a single port so that you can plug your analyzer into that single port +to sniff all traffic. You would have to check the documentation for the +switch to see if this is possible and, if so, to see how to do this. See +https://gitlab.com/wireshark/wireshark/-/wikis/SwitchReference[the switch reference page] on +https://gitlab.com/wireshark/wireshark/-/wikis[the Wireshark Wiki] for information on some +switches. (Note that it's a Wiki, so you can update or fix that +information, or add additional information on those switches or +information on new switches, yourself.) + +Note also that many firewall/NAT boxes have a switch built into them; +this includes many of the "cable/DSL router" boxes. If you have a box of +that sort, that has a switch with some number of Ethernet ports into +which you plug machines on your network, and another Ethernet port used +to connect to a cable or DSL modem, you can, at least, sniff traffic +between the machines on your network and the Internet by plugging the +Ethernet port on the router going to the modem, the Ethernet port on the +modem, and the machine on which you're running Wireshark into a hub +(make sure it's not a switching hub, and that, if it's a dual-speed hub, +all three of those ports are running at the same speed. + +If your machine is _not_ plugged into a switched network or a +dual-speed hub, or it is plugged into a switched network but the port is +set up to have all traffic replicated to it, the problem might be that +the network interface on which you're capturing doesn't support +"promiscuous" mode, or because your OS can't put the interface into +promiscuous mode. Normally, network interfaces supply to the host only: + +* packets sent to one of that host's link-layer addresses; +* broadcast packets; +* multicast packets sent to a multicast address that the host has +configured the interface to accept. + +Most network interfaces can also be put in "promiscuous" mode, in which +they supply to the host all network packets they see. Wireshark will try +to put the interface on which it's capturing into promiscuous mode +unless the "Capture packets in promiscuous mode" option is turned off in +the "Capture Options" dialog box, and TShark will try to put the +interface on which it's capturing into promiscuous mode unless the `-p` +option was specified. However, some network interfaces don't support +promiscuous mode, and some OSes might not allow interfaces to be put +into promiscuous mode. + +If the interface is not running in promiscuous mode, it won't see any +traffic that isn't intended to be seen by your machine. It *will* see +broadcast packets, and multicast packets sent to a multicast MAC address +the interface is set up to receive. + +You should ask the vendor of your network interface whether it supports +promiscuous mode. If it does, you should ask whoever supplied the driver +for the interface (the vendor, or the supplier of the OS you're running +on your machine) whether it supports promiscuous mode with that network +interface. + +In the case of wireless LAN interfaces, it appears that, when those +interfaces are promiscuously sniffing, they're running in a +significantly different mode from the mode that they run in when they're +just acting as network interfaces (to the extent that it would be a +significant effort for those drivers to support for promiscuously +sniffing _and_ acting as regular network interfaces at the same time), +so it may be that Windows drivers for those interfaces don't support +promiscuous mode. + +=== When I capture with Wireshark, why can't I see any TCP packets other than packets to and from my machine, even though another analyzer on the network sees those packets? + +You're probably not seeing _any_ packets other than unicast packets +to or from your machine, and broadcast and multicast packets; a switch +will normally send to a port only unicast traffic sent to the MAC +address for the interface on that port, and broadcast and multicast +traffic - it won't send to that port unicast traffic sent to a MAC +address for some other interface - and a network interface not in +promiscuous mode will receive only unicast traffic sent to the MAC +address for that interface, broadcast traffic, and multicast traffic +sent to a multicast MAC address the interface is set up to receive. + +TCP doesn't use broadcast or multicast, so you will only see your own +TCP traffic, but UDP services may use broadcast or multicast so you'll +see some UDP traffic - however, this is not a problem with TCP traffic, +it's a problem with unicast traffic, as you also won't see all UDP +traffic between other machines. + +I.e., this is probably link:#promiscsniff[the same question as this +earlier one]; see the response to that question. + +=== Why am I only seeing ARP packets when I try to capture traffic? + +You're probably on a switched network, and running Wireshark on a +machine that's not sending traffic to the switch and not being sent any +traffic from other machines on the switch. ARP packets are often +broadcast packets, which are sent to all switch ports. + +I.e., this is probably link:#promiscsniff[the same question as this +earlier one]; see the response to that question. + +=== Why am I not seeing any traffic when I try to capture traffic? + +Is the machine running Wireshark sending out any traffic on the +network interface on which you're capturing, or receiving any traffic on +that network, or is there any broadcast traffic on the network or +multicast traffic to a multicast group to which the machine running +Wireshark belongs? + +If not, this may just be a problem with promiscuous sniffing, either +due to running on a switched network or a dual-speed hub, or due to +problems with the interface not supporting promiscuous mode; see the +response to link:#promiscsniff[this earlier question]. + +Otherwise, on Windows, see the response to link:#capprobwin[this +question] and, on a UNIX-flavored OS, see the response to +link:#capprobunix[this question]. + +=== How do I put an interface into promiscuous mode? + +By not disabling promiscuous mode when running Wireshark or TShark. + +Note, however, that: + +* the form of promiscuous mode that libpcap (the library that programs +such as tcpdump, Wireshark, etc. use to do packet capture) turns on will +*not* necessarily be shown if you run `ifconfig` on the interface on a +UNIX system; +* some network interfaces might not support promiscuous mode, and some +drivers might not allow promiscuous mode to be turned on - see +link:#promiscsniff[this earlier question] for more information on that; +* the fact that you're not seeing any traffic, or are only seeing +broadcast traffic, or aren't seeing any non-broadcast traffic other than +traffic to or from the machine running Wireshark, does not mean that +promiscuous mode isn't on - see link:#promiscsniff[this earlier +question] for more information on that. + +I.e., this is probably link:#promiscsniff[the same question as this +earlier one]; see the response to that question. + +=== I can set a display filter just fine; why don't capture filters work? + +Capture filters currently use a different syntax than display +filters. Here's the corresponding section from the +https://www.wireshark.org/docs/man-pages/wireshark.html[wireshark(1)] +man page: + +"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." + +The capture filter syntax used by libpcap can be found in the +http://www.tcpdump.org/tcpdump_man.html[tcpdump(8)] man page. + +=== How can I capture packets with CRC errors? + +Wireshark can capture only the packets that the packet capture +library - libpcap on UNIX-flavored OSes, and the Npcap port to Windows +of libpcap on Windows - can capture, and libpcap/Npcap can capture only +the packets that the OS's raw packet capture mechanism (or the Npcap +driver, and the underlying OS networking code and network interface +drivers, on Windows) will allow it to capture. + +Unless the OS always supplies packets with errors such as invalid CRCs +to the raw packet capture mechanism, or can be configured to do so, +invalid CRCs to the raw packet capture mechanism, Wireshark - and other +programs that capture raw packets, such as tcpdump - cannot capture +those packets. You will have to determine whether your OS needs to be so +configured and, if so, can be so configured, configure it if necessary +and possible, and make whatever changes to libpcap and the packet +capture program you're using are necessary, if any, to support capturing +those packets. + +Most OSes probably do *not* support capturing packets with invalid CRCs +on Ethernet, and probably do not support it on most other link-layer +types. Some drivers on some OSes do support it, such as some Ethernet +drivers on FreeBSD; in those OSes, you might always get those packets, +or you might only get them if you capture in promiscuous mode (you'd +have to determine which is the case). + +Note that libpcap does not currently supply to programs that use it an +indication of whether the packet's CRC was invalid (because the drivers +themselves do not supply that information to the raw packet capture +mechanism); therefore, Wireshark will not indicate which packets had CRC +errors unless the FCS was captured (see the next question) and you're +using Wireshark 0.9.15 and later, in which case Wireshark will check the +CRC and indicate whether it's correct or not. + +=== How can I capture entire frames, including the FCS? + +Wireshark can only capture data that the packet capture library - +libpcap on UNIX-flavored OSes, and the Npcap port to Windows of libpcap +on Windows - can capture, and libpcap/Npcap can capture only the data +that the OS's raw packet capture mechanism (or the Npcap driver, and the +underlying OS networking code and network interface drivers, on Windows) +will allow it to capture. + +For any particular link-layer network type, unless the OS supplies the +FCS of a frame as part of the frame, or can be configured to do so, +Wireshark - and other programs that capture raw packets, such as tcpdump +- cannot capture the FCS of a frame. You will have to determine whether +your OS needs to be so configured and, if so, can be so configured, +configure it if necessary and possible, and make whatever changes to +libpcap and the packet capture program you're using are necessary, if +any, to support capturing the FCS of a frame. + +Most OSes do *not* support capturing the FCS of a frame on Ethernet, +and probably do not support it on most other link-layer types. Some +drivers on some OSes do support it, such as some (all?) Ethernet drivers +on NetBSD and possibly the driver for Apple's gigabit Ethernet interface +in macOS; in those OSes, you might always get the FCS, or you might only +get the FCS if you capture in promiscuous mode (you'd have to determine +which is the case). + +Versions of Wireshark prior to 0.9.15 will not treat an Ethernet FCS in +a captured packet as an FCS. 0.9.15 and later will attempt to determine +whether there's an FCS at the end of the frame and, if it thinks there +is, will display it as such, and will check whether it's the correct +CRC-32 value or not. + +=== I'm capturing packets on a machine on a VLAN; why don't the packets I'm capturing have VLAN tags? + +You might be capturing on what might be called a "VLAN interface" - +the way a particular OS makes VLANs plug into the networking stack +might, for example, be to have a network device object for the physical +interface, which takes VLAN packets, strips off the VLAN header and +constructs an Ethernet header, and passes that packet to an internal +network device object for the VLAN, which then passes the packets onto +various higher-level protocol implementations. + +In order to see the raw Ethernet packets, rather than "de-VLANized" +packets, you would have to capture not on the virtual interface for the +VLAN, but on the interface corresponding to the physical network device, +if possible. See https://gitlab.com/wireshark/wireshark/-/wikis/CaptureSetup/VLAN[the +Wireshark Wiki item on VLAN capturing] for details. + +=== Why does Wireshark hang after I stop a capture? + +The most likely reason for this is that Wireshark is trying to look +up an IP address in the capture to convert it to a name (so that, for +example, it can display the name in the source address or destination +address columns), and that lookup process is taking a very long time. + +Wireshark calls a routine in the OS of the machine on which it's +running to convert of IP addresses to the corresponding names. That +routine probably does one or more of: + +* a search of a system file listing IP addresses and names; +* a lookup using DNS; +* on UNIX systems, a lookup using NIS; +* on Windows systems, a NetBIOS-over-TCP query. + +If a DNS server that's used in an address lookup is not responding, the +lookup will fail, but will only fail after a timeout while the system +routine waits for a reply. + +In addition, on Windows systems, if the DNS lookup of the address +fails, either because the server isn't responding or because there are +no records in the DNS that could be used to map the address to a name, a +NetBIOS-over-TCP query will be made. That query involves sending a +message to the NetBIOS-over-TCP name service on that machine, asking for +the name and other information about the machine. If the machine isn't +running software that responds to those queries - for example, many +non-Windows machines wouldn't be running that software - the lookup will +only fail after a timeout. Those timeouts can cause the lookup to take a +long time. + +If you disable network address-to-name translation - for example, by +turning off the "Enable network name resolution" option in the "Capture +Options" dialog box for starting a network capture - the lookups of the +address won't be done, which may speed up the process of reading the +capture file after the capture is stopped. You can make that setting the +default by selecting "Preferences" from the "Edit" menu, turning off the +"Enable network name resolution" option in the "Name resolution" options +in the preferences dialog box, and using the "Save" button in that +dialog box; note that this will save _all_ your current preference +settings. + +If Wireshark hangs when reading a capture even with network name +resolution turned off, there might, for example, be a bug in one of +Wireshark's dissectors for a protocol causing it to loop infinitely. If +you're not running the most recent release of Wireshark, you should +first upgrade to that release, as, if there's a bug of that sort, it +might've been fixed in a release after the one you're running. If the +hang occurs in the most recent release of Wireshark, the bug should be +reported to mailto:wireshark-dev@wireshark.org[the Wireshark developers' +mailing list] at `wireshark-dev@wireshark.org`. + +On UNIX-flavored OSes, please try to force Wireshark to dump core, by +sending it a `SIGABRT` signal (usually signal 6) with the `kill` +command, and then get a stack trace if you have a debugger installed. A +stack trace can be obtained by using your debugger (`gdb` in this +example), the Wireshark binary, and the resulting core file. Here's an +example of how to use the gdb command `backtrace` to do so. + +---- +$ gdb wireshark core +(gdb) backtrace +..... prints the stack trace +(gdb) quit +$ +---- + +The core dump file may be named "wireshark.core" rather than "core" on +some platforms (e.g., BSD systems). + +Also, if at all possible, please send a copy of the capture file that +caused the problem. When capturing packets, Wireshark normally writes +captured packets to a temporary file, which will probably be in `/tmp` +or `/var/tmp` on UNIX-flavored OSes, `\TEMP` on the main system disk +(normally `\Documents and Settings\<your login name>\Local Settings\Temp` on the main system disk on Windows XP and +Server 2003, and `\Users\<your login name>\AppData\Local\Temp` on the main +system disk on Windows Vista and later, so the capture file will +probably be there. If you are capturing on a single interface, it will +have a name of the form, +`wireshark_<iface>_YYYYmmddHHMMSS_XXXXXX.<fmt>`, where <fmt> is the +capture file format (pcap or pcapng), and <iface> is the actual name of +the interface you are capturing on; otherwise, if you are capturing on +multiple interfaces, it will have a name of the form, +`wireshark_<N>_interfaces_YYYYmmddHHMMSS_XXXXXX.<fmt>`, where <N> is the +number of simultaneous interfaces you are capturing on. Please don't +send a trace file greater than 1 MB when compressed; instead, make it +available via FTP or HTTP, or say it's available but leave it up to a +developer to ask for it. If the trace file contains sensitive +information (e.g., passwords), then please do not send it. + +== Capturing packets on Windows + +[#capprobwin] +=== I'm running Wireshark on Windows; why does some network interface on my machine not show up in the list of interfaces in the "Interface:" field in the dialog box popped up by "Capture->Start", and/or why does Wireshark give me an error if I try to capture on that interface? + +Wireshark relies on the Npcap library, the Npcap device driver, +and the facilities that come with the OS on which it's running in +order to do captures. + +Therefore, if the OS, the Npcap library, or the Npcap driver don't +support capturing on a particular network interface device, Wireshark +won't be able to capture on that device. + +If an interface doesn't show up in the list of interfaces in the +"Interface:" field, and you know the name of the interface, try entering +that name in the "Interface:" field and capturing on that device. + +If the attempt to capture on it succeeds, the interface is somehow not +being reported by the mechanism Wireshark uses to get a list of +interfaces. Try listing the interfaces with WinDump; see +https://www.winpcap.org/windump/[the WinDump Web site] for information on using +WinDump. + +You would run WinDump with the `-D` flag; if it lists the interface, +please report this to +mailto:wireshark-dev@wireshark.org[wireshark-dev@wireshark.org] giving +full details of the problem, including + +* the operating system you're using, and the version of that operating +system; +* the type of network device you're using; +* the output of WinDump. + +If WinDump does _not_ list the interface, this is almost certainly a +problem with one or more of: + +* the operating system you're using; +* the device driver for the interface you're using; +* the Npcap library and/or the Npcap device driver; + +so first check {npcap-main-url}guide/npcap-users-guide.html[the Npcap User's Guide] to see if your problem is mentioned there. +If not, then see {npcap-main-url}[the main Npcap page] - check the "Patches, Bug Reports, Questions, Suggestions, etc" section. + +If you are having trouble capturing on a particular network interface, +first try capturing on that device with WinDump; see +https://www.winpcap.org/windump/[the WinDump Web site] for information on using +WinDump. + +If you can capture on the interface with WinDump, send mail to +mailto:wireshark-users@wireshark.org[wireshark-users@wireshark.org] +giving full details of the problem, including + +* the operating system you're using, and the version of that operating +system; +* the type of network device you're using; +* the error message you get from Wireshark. + +If you _cannot_ capture on the interface with WinDump, this is almost +certainly a problem with one or more of: + +* the operating system you're using; +* the device driver for the interface you're using; +* the Npcap library and/or the Npcap device driver; + +so first check {npcap-main-url}guide/npcap-users-guide.html[the Npcap User's Guide] to see if your problem is mentioned there. +If not, then see {npcap-main-url}[the main Npcap page] - check the "Patches, Bug Reports, Questions, Suggestions, etc" section. + +You may also want to ask the +mailto:wireshark-users@wireshark.org[wireshark-users@wireshark.org] and +the mailto:dev@nmap.org[dev@nmap.org] mailing +lists to see if anybody happens to know about the problem and know a +workaround or fix for the problem. (Note that you will have to subscribe +to that list in order to be allowed to mail to it; see +{npcap-main-url}[the Npcap support page] for information on the +mailing list.) In your mail, please give full details of the problem, as +described above, and also indicate that the problem occurs with WinDump, +not just with Wireshark. + +=== I'm running Wireshark on Windows; why do no network interfaces show up in the list of interfaces in the "Interface:" field in the dialog box popped up by "Capture->Start"? + +This is really link:#capprobwin[the same question as a previous one]; +see the response to that question. + +=== I'm running Wireshark on Windows; why am I not seeing any traffic being sent by the machine running Wireshark? + +If you are running some form of VPN client software, it might be +causing this problem; people have seen this problem when they have Check +Point's VPN software installed on their machine. If that's the cause of +the problem, you will have to remove the VPN software in order to have +Wireshark (or any other application using Npcap) see outgoing packets; +unfortunately, neither we nor the Npcap developers know any way to make +Npcap and the VPN software work well together. + +Also, some drivers for Windows (especially some wireless network +interface drivers) apparently do not, when running in promiscuous mode, +arrange that outgoing packets are delivered to the software that +requested that the interface run promiscuously; try turning promiscuous +mode off. + +=== When I capture on Windows in promiscuous mode, I can see packets other than those sent to or from my machine; however, those packets show up with a "Short Frame" indication, unlike packets to or from my machine. What should I do to arrange that I see those packets in their entirety? + +In at least some cases, this appears to be the result of PGPnet +running on the network interface on which you're capturing; turn it off +on that interface. + +=== I'm trying to capture 802.11 traffic on Windows; why am I not seeing any packets? + +You should first ensure that Npcap was installed with {npcap-main-url}/guide/npcap-devguide.html#npcap-feature-dot11[raw 802.11 support] and that monitor mode is enabled. + +At least some 802.11 card drivers on Windows appear not to see any +packets if they're running in promiscuous mode. Try turning promiscuous +mode off; you'll only be able to see packets sent by and received by +your machine, not third-party traffic, and it'll look like Ethernet +traffic and won't include any management or control frames, but that's a +limitation of the card drivers. + +// XXX Is this still relevant? +// See the archived +// https://web.archive.org/web/20090226193157/http://www.micro-logix.com/winpcap/Supported.asp[MicroLogix's +// list of cards supported with WinPcap] for information on support of +// various adapters and drivers with WinPcap. + +=== I'm trying to capture 802.11 traffic on Windows; why am I seeing packets received by the machine on which I'm capturing traffic, but not packets sent by that machine? + +This appears to be another problem with promiscuous mode; try turning +it off. + +=== I'm trying to capture Ethernet VLAN traffic on Windows, and I'm capturing on a "raw" Ethernet device rather than a "VLAN interface", so that I can see the VLAN headers; why am I seeing packets received by the machine on which I'm capturing traffic, but not packets sent by that machine? + +The way the Windows networking code works probably means that packets +are sent on a "VLAN interface" rather than the "raw" device, so packets +sent by the machine will only be seen when you capture on the "VLAN +interface". If so, you will be unable to see outgoing packets when +capturing on the "raw" device, so you are stuck with a choice between +seeing VLAN headers and seeing outgoing packets. + +== Capturing packets on UN*Xes + +[#capprobunix] +=== I'm running Wireshark on a UNIX-flavored OS; why does some network interface on my machine not show up in the list of interfaces in the "Interface:" field in the dialog box popped up by "Capture->Start", and/or why does Wireshark give me an error if I try to capture on that interface? + +You may need to run Wireshark from an account with sufficient +privileges to capture packets, such as the super-user account, or may +need to give your account sufficient privileges to capture packets. Only +those interfaces that Wireshark can open for capturing show up in that +list; if you don't have sufficient privileges to capture on any +interfaces, no interfaces will show up in the list. See +https://gitlab.com/wireshark/wireshark/-/wikis/CaptureSetup/CapturePrivileges[the Wireshark +Wiki item on capture privileges] for details on how to give a particular +account or account group capture privileges on platforms where that can +be done. + +If you are running Wireshark from an account with sufficient +privileges, then note that Wireshark relies on the libpcap library, and +on the facilities that come with the OS on which it's running in order +to do captures. On some OSes, those facilities aren't present by +default; see https://gitlab.com/wireshark/wireshark/-/wikis/CaptureSetup/CaptureSupport[the +Wireshark Wiki item on adding capture support] for details. + +And, even if you're running with an account that has sufficient +privileges to capture, and capture support is present in your OS, if the +OS or the libpcap library don't support capturing on a particular +network interface device or particular types of devices, Wireshark won't +be able to capture on that device. + +On Solaris, note that libpcap 0.6.2 and earlier didn't support Token +Ring interfaces; the current version, 0.7.2, does support Token Ring, +and the current version of Wireshark works with libpcap 0.7.2 and later. + +If an interface doesn't show up in the list of interfaces in the +"Interface:" field, and you know the name of the interface, try entering +that name in the "Interface:" field and capturing on that device. + +If the attempt to capture on it succeeds, the interface is somehow not +being reported by the mechanism Wireshark uses to get a list of +interfaces; please report this to +mailto:wireshark-dev@wireshark.org[wireshark-dev@wireshark.org] giving +full details of the problem, including + +* the operating system you're using, and the version of that operating +system (for Linux, give both the version number of the kernel and the +name and version number of the distribution you're using); +* the type of network device you're using. + +If you are having trouble capturing on a particular network interface, +and you've made sure that (on platforms that require it) you've arranged +that packet capture support is present, as per the above, first try +capturing on that device with `tcpdump`. + +If you can capture on the interface with `tcpdump`, send mail to +mailto:wireshark-users@wireshark.org[wireshark-users@wireshark.org] +giving full details of the problem, including + +* the operating system you're using, and the version of that operating +system (for Linux, give both the version number of the kernel and the +name and version number of the distribution you're using); +* the type of network device you're using; +* the error message you get from Wireshark. + +If you _cannot_ capture on the interface with `tcpdump`, this is almost +certainly a problem with one or more of: + +* the operating system you're using; +* the device driver for the interface you're using; +* the libpcap library; + +so you should report the problem to the company or organization that +produces the OS (in the case of a Linux distribution, report the problem +to whoever produces the distribution). + +You may also want to ask the +mailto:wireshark-users@wireshark.org[wireshark-users@wireshark.org] and +the +mailto:tcpdump-workers@lists.tcpdump.org[tcpdump-workers@lists.tcpdump.org] +mailing lists to see if anybody happens to know about the problem and +know a workaround or fix for the problem. In your mail, please give full +details of the problem, as described above, and also indicate that the +problem occurs with `tcpdump` not just with Wireshark. + +=== I'm running Wireshark on a UNIX-flavored OS; why do no network interfaces show up in the list of interfaces in the "Interface:" field in the dialog box popped up by "Capture->Start"? + +This is really link:#capprobunix[the same question as the previous +one]; see the response to that question. + +=== I'm capturing packets on Linux; why do the time stamps have only 100ms resolution, rather than 1us resolution? + +Wireshark gets time stamps from libpcap/Npcap, and libpcap/Npcap get +them from the OS kernel, so Wireshark - and any other program using +libpcap, such as tcpdump - is at the mercy of the time stamping code in +the OS for time stamps. + +At least on x86-based machines, Linux can get high-resolution time +stamps on newer processors with the Time Stamp Counter (TSC) register; +for example, Intel x86 processors, starting with the Pentium Pro, and +including all x86 processors since then, have had a TSC, and other +vendors probably added the TSC at some point to their families of x86 +processors. The Linux kernel must be configured with the CONFIG_X86_TSC +option enabled in order to use the TSC. Make sure this option is enabled +in your kernel. + +In addition, some Linux distributions may have bugs in their versions +of the kernel that cause packets not to be given high-resolution time +stamps even if the TSC is enabled. See, for example, bug 61111 for Red +Hat Linux 7.2. If your distribution has a bug such as this, you may have +to run a standard kernel from kernel.org in order to get high-resolution +time stamps. + +== Capturing packets on wireless LANs + +=== How can I capture raw 802.11 frames, including non-data (management, beacon) frames? + +That depends on the operating system on which you're running, and on +the 802.11 interface on which you're capturing. + +This would probably require that you capture in promiscuous mode or in +the mode called "monitor mode" or "RFMON mode". On some platforms, or +with some cards, this might require that you capture in monitor mode - +promiscuous mode might not be sufficient. If you want to capture traffic +on networks other than the one with which you're associated, you will +have to capture in monitor mode. + +Not all operating systems support capturing non-data packets and, even +on operating systems that do support it, not all drivers, and thus not +all interfaces, support it. Even on those that do, monitor mode might +not be supported by the operating system or by the drivers for all +interfaces. + +*NOTE:* an interface running in monitor mode will, on most if not all +platforms, not be able to act as a regular network interface; putting it +into monitor mode will, in effect, take your machine off of whatever +network it's on as long as the interface is in monitor mode, allowing it +only to passively capture packets. + +This means that you should disable name resolution when capturing in +monitor mode; otherwise, when Wireshark (or TShark, or tcpdump) tries to +display IP addresses as host names, it will probably block for a long +time trying to resolve the name because it will not be able to +communicate with any DNS or NIS servers. + +See https://gitlab.com/wireshark/wireshark/-/wikis/CaptureSetup/WLAN[the Wireshark Wiki +item on 802.11 capturing] for details. + +=== How do I capture on an 802.11 device in monitor mode? + +Whether you will be able to capture in monitor mode depends on the +operating system, adapter, and driver you're using. See +link:#raw_80211_sniff[the previous question] for information on monitor +mode, including a link to the Wireshark Wiki page that gives details on +802.11 capturing. + +== Viewing traffic + +=== Why am I seeing lots of packets with incorrect TCP checksums? + +If the packets that have incorrect TCP checksums are all being sent +by the machine on which Wireshark is running, this is probably because +the network interface on which you're capturing does TCP checksum +offloading. That means that the TCP checksum is added to the packet by +the network interface, not by the OS's TCP/IP stack; when capturing on +an interface, packets being sent by the host on which you're capturing +are directly handed to the capture interface by the OS, which means that +they are handed to the capture interface without a TCP checksum being +added to them. + +The only way to prevent this from happening would be to disable TCP +checksum offloading, but + +1. that might not even be possible on some OSes; +2. that could reduce networking performance significantly. + +However, you can disable the check that Wireshark does of the TCP +checksum, so that it won't report any packets as having TCP checksum +errors, and so that it won't refuse to do TCP reassembly due to a packet +having an incorrect TCP checksum. That can be set as an Wireshark +preference by selecting "Preferences" from the "Edit" menu, opening up +the "Protocols" list in the left-hand pane of the "Preferences" dialog +box, selecting "TCP", from that list, turning off the "Check the +validity of the TCP checksum when possible" option, clicking "Save" if +you want to save that setting in your preference file, and clicking +"OK". + +It can also be set on the Wireshark or TShark command line with a +`-o tcp.check_checksum:false` command-line flag, or manually set in your +preferences file by adding a `tcp.check_checksum:false` line. + +=== I've just installed Wireshark, and the traffic on my local LAN is boring. Where can I find more interesting captures? + +We have a collection of strange and exotic sample capture files at +https://gitlab.com/wireshark/wireshark/-/wikis/SampleCaptures[https://gitlab.com/wireshark/wireshark/-/wikis/SampleCaptures] + +=== Why doesn't Wireshark correctly identify RTP packets? It shows them only as UDP. + +Wireshark can identify a UDP datagram as containing a packet of a +particular protocol running atop UDP only if + +1. The protocol in question has a particular standard port number, and +the UDP source or destination port number is that port +2. Packets of that protocol can be identified by looking for a +"signature" of some type in the packet - i.e., some data that, if +Wireshark finds it in some particular part of a packet, means that the +packet is almost certainly a packet of that type. +3. Some _other_ traffic earlier in the capture indicated that, for +example, UDP traffic between two particular addresses and ports will be +RTP traffic. + +RTP doesn't have a standard port number, so 1) doesn't work; it doesn't, +as far as I know, have any "signature", so 2) doesn't work. + +That leaves 3). If there's RTSP traffic that sets up an RTP session, +then, at least in some cases, the RTSP dissector will set things up so +that subsequent RTP traffic will be identified. Currently, that's the +only place we do that; there may be other places. + +However, there will always be places where Wireshark is simply +*incapable* of deducing that a given UDP flow is RTP; a mechanism would +be needed to allow the user to specify that a given conversation should +be treated as RTP. As of Wireshark 0.8.16, such a mechanism exists; if +you select a UDP or TCP packet, the right mouse button menu will have a +"Decode As..." menu item, which will pop up a dialog box letting you +specify that the source port, the destination port, or both the source +and destination ports of the packet should be dissected as some +particular protocol. + +=== Why doesn't Wireshark show Yahoo Messenger packets in captures that contain Yahoo Messenger traffic? + +Wireshark only recognizes as Yahoo Messenger traffic packets to or +from TCP port 3050 that begin with "YPNS", "YHOO", or "YMSG". TCP +segments that start with the middle of a Yahoo Messenger packet that +takes more than one TCP segment will not be recognized as Yahoo +Messenger packets (even if the TCP segment also contains the beginning +of another Yahoo Messenger packet). + +== Filtering traffic + +=== I saved a filter and tried to use its name to filter the display; why do I get an "Unexpected end of filter string" error? + +You cannot use the name of a saved display filter as a filter. To +filter the display, you can enter a display filter expression - *not* +the name of a saved display filter - in the "Filter:" box at the bottom +of the display, and type the <Enter> key or press the "Apply" button +(that does not require you to have a saved filter), or, if you want to +use a saved filter, you can press the "Filter:" button, select the +filter in the dialog box that pops up, and press the "OK" button. + +=== How can I search for, or filter, packets that have a particular string anywhere in them? + +If you want to do this when capturing, you can't. That's a feature +that would be hard to implement in capture filters without changes to +the capture filter code, which, on many platforms, is in the OS kernel +and, on other platforms, is in the libpcap library. + +After capture, you can search for text by selecting _Edit→Find +Packet..._ and making sure _String_ is selected. Alternately, you can +use the "contains" display filter operator or "matches" operator if it's +supported on your system. + +=== How do I filter a capture to see traffic for virus XXX? + +For some viruses/worms there might be a capture filter to recognize +the virus traffic. Check the +https://gitlab.com/wireshark/wireshark/-/wikis/CaptureFilters[CaptureFilters] page on the +https://gitlab.com/wireshark/wireshark/-/wikis[Wireshark Wiki] to see if anybody's added +such a filter. + +Note that Wireshark was not designed to be an intrusion detection +system; you might be able to use it as an IDS, but in most cases +software designed to be an IDS, such as https://www.snort.org/[Snort] or +https://www.prelude-siem.org/[Prelude], will probably work better. + +== Questions Which Are Still Notable Even Though They Aren’t Asked Much Any More + +=== What's up with the name change? Is Wireshark a fork? + +In May of 2006, Gerald Combs (the original author of Ethereal) went +to work for CACE Technologies (best known for WinPcap). Unfortunately, +he had to leave the Ethereal trademarks behind. + +This left the project in an awkward position. The only reasonable way +to ensure the continued success of the project was to change the name. +This is how Wireshark was born. + +Wireshark is almost (but not quite) a fork. Normally a "fork" of an +open source project results in two names, web sites, development teams, +support infrastructures, etc. This is the case with Wireshark except for +one notable exception -- every member of the core development team is +now working on Wireshark. There has been no active development on +Ethereal since the name change. Several parts of the Ethereal web site` +(such as the mailing lists, source code repository, and build farm) have +gone offline. + +More information on the name change can be found here: + +* https://www.prweb.com/releases/2006/6/prweb396098.htm[Original press +release] +* https://www.linux.com/news/ethereal-changes-name-wireshark[NewsForge article] +* Many other articles in https://www.wireshark.org/bibliography.html[our +bibliography] diff --git a/doc/http3.md b/doc/http3.md new file mode 100644 index 0000000000..9fc10851ee --- /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 0000000000..eabac0d00a --- /dev/null +++ b/doc/idl2deb.adoc @@ -0,0 +1,82 @@ +include::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/idl2deb.pod b/doc/idl2deb.pod deleted file mode 100644 index 7daa798bcf..0000000000 --- a/doc/idl2deb.pod +++ /dev/null @@ -1,86 +0,0 @@ - -=head1 NAME - -idl2deb - Create a Debian package for CORBA monitoring from IDL - -=head1 SYNOPSIS - -B<idl2deb> -S< [ B<-d> E<lt>optsE<gt> ]> -S< [ B<--dbopts>=E<lt>optsE<gt> ]> -S< [ B<-e> E<lt>addressE<gt> ]> -S< [ B<--email>=E<lt>addressE<gt> ]> -S< [ B<-h> ]> -S< [ B<--help> ]> -S< [ B<-i> E<lt>idlfileE<gt> ]> -S< [ B<--idl>=E<lt>idlfileE<gt> ]> -S< [ B<-n> E<lt>nameE<gt> ]> -S< [ B<--name>=E<lt>nameE<gt> ]> -S< [ B<-p> ]> -S< [ B<--preserve> ]> -S< [ B<-v> ]> -S< [ B<--version> ]> - -=head1 DESCRIPTION - -This manual page documents briefly the B<idl2deb> command. B<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 analyser. - -=head1 OPTIONS - -=over 4 - -=item -d E<lt>optsE<gt> --dbopts=E<lt>optsE<gt> - -options for dpkg-buildpackage. - -=item -e E<lt>addressE<gt> --email=E<lt>addressE<gt> - -use e-mail address. - -=item -h --help - -print help and exit. - -=item -i E<lt>idlfileE<gt> --idl=E<lt>idlfileE<gt> - -IDL file to use (mandatory) - -=item -n E<lt>nameE<gt> --name=E<lt>nameE<gt> - -use user name. - -=item -p --preserve - -do not overwrite files. - -=item -v --version - -print version and exit. - -=back - -=head1 EXAMPLES - -/usr/bin/idl2deb -e me@foo.net -i bar.idl \-n "My Name" -d "-rfakeroot -uc -us"-d "-rfakeroot -uc -us" - -=head1 SEE ALSO - -A lot of tools are used, which you have to B<apt-get install>: wireshark-dev, python, cdbs, autotools-dev, debhelper, dpkg-dev. - -=head1 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. - -=head1 AUTHOR - -B<W. Borgert> Author. - -=head1 COPYRIGHT - -Copyright (C) 2003, 2005 W. Borger diff --git a/doc/idl2wrs.adoc b/doc/idl2wrs.adoc new file mode 100644 index 0000000000..43a910fc2a --- /dev/null +++ b/doc/idl2wrs.adoc @@ -0,0 +1,100 @@ +include::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/idl2wrs.pod b/doc/idl2wrs.pod deleted file mode 100644 index 38627ddc4e..0000000000 --- a/doc/idl2wrs.pod +++ /dev/null @@ -1,115 +0,0 @@ - -=head1 NAME - -idl2wrs - CORBA IDL to Wireshark Plugin Generator - -=head1 SYNOPSIS - -B<idl2wrs> E<lt>filenameE<gt> - -=head1 DESCRIPTION - -B<idl2wrs> is a program that takes a user specified B<CORBA IDL> -file and generates B<"C"> source code for a B<Wireshark> "plugin". - -This resulting file can be compiled as a B<Wireshark> plugin, and -used to monitor B<GIOP/IIOP> traffic that is using this IDL. - -B<idl2wrs> is actually a shell script wrapper for two B<Python> programs. -These programs are: - -=over 4 - -=item * B<wireshark_be.py> - -Contains the main IDL Visitor Class - -=item * B<wireshark_gen.py> - -Contains the Source Code Generator Class - -=back - -B<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. - - -=head1 OPTIONS - -Currently there are no options. B<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 - - - - -=head1 ENVIRONMENT - -B<idl2wrs> will look for B<wireshark_be.py> and B<wireshark_gen.py> in -B<$PYTHONPATH/site-packages/> and if not found, will try the current -directory B<./> - -The B<-p> option passed to omniidl (inside B<idl2wrs>) indicates where -B<wireshark_be.py> and B<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/python1.5/ - - -=head1 SEE ALSO - -wireshark(1), tshark(1) - - -=head1 NOTES - -B<idl2wrs> (including B<wireshark_be.py> and B<wireshark_gen.py>) are part of -the B<Wireshark> distribution. The latest version of B<Wireshark> can -be found at L<https://www.wireshark.org>. - -B<idl2wrs> uses B<omniidl>, an IDL parser, and can be found at -L<http://omniorb.sourceforge.net/> - -=head1 TODO - -Some of the more important things to do are: - -=over 4 - -=item * -Improve Explicit dissection code. - -=item * -Improve command line options. - -=item * -Improve decode algorithm when we have operation name collision. - -=back - -=head1 AUTHORS - - Original Author - -------- ------ - Frank Singleton <frank.singleton[AT]ericsson.com> - - - Contributors - ------------ - diff --git a/doc/make-authors-format.pl b/doc/make-authors-format.pl deleted file mode 100755 index 33d4a116a5..0000000000 --- a/doc/make-authors-format.pl +++ /dev/null @@ -1,96 +0,0 @@ -# Convert AUTHORS-SHORT file for use in man page and HTML documentation -# after processing through pod2man and pod2html. -# -# Must be called via perlnoutf. -# -# Copyright 2004 Graeme Hewson <ghewson@wormhole.me.uk> -# -# Wireshark - Network traffic analyzer -# By Gerald Combs <gerald@wireshark.org> -# Copyright 1998 Gerald Combs -# -# SPDX-License-Identifier: GPL-2.0-or-later -# - -use strict; - -print "=for html <pre>\n\n"; -print "=for man .nf\n\n"; - -while (<>) { - printline(); -} - -print "\n=for html </pre>\n"; -print "\n=for man .fi\n"; - -sub printline { - my $line = shift || $_; -# -# Translate UTF-8 characters to the E<> escapes handled by Pod::Man -# (and only those, since they're a subset of HTML entities) -# - $line =~ s/\xc3\x80/E<Agrave>/g; - $line =~ s/\xc3\x81/E<Aacute>/g; - $line =~ s/\xc3\x82/E<Acirc>/g; - $line =~ s/\xc3\x83/E<Atilde>/g; - $line =~ s/\xc3\x84/E<Auml>/g; - $line =~ s/\xc3\x85/E<Aring>/g; - $line =~ s/\xc3\x86/E<AElig>/g; - $line =~ s/\xc3\x87/E<Ccedil>/g; - $line =~ s/\xc3\x88/E<Egrave>/g; - $line =~ s/\xc3\x89/E<Eacute>/g; - $line =~ s/\xc3\x8a/E<Ecirc>/g; - $line =~ s/\xc3\x8b/E<Euml>/g; - $line =~ s/\xc3\x8c/E<Igrave>/g; - $line =~ s/\xc3\x8d/E<Iacute>/g; - $line =~ s/\xc3\x8e/E<Icirc>/g; - $line =~ s/\xc3\x8f/E<Iuml>/g; - $line =~ s/\xc3\x90/E<ETH>/g; - $line =~ s/\xc3\x91/E<Ntilde>/g; - $line =~ s/\xc3\x92/E<Ograve>/g; - $line =~ s/\xc3\x93/E<Oacute>/g; - $line =~ s/\xc3\x94/E<Ocirc>/g; - $line =~ s/\xc3\x95/E<Otilde>/g; - $line =~ s/\xc3\x96/E<Ouml>/g; - $line =~ s/\xc3\x98/E<Oslash>/g; - $line =~ s/\xc3\x99/E<Ugrave>/g; - $line =~ s/\xc3\x9a/E<Uacute>/g; - $line =~ s/\xc3\x9b/E<Ucirc>/g; - $line =~ s/\xc3\x9c/E<Uuml>/g; - $line =~ s/\xc3\x9d/E<Yacute>/g; - $line =~ s/\xc3\x9e/E<THORN>/g; - $line =~ s/\xc3\x9f/E<szlig>/g; - $line =~ s/\xc3\xa0/E<agrave>/g; - $line =~ s/\xc3\xa1/E<aacute>/g; - $line =~ s/\xc3\xa2/E<acirc>/g; - $line =~ s/\xc3\xa3/E<atilde>/g; - $line =~ s/\xc3\xa4/E<auml>/g; - $line =~ s/\xc3\xa5/E<aring>/g; - $line =~ s/\xc3\xa6/E<aelig>/g; - $line =~ s/\xc3\xa7/E<ccedil>/g; - $line =~ s/\xc3\xa8/E<egrave>/g; - $line =~ s/\xc3\xa9/E<eacute>/g; - $line =~ s/\xc3\xaa/E<ecirc>/g; - $line =~ s/\xc3\xab/E<euml>/g; - $line =~ s/\xc3\xac/E<igrave>/g; - $line =~ s/\xc3\xad/E<iacute>/g; - $line =~ s/\xc3\xae/E<icirc>/g; - $line =~ s/\xc3\xaf/E<iuml>/g; - $line =~ s/\xc3\xb0/E<eth>/g; - $line =~ s/\xc3\xb1/E<ntilde>/g; - $line =~ s/\xc3\xb2/E<ograve>/g; - $line =~ s/\xc3\xb3/E<oacute>/g; - $line =~ s/\xc3\xb4/E<ocirc>/g; - $line =~ s/\xc3\xb5/E<otilde>/g; - $line =~ s/\xc3\xb6/E<ouml>/g; - $line =~ s/\xc3\xb8/E<oslash>/g; - $line =~ s/\xc3\xb9/E<ugrave>/g; - $line =~ s/\xc3\xba/E<uacute>/g; - $line =~ s/\xc3\xbb/E<ucirc>/g; - $line =~ s/\xc3\xbc/E<uuml>/g; - $line =~ s/\xc3\xbd/E<yacute>/g; - $line =~ s/\xc3\xbe/E<thorn>/g; - $line =~ s/\xc3\xbf/E<yuml>/g; - print $line; -} diff --git a/doc/make-authors-short.pl b/doc/make-authors-short.pl deleted file mode 100755 index 5500bfd244..0000000000 --- a/doc/make-authors-short.pl +++ /dev/null @@ -1,40 +0,0 @@ -# Remove tasks from individual author entries from AUTHORS file -# for use in the about dialog. -# -# Must be called via perlnoutf. -# -# Copyright 2004 Ulf Lamping <ulf.lamping@web.de> -# -# Wireshark - Network traffic analyzer -# By Gerald Combs <gerald@wireshark.org> -# Copyright 1998 Gerald Combs -# -# SPDX-License-Identifier: GPL-2.0-or-later -# - -use strict; - -my $subinfo=0; -my $nextline; - -$_ = <>; -s/\xef\xbb\xbf//; # Skip UTF-8 byte order mark -print unless /^\n/; - -while (<>) { - if (/(.*?)\s*\{/) { - $subinfo = 1; - print "$1\n"; - } elsif (/\}/) { - $subinfo = 0; - if (($nextline = <>) !~ /^[\s]*$/) { - print STDERR "No blank line after '}', found: $nextline" - if $nextline =~ m/\{/; - print $nextline; - } - } elsif ($subinfo == 1) { - next; - } else { - print; - } -} diff --git a/doc/mergecap.adoc b/doc/mergecap.adoc new file mode 100644 index 0000000000..014331ca8d --- /dev/null +++ b/doc/mergecap.adoc @@ -0,0 +1,207 @@ +include::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/mergecap.pod b/doc/mergecap.pod deleted file mode 100644 index 671c5c68f6..0000000000 --- a/doc/mergecap.pod +++ /dev/null @@ -1,170 +0,0 @@ - -=head1 NAME - -mergecap - Merges two or more capture files into one - -=head1 SYNOPSIS - -B<mergecap> -S<[ B<-a> ]> -S<[ B<-F> E<lt>I<file format>E<gt> ]> -S<[ B<-h> ]> -S<[ B<-I> E<lt>I<IDB merge mode>E<gt> ]> -S<[ B<-s> E<lt>I<snaplen>E<gt> ]> -S<[ B<-v> ]> -S<[ B<-V> ]> -S<B<-w> E<lt>I<outfile>E<gt>|-> -E<lt>I<infile>E<gt> [E<lt>I<infile>E<gt> I<...>] - -=head1 DESCRIPTION - -B<Mergecap> is a program that combines multiple saved capture files into -a single output file specified by the B<-w> argument. B<Mergecap> knows -how to read B<pcap> capture files, including those of B<tcpdump>, -B<Wireshark>, and other tools that write captures in that format. - -By default, B<Mergecap> writes the capture file in B<pcap> format, and writes -all of the packets from the input capture files to the output file. - -B<Mergecap> is able to detect, read and write the same capture files that -are supported by B<Wireshark>. -The input files don't need a specific filename extension; the file -format and an optional gzip compression will be automatically detected. -Near the beginning of the DESCRIPTION section of wireshark(1) or -L<https://www.wireshark.org/docs/man-pages/wireshark.html> -is a detailed description of the way B<Wireshark> handles this, which is -the same way B<Mergecap> handles this. - -B<Mergecap> can write the file in several output formats. -The B<-F> flag can be used to specify the format in which to write the -capture file, B<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 B<-a> flag is specified. B<Mergecap> -assumes that frames within a single capture file are already stored in -chronological order. When the B<-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 B<pcap>, do not currently support WTAP_ENCAP_PER_PACKET. -This combination will cause the output file creation to fail. - -=head1 OPTIONS - -=over 4 - -=item -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 B<-a> is not specified, the contents of the input files -are merged in chronological order based on each frame's timestamp. - -Note: when merging, B<mergecap> assumes that packets within a capture -file are already in chronological order. - -=item -F E<lt>file formatE<gt> - -Sets the file format of the output capture file. B<Mergecap> can write -the file in several formats; B<mergecap -F> provides a list of the -available output formats. The default is to use the file format of the -first input file. - -=item -h - -Prints the version and options and exits. - -=item -I E<lt>IDB merge modeE<gt> - -Sets the Interface Description Block (IDB) merge mode to use during merging. -B<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: - - * 'B<none>': no merging of IDBs is performed, and instead all IDBs are - copied to the merged output file. - * 'B<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. This is the default mode. - * 'B<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. - -=item -s E<lt>snaplenE<gt> - -Sets the snapshot length to use when writing the data. -If the B<-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). - -=item -v - -Causes B<mergecap> to print a number of messages while it's working. - -=item -V - -Print the version and exit. - -=item -w E<lt>outfileE<gt>|- - -Sets the output filename. If the name is 'B<->', stdout will be used. -This setting is mandatory. - -=back - -=head1 EXAMPLES - -To merge two capture files together, 100 seconds apart use: - - capinfos -aeS a.pcap b.pcap - -(Let's suppose a.pcap starts at 1009932757 and b.pcap ends -at 873660281. 1009932757 - 873660281 - 100 = 136272376 -seconds.) - - editcap -t 136272376 b.pcap b-shifted.pcap - mergecap -w compare.pcap a.pcap b-shifted.pcap - -=head1 SEE ALSO - -pcap(3), wireshark(1), tshark(1), dumpcap(1), editcap(1), text2pcap(1), -pcap-filter(7) or tcpdump(8) - -=head1 NOTES - -B<Mergecap> is based heavily upon B<editcap> by Richard Sharpe -<sharpe[AT]ns.aus.com> and Guy Harris <guy[AT]alum.mit.edu>. - -B<Mergecap> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - -------- ------ - Scott Renfro <scott[AT]renfro.org> - - - Contributors - ------------ - Bill Guyton <guyton[AT]bguyton.com> diff --git a/doc/mmdbresolve.adoc b/doc/mmdbresolve.adoc new file mode 100644 index 0000000000..2509c54b56 --- /dev/null +++ b/doc/mmdbresolve.adoc @@ -0,0 +1,71 @@ +include::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/mmdbresolve.pod b/doc/mmdbresolve.pod deleted file mode 100644 index 43a827e448..0000000000 --- a/doc/mmdbresolve.pod +++ /dev/null @@ -1,69 +0,0 @@ - -=head1 NAME - -mmdbresolve - Read IPv4 and IPv6 addresses and print their IP geolocation information. - -=head1 SYNOPSIS - -B<mmdbresolve> -S<B<-f E<lt>dbfileE<gt>>> -S<[ B<-f E<lt>dbfileE<gt>> ]> -I<...> - -=head1 DESCRIPTION - -B<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. - -=head1 OPTIONS - -=over 4 - -=item -f - -Path to a MaxMind Database file. Multiple databases may be specified. - -=back - -=head1 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 - -=head1 SEE ALSO - -wireshark(1), tshark(1) - -=head1 NOTES - -B<mmdbresolve> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - --------------- - Gerald Combs <gerald[AT]wireshark.org> diff --git a/doc/packet-PROTOABBREV.c b/doc/packet-PROTOABBREV.c index 69262e8acc..a510fddb07 100644 --- a/doc/packet-PROTOABBREV.c +++ b/doc/packet-PROTOABBREV.c @@ -1,12 +1,12 @@ /* packet-PROTOABBREV.c * Routines for PROTONAME dissection - * Copyright 201x, YOUR_NAME <YOUR_EMAIL_ADDRESS> + * Copyright YEARS, YOUR_NAME <YOUR_EMAIL_ADDRESS> * * Wireshark - Network traffic analyzer * By Gerald Combs <gerald@wireshark.org> * Copyright 1998 Gerald Combs * - * SPDX-License-Identifier: GPL-2.0-or-later + * SPDX-License-Identifier: LICENSE */ /* @@ -14,7 +14,12 @@ * detailed documentation, etc.) */ -#include <config.h> +#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 */ @@ -24,7 +29,7 @@ ... #endif -#include <epan/packet.h> /* Should be first Wireshark include (other than config.h) */ +#include <epan/packet.h> /* Required dissection API header */ #include <epan/expert.h> /* Include only as needed */ #include <epan/prefs.h> /* Include only as needed */ @@ -37,26 +42,37 @@ #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_PROTOABBREV_FIELDABBREV = -1; -static expert_field ei_PROTOABBREV_EXPERTABBREV = EI_INIT; +static int proto_PROTOABBREV; +static int hf_FIELDABBREV; +static expert_field ei_PROTOABBREV_EXPERTABBREV; + +static dissector_handle_t PROTOABBREV_handle; +static dissector_handle_t PROTOABBREV_tls_handle; /* Global sample preference ("controls" display of numbers) */ -static gboolean pref_hex = FALSE; +static bool pref_hex = false; /* Global sample port preference - real port preferences should generally - * default to 0 unless there is an IANA-registered (or equivalent) port for your - * protocol. */ -#define PROTOABBREV_TCP_PORT 1234 -static guint tcp_port_pref = PROTOABBREV_TCP_PORT; + * 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 gint ett_PROTOABBREV = -1; +static int ett_PROTOABBREV; /* 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 @@ -72,8 +88,8 @@ dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, proto_item *ti, *expert_ti; proto_tree *PROTOABBREV_tree; /* Other misc. local variables. */ - guint offset = 0; - int len = 0; + unsigned offset = 0; + int len = 0; /*** HEURISTICS ***/ @@ -143,7 +159,15 @@ dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, col_clear(pinfo->cinfo, COL_INFO); #endif - col_set_str(pinfo->cinfo, COL_INFO, "XXX Request"); + /* 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 ***/ @@ -166,13 +190,13 @@ dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, /* 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_PROTOABBREV_FIELDABBREV, tvb, + 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_PROTOABBREV_FIELDABBREV isn't what's expected */ + /* 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... */ @@ -187,7 +211,7 @@ dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, /* Register the protocol with Wireshark. * - * This format is require because a script is used to build the C function that + * This format is required because a script is used to build the C function that * calls all the protocol registration. */ void @@ -199,15 +223,15 @@ proto_register_PROTOABBREV(void) /* Setup list of header fields See Section 1.5 of README.dissector for * details. */ static hf_register_info hf[] = { - { &hf_PROTOABBREV_FIELDABBREV, - { "FIELDNAME", "PROTOABBREV.FIELDABBREV", + { &hf_FIELDABBREV, + { "FIELDNAME", "FIELDFILTERNAME", FT_FIELDTYPE, FIELDDISPLAY, FIELDCONVERT, BITMASK, "FIELDDESCR", HFILL } } }; /* Setup protocol subtree array */ - static gint *ett[] = { + static int *ett[] = { &ett_PROTOABBREV }; @@ -220,8 +244,7 @@ proto_register_PROTOABBREV(void) }; /* Register the protocol name and description */ - proto_PROTOABBREV = proto_register_protocol("PROTONAME", - "PROTOSHORTNAME", "PROTOABBREV"); + 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)); @@ -231,6 +254,18 @@ proto_register_PROTOABBREV(void) 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 @@ -261,9 +296,10 @@ proto_register_PROTOABBREV(void) &pref_hex); /* Register an example port preference */ - prefs_register_uint_preference(PROTOABBREV_module, "tcp.port", "PROTOABBREV TCP Port", - " PROTOABBREV TCP port if other than the default", - 10, &tcp_port_pref); + 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. @@ -276,7 +312,7 @@ proto_register_PROTOABBREV(void) * 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 if you perform registration + * 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. @@ -284,35 +320,39 @@ proto_register_PROTOABBREV(void) void proto_reg_handoff_PROTOABBREV(void) { - static gboolean initialized = FALSE; - static dissector_handle_t PROTOABBREV_handle; - static int current_port; + static bool initialized = false; + static int current_tls_port_pref; if (!initialized) { - /* Use create_dissector_handle() to indicate that - * dissect_PROTOABBREV() returns the number of bytes it dissected (or 0 - * if it thinks the packet does not belong to PROTONAME). + /* Simple port preferences like TCP can be registered as automatic + * Decode As preferences. */ - PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV, - proto_PROTOABBREV); - initialized = TRUE; + 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 PROTOABBREV_handle and the value the preference had at the time - * you registered. The PROTOABBREV_handle value and the value of the - * preference can be saved using local statics in this - * function (proto_reg_handoff). + * the value the preference had at the time you registered, which + * can be saved using local statics in this function (proto_reg_handoff). */ - dissector_delete_uint("tcp.port", current_port, PROTOABBREV_handle); + ssl_dissector_delete(current_tls_port_pref, PROTOABBREV_tls_handle); } - current_port = tcp_port_pref; - - dissector_add_uint("tcp.port", current_port, PROTOABBREV_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 @@ -322,15 +362,7 @@ proto_reg_handoff_PROTOABBREV(void) void proto_reg_handoff_PROTOABBREV(void) { - dissector_handle_t PROTOABBREV_handle; - - /* Use create_dissector_handle() to indicate that dissect_PROTOABBREV() - * returns the number of bytes it dissected (or 0 if it thinks the packet - * does not belong to PROTONAME). - */ - PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV, - proto_PROTOABBREV); - dissector_add_uint_with_preference("tcp.port", PROTOABBREV_TCP_PORT, PROTOABBREV_handle); + dissector_add_uint_range_with_preference("tcp.port", PROTOABBREV_TCP_PORTS, PROTOABBREV_handle); } #endif diff --git a/doc/perlnoutf.pl b/doc/perlnoutf.pl deleted file mode 100755 index 8a6fea3395..0000000000 --- a/doc/perlnoutf.pl +++ /dev/null @@ -1,22 +0,0 @@ -#!/usr/bin/perl -w -# Call another Perl script, passing our caller's arguments, with -# environment variables unset so perl doesn't interpret bytes as UTF-8 -# characters. -# -# Copyright 2004 Graeme Hewson <ghewson@wormhole.me.uk> -# -# Wireshark - Network traffic analyzer -# By Gerald Combs <gerald@wireshark.org> -# Copyright 1998 Gerald Combs -# -# SPDX-License-Identifier: GPL-2.0-or-later -# - -use strict; - -delete $ENV{LANG}; -delete $ENV{LANGUAGE}; -delete $ENV{LC_ALL}; -delete $ENV{LC_CTYPE}; - -system("$^X -w @ARGV"); diff --git a/doc/plugins.example/CMakeLists.txt b/doc/plugins.example/CMakeLists.txt new file mode 100644 index 0000000000..a685ab37a2 --- /dev/null +++ b/doc/plugins.example/CMakeLists.txt @@ -0,0 +1,78 @@ +# 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 "" + SUFFIX "${Wireshark_PLUGIN_SUFFIX_EPAN}" + 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 index 04bc5885eb..27d6f48d4d 100644 --- a/doc/plugins.example/README +++ b/doc/plugins.example/README @@ -1,13 +1,35 @@ -This is an example of how to build a Wireshark plugin out-of-tree. +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. -Tested on Linux using GCC 7. Note this builds against Wireshark's *installed* -version. You should of course adapt to your own needs. +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: -$ autoreconf -v -i -$ PREFIX=/usr/local -$ ./configure --prefix="$PREFIX" PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig" +$ mkdir build && cd build +$ cmake .. $ make -$ sudo make install # or single-user: make install-home +$ 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/configure.ac b/doc/plugins.example/configure.ac deleted file mode 100644 index df66a02cc2..0000000000 --- a/doc/plugins.example/configure.ac +++ /dev/null @@ -1,38 +0,0 @@ -dnl Process this file with autoconf to produce a configure script. -dnl -dnl This file is free software; as a special exception the author gives -dnl unlimited permission to copy and/or distribute it, with or without -dnl modifications, as long as this notice is preserved. -dnl -dnl This program is distributed in the hope that it will be useful, but -dnl WITHOUT ANY WARRANTY, to the extent permitted by law; without even the -dnl implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - -AC_INIT([Wireshark Hello Plugin], [0.0.1]) - -AM_INIT_AUTOMAKE([foreign]) - -AC_PREREQ([2.62]) - -LT_PREREQ([2.2.2]) -LT_INIT([disable-static dlopen]) - -AC_CONFIG_SRCDIR([hello.c]) - -dnl Requires Wireshark 2.5.0 or greater. -PKG_CHECK_MODULES([WIRESHARK], [wireshark >= 2.5]) - -saved_CFLAGS="$CFLAGS"; saved_LIBS="$LIBS"; -CFLAGS="$WIRESHARK_CFLAGS" -LIBS="$WIRESHARK_LIBS" -AC_CHECK_FUNCS([proto_register_plugin], - [AC_DEFINE([HAVE_PLUGINS], 1, [Define to 1 if Wireshark supports loading plugins])], - [AC_MSG_ERROR([Wireshark was compiled without support for plugins])] -) -CFLAGS="$saved_CFLAGS"; LIBS="$saved_LIBS" - -AC_CONFIG_HEADER([config.h]) - -AC_CONFIG_FILES([Makefile]) - -AC_OUTPUT diff --git a/doc/plugins.example/hello.c b/doc/plugins.example/hello.c index 52c4a50ec6..6536a47805 100644 --- a/doc/plugins.example/hello.c +++ b/doc/plugins.example/hello.c @@ -7,33 +7,23 @@ * SPDX-License-Identifier: GPL-2.0-or-later */ -#ifdef HAVE_CONFIG_H -#include "config.h" -#endif - +#define WS_BUILD_DLL +#include <wireshark.h> +#include <wsutil/plugins.h> #include <epan/packet.h> #include <epan/proto.h> -#include <ws_attributes.h> #ifndef VERSION #define VERSION "0.0.0" #endif -#define DLL_PUBLIC __attribute__((__visibility__("default"))) - -DLL_PUBLIC const gchar plugin_version[] = VERSION; -DLL_PUBLIC const gchar plugin_release[] = VERSION_RELEASE; - -DLL_PUBLIC void plugin_register(void); - - -static int proto_hello = -1; +static int proto_hello; 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); + proto_tree_add_protocol_format(tree, proto_hello, tvb, 0, -1, "This is Hello version %s, a Wireshark postdissector plugin prototype", VERSION); return tvb_captured_length(tvb); } @@ -51,7 +41,7 @@ proto_reg_handoff_hello(void) /* empty */ } -void +static void plugin_register(void) { static proto_plugin plug; @@ -60,3 +50,14 @@ plugin_register(void) plug.register_handoff = proto_reg_handoff_hello; /* or NULL */ proto_register_plugin(&plug); } + +static struct ws_module module = { + .flags = WS_PLUGIN_DESC_DISSECTOR, + .version = VERSION, + .spdx_id = "GPL-2.0-or-later", + .home_url = "Your-URL-here", + .blurb = "Hello world for Wireshark plugin development", + .register_cb = &plugin_register, +}; + +WIRESHARK_PLUGIN_REGISTER_EPAN(&module, 0) diff --git a/doc/randpkt.pod b/doc/randpkt.adoc index eba131ebd4..0d399e140b 100644 --- a/doc/randpkt.pod +++ b/doc/randpkt.adoc @@ -1,58 +1,99 @@ +include::attributes.adoc[] += randpkt(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{stylesheet} -=head1 NAME +== NAME -randpkt - Random Packet Generator +randpkt - Random packet generator -=head1 SYNOPSIS +== SYNOPSIS -B<randpkt> -S<[ B<-b> E<lt>maxbytesE<gt> ]> -S<[ B<-c> E<lt>countE<gt> ]> -S<[ B<-t> E<lt>typeE<gt> ]> -E<lt>filenameE<gt> +[manarg] +*randpkt* +[ *-b* <maxbytes> ] +[ *-c* <count> ] +[ *-F* <file format> ] +[ *-r* ] +[ *-t* <type> ] +<filename> -=head1 DESCRIPTION +[manarg] +*randpkt* +*-h|--help* -B<randpkt> is a small utility that creates a B<pcap> trace file -full of random packets. +[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. -B<randpkt> produces I<very bad> packets. +*randpkt* produces __very bad__ packets. -When creating packets of a certain type, B<randpkt> uses a sample -packet that is stored internally to B<randpkt>. It uses this as the +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, B<randpkt> +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. -=head1 OPTIONS - -=over 4 - -=item -b E<lt>maxbytesE<gt> +== OPTIONS +-b <maxbytes>:: ++ +-- Default 5000. Defines the maximum number of bytes added to the sample packet. -If you choose a B<maxbytes> value that is less than the size of the +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! B<randpkt> exits on that condition. - -=item -c E<lt>countE<gt> +packet... not much variance there! *randpkt* exits on that condition. +-- +-c <count>:: ++ +-- Default 1000. Defines the number of packets to generate. - -=item -t E<lt>typeE<gt> - +-- + +-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: @@ -80,10 +121,14 @@ Defines the type of packet to generate: 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. -=back +include::diagnostic-options.adoc[] -=head1 EXAMPLES +== EXAMPLES To see a description of the randpkt options use: @@ -91,12 +136,12 @@ To see a description of the randpkt options use: To generate a capture file with 1000 DNS packets use: - randpkt -b 500 -t dns rand_dns.pcap + 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.pcap + randpkt -b 100 -c 1 -t llc single_llc.pcapng -=head1 SEE ALSO +== SEE ALSO -pcap(3), editcap(1) +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 index 72ecf2a616..0062f10d3b 100644 --- a/doc/randpkt.txt +++ b/doc/randpkt.txt @@ -52,7 +52,7 @@ in the following locations. 2) Type in the bytes from your sample packet /* Ethernet, indicating ARP */ - guint8 pkt_arp[] = { + uint8_t pkt_arp[] = { 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x32, 0x25, 0x0f, 0xff, diff --git a/doc/randpktdump.adoc b/doc/randpktdump.adoc new file mode 100644 index 0000000000..03763c8e1d --- /dev/null +++ b/doc/randpktdump.adoc @@ -0,0 +1,142 @@ +include::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/randpktdump.pod b/doc/randpktdump.pod deleted file mode 100644 index aa193e83fb..0000000000 --- a/doc/randpktdump.pod +++ /dev/null @@ -1,142 +0,0 @@ - -=head1 NAME - -randpktdump - Provide an interface to generate random captures using randpkt - -=head1 SYNOPSIS - -B<randpktdump> -S<[ B<--help> ]> -S<[ B<--version> ]> -S<[ B<--extcap-interfaces> ]> -S<[ B<--extcap-dlts> ]> -S<[ B<--extcap-interface>=E<lt>interfaceE<gt> ]> -S<[ B<--extcap-config> ]> -S<[ B<--capture> ]> -S<[ B<--fifo>=E<lt>path to file or pipeE<gt> ]> -S<[ B<--maxbytes>=E<lt>bytesE<gt> ]> -S<[ B<--random-type>=E<lt>true|falseE<gt> ]> -S<[ B<--all-random>=E<lt>true|falseE<gt> ]> -S<[ B<--type>=E<lt>packet typeE<gt> ]> - -=head1 DESCRIPTION - -B<randpktdump> is a extcap tool that provides access to the random -packet generator (randpkt). It is mainly used for testing and -educational purpose. - -=head1 OPTIONS - -=over 4 - -=item --help - -Print program arguments. - -=item --version - -Print program version. - -=item --extcap-interfaces - -List available interfaces. - -=item --extcap-interface=E<lt>interfaceE<gt> - -Use specified interfaces. - -=item --extcap-dlts - -List DLTs of specified interface. - -=item --extcap-config - -List configuration options of specified interface. - -=item --capture - -Start capturing from specified interface save saved it in place specified by --fifo. - -=item --fifo=E<lt>path to file or pipeE<gt> - -Save captured packet to file or send it through pipe. - -=item --maxbytes=E<lt>bytesE<gt> - -Set the max number of bytes per packet. - -=item --random-type - -Choose a random packet type for all packets if set to true. - -=item --all-random - -Choose a different random packet type for each packet if set to true. - -=item --type=E<lt>packet typeE<gt> - -Use the selected packet type. To list all the available packet type, run randpktdump --help. - -=back - -=head1 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=--random-type}{display=Random type}{type=boolean}{default=false}{tooltip=The packets type is randomly choosen} - arg {number=3}{call=--all-random}{display=All random packets}{type=boolean}{default=false}{tooltip=Packet type for each packet is randomly choosen} - arg {number=4}{call=--type}{display=Type of packet}{type=selector}{tooltip=Type of packet to generate} - value {arg=4}{value=arp}{display=Address Resolution Protocol} - [...] - value {arg=4}{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 application. - -=head1 SEE ALSO - -wireshark(1), tshark(1), dumpcap(1), extcap(4), randpkt(1) - -=head1 NOTES - -B<randpktdump> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - --------------- - Dario Lombardo <lomato[AT]gmail.com> diff --git a/doc/rawshark.adoc b/doc/rawshark.adoc new file mode 100644 index 0000000000..b0976e2db1 --- /dev/null +++ b/doc/rawshark.adoc @@ -0,0 +1,560 @@ +include::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-filter <read (display) filter>:: ++ +-- +Cause the specified filter (which uses the syntax of read/display filters, +rather than that of capture filters) to be applied before printing the output. +Read filters and display filters are synonymous in *rawshark*. +-- + +-s:: +Allows standard pcap files to be used as input, by skipping over the 24 +byte pcap file header. + +-S:: ++ +-- +Use the specified format string to print each field. The following formats +are supported: + +*%D* Field name or description, e.g. "Type" for dns.qry.type + +*%N* Base 10 numeric value of the field. + +*%S* String value of the field. + +For something similar to Wireshark's standard display ("Type: A (1)") you +could use *%D: %S (%N)*. +-- + +-v|--version:: +Print the full version information and exit. + +-Y|--display-filter <read (display) filter>:: ++ +-- +Cause the specified filter (which uses the syntax of read/display filters, +rather than that of capture filters) to be applied before printing the output. +Read filters and display filters are synonymous in *rawshark*. +-- + +include::dissection-options.adoc[tags=!tshark;!decode_as] + +include::diagnostic-options.adoc[] + +== READ FILTER SYNTAX + +For a complete table of protocol and protocol fields that are filterable +in *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/rawshark.pod b/doc/rawshark.pod deleted file mode 100644 index 66a66f8feb..0000000000 --- a/doc/rawshark.pod +++ /dev/null @@ -1,550 +0,0 @@ - -=head1 NAME - -rawshark - Dump and analyze raw pcap data - -=head1 SYNOPSIS - -B<rawshark> -S<[ B<-d> E<lt>encap:linktypeE<gt>|E<lt>proto:protonameE<gt> ]> -S<[ B<-F> E<lt>field to displayE<gt> ]> -S<[ B<-h> ]> -S<[ B<-l> ]> -S<[ B<-m> E<lt>bytesE<gt> ]> -S<[ B<-n> ]> -S<[ B<-N> E<lt>name resolving flagsE<gt> ]> -S<[ B<-o> E<lt>preference settingE<gt> ] ...> -S<[ B<-p> ]> -S<[ B<-r> E<lt>pipeE<gt>|- ]> -S<[ B<-R> E<lt>read (display) filterE<gt> ]> -S<[ B<-s> ]> -S<[ B<-S> E<lt>field formatE<gt> ]> -S<[ B<-t> a|ad|adoy|d|dd|e|r|u|ud|udoy ]> -S<[ B<-v> ]> - -=head1 DESCRIPTION - -B<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. - -=head1 INPUT - -Unlike B<TShark>, B<Rawshark> makes no assumptions about encapsulation or -input. The B<-d> and B<-r> flags must be specified in order for it to run. -One or more B<-F> flags should be specified in order for the output to be -useful. The other flags listed above follow the same conventions as -B<Wireshark> and B<TShark>. - -B<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 B<-p> is supplied B<rawshark> expects the following format. This -matches the I<struct pcap_pkthdr> structure and packet data used in -libpcap/WinPcap. This structure's format is platform-dependent; the -size of the I<tv_sec> field in the I<struct timeval> structure could be -32 bits or 64 bits. For B<rawshark> to work, the layout of the -structure in the input must match the layout of the structure in -B<rawshark>. Note that this format will probably be the same as the -previous format if B<rawshark> is a 32-bit program, but will not -necessarily be the same if B<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 B<rawshark> is running. - -=head1 OUTPUT - -If one or more fields are specified via the B<-F> flag, B<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 B<-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 B<-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. - -=head1 OPTIONS - -=over 4 - -=item -d E<lt>encapsulationE<gt> - -Specify how the packet data should be dissected. The encapsulation is of the -form I<type>B<:>I<value>, where I<type> is one of: - -B<encap>:I<name> Packet data should be dissected using the -libpcap/WinPcap data link type (DLT) I<name>, e.g. B<encap:EN10MB> for -Ethernet. Names are converted using pcap_datalink_name_to_val(). -A complete list of DLTs can be found at -L<http://www.tcpdump.org/linktypes.html>. - -B<encap>:I<number> Packet data should be dissected using the -libpcap/WinPcap LINKTYPE_ I<number>, e.g. B<encap:105> for raw IEEE -802.11 or B<encap:101> for raw IP. - -B<proto>:I<protocol> Packet data should be passed to the specified Wireshark -protocol dissector, e.g. B<proto:http> for HTTP data. - -=item -F E<lt>field to displayE<gt> - -Add the matching field to the output. Fields are any valid display filter -field. More than one B<-F> flag may be specified, and each field can match -multiple times in a given packet. A single field may be specified per B<-F> -flag. If you want to apply a display filter, use the B<-R> flag. - -=item -h - -Print the version and options and exits. - -=item -l - -Flush the standard output after the information for each packet is -printed. (This is not, strictly speaking, line-buffered if B<-V> -was specified; however, it is the same as line-buffered if B<-V> wasn't -specified, as only one line is printed for each packet, and, as B<-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 B<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 B<TShark> sees the -packet and generates that output, rather than seeing it only when the -standard output buffer containing that data fills up. - -=item -m E<lt>memory limit bytesE<gt> - -Limit rawshark's memory usage to the specified number of bytes. POSIX -(non-Windows) only. - -=item -n - -Disable network object name resolution (such as hostname, TCP and UDP port -names), the B<-N> flag might override this one. - -=item -N E<lt>name resolving flagsE<gt> - -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 flag overrides B<-n> if both B<-N> and B<-n> are -present. If both B<-N> and B<-n> flags are not present, all name resolutions are -turned on. - -The argument is a string that may contain the letters: - -B<m> to enable MAC address resolution - -B<n> to enable network address resolution - -B<N> to enable using external resolvers (e.g., DNS) for network address -resolution - -B<t> to enable transport-layer port number resolution - -B<d> to enable resolution from captured DNS packets - -=item -o E<lt>preferenceE<gt>:E<lt>valueE<gt> - -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 I<prefname>B<:>I<value>, where I<prefname> is the name of the -preference (which is the same name that would appear in the preference -file), and I<value> is the value to which it should be set. - -=item -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. - -=item -r E<lt>pipeE<gt>|- - -Read packet data from I<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. - -=item -R E<lt>read (display) filterE<gt> - -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. - -=item -s - -Allows standard pcap files to be used as input, by skipping over the 24 -byte pcap file header. - -=item -S - -Use the specified format string to print each field. The following formats -are supported: - -B<%D> Field name or description, e.g. "Type" for dns.qry.type - -B<%N> Base 10 numeric value of the field. - -B<%S> String value of the field. - -For something similar to Wireshark's standard display ("Type: A (1)") you -could use B<%D: %S (%N)>. - -=item -t a|ad|adoy|d|dd|e|r|u|ud|udoy - -Set the format of the packet timestamp printed in summary lines. -The format can be one of: - -B<a> absolute: The absolute time, as local time in your time zone, -is the actual time the packet was captured, with no date displayed - -B<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 - -B<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 - -B<d> delta: The delta time is the time since the previous packet was -captured - -B<dd> delta_displayed: The delta_displayed time is the time since the -previous displayed packet was captured - -B<e> epoch: The time in seconds since epoch (Jan 1, 1970 00:00:00) - -B<r> relative: The relative time is the time elapsed between the first packet -and the current packet - -B<u> UTC: The absolute time, as UTC, is the actual time the packet was -captured, with no date displayed - -B<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 - -B<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 - -The default format is relative. - -=item -v - -Print the version and exit. - -=back - -=head1 READ FILTER SYNTAX - -For a complete table of protocol and protocol fields that are filterable -in B<TShark> see the wireshark-filter(4) manual page. - -=head1 FILES - -These files contains various B<Wireshark> configuration values. - -=over 4 - -=item Preferences - -The F<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 B<-o> is used (possibly more than once), it will -in turn override values from the preferences files. - -The preferences settings are in the form I<prefname>B<:>I<value>, -one per line, -where I<prefname> is the name of the preference -and I<value> is the value to -which it should be set; white space is allowed between B<:> and -I<value>. A preference setting can be continued on subsequent lines by -indenting the continuation lines with white space. A B<#> 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 F<wireshark> directory -under the F<share> subdirectory of the main installation directory (for -example, F</usr/local/share/wireshark/preferences>) on UNIX-compatible -systems, and in the main installation directory (for example, -F<C:\Program Files\Wireshark\preferences>) on Windows systems. - -The personal preferences file is looked for in -F<$XDG_CONFIG_HOME/wireshark/preferences> -(or, if F<$XDG_CONFIG_HOME/wireshark> does not exist while F<$HOME/.wireshark> -is present, F<$HOME/.wireshark/preferences>) on -UNIX-compatible systems and F<%APPDATA%\Wireshark\preferences> (or, if -%APPDATA% isn't defined, F<%USERPROFILE%\Application -Data\Wireshark\preferences>) on Windows systems. - -=item Disabled (Enabled) Protocols - -The F<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 F<disabled_protos> file uses the same directory as the global -preferences file. - -The personal F<disabled_protos> file uses the same directory as the -personal preferences file. - -=item Name Resolution (hosts) - -If the personal F<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 F<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 and WinPcap on Windows. As such the Wireshark personal F<hosts> file -will not be consulted for capture filter name resolution. - -=item 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 F<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". - -=item Name Resolution (ethers) - -The F<ethers> files are consulted to correlate 6-byte hardware addresses to -names. First the personal F<ethers> file is tried and if an address is not -found there the global F<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 F<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 F<ethers> file is looked for in the F</etc> directory on -UNIX-compatible systems, and in the main installation directory (for -example, F<C:\Program Files\Wireshark>) on Windows systems. - -The personal F<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 WinPcap on Windows. As such the Wireshark personal F<ethers> file -will not be consulted for capture filter name resolution. - -=item Name Resolution (manuf) - -The F<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 F<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 F<manuf> file is looked for in the same directory as the global -preferences file. - -=item Name Resolution (services) - -The F<services> file is used to translate port numbers into names. - -The file has the standard F<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 - -=item Name Resolution (ipxnets) - -The F<ipxnets> files are used to correlate 4-byte IPX network numbers to -names. First the global F<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 F<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 F<ipxnets> file: - - C0.A8.2C.00 HR - c0-a8-1c-00 CEO - 00:00:BE:EF IT_Server1 - 110f FileServer3 - -The global F<ipxnets> file is looked for in the F</etc> directory on -UNIX-compatible systems, and in the main installation directory (for -example, F<C:\Program Files\Wireshark>) on Windows systems. - -The personal F<ipxnets> file is looked for in the same directory as the -personal preferences file. - -=back - -=head1 ENVIRONMENT VARIABLES - -=over 4 - -=item WIRESHARK_APPDATA - -On Windows, Wireshark normally stores all application data in %APPDATA% or -%USERPROFILE%. You can override the default location by exporting this -environment variable to specify an alternate location. - -=item 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 I<README.wmem> in the source distribution for -details. - -=item 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 *NIX. - -=item 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 *NIX. - -=item 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. - -=item 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. - -=item WIRESHARK_ABORT_ON_DISSECTOR_BUG - -If this environment variable is set, B<Rawshark> will call abort(3) -when a dissector bug is encountered. abort(3) will cause the program to -exit abnormally; if you are running B<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. - -=item WIRESHARK_ABORT_ON_TOO_MANY_ITEMS - -If this environment variable is set, B<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 -B<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. - -=back - -=head1 SEE ALSO - -wireshark-filter(4), wireshark(1), tshark(1), editcap(1), pcap(3), dumpcap(1), -text2pcap(1), pcap-filter(7) or tcpdump(8) - -=head1 NOTES - -B<Rawshark> is part of the B<Wireshark> distribution. The latest version of -B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - -B<Rawshark> uses the same packet dissection code that B<Wireshark> does, as -well as using many other modules from B<Wireshark>; see the list of authors -in the B<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 0000000000..b9227d718c --- /dev/null +++ b/doc/release-notes.adoc @@ -0,0 +1,288 @@ +include::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/ + +This is an experimental release intended to test new features for Wireshark 4.4. + +== What is Wireshark? + +Wireshark is the world’s most popular network protocol analyzer. +It is used for troubleshooting, analysis, development and education. + +== What’s New + +// Add a summary of **major** changes here. +// Add other changes to "New and Updated Features" below. + +Improved display filter support for value strings (optional string +representations for numeric fields). + +Display filter functions can be implemented as runtime-loadable C plugins. + +Plugin registration API was refactored. Plugin authors must update their +plugins as described below. + +Custom columns can be defined using any valid field expression, such as +display filter functions, slices, arithmetic calculations, logical tests, +raw byte addressing, and the layer modifier. + +Many other improvements have been made. +See the “New and Updated Features” section below for more details. + +//=== Bug Fixes + +//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. + +=== New and Updated Features + +The following features are new (or have been significantly updated) since version 4.2.0: + +//* The Windows installers now ship with Qt 6.5.2. +// They previously shipped with Qt 6.2.3. + +* Display filter syntax-related enhancements: + + ** Better handling of comparisons with value strings. Now the display filter engine can + correctly handle cases where multiple different numeric values map to the same value + string, including but not limited to range-type value strings. + + ** Fields with value strings now support regular expression matching. + + ** Date and time values now support arithmetic, with some restrictions: + the multiplier/divisor must be an integer or float and appear on the right-hand + side of the operator. + + ** The keyword "bitand" can be used as an alternative syntax for the bitwise-and operator. + + ** Functions alone can now be used as an entire logical expression. + The result of the expression is the truthiness of the function return + value (or of all values if more than one). This is useful for example to write + "len(something)" instead of "len(something) != 0". Even more so if a function + returns itself a boolean value, it is now possible to write + "bool_test(some.field)" instead of having to write "bool_test(some.field) == True" + (both forms are now valid). + + ** Display filter references can be written without curly braces. It + is now possible to write `$frame.number` instead of `${frame.number}` for example. + + ** Added new display filter functions to test various IP address properties. + Check the wireshark-filter(5) manpage for more information. + + ** Added new display filter functions to convert unsigned integer types to + decimal or hexadecimal. Check the wireshark-filter(5) manpage for more information. + + ** Display filter macros can be written with a semicolon after the macro + name before the argument list, e.g. `${mymacro;arg1;...;argN}`, instead + of `${mymacro:arg1;...;argN}`. The version with semicolons works better + with pop-up suggestions when editing the display filter, so the version + with the colon might be removed in the future. + + ** Display filter macros can be written using a function-like notation. + The macro `${mymacro:arg1;...;argN}` can be written + `$mymacro(arg1,...,argN)`. + +* Display filter functions can be implemented as libwireshark plugins. Plugins are loaded + during startup from the usual binary plugin configuration directories. See the + `ipaddr.c` source file in the distribution for an example of a display filter C plugin + and the doc/plugins.example folder for generic instructions how to build a plugin. + +* Display filter autocompletions now also include display filter functions. + +* The display filter macro configuration file has changed format. It now uses + the same format as the "dfilters" file and has been renamed accordingly to + "dmacros". Internally it no longer uses the UAT API and the display filter macro + GUI dialog has been updated. There is some basic migration logic implemented + but it is advisable to check that the "dfilter_macros" (old) and + "dmacros" (new) files in the profile directory are consistent. + +* Custom columns can be defined using any valid field expression: + + ** Display filter functions, like `len(tcp.payload)`, including nested functions + like `min(len(tcp.payload), len(udp.payload)` and newly defined functions + using the plugin system mentioned above. wsbuglink:15990[] wsbuglink:16181[] + + ** Arithmetic calculations, like `ip.len * 8` or `tcp.srcport + tcp.dstport`. + wsbuglink:7752[] + + ** Slices, like `tcp.payload[4:4]`. wsbuglink:10154[] + + ** The layer operator, like `ip.proto#1` to return the proto field in the + first IPv4 layer if there is tunneling. wsbuglink:18588[] + + ** Raw byte addressing, like `@ip`, useful to return the bytes of a protocol + or FT_NONE field, among others. wsbuglink:19076[] + + ** Logical tests, like `tcp.port == 443`, which produce a check mark if + the test matches (similar to protocol and none fields without `@`.) + This works with all logical operators, including e.g. regular expression + matching (`matches` or `~`.) + + ** Defined display filter macros. + + ** Any combination of the above also works. + + ** Multifield columns are still available. For backwards compatibility, + `X or Y` is interpreted as a multifield column as before. To represent a + logical test for the presence of multiple fields instead of concatenating + values, use parenthesis, like `(tcp.options.timestamp or tcp.options.nop`. + + ** Field references are not implemented, because there's no sense of a + currently selected frame. "Resolved" column values (such as host name + resolution or value string lookup) are not supported for any of the new + expressions yet. + +* When selecting "Manage Interfaces" from "Capture Options", Wireshark only + attempts to reconnect to rpcap (remote) hosts that were connected to in the + last session, instead of every remote host that the current profile has ever + connected to. wsbuglink:17484[] + +* Adding interfaces at startup is about twice as fast, and has many fewer + UAC pop-ups when npcap is installed with access restricted to Administrators + on Windows + +* The Resolved Addresses dialog only shows what addresses and ports are + present in the file (not including information from static files), and + selected rows or the entire table can be saved or copied to the clipboard + in several formats. + +* New menu:Tools[Install Plugin] option provides a convenient method to install + a binary plugin to the personal folder. + +* The personal binary plugins folder now has higher priority than the global + folder. + +* The binary plugins folder path no longer uses an X.Y version component. Plugins + are required to add the ABI version to the file name. + +* Truncated fields in the detail view are now displayed as "Field name […]: data" instead of "Field name [truncated]: data" + +* When capturing files in multiple file mode, a pattern that places the date and time + before the index number can be used (e.g., foo_20240714110102_00001.pcap instead of + foo_00001_20240714110102.pcap). This causes filenames to sort in chronological order + across file sets from different captures. The File Set dialog has been updated to + handle the new pattern, which has been capable of being produced by tshark since + version 3.6.0 + +* The "Follow Stream" dialog can now show delta times between turns and all packets and events. + +=== Removed Features and Support + +* The tshark `-G` option with no argument is deprecated and will be removed in + a future version. Use `tshark -G fields` to produce the same report. + +=== Removed Dissectors + +The Parlay dissector has been removed. + +//=== New File Format Decoding Support + +//[commaize] +//-- +//-- + +=== New Protocol Support + +// Add one protocol per line between the -- delimiters in the format +// “Full protocol name (Abbreviation)” +// git log --oneline --diff-filter=A --stat v4.3.0rc0.. epan/dissectors plugins +[commaize] +-- +Allied Telesis Resiliency Link (AT RL) +MAC NR Framed (mac-nr-framed) +RF4CE Network Layer (RF4CE) +RF4CE Profile (RF4CE Profile) +EGNOS Message Server (EMS) file format +-- + +=== Updated Protocol Support + +* IPv6: The "show address detail" preference is now enabled by default. The + address details provided have been extended to include more special purpose address + block properties (forwardable, globally-routable, etc). + +Too many other protocol updates have been made to list them all here. + +//=== 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] +-- +EGNOS Messager Server (EMS) files +-- + +// === New and Updated Capture Interfaces support +[commaize] +-- +u-blox GNSS receivers +-- + +//=== New and Updated Codec support + +//_Non-empty section placeholder._ + +=== Major API Changes + +* Plugin registration API was refactored. Plugin authors must do the following: + 1 - Remove the existing boilerplate (version, want_major` and `want_minor` and + plugin API declarations. 2 - Add a struct ws_module to the plugin. + 3 - Call one of the WIRESHARK_PLUGIN_REGISTER_* macros. See README.plugins + sections 5 and doc/plugins.example/hello.c for details and examples. + +== 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 0000000000..71069a0afc --- /dev/null +++ b/doc/reordercap.adoc @@ -0,0 +1,84 @@ +include::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/reordercap.pod b/doc/reordercap.pod deleted file mode 100644 index 19677d8243..0000000000 --- a/doc/reordercap.pod +++ /dev/null @@ -1,71 +0,0 @@ - -=head1 NAME - -reordercap - Reorder input file by timestamp into output file - -=head1 SYNOPSIS - -B<reordercap> -S<[ B<-n> ]> -S<[ B<-v> ]> -E<lt>I<infile>E<gt> E<lt>I<outfile>E<gt> - -=head1 DESCRIPTION - -B<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. - -B<Reordercap> writes the output capture file in the same format as the input -capture file. - -B<Reordercap> is able to detect, read and write the same capture files that -are supported by B<Wireshark>. -The input file doesn't need a specific filename extension; the file -format and an optional gzip compression will be detected automatically. -Near the beginning of the DESCRIPTION section of wireshark(1) or -L<https://www.wireshark.org/docs/man-pages/wireshark.html> -is a detailed description of the way B<Wireshark> handles this, which is -the same way B<reordercap> handles this. - -=head1 OPTIONS - -=over 4 - -=item -n - -When the B<-n> option is used, B<reordercap> will not write out the output -file if it finds that the input file is already in order. - -=item -v - -Print the version and exit. - -=back - -=head1 SEE ALSO - -pcap(3), wireshark(1), tshark(1), dumpcap(1), editcap(1), mergecap(1), -text2pcap(1), pcap-filter(7) or tcpdump(8) - -=head1 NOTES - -B<Reordercap> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -It may make sense to move this functionality into B<editcap>, or perhaps -B<mergecap>, in which case B<reordercap> could be retired. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - -------- ------ - Martin Mathieson <martin.r.mathieson[AT]googlemail.com> - diff --git a/doc/sdjournal.adoc b/doc/sdjournal.adoc new file mode 100644 index 0000000000..d81c5e3355 --- /dev/null +++ b/doc/sdjournal.adoc @@ -0,0 +1,132 @@ +include::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/sgml.doc.template b/doc/sgml.doc.template deleted file mode 100644 index 03347b0483..0000000000 --- a/doc/sgml.doc.template +++ /dev/null @@ -1 +0,0 @@ -=insert_dfilter_table
\ No newline at end of file diff --git a/doc/sshdump.adoc b/doc/sshdump.adoc new file mode 100644 index 0000000000..ec9abf1345 --- /dev/null +++ b/doc/sshdump.adoc @@ -0,0 +1,313 @@ +include::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/sshdump.pod b/doc/sshdump.pod deleted file mode 100644 index fdf886eb7d..0000000000 --- a/doc/sshdump.pod +++ /dev/null @@ -1,228 +0,0 @@ - -=head1 NAME - -sshdump - Provide interfaces to capture from a remote host through SSH using a remote capture binary. - -=head1 SYNOPSIS - -B<sshdump> -S<[ B<--help> ]> -S<[ B<--version> ]> -S<[ B<--extcap-interfaces> ]> -S<[ B<--extcap-dlts> ]> -S<[ B<--extcap-interface>=E<lt>interfaceE<gt> ]> -S<[ B<--extcap-config> ]> -S<[ B<--extcap-capture-filter>=E<lt>capture filterE<gt> ]> -S<[ B<--capture> ]> -S<[ B<--fifo>=E<lt>path to file or pipeE<gt> ]> -S<[ B<--remote-host>=E<lt>IP addressE<gt> ]> -S<[ B<--remote-port>=E<lt>TCP portE<gt> ]> -S<[ B<--remote-username>=E<lt>usernameE<gt> ]> -S<[ B<--remote-password>=E<lt>passwordE<gt> ]> -S<[ B<--sshkey>=E<lt>public key path<gt> ]> -S<[ B<--remote-interface>=E<lt>interfaceE<gt> ]> -S<[ B<--remote-capture-command>=E<lt>capture commandE<gt> ]> - -B<sshdump> -S<B<--extcap-interfaces>> - -B<sshdump> -S<B<--extcap-interface>=E<lt>interfaceE<gt>> -S<B<--extcap-dlts>> - -B<sshdump> -S<B<--extcap-interface>=E<lt>interfaceE<gt>> -S<B<--extcap-config>> - -B<sshdump> -S<B<--extcap-interface>=E<lt>interfaceE<gt>> -S<B<--fifo>=E<lt>path to file or pipeE<gt>> -S<B<--capture>> -S<B<--remote-host=myremotehost>> -S<B<--remote-port=22>> -S<B<--remote-username=user>> -S<B<--remote-interface=eth2>> -S<B<--remote-capture-command='tcpdump -U -i eth0 -w-'>> - -=head1 DESCRIPTION - -B<Sshdump> is a extcap tool that allows one to run a remote capture -tool in 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 - -Supported interfaces: - -=over 4 - -=item 1. ssh - -=back - -=head1 OPTIONS - -=over 4 - -=item --help - -Print program arguments. - -=item --version - -Print program version. - -=item --extcap-interfaces - -List available interfaces. - -=item --extcap-interface=E<lt>interfaceE<gt> - -Use specified interfaces. - -=item --extcap-dlts - -List DLTs of specified interface. - -=item --extcap-config - -List configuration options of specified interface. - -=item --capture - -Start capturing from specified interface and write raw packet data to the location specified by --fifo. - -=item --fifo=E<lt>path to file or pipeE<gt> - -Save captured packet to file or send it through pipe. - -=item --remote-host=E<lt>remote hostE<gt> - -The address of the remote host for capture. - -=item --remote-port=E<lt>remote portE<gt> - -The SSH port of the remote host. - -=item --remote-username=E<lt>usernameE<gt> - -The username for ssh authentication. - -=item --remote-password=E<lt>passwordE<gt> - -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. - -=item --sshkey=E<lt>SSH private key pathE<gt> - -The path to a private key for authentication. - -=item --remote-interface=E<lt>remote interfaceE<gt> - -The remote network interface to capture from. - -=item --remote-capture-command=E<lt>capture commandE<gt> - -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. - -=item --extcap-capture-filter=E<lt>capture filterE<gt> - -The capture filter - -=back - -=head1 EXAMPLES - -To see program arguments: - - sshdump --help - -To see program version: - - sshdump --version - -To see interfaces: - - sshdump --extcap-interfaces - -Only one interface (ssh) is supported. - - Output: - interface {value=ssh}{display=SSH remote capture} - -To see interface DLTs: - - sshdump --extcap-interface=ssh --extcap-dlts - - Output: - dlt {number=147}{name=ssh}{display=Remote capture dependent DLT} - -To see interface configuration options: - - sshdump --extcap-interface=ssh --extcap-config - - 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} - 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} - arg {number=2}{call=--remote-username}{display=Remote SSH server username}{type=string} - {default=myusername}{tooltip=The remote SSH username. If not provided, the current user will be used} - 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.} - 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} - arg {number=5}{call=--sshkey-passphrase}{display=SSH key passphrase} - {type=string}{tooltip=Passphrase to unlock the SSH private key} - arg {number=6}{call=--remote-interface}{display=Remote interface}{type=string}{default=eth0} - {tooltip=The remote network interface used for capture} - arg {number=7}{call=--remote-capture-command}{display=Remote capture command}{type=string} - {tooltip=The remote command used to capture.} - arg {number=8}{call=--remote-filter}{display=Remote capture filter}{type=string} - {default=not ((host myip) and port 22)}{tooltip=The remote capture filter} - arg {number=9}{call=--remote-count}{display=Packets to capture}{type=unsigned}{default=0} - {tooltip=The number of remote packets to capture. (Default: unlimited)} - -To capture: - - sshdump --extcap-interface=ssh --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=ssh --fifo=/tmp/ssh.pcap --capture --remote-host 192.168.1.10 - --remote-capture-command='dumpcap -i eth0 -P -w -' - - sshdump --extcap-interface=ssh --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 application. - -=head1 SEE ALSO - -wireshark(1), tshark(1), dumpcap(1), extcap(4), tcpdump(1) - -=head1 NOTES - -B<Sshdump> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - - Original Author - -------- ------ - Dario Lombardo <lomato[AT]gmail.com> diff --git a/doc/text2pcap.adoc b/doc/text2pcap.adoc new file mode 100644 index 0000000000..213eb348c4 --- /dev/null +++ b/doc/text2pcap.adoc @@ -0,0 +1,421 @@ +include::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/text2pcap.pod b/doc/text2pcap.pod deleted file mode 100644 index d19dab7fdd..0000000000 --- a/doc/text2pcap.pod +++ /dev/null @@ -1,261 +0,0 @@ - -=head1 NAME - -text2pcap - Generate a capture file from an ASCII hexdump of packets - -=head1 SYNOPSIS - -B<text2pcap> -S<[ B<-a> ]> -S<[ B<-d> ]> -S<[ B<-D> ]> -S<[ B<-e> E<lt>l3pidE<gt> ]> -S<[ B<-h> ]> -S<[ B<-i> E<lt>protoE<gt> ]> -S<[ B<-l> E<lt>typenumE<gt> ]> -S<[ B<-n> ]> -S<[ B<-m> E<lt>max-packetE<gt> ]> -S<[ B<-o> hex|oct|dec ]> -S<[ B<-q> ]> -S<[ B<-s> E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>tagE<gt> ]> -S<[ B<-S> E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>ppiE<gt> ]> -S<[ B<-t> E<lt>timefmtE<gt> ]> -S<[ B<-T> E<lt>srcportE<gt>,E<lt>destportE<gt> ]> -S<[ B<-u> E<lt>srcportE<gt>,E<lt>destportE<gt> ]> -S<[ B<-v> ]> -E<lt>I<infile>E<gt>|- -E<lt>I<outfile>E<gt>|- - -=head1 DESCRIPTION - -B<Text2pcap> is a program that reads in an ASCII hex dump and writes the -data described into a B<pcap> capture file. B<text2pcap> can -read hexdumps with multiple packets in them, and build a capture file of -multiple packets. B<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. - -B<Text2pcap> understands a hexdump of the form generated by I<od -Ax --tx1 -v>. In other words, each byte is individually displayed, with -spaces separating the bytes from each other. Each line begins with an offset -describing the position in the packet, each new packet starts with an offset -of 0 and there is a space separating the offset from the following bytes. -The offset is a hex number (can also be octal or decimal - see B<-o>), -of more than two hex digits. - -Here is a sample dump that B<text2pcap> can recognize: - - 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 - -Note the last byte must either be followed by the expected next offset value -as in the example above or a space or a line-end character(s). - -There is no limit on the width or number of bytes per line. Also the -text dump at the end of the line is ignored. Bytes/hex numbers can be -uppercase or lowercase. Any text before the offset is ignored, -including email forwarding characters '>'. Any lines of text between -the bytestring lines is ignored. The offsets are used to track the -bytes, so offsets must be correct. Any line which has only bytes -without a leading offset is ignored. An offset is recognized as being -a hex number longer than two characters. Any text after the bytes is -ignored (e.g. the character dump). Any hex numbers in this text are -also ignored. An offset of zero is indicative of starting a new -packet, so a single text file with a series of hexdumps can be -converted into a packet capture with multiple packets. Packets may be -preceded by a timestamp. These are interpreted according to the format -given on the command line (see B<-t>). If not, the first packet -is timestamped with the current time the conversion takes place. Multiple -packets are written with timestamps differing by one microsecond each. -In general, short of these restrictions, B<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.) - -There are a couple of other special features to note. Any line where -the first non-whitespace character is '#' will be ignored as a -comment. Any line beginning with #TEXT2PCAP is a directive and options -can be inserted after this command to be processed by -B<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. - -B<Text2pcap> also allows the user to read in dumps of -application-level data, by inserting dummy L2, L3 and L4 headers -before each packet. The user can elect to insert Ethernet headers, -Ethernet and IP, or Ethernet, IP and UDP/TCP/SCTP headers before each -packet. This allows Wireshark or any other full-packet decoder to -handle these dumps. - -=head1 OPTIONS - -=over 4 - -=item -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. - -B<NOTE:> Do not enable it if the input file does not contain the ASCII text dump. - -=item -d - -Displays debugging information during the process. Can be used -multiple times to generate more debugging information. - -=item -D - -The text before the packet starts either with an I or O indicating that -the packet is inbound or outbound. -This is only stored if the output format is pcapng. - -=item -e E<lt>l3pidE<gt> - -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: I<-e 0x806> to specify an ARP packet. - -For IP packets, instead of generating a fake Ethernet header you can -also use I<-l 101> to indicate a raw IP packet to Wireshark. Note that -I<-l 101> does not work for any non-IP Layer 3 packet (e.g. ARP), -whereas generating a dummy Ethernet header with I<-e> works for any -sort of L3 packet. - -=item -h - -Displays a help message. - -=item -i E<lt>protoE<gt> - -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. -Example: I<-i 46> to specify an RSVP packet (IP protocol 46). See -L<http://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml> for -the complete list of assigned internet protocol numbers. - -=item -l - -Specify the link-layer header type of this packet. Default is Ethernet -(1). See L<http://www.tcpdump.org/linktypes.html> for the complete list -of possible encapsulations. Note that this option should be used if -your dump is a complete hex dump of an encapsulated packet and you wish -to specify the exact type of encapsulation. Example: I<-l 7> for ARCNet -packets encapsulated BSD-style. - -=item -m E<lt>max-packetE<gt> - -Set the maximum packet length, default is 262144. -Useful for testing various packet boundaries when only an application -level datastream is available. Example: - -I<od -Ax -tx1 -v stream | text2pcap -m1460 -T1234,1234 - stream.pcap> - -will convert from plain datastream format to a sequence of Ethernet -TCP packets. - -=item -n - -Write the file in pcapng format rather than pcap format. - -=item -o hex|oct|dec - -Specify the radix for the offsets (hex, octal or decimal). Defaults to -hex. This corresponds to the C<-A> option for I<od>. - -=item -q - -Be completely quiet during the process. - -=item -s E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>tagE<gt> - -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. - -=item -S E<lt>srcportE<gt>,E<lt>destportE<gt>,E<lt>ppiE<gt> - -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 I<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. - -=item -t E<lt>timefmtE<gt> - -Treats the text before the packet as a date/time code; I<timefmt> is a -format string of the sort supported by strptime(3). -Example: The time "10:15:14.5476" has the format code "%H:%M:%S." - -B<NOTE:> The subsecond component delimiter must be specified (.) but no -pattern is required; the remaining number is assumed to be fractions of -a second. - -B<NOTE:> Date/time fields from the current date/time are -used as the default for unspecified fields. - -=item -T E<lt>srcportE<gt>,E<lt>destportE<gt> - -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. - -=item -u E<lt>srcportE<gt>,E<lt>destportE<gt> - -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: I<-u1000,69> to make the packets look like TFTP/UDP packets. - -=item -v - -Print the version and exit. - -=item -4 E<lt>srcipE<gt>,E<lt>destipE<gt> - -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: I<-4 10.0.0.1,10.0.0.2> to use 10.0.0.1 and 10.0.0.2 for all IP packets. - -=item -6 E<lt>srcipE<gt>,E<lt>destipE<gt> - -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: I<-6 fe80:0:0:0:202:b3ff:fe1e:8329, 2001:0db8:85a3:0000:0000:8a2e:0370:7334> to -use fe80:0:0:0:202:b3ff:fe1e:8329 and 2001:0db8:85a3:0000:0000:8a2e:0370:7334 for all IP packets. - -=back - -=head1 SEE ALSO - -od(1), pcap(3), wireshark(1), tshark(1), dumpcap(1), mergecap(1), -editcap(1), strptime(3), pcap-filter(7) or tcpdump(8) - -=head1 NOTES - -B<Text2pcap> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -=head1 AUTHORS - - Ashok Narayanan <ashokn[AT]cisco.com> diff --git a/doc/tshark.adoc b/doc/tshark.adoc new file mode 100644 index 0000000000..bbb07cbf41 --- /dev/null +++ b/doc/tshark.adoc @@ -0,0 +1,2627 @@ +include::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> ] [ *-C* <profile> ] + +[manarg] +*tshark* +*-h|--help* + +[manarg] +*tshark* +*-v|--version* + +== DESCRIPTION + +*TShark* is a network protocol analyzer. It lets you capture packet +data from a live network, or read packets from a previously saved +capture file, either printing a decoded form of those packets to the +standard output or writing the packets to a file. *TShark*'s native +capture file format is *pcapng* format, which is also the format used +by *Wireshark* and various other tools. + +Without any options set, *TShark* will work much like *tcpdump*. It +will use the pcap library to capture traffic from the first available +network interface and displays a summary line on the standard output for +each received packet. + +When run with the *-r* option, specifying a capture file from which to +read, *TShark* will again work much like *tcpdump*, reading packets +from the file and displaying a summary line on the standard output for +each packet read. *TShark* is able to detect, read and write the same +capture files that are supported by *Wireshark*. The input file +doesn't need a specific filename extension; the file format and an +optional gzip, 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_20240714120117.pcap, outfile_00002_20240714120523.pcap, ... + +With the __files__ option it's also possible to form a "ring buffer". +This will fill up new files until the number of files specified, +at which point *TShark* will discard the data in the first file and start +writing to that file and so on. If the __files__ option is not set, +new files filled up until one of the capture stop conditions match (or +until the disk is full). + +The criterion is of the form __key:value__, +where __key__ is one of: + +*duration*:__value__ switch to the next file after __value__ seconds have +elapsed, even if the current file is not completely filled up. Floating +point values (e.g. 0.5) are allowed. + +*files*:__value__ begin again with the first file after __value__ number of +files were written (form a ring buffer). This value must be less than 100000. +Caution should be used when using large numbers of files: some filesystems do +not handle many files in a single directory well. The *files* criterion +requires either *duration*, *interval* or *filesize* to be specified to +control when to go to the next file. It should be noted that each *-b* +parameter takes exactly one criterion; to specify two criterion, each must be +preceded by the *-b* option. + +*filesize*:__value__ switch to the next file after it reaches a size of +__value__ kB. Note that the filesize is limited to a maximum value of 2 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. + +*nametimenum*:__value__ Choose between two save filename templates. If +__value__ is 1, make running file number part before start time part; this is +the original and default behaviour (e.g. log_00001_20240714164426.pcap). If +__value__ is greater than 1, make start time part before running number part +(e.g. log_20210828164426_00001.pcap). The latter makes alphabetical sorting +order equal to creation time order, and keeps related multiple file sets in +same directory close to each other. + +Example: *tshark -b filesize:1000 -b files:5* results in a ring buffer of five +files of size one megabyte each. +-- + +-B|--buffer-size <capture buffer size>:: ++ +-- +Set capture buffer size (in MiB, default is 2 MiB). This is used by +the capture driver to buffer packet data until that data can be written +to disk. If you encounter packet drops while capturing, try to increase +this size. Note that, while *TShark* attempts to set the buffer size +to 2 MiB by default, and can be told to set it to a larger value, the +system or interface on which you're capturing might silently limit the +capture buffer size to a lower value or raise it to a higher value. + +This is available on UNIX-compatible systems, such as Linux, macOS, +\*BSD, Solaris, and AIX, with libpcap 1.0.0 or later, and on Windows. +It is not available on UNIX-compatible systems with earlier versions of +libpcap. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it sets the default capture buffer size. +If used after an *-i* option, it sets the capture buffer size for +the interface specified by the last *-i* option occurring before +this option. If the capture buffer size is not set specifically, +the default capture buffer size is used instead. +-- + +-c <capture packet count>:: ++ +-- +Set the maximum number of packets to read when capturing live +data. +If reading a capture file, set the maximum number of packets to read. +This includes any packets that do not pass the display filter, so it +may differ from *-a packets:*<capture packet count>. +-- + +-C <configuration profile>:: ++ +-- +Run with the given configuration profile. +-- + +-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). +If the quote character appears in a field value, it will be escaped +by being duplicated. + +*escape=y|n* If *y*, the whitespace control characters (tab, line feed, +carriage return, form feed, and vertical tab) backspace, and the +backslash will be replaced in field values by C-style escapes, e.g. +"\n" for line feed. If *n*, field value strings will be printed as-is. +Defaults to *y*. +-- + +-f <capture filter>:: ++ +-- +Set the capture filter expression. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it sets the default capture filter expression. +If used after an *-i* option, it sets the capture filter expression for +the interface specified by the last *-i* option occurring before +this option. If the capture filter expression is not set specifically, +the default capture filter expression is used if provided. + +Pre-defined capture filter names, as shown in the GUI menu item Capture->Capture +Filters, can be used by prefixing the argument with "predef:". +Example: *tshark -f "predef:MyPredefinedHostOnlyFilter"* +-- + +-F <file format>:: +Set the file format of the output capture file written using the *-w* +option. The output written with the *-w* option is raw packet data, not +text, so there is no *-F* option to request text output. The option *-F* +without a value will list the available formats. + +-g:: +This option causes the output file(s) to be created with group-read permission +(meaning that the output file(s) can be read by other members of the calling +user's group). + +-G [ <report type> ]:: ++ +-- +The *-G* option will cause *TShark* to dump one of several types of glossaries +and then exit. If no glossary type is specified, then the *fields* report +will be generated by default; this is deprecated and a future version will +require the report type argument. The *-G* option must be the first option given. +Using the report type of *help* lists all the current report types. + +The available report types include: + +*column-formats* Dumps the column formats understood by *TShark*. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: format string (e.g. "%rD") +Field 2:: text description of format string (e.g. "Dest port (resolved)") + +*currentprefs* Dumps a copy of the current preferences file to stdout. + +*decodes* Dumps the "layer type"/"decode as" associations to stdout. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: layer type, e.g. "tcp.port" +Field 2:: selector in decimal +Field 3:: "decode as" name, e.g. "http" + +*defaultprefs* Dumps a default preferences file to stdout. + +*dissectors* Dumps a list of registered dissectors to stdout. There is +one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: dissector name +Field 2:: dissector description + +*dissector-tables* Dumps a list of dissector tables to stdout. There +is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: dissector table name, e.g. "tcp.port" +Field 2:: name used for the dissector table in the GUI +Field 3:: type (textual representation of the ftenum type, or "heuristic") +Field 4:: base for display (for integer types) +Field 5:: protocol name +Field 6:: "decode as" support (for non-heuristic tables) + +*elastic-mapping* Dumps the ElasticSearch mapping file to stdout. Fields +falling in the default case (string) won't be mapped. + +*enterprises* Dumps the IANA Private Enterprise Number (PEN) table. + +*fieldcount* Dumps the number of header fields to stdout. + +*fields* Dumps the contents of the registration database to +stdout. An independent program can take this output and format it into nice +tables or HTML or whatever. There is one record per line. Each record is +either a protocol or a header field, differentiated by the first field. +The fields are tab-delimited. + +.Protocols +[horizontal] +Field 1:: 'P' +Field 2:: descriptive protocol name +Field 3:: protocol abbreviation + +.Header Fields +[horizontal] +Field 1:: 'F' +Field 2:: descriptive field name +Field 3:: field abbreviation +Field 4:: type (textual representation of the ftenum type) +Field 5:: parent protocol abbreviation +Field 6:: base for display (for integer types); "parent bitfield width" for FT_BOOLEAN +Field 7:: bitmask: format: hex: 0x.... +Field 8:: blurb describing field + +An optional search prefix argument can be given to +*fields*, in which case the output is limited to protocols and fields whose +abbreviation starts with the search prefix. + +.Search Output +[horizontal] +Field 1:: protocol or field abbreviation +Field 2:: descriptive protocol or field name + +*folders* Dumps various folders used by *TShark*. This is essentially the +same data reported in Wireshark's About | Folders tab. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: Folder type (e.g "Personal configuration:") +Field 2:: Folder location (e.g. "/home/vagrant/.config/wireshark/") + +*ftypes* Dumps the "ftypes" (fundamental types) understood by *TShark*. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: FTYPE (e.g "FT_IPv6") +Field 2:: text description of type (e.g. "IPv6 address") + +*heuristic-decodes* Dumps the heuristic decodes currently installed. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: heuristic dissector table name (e.g. "tcp") +Field 2:: name of heuristic decoder (e.g. "ucp") +Field 3:: heuristic enabled (e.g. "T" or "F") +Field 4:: heuristic enabled by default (e.g. "T" or "F") +Field 5:: heuristic short name (e.g. "ucp_tcp") +Field 6:: heuristic display name (e.g. "UCP over TCP") + +*help* Displays the available report types. + +*manuf* Dumps the MAC address lookup table in `manuf` format. + +*plugins* Dumps the plugins currently installed. +There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: plugin library/Lua script/extcap executable (e.g. "gryphon.so") +Field 2:: plugin version (e.g. 0.0.4) +Field 3:: plugin type ("dissector", "tap", "file type", etc.) +Field 4:: full path to plugin file + +*protocols* Dumps the protocols in the registration database to stdout. +An independent program can take this output and format it into nice tables +or HTML or whatever. There is one record per line. The fields are tab-delimited. + +[horizontal] +Field 1:: protocol name +Field 2:: protocol short name +Field 3:: protocol filter name +Field 4:: protocol enabled (e.g. "T" or "F") +Field 5:: protocol enabled by default (e.g. "T" or "F") +Field 6:: protocol can toggle (e.g. "T" or "F") + +*services* Dumps the TCP, UDP, and SCTP transport service (port) table. + +*values* Dumps the value_strings, range_strings or true/false strings +for fields that have them. There is one record per line. Fields are +tab-delimited. There are three types of records: Value String, Range +String and True/False String. The first field, 'V', 'R' or 'T', indicates +the type of record. + +.Value Strings +[horizontal] +Field 1:: 'V' +Field 2:: field abbreviation to which this value string corresponds +Field 3:: Integer value +Field 4:: String + +.Range Strings +[horizontal] +Field 1:: 'R' +Field 2:: field abbreviation to which this range string corresponds +Field 3:: Integer value: lower bound +Field 4:: Integer value: upper bound +Field 5:: String + +.True/False Strings +[horizontal] +Field 1:: 'T' +Field 2:: field abbreviation to which this true/false string corresponds +Field 3:: True String +Field 4:: False String +-- + +-h|--help:: +Print the version number and options and exit. + +-H <input hosts file>:: ++ +-- +Read a list of entries from a "hosts" file, which will then be written +to a capture file. Implies *-W n*. Can be called multiple times. + +The "hosts" file format is documented at +https://en.wikipedia.org/wiki/Hosts_(file). +-- + +-i|--interface <capture interface> | -:: ++ +-- +Set the name of the network interface or pipe to use for live packet +capture. + +Network interface names should match one of the names listed in "*tshark +-D*" (described above); a number, as reported by "*tshark -D*", can also +be used. + +If no interface is specified, *TShark* searches the list of +interfaces, choosing the first non-loopback interface if there are any +non-loopback interfaces, and choosing the first loopback interface if +there are no non-loopback interfaces. If there are no interfaces at all, +*TShark* reports an error and doesn't start the capture. + +Pipe names should be either the name of a FIFO (named pipe) or "-" to +read data from the standard input. On Windows systems, pipe names must be +of the form +"\\.\pipe\+*pipename*". Data read from pipes must be in +standard pcapng or pcap format. Pcapng data must have the same +endianness as the capturing host. + +"TCP@<host>:<port>" causes *TShark* to attempt to connect to the +specified port on the specified host and read pcapng or pcap data. + +This option can occur multiple times. When capturing from multiple +interfaces, the capture file will be saved in pcapng format. +-- + +-I|--monitor-mode:: ++ +-- +Put the interface in "monitor mode"; this is supported only on IEEE +802.11 Wi-Fi interfaces, and supported only on some operating systems. + +Note that in monitor mode the adapter might disassociate from the +network with which it's associated, so that you will not be able to use +any wireless networks with that adapter. This could prevent accessing +files on a network server, or resolving host names or network addresses, +if you are capturing in monitor mode and are not connected to another +network with another adapter. + +This option can occur multiple times. If used before the first +occurrence of the *-i* option, it enables the monitor mode for all interfaces. +If used after an *-i* option, it enables the monitor mode for +the interface specified by the last *-i* option occurring before +this option. +-- + +-j <protocol match filter>:: ++ +-- +Protocol match filter used for ek|json|jsonraw|pdml output file types. +Only the protocol's parent node is included. Child nodes are only +included if explicitly specified in the filter. + +Example: *tshark -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-3gpp,stat[,__filter__]:: ++ +-- +This option will activate a counter for LTE or NR MAC messages. You will get +information about the maximum number of UEs/TTI, common messages and +various counters for each UE that appears in the log. + +Example: *tshark -z mac-3gpp,stat*. + +This option can be used multiple times on the command line. + +Example: *-z "mac-3gpp,stat,mac-lte.rnti>3000"* will only collect stats for +LTE UEs with an assigned RNTI whose value is more than 3000. +-- + +*-z* megaco,rtd[,__filter__]:: ++ +-- +Collect requests/response RTD (Response Time Delay) data for MEGACO. +(This is similar to *-z smb,srt*). Data collected is the number of calls +for each known MEGACO Type, MinRTD, MaxRTD and AvgRTD. +Additionally you get the number of duplicate requests/responses, +unresponded requests, responses, which don't match with any request. +Example: *-z megaco,rtd*. + +Example: *-z "megaco,rtd,ip.addr==1.2.3.4"* will only collect stats for +MEGACO packets exchanged by the host at IP address 1.2.3.4 . + +This option can be used multiple times on the command line. +-- + +*-z* mgcp,rtd[,__filter__]:: ++ +-- +Collect requests/response RTD (Response Time Delay) data for MGCP. +(This is similar to *-z smb,srt*). Data collected is the number of calls +for each known MGCP Type, MinRTD, MaxRTD and AvgRTD. +Additionally you get the number of duplicate requests/responses, +unresponded requests, responses, which don't match with any request. +Example: *-z mgcp,rtd*. + +This option can be used multiple times on the command line. + +Example: *-z "mgcp,rtd,ip.addr==1.2.3.4"* will only collect stats for +MGCP packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* mtp3,msus[,__filter__]:: +Calculate statistics on MTP3 MSUs. For each combination of originating +point code, destination point code, and service indicator, calculates +the total number of MSUs, the total bytes, and the average bytes per MSU. + +*-z* ncp,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for Netware +Core Protocol. Minimum SRT, maximum SRT, average SRT, and sum SRT is +displayed for request/response pairs, organized by group, function and +subfunction, and verb. No statistics are gathered on unpaired messages. + +*-z* osmux,tree[,__filter__]:: +Calculate statistics for the OSmux voice/signaling multiplex protocol. +Displays the total number of OSmux packets, and displays for each stream +the number of packets, number of packets with the RTP market bit set, +number of AMR frames, jitter analysis, and sequence number analysis. + +*-z* pfcp,srt[,__filter__]:: +Collect requests/response SRT (Service Response Time) data for PFCP. +Data collected is the number of calls, minimum SRT, maximum SRT, average +SRT, and sum SRT for certain commands. Currently no statistics are gathered +on unpaired messages. + +*-z* pingpongprotocol,stat[,__filter__]:: +Calculate statistics on the Ping Pong Protocol of Reliable +Server Pooling. For each message type, displays the number, rate +and share among all message types of both packets and bytes, and the +first and last time that it is seen. + +*-z* plen,tree[,__filter__]:: +Calculate statistics on packet lengths. Packets are grouped into buckets +that grow exponentially with powers of two. + +*-z* proto,colinfo,__filter__,__field__:: ++ +-- +Append all __field__ values for the packet to the Info column of the +one-line summary output. +This feature can be used to append arbitrary fields to the Info column +in addition to the normal content of that column. +__field__ is the display-filter name of a field which value should be placed +in the Info column. +__filter__ is a filter string that controls for which packets the field value +will be presented in the info column. __field__ will only be presented in the +Info column for the packets which match __filter__. + +NOTE: In order for *TShark* to be able to extract the __field__ value +from the packet, __field__ MUST be part of the __filter__ string. If not, +*TShark* will not be able to extract its value. + +For a simple example to add the "nfs.fh.hash" field to the Info column +for all packets containing the "nfs.fh.hash" field, use + +*-z proto,colinfo,nfs.fh.hash,nfs.fh.hash* + +To put "nfs.fh.hash" in the Info column but only for packets coming from +host 1.2.3.4 use: + +*-z "proto,colinfo,nfs.fh.hash && ip.src==1.2.3.4,nfs.fh.hash"* + +This option can be used multiple times on the command line. +-- + +*-z* ptype,tree[,__filter__]:: +Calculate statistics on port types that occur on IPv4 packets. + +*-z* radius,rtd[,__filter__]:: +Collect requests/response RTD (Response Time Delay) data for RADIUS. +The data collected for each RADIUS code is the number of calls, +Minimum RTD, Maximum RTD, Average RTD, Minimum in Frame, and Maximum in Frame, +along with the number of Open Requests (Unresponded Requests), Discarded +Responses (Responses without matching request) and Duplicate Messages. + +*-z* rlc-3gpp,stat[,__filter__]:: ++ +-- +This option will activate a counter for LTE or NR RLC messages. You will get +information about common messages and various counters for each UE that appears +in the log. + +Example: *tshark -z rlc-3gpp,stat*. + +This option can be used multiple times on the command line. + +Example: *-z "rlc-3gpp,stat,rlc-nr.ueid>3000"* will only collect stats for +NR UEs with a UEId of more than 3000. +-- + +*-z* rpc,programs:: ++ +-- +Collect call/reply SRT data for all known ONC-RPC programs/versions. +Data collected is number of calls for each protocol/version, MinSRT, +MaxSRT and AvgSRT. +This option can only be used once on the command line. +-- + +*-z* rpc,srt,__program__,__version__[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for __program__/__version__. +Data collected is the number of calls for each procedure, MinSRT, MaxSRT, +AvgSRT, and the total time taken for each procedure. + +Example: *tshark -z rpc,srt,100003,3* will collect data for NFS v3. + +This option can be used multiple times on the command line. + +Example: *-z rpc,srt,100003,3,nfs.fh.hash==0x12345678* will collect NFS v3 +SRT statistics for a specific file. +-- + +*-z* rtp,streams:: +Collect statistics for all RTP streams and calculate max. delta, max. and +mean jitter and packet loss percentages. + +*-z* rtsp,stat[,__filter__]:: +Count the RTSP response status codes and the RSTP request methods. + +*-z* rtsp,tree[,__filter__]:: +Calculate the RTSP packet distribution. Displayed values are the +response status codes and request methods. + +*-z* sametime,tree[,__filter__]:: +Calculate statistics on SAMETIME messages. Displayed values are the +messages type, send type, and user status. + +*-z* scsi,srt,__cmdset__[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for SCSI commandset __cmdset__. + +Commandsets are 0:SBC 1:SSC 5:MMC + +Data collected +is the number of calls for each procedure, MinSRT, MaxSRT and AvgSRT. + +Example: *-z scsi,srt,0* will collect data for SCSI BLOCK COMMANDS (SBC). + +This option can be used multiple times on the command line. + +Example: *-z scsi,srt,0,ip.addr==1.2.3.4* will collect SCSI SBC +SRT statistics for a specific iscsi/ifcp/fcip host. +-- + +*-z* sctp,stat:: +Activate a counter for SCTP chunks. In addition to the total number of +SCTP packets, for each source and destination address and port combination +the number of chunks of the most common types (DATA, SACK, HEARTBEAT, +HEARTBEAT ACK, INIT, INIT ACK, COOKIE ECHO, COOKIE ACK, ABORT, and ERROR) +are displayed. + +*-z* sip,stat[,__filter__]:: ++ +-- +This option will activate a counter for SIP messages. You will get the number +of occurrences of each SIP Method and of each SIP Status-Code. Additionally +you also get the number of resent SIP Messages (only for SIP over UDP). + +Example: *-z sip,stat*. + +This option can be used multiple times on the command line. + +Example: *-z "sip,stat,ip.addr==1.2.3.4"* will only collect stats for +SIP packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* smb,sids:: ++ +-- +When this feature is used *TShark* will print a report with all the +discovered SID and account name mappings. Only those SIDs where the +account name is known will be presented in the table. + +For this feature to work you will need to either to enable +"Edit/Preferences/Protocols/SMB/Snoop SID to name mappings" in the +preferences or you can override the preferences by specifying +[.nowrap]#*-o "smb.sid_name_snooping:TRUE"*# on the *TShark* command line. + +The current method used by *TShark* to find the SID->name mapping +is relatively restricted with a hope of future expansion. +-- + +*-z* smb,srt[,__filter__]:: ++ +-- +Collect call/reply SRT (Service Response Time) data for SMB. Data collected +is number of calls for each SMB command, MinSRT, MaxSRT and AvgSRT. + +Example: *-z smb,srt* + +The data will be presented as separate tables for all normal SMB commands, +all Transaction2 commands and all NT Transaction commands. +Only those commands that are seen in the capture will have its stats +displayed. +Only the first command in a xAndX command chain will be used in the +calculation. So for common SessionSetupAndX + TreeConnectAndX chains, +only the SessionSetupAndX call will be used in the statistics. +This is a flaw that might be fixed in the future. + +This option can be used multiple times on the command line. + +Example: *-z "smb,srt,ip.addr==1.2.3.4"* will only collect stats for +SMB packets exchanged by the host at IP address 1.2.3.4 . +-- + +*-z* smb2,srt[,__filter__]:: +Collect call/reply SRT (Service Response Time) data for SMB versions 2 and 3. +The data collected for each normal command type is the number of calls, +MinSRT, MaxSRT, AvgSRT, and SumSRT. No data is collected on cancel or +oplock break requests, or on unpaired commands. Only the first response to +a given request is used; retransmissions are not included in the calculation. + +*-z* smpp_commands,tree[,__filter__]:: +Calculate the SMPP command distribution. Displayed values are +command IDs for both requests and responses, and status for responses. + +*-z* snmp,srt[,__filter__]:: +Collect call/reply SRT (Service Response Time) data for SNMP. The data +collected for each PDU type is the number of request/response pairs, +MinSRT, MaxSRT, AvgSRT, and SumSRT. No data is collected on unpaired +messages. + +*-z* someip_messages,tree[,__filter__]:: +Create statistic of SOME/IP messages. Messages are counted and displayed +as Messages grouped by sender/receiver. + +*-z* someipsd_entries,tree[,__filter__]:: +Create statistic of SOME/IP-SD entries. Entries are counted and displayed +as Entries grouped by sender/receiver. + +*-z* sv:: +Print out the time since the start of the capture and sample count for each +IEC 61850 Sampled Values packet. + +*-z* ucp_messages,tree[,__filter__]:: +Calculate the message distribution of UCP packets. Displayed values are +operation types for both operations and results, and whether results are +positive or negative, with error codes displayed for negative results. + +*-z* wsp,stat[,__filter__]:: +Count the PDU types and the status codes of reply packets for WSP packets. + +--capture-comment <comment>:: ++ +-- +Add a capture comment to the output file, if supported by the output +file format. + +This option may be specified multiple times. Note that Wireshark +currently only displays the first comment of a capture file. +-- + +--list-time-stamp-types:: +List time stamp types supported for the interface. If no time stamp type can be +set, no time stamp types are listed. + +--time-stamp-type <type>:: +Change the interface's timestamp method. + +--update-interval <interval>:: +Set the length of time in milliseconds between new packet reports during +a capture. Also sets the granularity of file duration conditions. +The default value is 100ms. + +--color:: +Enable coloring of packets according to standard Wireshark color +filters. On Windows colors are limited to the standard console +character attribute colors. Other platforms require a terminal that +handles 24-bit "true color" terminal escape sequences. See +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/tshark.pod b/doc/tshark.pod deleted file mode 100644 index 454991a5e1..0000000000 --- a/doc/tshark.pod +++ /dev/null @@ -1,2082 +0,0 @@ - -=head1 NAME - -tshark - Dump and analyze network traffic - -=head1 SYNOPSIS - -B<tshark> -S<[ B<-2> ]> -S<[ B<-a> E<lt>capture autostop conditionE<gt> ] ...> -S<[ B<-b> E<lt>capture ring buffer optionE<gt>] ...> -S<[ B<-B> E<lt>capture buffer sizeE<gt> ] > -S<[ B<-c> E<lt>capture packet countE<gt> ]> -S<[ B<-C> E<lt>configuration profileE<gt> ]> -S<[ B<-d> E<lt>layer typeE<gt>==E<lt>selectorE<gt>,E<lt>decode-as protocolE<gt> ]> -S<[ B<-D> ]> -S<[ B<-e> E<lt>fieldE<gt> ]> -S<[ B<-E> E<lt>field print optionE<gt> ]> -S<[ B<-f> E<lt>capture filterE<gt> ]> -S<[ B<-F> E<lt>file formatE<gt> ]> -S<[ B<-g> ]> -S<[ B<-h> ]> -S<[ B<-H> E<lt>input hosts fileE<gt> ]> -S<[ B<-i> E<lt>capture interfaceE<gt>|- ]> -S<[ B<-j> E<lt>protocol match filterE<gt> ]> -S<[ B<-I> ]> -S<[ B<-K> E<lt>keytabE<gt> ]> -S<[ B<-l> ]> -S<[ B<-L> ]> -S<[ B<-n> ]> -S<[ B<-N> E<lt>name resolving flagsE<gt> ]> -S<[ B<-o> E<lt>preference settingE<gt> ] ...> -S<[ B<-O> E<lt>protocolsE<gt> ]> -S<[ B<-p> ]> -S<[ B<-P> ]> -S<[ B<-q> ]> -S<[ B<-Q> ]> -S<[ B<-r> E<lt>infileE<gt> ]> -S<[ B<-R> E<lt>Read filterE<gt> ]> -S<[ B<-s> E<lt>capture snaplenE<gt> ]> -S<[ B<-S> E<lt>separatorE<gt> ]> -S<[ B<-t> a|ad|adoy|d|dd|e|r|u|ud|udoy ]> -S<[ B<-T> ek|fields|json|pdml|ps|psml|tabs|text ]> -S<[ B<-u> E<lt>seconds typeE<gt>]> -S<[ B<-U> E<lt>tap_nameE<gt>]> -S<[ B<-v> ]> -S<[ B<-V> ]> -S<[ B<-w> E<lt>outfileE<gt>|- ]> -S<[ B<-W> E<lt>file format optionE<gt>]> -S<[ B<-x> ]> -S<[ B<-X> E<lt>eXtension optionE<gt>]> -S<[ B<-y> E<lt>capture link typeE<gt> ]> -S<[ B<-Y> E<lt>displaY filterE<gt> ]> -S<[ B<-M> E<lt>auto session resetE<gt> ]> -S<[ B<-z> E<lt>statisticsE<gt> ]> -S<[ B<--capture-comment> E<lt>commentE<gt> ]> -S<[ B<--list-time-stamp-types> ]> -S<[ B<--time-stamp-type> E<lt>typeE<gt> ]> -S<[ B<--color> ]> -S<[ B<--no-duplicate-keys> ]> -S<[ B<--export-objects> E<lt>protocolE<gt>,E<lt>destdirE<gt> ]> -S<[ B<--enable-protocol> E<lt>proto_nameE<gt> ]> -S<[ B<--disable-protocol> E<lt>proto_nameE<gt> ]> -S<[ B<--enable-heuristic> E<lt>short_nameE<gt> ]> -S<[ B<--disable-heuristic> E<lt>short_nameE<gt> ]> -S<[ E<lt>capture filterE<gt> ]> - -B<tshark> -B<-G> [ E<lt>report typeE<gt> ] [ --elastic-mapping-filter E<lt>protocolsE<gt> ] - -=head1 DESCRIPTION - -B<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. B<TShark>'s native -capture file format is B<pcap> format, which is also the format used -by B<tcpdump> and various other tools. - -Without any options set, B<TShark> will work much like B<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 B<-r> option, specifying a capture file from which to -read, B<TShark> will again work much like B<tcpdump>, reading packets -from the file and displaying a summary line on the standard output for -each packet read. B<TShark> is able to detect, read and write the same -capture files that are supported by B<Wireshark>. The input file -doesn't need a specific filename extension; the file format and an -optional gzip compression will be automatically detected. Near the -beginning of the DESCRIPTION section of wireshark(1) or -L<https://www.wireshark.org/docs/man-pages/wireshark.html> is a detailed -description of the way B<Wireshark> handles this, which is the same way -B<Tshark> handles this. - -Compressed file support uses (and therefore requires) the zlib library. -If the zlib library is not present when compiling B<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, B<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 B<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 B<-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 B<-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 "B<tshark -G protocols>" to find the -abbreviations of the protocols you can specify. If the B<-P> option is -specified with either the B<-V> or B<-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 B<-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 read filter syntax described below, -and the filtering mechanism is limited in its abilities. - -Read filters in B<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 B<TShark> than in other protocol analyzers, and the syntax -you can use to create your filters is richer. As B<TShark> progresses, -expect more and more protocol fields to be allowed in read filters. -Read filters use the same syntax as display and color filters in -B<Wireshark>; a read filter is specified with the B<-R> option. - -Read filters can be specified when capturing or when reading from a -capture file. Note that that capture filters are much more efficient -than read filters, and it may be more difficult for B<TShark> to keep up -with a busy network if a read filter is specified for a live capture, so -you might be more likely to lose packets if you're using a read filter. - -A capture or read filter can either be specified with the B<-f> or B<-R> -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 B<-r> option was -specified) and a read filter if a capture file is being read (i.e., if a -B<-r> option was specified). - -If the B<-w> option is specified when capturing packets or reading from -a capture file, B<TShark> does not display packets on the standard -output. Instead, it writes the packets to a capture file with the name -specified by the B<-w> option. - -If you want to write the decoded form of packets to a file, run -B<TShark> without the B<-w> option, and redirect its standard output to -the file (do I<not> use the B<-w> option). - -If you want the packets to be displayed to the standard output and also -saved to a file, specify the B<-P> option in addition to the B<-w> -option to have the summary line displayed, specify the B<-V> option -in addition to the B<-w> option to have the details of the packet -displayed, and specify the B<-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 B<-P> -option is used together with the B<-V> or B<-O> option, the summary line -will be displayed along with the detail lines. - -When writing packets to a file, B<TShark>, by default, writes the file -in B<pcapng> format, and writes all of the packets it sees to the output -file. The B<-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 -B<-F> option without a value. However, you can't specify a file format -for a live capture. - -When capturing packets, B<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 B<-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 B<-Q> -option is specified, neither the initial line, nor the packet -information, nor any packet counts will be displayed. If the B<-q> or -B<-Q> option is used, the B<-P>, B<-V>, or B<-O> option can be used to -cause the corresponding output to be displayed even though other output -is suppressed. - -When reading packets, the B<-q> and B<-Q> option will suppress the -display of the packet summary or details; this would be used if B<-z> -options are specified in order to display statistics, so that only the -statistics, not the packet information, is displayed. - -The B<-G> option is a special mode that simply causes B<Tshark> -to dump one of several types of internal glossaries and then exit. - -=head1 OPTIONS - -=over 4 - -=item -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. - -=item -a E<lt>capture autostop conditionE<gt> - -Specify a criterion that specifies when B<TShark> is to stop writing -to a capture file. The criterion is of the form I<test>B<:>I<value>, -where I<test> is one of: - -B<duration>:I<value> Stop writing to a capture file after I<value> seconds -have elapsed. - -B<filesize>:I<value> Stop writing to a capture file after it reaches a size of -I<value> kB. If this option is used together with the -b option, B<TShark> -will stop writing to the current capture file and switch to the next one if -filesize is reached. When reading a capture file, B<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. - -B<files>:I<value> Stop writing to capture files after I<value> number of files -were written. - -=item -b E<lt>capture ring buffer optionE<gt> - -Cause B<TShark> to run in "multiple files" mode. In "multiple files" mode, -B<TShark> will write to several capture files. When the first capture file -fills up, B<TShark> will switch writing to the next file and so on. - -The created filenames are based on the filename given with the B<-w> option, -the number of the file and on the creation date and time, -e.g. outfile_00001_20050604120117.pcap, outfile_00002_20050604120523.pcap, ... - -With the I<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 B<TShark> will discard the data in the first file and start -writing to that file and so on. If the I<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 I<key>B<:>I<value>, -where I<key> is one of: - -B<duration>:I<value> switch to the next file after I<value> seconds have -elapsed, even if the current file is not completely filled up. - -B<interval>:I<value> switch to the next file when the time is an exact -multiple of I<value> seconds - -B<filesize>:I<value> switch to the next file after it reaches a size of -I<value> kB. Note that the filesize is limited to a maximum value of 2 GiB. - -B<files>:I<value> begin again with the first file after I<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 B<files> criterion -requires either B<duration>, B<interval> or B<filesize> to be specified to -control when to go to the next file. It should be noted that each B<-b> -parameter takes exactly one criterion; to specify two criterion, each must be -preceded by the B<-b> option. - -Example: B<tshark -b filesize:1000 -b files:5> results in a ring buffer of five files -of size one megabyte each. - -=item -B E<lt>capture buffer sizeE<gt> - -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 B<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 systems with libpcap 1.0.0 or later and on -Windows. It is not available on UNIX systems with earlier versions of -libpcap. - -This option can occur multiple times. If used before the first -occurrence of the B<-i> option, it sets the default capture buffer size. -If used after an B<-i> option, it sets the capture buffer size for -the interface specified by the last B<-i> option occurring before -this option. If the capture buffer size is not set specifically, -the default capture buffer size is used instead. - -=item -c E<lt>capture packet countE<gt> - -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. - -=item -C E<lt>configuration profileE<gt> - -Run with the given configuration profile. - -=item -d E<lt>layer typeE<gt>==E<lt>selectorE<gt>,E<lt>decode-as protocolE<gt> - -Like Wireshark's B<Decode As...> feature, this lets you specify how a -layer type should be dissected. If the layer type in question (for example, -B<tcp.port> or B<udp.port> for a TCP or UDP port number) has the specified -selector value, packets should be dissected as the specified protocol. - -Example: B<tshark -d tcp.port==8888,http> will decode any traffic running over -TCP port 8888 as HTTP. - -Example: B<tshark -d tcp.port==8888:3,http> will decode any traffic running over -TCP ports 8888, 8889 or 8890 as HTTP. - -Example: B<tshark -d tcp.port==8888-8890,http> will decode any traffic running over -TCP ports 8888, 8889 or 8890 as HTTP. - -Using an invalid selector or protocol will print out a list of valid selectors -and protocol names, respectively. - -Example: B<tshark -d .> is a quick way to get a list of valid selectors. - -Example: B<tshark -d ethertype==0x0800.> is a quick way to get a list of protocols that can be -selected with an ethertype. - -=item -D - -Print a list of the interfaces on which B<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 B<-i> option to specify an interface on which to capture. - -This can be useful on systems that don't have a command to list them -(UNIX systems lacking B<ifconfig -a> or Linux systems lacking -B<ip link show>). The number can be useful on Windows systems, where -the interface name might be a long name or a GUID. - -Note that "can capture" means that B<TShark> was able to open that -device to do a live capture. Depending on your system you may need to -run tshark from an account with special privileges (for example, as -root) to be able to capture network traffic. If B<tshark -D> is not run -from such an account, it will not list any interfaces. - -=item -e E<lt>fieldE<gt> - -Add a field to the list of fields to display if B<-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 B<-T fields> option is -selected. Column names may be used prefixed with "_ws.col." - -Example: B<tshark -e frame.number -e ip.addr -e udp -e _ws.col.Info> - -Giving a protocol rather than a single field will print multiple items -of data about the protocol as a single field. Fields are separated by -tab characters by default. B<-E> controls the format of the printed -fields. - -=item -E E<lt>field print optionE<gt> - -Set an option controlling the printing of fields when B<-T fields> is -selected. - -Options are: - -B<bom=y|n> If B<y>, prepend output with the UTF-8 byte order mark -(hexadecimal ef, bb, bf). Defaults to B<n>. - -B<header=y|n> If B<y>, print a list of the field names given using B<-e> -as the first line of the output; the field name will be separated using -the same character as the field values. Defaults to B<n>. - -B<separator=/t|/s|>E<lt>characterE<gt> Set the separator character to -use for fields. If B</t> tab will be used (this is the default), if -B</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. - -B<occurrence=f|l|a> Select which occurrence to use for fields that have -multiple occurrences. If B<f> the first occurrence will be used, if B<l> -the last occurrence will be used and if B<a> all occurrences will be used -(this is the default). - -B<aggregator=,|/s|>E<lt>characterE<gt> Set the aggregator character to -use for fields that have multiple occurrences. If B<,> a comma will be used -(this is the default), if B</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. - -B<quote=d|s|n> Set the quote character to use to surround fields. B<d> -uses double-quotes, B<s> single-quotes, B<n> no quotes (the default). - -=item -f E<lt>capture filterE<gt> - -Set the capture filter expression. - -This option can occur multiple times. If used before the first -occurrence of the B<-i> option, it sets the default capture filter expression. -If used after an B<-i> option, it sets the capture filter expression for -the interface specified by the last B<-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: B<tshark -f "predef:MyPredefinedHostOnlyFilter"> - -=item -F E<lt>file formatE<gt> - -Set the file format of the output capture file written using the B<-w> -option. The output written with the B<-w> option is raw packet data, not -text, so there is no B<-F> option to request text output. The option B<-F> -without a value will list the available formats. - -=item -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). - -=item -G [ E<lt>report typeE<gt> ] - -The B<-G> option will cause B<Tshark> to dump one of several types of glossaries -and then exit. If no specific glossary type is specified, then the B<fields> report will be generated by default. -Using the report type of B<help> lists all the current report types. - -The available report types include: - -B<column-formats> Dumps the column formats understood by tshark. -There is one record per line. The fields are tab-delimited. - - * Field 1 = format string (e.g. "%rD") - * Field 2 = text description of format string (e.g. "Dest port (resolved)") - -B<currentprefs> Dumps a copy of the current preferences file to stdout. - -B<decodes> Dumps the "layer type"/"decode as" associations to stdout. -There is one record per line. The fields are tab-delimited. - - * Field 1 = layer type, e.g. "tcp.port" - * Field 2 = selector in decimal - * Field 3 = "decode as" name, e.g. "http" - -B<defaultprefs> Dumps a default preferences file to stdout. - -B<dissector-tables> Dumps a list of dissector tables to stdout. There -is one record per line. The fields are tab-delimited. - - * 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 - -B<elastic-mapping> Dumps the ElasticSearch mapping file to stdout. - -B<fieldcount> Dumps the number of header fields to stdout. - -B<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 - * --------- - * Field 1 = 'P' - * Field 2 = descriptive protocol name - * Field 3 = protocol abbreviation - * - * Header Fields - * ------------- - * 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 - -B<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. - - * Field 1 = Folder type (e.g "Personal configuration:") - * Field 2 = Folder location (e.g. "/home/vagrant/.config/wireshark/") - -B<ftypes> Dumps the "ftypes" (fundamental types) understood by tshark. -There is one record per line. The fields are tab-delimited. - - * Field 1 = FTYPE (e.g "FT_IPv6") - * Field 2 = text description of type (e.g. "IPv6 address") - -B<heuristic-decodes> Dumps the heuristic decodes currently installed. -There is one record per line. The fields are tab-delimited. - - * 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") - -B<help> Displays the available report types. - -B<plugins> Dumps the plugins currently installed. -There is one record per line. The fields are tab-delimited. - - * Field 1 = plugin library (e.g. "gryphon.so") - * Field 2 = plugin version (e.g. 0.0.4) - * Field 3 = plugin type (e.g. "dissector" or "tap") - * Field 4 = full path to plugin file - -B<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. - - * Field 1 = protocol name - * Field 2 = protocol short name - * Field 3 = protocol filter name - -B<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 - * ------------- - * Field 1 = 'V' - * Field 2 = field abbreviation to which this value string corresponds - * Field 3 = Integer value - * Field 4 = String - * - * Range Strings - * ------------- - * 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 - * ------------------ - * Field 1 = 'T' - * Field 2 = field abbreviation to which this true/false string corresponds - * Field 3 = True String - * Field 4 = False String - -=item -h - -=item --help - -Print the version and options and exit. - -=item -H E<lt>input hosts fileE<gt> - -Read a list of entries from a "hosts" file, which will then be written -to a capture file. Implies B<-W n>. Can be called multiple times. - -The "hosts" file format is documented at -L<http://en.wikipedia.org/wiki/Hosts_(file)>. - -=item -i E<lt>capture interfaceE<gt> | - - -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 -"B<tshark -D>" (described above); a number, as reported by -"B<tshark -D>", can also be used. If you're using UNIX, "B<netstat --i>" or "B<ifconfig -a>" might also work to list interface names, -although not all versions of UNIX support the B<-a> option to B<ifconfig>. - -If no interface is specified, B<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, -B<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. Data read from pipes must be in -standard pcap format. - -This option can occur multiple times. When capturing from multiple -interfaces, the capture file will be saved in pcapng format. - -Note: the Win32 version of B<TShark> doesn't support capturing from -pipes! - -=item -I - -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 B<-i> option, it enables the monitor mode for all interfaces. -If used after an B<-i> option, it enables the monitor mode for -the interface specified by the last B<-i> option occurring before -this option. - -=item -j E<lt>protocol match filterE<gt> - -Protocol match filter used for ek|json|jsonraw|pdml output file types. -Parent node containing multiple child nodes is only included, -if the name is found in the filter. - -Example: B<tshark -j "ip ip.flags text"> - -=item -J E<lt>protocol match filterE<gt> - -Protocol top level filter used for ek|json|jsonraw|pdml output file types. -Parent node containing multiple child nodes is included with all children. - -Example: B<tshark -J "http tcp"> - -=item -K E<lt>keytabE<gt> - -Load kerberos crypto keys from the specified keytab file. -This option can be used multiple times to load keys from several files. - -Example: B<tshark -K krb5.keytab> - -=item -l - -Flush the standard output after the information for each packet is -printed. (This is not, strictly speaking, line-buffered if B<-V> -was specified; however, it is the same as line-buffered if B<-V> wasn't -specified, as only one line is printed for each packet, and, as B<-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 B<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 B<TShark> sees the -packet and generates that output, rather than seeing it only when the -standard output buffer containing that data fills up. - -=item -L - -List the data link types supported by the interface and exit. The reported -link types can be used for the B<-y> option. - -=item -n - -Disable network object name resolution (such as hostname, TCP and UDP port -names); the B<-N> option might override this one. - -=item -N E<lt>name resolving flagsE<gt> - -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 overrides B<-n> if both B<-N> and B<-n> -are present. If both B<-N> and B<-n> options are not present, all name -resolutions are turned on. - -The argument is a string that may contain the letters: - -B<d> to enable resolution from captured DNS packets - -B<m> to enable MAC address resolution - -B<n> to enable network address resolution - -B<N> to enable using external resolvers (e.g., DNS) for network address -resolution - -B<t> to enable transport-layer port number resolution - -=item -o E<lt>preferenceE<gt>:E<lt>valueE<gt> - -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 I<prefname>B<:>I<value>, where I<prefname> is the name of the -preference (which is the same name that would appear in the preference -file), and I<value> is the value to which it should be set. - -=item -O E<lt>protocolsE<gt> - -Similar to the B<-V> option, but causes B<TShark> to only show a -detailed view of the comma-separated list of I<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 "B<tshark -G -protocols>" to find the abbreviations of the protocols you can specify. - -=item -p - -I<Don't> put the interface into promiscuous mode. Note that the -interface might be in promiscuous mode for some other reason; hence, -B<-p> cannot be used to ensure that the only traffic that is captured is -traffic sent to or from the machine on which B<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 B<-i> option, no interface will be put into the -promiscuous mode. -If used after an B<-i> option, the interface specified by the last B<-i> -option occurring before this option will not be put into the -promiscuous mode. - -=item -P - -=item --print - -Decode and display the packet summary or details, even if writing raw -packet data using the B<-w> option, and even if packet output is -otherwise suppressed with B<-Q>. - -=item -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 B<-z> -option to calculate statistics and don't want the packet information -printed, just the statistics. - -=item -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. - -only display true errors; don't display the -initial message indicating the. This outputs less -than the B<-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 B<-z> -option to calculate statistics and don't want the packet information -printed, just the statistics. - -=item -r E<lt>infileE<gt> - -Read packet data from I<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). - -=item -R E<lt>Read filterE<gt> - -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 calculate when this filter is -applied. - -=item -s E<lt>capture snaplenE<gt> - -Set the default snapshot length to use when capturing live data. -No more than I<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 B<-i> option, it sets the default snapshot length. -If used after an B<-i> option, it sets the snapshot length for -the interface specified by the last B<-i> option occurring before -this option. If the snapshot length is not set specifically, -the default snapshot length is used if provided. - -=item -S E<lt>separatorE<gt> - -Set the line separator to be printed between packets. - -=item -t a|ad|adoy|d|dd|e|r|u|ud|udoy - -Set the format of the packet timestamp printed in summary lines. -The format can be one of: - -B<a> absolute: The absolute time, as local time in your time zone, -is the actual time the packet was captured, with no date displayed - -B<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 - -B<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 - -B<d> delta: The delta time is the time since the previous packet was -captured - -B<dd> delta_displayed: The delta_displayed time is the time since the -previous displayed packet was captured - -B<e> epoch: The time in seconds since epoch (Jan 1, 1970 00:00:00) - -B<r> relative: The relative time is the time elapsed between the first packet -and the current packet - -B<u> UTC: The absolute time, as UTC, is the actual time the packet was -captured, with no date displayed - -B<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 - -B<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 - -The default format is relative. - -=item -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: - -B<ek> Newline delimited JSON format for bulk import into Elasticsearch. -It can be used with B<-j> or B<-J> including the JSON filter or with -B<-x> to include raw hex-encoded packet data. -If B<-P> is specified it will print the packet summary only, with both -B<-P> and B<-V> it will print the packet summary and packet details. -If neither B<-P> or B<-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 - - -B<fields> The values of fields specified with the B<-e> option, in a -form specified by the B<-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. - -B<json> JSON file format. It can be used with B<-j> or B<-J> including -the JSON filter or with B<-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 - -B<jsonraw> JSON file format including only raw hex-encoded packet data. -It can be used with B<-j> including or B<-J> the JSON filter option. -Example of usage: - - tshark -T jsonraw -r file.pcap - tshark -T jsonraw -j "http tcp ip" -x -r file.pcap - -B<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 B<-V> option. Using the --color option -will add color attributes to B<pdml> output. These attributes are -nonstandard. - -B<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 B<-V> option was specified. - -B<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 B<pdml> output. These -attributes are nonstandard. - -B<tabs> Similar to the default B<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. - -B<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 B<-V> option was specified. This is the default. - -=item -u E<lt>seconds typeE<gt> - -Specifies the seconds type. Valid choices are: - -B<s> for seconds - -B<hms> for hours, minutes and seconds - -=item -U E<lt>tap nameE<gt> - -PDUs export, exports PDUs from infile to outfile according to the tap name given. Use -Y to filter. - -Enter an empty tap name "" to get a list of available names. - -=item -v - -=item --version - -Print the version and exit. - -=item -V - -Cause B<TShark> to print a view of the packet details. - -=item -w E<lt>outfileE<gt> | - - -Write raw packet data to I<outfile> or to the standard output if -I<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 B<-w> -option for this. - -=item -W E<lt>file format optionE<gt> - -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 Wireshark may automatically change the capture format to -B<pcapng> as needed. - -The argument is a string that may contain the following letter: - -B<n> write network address resolution information (pcapng only) - -=item -x - -Cause B<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. - -=item -X E<lt>eXtension optionsE<gt> - -Specify an option to be passed to a B<TShark> module. The eXtension option -is in the form I<extension_key>B<:>I<value>, where I<extension_key> can be: - -B<lua_script>:I<lua_script_filename> tells B<TShark> to load the given script in addition to the -default Lua scripts. - -B<lua_script>I<num>:I<argument> tells B<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'. - -B<read_format>:I<file_format> tells B<TShark> to use the given file format to read in the -file (the file given in the B<-r> command option). Providing no I<file_format> argument, or -an invalid one, will produce a file of available file formats to use. - -=item -y E<lt>capture link typeE<gt> - -Set the data link type to use while capturing packets. The values -reported by B<-L> are the values that can be used. - -This option can occur multiple times. If used before the first -occurrence of the B<-i> option, it sets the default capture link type. -If used after an B<-i> option, it sets the capture link type for -the interface specified by the last B<-i> option occurring before -this option. If the capture link type is not set specifically, -the default capture link type is used if provided. - -=item -Y E<lt>displaY filterE<gt> - -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. - -=item -M E<lt>auto session resetE<gt> - -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 - -=item -z E<lt>statisticsE<gt> - -Get B<TShark> to collect various types of statistics and display the -result after finishing reading the capture file. Use the B<-q> option -if you're reading a capture file and only want the statistics printed, -not any per-packet information. - -Note that the B<-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 B<-q> -option, as that option would suppress the printing of the regular packet -summary output, and must also not use the B<-V> option, as that would -cause packet detail information rather than packet summary information -to be printed. - -Currently implemented statistics are: - -=over 4 - -=item B<-z help> - -Display all possible values for B<-z>. - -=item B<-z> afp,srt[,I<filter>] - -Show Apple Filing Protocol service response time statistics. - -=item B<-z> camel,srt - -=item B<-z> compare,I<start>,I<stop>,I<ttl[0|1]>,I<order[0|1]>,I<variance>[,I<filter>] - -If the optional I<filter> is specified, only those packets that match the -filter will be used in the calculations. - -=item B<-z> conv,I<type>[,I<filter>] - -Create a table that lists all conversations that could be seen in the -capture. I<type> specifies the conversation endpoint types for which we -want to generate the statistics; currently the supported ones are: - - "bluetooth" Bluetooth addresses - "eth" Ethernet addresses - "fc" Fibre Channel addresses - "fddi" FDDI addresses - "ip" IPv4 addresses - "ipv6" IPv6 addresses - "ipx" IPX addresses - "jxta" JXTA message addresses - "ncp" NCP connections - "rsvp" RSVP connections - "sctp" SCTP addresses - "tcp" TCP/IP socket pairs Both IPv4 and IPv6 are supported - "tr" Token Ring addresses - "usb" USB addresses - "udp" UDP/IP socket pairs Both IPv4 and IPv6 are supported - "wlan" IEEE 802.11 addresses - -If the optional I<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. The table is sorted according to the total -number of frames. - -=item B<-z> dcerpc,srt,I<uuid>,I<major>.I<minor>[,I<filter>] - -Collect call/reply SRT (Service Response Time) data for DCERPC interface I<uuid>, -version I<major>.I<minor>. -Data collected is the number of calls for each procedure, MinSRT, MaxSRT -and AvgSRT. - -Example: S<B<-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 I<filter> is provided, the stats will only be calculated -on those calls that match that filter. - -Example: S<B<-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. - -=item B<-z> bootp,stat[,I<filter>] - -Show DHCP (BOOTP) statistics. - -=item B<-z> diameter,avp[,I<cmd.code>,I<field>,I<field>,I<...>] - -This option enables extraction of most important diameter fields from large capture files. -Exactly one text line for each diameter message with matched B<diameter.cmd.code> will be printed. - -Empty diameter command code or '*' can be specified to mach any B<diameter.cmd.code> - -Example: B<-z diameter,avp> extract default field set from diameter messages. - -Example: B<-z diameter,avp,280> extract default field set from diameter DWR messages. - -Example: B<-z diameter,avp,272> extract default field set from diameter CC messages. - -Extract most important fields from diameter CC messages: - -B<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. - -B<-z diameter,avp> option is much faster than B<-V -T text> or B<-T pdml> options. - -B<-z diameter,avp> option is more powerful than B<-T field> and B<-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. I<diameter.Subscription-Id-Data> or I<diameter.Rating-Group>. - -Note: B<tshark -q> option is recommended to suppress default B<tshark> output. - -=item B<-z> dns,tree[,I<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. - -=item B<-z> endpoints,I<type>[,I<filter>] - -Create a table that lists all endpoints that could be seen in the -capture. I<type> specifies the endpoint types for which we -want to generate the statistics; currently the supported ones are: - - "bluetooth" Bluetooth addresses - "eth" Ethernet addresses - "fc" Fibre Channel addresses - "fddi" FDDI addresses - "ip" IPv4 addresses - "ipv6" IPv6 addresses - "ipx" IPX addresses - "jxta" JXTA message addresses - "ncp" NCP connections - "rsvp" RSVP connections - "sctp" SCTP addresses - "tcp" TCP/IP socket pairs Both IPv4 and IPv6 are supported - "tr" Token Ring addresses - "usb" USB addresses - "udp" UDP/IP socket pairs Both IPv4 and IPv6 are supported - "wlan" IEEE 802.11 addresses - -If the optional I<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. The table is sorted according to the total -number of frames. - -=item B<-z> expert[I<,error|,warn|,note|,chat>][I<,filter>] - -Collects information about all expert info, and will display them in order, -grouped by severity. - -Example: B<-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. - -If the optional I<filter> is provided, the stats will only be calculated -on those calls that match that filter. - -Example: B<-z "expert,note,tcp"> will only collect expert items for frames that -include the tcp protocol, with a severity of note or higher. - -=item B<-z> flow,I<name>,I<mode>,[I<filter>] - -Displays the flow of data between two nodes. Output is the same as ASCII format -saved from GUI. - -I<name> specifies the flow name. It can be one of: - - any All frames - icmp ICMP - icmpv6 ICMPv6 - lbm_uim UIM - tcp TCP - -I<mode> specifies the address type. It can be one of: - - standard Any address - network Network address - -Example: B<-z flow,tcp,network> will show data flow for all TCP frames - -=item B<-z> follow,I<prot>,I<mode>,I<filter>[I<,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. - -I<prot> specifies the transport protocol. It can be one of: - - tcp TCP - udp UDP - ssl SSL - -I<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 - -Since the output in B<ascii> or B<ebcdic> mode may contain newlines, the length -of each section of output plus a newline precedes each section of output. - -I<filter> specifies the stream to be displayed. UDP/TCP streams are selected -with either the stream index or IP address plus port pairs. SSL streams are -selected with the stream index. For example: - - ip-addr0:port0,ip-addr1:port1 - stream-index - -I<range> optionally specifies which "chunks" of the stream should be displayed. - -Example: B<-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: B<-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 - .... - -=item B<-z> h225,counter[I<,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: B<-z h225,counter>. - -If the optional I<filter> is provided, the stats will only be calculated -on those calls that match that filter. -Example: use B<-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. - -=item B<-z> h225,srt[I<,filter>] - -Collect requests/response SRT (Service Response Time) data for ITU-T H.225 RAS. -Data collected is 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: B<tshark -z h225,srt> - -This option can be used multiple times on the command line. - -If the optional I<filter> is provided, the stats will only be calculated -on those calls that match that filter. - -Example: B<-z "h225,srt,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 . - -=item B<-z> hosts[,ipv4][,ipv6] - -Dump any collected IPv4 and/or IPv6 addresses in "hosts" format. Both IPv4 -and IPv6 addresses are dumped by default. - -Addresses are collected from a number of sources, including standard "hosts" -files and captured traffic. - -=item B<-z> hpfeeds,tree[,I<filter>] - -Calculate statistics for HPFEEDS traffic such as publish per channel, and opcode -distribution. - -=item B<-z> http,stat, - -Calculate the HTTP statistics distribution. Displayed values are -the HTTP status codes and the HTTP request methods. - -=item B<-z> http,tree - -Calculate the HTTP packet distribution. Displayed values are the -HTTP request modes and the HTTP status codes. - -=item B<-z> http_ref,tree - -Calculate the HTTP requests by referer. Displayed values are the -referring URI. - -=item B<-z> http_req,tree - -Calculate the HTTP requests by server. Displayed values are the -server name and the URI path. - -=item B<-z> http_srv,tree - -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. - -=item B<-z> icmp,srt[,I<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: S<B<-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. - -=item B<-z> icmpv6,srt[,I<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: S<B<-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. - -=item B<-z> io,phs[,I<filter>] - -Create Protocol Hierarchy Statistics listing both number of packets and bytes. -If no I<filter> is specified the statistics will be calculated for all packets. -If a I<filter> is specified statistics will only be calculated for those -packets that match the filter. - -This option can be used multiple times on the command line. - -=item B<-z> io,stat,I<interval>[,I<filter>][,I<filter>][,I<filter>]... - -Collect packet/bytes statistics for the capture in intervals of -I<interval> seconds. I<Interval> can be specified either as a whole or -fractional second and can be specified with microsecond (us) resolution. -If I<interval> is 0, the statistics will be calculated over all packets. - -If no I<filter> is specified the statistics will be calculated for all packets. -If one or more I<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: B<-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: B<-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. - -B<io,stat> can also do much more statistics and calculate COUNT(), SUM(), -MIN(), MAX(), AVG() and LOAD() using a slightly different filter syntax: - -=item -z io,stat,I<interval>,E<34>[COUNT|SUM|MIN|MAX|AVG|LOAD](I<field>)I<filter>E<34> - -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: B<-z io,stat,0.010,AVG(smb.time)> does not work. Use B<-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. - -B<COUNT(I<field>)I<filter>> - Calculates the number of times that the -field I<name> (not its value) appears per interval in the filtered packet list. -''I<field>'' can be any display filter name. - -Example: B<-z io,stat,0.010,E<34>COUNT(smb.sid)smb.sidE<34>> - -This will count the total number of SIDs seen in each 10ms interval. - -B<SUM(I<field>)I<filter>> - Unlike COUNT, the I<values> of the -specified field are summed per time interval. -''I<field>'' can only be a named integer, float, double or relative time field. - -Example: B<tshark -z io,stat,0.010,E<34>SUM(frame.len)frame.lenE<34>> - -Reports the total number of bytes that were transmitted bidirectionally in -all the packets within a 10 millisecond interval. - -B<MIN/MAX/AVG(I<field>)I<filter>> - 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 - ===================================================================================== - -B<LOAD(I<field>)I<filter>> - 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 - - - -B<FRAMES | BYTES[()I<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 - ======================================================================================================================= - -=item B<-z> mac-lte,stat[I<,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: B<tshark -z mac-lte,stat>. - -This option can be used multiple times on the command line. - -If the optional I<filter> is provided, the stats will only be calculated -for those frames that match that filter. -Example: B<-z "mac-lte,stat,mac-lte.rnti>3000"> will only collect stats for -UEs with an assigned RNTI whose value is more than 3000. - -=item B<-z> megaco,rtd[I<,filter>] - -Collect requests/response RTD (Response Time Delay) data for MEGACO. -(This is similar to B<-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: B<-z megaco,rtd>. - -If the optional I<filter> is provided, the stats will only be calculated -on those calls that match that filter. -Example: B<-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. - -=item B<-z> mgcp,rtd[I<,filter>] - -Collect requests/response RTD (Response Time Delay) data for MGCP. -(This is similar to B<-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: B<-z mgcp,rtd>. - -This option can be used multiple times on the command line. - -If the optional I<filter> is provided, the stats will only be calculated -on those calls that match that filter. -Example: B<-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 . - -=item B<-z> proto,colinfo,I<filter>,I<field> - -Append all I<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. -I<field> is the display-filter name of a field which value should be placed -in the Info column. -I<filter> is a filter string that controls for which packets the field value -will be presented in the info column. I<field> will only be presented in the -Info column for the packets which match I<filter>. - -NOTE: In order for B<TShark> to be able to extract the I<field> value -from the packet, I<field> MUST be part of the I<filter> string. If not, -B<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 - -B<-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: - -B<-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. - -=item B<-z> rlc-lte,stat[I<,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: B<tshark -z rlc-lte,stat>. - -This option can be used multiple times on the command line. - -If the optional I<filter> is provided, the stats will only be calculated -for those frames that match that filter. -Example: B<-z "rlc-lte,stat,rlc-lte.ueid>3000"> will only collect stats for -UEs with a UEId of more than 3000. - -=item B<-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. - -=item B<-z> rpc,srt,I<program>,I<version>[,I<filter>] - -Collect call/reply SRT (Service Response Time) data for I<program>/I<version>. -Data collected is the number of calls for each procedure, MinSRT, MaxSRT, -AvgSRT, and the total time taken for each procedure. - - -Example: B<tshark -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 I<filter> is provided, the stats will only be calculated -on those calls that match that filter. - -Example: B<-z rpc,srt,100003,3,nfs.fh.hash==0x12345678> will collect NFS v3 -SRT statistics for a specific file. - -=item B<-z> rtp,streams - -Collect statistics for all RTP streams and calculate max. delta, max. and -mean jitter and packet loss percentages. - -=item B<-z> scsi,srt,I<cmdset>[,I<filter>] - -Collect call/reply SRT (Service Response Time) data for SCSI commandset I<cmdset>. - -Commandsets are 0:SBC 1:SSC 5:MMC - -Data collected -is the number of calls for each procedure, MinSRT, MaxSRT and AvgSRT. - -Example: B<-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 I<filter> is provided, the stats will only be calculated -on those calls that match that filter. - -Example: B<-z scsi,srt,0,ip.addr==1.2.3.4> will collect SCSI SBC -SRT statistics for a specific iscsi/ifcp/fcip host. - -=item B<-z> sip,stat[I<,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: B<-z sip,stat>. - -This option can be used multiple times on the command line. - -If the optional I<filter> is provided, the stats will only be calculated -on those calls that match that filter. -Example: B<-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 . - -=item B<-z> smb,sids - -When this feature is used B<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 -S<B<-o "smb.sid_name_snooping:TRUE">> on the B<TShark> command line. - -The current method used by B<TShark> to find the SID->name mapping -is relatively restricted with a hope of future expansion. - -=item B<-z> smb,srt[,I<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: B<-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. - -If the optional I<filter> is provided, the stats will only be calculated -on those calls that match that filter. - -Example: B<-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 . - -=back - -=item --capture-comment E<lt>commentE<gt> - -Add a capture comment to the output file. - -This option is only available if a new output file in pcapng format is -created. Only one capture comment may be set per output file. - -=item --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. - -=item --time-stamp-type E<lt>typeE<gt> - -Change the interface's timestamp method. - -=item --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 -L<https://wiki.wireshark.org/ColoringRules> for more information on -configuring color filters. - -=item --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) - -=item --elastic-mapping-filter E<lt>protocolE<gt>,E<lt>protocolE<gt>,... - -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. - -=item --export-objects E<lt>protocolE<gt>,E<lt>destdirE<gt> - -Export all objects within a protocol into directory B<destdir>. The available -values for B<protocol> can be listed with B<--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. - -=item --enable-protocol E<lt>proto_nameE<gt> - -Enable dissection of proto_name. - -=item --disable-protocol E<lt>proto_nameE<gt> - -Disable dissection of proto_name. - -=item --enable-heuristic E<lt>short_nameE<gt> - -Enable dissection of heuristic protocol. - -=item --disable-heuristic E<lt>short_nameE<gt> - -Disable dissection of heuristic protocol. - -=back - -=head1 CAPTURE FILTER SYNTAX - -See the manual page of pcap-filter(7) or, if that doesn't exist, tcpdump(8), -or, if that doesn't exist, L<https://wiki.wireshark.org/CaptureFilters>. - -=head1 READ FILTER SYNTAX - -For a complete table of protocol and protocol fields that are filterable -in B<TShark> see the wireshark-filter(4) manual page. - -=head1 FILES - -These files contains various B<Wireshark> configuration values. - -=over 4 - -=item Preferences - -The F<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 B<-o> is used (possibly more than once), it will -in turn override values from the preferences files. - -The preferences settings are in the form I<prefname>B<:>I<value>, -one per line, -where I<prefname> is the name of the preference -and I<value> is the value to -which it should be set; white space is allowed between B<:> and -I<value>. A preference setting can be continued on subsequent lines by -indenting the continuation lines with white space. A B<#> 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 F<wireshark> directory -under the F<share> subdirectory of the main installation directory (for -example, F</usr/local/share/wireshark/preferences>) on UNIX-compatible -systems, and in the main installation directory (for example, -F<C:\Program Files\Wireshark\preferences>) on Windows systems. - -The personal preferences file is looked for in -F<$XDG_CONFIG_HOME/wireshark/preferences> -(or, if F<$XDG_CONFIG_HOME/wireshark> does not exist while F<$HOME/.wireshark> -is present, F<$HOME/.wireshark/preferences>) on -UNIX-compatible systems and F<%APPDATA%\Wireshark\preferences> (or, if -%APPDATA% isn't defined, F<%USERPROFILE%\Application -Data\Wireshark\preferences>) on Windows systems. - -=item Disabled (Enabled) Protocols - -The F<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 F<disabled_protos> file uses the same directory as the global -preferences file. - -The personal F<disabled_protos> file uses the same directory as the -personal preferences file. - -=item Name Resolution (hosts) - -If the personal F<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 F<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 and WinPcap on Windows. As such the Wireshark personal F<hosts> file -will not be consulted for capture filter name resolution. - -=item 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 F<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". - -=item Name Resolution (ethers) - -The F<ethers> files are consulted to correlate 6-byte hardware addresses to -names. First the personal F<ethers> file is tried and if an address is not -found there the global F<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 F<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 F<ethers> file is looked for in the F</etc> directory on -UNIX-compatible systems, and in the main installation directory (for -example, F<C:\Program Files\Wireshark>) on Windows systems. - -The personal F<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 WinPcap on Windows. As such the Wireshark personal F<ethers> file -will not be consulted for capture filter name resolution. - -=item Name Resolution (manuf) - -The F<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 F<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 F<manuf> file is looked for in the same directory as the global -preferences file. - -=item Name Resolution (services) - -The F<services> file is used to translate port numbers into names. - -The file has the standard F<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 - -=item Name Resolution (ipxnets) - -The F<ipxnets> files are used to correlate 4-byte IPX network numbers to -names. First the global F<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 F<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 F<ipxnets> file: - - C0.A8.2C.00 HR - c0-a8-1c-00 CEO - 00:00:BE:EF IT_Server1 - 110f FileServer3 - -The global F<ipxnets> file is looked for in the F</etc> directory on -UNIX-compatible systems, and in the main installation directory (for -example, F<C:\Program Files\Wireshark>) on Windows systems. - -The personal F<ipxnets> file is looked for in the same directory as the -personal preferences file. - -=back - -=head1 OUTPUT - -B<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 B<TShark> output -should expect UTF-8 and be prepared for invalid output. - -If B<TShark> detects that it is writing to a TTY on UNIX or Linux and -the locale does not support UTF-8, output will be re-encoded to match the -current locale. - -If B<TShark> detects that it is writing to a TTY on Windows, output will be -encoded as UTF-16LE. - -=head1 ENVIRONMENT VARIABLES - -=over 4 - -=item WIRESHARK_APPDATA - -On Windows, Wireshark normally stores all application data in %APPDATA% or -%USERPROFILE%. You can override the default location by exporting this -environment variable to specify an alternate location. - -=item 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 I<README.wmem> in the source distribution for -details. - -=item 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 *NIX. - -=item 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 *NIX. - -=item 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. - -=item 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. - -=item WIRESHARK_ABORT_ON_DISSECTOR_BUG - -If this environment variable is set, B<TShark> will call abort(3) -when a dissector bug is encountered. abort(3) will cause the program to -exit abnormally; if you are running B<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. - -=item WIRESHARK_ABORT_ON_TOO_MANY_ITEMS - -If this environment variable is set, B<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 -B<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. - -=back - -=head1 SEE ALSO - -wireshark-filter(4), wireshark(1), editcap(1), pcap(3), dumpcap(1), -text2pcap(1), mergecap(1), pcap-filter(7) or tcpdump(8) - -=head1 NOTES - -B<TShark> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. - -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. - -=head1 AUTHORS - -B<TShark> uses the same packet dissection code that B<Wireshark> does, -as well as using many other modules from B<Wireshark>; see the list of -authors in the B<Wireshark> man page for a list of authors of that code. diff --git a/doc/udpdump.pod b/doc/udpdump.adoc index 6a5a4c255c..4c68488ae6 100644 --- a/doc/udpdump.pod +++ b/doc/udpdump.adoc @@ -1,78 +1,71 @@ - -=head1 NAME - -udpdump - Provide an UDP receiver that gets packets from network devices (like Aruba routers) and exports them in PCAP format. - -=head1 SYNOPSIS - -B<udpdump> -S<[ B<--help> ]> -S<[ B<--version> ]> -S<[ B<--extcap-interfaces> ]> -S<[ B<--extcap-dlts> ]> -S<[ B<--extcap-interface>=E<lt>interfaceE<gt> ]> -S<[ B<--extcap-config> ]> -S<[ B<--capture> ]> -S<[ B<--fifo>=E<lt>path to file or pipeE<gt> ]> -S<[ B<--port>=E<lt>portE<gt> ]> -S<[ B<--payload>=E<lt>typeE<gt> ]> - -=head1 DESCRIPTION - -B<udpdump> is a extcap tool that provides an UDP receiver that listens for exported datagrams coming from +include::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://code.wireshark.org/review/gitweb?p=wireshark.git;a=blob;f=epan/exported_pdu.h;hb=refs/heads/master - -=head1 OPTIONS +https://gitlab.com/wireshark/wireshark/-/raw/master/epan/exported_pdu.h -=over 4 - -=item --help +== OPTIONS +--help:: Print program arguments. -=item --version - +--version:: Print program version. -=item --extcap-interfaces - +--extcap-interfaces:: List available interfaces. -=item --extcap-interface=E<lt>interfaceE<gt> - +--extcap-interface=<interface>:: Use specified interfaces. -=item --extcap-dlts - +--extcap-dlts:: List DLTs of specified interface. -=item --extcap-config - +--extcap-config:: List configuration options of specified interface. -=item --capture - +--capture:: Start capturing from specified interface save saved it in place specified by --fifo. -=item --fifo=E<lt>path to file or pipeE<gt> - +--fifo=<path to file or pipe>:: Save captured packet to file or send it through pipe. -=item --port=E<lt>portE<gt> - -Set the listerner port. Port 5555 is the default. - -=item --payload=E<lt>typeE<gt> +--port=<port>:: +Set the listener port. Port 5555 is the default. +--payload=<type>:: Set the payload of the exported PDU. Default: data. -=back - -=head1 EXAMPLES +== EXAMPLES To see program arguments: @@ -86,43 +79,43 @@ To see interfaces: udpdump --extcap-interfaces - Example output: +.Example output interface {value=udpdump}{display=UDP Listener remote capture} To see interface DLTs: udpdump --extcap-interface=udpdump --extcap-dlts - Example output: +.Example output dlt {number=252}{name=udpdump}{display=Exported PDUs} To see interface configuration options: udpdump --extcap-interface=udpdump --extcap-config - Example output: +.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 application. +NOTE: To stop capturing CTRL+C/kill/terminate the application. -=head1 SEE ALSO +== SEE ALSO -wireshark(1), tshark(1), dumpcap(1), extcap(4) +xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4) -=head1 NOTES +== NOTES -B<udpdump> is part of the B<Wireshark> distribution. The latest version -of B<Wireshark> can be found at L<https://www.wireshark.org>. +*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: -L<https://www.wireshark.org/docs/man-pages>. +HTML versions of the Wireshark project man pages are available at +https://www.wireshark.org/docs/man-pages. -=head1 AUTHORS +== AUTHORS - Original Author - --------------- - Dario Lombardo <lomato[AT]gmail.com> +.Original Author +[%hardbreaks] +Dario Lombardo <lomato[AT]gmail.com> diff --git a/doc/wifidump.adoc b/doc/wifidump.adoc new file mode 100644 index 0000000000..930ee27a37 --- /dev/null +++ b/doc/wifidump.adoc @@ -0,0 +1,229 @@ +include::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 0000000000..fe74dd81c3 --- /dev/null +++ b/doc/wireshark-filter.adoc @@ -0,0 +1,715 @@ +include::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 + dec(field) - converts an unsigned integer to a decimal string + hex(field) - converts an unsigned integer to a hexadecimal string + max(f1,...,fn) - return the maximum value + min(f1,...,fn) - return the minimum value + abs(field) - return the absolute value of numeric fields + +upper() and lower() are useful for performing case-insensitive string +comparisons. For example: + + upper(ncp.nds_stream_name) contains "MACRO" + lower(mount.dump.hostname) == "angel" + +string() converts a field value to a string, suitable for use with operators like +"matches" or "contains". Integer fields are converted to their decimal representation. +It can be used with IP/Ethernet addresses (as well as others), but not with string or +byte fields. For example: + + string(frame.number) matches "[13579]$" + +gives you all the odd packets. + +dec() and hex() convert unsigned integer fields to decimal or hexadecimal +representation. Currently dec() and string() give same result for an unsigned +integer, but it is possible that in the future string() will use the native +base of the field. + +max() and min() take any number of arguments and returns one value, respectively +the largest/smallest. The arguments must all have the same type. + +There is also a set of functions to test IP addresses: + + ip_special_name(ip) - Returns the IP special-purpose block name as a string + ip_special_mask(ip) - Returns the IP special-purpose block flags as a mask. The bits are: + 4 3 2 1 0 + --------- + S D F G R + S = Source, D = Destination, F = Forwardable, G = Globally-reachable, R = Reserved-by-protocol + + ip_linklocal(ip) - true if the IPv4 or IPv6 address is link-local + ip_multicast(ip) - true if the IPv4 or IPv6 address is multicast + ip_rfc1918(ipv4) - true if the IPv4 address is private-use (from the allocation in RFC 1918) + ip_ula(ipv6) - true if the IPv6 address is unique-local (ULA) as in RFC 4193 + +=== Macros + +It is possible to define display filter macros. Macro are names that are +replaced with the associated expression, possibly performing argument substitution. +Macro expansions are purely textual replacements and performed recursively before compilation. +They allow replacing long and often used expressions with easy to use names. + +Macros are defined using the GUI or directly in the "dmacros" configuration +file. For example the definition + + "addplusone" {$1 + $2 + 1} + +creates a macro called `addplusone` that takes two arguments and expands to the given expression. +Arguments in the replacement expression are given using the dollar sign. + +Macros are invoked like function but preceded with a dollar sign +(sometimes also called a sigil): + + $addplusone(udp.src_port,udp.dst_port) + +results in the expression + + {udp.src_port + udp.dst_port + 1} + +after argument substitution. There is an older alternative notation to invoke macros: + + ${addplusone:udp.src_port;udp.dst_port} + +or + + ${addplusone;udp.src_port;udp.dst_port} + +Both forms are equivalent and can be used interchangibly as a matter of +preference. + +=== Protocol field types + +Each protocol field is typed. The types are: +// `tshark -G ftypes | sed -e 's/.*\t/ /' | sort -f -u`, then fix up by hand + + ASN.1 object identifier, plain or relative + AX.25 address + Boolean + Byte sequence + Character string + Character, 1 byte + Date and time + Ethernet or other MAC address + EUI64 address + Fibre Channel WWN + Floating point, single or double precision + Frame number + Globally Unique Identifier + IEEE-11073 floating point, 16 or 32 bits + IPv4 address + IPv6 address + IPX network number + Label + OSI System-ID + Protocol + Signed integer, 1, 2, 3, 4, or 8 bytes + Time offset + Unsigned integer, 1, 2, 3, 4, or 8 bytes + VINES address + +An integer may be expressed in decimal, octal, hexadecimal or binary notation, +or as a C-style character constant. The following seven display filters +are equivalent: + + frame.len > 10 + frame.len > 012 + frame.len > 0xa + frame.len > 0b1010 + frame.len > '\n' + frame.len > '\x0a' + frame.len > '\012' + +Boolean values are either true or false. In a display filter expression +testing the value of a Boolean field, true is expressed as the word `true` +(case-insensitive) or any non-zero number. False is expressed as +`false` (case-insensitive) or the number zero. For example, a token-ring packet's +source route field is Boolean. To find any source-routed packets, a display +filter would be any of the following: + + tr.sr == 1 + tr.sr == true + tr.sr == TRUE + +Non source-routed packets can be found with: + + tr.sr == 0 + tr.sr == false + tr.sr == FALSE + +Ethernet addresses and byte arrays are represented by hex +digits. The hex digits may be separated by colons, periods, or hyphens: + + eth.dst eq ff:ff:ff:ff:ff:ff + aim.data == 0.1.0.d + fddi.src == aa-aa-aa-aa-aa-aa + echo.data == 7a + +IPv4 addresses can be represented in either dotted decimal notation or +by using the hostname: + + ip.src == 192.168.1.1 + ip.dst eq www.mit.edu + +IPv4 addresses can be compared with the same logical relations as numbers: +eq, ne, gt, ge, lt, and le. The IPv4 address is stored in host order, +so you do not have to worry about the endianness of an IPv4 address +when using it in a display filter. + +Classless Inter-Domain Routing (CIDR) notation can be used to test if an +IPv4 address is in a certain subnet. For example, this display filter +will find all packets in the 129.111 network: + + ip.addr == 129.111.0.0/16 + +Remember, the number after the slash represents the number of bits used +to represent the network. CIDR notation can also be used with +hostnames, as in this example of finding IP addresses on the same +network as 'sneezy' (requires that 'sneezy' resolve to an IP address for filter to be valid): + + ip.addr eq sneezy/24 + +The CIDR notation can only be used on IP addresses or hostnames, not in +variable names. So, a display filter like "ip.src/24 == ip.dst/24" is +not valid (yet). + +Transaction and other IDs are often represented by unsigned 16 or 32 bit integers +and formatted as a hexadecimal string with "0x" prefix: + + (dhcp.id == 0xfe089c15) || (ip.id == 0x0373) + +Strings are enclosed in double quotes: + + http.request.method == "POST" + +Inside double quotes, you may use a backslash to embed a double quote +or an arbitrary byte represented in either octal or hexadecimal. + + browser.comment == "An embedded \" double-quote" + +Use of hexadecimal to look for "HEAD": + + http.request.method == "\x48EAD" + +Use of octal to look for "HEAD": + + http.request.method == "\110EAD" + +This means that you must escape backslashes with backslashes inside +double quotes. + + smb.path contains "\\\\SERVER\\SHARE" + +looks for \\SERVER\SHARE in "smb.path". This may be more conveniently written +as + + smb.path contains r"\\SERVER\SHARE" + +String literals prefixed with 'r' are called "raw strings". Such strings treat +backslash as a literal character. Double quotes may still be escaped with +backslash but note that backslashes are always preserved in the result. + +The following table lists all escape sequences supported with strings +and character constants: + + \' single quote + \" double quote + \\ backslash + \a audible bell + \b backspace + \f form feed + \n line feed + \r carriage return + \t horizontal tab + \v vertical tab + \NNN arbitrary octal value + \xNN arbitrary hexadecimal value + \uNNNN Unicode codepoint U+NNNN + \UNNNNNNNN Unicode codepoint U+NNNNNNNN + +Date and time values can be given in ISO 8601 format or using a legacy +month-year-time format: + + "2020-07-04T12:34:56" + "Sep 26, 2004 23:18:04.954975" + +The 'T' separator in ISO 8601 can be omitted. The timezone can be given +as "Z" or an offset from UTC. + +When not using ISO 8601 the timezone can be given as the strings "UTC", "GMT" +or "UT" for UTC or also given as an offset from UTC, plus some North American and Nautical/Military +designations (https://man.netbsd.org/strptime.3[see the specification for %z in strptime(3)]). +Note that arbitrary timezone names are not supported however. + +If the timezone is omitted then date and time values are interpreted as local time. + +=== The slice operator + +You can take a slice of a field if the field base type is a text string or a +byte array (the base type of most network address fields is bytes). +For example, you can filter on the vendor portion of an ethernet address +(the first three bytes) like this: + + eth.src[0:3] == 00:00:83 + +Another example is: + + http.content_type[0:4] == "text" + +You can use the slice operator on a protocol name, too. +The "frame" protocol can be useful, encompassing all the data captured +by *Wireshark* or *TShark*. + + token[0:5] ne 0.0.0.1.1 + llc[0] eq aa + frame[100-199] contains "wireshark" + +The following syntax governs slices: + + [i:j] i = start_offset, j = length + [i-j] i = start_offset, j = end_offset, inclusive. + [i] i = start_offset, length = 1 + [:j] start_offset = 0, length = j + [i:] start_offset = i, end_offset = end_of_field + +Slice indexes are zero-based. +Offsets can be negative, in which case they indicate the +offset from the *end* of the field. The last byte of the field is at offset +-1, the last but one byte is at offset -2, and so on. +Here's how to check the last four bytes of a frame: + + frame[-4:4] == 0.1.2.3 + +or + + frame[-4:] == 0.1.2.3 + +As mentioned above the slice operator can be used on string and byte fields +and will respectively produce string or byte slices. String slices are +indexed on UTF-8 codepoint boundaries (i.e: internationalized characters), +so the following comparison is true: + + "touché"[5] == "é" + +The example above generates an error because the compiler rejects constant +expressions but is otherwise syntactically correct and exemplifies the +behaviour of string slices. + +To obtain a byte slice of the same string the raw (@) operator can be used: + + @"touché"[5-6] == c3:a9 + +A slice can always be compared against either a string or a byte sequence. + +Slices can be combined. You can concatenate them using the comma operator: + + ftp[1,3-5,9:] == 01:03:04:05:09:0a:0b + +This concatenates offset 1, offsets 3-5, and offset 9 to the end of the ftp +data. + +=== The layer operator + +A field can be restricted to a certain layer in the protocol stack using the +layer operator (#), followed by a decimal number: + + ip.addr#2 == 192.168.30.40 + +matches only the inner (second) layer in the packet. +Layers use simple stacking semantics and protocol layers are counted sequentially starting from 1. +For example, in a packet that contains two IPv4 headers, the outer (first) source address can be matched with "ip.src#1" and the inner (second) source address can be matched with "ip.src#2". + +For more complicated ranges the same syntax used with slices is valid: + + tcp.port#[2-4] + +means layers number 2, 3 or 4 inclusive. The hash symbol is required to +distinguish a layer range from a slice. + +=== The at operator + +By prefixing the field name with an at sign (@) the comparison is done against +the raw packet data for the field. + +A character string must be decoded from a source encoding during dissection. +If there are decoding errors the resulting string will usually contain +replacement characters: + +[subs="replacements"] +---- +browser.comment == "string is ����" +---- + +The at operator allows testing the raw undecoded data: + + @browser.comment == 73:74:72:69:6e:67:20:69:73:20:aa:aa:aa:aa + +The syntactical rules for a bytes field type apply to the second example. + +=== The membership operator + +A field may be checked for matches against a set of values simply with the +membership operator. For instance, you may find traffic on common HTTP/HTTPS +ports with the following filter: + + tcp.port in {80,443,8080} + +as opposed to the more verbose: + + tcp.port == 80 or tcp.port == 443 or tcp.port == 8080 + +To find HTTP requests using the HEAD or GET methods: + + http.request.method in {"HEAD", "GET"} + +The set of values can also contain ranges: + + tcp.port in {443, 4430..4434} + ip.addr in {10.0.0.5 .. 10.0.0.9, 192.168.1.1..192.168.1.9} + frame.time_delta in {10 .. 10.5} + +=== Implicit type conversions + +Fields which are sequences of bytes, including protocols, are implicitly +converted to strings for comparisons against (double quoted) literal strings +and raw strings. + +So, for instance, the following filters are equivalent: + + tcp.payload contains "GET" + tcp.payload contains 47.45.54 + +As noted above, a slice can also be compared in either way: + + frame[60:2] gt 50.51 + frame[60:2] gt "PQ" + +The inverse does not occur; stringlike fields are not implicitly converted to +byte arrays. (Some operators allow stringlike fields to be compared with +unquoted literals, which are then treated as strings; this is deprecated in +general and specifically disallowed by the "matches" operator. +Literal strings should be double quoted for clarity.) + +A hex integer that is 0xff or less (which means it fits inside one byte) +can be implicitly converted to a byte string. This is not allowed for +hex integers greater than one byte, because then one would need to specify +the endianness of the multi-byte integer. Also, this is not allowed for +decimal or octal numbers, since they would be confused with the hex numbers +that make up byte string literals. Nevertheless, single-byte hex integers +can be convenient: + + frame[4] == 0xff + frame[1:4] contains 0x02 + +=== Bitwise operators + +It is also possible to define tests with bitwise operations. Currently the +following bitwise operator is supported: + + bitand, bitwise_and, & Bitwise AND + +The bitwise AND operation allows masking bits and testing to see if one or +more bits are set. Bitwise AND operates on integer protocol fields and slices. + +When testing for TCP SYN packets, you can write: + + tcp.flags & 0x02 + +That expression will match all packets that contain a "tcp.flags" field +with the 0x02 bit, i.e. the SYN bit, set. + +To match locally administered unicast ethernet addresses you can use: + + eth.addr[0] & 0x0f == 2 + +When using slices, the bit mask must be specified as a byte string, and it must +have the same number of bytes as the slice itself, as in: + + ip[42:2] & 40:ff + +=== Arithmetic operators + +Arithmetic expressions are supported with the usual operators: + + + Addition + - Subtraction + * Multiplication + / Division + % Modulo (integer remainder) + +Arithmetic operations can be performed on numeric types. Numeric types are +integers, floating point numbers and date and time values. + +Date and time values can only be multiplied by integers or floating point +numbers (i.e: scalars) and furthermore the scalar multiplier must appear on +the right-hand side of the arithmetic operation. + +For example it is possible to filter for UDP destination ports greater or +equal by one to the source port with the expression: + + udp.dstport >= udp.srcport + 1 + +It is possible to group arithmetic expressions using curly brackets (parenthesis +will not work for this): + + tcp.dstport >= 4 * {tcp.srcport + 3} + +Do not confuse this usage of curly brackets with set membership. + +An unfortunate quirk in the filter syntax is that the subtraction operator +must be preceded by a space character, so "A-B" must be written as "A -B" +or "A - B". + +=== Protocol field references + +A variable using a sigil with the form $some.proto.field or ${some.proto.field} is called a field +reference. A field reference is a field value read from the currently +selected frame in the GUI. This is useful to build dynamic filters such as, +frames since the last five minutes to the selected frame: + + frame.time_relative >= ${frame.time_relative} - 300 + +or more simply + + frame.time_relative >= $frame.time_relative - 300 + +Field references share a similar notation to macros but are distinct +syntactical elements in the filter language. + +=== Logical expressions + +Tests can be combined using logical expressions. +These too are expressible in C-like syntax or with English-like +abbreviations. The following table lists the logical operators from +highest to lowest precedence: + + not, ! Logical NOT (right-associative) + and, && Logical AND (left-associative) + xor, ^^ Logical XOR (left-associative) + or, || Logical OR (left-associative) + +The evaluation is always performed left to right. Expressions can be grouped +by parentheses as well. The expression "A and B or not C or D and not E or F" +is read: + + (A and B) or (not C) or (D and (not E)) or F + +It's usually better to be explicit about grouping using parenthesis. +The following are all valid display filter expressions: + + tcp.port == 80 and ip.src == 192.168.2.1 + not llc + http and frame[100-199] contains "wireshark" + (ipx.src.net == 0xbad && ipx.src.node == 0.0.0.0.0.1) || ip + +Remember that whenever a protocol or field name occurs in an expression, the +"exists" operator is implicitly called. The "exists" operator has the highest +priority. This means that the first filter expression must be read as "show me +the packets for which tcp.port exists and equals 80, and ip.src exists and +equals 192.168.2.1". The second filter expression means "show me the packets +where not exists llc", or in other words "where llc does not exist" and hence +will match all packets that do not contain the llc protocol. +The third filter expression includes the constraint that offset 199 in the +frame exists, in other words the length of the frame is at least 200. + +Because each comparison has an implicit exists test for field values care must +be taken when using the display filter to remove noise from +the packet trace. If, for example, you want to filter out all IP +multicast packets to address 224.1.2.3, then using: + + ip.dst ne 224.1.2.3 + +may be too restrictive. This is the same as writing: + + ip.dst and ip.dst ne 224.1.2.3 + +The filter selects only frames that have the "ip.dst" field. Any +other frames, including all non-IP packets, will not be displayed. To +display the non-IP packets as well, you can use one of the following +two expressions: + + not ip.dst or ip.dst ne 224.1.2.3 + not ip.dst eq 224.1.2.3 + +The first filter uses "not ip.dst" to include all non-IP packets and then +lets "ip.dst ne 224.1.2.3" filter out the unwanted IP packets. The +second filter also negates the implicit existence test and so is +a shorter way to write the first. + +== FILTER FIELD REFERENCE + +The entire list of display filters is too large to list here. You can +can find references and examples at the following locations: + +* The online Display Filter Reference: https://www.wireshark.org/docs/dfref/ + +* __View:Internals:Supported Protocols__ in Wireshark + +* `tshark -G fields` on the command line + +* The Wireshark wiki: 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-filter.pod b/doc/wireshark-filter.pod deleted file mode 100644 index adffef2aab..0000000000 --- a/doc/wireshark-filter.pod +++ /dev/null @@ -1,465 +0,0 @@ - -=head1 NAME - -wireshark-filter - Wireshark filter syntax and reference - -=head1 SYNOPSIS - -B<wireshark> [other options] -S<[ B<-R> "filter expression" ]> - -B<tshark> [other options] -S<[ B<-R> "filter expression" ]> - -=head1 DESCRIPTION - -B<Wireshark> and B<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 B<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 -L<https://www.wireshark.org/docs/dfref/>. - -=head1 FILTER SYNTAX - -=head2 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". - -Think of a protocol or field in a filter as implicitly having the "exists" -operator. - -=head2 Comparison operators - -Fields can also be compared against values. 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 - -=head2 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 protocol or text 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 (quoted or unquoted), or bytes, -expressed as a byte array, or for a single character, expressed as a -C-style character constant. 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 (PCRE). The "matches" operator is only -implemented for protocols and for protocol fields with a text string -representation. Matches are case-insensitive by default. For example, -to search for a given WAP WSP User-Agent, you can write: - - wsp.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.user_agent matches "(?-i)cldc" - -This is an example of PCRE's B<(?>optionB<)> construct. B<(?-i)> performs a -case-sensitive pattern match but other options can be specified as well. More -information can be found in the pcrepattern(3) man page at -L<http://perldoc.perl.org/perlre.html>). - -=head2 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 - -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" - -=head2 Protocol field types - -Each protocol field is typed. The types are: - - ASN.1 object identifier - Boolean - Character string - Compiled Perl-Compatible Regular Expression (GRegex) object - Date and time - Ethernet or other MAC address - EUI64 address - Floating point (double-precision) - Floating point (single-precision) - Frame number - Globally Unique Identifier - IPv4 address - IPv6 address - IPX network number - Label - Protocol - Sequence of bytes - Signed integer, 1, 2, 3, 4, or 8 bytes - Time offset - Unsigned integer, 1, 2, 3, 4, or 8 bytes - 1-byte ASCII character - -An integer may be expressed in decimal, octal, or hexadecimal notation, -or as a C-style character constant. The following six display filters -are equivalent: - - frame.pkt_len > 10 - frame.pkt_len > 012 - frame.pkt_len > 0xa - frame.pkt_len > '\n' - frame.pkt_len > '\xa' - frame.pkt_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 1 or any -other non-zero value, and "false" is expressed as zero. For example, a -token-ring packet's source route field is Boolean. To find any -source-routed packets, a display filter would be: - - tr.sr == 1 - -Non source-routed packets can be found with: - - tr.sr == 0 - -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.dst eq www.mit.edu - ip.src == 192.168.1.1 - -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 InterDomain 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 Class-B 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 Class C -network as 'sneezy': - - 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). - -IPX networks are represented by unsigned 32-bit integers. Most likely -you will be using hexadecimal when testing IPX network values: - - ipx.src.net == 0xc0a82c00 - -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". - -=head2 The slice operator - -You can take a slice of a field if the field is a text string or a -byte array. -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 B<Wireshark> or B<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 - -Offsets can be negative, in which case they indicate the -offset from the B<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 - -A slice is always compared against either a string or a byte sequence. -As a special case, when the slice is only 1 byte wide, you can compare -it against a hex integer that 0xff or less (which means it fits inside -one byte). This is not allowed for byte sequences 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 numbers, since they -would be confused with hex numbers that are already allowed as -byte strings. Neverthelss, single-byte hex integers can be convienent: - - frame[4] == 0xff - -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. - -=head2 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} - -=head2 Type conversions - -If a field is a text string or a byte array, it can be expressed in whichever -way is most convenient. - -So, for instance, the following filters are equivalent: - - http.request.method == "GET" - http.request.method == 47.45.54 - -A range can also be expressed in either way: - - frame[60:2] gt 50.51 - frame[60:2] gt "PQ" - -=head2 Bit field operations - -It is also possible to define tests with bit field operations. Currently the -following bit field operation is supported: - - bitwise_and, & Bitwise AND - -The bitwise AND operation allows 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. - -Similarly, filtering for all WSP GET and extended GET methods is achieved with: - - wsp.pdu_type & 0x40 - -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 - -=head2 Logical expressions - -Tests can be combined using logical expressions. -These too are expressible in C-like syntax or with English-like -abbreviations: - - and, && Logical AND - or, || Logical OR - not, ! Logical NOT - -Expressions can be grouped by parentheses as well. 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 (llc exists)", 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. - -A special caveat must be given regarding fields that occur more than -once per packet. "ip.addr" occurs twice per IP packet, once for the -source address, and once for the destination address. Likewise, -"tr.rif.ring" fields can occur more than once per packet. The following -two expressions are not equivalent: - - ip.addr ne 192.168.4.1 - not ip.addr eq 192.168.4.1 - -The first filter says "show me packets where an ip.addr exists that -does not equal 192.168.4.1". That is, as long as one ip.addr in the -packet does not equal 192.168.4.1, the packet passes the display -filter. The other ip.addr could equal 192.168.4.1 and the packet would -still be displayed. -The second filter says "don't show me any packets that have an -ip.addr field equal to 192.168.4.1". If one ip.addr is 192.168.4.1, -the packet does not pass. If B<neither> ip.addr field is 192.168.4.1, -then the packet is displayed. - -It is easy to think of the 'ne' and 'eq' operators as having an implicit -"exists" modifier when dealing with multiply-recurring fields. "ip.addr -ne 192.168.4.1" can be thought of as "there exists an ip.addr that does -not equal 192.168.4.1". "not ip.addr eq 192.168.4.1" can be thought of as -"there does not exist an ip.addr equal to 192.168.4.1". - -Be careful with multiply-recurring fields; they can be confusing. - -Care must also 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. Filtering with "ip.dst" selects only those -B<IP> packets that satisfy the rule. Any other packets, 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 or ip.dst ne 224.1.2.3 - not ip.addr eq 224.1.2.3 - -The first filter uses "not ip" 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 has already been explained above where filtering with -multiply occurring fields was discussed. - -=head1 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: - -=over 4 - -=item * - -The online Display Filter Reference: L<https://www.wireshark.org/docs/dfref/> - -=item * - -I<Help:Supported Protocols> in Wireshark - -=item * - -C<tshark -G fields> on the command line - -=item * - -The Wireshark wiki: L<https://wiki.wireshark.org/DisplayFilters> - -=back - -=head1 NOTES - -The B<wireshark-filters> manpage is part of the B<Wireshark> distribution. -The latest version of B<Wireshark> can be found at -L<https://www.wireshark.org>. - -Regular expressions in the "matches" operator are provided by GRegex in GLib. -See L<http://developer.gnome.org/glib/2.32/glib-regex-syntax.html/> or L<http://www.pcre.org/> for more information. - -This manpage does not describe the capture filter syntax, which is -different. See the manual page of pcap-filter(7) or, if that doesn't exist, -tcpdump(8), or, if that doesn't exist, L<https://wiki.wireshark.org/CaptureFilters> -for a description of capture filters. - -=head1 SEE ALSO - -wireshark(1), tshark(1), editcap(1), pcap(3), pcap-filter(7) or tcpdump(8) if it -doesn't exist. - -=head1 AUTHORS - -See the list of authors in the B<Wireshark> man page for a list of authors of -that code. diff --git a/doc/wireshark.pod.template b/doc/wireshark.adoc index 039fb7138f..f77ebcbe3f 100644 --- a/doc/wireshark.pod.template +++ b/doc/wireshark.adoc @@ -1,218 +1,164 @@ -=begin man +include::attributes.adoc[] += wireshark(1) +:doctype: manpage +:stylesheet: ws.css +:linkcss: +:copycss: ../docbook/{stylesheet} -=encoding utf8 +== NAME -=end man +wireshark - Interactively dump and analyze network traffic -=head1 NAME +== SYNOPSIS -wireshark - Interactively dump and analyze network traffic +[manarg] +*wireshark* +[ *-i* <capture interface>|- ] +[ *-f* <capture filter> ] +[ *-Y* <display filter> ] +[ *-w* <outfile> ] +[ *options* ] +[ <infile> ] -=head1 SYNOPSIS - -B<wireshark> -S<[ B<-a> E<lt>capture autostop conditionE<gt> ] ...> -S<[ B<-b> E<lt>capture ring buffer optionE<gt> ] ...> -S<[ B<-B> E<lt>capture buffer sizeE<gt> ] > -S<[ B<-c> E<lt>capture packet countE<gt> ]> -S<[ B<-C> E<lt>configuration profileE<gt> ]> -S<[ B<-d> E<lt>layer typeE<gt>==E<lt>selectorE<gt>,E<lt>decode-as protocolE<gt> ]> -S<[ B<-D> ]> -S<[ B<--display=>E<lt>X display to useE<gt> ] > -S<[ B<-f> E<lt>capture filterE<gt> ]> -S<[ B<--fullscreen> ]> -S<[ B<-g> E<lt>packet numberE<gt> ]> -S<[ B<-h> ]> -S<[ B<-H> ]> -S<[ B<-i> E<lt>capture interfaceE<gt>|- ]> -S<[ B<-I> ]> -S<[ B<-j> ]> -S<[ B<-J> E<lt>jump filterE<gt> ]> -S<[ B<-k> ]> -S<[ B<-K> E<lt>keytabE<gt> ]> -S<[ B<-l> ]> -S<[ B<-L> ]> -S<[ B<-m> E<lt>fontE<gt> ]> -S<[ B<-n> ]> -S<[ B<-N> E<lt>name resolving flagsE<gt> ] > -S<[ B<-o> E<lt>preference/recent settingE<gt> ] ...> -S<[ B<-p> ]> -S<[ B<-P> E<lt>path settingE<gt>]> -S<[ B<-r> E<lt>infileE<gt> ]> -S<[ B<-R> E<lt>read (display) filterE<gt> ]> -S<[ B<-s> E<lt>capture snaplenE<gt> ]> -S<[ B<-S> ]> -S<[ B<-t> a|ad|adoy|d|dd|e|r|u|ud|udoy ]> -S<[ B<-v> ]> -S<[ B<-w> E<lt>outfileE<gt> ]> -S<[ B<-X> E<lt>eXtension optionE<gt> ]> -S<[ B<-y> E<lt>capture link typeE<gt> ]> -S<[ B<-Y> E<lt>displaY filterE<gt> ]> -S<[ B<-z> E<lt>statisticsE<gt> ]> -S<[ B<--enable-protocol> E<lt>proto_nameE<gt> ]> -S<[ B<--disable-protocol> E<lt>proto_nameE<gt> ]> -S<[ B<--enable-heuristic> E<lt>short_nameE<gt> ]> -S<[ B<--disable-heuristic> E<lt>short_nameE<gt> ]> -S<[ B<--list-time-stamp-types> ]> -S<[ B<--time-stamp-type> E<lt>typeE<gt> ]> -S<[ E<lt>infileE<gt> ]> - -=head1 DESCRIPTION - -B<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. B<Wireshark>'s native capture file format -is B<pcap> format, which is also the format used by B<tcpdump> and -various other tools. +[manarg] +*wireshark* +*-h|--help* -B<Wireshark> can read / import the following file formats: +[manarg] +*wireshark* +*-v|--version* -=over 4 +== DESCRIPTION -=item * -pcap - captures from B<Wireshark>/B<TShark>/B<dumpcap>, B<tcpdump>, -and various other tools using libpcap's/WinPcap's/tcpdump's/WinDump's -capture format +*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. -=item * -pcapng - "next-generation" successor to pcap format +*Wireshark* can also read / import the following file formats: -=item * -B<snoop> and B<atmsnoop> captures +* Oracle (previously Sun) *snoop* and *atmsnoop* captures -=item * -Shomiti/Finisar B<Surveyor> captures +* Finisar (previously Shomiti) *Surveyor* captures -=item * -Novell B<LANalyzer> captures +* Microsoft *Network Monitor* captures -=item * -Microsoft B<Network Monitor> captures +* Novell *LANalyzer* captures -=item * -AIX's B<iptrace> captures +* AIX's *iptrace* captures -=item * -Cinco Networks B<NetXRay> captures +* Cinco Networks *NetXRay* captures -=item * -Network Associates Windows-based B<Sniffer> captures +* NETSCOUT (previously Network Associates/Network General) Windows-based +*Sniffer* captures -=item * -Network General/Network Associates DOS-based B<Sniffer> (compressed or uncompressed) captures +* Network General/Network Associates DOS-based *Sniffer* captures +(compressed or uncompressed) -=item * -AG Group/WildPackets/Savvius B<EtherPeek>/B<TokenPeek>/B<AiroPeek>/B<EtherHelp>/B<PacketGrabber> captures +* LiveAction (previously WildPackets/Savvius) **Peek*/*EtherHelp*/*PacketGrabber* captures -=item * -B<RADCOM>'s WAN/LAN analyzer captures +* *RADCOM*'s WAN/LAN analyzer captures -=item * -Network Instruments B<Observer> version 9 captures +* Viavi (previously Network Instruments) *Observer* captures -=item * -B<Lucent/Ascend> router debug output +* *Lucent/Ascend* router debug output -=item * -files from HP-UX's B<nettl> +* captures from HP-UX *nettl* -=item * -B<Toshiba's> ISDN routers dump output +* *Toshiba's* ISDN routers dump output -=item * -the output from B<i4btrace> from the ISDN4BSD project +* the output from *i4btrace* from the ISDN4BSD project -=item * -traces from the B<EyeSDN> USB S0. +* traces from the *EyeSDN* USB S0 -=item * -the output in B<IPLog> format from the Cisco Secure Intrusion Detection System +* the *IPLog* format output from the Cisco Secure Intrusion Detection System -=item * -B<pppd logs> (pppdump format) +* *pppd logs* (pppdump format) -=item * -the output from VMS's B<TCPIPtrace>/B<TCPtrace>/B<UCX$TRACE> utilities +* the output from VMS's *TCPIPtrace*/*TCPtrace*/*UCX$TRACE* utilities -=item * -the text output from the B<DBS Etherwatch> VMS utility +* the text output from the *DBS Etherwatch* VMS utility -=item * -Visual Networks' B<Visual UpTime> traffic capture +* Visual Networks' *Visual UpTime* traffic capture -=item * -the output from B<CoSine> L2 debug +* the output from *CoSine* L2 debug -=item * -the output from InfoVista's B<5View> LAN agents +* the output from InfoVista (previously Accellent) *5View* LAN agents -=item * -Endace Measurement Systems' ERF format captures +* Endace Measurement Systems' ERF format captures -=item * -Linux Bluez Bluetooth stack B<hcidump -w> traces +* Linux Bluez Bluetooth stack *hcidump -w* traces -=item * -Catapult DCT2000 .out files +* Catapult DCT2000 .out files -=item * -Gammu generated text output from Nokia DCT3 phones in Netmonitor mode +* Gammu generated text output from Nokia DCT3 phones in Netmonitor mode -=item * -IBM Series (OS/400) Comm traces (ASCII & UNICODE) +* IBM Series (OS/400) Comm traces (ASCII & UNICODE) -=item * -Juniper Netscreen snoop files +* Juniper Netscreen snoop files -=item * -Symbian OS btsnoop files +* Symbian OS btsnoop files -=item * -TamoSoft CommView files +* TamoSoft CommView files -=item * -Textronix K12xx 32bit .rf5 format files +* Tektronix K12xx 32bit .rf5 format files -=item * -Textronix K12 text file format captures +* Tektronix K12 text file format captures -=item * -Apple PacketLogger files +* Apple PacketLogger files -=item * -Files from Aethra Telecommunications' PC108 software for their test +* Captures from Aethra Telecommunications' PC108 software for their test instruments -=item * -MPEG-2 Transport Streams as defined in ISO/IEC 13818-1 +* 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 -=item * -Rabbit Labs CAM Inspector files +* Ixia IxVeriWave raw captures -=item * -Colasoft Capsa files +* Rabbit Labs CAM Inspector files -=back +* _systemd_ journal files -There is no need to tell B<Wireshark> what type of +* 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. -B<Wireshark> is also capable of reading any of these file formats if they -are compressed using gzip. B<Wireshark> recognizes this directly from +*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, B<Wireshark>'s main window shows 3 views +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, B<Wireshark> has some features that make it unique. It can +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 -B<Wireshark> are very powerful; more fields are filterable in B<Wireshark> +*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 B<Wireshark> progresses, expect more and more +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 @@ -220,205 +166,221 @@ 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, B<Wireshark> will compile, but will +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 -B<-r> option or can be specified as a command-line argument. +*-r* option or can be specified as a command-line argument. -=head1 OPTIONS +== OPTIONS -Most users will want to start B<Wireshark> without options and configure +Most users will want to start *Wireshark* without options and configure it from the menus instead. Those users may just skip this section. -=over 4 - -=item -a E<lt>capture autostop conditionE<gt> +-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: -Specify a criterion that specifies when B<Wireshark> is to stop writing -to a capture file. The criterion is of the form I<test>B<:>I<value>, -where I<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. -B<duration>:I<value> Stop writing to a capture file after I<value> seconds have -elapsed. +*files*:__value__ Stop writing to capture files after __value__ number of files +were written. -B<filesize>:I<value> Stop writing to a capture file after it reaches a size of -I<value> kB. If this option is used together with the -b option, Wireshark +*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. -B<files>:I<value> Stop writing to capture files after I<value> number of files -were written. - -=item -b E<lt>capture ring buffer optionE<gt> +*packets*:__value__ Stop writing to a capture file after it contains __value__ +packets. Acts the same as *-c*<capture packet count>. +-- -Cause B<Wireshark> to run in "multiple files" mode. In "multiple files" mode, -B<Wireshark> will write to several capture files. When the first capture file -fills up, B<Wireshark> will switch writing to the next file and so on. +-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 B<-w> flag, +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_20050604120117.pcap, outfile_00002_20050604120523.pcap, ... +e.g. outfile_00001_20240714120117.pcap, outfile_00002_20240714120523.pcap, ... -With the I<files> option it's also possible to form a "ring buffer". +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 B<Wireshark> will discard the data in the first file and start -writing to that file and so on. If the I<files> option is not set, +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 I<key>B<:>I<value>, -where I<key> is one of: - -B<duration>:I<value> switch to the next file after I<value> seconds have -elapsed, even if the current file is not completely filled up. +The criterion is of the form __key:value__, +where __key__ is one of: -B<interval>:I<value> switch to the next file when the time is an exact -multiple of I<value> seconds +*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. -B<filesize>:I<value> switch to the next file after it reaches a size of -I<value> kB. Note that the filesize is limited to a maximum value of 2 GiB. - -B<files>:I<value> begin again with the first file after I<value> number of +*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 B<files> criterion -requires either B<duration>, B<interval> or B<filesize> to be specified to -control when to go to the next file. It should be noted that each B<-b> -parameter takes exactly one criterion; to specify two criterion, each must be -preceded by the B<-b> option. +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. -Example: B<-b filesize:1000 -b files:5> results in a ring buffer of five files -of size one megabyte each. +*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. -=item -B E<lt>capture buffer sizeE<gt> +*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 B<Wireshark> attempts to set the buffer size +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 systems with libpcap 1.0.0 or later and on -Windows. It is not available on UNIX systems with earlier versions of +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 B<-i> option, it sets the default capture buffer size. -If used after an B<-i> option, it sets the capture buffer size for -the interface specified by the last B<-i> option occurring before +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. +-- -=item -c E<lt>capture packet countE<gt> - +-c <capture packet count>:: ++ +-- Set the maximum number of packets to read when capturing live -data. - -=item -C E<lt>configuration profileE<gt> +data. Acts the same as *-a packets:*<capture packet count>. +-- +-C <configuration profile>:: ++ +-- Start with the given configuration profile. - -=item -d E<lt>layer typeE<gt>==E<lt>selectorE<gt>,E<lt>decode-as protocolE<gt> - -Like Wireshark's B<Decode As...> feature, this lets you specify how a -layer type should be dissected. If the layer type in question (for example, -B<tcp.port> or B<udp.port> for a TCP or UDP port number) has the specified -selector value, packets should be dissected as the specified protocol. - -Example: B<-d tcp.port==8888,http> will decode any traffic running over -TCP port 8888 as HTTP. - -See the tshark(1) manual page for more examples. - -=item -D - -Print a list of the interfaces on which B<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 B<-i> flag to specify an interface on which to capture. - -This can be useful on systems that don't have a command to list them -(UNIX systems lacking B<ifconfig -a> or Linux systems lacking -B<ip link show>). The number can be useful on Windows systems, where -the interface name might be a long name or a GUID. - -Note that "can capture" means that B<Wireshark> was able to open -that device to do a live capture; if, on your system, a program doing a -network capture must be run from an account with special privileges (for -example, as root), then, if B<Wireshark> is run with the B<-D> flag and -is not run from such an account, it will not list any interfaces. - -=item --display=E<lt>X display to useE<gt> - +-- + +--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 Windows. - -=item -f E<lt>capture filterE<gt> +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 B<-i> option, it sets the default capture filter expression. -If used after an B<-i> option, it sets the capture filter expression for -the interface specified by the last B<-i> option occurring before +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: B<-f "predef:MyPredefinedHostOnlyFilter"> - -=item --fullscreen +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). +-- -=item -g E<lt>packet numberE<gt> - -After reading in a capture file using the B<-r> flag, go to the given I<packet number>. - -=item -h - -Print the version and options and exit. +-g <packet number>:: +After reading in a capture file using the *-r* flag, go to the given __packet number__. -=item -H +-h|--help:: +Print the version number and options and exit. +-H:: Hide the capture info dialog during live packet capture. -=item -i E<lt>capture interfaceE<gt>|- - +-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 -"B<wireshark -D>" (described above); a number, as reported by -"B<wireshark -D>", can also be used. If you're using UNIX, "B<netstat --i>" or "B<ifconfig -a>" might also work to list interface names, -although not all versions of UNIX support the B<-a> flag to B<ifconfig>. +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, B<Wireshark> searches the list of +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, -B<Wireshark> reports an error and doesn't start the capture. +*Wireshark* reports an error and doesn't start the capture. -Pipe names should be either the name of a FIFO (named pipe) or ``-'' to +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\.\B<pipename>''. Data read from pipes must be in -standard pcap format. +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. -This option can occur multiple times. When capturing from multiple -interfaces, the capture file will be saved in pcapng format. +"TCP@<host>:<port>" causes *Wireshark* to attempt to connect to the +specified port on the specified host and read pcapng or pcap data. -=item -I +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. @@ -430,260 +392,227 @@ 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 B<-i> option, it enables the monitor mode for all interfaces. -If used after an B<-i> option, it enables the monitor mode for -the interface specified by the last B<-i> option occurring before +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. +-- -=item -j - -Use after B<-J> to change the behavior when no exact match is found for +-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. -=item -J E<lt>jump filterE<gt> - -After reading in a capture file using the B<-r> flag, jump to the packet +-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. +-- -=item -k - -Start the capture session immediately. If the B<-i> flag was +-k:: ++ +-- +Start the capture session immediately. If the *-i* flag was specified, the capture uses the specified interface. Otherwise, -B<Wireshark> searches the list of interfaces, choosing the first +*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, B<Wireshark> reports an error and +interfaces; if there are no interfaces, *Wireshark* reports an error and doesn't start the capture. +-- -=item -K E<lt>keytabE<gt> - -Load kerberos crypto keys from the specified keytab file. -This option can be used multiple times to load keys from several files. - -Example: B<-K krb5.keytab> - -=item -l - +-l:: Turn on automatic scrolling if the packet display is being updated automatically as packets arrive during a capture (as specified by the -B<-S> flag). - -=item -L +*-S* flag). +-L|--list-data-link-types:: List the data link types supported by the interface and exit. -=item -n - -Disable network object name resolution (such as hostname, TCP and UDP port -names), the B<-N> flag might override this one. - -=item -N E<lt>name resolving flagsE<gt> - -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 flag overrides B<-n> if both B<-N> and B<-n> are -present. If both B<-N> and B<-n> flags are not present, all name resolutions -are turned on. - -The argument is a string that may contain the letters: - -B<m> to enable MAC address resolution - -B<n> to enable network address resolution - -B<N> to enable using external resolvers (e.g., DNS) for network address -resolution - -B<t> to enable transport-layer port number resolution - -B<d> to enable resolution from captured DNS packets - -=item -o E<lt>preference/recent settingE<gt> +--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 I<prefname>B<:>I<value>, where I<prefname> is the name of the +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 I<value> is the value to which it should be set. -Since B<Ethereal> 0.10.12, the recent settings replaces the formerly used +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 I<prefname> is "uat", you can override settings in various user access -tables using the form uatB<:>I<uat filename>:I<uat record>. I<uat filename> -must be the name of a UAT file, e.g. I<user_dlts>. I<uat_record> must be in +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\",\"\"" +-- -=item -p - -I<Don't> put the interface into promiscuous mode. Note that the +-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, -B<-p> cannot be used to ensure that the only traffic that is captured is -traffic sent to or from the machine on which B<Wireshark> is running, +*-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 B<-i> option, no interface will be put into the +occurrence of the *-i* option, no interface will be put into the promiscuous mode. -If used after an B<-i> option, the interface specified by the last B<-i> +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. +-- -=item -P E<lt>path settingE<gt> - +-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 I<key>B<:>I<path>, where I<key> is one of: +The criterion is of the form __key:path__, where __key__ is one of: -B<persconf>:I<path> path of personal configuration files, like the +*persconf*:__path__ path of personal configuration files, like the preferences files. -B<persdata>:I<path> path of personal data files, it's the folder initially +*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. +-- -=item -r E<lt>infileE<gt> - -Read packet data from I<infile>, can be any supported capture file format +-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 B<-i -> +here! To capture from a pipe or from stdin use *-i -* +-- -=item -R E<lt>read (display) filterE<gt> - -When reading a capture file specified with the B<-r> flag, causes the +-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. +-- -=item -s E<lt>capture snaplenE<gt> - +-s|--snapshot-length <capture snaplen>:: ++ +-- Set the default snapshot length to use when capturing live data. -No more than I<snaplen> bytes of each network packet will be read into +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 B<-i> option, it sets the default snapshot length. -If used after an B<-i> option, it sets the snapshot length for -the interface specified by the last B<-i> option occurring before +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. +-- -=item -S - +-S:: Automatically update the packet display as packets are coming in. -=item -t a|ad|adoy|d|dd|e|r|u|ud|udoy - -Set the format of the packet timestamp displayed in the packet list -window. The format can be one of: - -B<a> absolute: The absolute time, as local time in your time zone, -is the actual time the packet was captured, with no date displayed - -B<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 - -B<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 - -B<d> delta: The delta time is the time since the previous packet was -captured - -B<dd> delta_displayed: The delta_displayed time is the time since the -previous displayed packet was captured - -B<e> epoch: The time in seconds since epoch (Jan 1, 1970 00:00:00) - -B<r> relative: The relative time is the time elapsed between the first packet -and the current packet - -B<u> UTC: The absolute time, as UTC, is the actual time the packet was -captured, with no date displayed - -B<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 - -B<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 - -The default format is relative. - -=item -v - -Print the version and exit. - -=item -w E<lt>outfileE<gt> - -Set the default capture file name. - -=item -X E<lt>eXtension optionsE<gt> - -Specify an option to be passed to an B<Wireshark> module. The eXtension option -is in the form I<extension_key>B<:>I<value>, where I<extension_key> can be: - -B<lua_script>:I<lua_script_filename> tells B<Wireshark> to load the given script in addition to the +--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. -B<lua_script>I<num>:I<argument> tells B<Wireshark> to pass the given argument +**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'. -B<read_format>:I<file_format> tells B<Wireshark> to use the given file format to read in the -file (the file given in the B<-r> command option). - -B<stdin_descr>:I<description> tells B<Wireshark> to use the given description when -capturing from standard input (B<-i ->). +*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). -=item -y E<lt>capture link typeE<gt> +*stdin_descr*:__description__ tells *Wireshark* to use the given description when +capturing from standard input (*-i -*). +-- -If a capture is started from the command line with B<-k>, set the data -link type to use while capturing packets. The values reported by B<-L> +-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 B<-i> option, it sets the default capture link type. -If used after an B<-i> option, it sets the capture link type for -the interface specified by the last B<-i> option occurring before +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. +-- -=item -Y E<lt>displaY filterE<gt> - +-Y|--display-filter <displaY filter>:: Start with the given display filter. -=item -z E<lt>statisticsE<gt> - -Get B<Wireshark> to collect various types of statistics and display the result +-z <statistics>:: ++ +-- +Get *Wireshark* to collect various types of statistics and display the result in a window that updates in semi-real time. -Currently implemented statistics are: +Some of the currently implemented statistics are: +-- -=over 4 - -=item B<-z help> - -Display all possible values for B<-z>. - -=item B<-z> afp,srt[,I<filter>] +*-z help*:: +Display all possible values for *-z*. +*-z* afp,srt[,__filter__]:: ++ +-- Show Apple Filing Protocol service response time statistics. +-- -=item B<-z> conv,I<type>[,I<filter>] - +*-z* conv,__type__[,__filter__]:: ++ +-- Create a table that lists all conversations that could be seen in the -capture. I<type> specifies the conversation endpoint types for which we +capture. __type__ specifies the conversation endpoint types for which we want to generate the statistics; currently the supported ones are: "eth" Ethernet addresses @@ -696,7 +625,7 @@ want to generate the statistics; currently the supported ones are: "tr" Token Ring addresses "udp" UDP/IP socket pairs Both IPv4 and IPv6 are supported -If the optional I<filter> is specified, only those packets that match the +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 @@ -706,39 +635,41 @@ 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/". +-- -=item B<-z> dcerpc,srt,I<name-or-uuid>,I<major>.I<minor>[,I<filter>] - +*-z* dcerpc,srt,__name-or-uuid__,__major__.__minor__[,__filter__]:: ++ +-- Collect call/reply SRT (Service Response Time) data for DCERPC interface -I<name> or I<uuid>, version I<major>.I<minor>. +__name__ or __uuid__, version __major__.__minor__. Data collected is the number of calls for each procedure, MinSRT, MaxSRT and AvgSRT. -Interface I<name> and I<uuid> are case-insensitive. +Interface __name__ and __uuid__ are case-insensitive. -Example: S<B<-z dcerpc,srt,12345778-1234-abcd-ef00-0123456789ac,1.0>> will collect data for the CIFS SAMR Interface. +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 I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: S<B<-z dcerpc,srt,12345778-1234-abcd-ef00-0123456789ac,1.0,ip.addr==1.2.3.4>> will collect SAMR +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. +-- -=item B<-z> bootp,stat[,I<filter>] - +*-z* dhcp,stat[,__filter__]:: Show DHCP (BOOTP) statistics. -=item B<-z> expert - +*-z* expert:: Show expert information. -=item B<-z> fc,srt[,I<filter>] - +*-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: B<-z fc,srt> +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. @@ -748,49 +679,55 @@ displayed. This option can be used multiple times on the command line. -If the optional I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: B<-z "fc,srt,fc.id==01.02.03"> will collect stats only for +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 . +-- -=item B<-z> h225,counter[I<,filter>] - +*-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: B<-z h225,counter> +Example: *-z h225,counter* This option can be used multiple times on the command line. -If the optional I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: B<-z "h225,counter,ip.addr==1.2.3.4"> will collect stats only for +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 . +-- -=item B<-z> h225,srt[I<,filter>] - +*-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: B<-z h225,srt> +Example: *-z h225,srt* This option can be used multiple times on the command line. -If the optional I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: B<-z "h225,srt,ip.addr==1.2.3.4"> will collect stats only for +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 . +-- -=item B<-z> io,stat - +*-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 @@ -800,13 +737,15 @@ 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. +-- -=item B<-z> ldap,srt[,I<filter>] - +*-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: B<-z ldap,srt> +Example: *-z ldap,srt* will calculate the Service Response Time as the time delta between the Request and the Response. @@ -816,10 +755,10 @@ displayed. This option can be used multiple times on the command line. -If the optional I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: use B<-z "ldap,srt,ip.addr==10.1.1.1"> will collect stats only for +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: @@ -831,73 +770,81 @@ DELETE MODRDN COMPARE EXTENDED +-- -=item B<-z> megaco,srt[I<,filter>] - +*-z* megaco,srt[__,filter__]:: ++ +-- Collect request/response SRT (Service Response Time) data for MEGACO. -(This is similar to B<-z smb,srt>). Data collected is the number of calls +(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: B<-z megaco,srt> +Example: *-z megaco,srt* This option can be used multiple times on the command line. -If the optional I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: B<-z "megaco,srt,ip.addr==1.2.3.4"> will collect stats only for +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 . +-- -=item B<-z> mgcp,srt[I<,filter>] - +*-z* mgcp,srt[__,filter__]:: ++ +-- Collect request/response SRT (Service Response Time) data for MGCP. -(This is similar to B<-z smb,srt>). Data collected is the number of calls +(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: B<-z mgcp,srt> +Example: *-z mgcp,srt* This option can be used multiple times on the command line. -If the optional I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: B<-z "mgcp,srt,ip.addr==1.2.3.4"> will collect stats only for +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 . +-- -=item B<-z> mtp3,msus[,<filter>] - +*-z* mtp3,msus[,<filter>]:: Show MTP3 MSU statistics. -=item B<-z> multicast,stat[,<filter>] - +*-z* multicast,stat[,<filter>]:: Show UDP multicast stream statistics. -=item B<-z> rpc,programs - +*-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. +-- -=item B<-z> rpc,srt,I<name-or-number>,I<version>[,<filter>] - +*-z* rpc,srt,__name-or-number__,__version__[,<filter>]:: ++ +-- Collect call/reply SRT (Service Response Time) data for program -I<name>/I<version> or I<number>/I<version>. +__name__/__version__ or __number__/__version__. Data collected is the number of calls for each procedure, MinSRT, MaxSRT and AvgSRT. -Program I<name> is case-insensitive. +Program __name__ is case-insensitive. -Example: B<-z rpc,srt,100003,3> will collect data for NFS v3. +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 I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: S<B<-z rpc,srt,nfs,3,nfs.fh.hash==0x12345678>> will collect NFS v3 +Example: [.nowrap]#*-z rpc,srt,nfs,3,nfs.fh.hash==0x12345678*# will collect NFS v3 SRT statistics for a specific file. +-- -=item B<-z> scsi,srt,I<cmdset>[,<filter>] - +*-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 @@ -905,38 +852,42 @@ Commandsets are 0:SBC 1:SSC 5:MMC Data collected is the number of calls for each procedure, MinSRT, MaxSRT and AvgSRT. -Example: B<-z scsi,srt,0> will collect data for SCSI BLOCK COMMANDS (SBC). +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 I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: B<-z scsi,srt,0,ip.addr==1.2.3.4> will collect SCSI SBC +Example: *-z scsi,srt,0,ip.addr==1.2.3.4* will collect SCSI SBC SRT statistics for a specific iscsi/ifcp/fcip host. +-- -=item B<-z> sip,stat[I<,filter>] - +*-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: B<-z sip,stat> +Example: *-z sip,stat* This option can be used multiple times on the command line. -If the optional I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: B<-z "sip,stat,ip.addr==1.2.3.4"> will collect stats only for +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 . +-- -=item B<-z> smb,srt[,I<filter>] - +*-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: B<-z smb,srt> +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. @@ -949,85 +900,56 @@ 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 I<filter> is provided, the stats will only be calculated +If the optional __filter__ is provided, the stats will only be calculated on those calls that match that filter. -Example: B<-z "smb,srt,ip.addr==1.2.3.4"> will collect stats only for +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 . +-- -=item B<-z> voip,calls - +*-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: B<-z voip,calls> - -=item B<-z> wlan,stat[,<filter>] +Example: *-z voip,calls* +-- +*-z* wlan,stat[,<filter>]:: Show IEEE 802.11 network and station statistics. -=item B<-z> wsp,stat[,<filter>] - +*-z* wsp,stat[,<filter>]:: Show WSP packet counters. -=back +include::dissection-options.adoc[tag=!tshark] -=item --enable-protocol E<lt>proto_nameE<gt> +include::diagnostic-options.adoc[] -Enable dissection of proto_name. +== INTERFACE -=item --disable-protocol E<lt>proto_nameE<gt> +=== MENU ITEMS -Disable dissection of proto_name. +menu:File[Open]:: -=item --enable-heuristic E<lt>short_nameE<gt> +menu:File[Open Recent]:: -Enable dissection of heuristic protocol. - -=item --disable-heuristic E<lt>short_nameE<gt> - -Disable dissection of heuristic protocol. - -=item --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. - -=item --time-stamp-type E<lt>typeE<gt> - -Change the interface's timestamp method. - -=back - -=head1 INTERFACE - -=head2 MENU ITEMS - -=over 4 - -=item File:Open - -=item File:Open Recent - -=item File:Merge - -Merge another capture file to the currently loaded one. The I<File:Merge> +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. -=item File:Close - -Open or close a capture file. The I<File:Open> dialog box +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 I<File:Open Recent> is a submenu +matching the filter are discarded. The __File:Open Recent__ is a submenu and will show a list of previously opened files. -=item File:Save - -=item File:Save As +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 @@ -1036,57 +958,44 @@ 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. -=item File:File Set:List Files - +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_20050604101530.pcap. - -=item File:File Set:Next File +e.g.: Filename_00001_20240714101530.pcap. -=item File:File Set:Previous File +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. -=item File:Export - +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. -=item File:Print - +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. -Printing options can be set with the I<Edit:Preferences> menu item, or in the -dialog box popped up by this menu item. - -=item File:Quit - +menu:File[Quit]:: Exit the application. -=item Edit:Copy:Description - -Copies the description of the selected field in the protocol tree to -the clipboard. - -=item Edit:Copy:Fieldname +menu:Edit[Copy,Description]:: +Copies the description of the selected field in the protocol tree to the clipboard. -Copies the fieldname 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. -=item Edit:Copy:Value - -Copies the value of the selected field in the protocol tree to -the clipboard. - -=item Edit:Copy:As Filter +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. @@ -1095,9 +1004,11 @@ 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. +-- -=item Edit:Find 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 @@ -1110,37 +1021,35 @@ 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. +-- -=item Edit:Find Next - -=item Edit:Find Previous +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). -=item Edit:Mark Packet (toggle) - +menu:Edit[Mark Selected (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 L</"Edit:Find Packet"> dialog can be used to find the next or previous +the /"Edit:Find Packet" dialog can be used to find the next or previous marked packet. -=item Edit:Find Next Mark - -=item Edit:Find Previous Mark +menu:Edit[Find Next Mark]:: -Find next/previous marked packet. +menu:Edit[Find Previous Mark]:: +Find next or previous marked packet. -=item Edit:Mark All Packets +menu:Edit[Mark All Packets]:: -=item Edit:Unmark All Packets - -Mark / Unmark all packets that are currently displayed. - -=item Edit:Time Reference:Set Time Reference (toggle) +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*". @@ -1154,94 +1063,75 @@ hide these packets. If there is a column displayed for "Cumulative Bytes" this counter will be reset at every Time Reference packet. +-- -=item Edit:Time Reference:Find Next - -=item Edit:Time Reference:Find Previous +menu:Edit[Time Reference,Find Next]:: -Search forward / backward for a time referenced packet. +menu:Edit[Time Reference,Find Previous]:: +Search forward or backward for a time referenced packet. -=item Edit:Configuration Profiles +menu:Edit[Configuration Profiles]:: +Manage configuration profiles to be able to use more than one set of preferences and configurations. -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). -=item Edit:Preferences +menu:View[Main Toolbar]:: -Set the GUI, capture, printing and protocol options -(see L</Preferences> dialog below). - -=item View:Main Toolbar - -=item View:Filter Toolbar - -=item View:Statusbar +menu:View[Filter Toolbar]:: +menu:View[Statusbar]:: Show or hide the main window controls. -=item View:Packet List +menu:View[Packet List]:: -=item View:Packet Details - -=item View:Packet Bytes +menu:View[Packet Details]:: +menu:View[Packet Bytes]:: Show or hide the main window panes. -=item View:Time Display Format - +menu:View[Time Display Format]:: Set the format of the packet timestamp displayed in the packet list window. -=item View:Name Resolution:Resolve Name - +menu:View[Name Resolution,Resolve Name]:: Try to resolve a name for the currently selected item. -=item View:Name Resolution:Enable for ... Layer - +menu:View[Name Resolution,Enable for ... Layer]:: Enable or disable translation of addresses to names in the display. -=item View:Colorize Packet List - -Enable or disable the coloring rules. Disabling will improve performance. - -=item View:Auto Scroll in Live Capture - -Enable or disable the automatic scrolling of the -packet list while a live capture is in progress. - -=item View:Zoom In +menu:View[Colorize Packet List]:: +Enable or disable the coloring rules. +Disabling will improve performance. -=item View:Zoom Out +menu:View[Auto Scroll in Live Capture]:: +Enable or disable the automatic scrolling of the packet list while a live capture is in progress. -Zoom into / out of the main window data (by changing the font size). +menu:View[Zoom In]:: -=item View:Normal Size +menu:View[Zoom Out]:: +Zoom into or out of the main window data (by changing the font size). -Reset the zoom factor of zoom in / zoom out back to normal font size. - -=item View:Resize All Columns +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. -=item View:Expand / Collapse Subtrees - -Expands / Collapses the currently selected item and it's subtrees in the packet details. - -=item View:Expand All - -=item View:Collapse All - -Expand / Collapse all branches of the packet details. - -=item View:Colorize Conversation +menu:View[Expand / Collapse Subtrees]:: +Expand or collapse the currently selected item and its subtrees in the packet details. -Select color for a conversation. +menu:View[Expand All]:: -=item View:Reset Coloring 1-10 +menu:View[Collapse All]:: +Expand or Collapse all branches of the packet details. -Reset Color for a conversation. +menu:View[Colorize Conversation]:: +Select a color for a conversation. -=item View:Coloring Rules +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 @@ -1250,10 +1140,9 @@ 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. -=over - -=item How Colorization Works - +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 @@ -1261,48 +1150,31 @@ expressions use exactly the same syntax as display filter expressions. When Wireshark starts, the color filters are loaded from: -=over - -=item 1. - -The user's personal color filters file or, if that does not exist, - -=item 2. - -The global color filters file. - -=back +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. +-- -=back - -=item View:Show Packet In New Window - +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. -=item View:Reload - -Reload a capture file. Same as I<File:Close> and I<File:Open> the same -file again. - -=item Go:Back +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. -=item Go:Forward - +menu:Go[Forward]:: Go forward in previously visited packets history. -=item Go:Go To Packet - +menu:Go[Go To Packet]:: Go to a particular numbered packet. -=item Go:Go To Corresponding 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 @@ -1311,69 +1183,59 @@ 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. -=item Go:Previous Packet - -=item Go:Next Packet - -=item Go:First Packet - -=item Go:Last Packet +menu:Go[Previous Packet]:: -Go to the previous / next / first / last packet in the capture. +menu:Go[Next Packet]:: -=item Go:Previous Packet In Conversation +menu:Go[First Packet]:: -=item Go:Next Packet In Conversation +menu:Go[Last Packet]:: +Go to the previous, next, first, or last packet in the capture. -Go to the previous / next packet of the conversation (TCP, UDP or IP) +menu:Go[Previous Packet In Conversation]:: -=item Capture:Interfaces +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! -=item Capture:Options - -Initiate a live packet capture (see L</"Capture Options Dialog"> +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. The location of the file can be chosen by setting your -TMPDIR environment variable before starting B<Wireshark>. Otherwise, the -default TMPDIR location is system-dependent, but is likely either F</var/tmp> -or F</tmp>. - -=item Capture:Start +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. -=item Capture:Stop - +menu:Capture[Stop]:: Stop a running live capture. -=item Capture:Restart - +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. -=item Capture:Capture Filters - -Edit the saved list of capture filters, allowing filters to be added, -changed, or deleted. - -=item Analyze:Display Filters +menu:Capture[Capture Filters]:: +Edit the saved list of capture filters, allowing filters to be added, changed, or deleted. -Edit the saved list of display 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. -=item Analyze:Display Filter Macros - -Create shortcuts for complex macros - -=item Analyze:Apply as Filter +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. @@ -1383,21 +1245,25 @@ 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 B<Selected> option creates a display filter that tests for a match -of the data; the B<Not Selected> option creates a display filter that -tests for a non-match of the data. The B<And Selected>, B<Or Selected>, -B<And Not Selected>, and B<Or Not Selected> options add to the end of +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. +-- -=item Analyze:Prepare a Filter - +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. +-- -=item Analyze:Enabled Protocols - +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. @@ -1413,9 +1279,9 @@ dependent on TCP. The list of protocols can be saved, so that Wireshark will start up with the protocols in that list disabled. +-- -=item Analyze:Decode As - +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 @@ -1424,14 +1290,14 @@ 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. -=item Analyze:User Specified Decodes - +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. -=item Analyze:Follow TCP Stream - +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, @@ -1442,70 +1308,58 @@ resetting it back to no display filter). The window in which the data stream is displayed lets you select: -=over 8 - -=item * - -whether to display the entire conversation, or one or the other side of +* whether to display the entire conversation, or one or the other side of it; -=item * - -whether the data being displayed is to be treated as ASCII or EBCDIC +* whether the data being displayed is to be treated as ASCII or EBCDIC text or as raw hex data; -=back - and lets you print what's currently being displayed, using the same -print options that are used for the I<File:Print Packet> menu item, or +print options that are used for the __File:Print Packet__ menu item, or save it as text to a file. +-- -=item Analyze:Follow UDP Stream - -=item Analyze:Follow SSL Stream +menu:Analyze[Follow UDP Stream]:: -(Similar to Analyze:Follow TCP Stream) +menu:Analyze[Follow TLS Stream]:: +Similar to Analyze:Follow TCP Stream. -=item Analyze:Expert Info +menu:Analyze[Expert Info]:: -=item Analyze:Expert Info Composite +menu:Analyze[Expert Info Composite]:: +Show anomalies found by Wireshark in a capture file. -(Kind of) a log of anomalies found by Wireshark in a capture file. - -=item Analyze:Conversation Filter - -=item Statistics:Summary +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. -=item Statistics:Protocol Hierarchy - +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) B<ended> in a particular protocol. In +associated with those packets) *ended* in a particular protocol. In the table, they are listed under "End Packets" and "End Bytes". -=item Statistics:Conversations - -Lists of conversations; selectable by protocol. See Statistics:Conversation List below. - -=item Statistics:End Points - -List of End Point Addresses by protocol with packets/bytes/.... counts. +menu:Statistics[Conversations]:: +Lists of conversations; selectable by protocol. +See Statistics:Conversation List below. -=item Statistics:Packet Lengths +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, ...) -=item Statistics:IO Graphs - +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. @@ -1552,7 +1406,7 @@ second intervals. 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 B<Wireshark> will try to adjust the maxvalue +"auto" which means that *Wireshark* will try to adjust the maxvalue automatically. "advanced..." If Unit:advanced... is selected the window will display @@ -1646,9 +1500,11 @@ Below the graph are the LOAD values for each interval that would be calculated. | | | | | | | | | --------------------------------------------------> Time 500 1500 500 750 1000 500 0 0 +-- -=item Statistics:Conversation List - +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 @@ -1660,55 +1516,46 @@ 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 +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 B<-z conv> argument. - -=item Statistics:Service Response Time - -=over 4 - -=item * - -AFP +line using the *-z conv* argument. +-- -=item * +menu:Statistics[Service Response Time]:: ++ +-- -CAMEL +* AFP -=item * +* CAMEL -DCE-RPC +* DCE-RPC Open a window to display Service Response Time statistics for an arbitrary DCE-RPC program -interface and display B<Procedure>, B<Number of Calls>, B<Minimum SRT>, -B<Maximum SRT> and B<Average SRT> for all procedures for that +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 B<Wireshark>. +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. -=item * +* Diameter -Diameter - -=item * - -Fibre Channel +* Fibre Channel Open a window to display Service Response Time statistics for Fibre Channel -and display B<FC Type>, B<Number of Calls>, B<Minimum SRT>, -B<Maximum SRT> and B<Average SRT> for all FC types. +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 B<Wireshark>. +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. @@ -1717,60 +1564,46 @@ 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. -=item * - -GTP +* GTP -=item * - -H.225 RAS +* H.225 RAS Collect requests/response SRT (Service Response Time) data for ITU-T H.225 RAS. -Data collected is B<number of calls> for each known ITU-T H.225 RAS Message Type, -B<Minimum SRT>, B<Maximum SRT>, B<Average SRT>, B<Minimum in Packet>, and B<Maximum in Packet>. -You will also get the number of B<Open Requests> (Unresponded Requests), -B<Discarded Responses> (Responses without matching request) and Duplicate Messages. +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 B<Wireshark>. +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. -=item * - -LDAP - -=item * +* LDAP -MEGACO +* MEGACO -=item * - -MGCP +* MGCP Collect requests/response SRT (Service Response Time) data for MGCP. -Data collected is B<number of calls> for each known MGCP Type, -B<Minimum SRT>, B<Maximum SRT>, B<Average SRT>, B<Minimum in Packet>, and B<Maximum in Packet>. +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 B<Wireshark>. +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. -=item * - -NCP - -=item * +* NCP -ONC-RPC +* ONC-RPC Open a window to display statistics for an arbitrary ONC-RPC program interface -and display B<Procedure>, B<Number of Calls>, B<Minimum SRT>, B<Maximum SRT> and B<Average SRT> for all procedures for that program/version. +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 B<Wireshark>. +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 @@ -1779,20 +1612,14 @@ 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 +mouse button) Wireshark will display a popup menu offering several different filter operations to apply to the capture. -=item * - -RADIUS - -=item * - -SCSI +* RADIUS -=item * +* SCSI -SMB +* 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. @@ -1812,160 +1639,139 @@ 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 +mouse button) Wireshark will display a popup menu offering several different filter operations to apply to the capture. -=item * - -SMB2 - -=back - -=item Statistics:BOOTP-DHCP - - +* SMB2 +-- -=item Statistics:Compare +menu:Statistics[BOOTP-DHCP]:: +Show DHCP statistics. -Compare two Capture Files +menu:Statistics[Compare]:: +Compare two capture files. -=item Statistics:Flow Graph +menu:Statistics[Flow Graph]:: +Show protocol flows. -Flow Graph: General/TCP +menu:Statistics[HTTP]:: +HTTP Load Distribution, Packet Counter & Requests. -=item Statistics:HTTP +menu:Statistics[IP Addresses]:: +Count, Rate, and Percent by IP Address. -HTTP Load Distribution, Packet Counter & Requests +menu:Statistics[IP Destinations]:: +Count, Rate, and Percent by IP Address, protocol, and port. -=item Statistics:IP Addresses +menu:Statistics[IP Protocol Types]:: +Count, Rate, and Percent by IP Protocol Types. -Count/Rate/Percent by IP Address +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. -=item Statistics:IP Destinations +menu:Statistics[TCP Stream Graph]:: +Show Round Trip, Throughput, Time-Sequence (Stevens), or Time-Sequence (tcptrace) graphs. -Count/Rate/Percent by IP Address/protocol/port +menu:Statistics[UDP Multicast streams]:: +Multicast Streams counts, rates, and other statistics by source and destination address and port pairs. -=item Statistics:IP Protocol Types - -Count/Rate/Percent by IP Protocol Types - -=item 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. - -=item Statistics:TCP Stream Graph - -Graphs: Round Trip; Throughput; Time-Sequence (Stevens); Time-Sequence (tcptrace) - -=item Statistics:UDP Multicast streams - -Multicast Streams Counts/Rates/... by Source/Destination Address/Port pairs - -=item Statistics:WLAN Traffic - -WLAN Traffic Statistics - -=item Telephony:ITU-T H.225 +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 B<Wireshark>. +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. +-- -=item Telephony:SIP - +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 B<Wireshark>. +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. +-- -=item Tools:Firewall ACL Rules - +menu:Tools[Firewall ACL Rules]:: +Generate firewall rules for a selected packet. +menu:Help[Contents]:: +Display the User's Guide. -=item Help:Contents - -Some help texts. - -=item Help:Supported Protocols - +menu:Help[Supported Protocols]:: List of supported protocols and display filter protocol fields. -=item Help:Manual Pages - +menu:Help[Manual Pages]:: Display locally installed HTML versions of these manual pages in a web browser. -=item Help:Wireshark Online - -Various links to online resources to be open in a web browser, like -L<https://www.wireshark.org>. - -=item Help:About Wireshark +menu:Help[Wireshark Online]:: +Various links to online resources to be open in a web browser, like https://www.wireshark.org. -See various information about Wireshark (see L</About> dialog below), like the -version, the folders used, the available plugins, ... +menu:Help[About Wireshark]:: +See various information about Wireshark (see /About dialog below), like the version, the folders used, the available plugins, ... -=back - -=head2 WINDOWS - -=over 4 - -=item Main Window +=== 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 I<Layout> page in the dialog box popped -up by I<Edit:Preferences>, the following will describe the layout with the +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. +-- -=over 6 - -=item Main Toolbar - +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 -I<View:Main Toolbar>. - -=item Filter Toolbar +__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 I<Filter:> button lets you choose from a list of named +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 I<Apply> button, will cause the filter to be -applied to the current list of packets. Selecting the I<Reset> button +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 I<View:Filter Toolbar>. - -=item Packet List Pane +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 I<Columns> page in the dialog box popped -up by I<Edit:Preferences> lets you change this (although, unfortunately, +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). @@ -1980,49 +1786,42 @@ 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. +-- -=item Packet Details Pane - +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. -=item Packet Bytes Pane - +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. +-- -=item Statusbar - +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 I<View:Statusbar>. - -=back +The statusbar can be hidden by __View:Statusbar__. +-- -=item Preferences +Preferences:: +Adjust the behavior of *Wireshark*. -The I<Preferences> dialog lets you control various personal preferences -for the behavior of B<Wireshark>. - -=over 6 - -=item User Interface Preferences - -The I<User Interface> page is used to modify small aspects of the GUI to -your own personal taste: - -=over 6 - -=item Selection Bars +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, @@ -2031,23 +1830,19 @@ 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. -=item Save Window Position - +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. -=item Save Window Size - +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. -=item Save Window Maximized state - +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. -=item File Open Dialog Behavior - +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 @@ -2055,135 +1850,108 @@ 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. -=item Directory - +Directory:: Allows the user to specify a persistent File Open directory. Trailing slashes or backslashes will automatically be added. -=item File Open Preview timeout - +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. -=item Open Recent maximum list entries - +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. -=item Ask for unsaved capture files - +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. -=item Wrap during find - +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. -=item Settings dialogs show a save button - +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. -=item Web browser command - +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. -=item Display LEDs in the Expert Infos dialog tab labels - -This item determines if LED-like colored images are displayed in the -Expert Infos dialog tab labels. - -=back - -=item Layout Preferences - -The I<Layout> page lets you specify the general layout of the main window. +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. -=over 6 - -=item Scrollbars - +Scrollbars:: The vertical scrollbars in the three panes can be set to be either on the left or the right. -=item Alternating row colors - -=item Hex Display +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. -=item Toolbar style +Toolbar style:: -=item Filter toolbar placement +Filter toolbar placement:: -=item Custom window title +Custom window title:: -=back - -=item Column Preferences - -The I<Columns> page lets you specify the number, title, and format +Column Preferences:: ++ +-- +The __Columns__ page lets you specify the number, title, and format of each column in the packet list. -The I<Column title> entry is used to specify the title of the column +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 I<Column format> option menu. +displays can be specified using the __Column format__ option menu. The row of buttons on the left perform the following actions: +-- -=over 6 - -=item New - +New:: Adds a new column to the list. -=item Delete - +Delete:: Deletes the currently selected list item. -=item Up / Down - +Up / Down:: Moves the selected list item up or down one position. -=back +Font Preferences:: +The __Font__ page lets you select the font to be used for most text. -=item Font Preferences - -The I<Font> page lets you select the font to be used for most text. - -=item Color Preferences - -The I<Colors> page can be used to change the color of the 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. -=item Capture Preferences - -The I<Capture> page lets you specify various parameters for capturing +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 I<Interface:> combo box lets you specify the interface from which to +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 I<Data link type:> option menu lets you, for some interfaces, select +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 I<Limit each packet to ... bytes> check box lets you set the +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 I<Filter:> text entry lets you set a capture filter expression to be +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, @@ -2191,169 +1959,138 @@ 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 I<Capture packets in promiscuous mode> check box lets you specify +The __Capture packets in promiscuous mode__ check box lets you specify whether to put the interface in promiscuous mode when capturing. -The I<Update list of packets in real time> check box lets you specify +The __Update list of packets in real time__ check box lets you specify that the display should be updated as packets are seen. +-- -The I<Automatic scrolling in live capture> check box lets you specify -whether, in an "Update list of packets in real time" capture, the packet -list pane should automatically scroll to show the most recently captured -packets. - -=item Printing Preferences - -The radio buttons at the top of the I<Printing> page allow you choose -between printing packets with the I<File:Print Packet> menu item as text -or PostScript, and sending the output directly to a command or saving it -to a file. The I<Command:> text entry box, on UNIX-compatible systems, -is the command to send files to (usually B<lpr>), and the I<File:> entry -box lets you enter the name of the file you wish to save to. -Additionally, you can select the I<File:> button to browse the file -system for a particular save file. - -=item Name Resolution Preferences - -The I<Enable MAC name resolution>, I<Enable network name resolution> and -I<Enable transport name resolution> check boxes let you specify whether +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 I<Enable concurrent DNS name resolution> allows Wireshark to send out +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. -I<SMI paths> +__SMI paths__ -I<SMI modules> - -=item RTP Player Preferences +__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. -=item Protocol Preferences - +Protocol Preferences:: There are also pages for various protocols that Wireshark dissects, controlling the way Wireshark handles those protocols. -=back - -=item Edit Capture Filter List +Edit Capture Filter List:: -=item Edit Display Filter List +Edit Display Filter List:: -=item Capture Filter +Capture Filter:: -=item Display Filter +Display Filter:: -=item Read Filter +Read Filter:: -=item Search Filter - -The I<Edit Capture Filter List> dialog lets you create, modify, and -delete capture filters, and the I<Edit Display Filter List> dialog lets +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 I<Capture Filter> dialog lets you do all of the editing operations +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 I<Display Filter> dialog lets you do all of the editing operations +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 I<Read Filter> dialog lets you do all of the editing operations +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 I<Search Filter> dialog lets you do all of the editing operations +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 I<Filter name> entry specifies a -descriptive name for a filter, e.g. B<Web and DNS traffic>. The -I<Filter string> entry is the text that actually describes the filtering +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: +-- -=over 6 - -=item New - -If there is text in the two entry boxes, creates a new associated list -item. +New:: +If there is text in the two entry boxes, creates a new associated list item. -=item Edit - -Modifies the currently selected list item to match what's in the entry -boxes. - -=item Delete +Edit:: +Modifies the currently selected list item to match what's in the entry boxes. +Delete:: Deletes the currently selected list item. -=item Add Expression... - +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 I<Filter string> entry at the current +constructed to be entered into the __Filter string__ entry at the current cursor position. - -=item OK - -In the I<Capture Filter> dialog, closes the dialog box and makes the -filter in the I<Filter string> entry the filter in the I<Capture -Preferences> dialog. In the I<Display Filter> dialog, closes the dialog -box and makes the filter in the I<Filter string> entry the current -display filter, and applies it to the current capture. In the I<Read -Filter> dialog, closes the dialog box and makes the filter in the -I<Filter string> entry the filter in the I<Open Capture File> dialog. -In the I<Search Filter> dialog, closes the dialog box and makes the -filter in the I<Filter string> entry the filter in the I<Find Packet> +-- + +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. +-- -=item Apply - -Makes the filter in the I<Filter string> entry the current display -filter, and applies it to the current capture. - -=item Save +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. -=item Close - -Closes the dialog without doing anything with the filter in the I<Filter -string> entry. - -=back - -=item The Color Filters Dialog +Close:: +Closes the dialog without doing anything with the filter in the __Filter string__ entry. -This dialog displays a list of color filters and allows it to be -modified. - -=over - -=item THE FILTER LIST +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. -=item NEW - +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 @@ -2362,33 +2099,27 @@ 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. -=item EDIT - +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.) -=item ENABLE - +ENABLE:: Enables the selected color filter(s). -=item DISABLE - +DISABLE:: Disables the selected color filter(s). -=item DELETE - +DELETE:: Deletes the selected color filter(s). -=item EXPORT - +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). -=item IMPORT - +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 @@ -2396,101 +2127,89 @@ 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. -=item CLEAR - -Deletes your personal color filters file, reloads the global -color filters file, if any, and closes the dialog. - -=item UP +CLEAR:: +Deletes your personal color filters file, reloads the global color filters file, if any, and closes the dialog. -Moves the selected filter(s) up the list, making it more likely that -they will be used to color packets. +UP:: +Moves the selected filter(s) up the list, making it more likely that they will be used to color packets. -=item DOWN - -Moves the selected filter(s) down the list, making it less likely that -they will be used to color packets. - -=item OK +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. -=item APPLY - -Colors the packets according to the current list of color filters, but -does not close the dialog. - -=item SAVE +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. -=item CLOSE - +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. -=back - -=item Capture Options Dialog - -The I<Capture Options Dialog> lets you specify various parameters for +Capture Options Dialog:: ++ +-- +The __Capture Options Dialog__ lets you specify various parameters for capturing live packet data. -The I<Interface:> field lets you specify the interface from which to +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 I<Link layer header type:> field lets you specify the interfaces link +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 I<Capture packets in promiscuous mode> check box lets you specify +The __Capture packets in promiscuous mode__ check box lets you specify whether the interface should be put into promiscuous mode when capturing. -The I<Limit each packet to ... bytes> check box and field lets you +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 I<Capture Filter:> entry lets you specify the capture filter using a +The __Capture Filter:__ entry lets you specify the capture filter using a tcpdump-style filter string as described above. -The I<File:> entry lets you specify the file into which captured packets -should be saved, as in the I<Printer Options> dialog above. If not +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 I<File:Save As> menu item. +can save those packets to a file with the __File:Save As__ menu item. -The I<Use multiple files> check box lets you specify that the capture +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 -I<Update list of packets in real time> option is checked. +__Update list of packets in real time__ option is checked. -The I<Next file every ... megabyte(s)> check box and fields lets +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 I<Next file every ... minute(s)> check box and fields lets +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 I<Ring buffer with ... files> field lets you specify the number +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 I<Stop capture after ... files> field lets you specify the number +The __Stop capture after ... files__ field lets you specify the number of capture files used, until the capture is stopped. -The I<Stop capture after ... packet(s)> check box and field let +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 I<Stop capture after ... megabyte(s)> check box and field lets +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 @@ -2499,145 +2218,150 @@ 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 I<Stop capture after ... second(s)> check box and field let you +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 I<Update list of packets in real time> check box lets you specify +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 I<Automatic scrolling in live capture> check box +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 I<Enable MAC name resolution>, I<Enable network name resolution> and -I<Enable transport name resolution> check boxes let you specify whether +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. +-- -=item About - -The I<About> dialog lets you view various information about Wireshark. - -=item About:Wireshark +About:: +The __About__ dialog lets you view various information about Wireshark. -The I<Wireshark> page lets you view general information about Wireshark, +menu:About[Wireshark]:: +The __Wireshark__ page lets you view general information about Wireshark, like the installed version, licensing information and such. -=item About:Authors - -The I<Authors> page shows the author and all contributors. - -=item About:Folders - -The I<Folders> page lets you view the directory names where Wireshark is -searching it's various configuration and other files. +menu:About[Authors]:: +The __Authors__ page shows the author and all contributors. -=item About:Plugins +menu:About[Folders]:: +The __Folders__ page lets you view the directory names where Wireshark is +searching its various configuration and other files. -The I<Plugins> page lets you view the dissector plugin modules +menu:About[Plugins]:: ++ +-- +The __Plugins__ page lets you view the dissector plugin modules available on your system. -The I<Plugins List> shows the name and version of each dissector plugin +The __Plugins List__ shows the name and version of each dissector plugin module found on your system. -On Unix-compatible systems, the plugins are looked for in the following -directories: the F<lib/wireshark/plugins/$VERSION> directory under the -main installation directory (for example, -F</usr/local/lib/wireshark/plugins/$VERSION>), and then -F<$HOME/.wireshark/plugins>. +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: F<plugins\$VERSION> directory under the main installation -directory (for example, F<C:\Program Files\Wireshark\plugins\$VERSION>), -and then F<%APPDATA%\Wireshark\plugins\$VERSION> (or, if %APPDATA% isn't -defined, F<%USERPROFILE%\Application Data\Wireshark\plugins\$VERSION>). +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 I<Edit:Protocols> dialog box, just as +enabled and disabled using the __Edit:Protocols__ dialog box, just as protocols built into Wireshark are. +-- -=back +== CAPTURE FILTER SYNTAX -=head1 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 the manual page of pcap-filter(7) or, if that doesn't exist, tcpdump(8), -or, if that doesn't exist, L<https://wiki.wireshark.org/CaptureFilters>. - -=head1 DISPLAY FILTER SYNTAX +== DISPLAY FILTER SYNTAX For a complete table of protocol and protocol fields that are filterable -in B<Wireshark> see the wireshark-filter(4) manual page. - -=head1 FILES - -These files contains various B<Wireshark> configuration settings. +in *Wireshark* see the xref:wireshark-filter.html[wireshark-filter](4) manual page. -=over 4 +== FILES -=item Preferences +These files contains various *Wireshark* configuration settings. -The F<preferences> files contain global (system-wide) and personal +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 B<-o> is used (possibly more than once), it will +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 I<prefname>B<:>I<value>, +The preferences settings are in the form __prefname:value__, one per line, -where I<prefname> is the name of the preference -and I<value> is the value to -which it should be set; white space is allowed between B<:> and -I<value>. A preference setting can be continued on subsequent lines by -indenting the continuation lines with white space. A B<#> character +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 F<wireshark> directory -under the F<share> subdirectory of the main installation directory (for -example, F</usr/local/share/wireshark/preferences>) on UNIX-compatible -systems, and in the main installation directory (for example, -F<C:\Program Files\Wireshark\preferences>) on Windows systems. - -The personal preferences file is looked for in -F<$XDG_CONFIG_HOME/wireshark/preferences> -(or, if F<$XDG_CONFIG_HOME/wireshark> does not exist while F<$HOME/.wireshark> -is present, F<$HOME/.wireshark/preferences>) on -UNIX-compatible systems and F<%APPDATA%\Wireshark\preferences> (or, if -%APPDATA% isn't defined, F<%USERPROFILE%\Application -Data\Wireshark\preferences>) on Windows systems. - -Note: Whenever the preferences are saved by using the I<Save> button -in the I<Edit:Preferences> dialog box, your personal preferences file +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. - -=item Recent - -The F<recent> file contains personal settings (mostly GUI related) such -as the current B<Wireshark> window size. The file is saved at program exit and -read in at program start automatically. Note: The command line flag B<-o> +-- + +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 F<preferences> +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. +-- -=item Disabled (Enabled) Protocols - -The F<disabled_protos> files contain system-wide and personal lists of +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 @@ -2646,38 +2370,44 @@ for the protocol: http tcp # a comment -If a protocol is listed in the global F<disabled_protos> file, it is not -displayed in the I<Analyze:Enabled Protocols> dialog box, and so cannot +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 F<disabled_protos> file uses the same directory as the global +The global __disabled_protos__ file uses the same directory as the global preferences file. -The personal F<disabled_protos> file uses the same directory as the +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 I<Save> -button in the I<Analyze:Enabled Protocols> dialog box, your personal +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. +-- -=item Name Resolution (hosts) - -If the personal F<hosts> file exists, it is +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 F<hosts> +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 and WinPcap on Windows. As such the Wireshark personal F<hosts> file -will not be consulted for capture filter name resolution. +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. +-- -=item Name Resolution (subnets) +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 F<subnets> file. -Both the global F<subnets> file and personal F<subnets> files are used +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 @@ -2693,41 +2423,47 @@ An example is: 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". - -=item Name Resolution (ethers) +printed address would be "ws_test_network.0.1". +-- -The F<ethers> files are consulted to correlate 6-byte hardware addresses to -names. First the personal F<ethers> file is tried and if an address is not -found there the global F<ethers> file is tried next. +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 F<ethers> file: +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 F<ethers> file is looked for in the F</etc> directory on -UNIX-compatible systems, and in the main installation directory (for -example, F<C:\Program Files\Wireshark>) on Windows systems. +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 F<ethers> file is looked for in the same directory as the personal +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 WinPcap on Windows. As such the Wireshark personal F<ethers> file -will not be consulted for capture filter name resolution. - -=item Name Resolution (manuf) - -The F<manuf> file is used to match the 3-byte vendor portion of a 6-byte +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 F<ethers> files, except that entries such as: +file is the same as the __ethers__ files, except that entries such as: 00:00:0C Cisco @@ -2742,16 +2478,18 @@ 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 F<manuf> file is looked for in the same directory as the global +The __manuf__ file is looked for in the same directory as the global preferences file. +-- -=item Name Resolution (services) - -The F<services> file is used to translate port numbers into names. -Both the global F<services> file and personal F<services> files are used +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 F<services> file syntax; each line contains one +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 /. @@ -2760,74 +2498,83 @@ An example is: mydns 5045/udp # My own Domain Name Server mydns 5045/tcp # My own Domain Name Server +-- -=item Name Resolution (ipxnets) - -The F<ipxnets> files are used to correlate 4-byte IPX network numbers to -names. First the global F<ipxnets> file is tried and if that address is not +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 F<ethers> +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 F<ipxnets> file: +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 F<ipxnets> file is looked for in the F</etc> directory on -UNIX-compatible systems, and in the main installation directory (for -example, F<C:\Program Files\Wireshark>) on Windows systems. +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 F<ipxnets> file is looked for in the same directory as the +The personal __ipxnets__ file is looked for in the same directory as the personal preferences file. +-- -=item Capture Filters - -The F<cfilters> files contain system-wide and personal capture filters. +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 F<cfilters> file uses the same directory as the +The global __cfilters__ file uses the same directory as the global preferences file. -The personal F<cfilters> file uses the same directory as the personal +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 F<cfilters> file exists, it is used only if the personal -F<cfilters> file does not exist; global and personal capture filters are +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. +-- -=item Display Filters - -The F<dfilters> files contain system-wide and personal display filters. +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 F<dfilters> file uses the same directory as the +The global __dfilters__ file uses the same directory as the global preferences file. -The personal F<dfilters> file uses the same directory as the +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 F<dfilters> file exists, it is used only if the personal -F<dfilters> file does not exist; global and personal display filters are +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. +-- -=item Color Filters (Coloring Rules) - -The F<colorfilters> files contain system-wide and personal color filters. +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: @@ -2836,114 +2583,153 @@ background and foreground colors are appended: @tcp@tcp@[59345,58980,65534][0,0,0] @udp@udp@[28834,57427,65533][0,0,0] -The global F<colorfilters> file uses the same directory as the +The global __colorfilters__ file uses the same directory as the global preferences file. -The personal F<colorfilters> file uses the same directory as the +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 F<colorfilters> file exists, it is used only if the personal -F<colorfilters> file does not exist; global and personal color filters are +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. +-- -=item Plugins - +Plugins:: See above in the description of the About:Plugins page. -=back - -=head1 ENVIRONMENT VARIABLES - -=over 4 - -=item WIRESHARK_APPDATA - -On Windows, Wireshark normally stores all application data in %APPDATA% or -%USERPROFILE%. You can override the default location by exporting this -environment variable to specify an alternate location. - -=item WIRESHARK_DEBUG_WMEM_OVERRIDE - +== 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 I<README.wmem> in the source distribution for +when testing or debugging. See __README.wmem__ in the source distribution for details. -=item 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 *NIX. - -=item WIRESHARK_DATA_DIR +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 *NIX. +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. -=item ERF_RECORDS_TO_CHECK +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. -=item IPFIX_RECORDS_TO_CHECK - +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. -=item WIRESHARK_ABORT_ON_DISSECTOR_BUG - -If this environment variable is set, B<Wireshark> will call abort(3) +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 B<Wireshark> in a debugger, it +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. -=item WIRESHARK_ABORT_ON_TOO_MANY_ITEMS - -If this environment variable is set, B<Wireshark> will call abort(3) +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 -B<Wireshark> in a debugger, it should halt in the debugger and allow +*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. -=item WIRESHARK_QUIT_AFTER_CAPTURE - -Cause B<Wireshark> to exit after the end of the capture session. This -doesn't automatically start a capture; you must still use B<-k> to do -that. You must also specify an autostop condition, e.g. B<-c> or B<-a -duration:...>. This means that you will not be able to see the results +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. -=back +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. -=head1 SEE ALSO +== AUTHORS -wireshark-filter(4), tshark(1), editcap(1), pcap(3), dumpcap(1), mergecap(1), -text2pcap(1), pcap-filter(7) or tcpdump(8) +Wireshark would not be the powerful, featureful application it is without the generous contributions of hundreds of developers. -=head1 NOTES +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. -The latest version of B<Wireshark> can be found at -L<https://www.wireshark.org>. +== SEE ALSO -HTML versions of the Wireshark project man pages are available at: -L<https://www.wireshark.org/docs/man-pages>. +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) -=head1 AUTHORS +== 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. |