cbepctl tool

cbepctl tool

The cbepctl tool is used to control vBucket states, configuration, and memory and disk persistence behavior.


This tool is a per-node, per-bucket operation. That means that the IP address of a node in the cluster and a named bucket must be specified. If a named bucket is not provided, the server applies the setting to any default bucket that exists at the specified node. To perform this operation for an entire cluster, perform the command for every node/bucket combination that exists for that cluster.

For example, when a data bucket is shared by two nodes, issue this command twice and provide the different host names and ports for each node along with the bucket name. Similarly, when two data buckets are on the same node, issue the command twice for each data bucket. If a bucket is not specified, the command applies to the default bucket or returns an error if a default bucket does not exist.

Important: Changes to the cluster configuration using cbepctl are not persisted over a cluster restart.

The tool is found in the following locations:

Operating system Location
Linux /opt/couchbase/bin/cbepctl
Windows C:\Program Files\Couchbase\Server\bin\cbepctl.exe
Mac OS X /Applications/Couchbase Server.app/Contents/Resources/couchbase-core/bin/cbepctl

CLI command and parameters

Basic syntax for this command:

cbepctl [localhost]:11210 -b [bucket_name] -p [bucket-password] start
cbepctl [localhost]:11210 -b [bucket_name] -p [bucket-password] stop
cbepctl [localhost]:11210 -b [bucket_name] -p [bucket-password] set [command-type] [parameter] [value]

For this command, host is the IP address for the Couchbase cluster or node in the cluster. The port is always the standard port used for cluster-wide stats and is at 11210 . The bucket name and password is provided first and then the command option and authentication.

Use the following command options to manage persistence:

Table 1. cbepctl command options
Command option Description
stop Stop persistence
start Start persistence
drain Wait until queues are drained
set Set checkpoint_param , flush_param , and tap_param command types. This changes how or when persistence occurs.

The set command option along with the checkpoint_param , flush_param , and tap_param command types change the behavior of persistence in Couchbase Server.

cbepctl set checkpoint_param

The parameters for set checkpoint_param are:

Parameter Description
chk_max_items Max number of items allowed in a checkpoint.
chk_period Time bound (in sec.) on a checkpoint.
item_num_based_new_chk True if a new checkpoint can be created based on. the number of items in the open checkpoint.
keep_closed_chks True if we want to keep closed checkpoints in memory, as long as the current memory usage is below high water mark.
max_checkpoints Max number of checkpoints allowed per vbucket.
enable_chk_merge True, if merging closed checkpoints is enabled.

cbepctl set flush_param

The parameters for set flush_param are:

Parameter Description
alog_sleep_time Access scanner interval (minute)
alog_task_time Access scanner next task time (UTC)
backfile_mem_threshold Memory threshold (%) on the current bucket quota before backfill task is made to back off.
bg_fetch_delay Delay before executing a bg fetch (test feature).
couch_response_timeout timeout in receiving a response from CouchDB.
exp_pager_stime Expiry Pager interval. Time interval that Couchbase Server waits before it performs cleanup and removal of expired items from disk.
flushall_enabled Deprecated. Enable flush operation.
pager_active_vb_pcnt Percentage of active vBuckets items among all ejected items by item pager.
max_size Maximum memory used by the server.
mem_high_wat High water mark in bytes.
mem_low_wat Low water mark in bytes.
mutation_mem_threshold Amount of RAM that can be consumed in that caching layer before clients start receiving temporary out of memory messages.
timing_log Path to log detailed timing stats.
warmup_min_memory_threshold Memory threshold (%) during warmup to enable traffic.
warmup_min_item_threshold Item number threshold (%) during warmup to enable traffic.
max_num_readers Override the default number of global threads that prioritize read operations.
max_num_writers Override the default number of global threads that prioritize write operations.
max_num_auxio Override the default number of global threads that prioritize auxio operations.
max_num_nonio Override the default number of global threads that prioritize nonio operations.
Note: % You must use the percentage sign in order to set the value by percentage.

cbepctl set tap_param

The parameters for set tap_param are:

Parameter Description
tap_keepalive Seconds to hold a named tap connection.
tap_throttle_queue_cap Maximum disk write queue size to throttle tap streams (infinite means no cap).
tap_throttle_cap_pcnt Percentage of total items in write queue at which we throttle tap input.
tap_throttle_threshold Percentage of memory in use to throttle tap streams