diff --git a/.github/workflows/ci-pr-validation.yaml b/.github/workflows/ci-pr-validation.yaml index 492ef950..67ce86fa 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 2492f653..7db05c42 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 ea0ccb7d..e3691c57 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 6676b4bc..dbfb0faa 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 68d55494..6c80a329 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 +![](./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=` - -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) diff --git a/wireshark/pulsar-dissector-example.jpg b/wireshark/pulsar-dissector-example.jpg new file mode 100755 index 00000000..f18e1be0 Binary files /dev/null and b/wireshark/pulsar-dissector-example.jpg differ diff --git a/wireshark/pulsarDissector.cc b/wireshark/pulsarDissector.cc index 12702b8b..c84741cb 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 +constexpr int kWiresharkMajorVersion = WIRESHARK_VERSION_MAJOR; +constexpr int kWiresharkMinorVersion = WIRESHARK_VERSION_MINOR; +#else +#include +constexpr int kWiresharkMajorVersion = VERSION_MAJOR; +constexpr int kWiresharkMinorVersion = VERSION_MINOR; +#endif + #include #include #include #include #include #include -#include #include #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 00000000..f714fbad Binary files /dev/null and b/wireshark/wireshark-plugins.jpg differ