The broker.xml file located in the <MB_HOME>/repository/conf directory contains the configurations relating to optimization, messaging transports, persistent store information, performance tuning and cluster coordination.
This file is compliant with the Cipher Tool.
The following is a tree of the XML elements in the file:
Click an element below for more information on that element.
<broker>
This is the top level element of the broker.xml file. It contains all the other elements needed to configure WSO2 MB.
<coordination>
This element contains configurations relating to the Apache Thrift communications. These configurations are important when MB is run in a clustered mode.
Configurable sub elements
| Element Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <nodeID> | In a clustered deployment, a ID is assigned to each MB node via the cluster node identifier. This element can be used to override the cluster node identifier for this MB node. If the value for this element is left as default, the default node ID is generated using the IP (Internet Protocol) and UUID). | String | default | N/A | Mandatory | The node ID of each member in a cluster should be unique. |
| <thriftServerHost> | Apache Thrift is embedded in WSO2 MB and is used for communications related to message delivery. In each MB node of a cluster, the value for this property (thrift server host) should be the IP address of that respective node. Note: One of the nodes in an MB cluster will be used as the coordinating MB node at server startup. The Thrift server configured for the coordinating MB node will serve as the central Thrift server, which will be used by all nodes in the cluster to consume thrift services. The coordinating MB node may switch to another node in the cluster in case the current coordinator becomes unavailable. | String | localhost | N/A | Mandatory | |
| <thriftServerPort> | This should point to the port of the Apache Thrift server in WSO2 MB. | String | 7611 | N/A | Mandatory | |
| <thriftServerReconnectTimeout> | The number of seconds taken by the thrift server to reconnect after a time out. | Integer | 5 | N/A | Mandatory | |
| <thriftSOTimeout> | This is used to handle half-open TCP connections between the broker nodes in a cluster. In such situations, the socket may need to have a timeout value to invalidate the connection. (in milliseconds). A timeout of zero is interpreted as an infinite timeout. | Integer | 0 | N/A | Optional |
<transports>
This element contains all the messaging transports used by WSO2 MB. These messaging transports can be enabled/disabled as required. All the transports are enabled by default. This element also contains configuration parameters that enable you to customise the logical aspects of the message flows used within WSO2 MB.
Configurable sub elements
The following configurable sub elements are common to both AMQP and MQTT transports.
| Element/Attribute Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <bindAddress> | The IP address to which all transport listeners are bound (e.g. amqp and mqtt listeners). | Integer | The IP of the resident node | Mandatory | This is the address exposed from the server and not the host name inferred from carbon.xml. | |
| <defaultConnection> | This element is used to specify default values with regard to the connection of the transport. It contains the enabled and port attributes. | |||||
| enabled | If the value is true, the relevant transport is enabled for WSO2 MB. | Boolean | true | true/false | Mandatory | |
| port | The default listening port for messages/commands from the MB server via the relevant transport. | Integer | 5672 | |||
<sslConnection> | This element is used to specify default values with regard to the SSL (Security Sockets Layer) connection of the transport. It contains the enabled and port attributes. | |||||
enabled | If the value is true, SSL is enabled for WSO2 MB. | Boolean | true | true/false | Mandatory | |
| port | The default listening SSL port for messages/commands from the MB server via the relevant transport. This port is used only if the enabled attribute of the sslConnection element is set to true. | Integer | 8672 | Mandatory if SSL is enabled. | ||
| <keyStore> | This element contains parameters relating to the keystore directory which include location and password. See the section on working with security for details on keystores. | |||||
| <location> | The path to the keystore directory. See the section on working with security for details on keystores. | String | repository/resources/security/wso2carbon.jks | repository/resources/security/wso2carbon.jks | Mandatory | |
| <password> | The password for the key store. | String | wso2carbon | wso2carbon | Mandatory | |
| <trustStore> | This element contains parameters relating to the truststore which include location and password. | |||||
| <location> | The location of the truststore. | String | repository/resources/security/client-truststore.jks | |||
| <password> | The password for the truststore | String | wso2carbon |
The following configurable sub elements are specific to the AMQP transport.
| Element Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <maximumRedeliveryAttempts> | The maximum number of times the WSO2 MB should attempt to redeliver a message which has not reached a subscriber. For example, when the value for this is 10, ten more attempts will be made to deliver the message. The default value can be changed depending on your reliability requirements. See the topic on maximum delivery attempts for more information on this configuration. | Integer | 10 | Mandatory | ||
| <allowSharedTopicSubscriptions> | If the value for this parameter is true, it is possible to have multiple durable subscriptions with the same subscription ID. As a result, when a topic is used, only one of the subscribers will get the given message based in a Round Robin manner. | Boolean | False | |||
| <allowStrictNameValidation> | If this value is set to false, it is possible to use the colon (':') symbol in topic names. Note that this only applies when amqp is used. | Boolean | False |
The following configurable sub elements are specific to the MQTT Transport.
| Element Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <inboundBufferSize> | The ring buffer size of the MQTT inbound event disruptor. Increasing this value would improve performance, but it would also increase the memory consumption. | Integer | 32768 | |||
| <deliveryBufferSize> | The ring buffer size of the MQTT delivery event disruptor. As for <inboundBufferSize>, increasing this value would improve performance, but it would also increase the memory consumption. | Integer | 32768 | |||
| <security> | This element contains parameters relating to authentication for the MQTT transport which include <authentication> and <authenticator>. | |||||
| <authentication> | This parameter is used to specify whether clients should always send credentials when establishing a connection. Possible values are as follows. Optional: If this is selected, credentials of the client are validated if they are sent and the connection is established if the credentials are valid. However, if no credentials are sent, the connection is established without performing a validation test. This behaviour adheres to MQTT 3.1 specification. Required: If this is selected, the server always performs an authentication test before establishing a connection. The connection is rejected if no credentials are provided by the client or if the credentials sent are not valid. | Boolean | OPTIONAL | Yes | ||
| <authenticator> | The fully qualified class name of the authenticator. Class should be inherited from Default implementation authenticates against the carbon user store based on the supplied username/password. | String | org.wso2.carbon.andes.authentication.andes.CarbonBasedMQTTAuthenticator | Yes |
<persistence>
This element contains configuration parameters relating to data persistence.
Configurable sub elements
| Element Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <messageStore> | The class that is used to access an external RDBMS database to operate on messages. | String | org.wso2.andes.store.jdbc.JDBCMessageStoreImpl | |||
| <contextStore> | The class that is used to access an external RDBMS database to operate on server context. e.g. subscriptions. | org.wso2.andes.store.jdbc.JDBCAndesContextStoreImpl | ||||
| <idGenerator> | The ID generation class that is used to maintain unique IDs for each message that arrives at the server. | org.wso2.andes.server.cluster.coordination.TimeStampBasedMessageIdGenerator | ||||
| <storeHealthCheckInterval> | The length of the time interval between two checks made by the system to ensure that communication between the message store and the MB server instance is healthy. | Integer | 10 |
<transaction>
This element contains configurations relating to publisher transactions.
| Element Name | Description | Type | Default | Fixed | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <dbConnectionPoolSize> | The number of connections reserved at a given time for transactional database tasks. A transaction reserves a database connection until the transaction is committed, rolled back or closed. | Integer | 10 | |||
| <maxBatchSizeInBytes> | The maximum number of bytes included in a transaction. Exceeding this number will cause failure in commit requests. | Integer | 10000000 |
<performanceTuning>
This element contains configurations relating to the memory and processor allocations of the WSO2 MB server.
| Element Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
<slots> | Each subscriber is assigned a slot by WSO2 MB. The subscriber reads messages from this assigned slot. A slot comprises of a chunk of messages in a row. This element contains all parameters relating to slots which include | |||||
| <slotRetainTimeInMemory> | The maximum time duration for which a slot can be retained in memory. Once the time specified in this parameter elapses, the messages in the slot are updated to the coordinator node in the cluster. | Integer | 1000 | The value is given in milliseconds. | ||
<windowSize> | This parameter is used to specify a rough estimate for the size of the slot. e.g., If the size of the slot is 1000, it can expand to 3000 when there are 3 nodes. | Integer | 1000 | |||
| <windowCreationTimeout> | This parameter defines the timeout for the slot window creation task. In a slow message publishing scenario, this parameter accounts for the delay in the delivery of each message. e.g., If one message is published per minute, then each message will be delivered only after they are submitted to the slot coordinator once this timeout has taken place. | 3000 | ||||
| <workerThreadCount> | The number of slot delivery worker threads that should be started. Slot delivery worker threads read message meta data from message store. | Integer | 5 | |||
| <delivery> | This element contains all the parameters relating to message delivery which include maxNumberOfReadButUndeliveredMessages, ringBufferSize, parallelContentReaders, and parallelDeliveryHandlers. | |||||
| <maxNumberOfReadButUndeliveredMessages> | The maximum number of undelivered messages that can be stored in the memory. Increasing the value for this parameter can cause out-of-memory exceptions, but the performance will be improved. | Integer | 1000 | |||
| <ringBufferSize> | The thread pool size of the queue delivery workers. This should be increased if there are a lot of unique queues in the system at a given time. | Integer | 4096 | |||
| <parallelContentReaders> | The number of parallel readers used to read content from the message store. Increasing this value would increase the speed of the message sending mechanism. However, it would also cause the load on the data store to increase. | Integer | 5 | |||
| <parallelDeliveryHandlers> | The number of parallel delivery handlers used to send messages to subscribers. Increasing this value will increase the speed of the message sending mechanism. However, it would also cause the load on the data store to increase. | Integer | 5 | |||
| <contentReadBatchSize> | ||||||
| <ackHandling> | This element contains parameters relating to message acknowledgement which include maxUnackedMessages, ackHandlerBatchSize, and ackHandlerBatchSize. | |||||
| <maxUnackedMessages> | The maximum number of unacknowledged messages allowed. The message delivery from the server to the client is temporarily paused when the number specified for this parameter is reached. This number should be specified considering the message consumption rate. | Integer | 1000 | |||
| <ackHandlerBatchSize> | The maximum batch size of the acknowledgement handler. Andes processes acknowledgements in batches using Disruptor. Increasing the batch size reduces the number of calls made to database by MB. The value for this parameter should be set based on database optimization. The maximum batch size is applicable in high throughput scenarios. Messages are handled in smaller batches using the Disruptor in low throughput scenarios. | Integer | 100 | |||
| <ackHandlerCount> | The number of acknowledgement handlers used to process acknowledgements concurrently. Acknowledgements are batched and processed by these acknowledgement handlers. | Integer | 5 | |||
| <contentHandling> | This element contains parameters relating to content handling which include contentChunkHandlerCount and maxContentChunkSize. | |||||
| <contentChunkHandlerCount> | The number of message chunk handlers used to process content chunks concurrently. The content chunks are batched and processed by these content chunk handlers. The value for this parameter should be set based on database optimization. | Integer | 3 | |||
| <maxContentChunkSize> | The maximum column size for a content chuck handler. | Integer | 65500 | |||
| <inboundEvents> | This element contains parameters relating to the inbound events, which include | |||||
| <parallelMessageWriters> | The number of parallel writers used to write content to the message store. Increasing this value will increase the speed of the message receiving mechanism. However, it would also cause the load on the data store to increase. | Integer | 1 | |||
| <bufferSize> | The size of the Disruptor ring buffer for inbound event handling. Increasing the buffer size is recommended when there is an increased rate of publishing. In such situations, the messages can be stored in the memory. | Integer | 65536 | The buffer size should be an even number. | ||
| <messageWriterBatchSize> | The maximum batch size of the batch write operation for inbound messages. MB internals use Disruptor to batch events. Hence this batch size is set to avoid database requests with a high load (i.e. with large batch sizes) to write messages. This should to be configured in high throughput messaging scenarios to regulate the load on the database from MB. | Integer | 70 | |||
| <purgedCountTimeout> | The number of milliseconds to wait for a queue to complete a purge event in order to update the purge count. If the time specified here elapses before the queue completes the purge event, the purge count will not be updated to include the event. The value for this parameter can be increased to ensure that the purge count is accurate. | Integer | 180 | |||
| <transactionMessageWriters> | The number of parallel writers used to write content to the message store for transaction based publishing. Increasing the value for this parameter reduces the time taken to commit a transaction, but the load on the data store would also increase. | Integer | 1 | |||
| <failover> | This element contains parameters relating to failover which includes vHostSyncTaskInterval. | |||||
| <messageCounter> | This element contains parameters relating to the message counter which includes counterTaskInterval and countUpdateBatchSize. | |||||
| <counterTaskInterval> | Message counter tasks delay that occurs between the end of one execution and the start of another. | Integer | 5 | This value is specified in seconds. | ||
| <countUpdateBatchSize> | The message count is updated in batches. Once the count exceeds the batch size, the message count update is moved to the Message Count Update task. | Integer | 100 | |||
| <messageDeletion> | This element contains parameters relating to message deletion which include contentRemovalTaskInterval. | |||||
| <contentRemovalTaskInterval> | The task interval for the content removal task which will remove the actual message content from the store in the background. If the message rate is very high, this can be set to a lower value to minimise the number of delete requests per task. | Integer | 3 | This value is specified in seconds. | ||
| <topicMatching> | The method used for topic matching. If | Boolean | SIMPLE | SIMPLE/BitMaps |
<managementConsole>
This element contains parameters relating to the management console.
| Element Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <messageBrowsePageSize> | The maximum number of messages to be displayed in a page at a given time when viewing messages in a queue or the dead letter channel. | Integer | 100 | |||
| <maximumMessageDisplayLength> | The maximum number of characters in a message that should be displayed in the Management Console when browsing queues. If the number of characters in a message exceeds the value specified for this parameter, the truncated message content will be displayed with the text message content too large to display. Increasing this value can cause delays when viewing the message content in the Management Console. | Integer | 100000 |
<flowControl>
This element contains parameters relating to the message flow control.
| Element Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <global> | This element contains parameters which define buffer limits which enable/disable flow control at a global level which include lowLimit and highLimit. | |||||
<lowLimit> | The total number of message content chunks that would disable flow control if they are enabled, that should be stored in the buffer. Having a small difference between the lower and higher limits will lead to frequent enabling and disabling of flow control, causing the message publishing rate to be reduced. | Integer | 800 | |||
<highLimit> | The total maximum number of message content chunks that should be stored in the buffer. When this limit is reached, flow control is enabled. Having a higher limit will increase the number of messages in memory before storing in DB. This results in a higher overall message publishing rate, but with reduced reliability. | Integer | 8000 | |||
| <bufferBased> | This element contains parameters relating to the channel specific buffer limits which enable and disable the flow control locally which include lowLimit and highLimit. | |||||
<lowLimit> | The number of message content chunks that would disable flow control if they are enabled, that should be stored in the buffer. Having a small difference between the lower and higher limits will lead to frequent enabling and disabling of flow control, causing the message publishing rate to be reduced. | Integer | 100 | |||
<highLimit> | The maximum number of message content chunks that should be stored in buffer per publisher. When this limit is reached, flow control is enabled for the relevant publisher. Having a higher limit will increase the number of messages in memory before storing in the DB. This would lead to higher message publishing rates, but with reduced reliability. | Integer | 1000 | |||
| <memoryBased> | This element contains memory based parameters which include memoryCheckInterval, globalMemoryThresholdRatio, and globalMemoryRecoveryThresholdRatio. | |||||
| <memoryCheckInterval> | The time interval at which the server should check for memory consumption and apply flow control to recover. | Integer | 2000 | |||
| <globalMemoryThresholdRatio> | The maximum ratio of memory allowed to be used by the server. Used Memory/Allocated Memory | Integer | 1.0 | This is specified as a decimal between 0 and 1. | ||
| <globalMemoryRecoveryThresholdRatio> | The ratio at which the server should apply flow control to recover. Used Memory/Allocated Memory | Integer | 1.0 | This is specified as a decimal between 0 and 1. | ||
| <connectionBased> | This element contains connection based parameters which include perConnectionMessageThreshold. | |||||
| <perConnectionMessageThreshold> | This allows you to apply flow control based on the message count on a given connection. | Integer | 1000 | Not used at present. |
<slotManagement>
This element contains parameters relating to slot management.
| Element Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <storage> | This parameter specifies the slot storage mode (i.e RDBMS/Hazelcast). | String | Hazelcast |
<recovery>
This element contains configurations relating to cluster recovery. Cluster recovery involves retrieving messages from a storage queues after the cluster or a single node has been inactive.
| Element Name | Description | Type | Default Value | Fixed Values | Mandatory/Optional | Notes |
|---|---|---|---|---|---|---|
| <concurrentStorageQueueReads> | The number of storage queue reads carried out concurrently at a given time. There can be multiple storage queues operating before a cluster or a single node becomes inactive. The value for this parameter should be entered depending on the number of storage queues. | Integer | 5 | |||
| <vHostSyncTaskInterval> | The time interval after which the virtual host syncing task can sync host details across the cluster. | integer | 900 | This value is specified in seconds. |