Support the Wireshark plugin for more Wireshark distributions

.github/workflows/ci-pr-validation.yaml

@@ -29,6 +29,34 @@ concurrency:
 
 jobs:
 
+  wireshark-dissector-build:
+    name: Build the Wireshark dissector
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        os: [ubuntu-20.04, macos-12]
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: Install deps (Ubuntu)
+        if: ${{ startsWith(matrix.os, 'ubuntu') }}
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y protobuf-compiler libprotobuf-dev wireshark-dev
+
+      - name: Install deps (macOS)
+        if: ${{ startsWith(matrix.os, 'macos') }}
+        run:
+          brew install wireshark protobuf
+
+      - name: Build wireshark plugin
+        run: |
+          cmake -S wireshark -B build-wireshark
+          cmake --build build-wireshark
+
   unit-tests:
     name: Run unit tests
     runs-on: ubuntu-22.04
@@ -264,7 +292,7 @@ jobs:
   check-completion:
     name: Check Completion
     runs-on: ubuntu-latest
-    needs: [unit-tests, cpp-build-windows, package, cpp-build-macos]
+    needs: [wireshark-dissector-build, unit-tests, cpp-build-windows, package, cpp-build-macos]
 
     steps:
       - run: true

CMakeLists.txt

@@ -71,9 +71,6 @@ MESSAGE(STATUS "BUILD_STATIC_LIB:  " ${BUILD_STATIC_LIB})
 option(BUILD_TESTS "Build tests" ON)
 MESSAGE(STATUS "BUILD_TESTS:  " ${BUILD_TESTS})
 
-option(BUILD_WIRESHARK "Build Pulsar Wireshark dissector" OFF)
-MESSAGE(STATUS "BUILD_WIRESHARK:  " ${BUILD_WIRESHARK})
-
 option(BUILD_PERF_TOOLS "Build Pulsar CLI perf producer/consumer" OFF)
 MESSAGE(STATUS "BUILD_PERF_TOOLS:  " ${BUILD_PERF_TOOLS})
 
@@ -416,10 +413,6 @@ if (BUILD_TESTS)
     add_subdirectory(tests)
 endif()
 
-if (BUILD_WIRESHARK)
-    add_subdirectory(wireshark)
-endif()
-
 find_package(ClangTools)
 set(BUILD_SUPPORT_DIR "${PROJECT_SOURCE_DIR}/build-support")
 add_custom_target(format ${BUILD_SUPPORT_DIR}/run_clang_format.py

README.md

@@ -225,6 +225,10 @@ cd tests
 ./pulsar-test-service-stop.sh
 ```
 
+## Wireshark Dissector
+
+See the [wireshark](wireshark/) directory for details.
+
 ## Requirements for Contributors
 
 It's required to install [LLVM](https://llvm.org/builds/) for `clang-tidy` and `clang-format`. Pulsar C++ client use `clang-format` **11** to format files.  `make format` automatically formats the files.

wireshark/CMakeLists.txt

@@ -17,67 +17,46 @@
 # under the License.
 #
 
-set(CMAKE_CXX_FLAGS "-O3 -g ${CMAKE_CXX_FLAGS}")
+cmake_minimum_required(VERSION 3.7)
+project(pulsar-cpp-wireshark)
 
-MESSAGE(STATUS "Use WIRESHARK_BUILD_TYPE: ${CMAKE_BUILD_TYPE}")
+set(CMAKE_CXX_STANDARD 11)
 
-if(CMAKE_BUILD_TYPE STREQUAL "Debug")
-    add_definitions("-DDEBUG")
-endif()
+find_path(WIRESHARK_INCLUDE_PATH wireshark/ws_version.h)
+if (WIRESHARK_INCLUDE_PATH)
+    add_definitions("-DWITH_WS_VERSION")
+else ()
+    message(STATUS "Cannot find ws_version.h, fallback to find config.h")
+    find_path(WIRESHARK_INCLUDE_PATH wireshark/config.h)
+endif ()
+if (NOT WIRESHARK_INCLUDE_PATH)
+    message(FATAL_ERROR "Failed to find WIRESHARK_INCLUDE_PATH")
+endif ()
 
-# Wireshark dependency's
-find_library(WIRESHARK_LIB wireshark)
-find_library(WIRESHARK_UTIL_LIB wsutil)
-find_path(WIRESHARK_INCLUDE_PATH wireshark/config.h)
-find_library(GLIB_LIB glib)
-include_directories(${GLIB_INCLUDE_DIRS})
 include(FindPkgConfig)
 pkg_check_modules(GLIB glib-2.0)
-include_directories(${WIRESHARK_INCLUDE_PATH}/wireshark ${GLIB_INCLUDE_DIRS} ../lib )
 
-MESSAGE(STATUS "Use WIRESHARK_LIB: ${WIRESHARK_LIB}")
-MESSAGE(STATUS "Use WIRESHARK_UTIL_LIB: ${WIRESHARK_UTIL_LIB}")
 MESSAGE(STATUS "Use WIRESHARK_INCLUDE_PATH: ${WIRESHARK_INCLUDE_PATH}")
 MESSAGE(STATUS "Use GLIB_INCLUDE_DIRS: ${GLIB_INCLUDE_DIRS}")
 
-# Protobuf libs
-if (NOT PROTOC_PATH)
-    set(PROTOC_PATH protoc)
-endif()
-
-include_directories(${Protobuf_INCLUDE_DIRS})
-find_library(Protobuf_LIBRARIES protobuf libprotobuf)
-find_path(Protobuf_INCLUDE_DIRS google/protobuf/stubs/common.h)
+find_package(Protobuf REQUIRED)
 
-set(AUTOGEN_DIR ${CMAKE_BINARY_DIR}/generated)
-file(MAKE_DIRECTORY ${AUTOGEN_DIR})
-set(LIB_AUTOGEN_DIR ${AUTOGEN_DIR}/lib)
-file(MAKE_DIRECTORY ${LIB_AUTOGEN_DIR})
-include_directories(${LIB_AUTOGEN_DIR})
+set(PROTO_SOURCES PulsarApi.pb.cc)
+protobuf_generate_cpp(${PROTO_SOURCES}
+    PulsarApi.pb.h
+    ${CMAKE_CURRENT_SOURCE_DIR}/../proto/PulsarApi.proto)
 
-# Protobuf generation is only supported natively starting from CMake 3.8
-# Using custom command for now
-set(PROTO_SOURCES ${LIB_AUTOGEN_DIR}/PulsarApi.pb.cc ${LIB_AUTOGEN_DIR}/PulsarApi.pb.h)
-ADD_CUSTOM_COMMAND(
-        OUTPUT ${PROTO_SOURCES}
-        COMMAND ${PROTOC_PATH} -I ../proto ../proto/PulsarApi.proto --cpp_out=${LIB_AUTOGEN_DIR}
-        DEPENDS
-        ../proto/PulsarApi.proto
-        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
-link_libraries(${Protobuf_LIBRARIES})
+include_directories(${WIRESHARK_INCLUDE_PATH}/wireshark
+    ${GLIB_INCLUDE_DIRS}
+    ${CMAKE_BINARY_DIR})
 
 # Build wireshark shared lib
 add_library(pulsar-dissector SHARED pulsarDissector.cc ${PROTO_SOURCES})
-SET(CMAKE_SHARED_LIBRARY_PREFIX )
 SET(CMAKE_SHARED_LIBRARY_SUFFIX .so)
 set_target_properties(pulsar-dissector PROPERTIES PREFIX "" DEFINE_SYMBOL "")
 
 if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "AppleClang" OR "${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
     set(CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS "${CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS} -undefined dynamic_lookup")
 endif()
 
-if (APPLE)
-    target_link_libraries(pulsar-dissector -Wl,-all_load ${PROTO_LIBRARIES})
-else ()
-    target_link_libraries(pulsar-dissector ${PROTOBUF_LIBRARIES})
-endif ()
+target_link_libraries(pulsar-dissector protobuf::libprotobuf-lite) 

wireshark/README.md

@@ -24,29 +24,15 @@
 The Pulsar Wireshark dissector allows to automatically decode the Pulsar binary protocol
 and visualize useful debug information (linking requests with responses, latency stats, etc.)
 
-## Install Wireshark
+![](./pulsar-dissector-example.jpg)
 
-Based on your operating system, run the following command.
+There is also [a dissector written in Lua](https://github.com/apache/pulsar/tree/master/wireshark), which only supports Wireshark before 4.0.
 
-- macOS
-
-```bash
-brew install homebrew/cask/wireshark
-```
-
-- Ubuntu
-
-```bash
-sudo apt install wireshark
-```
-
-## Install dependencies
+To install the Wireshark, see [the official documents](https://www.wireshark.org/) for details.
 
-To build the Wireshark plugin, install Wireshark with the development headers
+## How to use
 
-> **NOTE**
-> 
-> Make sure the Wireshark application version is the same as the Wireshark headers version.
+### Install dependencies
 
 - macOS
 
@@ -60,50 +46,31 @@ $ brew install wireshark
 $ sudo apt install wireshark-dev
 ```
 
-## Compile the dissector
+### Build from source
 
-> **Tip**
-> 
-> If the compiler cannot find the Wireshark headers, add the include path manually.
-> `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>`
-
-Compile the dissector.
+Run the following commands in this subdirectory.
 
 ```shell
-cmake -DBUILD_WIRESHARK=ON .
-make pulsar-dissector
+cmake -B build
+cmake --build build
 ```
 
-This creates the `pulsar-dissector.so` plugin library in the Wireshark directory.
-
-## Install Wireshark dissector
-
-Copy the dissector in the appropriate location so that Wireshark can find it at startup.
-
-### Find the Personal Plugins Location
-
-1. Open Wireshark.
-2. Click **About Wireshark**.
-3. Click **Folders** tab.
+Then the `pulsar-dissector.so` plugin will be created under the `build-wireshark` directory.
 
-You can see the location of personal plugins, which is important for the next step.
+> **NOTE**:
+>
+> If `cmake -B build` cannot find the `WIRESHARK_INCLUDE_PATH`, you have to provide the path manually by adding the `-DWIRESHARK_INCLUDE_PATH=/path/to/wireshark/include` option.
 
-Example
+### Copy to the plugin directory
 
-Wireshark 4.0.3 on macOS
+1. Run the Wireshark and click the menu **Help - About Wireshark - Plugins**, and then you can find the plugin directory. For example, it's `/usr/lib/x86_64-linux-gnu/wireshark/plugins/3.2/epan` on Ubuntu 20.04. Then, copy the dissector into that directory:
 
-```shell
-~/.local/lib/wireshark/plugins/4-0/
-```
-
-### Copy Wireshark dissector to appropriate location
+2. Copy the dissector into that directory.
 
-```shell
-mkdir -p ~/.local/lib/wireshark/plugins/4-0/epan
-cd wireshark
-cp pulsar-dissector.so ~/.local/lib/wireshark/plugins/4-0/epan
+```bash
+sudo cp ./build/pulsar-dissector.so /usr/lib/x86_64-linux-gnu/wireshark/plugins/3.2/epan/
 ```
 
-### Complete installation
+To verify whether it has been loaded successfully, restart the Wireshark and then you can see the plugin in the plugin list:
 
-Reboot Wireshark. You can see the pulsar-dissector in **View > Internals > Dissector Tables**.
+![](./wireshark-plugins.jpg)

wireshark/pulsarDissector.cc

@@ -16,13 +16,22 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+#if WITH_WS_VERSION
+#include <ws_version.h>
+constexpr int kWiresharkMajorVersion = WIRESHARK_VERSION_MAJOR;
+constexpr int kWiresharkMinorVersion = WIRESHARK_VERSION_MINOR;
+#else
+#include <config.h>
+constexpr int kWiresharkMajorVersion = VERSION_MAJOR;
+constexpr int kWiresharkMinorVersion = VERSION_MINOR;
+#endif
+
 #include <epan/column-utils.h>
 #include <epan/dissectors/packet-tcp.h>
 #include <epan/packet.h>
 #include <epan/proto.h>
 #include <epan/value_string.h>
 #include <glib.h>
-#include <ws_version.h>
 #include <wsutil/nstime.h>
 
 #include "PulsarApi.pb.h"
@@ -1216,8 +1225,8 @@ void proto_register_pulsar() {
 extern "C" {
 
 extern __attribute__((unused)) WS_DLL_PUBLIC_DEF const gchar plugin_version[] = VERSION;
-extern __attribute__((unused)) WS_DLL_PUBLIC_DEF const int plugin_want_major = WIRESHARK_VERSION_MAJOR;
-extern __attribute__((unused)) WS_DLL_PUBLIC_DEF const int plugin_want_minor = WIRESHARK_VERSION_MINOR;
+extern __attribute__((unused)) WS_DLL_PUBLIC_DEF const int plugin_want_major = kWiresharkMajorVersion;
+extern __attribute__((unused)) WS_DLL_PUBLIC_DEF const int plugin_want_minor = kWiresharkMinorVersion;
 
 WS_DLL_PUBLIC void plugin_register(void);