ZooKeeper is commonly used as a distributed key-value store. A lot of systems use it for storing configuration, doing service discovery, or for doing distributed locking.

This page aims to document the network protocol used by Zookeeper clients to talk to Zookeeper nodes.


Service Protocol Port
Zookeeper TCP 2181
ClickHouse Keeper TCP 9181

Protocol notes

When the client connects, it learns a session ID, which seems to be incremented by 1 for each new connection. So the server must be keeping track of the last session ID it gave out.

Integers are big-endian.

Message types

Opcode Name Description
N/A Handshake To establish a connection
1 Create Create a node


On connecting to a Zookeeper node, the client sends a handshake request packet. In return, the server responds with a handshake response packet.

These handshake packets are slightly different from all the other packets in that they do not contain the xid and packet type fields.

Client -> Server

Length Name Description
4 Length Length of the remaining packet
4 Protocol version Protocol version number, always 0
4 Last seen zxid Last seen zxid

blah blah blah

Server -> Client

blah blah blah

Some useful resources

  • https://clickhouse.com/codebrowser/ClickHouse/src/Common/ZooKeeper/ZooKeeperConstants.h.html
  • https://clickhouse.com/codebrowser/ClickHouse/src/Common/ZooKeeper/ZooKeeperCommon.cpp.html#277
  • https://zookeeper.apache.org/doc/r3.9.1/zookeeperProgrammers.html
  • https://zookeeper.apache.org/doc/r3.9.1/recipes.html