Skip to main content
Version: 4.17.1

BookKeeper CLI tool reference

bookkeeper command

Manages bookies.

Environment variables

Environment variableDescriptionDefault
BOOKIE_LOG_CONFThe Log4j configuration file.${bookkeeperHome}/bookkeeper-server/conf/log4j2.xml
BOOKIE_CONFThe configuration file for the bookie.${bookkeeperHome}/bookkeeper-server/conf/bk_server.conf
BOOKIE_EXTRA_CLASSPATHExtra paths to add to BookKeeper's classpath.
ENTRY_FORMATTER_CLASSThe entry formatter class used to format entries.
BOOKIE_PID_DIRThe directory where the bookie server PID file is stored.
BOOKIE_STOP_TIMEOUTThe wait time before forcefully killing the bookie server instance if stopping it is not successful.

Commands

bookie

Starts up a bookie.

Usage
$ bin/bookkeeper bookie

localbookie

Starts up an ensemble of N bookies in a single JVM process. Typically used for local experimentation and development.

Usage
$ bin/bookkeeper localbookie \ 
N

autorecovery

Runs the autorecovery service.

Usage
$ bin/bookkeeper autorecovery

upgrade

Upgrades the bookie's filesystem.

Usage
$ bin/bookkeeper upgrade \ 
<options>
FlagDescription
--upgradeUpgrade the filesystem.
--rollbackRollback the filesystem to a previous version.
--finalizeMark the upgrade as complete.

shell

Runs the bookie's shell for admin commands.

Usage
$ bin/bookkeeper shell

help

Displays the help message for the bookkeeper tool.

Usage
$ bin/bookkeeper help

BookKeeper shell

queryautorecoverystatus

Query the autorecovery status

Usage
$ bin/bookkeeper shell queryautorecoverystatus
FlagDescription
-v,--verboseList recovering detailed ledger info

autorecovery

Enable or disable autorecovery in the cluster.

Usage
$ bin/bookkeeper shell autorecovery \ 
<options>
FlagDescription
-e,--enableEnable autorecovery of underreplicated ledgers
-d,--disableDisable autorecovery of underreplicated ledgers

bookieformat

Format the current server contents.

Usage
$ bin/bookkeeper shell bookieformat \ 
<options>
FlagDescription
-n,--nonInteractiveWhether to confirm if old data exists.
-f,--forceIf [nonInteractive] is specified, then whether to force delete the old data without prompt..?
-d,--deleteCookieDelete its cookie on zookeeper

initbookie

Initialize new bookie, by making sure that the journalDir, ledgerDirs and indexDirs are empty and there is no registered Bookie with this BookieId.

If there is data present in current bookie server, the init operation will fail. If you want to format the bookie server, use bookieformat.

Usage
$ bin/bookkeeper shell initbookie

bookieinfo

Retrieve bookie info such as free and total disk space.

Usage
$ bin/bookkeeper shell bookieinfo

bookiesanity

Sanity test for local bookie. Create ledger and write/read entries on the local bookie.

Usage
$ bin/bookkeeper shell bookiesanity \ 
<options>
FlagDescription
-e,--entries NTotal entries to be added for the test (default 10)
-t,--timeout NTimeout for write/read operations in seconds (default 1)

decommissionbookie

Force trigger the Audittask and make sure all the ledgers stored in the decommissioning bookie are replicated.

Usage
$ bin/bookkeeper shell decommissionbookie

deleteledger

Delete a ledger

Usage
$ bin/bookkeeper shell deleteledger \ 
<options>
FlagDescription
-l,--ledgerid LEDGER_IDLedger ID
-f,--forceWhether to force delete the Ledger without prompt..?

endpointinfo

Get endpoints of a Bookie.

Usage
$ bin/bookkeeper shell endpointinfo

expandstorage

Add new empty ledger/index directories. Update the directories info in the conf file before running the command.

Usage
$ bin/bookkeeper shell expandstorage

help

Displays the help message.

Usage
$ bin/bookkeeper shell help

lastmark

Print last log marker.

Usage
$ bin/bookkeeper shell lastmark

ledger

Dump ledger index entries into readable format.

Usage
$ bin/bookkeeper shell ledger \ 
<options>
FlagDescription
-m,--meta LEDGER_IDPrint meta information

ledgermetadata

Print the metadata for a ledger.

Usage
$ bin/bookkeeper shell ledgermetadata \ 
<options>
FlagDescription
-l,--ledgerid LEDGER_IDLedger ID
--dump-to-file FILENAMEDump metadata for ledger, to a file
--restore-from-file FILENAMERestore metadata for ledger, from a file

listbookies

List the bookies, which are running as either readwrite or readonly mode.

Usage
$ bin/bookkeeper shell listbookies \ 
<options>
FlagDescription
-a,--allPrint all bookies
-rw,--readwritePrint readwrite bookies
-ro,--readonlyPrint readonly bookies
-h,--hostnamesAlso print hostname of the bookie

listfilesondisc

List the files in JournalDirectory/LedgerDirectories/IndexDirectories.

Usage
$ bin/bookkeeper shell listfilesondisc \ 
<options>
FlagDescription
-txn,--journalPrint list of journal files
-log,--entrylogPrint list of entryLog files
-idx,--indexPrint list of index files

listledgers

List all ledgers in the cluster (this may take a long time).

Usage
$ bin/bookkeeper shell listledgers \ 
<options>
FlagDescription
-bookieid BOOKIE_IDList ledgers residing in this bookie
-m,--metaPrint metadata

listunderreplicated

List ledgers marked as underreplicated, with optional options to specify missing replica (BookieId) and to exclude missing replica.

Usage
$ bin/bookkeeper shell listunderreplicated \ 
<options>
FlagDescription
-missingreplica BOOKIE_ADDRESSBookie Id of missing replica
-excludingmissingreplica BOOKIE_ADDRESSBookie Id of missing replica to ignore
-printmissingreplicaWhether to print missingreplicas list?
-printreplicationworkeridWhether to print replicationworkerid?
-c,--onlydisplayledgercountOnly display underreplicated ledger count

metaformat

Format Bookkeeper metadata in Zookeeper. This command is deprecated since 4.7.0, in favor of using initnewcluster for initializing a new cluster and nukeexistingcluster for nuking an existing cluster.

Usage
$ bin/bookkeeper shell metaformat \ 
<options>
FlagDescription
-n,--nonInteractiveWhether to confirm if old data exists..?
-f,--forceIf [nonInteractive] is specified, then whether to force delete the old data without prompt.

initnewcluster

Initializes a new bookkeeper cluster. If initnewcluster fails then try nuking existing cluster by running nukeexistingcluster before running initnewcluster again

Usage
$ bin/bookkeeper shell initnewcluster

nukeexistingcluster

Nuke bookkeeper cluster by deleting metadata

Usage
$ bin/bookkeeper shell nukeexistingcluster \ 
<options>
FlagDescription
-p,--zkledgersrootpath ZK_LEDGER_ROOT_PATHzookeeper ledgers rootpath
-i,--instanceid INSTANCE_IDinstance id
-f,--forceIf instanceid is not specified, then whether to force nuke the metadata without validating instanceid

lostbookierecoverydelay

Setter and Getter for LostBookieRecoveryDelay value (in seconds) in Zookeeper.

Usage
$ bin/bookkeeper shell lostbookierecoverydelay \ 
<options>
FlagDescription
-g,--getGet LostBookieRecoveryDelay value (in seconds)
-s,--set VALUESet LostBookieRecoveryDelay value (in seconds)

readjournal

Scan a journal file and format the entries into readable format.

Usage
$ bin/bookkeeper shell readjournal \ 
<options>
FlagDescription
-m,--msgPrint message body
-dir JOURNAL_ID or JOURNAL_FILE_NAMEJournal directory (needed if more than one journal configured)

readledger

Read a range of entries from a ledger.

Usage
$ bin/bookkeeper shell readledger \ 
<ledger_id> [<start_entry_id> [<end_entry_id>]]
FlagDescription
-m,--msgPrint message body
-l,--ledgerid LEDGER_IDLedger ID
-fe,--firstentryid ENTRY_IDFirst EntryID
-le,--lastentryid ENTRY_IDLast EntryID
-b,--bookie BOOKIE_IDOnly read from a specific bookie
-r,--force-recoveryEnsure the ledger is properly closed before reading

readlog

Scan an entry file and format the entries into readable format.

Usage
$ bin/bookkeeper shell readlog \ 
<entry_log_id | entry_log_file_name> \
<options>
FlagDescription
-m,--msgPrint message body
-l,--ledgerid LEDGER_IDLedger ID
-e,--entryid ENTRY_IDEntry ID
-sp,--startpos START_ENTRY_LOG_BYTE_POSStart Position
-ep,--endpos END_ENTRY_LOG_BYTE_POSEnd Position

recover

Recover the ledger data for failed bookie.

Usage
$ bin/bookkeeper shell recover \ 
<bookieSrc[,bookieSrc,...]> \
<options>
FlagDescription
-d,--deleteCookieDelete cookie node for the bookie.
-dr,--dryrunPrinting the recovery plan w/o doing actual recovery
-f,--forceForce recovery without confirmation
-l,--ledger LEDGER_IDRecover a specific ledger
-q,--queryQuery the ledgers that contain given bookies
-sk,--skipOpenLedgersSkip recovering open ledgers
-sku,--skipUnrecoverableLedgersSkip unrecoverable ledgers

simpletest

Simple test to create a ledger and write entries to it.

Usage
$ bin/bookkeeper shell simpletest \ 
<options>
FlagDescription
-e,--ensemble NEnsemble size (default 3)
-w,--writeQuorum NWrite quorum size (default 2)
-a,--ackQuorum NAck quorum size (default 2)
-n,--numEntries NEntries to write (default 1000)

triggeraudit

Force trigger the Audit by resetting the lostBookieRecoveryDelay.

Usage
$ bin/bookkeeper shell triggeraudit

updatecookie

Update bookie id in cookie.

Usage
$ bin/bookkeeper shell updatecookie \ 
<options>
FlagDescription
-b,--bookieId HOSTNAME or IPBookie Id
-d,--delete FORCEDelete cookie both locally and in ZooKeeper
-e,--expandstorageExpand Storage
-l,--listList paths of all the cookies present locally and on zookkeeper

updateledgers

Update bookie id in ledgers (this may take a long time).

Usage
$ bin/bookkeeper shell updateledgers \ 
<options>
FlagDescription
-b,--bookieId HOSTNAME or IPBookie Id
-s,--updatespersecNumber of ledgers updating per second (default 5 per sec)
-l,--limit NMaximum number of ledgers to update (default no limit)
-v,--verbosePrint status of the ledger updation (default false)
-p,--printprogress NPrint messages on every configured seconds if verbose turned on (default 10 secs)
-r,--maxOutstandingReads NMax outstanding reads (default: 5 * updatespersec)

updateBookieInLedger

Replace srcBookie with destBookie in ledger metadata. (this may take a long time). Useful when Host-reip or data-migration. In that case, shutdown bookie process in src-bookie, use this command to update ledger metadata by replacing src-bookie to dest-bookie where data has been copied/moved. Start the bookie process on dest-bookie and dest-bookie will serve copied ledger data from src-bookie.

Usage
$ bin/bookkeeper shell updateBookieInLedger \ 
<options>
FlagDescription
-sb,--srcBookie BOOKIE_IDSource Bookie Id
-db,--destBookie BOOKIE_IDDestination Bookie Id
-s,--updatespersec NNumber of ledgers updating per second (default 5 per sec)
-l,--limit NMaximum number of ledgers to update (default no limit)
-v,--verbosePrint status of the ledger updation (default false)
-p,--printprogress NPrint messages on every configured seconds if verbose turned on (default 10 secs)
-r,--maxOutstandingReads NMax outstanding reads (default: 5 * updatespersec)

whoisauditor

Print the node which holds the auditor lock

Usage
$ bin/bookkeeper shell whoisauditor

whatisinstanceid

Print the instanceid of the cluster

Usage
$ bin/bookkeeper shell whatisinstanceid

convert-to-db-storage

Convert bookie indexes from InterleavedStorage to DbLedgerStorage format

Usage
$ bin/bookkeeper shell convert-to-db-storage

convert-to-interleaved-storage

Convert bookie indexes from DbLedgerStorage to InterleavedStorage format

Usage
$ bin/bookkeeper shell convert-to-interleaved-storage

rebuild-db-ledger-locations-index

Rebuild DbLedgerStorage locations index

Usage
$ bin/bookkeeper shell rebuild-db-ledger-locations-index