Support the Wireshark plugin for more Wireshark distributions

### Motivation

apache#182 fixes the Wireshark
build process on macOS. However, it breaks the compatibility with some
Wireshark distributions like the default Wireshark 3.2.3 on Ubuntu
20.04. The reason is some Wireshark distributions use `config.h` to
record the versions, while other might use `ws_version.h`.

See
https://listman.redhat.com/archives/libvir-list/2020-September/msg00377.html
for a similar fix.

### Modifications

Try to find the `ws_version.h` first, if it's not found, find the
`config.h`. Add the workflow to verify it can be built on Ubuntu.

To be more user friendly:
- Separate the dissector from the whole project so that we can build the
  dissector without building the Pulsar C++ client.
- Refactor the README of the Wireshark dissector by focusing on how to
  use.

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

@@ -29,6 +29,25 @@ concurrency:
 
 jobs:
 
+  wireshark-dissector-build:
+    name: Build the Wireshark dissector
+    runs-on: ubuntu-20.04
+    timeout-minutes: 60
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: Install deps
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y protobuf-compiler libprotobuf-dev wireshark-dev
+
+      - 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 +283,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,26 +17,24 @@
 # 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}")
-
-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 )
+include_directories(${WIRESHARK_INCLUDE_PATH}/wireshark ${GLIB_INCLUDE_DIRS})
 
-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}")
 
@@ -45,9 +43,7 @@ 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})
@@ -64,7 +60,6 @@ ADD_CUSTOM_COMMAND(
         DEPENDS
         ../proto/PulsarApi.proto
         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
-link_libraries(${Protobuf_LIBRARIES})
 
 # Build wireshark shared lib
 add_library(pulsar-dissector SHARED pulsarDissector.cc ${PROTO_SOURCES})
@@ -76,8 +71,4 @@ if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "AppleClang" OR "${CMAKE_CXX_COMPILER_ID}
     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_LITE_LIBRARIES})

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
+To install the Wireshark, see [the official documents](https://www.wireshark.org/) for details.
 
-```bash
-brew install homebrew/cask/wireshark
-```
+## How to use
 
-- Ubuntu
-
-```bash
-sudo apt install wireshark
-```
-
-## Install dependencies
-
-To build the Wireshark plugin, install Wireshark with the development headers
-
-> **NOTE**
-> 
-> Make sure the Wireshark application version is the same as the Wireshark headers version.
+### Install dependencies
 
 - macOS
 
@@ -60,50 +46,25 @@ $ brew install wireshark
 $ sudo apt install wireshark-dev
 ```
 
-## Compile the dissector
-
-> **Tip**
-> 
-> If the compiler cannot find the Wireshark headers, add the include path manually.
-> `-DWIRESHARK_INCLUDE_PATH=<WIRESHARK_INCLUDE_PATH>`
+### Build from source
 
-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.
+Then the `pulsar-dissector.so` plugin will be created under the `build-wireshark` directory.
 
-## Install Wireshark dissector
+### Copy to the plugin directory
 
-Copy the dissector in the appropriate location so that Wireshark can find it at startup.
+Run the Wireshark, then click the menu `Help - About Wireshark - Plugins`, you will 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:
 
-### Find the Personal Plugins Location
-
-1. Open Wireshark.
-2. Click **About Wireshark**.
-3. Click **Folders** tab.
-
-You can see the location of personal plugins, which is important for the next step.
-
-Example
-
-Wireshark 4.0.3 on macOS
-
-```shell
-~/.local/lib/wireshark/plugins/4-0/
-```
-
-### Copy Wireshark dissector to appropriate location
-
-```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 it has been loaded successfully, restart the Wireshark, you will 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);