Pulsar command-line tools


Pulsar offers several command-line tools that you can use for managing Pulsar installations, performance testing, using command-line producers and consumers, and more.

All Pulsar command-line tools can be run from the bin directory of your installed Pulsar package. The following tools are currently documented:

Getting help

You can get help for any CLI tool, command, or subcommand using the --help flag, or -h for short. Here’s an example:

$ bin/pulsar-admin clusters --help

pulsar

The pulsar tool is used to start Pulsar components, such as bookies and ZooKeeper, in the foreground.

These processes can also be started in the background, using nohup, using the pulsar-daemon tool, which has the same command interface as pulsar.

Usage
$ pulsar command
Commands
Example
$ pulsar broker \
  --conf /path/to/broker.conf
Environment variables

The table below lists the environment variables that you can use to configure the pulsar tool.

Variable Description Default
PULSAR_LOG_CONF Log4j configuration file conf/log4j2.yaml
PULSAR_BROKER_CONF Configuration file for broker conf/broker.conf
PULSAR_BOOKKEEPER_CONF Configuration file for bookie conf/bookkeeper.conf
PULSAR_ZK_CONF Configuration file for zookeeper conf/zookeeper.conf
PULSAR_CONFIGURATION_STORE_CONF Configuration file for the configuration store conf/global_zookeeper.conf
PULSAR_DISCOVERY_CONF Configuration file for discovery service conf/discovery.conf
PULSAR_WEBSOCKET_CONF Configuration file for websocket proxy conf/websocket.conf
PULSAR_STANDALONE_CONF Configuration file for standalone conf/standalone.conf
PULSAR_EXTRA_OPTS Extra options to be passed to the jvm
PULSAR_EXTRA_CLASSPATH Extra paths for Pulsar's classpath
PULSAR_PID_DIR Folder where the pulsar server PID file should be stored
PULSAR_STOP_TIMEOUT Wait time before forcefully killing the Bookie server instance if attempts to stop it are not successful

bookie

Starts up a bookie server

Usage
$ pulsar bookie options
Options
Flag Description Default
-c , --conf

Configuration for the bookie server

-readOnly

Force start a read-only bookie server

false

-withAutoRecovery

Start auto-recovery service bookie server

false

Example
$ pulsar bookie \
  -readOnly \
  -withAutoRecovery \
  --conf /path/to/bookkeeper.conf

broker

Starts up a Pulsar broker

Usage
$ pulsar broker options
Options
Flag Description Default
-c , --broker-conf

Configuration file for the broker

-bc , --bookie-conf

Configuration file for BookKeeper

-rb , --run-bookie

Run a BookKeeper bookie on the same host as the Pulsar broker

false

-ra , --run-bookie-autorecovery

Run a BookKeeper autorecovery daemon on the same host as the Pulsar broker

false

Example
$ pulsar broker \
  --conf /path/to/broker.conf

compact-topic

Run compaction against a Pulsar topic (in a new process)

Usage
$ pulsar compact-topic options
Options
Flag Description Default
-t , --topic

The Pulsar topic that you would like to compact

-c , --broker-conf

Configuration file for the broker

${pulsarDirectory}/conf/broker.conf

Example
$ pulsar compact-topic \
  --topic topic-to-compact

discovery

Run a discovery server

Usage
$ pulsar discovery options
Options
Flag Description Default
-c , --conf

Configuration file for the discovery service

Example
$ pulsar discovery \
  --conf /path/to/discovery.conf

configuration-store

Starts up the Pulsar configuration store

Usage
$ pulsar configuration-store options
Options
Flag Description Default
-c , --conf

Configuration file for the configuration store

initialize-cluster-metadata

One-time cluster metadata initialization

Usage
$ pulsar initialize-cluster-metadata options
Options
Flag Description Default
-ub , --broker-service-url

The broker service URL for the new cluster

-tb , --broker-service-url-tls

The broker service URL for the new cluster with TLS encryption

-c , --cluster

Cluster name

--configuration-store

The configuration store quorum connection string

-uw , --web-service-url

The web service URL for the new cluster

-tw , --web-service-url-tls

The web service URL for the new cluster with TLS encryption

-zk , --zookeeper

The local ZooKeeper quorum connection string

proxy

Manages the Pulsar proxy

Usage
$ pulsar proxy options
Options
Flag Description Default
-c , --config

Path to a Pulsar proxy configuration file

--configuration-store

Configuration store connection string

-zk , --zookeeper-servers

Local ZooKeeper connection string

Example
$ pulsar proxy \
  --zookeeper-servers zk-0,zk-1,zk2 \
  --configuration-store zk-0,zk-1,zk-2

standalone

Run a broker service with local bookies and local ZooKeeper

Usage
$ pulsar standalone options
Options
Flag Description Default
-a , --advertised-address

The standalone broker advertised address

--bookkeeper-dir

Local bookies’ base data directory

data/standalone/bookeeper

--bookkeeper-port

Local bookies’ base port

3181

-c , --config

Configuration file path

--no-broker

Only start ZooKeeper and BookKeeper services, not the broker

false

--num-bookies

The number of local bookies

1

--only-broker

Only start the Pulsar broker service (not ZooKeeper or BookKeeper)

--wipe-data

Clean up previous ZooKeeper/BookKeeper data

--zookeeper-dir

Local ZooKeeper’s data directory

data/standalone/zookeeper

--zookeeper-port

Local ZooKeeper’s port

2181

websocket

Usage
$ pulsar websocket options
Options
Flag Description Default
-c , --conf

Configuration file for WebSocket service

zookeeper

Starts up a ZooKeeper cluster

Usage
$ pulsar zookeeper options
Options
Flag Description Default
-c , --conf

Configuration file for ZooKeeper

zookeeper-shell

Connects to a running ZooKeeper cluster using the ZooKeeper shell

Usage
$ pulsar zookeeper-shell options
Options
Flag Description Default
-c , --conf

Configuration file for ZooKeeper

zookeeper-shell

Opens up a shell client to the ZooKeeper cluster used by Pulsar

Usage
$ pulsar zookeeper-shell

pulsar-admin

The pulsar-admin tool enables you to manage Pulsar installations, including clusters, brokers, namespaces, tenants, and more.

Usage
$ pulsar-admin command
Commands

broker-stats

Operations to collect broker statistics

Usage
$ pulsar-admin broker-stats subcommand
Subcommands

allocator-stats

Dump allocator stats

Usage
$ pulsar-admin broker-stats allocator-stats allocator-name

destinations

Dump topic stats

Usage
$ pulsar-admin broker-stats destinations options
Options
Flag Description Default
-i , --indent

Indent JSON output

false

mbeans

Dump Mbean stats

Usage
$ pulsar-admin broker-stats mbeans options
Options
Flag Description Default
-i , --indent

Indent JSON output

false

monitoring-metrics

dump metrics for Monitoring

Usage
$ pulsar-admin broker-stats monitoring-metrics options
Options
Flag Description Default
-i , --indent

Indent JSON output

false

topics

Dump topic stats

Usage
$ pulsar-admin broker-stats topics options
Options
Flag Description Default
-i , --indent

Indent JSON output

false

brokers

Operations about brokers

Usage
$ pulsar-admin brokers subcommand
Subcommands

list

List active brokers of the cluster

Usage
$ pulsar-admin brokers list cluster-name

namespaces

List namespaces owned by the broker

Usage
$ pulsar-admin brokers namespaces cluster-name options
Options
Flag Description Default
--url

The URL for the broker

update-dynamic-config

Update a broker's dynamic service configuration

Usage
$ pulsar-admin brokers update-dynamic-config options
Options
Flag Description Default
--config

Service configuration parameter name

--value

Value for the configuration parameter value specified using the --config flag

list-dynamic-config

Get list of updatable configuration name

Usage
$ pulsar-admin brokers list-dynamic-config

get-all-dynamic-config

Get all overridden dynamic-configuration values

Usage
$ pulsar-admin brokers get-all-dynamic-config

get-internal-config

Get internal configuration information

Usage
$ pulsar-admin brokers get-internal-config

clusters

Operations about clusters

Usage
$ pulsar-admin clusters subcommand
Subcommands

get

Get the configuration data for the specified cluster

Usage
$ pulsar-admin clusters get cluster-name

create

Provisions a new cluster. This operation requires Pulsar super-user privileges.

Usage
$ pulsar-admin clusters create cluster-name options
Options
Flag Description Default
--broker-url

The URL for the broker service.

--broker-url-secure

The broker service URL for a secure connection

--url

service-url

--url-secure

service-url for secure connection

update

Update the configuration for a cluster

Usage
$ pulsar-admin clusters update cluster-name options
Options
Flag Description Default
--broker-url

The URL for the broker service.

--broker-url-secure

The broker service URL for a secure connection

--url

service-url

--url-secure

service-url for secure connection

delete

Deletes an existing cluster

Usage
$ pulsar-admin clusters delete cluster-name

list

List the existing clusters

Usage
$ pulsar-admin clusters list

update-peer-clusters

Update peer cluster names

Usage
$ pulsar-admin clusters update-peer-clusters peer-cluster-names

functions

A command-line interface for Pulsar Functions

Usage
$ pulsar-admin functions subcommand
Subcommands

localrun

Run a Pulsar Function locally

Usage
$ pulsar-admin functions localrun options
Options
Flag Description Default
--cpu

The CPU to allocate to each function instance (in number of cores)

--ram

The RAM to allocate to each function instance (in bytes)

--disk

The disk space to allocate to each function instance (in bytes)

--brokerServiceUrl

The URL of the Pulsar broker

--className

The name of the function’s class

--customSerdeInputs

A map of the input topic to SerDe name

--functionConfigFile

The path of the YAML config file used to configure the function

--inputs

The input topics for the function (as a comma-separated list if more than one topic is desired)

--logTopic

The topic to which logs from this function are published

--jar

A path to the JAR file for the function (if the function is written in Java)

--name

The name of the function

The value specified by --className

--namespace

The function’s namespace

--output

The name of the topic to which the function publishes its output (if any)

--outputSerdeClassName

The SerDe class used for the function’s output

--parallelism

The function’s parallelism factor, i.e. the number of instances of the function to run

1

--processingGuarantees

The processing guarantees applied to the function. Can be one of: ATLEAST_ONCE, ATMOST_ONCE, or EFFECTIVELY_ONCE

ATLEAST_ONCE

--py

The path of the Python file containing the function’s processing logic (if the function is written in Python)

--stateStorageServiceUrl

The service URL for the function’s state storage (if the function uses a storage system different from the Apache BookKeeper cluster used by Pulsar)

--subscriptionType

The subscription type used by the function when consuming messages on the input topic(s). Can be either SHARED or EXCLUSIVE

SHARED

--tenant

The function’s tenant

--userConfig

A user-supplied config value, set as a key/value pair. You can set multiple user config values.

create

Creates a new Pulsar Function on the target infrastructure

Usage
$ pulsar-admin functions create options
Options
Flag Description Default
--cpu

The CPU to allocate to each function instance (in number of cores)

--ram

The RAM to allocate to each function instance (in bytes)

--disk

The disk space to allocate to each function instance (in bytes)

--className

The name of the function’s class

--customSerdeInputs

A map of the input topic to SerDe name

--functionConfigFile

The path of the YAML config file used to configure the function

--inputs

The input topics for the function (as a comma-separated list if more than one topic is desired)

--jar

A path to the JAR file for the function (if the function is written in Java)

--name

The name of the function

The value specified by --className

--namespace

The function’s namespace

--logTopic

The topic to which logs from this function are published

--output

The name of the topic to which the function publishes its output (if any)

--outputSerdeClassName

The SerDe class used for the function’s output

--parallelism

The function’s parallelism factor, i.e. the number of instances of the function to run

1

--processingGuarantees

The processing guarantees applied to the function. Can be one of: ATLEAST_ONCE, ATMOST_ONCE, or EFFECTIVELY_ONCE

ATLEAST_ONCE

--py

The path of the Python file containing the function’s processing logic (if the function is written in Python)

--subscriptionType

The subscription type used by the function when consuming messages on the input topic(s). Can be either SHARED or EXCLUSIVE

SHARED

--tenant

The function’s tenant

--userConfig

A user-supplied config value, set as a key/value pair. You can set multiple user config values.

delete

Deletes an existing Pulsar Function

Usage
$ pulsar-admin functions delete options
Options
Flag Description Default
--name

The name of the function to delete

--namespace

The namespace of the function to delete

--tenant

The tenant of the function to delete

update

Updates an existing Pulsar Function

Usage
$ pulsar-admin functions update options
Options
Flag Description Default
--className

The name of the function’s class

--customSerdeInputs

A map of the input topic to SerDe name

--functionConfigFile

The path of the YAML config file used to configure the function

--inputs

The input topics for the function (as a comma-separated list if more than one topic is desired)

--jar

A path to the JAR file for the function (if the function is written in Java)

--name

The name of the function

The value specified by --className

--namespace

The function’s namespace

--logTopic

The topic to which logs from this function are published

--output

The name of the topic to which the function publishes its output (if any)

--outputSerdeClassName

The SerDe class used for the function’s output

--parallelism

The function’s parallelism factor, i.e. the number of instances of the function to run

1

--processingGuarantees

The processing guarantees applied to the function. Can be one of: ATLEAST_ONCE, ATMOST_ONCE, or EFFECTIVELY_ONCE

ATLEAST_ONCE

--py

The path of the Python file containing the function’s processing logic (if the function is written in Python)

--subscriptionType

The subscription type used by the function when consuming messages on the input topic(s). Can be either SHARED or EXCLUSIVE

SHARED

--tenant

The function’s tenant

--userConfig

A user-supplied config value, set as a key/value pair. You can set multiple user config values.

get

Fetch information about an existing Pulsar Function

Usage
$ pulsar-admin functions get options
Options
Flag Description Default
--name

The name of the function about which you want to fetch information

--namespace

The namespace of the function about which you want to fetch information

--tenant

The tenant of the function about which you want to fetch information

getstatus

Get the status of an existing Pulsar Function

Usage
$ pulsar-admin functions getstatus options
Options
Flag Description Default
--name

The name of the function about which you want to fetch status information

--namespace

The namespace of the function about which you want to fetch status information

--tenant

The tenant of the function about which you want to fetch status information

list

List all Pulsar Functions for a specific tenant and namespace

Usage
$ pulsar-admin functions list options
Options
Flag Description Default
--namespace

The namespace of the functions you want to list

--tenant

The tenant of the functions you want to list

querystate

Retrieve the current state of a Pulsar Function by key

Usage
$ pulsar-admin functions querystate options
Options
Flag Description Default
-k , --key

The key for the state you want to fetch

--name

The name of the function whose state you want to query

--namespace

The namespace of the function whose state you want to query

--tenant

The tenant of the function whose state you want to query

-u , --storage-service-url

The service URL for the function’s state storage (if the function uses a storage system different from the Apache BookKeeper cluster used by Pulsar)

-w , --watch

If set, watching for state changes is enabled

false

trigger

Triggers the specified Pulsar Function with a supplied value or file data

Usage
$ pulsar-admin functions trigger options
Options
Flag Description Default
--name

The name of the Pulsar Function to trigger

--namespace

The namespace of the Pulsar Function to trigger

--tenant

The tenant of the Pulsar Function to trigger

--triggerFile

The path to the file containing the data with which the Pulsar Function is to be triggered

--triggerValue

The value with which the Pulsar Function is to be triggered

namespaces

Operations for managing namespaces

Usage
$ pulsar-admin namespaces subcommand
Subcommands

list

Get the namespaces for a tenant

Usage
$ pulsar-admin namespaces list tenant-name

list-cluster

Get the namespaces for a tenant in the cluster

Usage
$ pulsar-admin namespaces list-cluster tenant/cluster

destinations

Get the destinations for a namespace

Usage
$ pulsar-admin namespaces destinations tenant/cluster/namespace

policies

Get the policies of a namespace

Usage
$ pulsar-admin namespaces policies tenant/cluster/namespace

create

Create a new namespace

Usage
$ pulsar-admin namespaces create tenant/cluster/namespace options
Options
Flag Description Default
-b , --bundles

The number of bundles to activate

0

delete

Deletes a namespace

Usage
$ pulsar-admin namespaces delete tenant/cluster/namespace

set-deduplication

Enable or disable message deduplication on a namespace

Usage
$ pulsar-admin namespaces set-deduplication tenant/cluster/namespace options
Options
Flag Description Default
--enable , -e

Enable message deduplication on the specified namespace

false

--disable , -d

Disable message deduplication on the specified namespace

false

permissions

Get the permissions on a namespace

Usage
$ pulsar-admin namespaces permissions tenant/cluster/namespace

grant-permission

Grant permissions on a namespace

Usage
$ pulsar-admin namespaces grant-permission tenant/cluster/namespace options
Options
Flag Description Default
--actions

Actions to be granted (produce or consume)

--role

The client role to which to grant the permissions

revoke-permission

Revoke permissions on a namespace

Usage
$ pulsar-admin namespaces revoke-permission tenant/cluster/namespace options
Options
Flag Description Default
--role

The client role from which to revoke the permissions

set-clusters

Set replication clusters for a namespace

Usage
$ pulsar-admin namespaces set-clusters tenant/cluster/namespace options
Options
Flag Description Default
-c , --clusters

Replication clusters ID list (comma-separated values)

get-clusters

Get replication clusters for a namespace

Usage
$ pulsar-admin namespaces get-clusters tenant/cluster/namespace

get-backlog-quotas

Get the backlog quota policies for a namespace

Usage
$ pulsar-admin namespaces get-backlog-quotas tenant/cluster/namespace

set-backlog-quota

Set a backlog quota for a namespace

Usage
$ pulsar-admin namespaces set-backlog-quota tenant/cluster/namespace options
Options
Flag Description Default
-l , --limit

The backlog size limit (for example 10M or 16G)

-p , --policy

The retention policy to enforce when the limit is reached. The valid options are:

  • producer_request_hold
  • producer_exception
  • consumer_backlog_eviction
Example
$ pulsar-admin namespaces set-backlog-quota my-prop/my-cluster/my-ns \
--limit 2G \
--policy producer_request_hold

remove-backlog-quota

Remove a backlog quota policy from a namespace

Usage
$ pulsar-admin namespaces remove-backlog-quota tenant/cluster/namespace

get-persistence

Get the persistence policies for a namespace

Usage
$ pulsar-admin namespaces get-persistence tenant/cluster/namespace

set-persistence

Set the persistence policies for a namespace

Usage
$ pulsar-admin namespaces set-persistence tenant/cluster/namespace options
Options
Flag Description Default
-a , --bookkeeper-ack-quorom

The number of acks (guaranteed copies) to wait for each entry

0

-e , --bookkeeper-ensemble

The number of bookies to use for a topic

0

-w , --bookkeeper-write-quorum

How many writes to make of each entry

0

-r , --ml-mark-delete-max-rate

Throttling rate of mark-delete operation (0 means no throttle)

get-message-ttl

Get the message TTL for a namespace

Usage
$ pulsar-admin namespaces get-message-ttl tenant/cluster/namespace

set-message-ttl

Set the message TTL for a namespace

Usage
$ pulsar-admin namespaces set-message-ttl options
Options
Flag Description Default
-ttl , --messageTTL

Message TTL in seconds

0

get-retention

Get the retention policy for a namespace

Usage
$ pulsar-admin namespaces get-retention tenant/cluster/namespace

set-retention

Set the retention policy for a namespace

Usage
$ pulsar-admin namespaces set-retention tenant/cluster/namespace options
Options
Flag Description Default
-s , --size

The retention size limits (for example 10M, 16G or 3T). 0 means no retention and -1 means infinite size retention

-t , --time

The retention time in minutes, hours, days, or weeks. Examples: 100m, 13h, 2d, 5w. 0 means no retention and -1 means infinite time retention

unload

Unload a namespace or namespace bundle from the current serving broker.

Usage
$ pulsar-admin namespaces unload tenant/cluster/namespace options
Options
Flag Description Default
-b , --bundle

clear-backlog

Clear the backlog for a namespace

Usage
$ pulsar-admin namespaces clear-backlog tenant/cluster/namespace options
Options
Flag Description Default
-b , --bundle
-f , --force

Whether to force a clear backlog without prompt

false

-s , --sub

The subscription name

unsubscribe

Unsubscribe the given subscription on all destinations on a namespace

Usage
$ pulsar-admin namespaces unsubscribe tenant/cluster/namespace options
Options
Flag Description Default
-b , --bundle
-s , --sub

The subscription name

get-compaction-threshold

Get compactionThreshold for a namespace

Usage
$ pulsar-admin namespaces get-compaction-threshold tenant/namespace

set-compaction-threshold

Set compactionThreshold for a namespace

Usage
$ pulsar-admin namespaces set-compaction-threshold tenant/namespace options
Options
Flag Description Default
-t , --threshold

Maximum number of bytes in a topic backlog before compaction is triggered (eg: 10M, 16G, 3T). 0 disables automatic compaction

0

get-offload-threshold

Get offloadThreshold for a namespace

Usage
$ pulsar-admin namespaces get-offload-threshold tenant/namespace

set-offload-threshold

Set offloadThreshold for a namespace

Usage
$ pulsar-admin namespaces set-offload-threshold tenant/namespace options
Options
Flag Description Default
-s , --size

Maximum number of bytes stored in the pulsar cluster for a topic before data will start being automatically offloaded to longterm storage (eg: 10M, 16G, 3T, 100). Negative values disable automatic offload. 0 triggers offloading as soon as possible.

-1

ns-isolation-policy

Operations for managing namespace isolation policies.

Usage
$ pulsar-admin ns-isolation-policy subcommand
Subcommands

set

Create/update a namespace isolation policy for a cluster. This operation requires Pulsar superuser privileges.

Usage
$ pulsar-admin ns-isolation-policy set cluster-name policy-name options
Options
Flag Description Default
--auto-failover-policy-params

Comma-separated name=value auto failover policy parameters

[]

--auto-failover-policy-type

Auto failover policy type name. Currently available options: min_available.

[]

--namespaces

Comma-separated namespaces regex list

[]

--primary

Comma-separated primary broker regex list

[]

--secondary

Comma-separated secondary broker regex list

[]

get

Get the namespace isolation policy of a cluster. This operation requires Pulsar superuser privileges.

Usage
$ pulsar-admin ns-isolation-policy get cluster-name policy-name

list

List all namespace isolation policies of a cluster. This operation requires Pulsar superuser privileges.

Usage
$ pulsar-admin ns-isolation-policy list cluster-name

delete

Delete namespace isolation policy of a cluster. This operation requires superuser privileges.

Usage
$ pulsar-admin ns-isolation-policy delete

sink

An interface for managing Pulsar IO sinks (egress data from Pulsar)

Usage
$ pulsar-admin sink subcommand
Subcommands

create

Submit a Pulsar IO sink connector to run in a Pulsar cluster

Usage
$ pulsar-admin sink create options
Options
Flag Description Default
--className

The sink’s Java class name

--cpu

The CPU (in cores) that needs to be allocated per sink instance (applicable only to the Docker runtime)

--customSerdeInputs

The map of input topics to SerDe class names (as a JSON string)

--disk

The disk (in bytes) that needs to be allocated per sink instance (applicable only to the Docker runtime)

--inputs

The sink’s input topic(s) (multiple topics can be specified as a comma-separated list)

--jar

Path to the Java jar file for the sink

--name

The sink’s name

--namespace

The sink’s namespace

--parallelism

“The sink’s parallelism factor (i.e. the number of sink instances to run).”

--processingGuarantees

“The processing guarantees (aka delivery semantics) applied to the sink. Available values: ATLEAST_ONCE, ATMOST_ONCE, EFFECTIVELY_ONCE.”

--ram

The RAM (in bytes) that needs to be allocated per sink instance (applicable only to the Docker runtime)

--sinkConfig

Sink config key/values

--sinkConfigFile

The path to a YAML config file specifying the sink’s configuration

--tenant

The sink’s tenant

delete

Stops a Pulsar IO sink

Usage
$ pulsar-admin sink delete options
Options
Flag Description Default
--name

The name of the sink

--namespace

The namespace of the sink

--tenant

The tenant of the sink

localrun

Run the Pulsar sink locally (rather than in the Pulsar cluster)

Usage
$ pulsar-admin sink localrun options
Options
Flag Description Default
--brokerServiceUrl

The URL for the Pulsar broker

--className

The sink’s Java class name

--cpu

The CPU (in cores) that needs to be allocated per sink instance (applicable only to the Docker runtime)

--customSerdeInputs

The map of input topics to SerDe class names (as a JSON string)

--disk

The disk (in bytes) that needs to be allocated per sink instance (applicable only to the Docker runtime)

--inputs

The sink’s input topic(s) (multiple topics can be specified as a comma-separated list)

--jar

Path to the Java jar file for the sink

--name

The sink’s name

--namespace

The sink’s namespace

--parallelism

“The sink’s parallelism factor (i.e. the number of sink instances to run).”

--processingGuarantees

“The processing guarantees (aka delivery semantics) applied to the sink. Available values: ATLEAST_ONCE, ATMOST_ONCE, EFFECTIVELY_ONCE.”

--ram

The RAM (in bytes) that needs to be allocated per sink instance (applicable only to the Docker runtime)

--sinkConfig

Sink config key/values

--sinkConfigFile

The path to a YAML config file specifying the sink’s configuration

--tenant

The sink’s tenant

source

An interface for managing Pulsar IO sources (ingress data into Pulsar)

Usage
$ pulsar-admin source subcommand
Subcommands

create

Submit a Pulsar IO source connector to run in a Pulsar cluster

Usage
$ pulsar-admin source create options
Options
Flag Description Default
--className

The source’s Java class name

--cpu

The CPU (in cores) that needs to be allocated per source instance (applicable only to the Docker runtime)

--deserializationClassName

The SerDe classname for the source

--destinationTopicName

The Pulsar topic to which data is sent

--disk

The disk (in bytes) that needs to be allocated per source instance (applicable only to the Docker runtime)

--jar

Path to the Java jar file for the source

--name

The source’s name

--namespace

The source’s namespace

--parallelism

The source’s parallelism factor (i.e. the number of source instances to run).

--processingGuarantees

“The processing guarantees (aka delivery semantics) applied to the source. Available values: ATLEAST_ONCE, ATMOST_ONCE, EFFECTIVELY_ONCE.”

--ram

The RAM (in bytes) that needs to be allocated per source instance (applicable only to the Docker runtime)

--sourceConfig

Source config key/values

--sourceConfigFile

The path to a YAML config file specifying the source’s configuration

--tenant

The source’s tenant

delete

Stops a Pulsar IO source

Usage
$ pulsar-admin source delete options
Options
Flag Description Default
--name

The name of the source

--namespace

The namespace of the source

--tenant

The tenant of the source

localrun

Run the Pulsar source locally (rather than in the Pulsar cluster)

Usage
$ pulsar-admin source localrun options
Options
Flag Description Default
--className

The source’s Java class name

--cpu

The CPU (in cores) that needs to be allocated per source instance (applicable only to the Docker runtime)

--deserializationClassName

The SerDe classname for the source

--destinationTopicName

The Pulsar topic to which data is sent

--disk

The disk (in bytes) that needs to be allocated per source instance (applicable only to the Docker runtime)

--jar

Path to the Java jar file for the source

--name

The source’s name

--namespace

The source’s namespace

--parallelism

The source’s parallelism factor (i.e. the number of source instances to run).

--processingGuarantees

“The processing guarantees (aka delivery semantics) applied to the source. Available values: ATLEAST_ONCE, ATMOST_ONCE, EFFECTIVELY_ONCE.”

--ram

The RAM (in bytes) that needs to be allocated per source instance (applicable only to the Docker runtime)

--sourceConfig

Source config key/values

--sourceConfigFile

The path to a YAML config file specifying the source’s configuration

--tenant

The source’s tenant

topics

Operations for managing Pulsar topics (both persistent and non persistent)

Usage
$ pulsar-admin topics subcommand
Subcommands

compact

Run compaction on the specified topic (persistent topics only)

Usage
$ pulsar-admin topics compact persistent://tenant/namespace/topic

compaction-status

Check the status of a topic compaction (persistent topics only)

Usage
$ pulsar-admin topics compaction-status persistent://tenant/namespace/topic options
Options
Flag Description Default
-w , --wait-complete

Wait for compaction to complete

false

offload

Trigger offload of data from a topic to long-term storage (e.g. Amazon S3)

Usage
$ pulsar-admin topics offload persistent://tenant/namespace/topic options
Options
Flag Description Default
-s , --size-threshold

The maximum amount of data to keep in BookKeeper for the specific topic

offload-status

Check the status of data offloading from a topic to long-term storage

Usage
$ pulsar-admin topics offload-status persistent://tenant/namespace/topic options
Options
Flag Description Default
-w , --wait-complete

Wait for offloading to complete

create-partitioned-topic

Create a partitioned topic. A partitioned topic must be created before producers can publish to it.

Usage
$ pulsar-admin topics create-partitioned-topic {persistent|non-persistent}://tenant/namespace/topic options
Options
Flag Description Default
-p , --partitions

The number of partitions for the topic

0

delete-partitioned-topic

Delete a partitioned topic. This will also delete all the partitions of the topic if they exist.

Usage
$ pulsar-admin topics delete-partitioned-topic {persistent|non-persistent}://tenant/namespace/topic

get-partitioned-topic-metadata

Get the partitioned topic metadata. If the topic is not created or is a non-partitioned topic, this will return an empty topic with zero partitions.

Usage
$ pulsar-admin topics get-partitioned-topic-metadata {persistent|non-persistent}://tenant/namespace/topic

list

Get the list of topics under a namespace

Usage
$ pulsar-admin topics list tenant/cluster/namespace

list-in-bundle

Get a list of non-persistent topics present under a namespace bundle

Usage
$ pulsar-admin topics list-in-bundle tenant/namespace options
Options
Flag Description Default
-b , --bundle

The bundle range

terminate

Terminate a topic (disallow further messages from being published on the topic)

Usage
$ pulsar-admin topics terminate {persistent|non-persistent}://tenant/namespace/topic

permissions

Get the permissions on a topic. Retrieve the effective permissions for a desination. These permissions are defined by the permissions set at the namespace level combined (union) with any eventual specific permissions set on the topic.

Usage
$ pulsar-admin topics permissions topic

grant-permission

Grant a new permission to a client role on a single topic

Usage
$ pulsar-admin topics grant-permission {persistent|non-persistent}://tenant/namespace/topic options
Options
Flag Description Default
--actions

Actions to be granted (produce or consume)

--role

The client role to which permissions are to be granted

revoke-permission

Revoke permissions to a client role on a single topic. If the permission was not set at the topic level, but rather at the namespace level, this operation will return an error (HTTP status code 412).

Usage
$ pulsar-admin topics revoke-permission topic

lookup

Look up a topic from the current serving broker

Usage
$ pulsar-admin topics lookup topic

bundle-range

Get the namespace bundle which contains the given topic

Usage
$ pulsar-admin topics bundle-range topic

delete

Delete a topic. The topic cannot be deleted if there are any active subscriptions or producers connected to the topic.

Usage
$ pulsar-admin topics delete topic

unload

Unload a topic

Usage
$ pulsar-admin topics unload topic

subscriptions

Get the list of subscriptions on the topic

Usage
$ pulsar-admin topics subscriptions topic

unsubscribe

Delete a durable subscriber from a topic

Usage
$ pulsar-admin topics unsubscribe topic options
Options
Flag Description Default
-s , --subscription

The subscription to delete

stats

Get the stats for the topic and its connected producers and consumers. All rates are computed over a 1-minute window and are relative to the last completed 1-minute period.

Usage
$ pulsar-admin topics stats topic

stats-internal

Get the internal stats for the topic

Usage
$ pulsar-admin topics stats-internal topic

info-internal

Get the internal metadata info for the topic

Usage
$ pulsar-admin topics info-internal topic

partitioned-stats

Get the stats for the partitioned topic and its connected producers and consumers. All rates are computed over a 1-minute window and are relative to the last completed 1-minute period.

Usage
$ pulsar-admin topics partitioned-stats topic options
Options
Flag Description Default
--per-partition

Get per-partition stats

false

skip

Skip some messages for the subscription

Usage
$ pulsar-admin topics skip topic options
Options
Flag Description Default
-n , --count

The number of messages to skip

0

-s , --subscription

The subscription on which to skip messages

skip-all

Skip all the messages for the subscription

Usage
$ pulsar-admin topics skip-all topic options
Options
Flag Description Default
-s , --subscription

The subscription to clear

expire-messages

Expire messages that are older than the given expiry time (in seconds) for the subscription.

Usage
$ pulsar-admin topics expire-messages topic options
Options
Flag Description Default
-t , --expireTime

Expire messages older than the time (in seconds)

0

-s , --subscription

The subscription to skip messages on

expire-messages-all-subscriptions

Expire messages older than the given expiry time (in seconds) for all subscriptions

Usage
$ pulsar-admin topics expire-messages-all-subscriptions topic options
Options
Flag Description Default
-t , --expireTime

Expire messages older than the time (in seconds)

0

peek-messages

Peek some messages for the subscription.

Usage
$ pulsar-admin topics peek-messages topic options
Options
Flag Description Default
-n , --count

The number of messages

1

-s , --subscription

Subscription to get messages from

reset-cursor

Reset position for subscription to closest to timestamp

Usage
$ pulsar-admin topics reset-cursor topic options
Options
Flag Description Default
-s , --subscription

Subscription to reset position on

-t , --time

The time, in minutes, to reset back to (or minutes, hours, days, weeks, etc.). Examples: 100m, 3h, 2d, 5w.

tenants

Operations for managing tenants

Usage
$ pulsar-admin tenants subcommand
Subcommands

list

List the existing tenants

Usage
$ pulsar-admin tenants list

get

Gets the configuration of a tenant

Usage
$ pulsar-admin tenants get tenant-name

create

Creates a new tenant

Usage
$ pulsar-admin tenants create tenant-name options
Options
Flag Description Default
-r , --admin-roles

Comma-separated admin roles

-c , --allowed-clusters

Comma-separated allowed clusters

update

Updates a tenant

Usage
$ pulsar-admin tenants update tenant-name options
Options
Flag Description Default
-r , --admin-roles

Comma-separated admin roles

-c , --allowed-clusters

Comma-separated allowed clusters

delete

Deletes an existing tenant

Usage
$ pulsar-admin tenants delete tenant-name

resource-quotas

Operations for managing resource quotas

Usage
$ pulsar-admin resource-quotas subcommand
Subcommands

get

Get the resource quota for a specified namespace bundle, or default quota if no namespace/bundle is specified.

Usage
$ pulsar-admin resource-quotas get options
Options
Flag Description Default
-b , --bundle

A bundle of the form {start-boundary}_{end_boundary}. This must be specified together with -n/--namespace.

-n , --namespace

The namespace

set

Set the resource quota for the specified namespace bundle, or default quota if no namespace/bundle is specified.

Usage
$ pulsar-admin resource-quotas set options
Options
Flag Description Default
-bi , --bandwidthIn

The expected inbound bandwidth (in bytes/second)

0

-bo , --bandwidthOut

Expected outbound bandwidth (in bytes/second)

0

-b , --bundle

A bundle of the form {start-boundary}_{end_boundary}. This must be specified together with -n/--namespace.

-d , --dynamic

Allow to be dynamically re-calculated (or not)

false

-mem , --memory

Expectred memory usage (in megabytes)

0

-mi , --msgRateIn

Expected incoming messages per second

0

-mo , --msgRateOut

Expected outgoing messages per second

0

-n , --namespace

The namespace as tenant/namespace, for example my-tenant/my-ns. Must be specified together with -b/--bundle.

reset-namespace-bundle-quota

Reset the specifed namespace bundle's resource quota to a default value.

Usage
$ pulsar-admin resource-quotas reset-namespace-bundle-quota options
Options
Flag Description Default
-b , --bundle

A bundle of the form {start-boundary}_{end_boundary}.

-n , --namespace

The namespace as property/cluster/namespace, for example my-prop/my-cluster/my-ns.

schemas

Operations related to Schemas associated with Pulsar topics.

Usage
$ pulsar-admin schemas subcommand
Subcommands

upload

Upload the schema definition for a topic

Usage
$ pulsar-admin schemas upload persistent://tenant/namespace/topic options
Options
Flag Description Default
--filename

The path to the schema definition file. An example schema file is available under conf directory.

delete

Delete the schema definition associated with a topic

Usage
$ pulsar-admin schemas delete persistent://tenant/namespace/topic

get

Retrieve the schema definition assoicated with a topic (at a given version if version is supplied).

Usage
$ pulsar-admin schemas get persistent://tenant/namespace/topic options
Options
Flag Description Default
--version

The version of the schema definition to retrive for a topic.

pulsar-client

The pulsar-client tool

Usage
$ pulsar-client command
Commands
Options
Flag Description Default
--auth-params

Authentication parameters, for example key1:val1,key2:val2

--auth-plugin

Authentication plugin class name

--url

Broker URL to which to connect

pulsar://localhost:6650/

produce

Send a message or messages to a specific broker and topic

Usage
$ pulsar-client produce topic options
Options
Flag Description Default
-f , --files

Comma-separated file paths to send; either -m or -f must be specified

[]

-m , --messages

Comma-separated string of messages to send; either -m or -f must be specified

[]

-n , --num-produce

The number of times to send the message(s); the count of messages/files * num-produce should be below 1000

1

-r , --rate

Rate (in messages per second) at which to produce; a value 0 means to produce messages as fast as possible

0.0

consume

Consume messages from a specific broker and topic

Usage
$ pulsar-client consume topic options
Options
Flag Description Default
--hex

Display binary messages in hexadecimal format.

false

-n , --num-messages

Number of messages to consume, 0 means to consume forever.

0

-r , --rate

Rate (in messages per second) at which to produce; a value 0 means to produce messages as fast as possible

0.0

-s , --subscription-name

Subscription name

-t , --subscription-type

The type of the subscription. Possible values: Exclusive, Shared, Failover.

exclusive

pulsar-daemon

A wrapper around the pulsar tool that’s used to start and stop processes, such as ZooKeeper, bookies, and Pulsar brokers, in the background using nohup.

pulsar-daemon has a similar interface to the pulsar command but adds start and stop commands for various services. For a listing of those services, run pulsar-daemon to see the help output or see the documentation for the pulsar command.

Usage
$ pulsar-daemon command
Commands

start

Start a service in the background using nohup.

Usage
$ pulsar-daemon start service

stop

Stop a service that’s already been started using start.

Usage
$ pulsar-daemon stop service options
Options
Flag Description Default
-force

Stop the service forcefully if not stopped by normal shutdown.

false

pulsar-perf

A tool for performance testing a Pulsar broker.

Usage
$ pulsar-perf command
Commands
Environment variables

The table below lists the environment variables that you can use to configure the pulsar-perf tool.

Variable Description Default
PULSAR_LOG_CONF Log4j configuration file conf/log4j2.yaml
PULSAR_CLIENT_CONF Configuration file for the client conf/client.conf
PULSAR_EXTRA_OPTS Extra options to be passed to the JVM
PULSAR_EXTRA_CLASSPATH Extra paths for Pulsar's classpath

consume

Run a consumer

Usage
$ pulsar-perf consume options
Options
Flag Description Default
--auth_params

Authentication parameters in the form of key1:val1,key2:val2

--auth_plugin

Authentication plugin class name

-b , --batch-time-window

Batch messages in a window of the specified number of milliseconds

1

-z , --compression

Compress messages’ payload. Possible values are NONE, LZ4, or ZLIB.

--conf-file

Configuration file

-c , --max-connections

Max number of TCP connections to a single broker

0

-o , --max-outstanding

Max number of outstanding messages

1000

-m , --num-messages

Number of messages to publish in total. If set to 0, it will keep publishing.

0

-n , --num-producers

The number of producers (per topic)

1

-t , --num-topic

The number of topics

1

-f , --payload-file

Use payload from a file instead of an empty buffer

-r , --rate

Publish rate msg/s across topics

100

-u , --service-url

Pulsar service URL

-s , --size

Message size (in bytes)

1024

-i , --stats-interval-seconds

Statistics interval seconds. If 0, statistics will be disabled.

0

-time , --test-duration

Test duration in secs. If set to 0, it will keep publishing.

0

produce

Run a producer

Usage
$ pulsar-perf produce options
Options
Flag Description Default
--auth_params

Authentication parameters in the form of key1:val1,key2:val2

--auth_plugin

Authentication plugin class name

-b , --batch-time-window

Batch messages in a window of the specified number of milliseconds

1

-z , --compression

Compress messages’ payload. Possible values are NONE, LZ4, or ZLIB.

["--conf-file"]

Configuration file

-c , --max-connections

Max number of TCP connections to a single broker

0

-o , --max-outstanding

Max number of outstanding messages

1000

-m , --num-messages

Number of messages to publish in total. If set to 0, it will keep publishing.

0

-n , --num-producers

The number of producers (per topic)

1

-t , --num-topic

The number of topics

1

-f , --payload-file

Use payload from a file instead of an empty buffer

-r , --rate

Publish rate msg/s across topics

100

-u , --service-url

Pulsar service URL

-s , --size

Message size (in bytes)

1024

-i , --stats-interval-seconds

Statistics interval seconds. If 0, statistics will be disabled.

0

-time , --test-duration

Test duration in secs. If set to 0, it will keep publishing.

0

monitor-brokers

Continuously receive broker data and/or load reports

Usage
$ pulsar-perf monitor-brokers options
Options
Flag Description Default
--connect-string

A connection string for one or more ZooKeeper servers

simulation-client

Run a simulation server acting as a Pulsar client. Uses the client configuration specified in conf/client.conf.

Usage
$ pulsar-perf simulation-client

simulation-controller

Run a simulation controller to give commands to servers

Usage
$ pulsar-perf simulation-controller options
Options
Flag Description Default
--client-port

The port that the clients are listening on

0

--clients

Comma-separated list of client hostnames

--cluster

The cluster to test on

bookkeeper

A tool for managing BookKeeper.

Usage
$ bookkeeper command
Commands
Environment variables

The table below lists the environment variables that you can use to configure the bookkeeper tool.

Variable Description Default
BOOKIE_LOG_CONF Log4j configuration file conf/log4j2.yaml
BOOKIE_CONF BookKeeper configuration file conf/bk_server.conf
BOOKIE_EXTRA_OPTS Extra options to be passed to the JVM
BOOKIE_EXTRA_CLASSPATH Extra paths for BookKeeper's classpath
ENTRY_FORMATTER_CLASS The Java class used to format entries
BOOKIE_PID_DIR Folder where the BookKeeper server PID file should be stored
BOOKIE_STOP_TIMEOUT Wait time before forcefully killing the Bookie server instance if attempts to stop it are not successful

auto-recovery

Runs an auto-recovery service daemon

Usage
$ bookkeeper auto-recovery options
Options
Flag Description Default
-c , --conf

Configuration for the auto-recovery daemon

bookie

Starts up a BookKeeper server (aka bookie)

Usage
$ bookkeeper bookie options
Options
Flag Description Default
-c , --conf

Configuration for the bookie server

-readOnly

Force start a read-only bookie server

false

-withAutoRecovery

Start auto-recovery service bookie server

false

localbookie

Runs a test ensemble of N bookies locally

Usage
$ bookkeeper localbookie N

upgrade

Upgrade the bookie’s filesystem

Usage
$ bookkeeper upgrade options
Options
Flag Description Default
-c , --conf

Configuration for the bookie server

-c , --conf

Finalize the upgrade

-c , --conf

Roll the upgrade back

-u , --upgrade

Upgrade the bookie’s directories

shell

Run shell for admin commands. To see a full listing of those commands, run bookkeeper shell without an argument.

Usage
$ bookkeeper shell
Example
$ $ bookkeeper shell bookiesanity