BookKeeper CLI tool reference

bookkeeper command

Manages bookies.

Environment variables

Environment variable	Description	Default
BOOKIE_LOG_CONF	The Log4j configuration file.	${bookkeeperHome}/bookkeeper-server/conf/log4j.properties
BOOKIE_CONF	The configuration file for the bookie.	${bookkeeperHome}/bookkeeper-server/conf/bk_server.conf
BOOKIE_EXTRA_CLASSPATH	Extra paths to add to BookKeeper's classpath.
ENTRY_FORMATTER_CLASS	The entry formatter class used to format entries.
BOOKIE_PID_DIR	The directory where the bookie server PID file is stored.
BOOKIE_STOP_TIMEOUT	The 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>

Flag	Description
--upgrade	Upgrade the filesystem.
--rollback	Rollback the filesystem to a previous version.
--finalize	Mark 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

autorecovery

Enable or disable autorecovery in the cluster.

Usage

$ bin/bookkeeper shell autorecovery \ 
    <options>

Flag	Description
-enable	Enable autorecovery of underreplicated ledgers
-disable	Disable autorecovery of underreplicated ledgers

bookieformat

Format the current server contents.

Usage

$ bin/bookkeeper shell bookieformat \ 
    <options>

Flag	Description
-nonInteractive	Whether to confirm if old data exists.
-force	If [nonInteractive] is specified, then whether to force delete the old data without prompt..?
-deleteCookie	Delete 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>

Flag	Description
-entries N	Total entries to be added for the test (default 10)
-timeout N	Timeout 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>

Flag	Description
-ledgerid N	Ledger ID
-force	Whether 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>

Flag	Description
-m LEDGER_ID	Print meta information

ledgermetadata

Print the metadata for a ledger.

Usage

$ bin/bookkeeper shell ledgermetadata \ 
    <options>

Flag	Description
-ledgerid N	Ledger ID

listbookies

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

Usage

$ bin/bookkeeper shell listbookies \ 
    <options>

Flag	Description
-readwrite	Print readwrite bookies
-readonly	Print readonly bookies
-hostnames	Also print hostname of the bookie

listfilesondisc

List the files in JournalDirectory/LedgerDirectories/IndexDirectories.

Usage

$ bin/bookkeeper shell listfilesondisc \ 
    <options>

Flag	Description
-journal	Print list of journal files
-entrylog	Print list of entryLog files
-index	Print list of index files

listledgers

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

Usage

$ bin/bookkeeper shell listledgers \ 
    <options>

Flag	Description
-meta	Print 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>

Flag	Description
-missingreplica N	Bookie Id of missing replica
-excludingmissingreplica N	Bookie Id of missing replica to ignore
-printmissingreplica	Whether to print missingreplicas list?

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>

Flag	Description
-nonInteractive	Whether to confirm if old data exists..?
-force	If [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>

Flag	Description
-zkledgersrootpath	zookeeper ledgers rootpath
-instanceid	instance id
-force	If 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>

Flag	Description
-get	Get LostBookieRecoveryDelay value (in seconds)
-set N	Set LostBookieRecoveryDelay value (in seconds)

readjournal

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

Usage

$ bin/bookkeeper shell readjournal \ 
    <options>

Flag	Description
-msg JOURNAL_ID	JOURNAL_FILENAME
-dir	Journal 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>]]

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>

Flag	Description
-msg	Print message body
-ledgerid N	Ledger ID
-entryid N	Entry ID
-startpos N	Start Position
-endpos	End Position

recover

Recover the ledger data for failed bookie.

Usage

$ bin/bookkeeper shell recover \ 
    <bookieSrc[,bookieSrc,...]> \ 
    <options>

Flag	Description
-deleteCookie	Delete cookie node for the bookie.

simpletest

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

Usage

$ bin/bookkeeper shell simpletest \ 
    <options>

Flag	Description
-ensemble N	Ensemble size (default 3)
-writeQuorum N	Write quorum size (default 2)
ackQuorum N	Ack quorum size (default 2)
-numEntries N	Entries 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>

Flag	Description
-bookieId <hostname	ip>

updateledgers

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

Usage

$ bin/bookkeeper shell updateledgers \ 
    <options>

Flag	Description
-bookieId <hostname	ip>
-updatespersec N	Number of ledgers updating per second (default 5 per sec)
-limit N	Maximum number of ledgers to update (default no limit)
-verbose	Print status of the ledger updation (default false)
-printprogress N	Print messages on every configured seconds if verbose turned on (default 10 secs)

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>

Flag	Description
-srcBookie BOOKIE_ID	Source Bookie Id
-destBookie BOOKIE_ID	Destination Bookie Id
-updatespersec N	Number of ledgers updating per second (default 5 per sec)
-limit N	Maximum number of ledgers to update (default no limit)
-verbose	Print status of the ledger updation (default false)
-printprogress N	Print messages on every configured seconds if verbose turned on (default 10 secs)

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