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¶

Start Docker container with ZooNavigator Docker image:

docker run \
  -d --network host \
  -e HTTP_PORT=9000 \
  --name zoonavigator \
  --restart unless-stopped \
  elkozmon/zoonavigator:latest

Go to http://localhost:9000.

Windows and Mac users: If wanting to access ZooKeeper running locally on host machine (not in Docker container), follow this advice.

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 ships as a 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:

Application - configures the application and a web server
Java - configures the Java Virtual Machine
ZooKeeper client - configuration related to ZooKeeper

Application¶

HTTP_PORT¶

default: 9000

Tells the HTTP server which port to bind to. To disable HTTP set this variable to disabled.

HTTPS_PORT¶

If set, HTTPS server will bind to this port.

SSL_KEYSTORE_PATH¶

The path to the keystore containing the private key and certificate, if not provided generates a keystore for you.

SSL_KEYSTORE_PASSWORD¶

The password to the keystore, defaults to a blank password.

SSL_KEYSTORE_TYPE¶

default: JKS

The key store type.

SECRET_KEY¶

Secret key for Play Framework - used for signing session cookies and CSRF tokens. Defaults to 64 random characters generated from /dev/urandom.

CONNECTION_<MYZK>_NAME¶

Optional name for preset ZooKeeper connection ‘<MYZK>’

Note

environment variable name should consist only of uppercase letters, digits and underscores.

CONNECTION_<MYZK>_CONN¶

Connection string for preset ZooKeeper connection ‘<MYZK>’

Note

environment variable name should consist only of uppercase letters, digits and underscores.

CONNECTION_<MYZK>_AUTH_<MYAUTH>_SCHEME¶

Auth scheme for auth entry ‘<MYAUTH>’ for preset ZooKeeper connection ‘<MYZK>’

Note

environment variable name should consist only of uppercase letters, digits and underscores.

CONNECTION_<MYZK>_AUTH_<MYAUTH>_ID¶

Auth id for auth entry ‘<MYAUTH>’ for preset ZooKeeper connection ‘<MYZK>’

Note

environment variable name should consist only of uppercase letters, digits and underscores.

AUTO_CONNECT_CONNECTION_ID¶

If set, enables Auto Connect feature.

Set to MYZK to automatically connect to connection defined by CONNECTION_MYZK_CONN environment variable.

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_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.

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. Note that user does not get logged out unlike in event of session timeout. This value is in milliseconds.

ZK_CONNECT_TIMEOUT_MILLIS¶

default: 5000

Sets timeout for attempt to establish connection with ZooKeeper. This value is in milliseconds.

ZK_SASL_CLIENT¶

default: true

Set the value to false to disable SASL authentication.

ZK_SASL_CLIENT_CONFIG¶

default: Client

Specifies the context key in the JAAS login file.

ZK_SASL_CLIENT_USERNAME¶

default: zookeeper

Specifies the primary part of the server principal. Learn more here.

ZK_SERVER_REALM¶

Realm part of the server principal.

By default it is the client principal realm.

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.

Note that it requires using the Netty client.

ZK_CLIENT_CNXN_SOCKET¶

default: org.apache.zookeeper.ClientCnxnSocketNIO

Specifies which ClientCnxnSocket to be used. If you want to connect to server’s secure client port, you need to set this property to :org.apache.zookeeper.ClientCnxnSocketNetty.

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.

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 ZooKeeper
CONNECTION_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>_SCHEME
CONNECTION_<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 URL¶

By default ZooNavigator will be available on root of your domain, e.g. https://www.example.com/

If you need to deploy ZooNavigator with custom URL using a suffix like /zoonavigator, you will have to build ZooNavigator’s Docker image yourself.

There is a Docker build argument for that called BASE_HREF in ZooNavigator’s Dockerfile. You will need to clone its Git repository and from within that directory build your own Docker image like so:

git submodule init

docker build \
  -t my-zoonavigator \
  -f build/docker/Dockerfile \
  --build-arg BASE_HREF=/zoonavigator/ \
  --build-arg APP_VERSION=my-build \
  .

Note

Note that BASE_HREF has to start and end with forward slash /

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: If you’re trying to access ZooKeeper running locally on host machine (not in Docker container), follow this advice.

Change Log¶

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/data API endpoint accepts application/json instead of text/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_HREF Docker build argument
Fix app freezing after session expired
Fix Docker healthcheck when HTTP_PORT is set to disabled

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_HREF Dockerfile 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

Welcome¶

Quick Start¶

Features¶

Compatibility¶

Docker¶

Configuration¶

Application¶

HTTP_PORT¶

HTTPS_PORT¶

SSL_KEYSTORE_PATH¶

SSL_KEYSTORE_PASSWORD¶

SSL_KEYSTORE_TYPE¶

SECRET_KEY¶

CONNECTION_<MYZK>_NAME¶

CONNECTION_<MYZK>_CONN¶

CONNECTION_<MYZK>_AUTH_<MYAUTH>_SCHEME¶

CONNECTION_<MYZK>_AUTH_<MYAUTH>_ID¶

AUTO_CONNECT_CONNECTION_ID¶

Java¶

JAVA_OPTS¶

JAVA_XMS¶

JAVA_XMX¶

JAVA_JAAS_LOGIN_CONFIG¶

JAVA_KRB5_DEBUG¶

JAVA_KRB5_REALM¶

JAVA_KRB5_KDC¶

ZooKeeper client¶

ZK_CLIENT_TIMEOUT_MILLIS¶

ZK_CONNECT_TIMEOUT_MILLIS¶

ZK_SASL_CLIENT¶

ZK_SASL_CLIENT_CONFIG¶

ZK_SASL_CLIENT_USERNAME¶

ZK_SERVER_REALM¶

ZK_CLIENT_SECURE¶

ZK_CLIENT_CNXN_SOCKET¶

ZK_SSL_KEYSTORE_PATH¶

ZK_SSL_KEYSTORE_PASSWORD¶

ZK_SSL_TRUSTSTORE_PATH¶

ZK_SSL_TRUSTSTORE_PASSWORD¶

Preset Connections¶

Adding a Preset Connection¶

Adding auth entry to a Preset Connection¶

Auto Connect¶

Custom URL¶

Development Guide¶

Frequently Asked Questions¶

What should I fill in for Auth username and Auth password?¶

How to enable Basic Authentication?¶

I’m getting error that says “Unable to establish connection with ZooKeeper.”¶

Change Log¶

1.0.0¶

0.8.0¶

0.7.1¶

0.7.0¶

0.6.2¶

0.6.1¶

0.6.0¶

0.5.1¶

0.5.0¶

0.4.0¶

0.3.0¶