Zookeeper Client Packets Wireshark Dissector

Should works as of Wireshark v2.0.2.

This is a LUA dissector for the ZAB protocol used by Zookeeper.

Only the messages exchanged between the client and the server are supported

Installation

For the tshark CLI utility

$ tshark  \
    -X lua_script:zab.lua \
    -X lua_script1:port=20000 \
    [ ... tshark read/capture params ... ] \
    -VOzab  -Yzab -x | view -

A client may talk to many servers on different ports. Use the ports= argument to register several ports at once (this is useful for cluster scenarios):

$ tshark \
    -X lua_script:zab.lua \
    -X lua_script1:ports=2181,2182,20000 \
    -r <capture file> -Yzab

port=N always sets a single port (and is equivalent to ports=N), so the single-port form remains fully backward compatible.

For the Wireshark GUI

Windows:

1. Copy zab.lua to somewhere in your wireshark directory. For example, C:\Program Files\Wireshark.
2. Open init.lua in your wireshark root directory. Comment the line disable_lua = true or change it to disable_lua = false.

Linux/MacOS

1. Open/Create init.lua in your Wireshark config directory, ~/.config/wireshark, with the line disable_lua = false
2. Copy zab.lua to your plugins directory ~/.config/wireshark/plugins (you may have to create it)

Running

The default port is set to 2181, but keep in mind that clients can connect to the Zookeeper server using any port configured in the configuration file.

In Wireshark GUI, you can right click on a packet and request to "decode as..." and select the ZAB protocol.

With the tshark CLI, you'll need to use the -X lua_script1:port as above.

Automated Unit Testing

Automated unit tests are organized into granular per-opcode request/response type directories under tests/fixtures/ (e.g. connect, create, delete, exists, get_data, set_data, ping, reconfig).

No manual tshark installation is required if you have Nix installed.

1. Running All Opcode Unit Tests

$ nix run .#tests

Or directly using Python:

$ python3 tests/run_tests.py

Or running Nix flake checks:

$ nix flake check

2. Running Focused Tests for a Specific Opcode

Filter test execution to a single opcode type (e.g. create or exists):

$ python3 tests/run_tests.py --type create

3. Extracting New Packet Fixtures from kazoo-capture-runs/

To extract specific ZAB opcode packet frames from kazoo-capture-runs/ captures into target fixture files:

$ python3 tests/run_tests.py extract \
    --input kazoo-capture-runs/plain-3.9.5-capture/captures/kazoo-client-zoo1-1787186909.pcapng \
    --out tests/fixtures/create/instance_1.pcapng \
    --range 7-8

4. Updating Baseline Outputs

To generate or update baseline text files for newly added packet instances:

$ python3 tests/run_tests.py --update

Code quality tooling

The project ships two portable shell runners for Lua code quality. Both exit with status 0 on clean code and 1 when issues are found.

$ ./scripts/lint.sh        # run luacheck against zab.lua
$ ./scripts/format.sh      # format zab.lua in place (stylua)
$ ./scripts/format.sh --check  # verify zab.lua is formatted (no changes)

Install the underlying tools if they are missing:

$ luarocks install luacheck   # Lua linter
$ brew install stylua         # or: cargo install stylua

The recommended way to get the exact tool versions used by CI is the Nix dev shell defined by flake.nix:

$ nix develop                                            # enter the dev shell
$ nix develop --command ./scripts/lint.sh                # lint (no shell entry)
$ nix develop --command ./scripts/format.sh --check      # format check (no shell entry)

nix develop provides luacheck and stylua pinned by flake.lock, so local runs and CI use identical tooling.

Every pull request is validated automatically by the CI workflow .github/workflows/lua-checks.yml, which runs exactly these two commands (./scripts/lint.sh and ./scripts/format.sh --check) inside the Nix dev shell. A PR only turns green when both checks pass, so the same commands used locally are what CI enforces.