Chapter 16. Configuring a multi-site, fault-tolerant messaging system using broker connections

Procedure

1. Create a broker-connections element in the broker.xml file for the first broker, for example:

   <broker-connections>
     <amqp-connection uri="tcp://<hostname>:<port>" name="DC1">
       <mirror/>
     </amqp-connection>
   </broker-connections>

   <hostname>

   The hostname of the other broker instance.

   <port>

   The port used by the broker on the other host.

   All messages on the first broker are mirrored to the second broker, but messages that existed before the mirror was created are not mirrored.

2. If you want the first broker to mirror messages synchronously to ensure that the mirrored broker is up-to-date for disaster recovery, set the sync=true attribute in the amqp-connection element of the broker, as shown in the following example.

   Synchronous mirroring requires that messages sent by a broker to a mirrored broker are written to the volumes of both brokers at the same time. Once the write operation is complete on both brokers, the source broker acknowledges that the write request is complete and control is returned to clients.

   <broker-connections>
     <amqp-connection uri="tcp://<hostname>:<port>" name="DC2">
       <mirror sync="true"/>
     </amqp-connection>
   </broker-connections>

   Note

   If the write request cannot be completed on the mirrored broker, for example, if the broker is unavailable, client connections are blocked until a mirror is available to complete the most recent write request.

   Note

   The broker connections name in the example, DC1, is used to create a queue named $ACTIVEMQ_ARTEMIS_MIRROR_mirror. Make sure that the corresponding broker is configured to accept those messages, even though the queue is not visible on that broker.

3. Create a broker-connections element in the broker.xml file for the second broker, for example:

   <broker-connections>
     <amqp-connection uri="tcp://<hostname>:<port>" name="DC2">
       <mirror/>
     </amqp-connection>
   </broker-connections>

4. If you want the second broker to mirror messages synchronously, set the sync=true attribute in the amqp-connection element of the broker. For example:

   <broker-connections>
     <amqp-connection uri="tcp://<hostname>:<port>" name="DC2">
       <mirror sync="true"/>
     </amqp-connection>
   </broker-connections>

5. (Optional) Configure the following parameters for the mirror, as required.

   queue-removal

   Specifies whether either queue or address removal events are sent. The default value is true.

   message-acknowledgments

   Specifies whether message acknowledgments are sent. The default value is true.

   queue-creation

   Specifies whether either queue or address creation events are sent. The default value is true.

   For example:

   <broker-connections>
     <amqp-connection uri="tcp://<hostname>:<port>" name="DC2">
       <mirror sync="true" queue-removal="false" message-acknowledgments ="false" queue-creation="false"/>
     </amqp-connection>
   </broker-connections>

6. (Optional) Customize the broker retry attempts to acknowledge messages on the target mirror.

   An acknowledgment might be received on a target mirror for a message that is not in the queue memory. To give the broker sufficient time to retry acknowledging the message on the target mirror, you can customize the following parameters for your environment:

   mirrorAckManagerQueueAttempts

   The number of attempts the broker makes to find a message in memory. The default value is 5. If the broker does not find the message in memory after the specified number of attempts, the broker searches for the message in page files.

   mirrorAckManagerPageAttempts

   The number of attempts the broker makes to find a message in page files if the message was not found in memory. The default value is 2.

   mirrorAckManagerRetryDelay

   The interval, in milliseconds, between attempts the broker makes to find a message to acknowledge in memory and then in page files.

   Specify any of these parameters outside of the broker-connections element. For example:

   <mirrorAckManagerQueueAttempts>8</mirrorAckManagerQueueAttempts>
   
   <broker-connections>
     <amqp-connection uri="tcp://<hostname>:<port>" name="DC2">
       <mirror/>
     </amqp-connection>
   </broker-connections>

7. (Optional) If messages are paged on the target mirror, set the mirrorPageTransaction to true if you want the broker to coordinate writing duplicate detection information with writing messages to page files.

   If the mirrorPageTransaction attribute is set to false, which is the default, and a communication failure occurs between the brokers, a duplicate message can, in rare circumstances, be written to the target mirror.

   Setting this parameter to true increases the broker’s memory usage.

8. Configure clients using the instructions documented in Section 15.6, “Configuring clients in a multi-site, fault-tolerant messaging system”, noting that with broker connections, there is no shared storage.