diff --git a/.github/workflows/ci-pr-validation.yaml b/.github/workflows/ci-pr-validation.yaml index 492ef950..93c6b74c 100644 --- a/.github/workflows/ci-pr-validation.yaml +++ b/.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 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..38bc30f8 100644 --- a/wireshark/CMakeLists.txt +++ b/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}) diff --git a/wireshark/README.md b/wireshark/README.md index 68d55494..91165d2f 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 +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=` +### 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) 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