Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.
This documentation is for WSO2 Message Broker version 3.2.0. For the latest documentation, see the documentation for WSO2 Enterprise Integrator.
Skip to end of metadata
Go to start of metadata

WSO2 Message Broker (WSO2 MB) is shipped with default configurations that will allow you to download, install and get started with your product instantly. However, when you go into production, it is recommended to change some of the default settings to ensure that you have a robust system that is suitable for your operational needs. Also, you may have specific use cases that require specific configurations to the server. If you are a product administrator, the follow content will provide an overview of the administration tasks that you need to perform when working with WSO2 Message Broker (WSO2 MB).

Upgrading from a previous release

If you are upgrading from WSO2 MB 3.1.0 to WSO2 MB 3.2.0 version, see the upgrading instructions for WSO2 Message Broker.

Changing the default database

WSO2 MB contains two embedded H2 databases: The default Carbon database, which is used for storing user management and registry data, and the default broker-specific database.

You can change the default database configurations in WSO2 MB by setting up new physical databases, and updating the relevant configurations. We recommend the use of an industry-standard RDBMS such as Oracle, PostgreSQL, MySQL, MS SQL, etc. when you set up your production environment.

  • For information on setting up a new database for your profile, see Setting up the Physical Database in the WSO2 Administration Guide.

    Add the database drivers to the <MB_HOME>/repository/components/lib/ directory when setting up the database.

  • Once you set up a new Carbon database, see Changing the Carbon Database for instructions on updating the configurations.
  • Once you set up a new broker-specific database, see Changing the Default Broker Database for instructions on updating the configurations.

Configuring users, roles and permissions

The user management feature in your product allows you to create new users and define the permissions granted to each user. You can also configure the user stores that are used for storing data related to user management.

Configuring security

After you install WSO2 MB, it is recommended to change the default security settings according to the requirements of your production environment. As MB is built on top of the WSO2 Carbon Kernel (version 4.4.6), the main security configurations applicable to MB are inherited from the Carbon kernel.

For instructions on configuring security in your server, see the following topics in the WSO2 Administration Guide.

Configuring transports 

WSO2 Message Broker (WSO2 MB) uses two transport protocols for the purpose of brokering messages between publishers and subscribers. These protocols are the Advanced Message Queueing Protocol (AMQP) and the Message Queueing and Telemetry Transport (MQTT).

For instructions on configuring these transports, see Configuring Transports for WSO2 MB.

Note that WSO2 Message Broker does not require the transports enabled through the Carbon Kernel.

Configuring multitenancy

You can create multiple tenants in your product server, which will allow you to maintain tenant isolation in a single server/cluster. For instructions on configuring multiple tenants for your server, see Working with Multiple Tenants in the WSO2 Administration Guide.

Configuring the registry

registry is a content store and a metadata repository for various artifacts such as services, WSDLs and configuration files. In WSO2 products, all configurations pertaining to modules, logging, security, data sources and other service groups are stored in the registry by default. 

For instructions on setting up and configuring the registry for your server, see Working with the Registry in the WSO2 Administration Guide.

Performance tuning

You can optimize the performance of your WSO2 server by using configurations and settings that are suitable to your production environment. At a basic level, you need to have the appropriate OS settings, JVM settings etc. Since WSO2 products are all based on a common platform called Carbon, most of the OS, JVM settings recommended for production are common to all WSO2 products. Additionally, there will be other performance enhancing configuration recommendations that will depend on very specific features used by your product. 

For instructions on the Carbon platform-level performance tuning recommendations, see Performance Tuning in the WSO2 Administration Guide.

For instructions on performance tuning recommendations that are specific to WSO2 MB functionality, see the topics given below.

Changing the default ports

When you run multiple WSO2 products, multiple instances of the same product, or multiple WSO2 product clusters on the same server or virtual machines (VMs), you must change their default ports with an offset value to avoid port conflicts.

For instructions on configuring posts, see Changing the Default Ports in the WSO2 Administration Guide.

Configuring custom proxy paths

This feature is particularly useful when multiple WSO2 products (fronted by a proxy server) are hosted under the same domain name. By adding a custom proxy path you can host all products under a single domain and assign proxy paths for each product separately . 

For instructions on configuring custom proxy paths, see Adding a Custom Proxy Path in the WSO2 Administration Guide.

Customizing error pages

You can make sure that sensitive information about the server is not revealed in error messages, by customizing the error pages in your product. 

For instructions, see Customizing Error Pages in the WSO2 Administration Guide.

Customizing the management console

Some of the WSO2 products, such as WSO2 MB consist of a web user interface named the management console. This allows administrators to configure, monitor, tune, and maintain the product using a simple interface. You can customize the look and feel of the management console for your product.

For instructions, see Customizing the Management Console in the WSO2 Administration Guide. 

Applying patches 

For instructions on applying patches (issued by WSO2), see WSO2 Patch Application Process in the WSO2 Administration Guide.

Monitoring the server

Monitoring is an important part of maintaining a product server. Listed below are the monitoring capabilities that are available for WSO2 MB.

  • Monitoring server logs: A properly configured logging system is vital for identifying errors, security threats and usage patterns in your product server. For instructions on monitoring the server logs, see Monitoring Logs in the WSO2 Administration Guide.
  • Message tracing in WSO2 MB: In WSO2 MB you have the option of tracing messages by enabling a trace log file. See the troubleshooting guide for instructions.
  • Monitoring using WSO2 metrics: WSO2 MB 3.5.0 is shipped with JVM Metrics, which allows you to monitor statistics of your server using Java Metrics. For instructions on setting up and using Carbon metrics for monitoring, see Using WSO2 Metrics in the WSO2 Administration Guide.

  • JMX-based monitoring: For information on monitoring your server using JMX, see JMX-based monitoring in the WSO2 Administration Guide.

Troubleshooting WSO2 MB

For details on how you can troubleshoot and trace errors that occur in your WSO2 MB server, see Troubleshooting WSO2 MB.


In a production environment, WSO2 Message Broker can be clustered and configured with an external Database Management System (DBMS) of your choice. For instructions on the clustered deployment, see Clustered Deployment.

  • No labels