Zookeeper tutorial

In this ZooKeeper tutorial we will learn how to download, install and move our first steps with Zookeeper distributed coordination system.

ZooKeeper is implemented in Java and requires Java 6 or later versions to run. While Oracle’s version of Java is recommended, OpenJDK should also work fine for the correct functioning of ZooKeeper

Oracle’s version of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html.

Zookeeper releases may be downloaded from Apache mirrors: Download (http://www.apache.org/dyn/closer.cgi/zookeeper/)

Once we have downloaded the ZooKeeper tarball, installing and setting up a standalone ZooKeeper node is pretty simple and straightforward. Let’s extract the compressed tar archive:

$ tar -zxf zookeeper-3.4.6.tar.gz

The location where the ZooKeeper archive is extracted in our case, /home/user1/zookeeper-3.4.6, which can be exported as ZK_HOME as follows:

$ export ZK_HOME=/home/user1/zookeeper-3.4.6

Zookeeper basic configuration

Once we have extracted the tarball, the next thing is to configure ZooKeeper. The conf folder holds the configuration files for ZooKeeper. ZooKeeper needs a configuration file called zoo.cfg in the conf folder inside the extracted ZooKeeper folder. There is a sample configuration file that contains some of the configuration parameters for reference. Let’s create our configuration file with the following minimal parameters and save it in the conf directory:

$ more conf/zoo.cfg



The configuration parameters’ meanings are explained here:

tickTime: the basic time unit in milliseconds used by ZooKeeper. It is used to do heartbeats and the minimum session timeout will be twice the tickTime.

clientPort: the port to listen for client connections

dataDir: the location to store the in-memory database snapshots and, unless specified otherwise, the transaction log of updates to the database.

Please note that extracting the ZooKeeper archive won’t create the data directory, so if this directory doesn’t exist in the system, you will need to create it and set writable permission to it.

Starting ZooKeeper

Now, considering that Java is installed and working properly, let’s start it. All ZooKeeper administration scripts to start/stop the server and invoke the ZooKeeper command shell are shipped along with the archive in the bin folder with the following code:

$ zkServer.sh start

JMX enabled by default

Using config: /home/user1/zookeeper-3.4.6/bin/../conf/zoo.cfg

Starting zookeeper ... STARTED

Stopping Zookeeper

You can conversely use the stop command to stop Zookeeper

$ zkServer.sh stop

JMX enabled by default

Using config: /home/user1/zookeeper-3.4.6/bin/../conf/zoo.cfg

Stopping zookeeper ... STOPPED

Checking the status of ZooKeeper when it has stopped or is not running will show the following result:

$ zkServer.sh status

JMX enabled by default

Using config: /home/user1/zookeeper-3.4.6/bin/../conf/zoo.cfg

Error contacting service. It is probably not running

Using the ZooKeeper with a Java-based shell

Zookeeper includes a Java-based command-line shell, which can be used for basic management tasks. In order to use it we need simply need to run zkCli.sh contained in the ZK_HOME/bin folder passing as argument the server IP and port as follows:

${ZK_HOME}/bin/zkCli.sh –server zk_server:port

In our case, we are running our ZooKeeper server on the same machine, so the ZooKeeper server will be localhost, or the loopback address

$ zkCli.sh -server localhost:2181

As we connect to the running ZooKeeper instance, we will see the output similar to the following one in the terminal (some output is omitted):

Connecting to localhost:2181
Welcome to ZooKeeper!
JLine support is enabled

WatchedEvent state:SyncConnected type:None path:null
[zk: localhost:2181(CONNECTED) 0]

We can execute a few simple commands to get a feel of the command-line interface. Let’s start by running the ls command, which, as in Unix, is used for listing:

[zk: localhost:2181(CONNECTED) 1] ls /

Now, the ls command returned a string called zookeeper, which is a znode in the ZooKeeper terminology.

ZooKeeper allows distributed processes to coordinate with each other through a shared hierarchal namespace which is organized similarly to a standard file system. The name space consists of data registers – called znodes, in ZooKeeper parlance – and these are similar to files and directories. Unlike a typical file system, which is designed for storage, ZooKeeper data is kept in-memory, which means ZooKeeper can achieve high throughput and low latency numbers.

To begin with, let’s create a Test znode with empty data:

[zk: localhost:2181(CONNECTED) 2] create /Test ""
Created /Test

[zk: localhost:2181(CONNECTED) 3] ls /
[zookeeper, Test]

We can delete the znode created by issuing the delete command as follows:

[zk: localhost:2181(CONNECTED) 4] delete /Test

[zk: localhost:2181(CONNECTED) 5] ls /

The Zookeeper shell contains a rich set of commands. To see a listing of the commands supported by the ZooKeeper Java shell, you can run the help command in the shell prompt:

[zk: localhost:2181(CONNECTED) 0] help

ZooKeeper -server host:port cmd args

  connect host:port

  get path [watch]

  ls path [watch]

  set path data [version]

  rmr path

  delquota [-n|-b] path


  printwatches on|off

  create [-s] [-e] path data acl

  stat path [watch]


  ls2 path [watch]


  listquota path

  setAcl path acl

  getAcl path

  sync path

  redo cmdno

  addauth scheme auth

  delete path [version]

  setquota -n|-b val path

Continue with next ZooKeeper tutorial: Clustering Zookeeper