This documentation is for WSO2 Enterprise Integrator version 6.0.0 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.

All docs This doc

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  1. Make an exact copy of EI Message Broker runtime in three different locations and rename them as MB1, MB2 and MB3. Those will be the 3 separate MB instances. 
  2. Navigate to MB1to <EI_HOME>/wso2/broker/conf/carbon.xml and define an offset of 1.

    Code Block
    <!-- Ports offset. This entry will set the value of the ports defined below to
     the define value + Offset.
     e.g. Offset=2 and HTTPS port=9443 will set the effective HTTPS port to 9445
  3. Navigate to MB2to <EI_HOME>/wso2/broker/conf/carbon.xml in MB2 and define an offset of 2. 
  4. Navigate to MB3to <EI_HOME>/wso2/broker/conf/carbon.xml and  in MB3 and define an offset of 3. 
  5. The 3 MB instances are ready. Start each instance of MB by running one of the following commands: 
    • <MB<EI_HOME>/wso2/broker/bin/ (on Linux) 
    • <MB<EI_HOME>/wso2/broker/bin/wso2server.bat (on Windows)

    The broker instances will start on ports 5673, 5674 and 5675 respectively.

Setting up Broker instances in different machines

  1. Make an exact copy of that folder in three separate machines. Let's assume MB1 is in the machine with IP1, MB2 in the machine with IP2 and MB3 in the machine with IP3.
  2. Start all the above instances by running one of the following commands:
    • <MB_HOME>/bin/ (on Linux) 
    • <MB_HOME>/bin/wso2server.bat (on Windows) 
    All severs will start with port offset 0, which is 5672.

Running the broker instances

  1. Start the Integrator runtime in WSO2 EI in the default port (port offset 0). This is possible if you used the single machine setup above, as those servers were started with different port offsets. If you are using different machines, use another machine to start the Integrator runtime. Instructions can be found here.


    It is not possible to start multiple WSO2 products with their default configurations simultaneously in the same environment. Since all WSO2 products use the same port in their default configuration, there will be port conflicts.

  2. There is only a single difference to enable failover across the three brokers we have setup. That is when specifying the following:

    Code Block

    For example, if you hope to use a single machine broker setup as described above,

    Code Block
    connectionfactory.QueueConnectionFactory = amqp://admin:[email protected]/carbon?failover='roundrobin'&cyclecount='2'&brokerlist='tcp://localhost:5673? retries='5'&connectdelay='30000';tcp://localhost:5674?retries='5'&connectdelay='30000';tcp://localhost:5675?retries='5'&connectdelay='30000''

    If you hope to use the broker setup made across several machines as described above,

    Code Block
    connectionfactory.QueueConnectionFactory = amqp://admin:[email protected]/carbon?failover='roundrobin'&cyclecount='2'&brokerlist='tcp://IP1:5672?retries='5'&connectdelay='30000';tcp://IP2:5672?retries='5'&connectdelay='30000';tcp://IP3:5672?retries='5'&connectdelay='30000''

     The parameters used above are described in detail below:

    Brokerlist option
    Code Block
    brokerlist='<broker url>[;<broker url>]'

    The broker list defines the various brokers that can be used for this connection. A minimum of one broker URL is required. Additional URLs are semi-colon(';') delimited.

    Broker URL format
    Code Block
    retries1The number of times to retry connecting to this Broker
    sslfalseUse ssl on the connection
    connecttimeout30000How long in (milliseconds) to wait for the connection to succeed
    connectdelaynoneHow long in (milliseconds) to wait before attempting to reconnect
    Brokerlist failover option
    Code Block
    singlebrokerThis will only use the first broker in the list.
    roundrobinThis method tries each broker in turn.
    nofailover[New in 0.5] This method disables all retry and failover logic.

    The current default is to use the singlebroker method when only one broker is present, and the roundrobin method with multiple brokers. The method value in the URL may also be any valid class on the classpath that implements the FailoverMethod interface.
    cyclecount1The number of times to loop through the list of available brokers before failure.

Testing the setup

When sending messages to a queue (you can configure SOAP UI to send messages continuously one after the other) using the setup described above, kill MB1. You will notice that failover happens at the Integrator instance to the second broker i.e MB2. The logs at the Integrator side will indicate that failover occurred. 

If there were previous messages at MB1, they will not be delivered. Usually, the solution for that (and many other problems) is broker clustering. For information on the advantages of clustering, see Clustering the Broker Profile