Apache ZooKeeper is a centralized service that facilitates configuration management, naming, distributed synchronization, and group coordination in distributed systems. It serves as a foundational component for platforms such as Apache Hadoop, HBase, and Solr, and was previously a core dependency in Apache Kafka. When managing such distributed applications, it is essential to monitor and confirm that ZooKeeper is running correctly. This article explains multiple reliable ways to check if ZooKeeper is up and running from the command prompt or terminal.
1. Prerequisites
Before checking the ZooKeeper status, ensure the following:
- Java is installed and added to your system’s
PATH. - ZooKeeper is installed (standalone or cluster mode).
- The ZooKeeper service is started, or you know the configured data and port settings (the default client port is
2181).
2. Use zkServer Script (Linux/macOS Only)
If you have installed ZooKeeper from the official tarball or a package manager on a Unix-like system (such as Linux or macOS), the zkServer.sh script is one of the simplest and most direct ways to perform a ZooKeeper status check. This script helps you start, stop, restart, and check the current status of the ZooKeeper server. It reads the configuration from the zoo.cfg file and prints whether the instance is running and in what mode (standalone or in a cluster).
Navigate to ZooKeeper’s bin directory and execute the following command to check its status.
./zkServer.sh status
Sample Output:
ZooKeeper JMX enabled by default Using config: /opt/apache-zookeeper-3.9.3/bin/../conf/zoo.cfg Client port found: 2181. Client address: localhost. Client SSL: false. Mode: standalone
This script checks the current ZooKeeper process and returns its mode. It works only in Unix-like environments and assumes that ZooKeeper is run using the provided scripts. Note: This script is unavailable on Windows.
3. Using Process Commands – ps and jps
Another effective way to check if ZooKeeper is running is by inspecting active Java processes. This works well if you have shell access and ZooKeeper is started via command line or service.
3.1 Using ps (Linux/macOS)
If you are running ZooKeeper on a Unix-based system, the ps command can help you check whether the ZooKeeper process is currently active. This command lists all running processes, and by filtering the output using grep, you can quickly determine if ZooKeeper is up and running.
ps -ef | grep zookeeper
Sample Output:
501 54067 45247 0 7:41pm ttys000 0:00.03 grep zookeeper ...org.apache.zookeeper.server.quorum.QuorumPeerMain /opt/apache-zookeeper-3.9.3/bin/../conf/zoo.cfg
The command ps -ef lists all active processes running on the system, and when combined with grep zookeeper, it filters the output to show only those related to the ZooKeeper service. If you see a Java process that includes QuorumPeerMain in its command or arguments, it indicates that the ZooKeeper server is up and running. It typically displays the process ID, the Java command, and the configuration file path, confirming that the service is active and functioning.
3.2 Using jps (Java Virtual Machine Process Status Tool)
The jps (Java Virtual Machine Process Status Tool) command is a convenient utility that comes with the JDK and is used to list all active Java processes on the system. When used in combination with grep, we can easily identify if the ZooKeeper server process, typically shown as QuorumPeerMain, is running.
jps | grep Quorum
Sample Output:
The jps command lists all currently running Java processes on the system, making it a useful tool for checking the status of Java-based services. Among the listed processes, QuorumPeerMain represents the main class of the ZooKeeper server. If this process appears in the output, it confirms that the ZooKeeper server is actively running.
4. Using 4-Letter Commands (ruok) With telnet or nc
ZooKeeper provides a simple set of 4-letter commands to check the health and status of the server. One of the commands is ruok, which checks whether the ZooKeeper server is running and responsive. When executed successfully, it returns imok, indicating the server is healthy.
We can use either telnet or nc (netcat) to send this command to the ZooKeeper server:
echo ruok | nc localhost 2181
Or, using telnet:
telnet localhost 2181
Once connected, type:
ruok
You should see the following response:
imok
This confirms that ZooKeeper is running and able to respond to basic health checks.
Command Not Executed? Enable it in the Whitelist
If you receive a response like this:
ruok is not executed because it is not in the whitelist.
It means the ruok command has not been enabled in the ZooKeeper configuration. By default, ZooKeeper restricts 4-letter commands for security reasons. To use them, you need to explicitly enable each one you plan to use.
To fix this, open your ZooKeeper configuration file, typically named zoo.cfg, located in the conf directory, and add or update the property 4lw.commands.whitelist to include ruok as one of the allowed commands.
4lw.commands.whitelist=ruok
You can include multiple commands by separating them with commas:
4lw.commands.whitelist=ruok,stat,mntr,conf
Save the file and restart ZooKeeper for the changes to take effect.
bin/zkServer.sh restart
Retry the ruok command.
echo ruok | nc localhost 2181
Now you should receive:
imok
5. Conclusion
In this article, we explored various ways to perform a ZooKeeper status check from the command prompt, including using the zkServer.sh script, 4-letter commands like ruok, process inspection with ps and jps, and networking tools such as telnet and nc. We also covered how to enable 4-letter commands through the ZooKeeper configuration by updating the whitelist. These methods offer reliable options for verifying the operational status of ZooKeeper.
This article provided a guide on how to check the status of ZooKeeper using various command-line methods.
