ZooKeeper-cli: the ZooKeeper command line interface

Pre-requisites

Enter into the ZooKeeper-cli

bash

# connect to the localhost with the default port:2181
bin/zkCli.sh
# connect to the remote host with timeout:3s
bin/zkCli.sh -timeout 3000 -server remoteIP:2181
# connect to the remote host with -waitforconnection option to wait for connection success before executing commands
bin/zkCli.sh -waitforconnection -timeout 3000 -server remoteIP:2181
# connect with a custom client configuration properties file
bin/zkCli.sh -client-configuration /path/to/client.properties

help

Showing helps about ZooKeeper commands

bash

[zkshell: 1] help
# a sample one
[zkshell: 2] h
ZooKeeper -server host:port cmd args
	addauth scheme auth
	close
	config [-c] [-w] [-s]
	connect host:port
	create [-s] [-e] [-c] [-t ttl] path [data] [acl]
	delete [-v version] path
	deleteall path
	delquota [-n|-b|-N|-B] path
	get [-s] [-w] path
	getAcl [-s] path
	getAllChildrenNumber path
	getEphemerals path
	history
	listquota path
	ls [-s] [-w] [-R] path
	printwatches on|off
	quit
	reconfig [-s] [-v version] [[-file path] | [-members serverID=host:port1:port2;port3[,...]*]] | [-add serverId=host:port1:port2;port3[,...]]* [-remove serverId[,...]*]
	redo cmdno
	removewatches path [-c|-d|-a] [-l]
	set [-s] [-v version] path data
	setAcl [-s] [-v version] [-R] path acl
	setquota -n|-b|-N|-B val path
	stat [-w] path
	sync path
	version

addauth

Add a authorized user for ACL

bash

[zkshell: 9] getAcl /acl_digest_test
    Insufficient permission : /acl_digest_test
[zkshell: 10] addauth digest user1:12345
[zkshell: 11] getAcl /acl_digest_test
    'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE=
    : cdrwa
# add a super user
# Notice:set zookeeper.DigestAuthenticationProvider
# e.g. zookeeper.DigestAuthenticationProvider.superDigest=zookeeper:qW/HnTfCSoQpB5G8LgkwT3IbiFc=
[zkshell: 12] addauth digest zookeeper:admin

close

Close this client/session.

bash

[zkshell: 0] close
	2019-03-09 06:42:22,178 [myid:] - INFO  [main-EventThread:ClientCnxn$EventThread@528] - EventThread shut down for session: 0x10007ab7c550006
	2019-03-09 06:42:22,179 [myid:] - INFO  [main:ZooKeeper@1346] - Session: 0x10007ab7c550006 closed

config

Showing the config of quorum membership

bash

[zkshell: 17] config
	server.1=[2001:db8:1:0:0:242:ac11:2]:2888:3888:participant
	server.2=[2001:db8:1:0:0:242:ac11:2]:12888:13888:participant
	server.3=[2001:db8:1:0:0:242:ac11:2]:22888:23888:participant
	version=0

connect

Connect a ZooKeeper server.

bash

[zkshell: 4] connect
	2019-03-09 06:43:33,179 [myid:localhost:2181] - INFO  [main-SendThread(localhost:2181):ClientCnxn$SendThread@986] - Socket connection established, initiating session, client: /127.0.0.1:35144, server: localhost/127.0.0.1:2181
	2019-03-09 06:43:33,189 [myid:localhost:2181] - INFO  [main-SendThread(localhost:2181):ClientCnxn$SendThread@1421] - Session establishment complete on server localhost/127.0.0.1:2181, sessionid = 0x10007ab7c550007, negotiated timeout = 30000
	connect "localhost:2181,localhost:2182,localhost:2183"

# connect a remote server
[zkshell: 5] connect remoteIP:2181

create

Create a znode.

bash

# create a persistent_node
[zkshell: 7] create /persistent_node
	Created /persistent_node

# create a ephemeral node
[zkshell: 8] create -e /ephemeral_node mydata
	Created /ephemeral_node

# create the persistent-sequential node
[zkshell: 9] create -s /persistent_sequential_node mydata
	Created /persistent_sequential_node0000000176

# create the ephemeral-sequential_node
[zkshell: 10] create -s -e /ephemeral_sequential_node mydata
	Created /ephemeral_sequential_node0000000174

# create a node with the schema
[zkshell: 11] create /zk-node-create-schema mydata digest:user1:+owfoSBn/am19roBPzR1/MfCblE=:crwad
	Created /zk-node-create-schema
[zkshell: 12] addauth digest user1:12345
[zkshell: 13] getAcl /zk-node-create-schema
	'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE=
	: cdrwa

# create the container node.When the last child of a container is deleted,the container becomes to be deleted
[zkshell: 14] create -c /container_node mydata
	Created /container_node
[zkshell: 15] create -c /container_node/child_1 mydata
	Created /container_node/child_1
[zkshell: 16] create -c /container_node/child_2 mydata
	Created /container_node/child_2
[zkshell: 17] delete /container_node/child_1
[zkshell: 18] delete /container_node/child_2
[zkshell: 19] get /container_node
	org.apache.zookeeper.KeeperException$NoNodeException: KeeperErrorCode = NoNode for /container_node

# create the ttl node.
# set zookeeper.extendedTypesEnabled=true
# Otherwise:KeeperErrorCode = Unimplemented for /ttl_node
[zkshell: 20] create -t 3000 /ttl_node mydata
	Created /ttl_node
# after 3s later
[zkshell: 21] get /ttl_node
	org.apache.zookeeper.KeeperException$NoNodeException: KeeperErrorCode = NoNode for /ttl_node

delete

Delete a node with a specific path

bash

[zkshell: 2] delete /config/topics/test
[zkshell: 3] ls /config/topics/test
	Node does not exist: /config/topics/test

deleteall

Delete all nodes under a specific path

bash

zkshell: 1] ls /config
	[changes, clients, topics]
[zkshell: 2] deleteall /config
[zkshell: 3] ls /config
	Node does not exist: /config

delquota

Delete the quota under a path

bash

[zkshell: 1] delquota /quota_test
[zkshell: 2] listquota /quota_test
	absolute path is /zookeeper/quota/quota_test/zookeeper_limits
	quota for /quota_test does not exist.
[zkshell: 3] delquota -n /c1
[zkshell: 4] delquota -N /c2
[zkshell: 5] delquota -b /c3
[zkshell: 6] delquota -B /c4

get

Get the data of the specific path

bash

[zkshell: 10] get /latest_producer_id_block
	{"version":1,"broker":0,"block_start":"0","block_end":"999"}

# -s to show the stat
[zkshell: 11] get -s /latest_producer_id_block
	{"version":1,"broker":0,"block_start":"0","block_end":"999"}
	cZxid = 0x90000009a
	ctime = Sat Jul 28 08:14:09 UTC 2018
	mZxid = 0x9000000a2
	mtime = Sat Jul 28 08:14:12 UTC 2018
	pZxid = 0x90000009a
	cversion = 0
	dataVersion = 1
	aclVersion = 0
	ephemeralOwner = 0x0
	dataLength = 60
	numChildren = 0

# -w to set a watch on the data change, Notice: turn on the printwatches
[zkshell: 12] get -w /latest_producer_id_block
	{"version":1,"broker":0,"block_start":"0","block_end":"999"}
[zkshell: 13] set /latest_producer_id_block mydata
	WATCHER::
	WatchedEvent state:SyncConnected type:NodeDataChanged path:/latest_producer_id_block

getAcl

Get the ACL permission of one path

bash

[zkshell: 4] create /acl_test mydata ip:127.0.0.1:crwda
	Created /acl_test
[zkshell: 5] getAcl /acl_test
	'ip,'127.0.0.1
	: cdrwa
	[zkshell: 6] getAcl /testwatch
	'world,'anyone
	: cdrwa

getAllChildrenNumber

Get all numbers of children nodes under a specific path

bash

[zkshell: 1] getAllChildrenNumber /
	73779
[zkshell: 2] getAllChildrenNumber /ZooKeeper
	2
[zkshell: 3] getAllChildrenNumber /ZooKeeper/quota
	0

getEphemerals

Get all the ephemeral nodes created by this session

bash

[zkshell: 1] create -e /test-get-ephemerals "ephemeral node"
	Created /test-get-ephemerals
[zkshell: 2] getEphemerals
	[/test-get-ephemerals]
[zkshell: 3] getEphemerals /
	[/test-get-ephemerals]
[zkshell: 4] create -e /test-get-ephemerals-1 "ephemeral node"
	Created /test-get-ephemerals-1
[zkshell: 5] getEphemerals /test-get-ephemerals
	test-get-ephemerals     test-get-ephemerals-1
[zkshell: 6] getEphemerals /test-get-ephemerals
	[/test-get-ephemerals-1, /test-get-ephemerals]
[zkshell: 7] getEphemerals /test-get-ephemerals-1
	[/test-get-ephemerals-1]

history

Showing the history about the recent 11 commands that you have executed

bash

[zkshell: 7] history
	0 - close
	1 - close
	2 - ls /
	3 - ls /
	4 - connect
	5 - ls /
	6 - ll
	7 - history

listquota

Listing the quota of one path

bash

[zkshell: 1] listquota /c1
             absolute path is /zookeeper/quota/c1/zookeeper_limits
             Output quota for /c1 count=-1,bytes=-1=;byteHardLimit=-1;countHardLimit=2
             Output stat for /c1 count=4,bytes=0

ls

Listing the child nodes of one path

bash

[zkshell: 36] ls /quota_test
	[child_1, child_2, child_3]

# -s to show the stat
[zkshell: 37] ls -s /quota_test
	[child_1, child_2, child_3]
	cZxid = 0x110000002d
	ctime = Thu Mar 07 11:19:07 UTC 2019
	mZxid = 0x110000002d
	mtime = Thu Mar 07 11:19:07 UTC 2019
	pZxid = 0x1100000033
	cversion = 3
	dataVersion = 0
	aclVersion = 0
	ephemeralOwner = 0x0
	dataLength = 0
	numChildren = 3

# -R to show the child nodes recursely
[zkshell: 38] ls -R /quota_test
	/quota_test
	/quota_test/child_1
	/quota_test/child_2
	/quota_test/child_3

# -w to set a watch on the child change,Notice: turn on the printwatches
[zkshell: 39] ls -w /brokers
	[ids, seqid, topics]
[zkshell: 40] delete /brokers/ids
	WATCHER::
	WatchedEvent state:SyncConnected type:NodeChildrenChanged path:/brokers

printwatches

A switch to turn on/off whether printing watches or not.

bash

[zkshell: 0] printwatches
	printwatches is on
[zkshell: 1] printwatches off
[zkshell: 2] printwatches
	printwatches is off
[zkshell: 3] printwatches on
[zkshell: 4] printwatches
	printwatches is on

quit

Quit the CLI windows.

bash

[zkshell: 1] quit

reconfig

Change the membership of the ensemble during the runtime.

Before using this cli,read the details in the Dynamic Reconfiguration about the reconfig feature,especially the "Security" part.

Pre-requisites:

set reconfigEnabled=true in the zoo.cfg
add a super user or skipAcl,otherwise will get “Insufficient permission”. e.g. addauth digest zookeeper:admin

bash

# Change follower 2 to an observer and change its port from 2182 to 12182
# Add observer 5 to the ensemble
# Remove Observer 4 from the ensemble
[zkshell: 1] reconfig --add 2=localhost:2781:2786:observer;12182 --add 5=localhost:2781:2786:observer;2185 -remove 4
	Committed new configuration:
	server.1=localhost:2780:2785:participant;0.0.0.0:2181
	server.2=localhost:2781:2786:observer;0.0.0.0:12182
	server.3=localhost:2782:2787:participant;0.0.0.0:2183
	server.5=localhost:2784:2789:observer;0.0.0.0:2185
	version=1c00000002

# -members to appoint the membership
[zkshell: 2] reconfig -members server.1=localhost:2780:2785:participant;0.0.0.0:2181,server.2=localhost:2781:2786:observer;0.0.0.0:12182,server.3=localhost:2782:2787:participant;0.0.0.0:12183
	Committed new configuration:
	server.1=localhost:2780:2785:participant;0.0.0.0:2181
	server.2=localhost:2781:2786:observer;0.0.0.0:12182
	server.3=localhost:2782:2787:participant;0.0.0.0:12183
	version=f9fe0000000c

# Change the current config to the one in the myNewConfig.txt
# But only if current config version is 2100000010
[zkshell: 3] reconfig -file /data/software/zookeeper/zookeeper-test/conf/myNewConfig.txt -v 2100000010
	Committed new configuration:
	server.1=localhost:2780:2785:participant;0.0.0.0:2181
	server.2=localhost:2781:2786:observer;0.0.0.0:12182
	server.3=localhost:2782:2787:participant;0.0.0.0:2183
	server.5=localhost:2784:2789:observer;0.0.0.0:2185
	version=220000000c

redo

Redo the cmd with the index from history.

bash

[zkshell: 4] history
	0 - ls /
	1 - get /consumers
	2 - get /hbase
	3 - ls  /hbase
	4 - history
[zkshell: 5] redo 3
	[backup-masters, draining, flush-table-proc, hbaseid, master-maintenance, meta-region-server, namespace, online-snapshot, replication, rs, running, splitWAL, switch, table, table-lock]

removewatches

Remove the watches under a node.

bash

[zkshell: 1] get -w /brokers
	null
[zkshell: 2] removewatches /brokers
	WATCHER::
	WatchedEvent state:SyncConnected type:DataWatchRemoved path:/brokers

set

Set/update the data on a path.

bash

[zkshell: 50] set /brokers myNewData

# -s to show the stat of this node.
[zkshell: 51] set -s /quota_test mydata_for_quota_test
	cZxid = 0x110000002d
	ctime = Thu Mar 07 11:19:07 UTC 2019
	mZxid = 0x1100000038
	mtime = Thu Mar 07 11:42:41 UTC 2019
	pZxid = 0x1100000033
	cversion = 3
	dataVersion = 2
	aclVersion = 0
	ephemeralOwner = 0x0
	dataLength = 21
	numChildren = 3

# -v to set the data with CAS,the version can be found from dataVersion using stat.
[zkshell: 52] set -v 0 /brokers myNewData
[zkshell: 53] set -v 0 /brokers myNewData
	version No is not valid : /brokers

setAcl

Set the Acl permission for one node.

bash

[zkshell: 28] addauth digest user1:12345
[zkshell: 30] setAcl /acl_auth_test auth:user1:12345:crwad
[zkshell: 31] getAcl /acl_auth_test
	'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE=
	: cdrwa

# -R to set Acl recursely
[zkshell: 32] ls /acl_auth_test
	[child_1, child_2]
[zkshell: 33] getAcl /acl_auth_test/child_2
	'world,'anyone
	: cdrwa
[zkshell: 34] setAcl -R /acl_auth_test auth:user1:12345:crwad
[zkshell: 35] getAcl /acl_auth_test/child_2
	'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE=
	: cdrwa

# -v set Acl with the acl version which can be found from the aclVersion using the stat
[zkshell: 36] stat /acl_auth_test
	cZxid = 0xf9fc0000001c
	ctime = Tue Mar 26 16:50:58 CST 2019
	mZxid = 0xf9fc0000001c
	mtime = Tue Mar 26 16:50:58 CST 2019
	pZxid = 0xf9fc0000001f
	cversion = 2
	dataVersion = 0
	aclVersion = 3
	ephemeralOwner = 0x0
	dataLength = 0
	numChildren = 2
[zkshell: 37] setAcl -v 3 /acl_auth_test auth:user1:12345:crwad

setquota

Set the quota in one path.

bash

# -n to limit the number of child nodes(included itself)
[zkshell: 18] setquota -n 2 /quota_test
[zkshell: 19] create /quota_test/child_1
	Created /quota_test/child_1
[zkshell: 20] create /quota_test/child_2
	Created /quota_test/child_2
[zkshell: 21] create /quota_test/child_3
	Created /quota_test/child_3
# Notice:don't have a hard constraint,just log the warning info
	2019-03-07 11:22:36,680 [myid:1] - WARN  [SyncThread:0:DataTree@374] - Quota exceeded: /quota_test count=3 limit=2
	2019-03-07 11:22:41,861 [myid:1] - WARN  [SyncThread:0:DataTree@374] - Quota exceeded: /quota_test count=4 limit=2

# -b to limit the bytes(data length) of one path
[zkshell: 22] setquota -b 5 /brokers
[zkshell: 23] set /brokers "I_love_zookeeper"
# Notice:don't have a hard constraint,just log the warning info
	WARN  [CommitProcWorkThread-7:DataTree@379] - Quota exceeded: /brokers bytes=4206 limit=5

# -N count Hard quota
[zkshell: 3] create /c1
Created /c1
[zkshell: 4] setquota -N 2 /c1
[zkshell: 5] listquota /c1
absolute path is /zookeeper/quota/c1/zookeeper_limits
Output quota for /c1 count=-1,bytes=-1=;byteHardLimit=-1;countHardLimit=2
Output stat for /c1 count=2,bytes=0
[zkshell: 6] create /c1/ch-3
Count Quota has exceeded : /c1/ch-3

# -B byte Hard quota
[zkshell: 3] create /c2
[zkshell: 4] setquota -B 4 /c2
[zkshell: 5] set /c2 "foo"
[zkshell: 6] set /c2 "foo-bar"
Bytes Quota has exceeded : /c2
[zkshell: 7] get /c2
foo

stat

Showing the stat/metadata of one node.

bash

[zkshell: 1] stat /hbase
	cZxid = 0x4000013d9
	ctime = Wed Jun 27 20:13:07 CST 2018
	mZxid = 0x4000013d9
	mtime = Wed Jun 27 20:13:07 CST 2018
	pZxid = 0x500000001
	cversion = 17
	dataVersion = 0
	aclVersion = 0
	ephemeralOwner = 0x0
	dataLength = 0
	numChildren = 15

sync

Sync the data of one node between leader and followers(Asynchronous sync)

bash

[zkshell: 14] sync /
[zkshell: 15] Sync is OK

version

Show the version of the ZooKeeper client/CLI

bash

[zkshell: 1] version
ZooKeeper CLI version: 3.6.0-SNAPSHOT-29f9b2c1c0e832081f94d59a6b88709c5f1bb3ca, built on 05/30/2019 09:26 GMT

whoami

Gives all authentication information added into the current session.

[zkshell: 1] whoami
Auth scheme: User
ip: 127.0.0.1
[zkshell: 2] addauth digest user1:12345
[zkshell: 3] whoami
Auth scheme: User
ip: 127.0.0.1
digest: user1