Skip to main content
Apache Pulsar brokers are configured through the broker.conf or standalone.conf configuration files. This guide covers the most important configuration parameters for production deployments.

​
General Broker Settings

Core settings that define how the broker operates and communicates.
​
metadataStoreUrl
string
The metadata store URL for ZooKeeper or other metadata services.Examples:
  • zk:my-zk-1:2181,my-zk-2:2181,my-zk-3:2181
  • zk:my-zk-1:2181,my-zk-2:2181,my-zk-3:2181/my-chroot-path
​
clusterName
string
Name of the cluster to which this broker belongs. This is required for multi-cluster deployments and geo-replication.
​
brokerServicePort
integer
default:"6650"
Broker data port for Pulsar binary protocol connections.
​
webServicePort
integer
default:"8080"
Port to serve HTTP requests, including the admin API.
​
brokerServicePortTls
integer
Broker data port for TLS connections. TLS is disabled by default.
​
webServicePortTls
integer
Port to serve HTTPS requests. TLS is disabled by default.

​
Network Configuration

​
bindAddress
string
default:"0.0.0.0"
Hostname or IP address the service binds on.
​
advertisedAddress
string
Hostname or IP address the service advertises to the outside world. If not set, uses the canonical hostname.
​
advertisedListeners
string
Multiple advertised listeners for the broker in the format: <listener_name>:pulsar://<host>:<port>Multiple listeners should be separated with commas. Do not use with advertisedAddress and brokerServicePort.

​
Thread Pool Configuration

​
numIOThreads
integer
Number of threads to use for Netty IO.Default: 2 * Runtime.getRuntime().availableProcessors()
​
numOrderedExecutorThreads
integer
default:"8"
Number of threads for the ordered executor, used for ZooKeeper operations, namespace policies, and bundle splitting.
​
numHttpServerThreads
integer
Number of threads for HTTP request processing.Default: 2 * Runtime.getRuntime().availableProcessors()
​
numExecutorThreadPoolSize
integer
Thread pool size for broker operations like load/unload bundles and leader election.Default: Runtime.getRuntime().availableProcessors()

​
Topic and Namespace Management

​
allowAutoTopicCreation
boolean
default:"true"
Enable topic auto-creation when new producers or consumers connect.
​
allowAutoTopicCreationType
string
default:"non-partitioned"
Type of topic allowed for auto-creation.Options: partitioned | non-partitioned
​
defaultNumPartitions
integer
default:"1"
Number of partitions for auto-created partitioned topics.
​
allowAutoSubscriptionCreation
boolean
default:"true"
Enable subscription auto-creation when new consumers connect.
​
brokerDeleteInactiveTopicsEnabled
boolean
default:"true"
Enable deletion of inactive topics. Should be used with allowAutoTopicCreation.
​
brokerDeleteInactiveTopicsFrequencySeconds
integer
default:"60"
How often to check for inactive topics (in seconds).
​
brokerDeleteInactiveTopicsMode
string
default:"delete_when_no_subscriptions"
Mode for deleting inactive topics.Options:
  • delete_when_no_subscriptions - Delete topics with no subscriptions and no active producers
  • delete_when_subscriptions_caught_up - Delete topics where all subscriptions are caught up

​
Message Handling

​
maxMessageSize
integer
default:"5242880"
Maximum size of messages in bytes (5 MB default).
​
messageExpiryCheckIntervalInMinutes
integer
default:"5"
How frequently to check and purge expired messages.
​
maxUnackedMessagesPerConsumer
integer
default:"50000"
Maximum unacknowledged messages allowed for a consumer on a shared subscription. When reached, the broker stops sending messages until the consumer acknowledges.Set to 0 to disable the limit.
​
maxUnackedMessagesPerSubscription
integer
default:"200000"
Maximum unacknowledged messages allowed per shared subscription.Set to 0 to disable the limit.

​
Backlog Quotas

​
backlogQuotaCheckEnabled
boolean
default:"true"
Enable backlog quota checks and enforcement.
​
backlogQuotaCheckIntervalInSeconds
integer
default:"60"
How often to check for topics that have reached quota limits.
​
backlogQuotaDefaultLimitBytes
integer
default:"-1"
Default per-topic backlog quota limit in bytes. -1 means no limitation.
​
backlogQuotaDefaultRetentionPolicy
string
default:"producer_request_hold"
Default backlog quota retention policy.Options:
  • producer_request_hold - Hold producer send requests until resources are available
  • producer_exception - Throw exception to the producer
  • consumer_backlog_eviction - Evict oldest messages from slowest consumer

​
Metadata Store Settings

​
metadataStoreSessionTimeoutMillis
integer
default:"30000"
Metadata store session timeout in milliseconds.
​
metadataStoreOperationTimeoutSeconds
integer
default:"30"
Metadata store operation timeout in seconds.
​
metadataStoreBatchingEnabled
boolean
default:"true"
Enable metadata operations batching for better performance.
​
metadataStoreBatchingMaxDelayMillis
integer
default:"5"
Maximum delay for batching grouping in milliseconds.

​
BookKeeper Client Configuration

​
bookkeeperClientTimeoutInSeconds
integer
default:"30"
Timeout for BookKeeper add/read operations.
​
bookkeeperClientHealthCheckEnabled
boolean
default:"true"
Enable bookies health checks. Bookies with too many failures are quarantined.
​
bookkeeperClientRackawarePolicyEnabled
boolean
default:"true"
Enable rack-aware bookie selection. BookKeeper chooses bookies from different racks when forming ensembles.

​
Managed Ledger Configuration

​
managedLedgerDefaultEnsembleSize
integer
default:"1"
Number of bookies to use when creating a ledger (standalone default).
​
managedLedgerDefaultWriteQuorum
integer
default:"1"
Number of copies to store for each message (standalone default).
​
managedLedgerDefaultAckQuorum
integer
default:"1"
Number of guaranteed copies (acks to wait before write is complete).
​
managedLedgerMaxEntriesPerLedger
integer
default:"50000"
Maximum entries to append to a ledger before triggering a rollover.
​
managedLedgerMinLedgerRolloverTimeMinutes
integer
default:"10"
Minimum time between ledger rollovers for a topic.
​
managedLedgerMaxLedgerRolloverTimeMinutes
integer
default:"240"
Maximum time before forcing a ledger rollover for a topic.

​
Performance Tuning

​
dispatcherMaxReadBatchSize
integer
default:"100"
Maximum number of entries to read from BookKeeper per batch.
​
dispatcherMaxReadSizeBytes
integer
default:"5242880"
Maximum size in bytes of entries to read from BookKeeper (5 MB default).
​
dispatchThrottlingRatePerTopicInMsg
integer
default:"0"
Default message dispatch throttling limit per topic. 0 disables throttling.
​
dispatchThrottlingRatePerTopicInByte
integer
default:"0"
Default byte dispatch throttling limit per topic. 0 disables throttling.

​
Configuration Files

Pulsar provides two main configuration files:
  • conf/broker.conf - Configuration for production broker deployments
  • conf/standalone.conf - Configuration for standalone (single-node) deployments
To apply configuration changes:
  1. Edit the configuration file
  2. Restart the broker service
bin/pulsar-daemon stop broker
bin/pulsar-daemon start broker

​
Environment Variables

Many configuration parameters can be overridden using environment variables with the PULSAR_PREFIX_ prefix: 
export PULSAR_PREFIX_brokerServicePort=6650
export PULSAR_PREFIX_clusterName=my-cluster

Build docs developers (and LLMs) love

Get started for freeTalk to us