Welcome¶
ZooNavigator is a web-based ZooKeeper UI and editor/browser with many features.
It is an open source project and the source code is available on GitHub.
If you like this project, please, consider supporting me by buying me a beer, thanks! 🍺❤️
 |
 |
 |
 |
 |
 |
Quick Start¶
You can run ZooNavigator from:
Docker¶
Start Docker container with ZooNavigator Docker image:
docker run \
-d \
-p 9000:9000 \
-e HTTP_PORT=9000 \
--name zoonavigator \
--restart unless-stopped \
elkozmon/zoonavigator:latest
Go to http://localhost:9000.
Note:
If wanting to access ZooKeeper running locally on host machine (not in Docker container):
- Linux users may use
--net hostinstead of exposing the port - Windows and Mac users should follow this advice
Snap¶
Install ZooNavigator from Snap store:
sudo snap install zoonavigator
Go to http://localhost:9000.
Features¶
The main goal of this project is to provide a way to efficiently manage ZNodes.
This is a brief summary of what you get:
- Manage multiple ZooKeeper clusters at once
- Advanced ZNode operations
- move, copy & paste
- export & import
- mass delete
- regex search tool (currently limited to children nodes)
- Smart ZNode data editor
- data validation, syntax highlighting and auto-formatting
- edit binary data in base64 mode
- edit compressed data (gzip)
- Auth & security
- SASL and Auth scheme ZooKeeper authentication
- ZNode ACL management (supports recursive changes)
Compatibility¶
ZooKeeper versions 3.4.x and 3.5.x are currently supported.
Docker¶
ZooNavigator is available at Docker image.
The following pages explain how to configure your Docker deployment.
Configuration¶
ZooNavigator’s Docker image can be configured using environment variables.
Configuration options could be split into three groups:
- ZooNavigator - configures ZooNavigator and the web server
- ZooKeeper client - configuration related to ZooKeeper
- Java - configures the Java Virtual Machine
ZooKeeper client¶
ZK_CLIENT_TIMEOUT_MILLIS¶
default: 5000
Sets inactivity timeout for ZooKeeper client. If user doesn’t make any request during this period ZooKeeper connection will be closed and recreated for the future request if any. This value is in milliseconds.
Note
on client timeout user does not get logged out unlike in event of session timeout
ZK_CONNECT_TIMEOUT_MILLIS¶
default: 5000
Sets timeout for attempt to establish connection with ZooKeeper. This value is in milliseconds.
ZK_SASL_CLIENT_USERNAME¶
default: zookeeper
Specifies the primary part of the server principal. Learn more here.
ZK_CLIENT_SECURE¶
If you want to connect to the server secure client port, you need to set this property to true.
This will connect to server using SSL with specified credentials.
ZK_SSL_KEYSTORE_PATH¶
Specifies the file path to a JKS containing the local credentials to be used for SSL connections.
ZK_SSL_KEYSTORE_PASSWORD¶
Specifies the password to a JKS containing the local credentials to be used for SSL connections.
ZK_SSL_TRUSTSTORE_PATH¶
Specifies the file path to a JKS containing the remote credentials to be used for SSL connections.
ZK_SSL_TRUSTSTORE_PASSWORD¶
Specifies the password to a JKS containing the remote credentials to be used for SSL connections.
Java¶
JAVA_OPTS¶
Custom Java arguments.
JAVA_XMS¶
Sets initial Java heap size. This value is in bytes if no unit is specified.
JAVA_XMX¶
Sets maximum Java heap size. This value is in bytes if no unit is specified.
JAVA_JAAS_LOGIN_CONFIG¶
Path to JAAS login configuration file to use.
JAVA_KRB5_DEBUG¶
If set to true, enables debugging mode and detailed logging for Kerberos.
JAVA_KRB5_REALM¶
Sets the default Kerberos realm.
JAVA_KRB5_KDC¶
Sets the default Kerberos KDC.
Preset Connections¶
Instead of manually entering connection string every time you open ZooNavigator, you can preset your ZooKeeper clusters when starting the Docker image and then select which cluster to connect to from the drop-down in the Connect form.
Adding a Preset Connection¶
Each connection must have a unique id, which is part of the environment variable name.
To add a preset connection, you must enter a valid connection string as CONNECTION_<ID>_CONN environment variable.
Optionally, you can add a name to your preset connection using environment variable CONNECTION_<ID>_NAME which will be displayed in the UI instead of the id.
Note
Replace <ID> by any id string you choose. Keep in mind that environment variable name should consist only of uppercase letters, digits and underscores.
For example, if one wants to add a ZooKeeper cluster running at localhost:2181, name it “Local ZooKeeper” and give it id LOCALZK, then he/she would set the environment variables like so:
CONNECTION_LOCALZK_NAME= Local ZooKeeperCONNECTION_LOCALZK_CONN= localhost:2181
Adding auth entry to a Preset Connection¶
Similarly, one can add auth entry to any Preset Connection.
Each auth entry also has to have a unique id (unique constraint only applies for auth entries for the same connection). To add auth entry you need to set these environment variables:
CONNECTION_<ID>_AUTH_<AUTHID>_SCHEMECONNECTION_<ID>_AUTH_<AUTHID>_ID
Auto Connect¶
Auto connect is a feature that lets you skip the Connect form where you enter ZooKeeper server address and throws you directly into the Editor UI. This is useful when you only have a single (or preferred) ZooKeeper cluster.
To enable this feature, first add the ZooKeeper cluster you want to use as a Preset Connection to ZooNavigator.
Then simply set the AUTO_CONNECT_CONNECTION_ID environment variable to the id of that preset connection.
For example, if you added your ZooKeeper cluster using CONNECTION_MYZK_CONN environment variable, then you would set AUTO_CONNECT_CONNECTION_ID to MYZK.
That’s it. When you open up ZooNavigator, it will automatically connect to your ZooKeeper cluster.
Custom build¶
If you want to build ZooNavigator Docker image yourself, you can do so like this:
git clone https://github.com/elkozmon/zoonavigator.git
cd zoonavigator
git submodule update --init --recursive
docker build \
-t my-zoonavigator \
-f build/docker/Dockerfile \
--build-arg APP_VERSION=my-build \
.
Note
Note that the docker build command is executed from within project’s root directory
Snap¶
ZooNavigator is available at Snap store.
The following pages explain how to manage ZooNavigator Snap.
Configuration¶
ZooNavigator exposes Snap configuration options that could be split into three groups:
- ZooNavigator - configures ZooNavigator and the web server
- ZooKeeper client - configuration related to ZooKeeper
- Java - configures the Java Virtual Machine
ZooKeeper client¶
zookeeper.client.max-age¶
default: 5000
Sets inactivity timeout for ZooKeeper client. If user doesn’t make any request during this period ZooKeeper connection will be closed and recreated for the future request if any. This value is in milliseconds.
Note
on client timeout user does not get logged out unlike in event of session timeout
zookeeper.client.connect-timeout¶
default: 5000
Sets timeout for attempt to establish connection with ZooKeeper. This value is in milliseconds.
zookeeper.sasl.client.username¶
default: zookeeper
Specifies the primary part of the server principal. Learn more here.
zookeeper.server.realm¶
Realm part of the server principal.
By default it is the client principal realm.
zookeeper.client.secure¶
If you want to connect to the server secure client port, you need to set this property to true.
This will connect to server using SSL with specified credentials.
zookeeper.ssl.key-store.location¶
Specifies the file path to a JKS containing the local credentials to be used for SSL connections.
zookeeper.ssl.key-store.password¶
Specifies the password to a JKS containing the local credentials to be used for SSL connections.
zookeeper.ssl.trust-store.location¶
Specifies the file path to a JKS containing the remote credentials to be used for SSL connections.
zookeeper.ssl.trust-store.password¶
Specifies the password to a JKS containing the remote credentials to be used for SSL connections.
Java¶
java.xmx¶
Sets initial Java heap size. This value is in bytes if no unit is specified.
java.xms¶
Sets maximum Java heap size. This value is in bytes if no unit is specified.
java.security.auth.login.config¶
Path to JAAS login configuration file to use.
java.security.krb5.debug¶
If set to true, enables debugging mode and detailed logging for Kerberos.
java.security.krb5.realm¶
Sets the default Kerberos realm.
java.security.krb5.kdc¶
Sets the default Kerberos KDC.
Preset Connections¶
Instead of manually entering connection string every time you open ZooNavigator, you can preset your ZooKeeper clusters when starting the Docker image and then select which cluster to connect to from the drop-down in the Connect form.
Adding a Preset Connection¶
Each connection must have a unique id, which is part of the configuration option name.
To add a preset connection, you must enter a valid connection string as zoonavigator.connection.<id>.connection-string configuration option.
Optionally, you can add a name to your preset connection using configuration option zoonavigator.connection.<id>.name which will be displayed in the UI instead of the id.
Note
Replace <id> by any id string you choose.
For example, if one wants to add a ZooKeeper cluster running at localhost:2181, name it “Local ZooKeeper” and give it id localzk, then he/she would set the configuration options like so:
snap set zoonavigator zoonavigator.connection.localzk.name=Local ZooKeeper
snap set zoonavigator zoonavigator.connection.localzk.connection-string=localhost:2181
Adding auth entry to a Preset Connection¶
Similarly, one can add auth entry to any Preset Connection.
Each auth entry also has to have a unique id (unique constraint only applies for auth entries for the same connection). To add auth entry you need to set these configuration option:
zoonavigator.connection.<connectionId>.auth.<authId>.schemezoonavigator.connection.<connectionId>.auth.<authId>.id
Auto Connect¶
Auto connect is a feature that lets you skip the Connect form where you enter ZooKeeper server address and throws you directly into the Editor UI. This is useful when you only have a single (or preferred) ZooKeeper cluster.
To enable this feature, first add the ZooKeeper cluster you want to use as a Preset Connection to ZooNavigator.
Then simply set the zoonavigator.auto-connect.connection-id configuration option to the id of that preset connection.
For example, if you added your ZooKeeper cluster using zoonavigator.connection.myzk.connection-string configuration option, then you would set zoonavigator.auto-connect.connection-id to myzk like so:
snap set zoonavigator zoonavigator.auto-connect.connection-id=myzk
That’s it. When you open up ZooNavigator, it will automatically connect to your ZooKeeper cluster.
Development Guide¶
Development setup requires NPM and SBT to be installed on your machine.
ZooNavigator API handles communication with ZooKeeper while ZooNavigator Web is the front-end which in turn talks to the ZooNavigator API.
First, let’s get ZooNavigator API running:
git clone https://github.com/elkozmon/zoonavigator-api.git
cd zoonavigator-api
sbt play/run
Play HTTP server should now be listening on port 9000. The default port is defined in play/conf/application.conf.
Next step is to start up ZooNavigator Web:
git clone https://github.com/elkozmon/zoonavigator-web.git
cd zoonavigator-web
npm install -g @angular/cli
npm install
npm run dev
This starts up Angular development server with proxy configured in proxy.conf.json that will forward API requests to http://localhost:9000 where ZooNavigator API should be running.
Once you’ve done all that open up http://localhost:4200 in your browser and you should see the Connect form.
Frequently Asked Questions¶
What should I fill in for Auth username and Auth password?¶
Auth username and password are optional, so feel free to leave those empty. Every username & password pair entered (you can enter many) serves as an extra ACL identity, so ZNodes can be given some permissions only for users logged in with certain credentials.
How to enable Basic Authentication?¶
At the moment there is no configuration option to enable Basic Auth out-of-the-box.
I suggest placing a proxy which supports Basic Auth in front of ZooNavigator. For example Traefik.
I’m getting error that says “Unable to establish connection with ZooKeeper.”¶
ZooNavigator cannot find ZooKeeper host(s) using the connection string you entered in the connect form.
Windows and Mac users using ZooNavigator in Docker: If you’re trying to access ZooKeeper running locally on host machine (not in Docker container), follow this advice.
Change Log¶
1.1.1¶
October 28, 2021
Changes:
- Use custom Authorization header to allow auth in proxies
Fixes:
- Correctly handle HEAD HTTP requests
1.0.0¶
May 16, 2020
Adds capability to manage multiple ZooKeeper clusters at once for larger deployments
Changes:
- Add support for preset ZooKeeper connections
- Switch between ZooKeeper clusters in Editor UI
- Change Auto connect Docker configuration
- Remove Session info dialog
- Show build version on Connect page
0.8.0¶
February 15, 2020
Changes:
- Gzip exports (json imports are still supported)
- Enable Docker image to run under arbitrary user
- When using node filter, show non-matching nodes as semi-transparent
- Clear node filter when navigating to other node
PUT /api/znode/dataAPI endpoint acceptsapplication/jsoninstead oftext/plain- Add Donation link
Fixes:
- Fix SSL support for ZooKeeper 3.5.x
- Fix false warnings about discarding changes
0.7.1¶
November 08, 2019
Minor bug fixes.
Changes:
- Increase default ZNode import size limit to 10mb
Fixes:
- Fix
BASE_HREFDocker build argument - Fix app freezing after session expired
- Fix Docker healthcheck when
HTTP_PORTis set todisabled
0.7.0¶
September 18, 2019
Release ZooNavigator as a single Docker image.
Changes:
- Single Docker image release
- Increase default session timeout to 1 hour
Fixes:
- Fix save button keyboard shortcut in editor
0.6.2¶
June 20, 2019
Allows to run ZooNavigator API’s Docker image as an unprivileged user.
Changes:
- Docker container set to run under user zoonavigator-api
0.6.1¶
April 13, 2019
Allows to run ZooNavigator Web’s Docker image as an unprivileged user.
Changes:
- Switched from official Nginx Docker image to Nginxinc
0.6.0¶
January 24, 2019
Implements several feature requests and fixes minor bugs.
Features:
- Export & import ZNode trees
- Read & write gzip compressed ZNode data
- Base64 editor mode for editing binary data
- Custom URLs using added
BASE_HREFDockerfile build argument
Changes:
- Turned off access logs on Dockers healthchecks
0.5.1¶
November 01, 2018
Decreases Dockers health-check interval so it doesn’t cause startup delays in tools like Docker Swarm.
Changes:
- Decreases Dockers health-check interval to 30 seconds
0.5.0¶
May 29, 2018
Adds support for SASL authentication with ZooKeeper and HTTPS.
Features:
- SASL authentication with ZooKeeper
- HTTPS support
Changes:
- Changed editors font to Fira Code
- Base Docker images on Alpine
- Enable applying ACLs recursively without making any changes
Fixes:
- Prevent submitting editor via keyboard shortcut when save button is disabled
0.4.0¶
April 02, 2018
Adds auto-format feature and fixes some minor bugs.
Features:
- Auto-format feature in editor
- Remember editor options (wrap, mode) for each ZNode
- Log ZooNavigator version on Docker startup
Changes:
- Editor buttons got minor polishing
- Changed editors font to DejaVu Sans Mono
Fixes:
- Switching editor tabs between changes (to data or acl) causes ‘Bad version’ error
- When session expires two ‘Session lost’ dialogs spawn at once
0.3.0¶
January 11, 2018
Adds many new ZNode editor features.
Features:
- Move ZNode feature
- Duplicate ZNode feature
- Children ZNode list sorting
- Data editor text wrapping
- Address bar for manual navigation
- Auto connect feature - skip connect form and use preconfigured connection parameters
- Hotkey for submitting ZNode data changes (ctrl+s)
- JVM memory settings via environment variables (API Docker image)
Changes:
- UI changes, redesigned editor tabs