Skip to main content

Pulsar configuration

Pulsar configuration can be managed either via a series of configuration files contained in the conf directory of a Pulsar installation

BookKeeper

BookKeeper is a replicated log storage system that Pulsar uses for durable storage of all messages.

NameDescriptionDefault
bookiePortThe port on which the bookie server listens.3181
allowLoopbackWhether the bookie is allowed to use a loopback interface as its primary interface (i.e. the interface used to establish its identity). By default, loopback interfaces are not allowed as the primary interface. Using a loopback interface as the primary interface usually indicates a configuration error. For example, it’s fairly common in some VPS setups to not configure a hostname or to have the hostname resolve to 127.0.0.1. If this is the case, then all bookies in the cluster will establish their identities as 127.0.0.1:3181 and only one will be able to join the cluster. For VPSs configured like this, you should explicitly set the listening interface.false
listeningInterfaceThe network interface on which the bookie listens. If not set, the bookie will listen on all interfaces.eth0
journalDirectoryThe directory where Bookkeeper outputs its write-ahead log (WAL)data/bookkeeper/journal
ledgerDirectoriesThe directory where Bookkeeper outputs ledger snapshots. This could define multiple directories to store snapshots separated by comma, for example ledgerDirectories=/tmp/bk1-data,/tmp/bk2-data. Ideally, ledger dirs and the journal dir are each in a different device, which reduces the contention between random I/O and sequential write. It is possible to run with a single disk, but performance will be significantly lower.data/bookkeeper/ledgers
ledgerManagerTypeThe type of ledger manager used to manage how ledgers are stored, managed, and garbage collected. See BookKeeper Internals for more info.hierarchical
zkLedgersRootPathThe root ZooKeeper path used to store ledger metadata. This parameter is used by the ZooKeeper-based ledger manager as a root znode to store all ledgers./ledgers
ledgerStorageClassLedger storage implementation classorg.apache.bookkeeper.bookie.storage.ldb.DbLedgerStorage
entryLogFilePreallocationEnabledEnable or disable entry logger preallocationtrue
logSizeLimitMax file size of the entry logger, in bytes. A new entry log file will be created when the old one reaches the file size limitation.1073741824
minorCompactionThresholdThreshold of minor compaction. Entry log files whose remaining size percentage reaches below this threshold will be compacted in a minor compaction. If set to less than zero, the minor compaction is disabled.0.2
minorCompactionIntervalTime interval to run minor compaction, in seconds. If set to less than zero, the minor compaction is disabled.3600
majorCompactionThresholdThe threshold of major compaction. Entry log files whose remaining size percentage reaches below this threshold will be compacted in a major compaction. Those entry log files whose remaining size percentage is still higher than the threshold will never be compacted. If set to less than zero, the minor compaction is disabled.0.5
majorCompactionIntervalThe time interval to run major compaction, in seconds. If set to less than zero, the major compaction is disabled.86400
compactionMaxOutstandingRequestsSets the maximum number of entries that can be compacted without flushing. When compacting, the entries are written to the entrylog and the new offsets are cached in memory. Once the entrylog is flushed the index is updated with the new offsets. This parameter controls the number of entries added to the entrylog before a flush is forced. A higher value for this parameter means more memory will be used for offsets. Each offset consists of 3 longs. This parameter should not be modified unless you’re fully aware of the consequences.100000
compactionRateThe rate at which compaction will read entries, in adds per second.1000
isThrottleByBytesThrottle compaction by bytes or by entries.false
compactionRateByEntriesThe rate at which compaction will read entries, in adds per second.1000
compactionRateByBytesSet the rate at which compaction reads entries. The unit is bytes added per second.1000000
journalMaxSizeMBMax file size of journal file, in megabytes. A new journal file will be created when the old one reaches the file size limitation.2048
journalMaxBackupsThe max number of old journal files to keep. Keeping a number of old journal files would help data recovery in special cases.5
journalPreAllocSizeMBHow space to pre-allocate at a time in the journal.16
journalWriteBufferSizeKBThe of the write buffers used for the journal.64
journalRemoveFromPageCacheWhether pages should be removed from the page cache after force write.true
journalAdaptiveGroupWritesWhether to group journal force writes, which optimizes group commit for higher throughput.true
journalMaxGroupWaitMSecThe maximum latency to impose on a journal write to achieve grouping.1
journalAlignmentSizeAll the journal writes and commits should be aligned to given size4096
journalBufferedWritesThresholdMaximum writes to buffer to achieve grouping524288
journalFlushWhenQueueEmptyIf we should flush the journal when journal queue is emptyfalse
numJournalCallbackThreadsThe number of threads that should handle journal callbacks8
rereplicationEntryBatchSizeThe number of max entries to keep in fragment for re-replication5000
gcWaitTimeHow long the interval to trigger next garbage collection, in milliseconds. Since garbage collection is running in background, too frequent gc will heart performance. It is better to give a higher number of gc interval if there is enough disk capacity.900000
gcOverreplicatedLedgerWaitTimeHow long the interval to trigger next garbage collection of overreplicated ledgers, in milliseconds. This should not be run very frequently since we read the metadata for all the ledgers on the bookie from zk.86400000
flushIntervalHow long the interval to flush ledger index pages to disk, in milliseconds. Flushing index files will introduce much random disk I/O. If separating journal dir and ledger dirs each on different devices, flushing would not affect performance. But if putting journal dir and ledger dirs on same device, performance degrade significantly on too frequent flushing. You can consider increment flush interval to get better performance, but you need to pay more time on bookie server restart after failure.60000
bookieDeathWatchIntervalInterval to watch whether bookie is dead or not, in milliseconds1000
zkServersA list of one of more servers on which zookeeper is running. The server list can be comma separated values, for example: zkServers=zk1:2181,zk2:2181,zk3:2181.localhost:2181
zkTimeoutZooKeeper client session timeout in milliseconds Bookie server will exit if it received SESSION_EXPIRED because it was partitioned off from ZooKeeper for more than the session timeout JVM garbage collection, disk I/O will cause SESSION_EXPIRED. Increment this value could help avoiding this issue30000
serverTcpNoDelayThis settings is used to enabled/disabled Nagle’s algorithm, which is a means of improving the efficiency of TCP/IP networks by reducing the number of packets that need to be sent over the network. If you are sending many small messages, such that more than one can fit in a single IP packet, setting server.tcpnodelay to false to enable Nagle algorithm can provide better performance.true
openFileLimitMax number of ledger index files could be opened in bookie server If number of ledger index files reaches this limitation, bookie server started to swap some ledgers from memory to disk. Too frequent swap will affect performance. You can tune this number to gain performance according your requirements.0
pageSizeSize of a index page in ledger cache, in bytes A larger index page can improve performance writing page to disk, which is efficient when you have small number of ledgers and these ledgers have similar number of entries. If you have large number of ledgers and each ledger has fewer entries, smaller index page would improve memory usage.8192
pageLimitHow many index pages provided in ledger cache If number of index pages reaches this limitation, bookie server starts to swap some ledgers from memory to disk. You can increment this value when you found swap became more frequent. But make sure pageLimit*pageSize should not more than JVM max memory limitation, otherwise you would got OutOfMemoryException. In general, incrementing pageLimit, using smaller index page would gain better performance in lager number of ledgers with fewer entries case If pageLimit is -1, bookie server will use 1/3 of JVM memory to compute the limitation of number of index pages.0
readOnlyModeEnabledIf all ledger directories configured are full, then support only read requests for clients. If "readOnlyModeEnabled=true" then on all ledger disks full, bookie will be converted to read-only mode and serve only read requests. Otherwise the bookie will be shutdown. By default this will be disabled.true
diskUsageThresholdFor each ledger dir, maximum disk space which can be used. Default is 0.95f. i.e. 95% of disk can be used at most after which nothing will be written to that partition. If all ledger dir partitions are full, then bookie will turn to readonly mode if ‘readOnlyModeEnabled=true’ is set, else it will shutdown. Valid values should be in between 0 and 1 (exclusive).0.95
diskCheckIntervalDisk check interval in milli seconds, interval to check the ledger dirs usage.10000
auditorPeriodicCheckIntervalInterval at which the auditor will do a check of all ledgers in the cluster. By default this runs once a week. The interval is set in seconds. To disable the periodic check completely, set this to 0. Note that periodic checking will put extra load on the cluster, so it should not be run more frequently than once a day.604800
auditorPeriodicBookieCheckIntervalThe interval between auditor bookie checks. The auditor bookie check, checks ledger metadata to see which bookies should contain entries for each ledger. If a bookie which should contain entries is unavailable, thea the ledger containing that entry is marked for recovery. Setting this to 0 disabled the periodic check. Bookie checks will still run when a bookie fails. The interval is specified in seconds.86400
numAddWorkerThreadsnumber of threads that should handle write requests. if zero, the writes would be handled by netty threads directly.0
numReadWorkerThreadsnumber of threads that should handle read requests. if zero, the reads would be handled by netty threads directly.8
maxPendingReadRequestsPerThreadIf read workers threads are enabled, limit the number of pending requests, to avoid the executor queue to grow indefinitely.2500
readBufferSizeBytesThe number of bytes we should use as capacity for BufferedReadChannel.4096
writeBufferSizeBytesThe number of bytes used as capacity for the write buffer65536
useHostNameAsBookieIDWhether the bookie should use its hostname to register with the coordination service (e.g.: zookeeper service). When false, bookie will use its ipaddress for the registration.false
statsProviderClassorg.apache.bookkeeper.stats.prometheus.PrometheusMetricsProvider
prometheusStatsHttpPort8000
dbStorage_writeCacheMaxSizeMbSize of Write Cache. Memory is allocated from JVM direct memory. Write cache is used to buffer entries before flushing into the entry log For good performance, it should be big enough to hold a substantial amount of entries in the flush interval.25% of direct memory
dbStorage_readAheadCacheMaxSizeMbSize of Read cache. Memory is allocated from JVM direct memory. This read cache is pre-filled doing read-ahead whenever a cache miss happens256
dbStorage_readAheadCacheBatchSizeHow many entries to pre-fill in cache after a read cache miss1000
dbStorage_rocksDB_blockCacheSizeSize of RocksDB block-cache. For best performance, this cache should be big enough to hold a significant portion of the index database which can reach ~2GB in some cases268435456
dbStorage_rocksDB_writeBufferSizeMB64
dbStorage_rocksDB_sstSizeInMB64
dbStorage_rocksDB_blockSize65536
dbStorage_rocksDB_bloomFilterBitsPerKey10
dbStorage_rocksDB_numLevels-1
dbStorage_rocksDB_numFilesInLevel04
dbStorage_rocksDB_maxSizeInLevel1MB256

Broker

Pulsar brokers are responsible for handling incoming messages from producers, dispatching messages to consumers, replicating data between clusters, and more.

NameDescriptionDefault
enablePersistentTopicsWhether persistent topics are enabled on the brokertrue
enableNonPersistentTopicsWhether non-persistent topics are enabled on the brokertrue
functionsWorkerEnabledWhether the Pulsar Functions worker service is enabled in the brokerfalse
zookeeperServersZookeeper quorum connection string
configurationStoreServersConfiguration store connection string (as a comma-separated list)
brokerServicePortBroker data port6650
brokerServicePortTlsBroker data port for TLS6651
webServicePortPort to use to server HTTP request8080
webServicePortTlsPort to use to server HTTPS request8443
webSocketServiceEnabledEnable the WebSocket API service in brokerfalse
bindAddressHostname or IP address the service binds on, default is 0.0.0.0.0.0.0.0
advertisedAddressHostname or IP address the service advertises to the outside world. If not set, the value of InetAddress.getLocalHost().getHostName() is used.
clusterNameName of the cluster to which this broker belongs to
brokerDeduplicationEnabledSets the default behavior for message deduplication in the broker. If enabled, the broker will reject messages that were already stored in the topic. This setting can be overridden on a per-namespace basis.false
brokerDeduplicationMaxNumberOfProducersThe maximum number of producers for which information will be stored for deduplication purposes.10000
brokerDeduplicationEntriesIntervalThe number of entries after which a deduplication informational snapshot is taken. A larger interval will lead to fewer snapshots being taken, though this would also lengthen the topic recovery time (the time required for entries published after the snapshot to be replayed).1000
brokerDeduplicationProducerInactivityTimeoutMinutesThe time of inactivity (in minutes) after which the broker will discard deduplication information related to a disconnected producer.360
zooKeeperSessionTimeoutMillisZookeeper session timeout in milliseconds30000
brokerShutdownTimeoutMsTime to wait for broker graceful shutdown. After this time elapses, the process will be killed60000
backlogQuotaCheckEnabledEnable backlog quota check. Enforces action on topic when the quota is reachedtrue
backlogQuotaCheckIntervalInSecondsHow often to check for topics that have reached the quota60
backlogQuotaDefaultLimitGBDefault per-topic backlog quota limit10
brokerDeleteInactiveTopicsEnabledEnable the deletion of inactive topics. If topics are not consumed for some while, these inactive topics might be cleaned up. Deleting inactive topics is enabled by default. The default period is 1 minute.true
brokerDeleteInactiveTopicsFrequencySecondsHow often to check for inactive topics60
messageExpiryCheckIntervalInMinutesHow frequently to proactively check and purge expired messages5
brokerServiceCompactionMonitorIntervalInSecondsInterval between checks to see if topics with compaction policies need to be compacted60
activeConsumerFailoverDelayTimeMillisHow long to delay rewinding cursor and dispatching messages when active consumer is changed.1000
clientLibraryVersionCheckEnabledEnable check for minimum allowed client library versionfalse
clientLibraryVersionCheckAllowUnversionedAllow client libraries with no version informationtrue
statusFilePathPath for the file used to determine the rotation status for the broker when responding to service discovery health checks
preferLaterVersionsIf true, (and ModularLoadManagerImpl is being used), the load manager will attempt to use only brokers running the latest software version (to minimize impact to bundles)false
tlsEnabledEnable TLSfalse
tlsCertificateFilePathPath for the TLS certificate file
tlsKeyFilePathPath for the TLS private key file
tlsTrustCertsFilePathPath for the trusted TLS certificate file
tlsAllowInsecureConnectionAccept untrusted TLS certificate from clientfalse
tlsProtocolsSpecify the tls protocols the broker will use to negotiate during TLS Handshake. Multiple values can be specified, separated by commas. Example:- TLSv1.2, TLSv1.1, TLSv1
tlsCiphersSpecify the tls cipher the broker will use to negotiate during TLS Handshake. Multiple values can be specified, separated by commas. Example:- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
tokenSecretKeyConfigure the secret key to be used to validate auth tokens. The key can be specified like: tokenSecretKey=data:base64,xxxxxxxxx or tokenSecretKey=file:///my/secret.key
tokenPublicKeyConfigure the public key to be used to validate auth tokens. The key can be specified like: tokenPublicKey=data:base64,xxxxxxxxx or tokenPublicKey=file:///my/secret.key
maxUnackedMessagesPerConsumerMax number of unacknowledged messages allowed to receive messages by a consumer on a shared subscription. Broker will stop sending messages to consumer once, this limit reaches until consumer starts acknowledging messages back. Using a value of 0, is disabling unackeMessage limit check and consumer can receive messages without any restriction50000
maxUnackedMessagesPerSubscriptionMax number of unacknowledged messages allowed per shared subscription. Broker will stop dispatching messages to all consumers of the subscription once this limit reaches until consumer starts acknowledging messages back and unack count reaches to limit/2. Using a value of 0, is disabling unackedMessage-limit check and dispatcher can dispatch messages without any restriction200000
subscriptionRedeliveryTrackerEnabledEnable subscription message redelivery trackertrue
maxConcurrentLookupRequestMax number of concurrent lookup request broker allows to throttle heavy incoming lookup traffic50000
maxConcurrentTopicLoadRequestMax number of concurrent topic loading request broker allows to control number of zk-operations5000
authenticationEnabledEnable authenticationfalse
authenticationProvidersAuthentication provider name list, which is comma separated list of class names
authorizationEnabledEnforce authorizationfalse
superUserRolesRole names that are treated as "super-user", meaning they will be able to do all admin operations and publish/consume from all topics
brokerClientAuthenticationPluginAuthentication settings of the broker itself. Used when the broker connects to other brokers, either in same or other clusters
brokerClientAuthenticationParameters
athenzDomainNamesSupported Athenz provider domain names(comma separated) for authentication
bookkeeperClientAuthenticationPluginAuthentication plugin to use when connecting to bookies
bookkeeperClientAuthenticationParametersNameBookKeeper auth plugin implementation specifics parameters name and values
bookkeeperClientAuthenticationParameters
bookkeeperClientTimeoutInSecondsTimeout for BK add / read operations30
bookkeeperClientSpeculativeReadTimeoutInMillisSpeculative reads are initiated if a read request doesn’t complete within a certain time Using a value of 0, is disabling the speculative reads0
bookkeeperClientHealthCheckEnabledEnable bookies health check. Bookies that have more than the configured number of failure within the interval will be quarantined for some time. During this period, new ledgers won’t be created on these bookiestrue
bookkeeperClientHealthCheckIntervalSeconds60
bookkeeperClientHealthCheckErrorThresholdPerInterval5
bookkeeperClientHealthCheckQuarantineTimeInSeconds1800
bookkeeperClientRackawarePolicyEnabledEnable rack-aware bookie selection policy. BK will chose bookies from different racks when forming a new bookie ensembletrue
bookkeeperClientRegionawarePolicyEnabledEnable region-aware bookie selection policy. BK will chose bookies from different regions and racks when forming a new bookie ensemble. If enabled, the value of bookkeeperClientRackawarePolicyEnabled is ignoredfalse
bookkeeperClientReorderReadSequenceEnabledEnable/disable reordering read sequence on reading entries.false
bookkeeperClientIsolationGroupsEnable bookie isolation by specifying a list of bookie groups to choose from. Any bookie outside the specified groups will not be used by the broker
bookkeeperEnableStickyReadsEnable/disable having read operations for a ledger to be sticky to a single bookie. If this flag is enabled, the client will use one single bookie (by preference) to read all entries for a ledger.true
managedLedgerDefaultEnsembleSizeNumber of bookies to use when creating a ledger2
managedLedgerDefaultWriteQuorumNumber of copies to store for each message2
managedLedgerDefaultAckQuorumNumber of guaranteed copies (acks to wait before write is complete)2
managedLedgerCacheSizeMBAmount of memory to use for caching data payload in managed ledger. This memory is allocated from JVM direct memory and it’s shared across all the topics running in the same broker. By default, uses 1/5th of available direct memory
managedLedgerCacheEvictionWatermarkThreshold to which bring down the cache level when eviction is triggered0.9
managedLedgerDefaultMarkDeleteRateLimitRate limit the amount of writes per second generated by consumer acking the messages1.0
managedLedgerMaxEntriesPerLedgerThe max number of entries to append to a ledger before triggering a rollover. A ledger rollover is triggered after the min rollover time has passed and one of the following conditions is true:
  • The max rollover time has been reached
  • The max entries have been written to the ledger
  • The max ledger size has been written to the ledger
50000
managedLedgerMinLedgerRolloverTimeMinutesMinimum time between ledger rollover for a topic10
managedLedgerMaxLedgerRolloverTimeMinutesMaximum time before forcing a ledger rollover for a topic240
managedLedgerCursorMaxEntriesPerLedgerMax number of entries to append to a cursor ledger50000
managedLedgerCursorRolloverTimeInSecondsMax time before triggering a rollover on a cursor ledger14400
managedLedgerMaxUnackedRangesToPersistMax number of "acknowledgment holes" that are going to be persistently stored. When acknowledging out of order, a consumer will leave holes that are supposed to be quickly filled by acking all the messages. The information of which messages are acknowledged is persisted by compressing in "ranges" of messages that were acknowledged. After the max number of ranges is reached, the information will only be tracked in memory and messages will be redelivered in case of crashes.1000
autoSkipNonRecoverableDataSkip reading non-recoverable/unreadable data-ledger under managed-ledger’s list.It helps when data-ledgers gets corrupted at bookkeeper and managed-cursor is stuck at that ledger.false
loadBalancerEnabledEnable load balancertrue
loadBalancerPlacementStrategyStrategy to assign a new bundle weightedRandomSelection
loadBalancerReportUpdateThresholdPercentagePercentage of change to trigger load report update10
loadBalancerReportUpdateMaxIntervalMinutesmaximum interval to update load report15
loadBalancerHostUsageCheckIntervalMinutesFrequency of report to collect1
loadBalancerSheddingIntervalMinutesLoad shedding interval. Broker periodically checks whether some traffic should be offload from some over-loaded broker to other under-loaded brokers30
loadBalancerSheddingGracePeriodMinutesPrevent the same topics to be shed and moved to other broker more than once within this timeframe30
loadBalancerBrokerMaxTopicsUsage threshold to allocate max number of topics to broker50000
loadBalancerBrokerUnderloadedThresholdPercentageUsage threshold to determine a broker as under-loaded1
loadBalancerBrokerOverloadedThresholdPercentageUsage threshold to determine a broker as over-loaded85
loadBalancerResourceQuotaUpdateIntervalMinutesInterval to update namespace bundle resource quota15
loadBalancerBrokerComfortLoadLevelPercentageUsage threshold to determine a broker is having just right level of load65
loadBalancerAutoBundleSplitEnabledenable/disable namespace bundle auto splitfalse
loadBalancerNamespaceBundleMaxTopicsmaximum topics in a bundle, otherwise bundle split will be triggered1000
loadBalancerNamespaceBundleMaxSessionsmaximum sessions (producers + consumers) in a bundle, otherwise bundle split will be triggered1000
loadBalancerNamespaceBundleMaxMsgRatemaximum msgRate (in + out) in a bundle, otherwise bundle split will be triggered1000
loadBalancerNamespaceBundleMaxBandwidthMbytesmaximum bandwidth (in + out) in a bundle, otherwise bundle split will be triggered100
loadBalancerNamespaceMaximumBundlesmaximum number of bundles in a namespace128
replicationMetricsEnabledEnable replication metricstrue
replicationConnectionsPerBrokerMax number of connections to open for each broker in a remote cluster More connections host-to-host lead to better throughput over high-latency links.16
replicationProducerQueueSizeReplicator producer queue size1000
replicatorPrefixReplicator prefix used for replicator producer name and cursor name pulsar.repl
replicationTlsEnabledEnable TLS when talking with other clusters to replicate messagesfalse
defaultRetentionTimeInMinutesDefault message retention time. 0 means retention is disabled. -1 means data is not removed by time quota
defaultRetentionSizeInMBDefault retention size. 0 means retention is disabled. -1 means data is not removed by size quota0
keepAliveIntervalSecondsHow often to check whether the connections are still alive30
brokerServicePurgeInactiveFrequencyInSecondsHow often broker checks for inactive topics to be deleted (topics with no subscriptions and no one connected)60
loadManagerClassNameName of load manager to useorg.apache.pulsar.broker.loadbalance.impl.SimpleLoadManagerImpl
managedLedgerOffloadDriverDriver to use to offload old data to long term storage (Possible values: S3)
managedLedgerOffloadMaxThreadsMaximum number of thread pool threads for ledger offloading2
s3ManagedLedgerOffloadRegionFor Amazon S3 ledger offload, AWS region
s3ManagedLedgerOffloadBucketFor Amazon S3 ledger offload, Bucket to place offloaded ledger into
s3ManagedLedgerOffloadServiceEndpointFor Amazon S3 ledger offload, Alternative endpoint to connect to (useful for testing)
s3ManagedLedgerOffloadMaxBlockSizeInBytesFor Amazon S3 ledger offload, Max block size in bytes. (64MB by default, 5MB minimum)67108864
s3ManagedLedgerOffloadReadBufferSizeInBytesFor Amazon S3 ledger offload, Read buffer size in bytes (1MB by default)1048576

Client

The pulsar-client CLI tool can be used to publish messages to Pulsar and consume messages from Pulsar topics. This tool can be used in lieu of a client library.

NameDescriptionDefault
webServiceUrlThe web URL for the cluster.http://localhost:8080/
brokerServiceUrlThe Pulsar protocol URL for the cluster.pulsar://localhost:6650/
authPluginThe authentication plugin.
authParamsThe authentication parameters for the cluster, as a comma-separated string.
useTlsWhether or not TLS authentication will be enforced in the cluster.false
tlsAllowInsecureConnection
tlsTrustCertsFilePath

Service discovery

NameDescriptionDefault
zookeeperServersZookeeper quorum connection string (comma-separated)
configurationStoreServersConfiguration store connection string (as a comma-separated list)
zookeeperSessionTimeoutMsZooKeeper session timeout30000
servicePortPort to use to server binary-proto request6650
servicePortTlsPort to use to server binary-proto-tls request6651
webServicePortPort that discovery service listen on8080
webServicePortTlsPort to use to server HTTPS request8443
bindOnLocalhostControl whether to bind directly on localhost rather than on normal hostnamefalse
authenticationEnabledEnable authenticationfalse
authenticationProvidersAuthentication provider name list, which is comma separated list of class names (comma-separated)
authorizationEnabledEnforce authorizationfalse
superUserRolesRole names that are treated as "super-user", meaning they will be able to do all admin operations and publish/consume from all topics (comma-separated)
tlsEnabledEnable TLSfalse
tlsCertificateFilePathPath for the TLS certificate file
tlsKeyFilePathPath for the TLS private key file

Log4j

NameDefault
pulsar.root.loggerWARN,CONSOLE
pulsar.log.dirlogs
pulsar.log.filepulsar.log
log4j.rootLogger${pulsar.root.logger}
log4j.appender.CONSOLEorg.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.ThresholdDEBUG
log4j.appender.CONSOLE.layoutorg.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern%d{ISO8601} - %-5p - [%t:%C{1}@%L] - %m%n
log4j.appender.ROLLINGFILEorg.apache.log4j.DailyRollingFileAppender
log4j.appender.ROLLINGFILE.ThresholdDEBUG
log4j.appender.ROLLINGFILE.Filepulsar.log.dir/{pulsar.log.dir}/{pulsar.log.file}
log4j.appender.ROLLINGFILE.layoutorg.apache.log4j.PatternLayout
log4j.appender.ROLLINGFILE.layout.ConversionPattern%d{ISO8601} - %-5p [%t:%C{1}@%L] - %m%n
log4j.appender.TRACEFILEorg.apache.log4j.FileAppender
log4j.appender.TRACEFILE.ThresholdTRACE
log4j.appender.TRACEFILE.Filepulsar-trace.log
log4j.appender.TRACEFILE.layoutorg.apache.log4j.PatternLayout
log4j.appender.TRACEFILE.layout.ConversionPattern%d{ISO8601} - %-5p [%t:%C{1}@%L][%x] - %m%n

Log4j shell

NameDefault
bookkeeper.root.loggerERROR,CONSOLE
log4j.rootLogger${bookkeeper.root.logger}
log4j.appender.CONSOLEorg.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.ThresholdDEBUG
log4j.appender.CONSOLE.layoutorg.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern%d{ABSOLUTE} %-5p %m%n
log4j.logger.org.apache.zookeeperERROR
log4j.logger.org.apache.bookkeeperERROR
log4j.logger.org.apache.bookkeeper.bookie.BookieShellINFO

Standalone

NameDescriptionDefault
zookeeperServersThe quorum connection string for local ZooKeeper
configurationStoreServersConfiguration store connection string (as a comma-separated list)
brokerServicePortThe port on which the standalone broker listens for connections6650
webServicePortThe port used by the standalone broker for HTTP requests8080
bindAddressThe hostname or IP address on which the standalone service binds0.0.0.0
advertisedAddressThe hostname or IP address that the standalone service advertises to the outside world. If not set, the value of InetAddress.getLocalHost().getHostName() is used.
clusterNameThe name of the cluster that this broker belongs to.standalone
zooKeeperSessionTimeoutMillisThe ZooKeeper session timeout, in milliseconds.30000
brokerShutdownTimeoutMsThe time to wait for graceful broker shutdown. After this time elapses, the process will be killed.60000
backlogQuotaCheckEnabledEnable the backlog quota check, which enforces a specified action when the quota is reached.true
backlogQuotaCheckIntervalInSecondsHow often to check for topics that have reached the backlog quota.60
backlogQuotaDefaultLimitGBThe default per-topic backlog quota limit.10
brokerDeleteInactiveTopicsEnabledEnable the deletion of inactive topics. If topics are not consumed for some while, these inactive topics might be cleaned up. Deleting inactive topics is enabled by default. The default period is 1 minute.true
brokerDeleteInactiveTopicsFrequencySecondsHow often to check for inactive topics, in seconds.60
messageExpiryCheckIntervalInMinutesHow often to proactively check and purged expired messages.5
activeConsumerFailoverDelayTimeMillisHow long to delay rewinding cursor and dispatching messages when active consumer is changed.1000
clientLibraryVersionCheckEnabledEnable checks for minimum allowed client library version.false
clientLibraryVersionCheckAllowUnversionedAllow client libraries with no version informationtrue
statusFilePathThe path for the file used to determine the rotation status for the broker when responding to service discovery health checks/usr/local/apache/htdocs
maxUnackedMessagesPerConsumerThe maximum number of unacknowledged messages allowed to be received by consumers on a shared subscription. The broker will stop sending messages to a consumer once this limit is reached or until the consumer begins acknowledging messages. A value of 0 disables the unacked message limit check and thus allows consumers to receive messages without any restrictions.50000
maxUnackedMessagesPerSubscriptionThe same as above, except per subscription rather than per consumer.200000
authenticationEnabledEnable authentication for the broker.false
authenticationProvidersA comma-separated list of class names for authentication providers.false
authorizationEnabledEnforce authorization in brokers.false
superUserRolesRole names that are treated as "superusers." Superusers are authorized to perform all admin tasks.
brokerClientAuthenticationPluginThe authentication settings of the broker itself. Used when the broker connects to other brokers either in the same cluster or from other clusters.
brokerClientAuthenticationParametersThe parameters that go along with the plugin specified using brokerClientAuthenticationPlugin.
athenzDomainNamesSupported Athenz authentication provider domain names as a comma-separated list.
bookkeeperClientAuthenticationPluginAuthentication plugin to be used when connecting to bookies (BookKeeper servers).
bookkeeperClientAuthenticationParametersNameBookKeeper authentication plugin implementation parameters and values.
bookkeeperClientAuthenticationParametersParameters associated with the bookkeeperClientAuthenticationParametersName
bookkeeperClientTimeoutInSecondsTimeout for BookKeeper add and read operations.30
bookkeeperClientSpeculativeReadTimeoutInMillisSpeculative reads are initiated if a read request doesn’t complete within a certain time. A value of 0 disables speculative reads.0
bookkeeperClientHealthCheckEnabledEnable bookie health checks.true
bookkeeperClientHealthCheckIntervalSecondsThe time interval, in seconds, at which health checks are performed. New ledgers are not created during health checks.60
bookkeeperClientHealthCheckErrorThresholdPerIntervalError threshold for health checks.5
bookkeeperClientHealthCheckQuarantineTimeInSecondsIf bookies have more than the allowed number of failures within the time interval specified by bookkeeperClientHealthCheckIntervalSeconds1800
bookkeeperClientRackawarePolicyEnabledtrue
bookkeeperClientRegionawarePolicyEnabledfalse
bookkeeperClientReorderReadSequenceEnabledfalse
bookkeeperClientIsolationGroups
managedLedgerDefaultEnsembleSize1
managedLedgerDefaultWriteQuorum1
managedLedgerDefaultAckQuorum1
managedLedgerCacheSizeMB1024
managedLedgerCacheEvictionWatermark0.9
managedLedgerDefaultMarkDeleteRateLimit0.1
managedLedgerMaxEntriesPerLedger50000
managedLedgerMinLedgerRolloverTimeMinutes10
managedLedgerMaxLedgerRolloverTimeMinutes240
managedLedgerCursorMaxEntriesPerLedger50000
managedLedgerCursorRolloverTimeInSeconds14400
autoSkipNonRecoverableDatafalse
loadBalancerEnabledfalse
loadBalancerPlacementStrategyweightedRandomSelection
loadBalancerReportUpdateThresholdPercentage10
loadBalancerReportUpdateMaxIntervalMinutes15
loadBalancerHostUsageCheckIntervalMinutes1
loadBalancerSheddingIntervalMinutes30
loadBalancerSheddingGracePeriodMinutes30
loadBalancerBrokerMaxTopics50000
loadBalancerBrokerUnderloadedThresholdPercentage1
loadBalancerBrokerOverloadedThresholdPercentage85
loadBalancerResourceQuotaUpdateIntervalMinutes15
loadBalancerBrokerComfortLoadLevelPercentage65
loadBalancerAutoBundleSplitEnabledfalse
loadBalancerNamespaceBundleMaxTopics1000
loadBalancerNamespaceBundleMaxSessions1000
loadBalancerNamespaceBundleMaxMsgRate1000
loadBalancerNamespaceBundleMaxBandwidthMbytes100
loadBalancerNamespaceMaximumBundles128
replicationMetricsEnabledtrue
replicationConnectionsPerBroker16
replicationProducerQueueSize1000
defaultRetentionTimeInMinutes0
defaultRetentionSizeInMB0
keepAliveIntervalSeconds30
brokerServicePurgeInactiveFrequencyInSeconds60

WebSocket

NameDescriptionDefault
configurationStoreServers
zooKeeperSessionTimeoutMillis30000
serviceUrl
serviceUrlTls
brokerServiceUrl
brokerServiceUrlTls
webServicePort8080
webServicePortTls8443
bindAddress0.0.0.0
clusterName
authenticationEnabledfalse
authenticationProviders
authorizationEnabledfalse
superUserRoles
brokerClientAuthenticationPlugin
brokerClientAuthenticationParameters
tlsEnabledfalse
tlsAllowInsecureConnectionfalse
tlsCertificateFilePath
tlsKeyFilePath
tlsTrustCertsFilePath

Pulsar proxy

The Pulsar proxy can be configured in the conf/proxy.conf file.

NameDescriptionDefault
zookeeperServersThe ZooKeeper quorum connection string (as a comma-separated list)
configurationStoreServersConfiguration store connection string (as a comma-separated list)
zookeeperSessionTimeoutMsZooKeeper session timeout (in milliseconds)30000
servicePortThe port to use for server binary Protobuf requests6650
servicePortTlsThe port to use to server binary Protobuf TLS requests6651
statusFilePathPath for the file used to determine the rotation status for the proxy instance when responding to service discovery health checks
authenticationEnabledWhether authentication is enabled for the Pulsar proxyfalse
authenticationProvidersAuthentication provider name list (a comma-separated list of class names)
authorizationEnabledWhether authorization is enforced by the Pulsar proxyfalse
authorizationProviderAuthorization provider as a fully qualified class nameorg.apache.pulsar.broker.authorization.PulsarAuthorizationProvider
brokerClientAuthenticationPluginThe authentication plugin used by the Pulsar proxy to authenticate with Pulsar brokers
brokerClientAuthenticationParametersThe authentication parameters used by the Pulsar proxy to authenticate with Pulsar brokers
brokerClientTrustCertsFilePathThe path to trusted certificates used by the Pulsar proxy to authenticate with Pulsar brokers
superUserRolesRole names that are treated as "super-users," meaning that they will be able to perform all admin
forwardAuthorizationCredentialsWhether client authorization credentials are forwarded to the broker for re-authorization. Authentication must be enabled via authenticationEnabled=true for this to take effect.false
maxConcurrentInboundConnectionsMax concurrent inbound connections. The proxy will reject requests beyond that.10000
maxConcurrentLookupRequestsMax concurrent outbound connections. The proxy will error out requests beyond that.50000
tlsEnabledInProxyWhether TLS is enabled for the proxyfalse
tlsEnabledWithBrokerWhether TLS is enabled when communicating with Pulsar brokersfalse
tlsCertificateFilePathPath for the TLS certificate file
tlsKeyFilePathPath for the TLS private key file
tlsTrustCertsFilePathPath for the trusted TLS certificate pem file
tlsHostnameVerificationEnabledWhether the hostname is validated when the proxy creates a TLS connection with brokersfalse
tlsRequireTrustedClientCertOnConnectWhether client certificates are required for TLS. Connections are rejected if the client certificate isn’t trusted.false
tlsProtocolsSpecify the tls protocols the broker will use to negotiate during TLS Handshake. Multiple values can be specified, separated by commas. Example:- TLSv1.2, TLSv1.1, TLSv1
tlsCiphersSpecify the tls cipher the broker will use to negotiate during TLS Handshake. Multiple values can be specified, separated by commas. Example:- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
tokenSecretKeyConfigure the secret key to be used to validate auth tokens. The key can be specified like: tokenSecretKey=data:base64,xxxxxxxxx or tokenSecretKey=file:///my/secret.key
tokenPublicKeyConfigure the public key to be used to validate auth tokens. The key can be specified like: tokenPublicKey=data:base64,xxxxxxxxx or tokenPublicKey=file:///my/secret.key

ZooKeeper

ZooKeeper handles a broad range of essential configuration- and coordination-related tasks for Pulsar. The default configuration file for ZooKeeper is in the conf/zookeeper.conf file in your Pulsar installation. The following parameters are available:

NameDescriptionDefault
tickTimeThe tick is the basic unit of time in ZooKeeper, measured in milliseconds and used to regulate things like heartbeats and timeouts. tickTime is the length of a single tick.2000
initLimitThe maximum time, in ticks, that the leader ZooKeeper server allows follower ZooKeeper servers to successfully connect and sync. The tick time is set in milliseconds using the tickTime parameter.10
syncLimitThe maximum time, in ticks, that a follower ZooKeeper server is allowed to sync with other ZooKeeper servers. The tick time is set in milliseconds using the tickTime parameter.5
dataDirThe location where ZooKeeper will store in-memory database snapshots as well as the transaction log of updates to the database.data/zookeeper
clientPortThe port on which the ZooKeeper server will listen for connections.2181
autopurge.snapRetainCountIn ZooKeeper, auto purge determines how many recent snapshots of the database stored in dataDir to retain within the time interval specified by autopurge.purgeInterval (while deleting the rest).3
autopurge.purgeIntervalThe time interval, in hours, by which the ZooKeeper database purge task is triggered. Setting to a non-zero number will enable auto purge; setting to 0 will disable. Read this guide before enabling auto purge.1
maxClientCnxnsThe maximum number of client connections. Increase this if you need to handle more ZooKeeper clients.60

In addition to the parameters in the table above, configuring ZooKeeper for Pulsar involves adding a server.N line to the conf/zookeeper.conf file for each node in the ZooKeeper cluster, where N is the number of the ZooKeeper node. Here's an example for a three-node ZooKeeper cluster:


server.1=zk1.us-west.example.com:2888:3888
server.2=zk2.us-west.example.com:2888:3888
server.3=zk3.us-west.example.com:2888:3888

We strongly recommend consulting the ZooKeeper Administrator's Guide for a more thorough and comprehensive introduction to ZooKeeper configuration