Chapter 16. Configuring a multi-site, fault-tolerant messaging system using broker connections Large-scale enterprise messaging systems commonly have discrete broker clusters located in geographically distributed data centers. In the event of a data center outage, system administrators might need to preserve existing messaging data and ensure that client applications can continue to produce and consume messages. You can use broker connections to ensure continuity of your messaging system during a data center outage. This type of solution is called a multi-site, fault-tolerant architecture . Note Only the AMQP protocol is supported for communication between brokers for broker connections. A client can use any supported protocol. Currently, messages are converted to AMQP through the mirroring process. The following sections explain how to protect your messaging system from data center outages using broker connections: Section 16.1, "About broker connections" Section 16.2, "Configuring broker mirroring" Note Multi-site fault tolerance is not a replacement for high-availability (HA) broker redundancy within data centers. Broker redundancy based on live-backup groups provides automatic protection against single broker failures within single clusters. In contrast, multi-site fault tolerance protects against large-scale data center outages. 16.1. About broker connections With broker connections, a broker can establish a connection to another broker and mirror messages to and from that broker. AMQP server connections A broker can initiate connections to other endpoints using the AMQP protocol using broker connections. This means, for example, that the broker can connect to other AMQP servers and create elements on those connections. The following types of operations are supported on an AMQP server connection: Mirrors - The broker uses an AMQP connection to another broker and duplicates messages and sends acknowledgements over the wire. Senders - Messages received on specific queues are transferred to another broker. Receivers - The broker pulls messages from another broker. Peers - The broker creates both senders and receivers on AMQ Interconnect endpoints. This chapter describes how to use broker connections to create a fault-tolerant system. See Chapter 17, Bridging brokers for information about sender, receiver, and peer options. The following events are sent through mirroring: Message sending - Messages sent to one broker will be "replicated" to the target broker. Message acknowledgement - Acknowledgements removing messages at one broker will be sent to the target broker. Queue and address creation. Queue and address deletion. Note If the message is pending for a consumer on the target mirror, the acknowledgement will not succeed and the message might be delivered by both brokers. Mirroring does not block any operation and does not affect the performance of a broker. The broker only mirrors messages arriving from the point in time the mirror was configured. Previously existing messages will not be forwarded to other brokers. 16.2. Configuring broker mirroring You can use broker connections to mirror messages between a pair of brokers. Only one of the brokers can be active at any time. Prerequisites You have two working brokers. Procedure 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. 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 USDACTIVEMQ_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. 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> 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> (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> (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> (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. 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. Important Red Hat does not support client applications consuming messages from both brokers in a mirror configuration. To prevent clients from consuming messages on both brokers, disable the client acceptors on one of the brokers.

Commands:
<broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC1"> <mirror/> </amqp-connection> </broker-connections>
<broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror sync="true"/> </amqp-connection> </broker-connections>
<broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror/> </amqp-connection> </broker-connections>
<broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror sync="true"/> </amqp-connection> </broker-connections>
<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>
<mirrorAckManagerQueueAttempts>8</mirrorAckManagerQueueAttempts> <broker-connections> <amqp-connection uri="tcp://<hostname>:<port>" name="DC2"> <mirror/> </amqp-connection> </broker-connections>