This is an automated email from the ASF dual-hosted git repository.
xyz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-client-cpp.git
The following commit(s) were added to refs/heads/main by this push:
new 63c4245 Support the Wireshark plugin for more Wireshark distributions
(#183)
63c4245 is described below
commit 63c424555cdb1209c82e2f844d7414c1fc399ef8
Author: Yunze Xu <[email protected]>
AuthorDate: Fri Feb 3 16:22:02 2023 +0800
Support the Wireshark plugin for more Wireshark distributions (#183)
* Support the Wireshark plugin for more Wireshark distributions
### Motivation
https://github.com/apache/pulsar-client-cpp/pull/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.
### Verifications
Add a workflow to build Wireshark dissector on both Ubuntu and macOS.
---
.github/workflows/ci-pr-validation.yaml | 30 ++++++++++++-
CMakeLists.txt | 7 ---
README.md | 4 ++
wireshark/CMakeLists.txt | 69 ++++++++++++------------------
wireshark/README.md | 73 +++++++++-----------------------
wireshark/pulsar-dissector-example.jpg | Bin 0 -> 876001 bytes
wireshark/pulsarDissector.cc | 15 +++++--
wireshark/wireshark-plugins.jpg | Bin 0 -> 271303 bytes
8 files changed, 92 insertions(+), 106 deletions(-)
diff --git a/.github/workflows/ci-pr-validation.yaml
b/.github/workflows/ci-pr-validation.yaml
index 492ef95..67ce86f 100644
--- a/.github/workflows/ci-pr-validation.yaml
+++ b/.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
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 2492f65..7db05c4 100644
--- a/CMakeLists.txt
+++ b/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
diff --git a/README.md b/README.md
index ea0ccb7..e3691c5 100644
--- a/README.md
+++ b/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.
diff --git a/wireshark/CMakeLists.txt b/wireshark/CMakeLists.txt
index 6676b4b..dbfb0fa 100644
--- a/wireshark/CMakeLists.txt
+++ b/wireshark/CMakeLists.txt
@@ -17,58 +17,47 @@
# 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")
+if (CMAKE_SYSTEM_NAME STREQUAL "Darwin" AND CMAKE_SYSTEM_PROCESSOR STREQUAL
"arm64")
+ execute_process(COMMAND sh -c "find $(brew --prefix)/Cellar/wireshark
-name 'include' -type d"
+ OUTPUT_STRIP_TRAILING_WHITESPACE
+ OUTPUT_VARIABLE
+ EXTRA_INCLUDE_PATH)
endif()
+find_path(WIRESHARK_INCLUDE_PATH wireshark/ws_version.h PATHS
${EXTRA_INCLUDE_PATH})
+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 PATHS
${EXTRA_INCLUDE_PATH})
+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()
+find_package(Protobuf REQUIRED)
-include_directories(${Protobuf_INCLUDE_DIRS})
-find_library(Protobuf_LIBRARIES protobuf libprotobuf)
-find_path(Protobuf_INCLUDE_DIRS google/protobuf/stubs/common.h)
+set(PROTO_SOURCES PulsarApi.pb.cc)
+protobuf_generate_cpp(${PROTO_SOURCES}
+ PulsarApi.pb.h
+ ${CMAKE_CURRENT_SOURCE_DIR}/../proto/PulsarApi.proto)
-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})
-
-# 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 "")
@@ -76,8 +65,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::libprotobuf-lite)
diff --git a/wireshark/README.md b/wireshark/README.md
index 68d5549..6c80a32 100644
--- a/wireshark/README.md
+++ b/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
+
-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**.
+
diff --git a/wireshark/pulsar-dissector-example.jpg
b/wireshark/pulsar-dissector-example.jpg
new file mode 100755
index 0000000..f18e1be
Binary files /dev/null and b/wireshark/pulsar-dissector-example.jpg differ
diff --git a/wireshark/pulsarDissector.cc b/wireshark/pulsarDissector.cc
index 12702b8..c84741c 100644
--- a/wireshark/pulsarDissector.cc
+++ b/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);
diff --git a/wireshark/wireshark-plugins.jpg b/wireshark/wireshark-plugins.jpg
new file mode 100755
index 0000000..f714fba
Binary files /dev/null and b/wireshark/wireshark-plugins.jpg differ
