| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.18"> |
| <link rel="icon" type="image/png" href="images/favicon.png"> |
| <title>Broker Connections</title> |
| <link rel="stylesheet" href="css/asciidoctor.css"> |
| <link rel="stylesheet" href="css/font-awesome.css"> |
| <link rel="stylesheet" href="css/rouge-github.css"> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>Broker Connections</h1> |
| <div id="toc" class="toc2"> |
| <div id="toctitle"><a href="index.html">User Manual for 2.33.0</a></div> |
| <ul class="sectlevel1"> |
| <li><a href="#amqp-server-connections">1. AMQP Server Connections</a></li> |
| <li><a href="#amqp-server-connection-operations">2. AMQP Server Connection Operations</a></li> |
| <li><a href="#reconnecting-and-failover">3. Reconnecting and Failover</a></li> |
| <li><a href="#mirroring">4. Mirroring</a> |
| <ul class="sectlevel2"> |
| <li><a href="#mirror-configuration">4.1. Mirror configuration</a></li> |
| <li><a href="#store-and-forward-queue">4.2. Store and Forward Queue</a></li> |
| <li><a href="#pre-existing-messages">4.3. Pre Existing Messages</a></li> |
| </ul> |
| </li> |
| <li><a href="#dual-mirror-disaster-recovery">5. Dual Mirror (Disaster Recovery)</a></li> |
| <li><a href="#example">6. Example</a></li> |
| <li><a href="#senders-and-receivers">7. Senders and Receivers</a></li> |
| <li><a href="#peers">8. Peers</a></li> |
| <li><a href="#address-consideration">9. Address Consideration</a></li> |
| <li><a href="#federation">10. Federation</a> |
| <ul class="sectlevel4"> |
| <li><a href="#local-and-remote-address-federation">Local and remote address federation</a></li> |
| <li><a href="#local-and-remote-queue-federation">Local and remote queue federation</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Instead of waiting for clients to connect, a broker can initiate a connection to another endpoint on a specific protocol.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Currently, this feature supports only the AMQP protocol. |
| However, in the future, it might be expanded to other protocols.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Broker connections are configured by the <code><broker-connections></code> XML element in the <code>broker.xml</code> configuration file.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| ... |
| <span class="nt"></broker-connections></span></code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="amqp-server-connections"><a class="anchor" href="#amqp-server-connections"></a><a class="link" href="#amqp-server-connections">1. AMQP Server Connections</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>An ActiveMQ Artemis broker can initiate connections using the AMQP protocol. |
| This means that the broker can connect to another AMQP server (not necessarily ActiveMQ Artemis) and create elements on that connection.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To define an AMQP broker connection, add an <code><amqp-connection></code> element within the <code><broker-connections</code> element in the <code>broker.xml</code> configuration file. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://HOST:PORT"</span> <span class="na">name=</span><span class="s">"other-server"</span> <span class="na">retry-interval=</span><span class="s">"100"</span> <span class="na">reconnect-attempts=</span><span class="s">"-1"</span> <span class="na">user=</span><span class="s">"john"</span> <span class="na">password=</span><span class="s">"doe"</span><span class="nt">></span> |
| ... |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span></code></pre> |
| </div> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">uri</dt> |
| <dd> |
| <p>: tcp://host:myport[?options] (this is a required argument)</p> |
| </dd> |
| <dt class="hdlist1">name</dt> |
| <dd> |
| <p>: Name of the connection used for management purposes</p> |
| </dd> |
| <dt class="hdlist1">user</dt> |
| <dd> |
| <p>: User name with which to connect to the endpoint (this is an optional argument)</p> |
| </dd> |
| <dt class="hdlist1">password</dt> |
| <dd> |
| <p>: Password with which to connect to the endpoint (this is an optional argument)</p> |
| </dd> |
| <dt class="hdlist1">retry-interval</dt> |
| <dd> |
| <p>: Time, in milliseconds to wait before retrying a connection after an error. |
| The default value is <code>5000</code>.</p> |
| </dd> |
| <dt class="hdlist1">reconnect-attempts</dt> |
| <dd> |
| <p>: default is -1 meaning infinite</p> |
| </dd> |
| <dt class="hdlist1">auto-start</dt> |
| <dd> |
| <p> : Should the broker connection start automatically with the broker. |
| Default is <code>true</code>. |
| If false it is necessary to call a management operation to start it.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| The connection URI options for transport settings, such as enabling and configuring TLS, are common with other Artemis connector URIs. |
| See <a href="configuring-transports.html#configuring-netty-ssl">the transport doc</a> for more. |
| An example configuration for a TLS AMQP broker-connection can be found in the broker <a href="examples.html">examples</a> at ./examples/features/broker-connection/amqp-sending-overssl. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| If auto-start is disabled on the broker connection, the start of the broker connection will only happen after the management method <code>startBrokerConnection(connectionName)</code> is called on the ServerController. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| The target endpoint needs permission for all operations that are configured. |
| Therefore, If a security manager is being used, ensure that you perform the configured operations with a user with sufficient permissions. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="amqp-server-connection-operations"><a class="anchor" href="#amqp-server-connection-operations"></a><a class="link" href="#amqp-server-connection-operations">2. AMQP Server Connection Operations</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The following types of operations are supported on an AMQP server connection:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Mirrors</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The broker uses an AMQP connection to another broker and duplicates messages and sends acknowledgements over the wire.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Senders</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Messages received on specific queues are transferred to another endpoint.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Receivers</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The broker pulls messages from another endpoint.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Peers</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The broker creates both senders and receivers on another endpoint that knows how to handle them. |
| This is currently implemented by Apache Qpid Dispatch.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="reconnecting-and-failover"><a class="anchor" href="#reconnecting-and-failover"></a><a class="link" href="#reconnecting-and-failover">3. Reconnecting and Failover</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>It is possible to determine how reconnection will happen on a broker connection.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These are the attributes that are available on the amqp-connection XML element:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>reconnect-attempts: default is -1 (infinite). |
| How many attempts will be done after a failed connection</p> |
| </li> |
| <li> |
| <p>retry-interval: default is 5000, in milliseconds, the wait between each retry of a connection.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>It is also possible to specify alternate hosts on a broker connection by appending a comma separated list after a # at the end of the URI. |
| The broker connection would keep trying on the alternate list until one of the targets is available to connect. |
| Example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://ServerA:5672#BackupA:5672,BackupB:5672"</span> <span class="na">name=</span><span class="s">"ServerA"</span> <span class="na">reconnect-attempts=</span><span class="s">"-1"</span> <span class="na">retry-interval=</span><span class="s">"5000"</span><span class="nt">></span> |
| ... |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="images/broker-connection-failover.jpg" alt="Broker Connection Failover"></span> Figure 1. |
| Broker Connection - Reconnecting and Failover.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The previous example portrays a case of connection failure towards ServerA. |
| The system would try to connect to serverA, backupA, and backupB until it successfully connects to one of these nodes.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="mirroring"><a class="anchor" href="#mirroring"></a><a class="link" href="#mirroring">4. Mirroring</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Mirroring will reproduce any operation that happened on the source brokers towards a target broker.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following events are sent through mirroring:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Message sending</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Messages sent to one broker will be "replicated" to the target broker.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Message acknowledgement</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Acknowledgements removing messages at one broker will be sent to the target broker.</p> |
| </li> |
| <li> |
| <p>Note that if the message is pending for a consumer on the target mirror, the ack will not succeed and the message might be delivered by both brokers.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Queue and address creation.</p> |
| </li> |
| <li> |
| <p>Queue and address deletion.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>By default every operation is sent asynchronously without blocking any clients. |
| However if you set sync="true" on the mirror configuration, the clients will always wait for the mirror on every blocking operation.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="mirror-configuration"><a class="anchor" href="#mirror-configuration"></a><a class="link" href="#mirror-configuration">4.1. Mirror configuration</a></h3> |
| <div class="paragraph"> |
| <p>Add a <code><mirror></code> element within the <code><amqp-connection></code> element to configure mirroring to the target broker.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following optional arguments can be utilized:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">queue-removal</dt> |
| <dd> |
| <p>: Specifies whether a queue- or address-removal event is sent. |
| The default value is <code>true</code>.</p> |
| </dd> |
| <dt class="hdlist1">message-acknowledgements</dt> |
| <dd> |
| <p>: Specifies whether message acknowledgements are sent. |
| The default value is <code>true</code>.</p> |
| </dd> |
| <dt class="hdlist1">queue-creation</dt> |
| <dd> |
| <p>: Specifies whether a queue- or address-creation event is sent. |
| The default value is <code>true</code>.</p> |
| </dd> |
| <dt class="hdlist1">address-filter</dt> |
| <dd> |
| <p>: An optional comma-separated list of inclusion and/or exclusion filter entries used to govern which addresses (and related queues) mirroring events will be created for on this broker-connection. |
| That is, events will only be mirrored to the target broker for addresses that match the filter. |
| An address is matched when it begins with an inclusion entry specified in this field, unless the address is also explicitly excluded by another entry. |
| An exclusion entry is prefixed with <code>!</code> to denote any address beginning with that value does not match. |
| If no inclusion entry is specified in the list, all addresses not explicitly excluded will match. |
| If the address-filter attribute is not specified, then all addresses (and related queues) will match and be mirrored.</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>'eu' matches all addresses starting with 'eu'</p> |
| </li> |
| <li> |
| <p>'!eu' matches all address except for those starting with 'eu'</p> |
| </li> |
| <li> |
| <p>'eu.uk,eu.de' matches all addresses starting with either 'eu.uk' or 'eu.de'</p> |
| </li> |
| <li> |
| <p>'eu,!eu.uk' matches all addresses starting with 'eu' but not those starting with 'eu.uk'</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Address exclusion will always take precedence over address inclusion.</p> |
| </li> |
| <li> |
| <p>Address matching on mirror elements is prefix-based and does not support wild-card matching.</p> |
| </li> |
| </ul> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </dd> |
| <dt class="hdlist1">sync</dt> |
| <dd> |
| <p>By default is <code>false</code>. |
| If set it to true any client blocking operation will be held until the mirror has confirmed receiving the operation.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Notice that a disconnected node would hold all operations from the client. |
| If you set sync=true you must reconnect a mirror before performing any operations.</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>An example of a mirror configuration is shown below:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://HOST:PORT"</span> <span class="na">name=</span><span class="s">"mirror"</span><span class="nt">></span> |
| <span class="nt"><mirror/></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span></code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="store-and-forward-queue"><a class="anchor" href="#store-and-forward-queue"></a><a class="link" href="#store-and-forward-queue">4.2. Store and Forward Queue</a></h3> |
| <div class="paragraph"> |
| <p>Mirror events are always stored on a local queue prefixed as "$ACTIVEMQ_ARTEMIS_MIRROR_" and then concatenated with the broker connection’s configured name.</p> |
| </div> |
| <div class="paragraph"> |
| <p>So, in the following configuration mirror events will be stored on a queue named "$ACTIVEMQ_ARTEMIS_MIRROR_brokerB".</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connection></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://brokerB:5672"</span> <span class="na">name=</span><span class="s">"brokerB"</span><span class="nt">></span> |
| <span class="nt"><mirror/></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connection></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>These messages are then transferred to brokerB:5672. |
| A producer to the address $ACTIVEMQ_ARTEMIS_MIRROR_brokerB will be created towards brokerB. |
| If there is a security manager configured, security roles must be provided to the user on the broker connection.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Notice the queue $ACTIVEMQ_ARTEMIS_MIRROR_brokerB will not actually exist on brokerB and so it wont be visible on the administration console. |
| The target broker will treat these messages accordingly as mirror events and perform the appropriate operations at the target broker.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="pre-existing-messages"><a class="anchor" href="#pre-existing-messages"></a><a class="link" href="#pre-existing-messages">4.3. Pre Existing Messages</a></h3> |
| <div class="paragraph"> |
| <p>The broker will only mirror messages arriving from the point in time the mirror was configured. |
| Previously existing messages will not be forwarded to other brokers.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="dual-mirror-disaster-recovery"><a class="anchor" href="#dual-mirror-disaster-recovery"></a><a class="link" href="#dual-mirror-disaster-recovery">5. Dual Mirror (Disaster Recovery)</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>ActiveMQ Artemis supports automatic fallback mirroring. |
| Every sent message and every acknowledgement is asynchronously replicated to the mirrored broker.</p> |
| </div> |
| <div class="paragraph"> |
| <p>On the following diagram, there will be two servers called DataCenter1, and DataCenter2. |
| In order to have a dual mirror configuration, it is necessary is to add the mirror broker connection on each broker.xml:</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="images/broker-connection-DR.jpg" alt="Broker Connection DR"></span> Figure 2. |
| Broker Connection - Disaster Recovery.</p> |
| </div> |
| <div class="paragraph"> |
| <p>on DataCenter1, the following code should be added on broker.xml:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://DataCenter2:5672"</span> <span class="na">name=</span><span class="s">"DC2"</span><span class="nt">></span> |
| <span class="nt"><mirror/></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following xml should be added on DataCenter2’s broker.xml:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://DataCenter1:5672"</span> <span class="na">name=</span><span class="s">"DC1"</span><span class="nt">></span> |
| <span class="nt"><mirror/></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The broker connections will replicate sends and acknowledgements to the other broker, no matter where they originated. |
| If messages are sent on DC1 (DataCenter1) these will be automatically transferred to DC2 (DataCenter2). |
| Messages acknowledgements received on DC2 will be automatically related back to DC1. |
| The only exception to that rule would be if there were already consumers with pending messages on any server, where a mirrored acknowledgement will not prevent the message being consumed by both consumers. |
| It is recommended to not have active consumers on both servers.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="example"><a class="anchor" href="#example"></a><a class="link" href="#example">6. Example</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>There is an example as part of the distribution showing dual broker configuration (or disaster recovery) under ./examples/features/broker-connection/disaster-recovery.</p> |
| </div> |
| <div class="paragraph"> |
| <p>On the example two brokers are configured to mirror each other and whatever happens in one broker is immediately copied over to the other broker.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="senders-and-receivers"><a class="anchor" href="#senders-and-receivers"></a><a class="link" href="#senders-and-receivers">7. Senders and Receivers</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>It is possible to connect an ActiveMQ Artemis broker to another AMQP endpoint simply by creating a sender or receiver broker connection element.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a <code>sender</code>, the broker creates a message consumer on a queue that sends messages to another AMQP endpoint.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a <code>receiver</code>, the broker creates a message producer on an address that receives messages from another AMQP endpoint.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Both elements function as a message bridge. |
| However, there is no additional overhead required to process messages. |
| Senders and receivers behave just like any other consumer or producer in ActiveMQ Artemis.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Specific queues can be configured by senders or receivers. |
| Wildcard expressions can be used to match senders and receivers to specific addresses or <em>sets</em> of addresses. |
| When configuring a sender or receiver, the following properties can be set:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">address-match</dt> |
| <dd> |
| <p>: Match the sender or receiver to a specific address or <strong>set</strong> of addresses, using a wildcard expression</p> |
| </dd> |
| <dt class="hdlist1">queue-name</dt> |
| <dd> |
| <p>: Configure the sender or receiver for a specific queue</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>Some examples are shown below.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Using address expressions:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://HOST:PORT"</span> <span class="na">name=</span><span class="s">"other-server"</span><span class="nt">></span> |
| <span class="nt"><sender</span> <span class="na">address-match=</span><span class="s">"queues.#"</span><span class="nt">/></span> |
| <span class="c"><!-- notice the local queues for remotequeues.# need to be created on this broker --></span> |
| <span class="nt"><receiver</span> <span class="na">address-match=</span><span class="s">"remotequeues.#"</span><span class="nt">/></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span> |
| |
| <span class="nt"><addresses></span> |
| <span class="nt"><address</span> <span class="na">name=</span><span class="s">"remotequeues.A"</span><span class="nt">></span> |
| <span class="nt"><anycast></span> |
| <span class="nt"><queue</span> <span class="na">name=</span><span class="s">"remoteQueueA"</span><span class="nt">/></span> |
| <span class="nt"></anycast></span> |
| <span class="nt"></address></span> |
| <span class="nt"><address</span> <span class="na">name=</span><span class="s">"queues.B"</span><span class="nt">></span> |
| <span class="nt"><anycast></span> |
| <span class="nt"><queue</span> <span class="na">name=</span><span class="s">"localQueueB"</span><span class="nt">/></span> |
| <span class="nt"></anycast></span> |
| <span class="nt"></address></span> |
| <span class="nt"></addresses></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Using queue names:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://HOST:PORT"</span> <span class="na">name=</span><span class="s">"other-server"</span><span class="nt">></span> |
| <span class="nt"><receiver</span> <span class="na">queue-name=</span><span class="s">"remoteQueueA"</span><span class="nt">/></span> |
| <span class="nt"><sender</span> <span class="na">queue-name=</span><span class="s">"localQueueB"</span><span class="nt">/></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span> |
| |
| <span class="nt"><addresses></span> |
| <span class="nt"><address</span> <span class="na">name=</span><span class="s">"remotequeues.A"</span><span class="nt">></span> |
| <span class="nt"><anycast></span> |
| <span class="nt"><queue</span> <span class="na">name=</span><span class="s">"remoteQueueA"</span><span class="nt">/></span> |
| <span class="nt"></anycast></span> |
| <span class="nt"></address></span> |
| <span class="nt"><address</span> <span class="na">name=</span><span class="s">"queues.B"</span><span class="nt">></span> |
| <span class="nt"><anycast></span> |
| <span class="nt"><queue</span> <span class="na">name=</span><span class="s">"localQueueB"</span><span class="nt">/></span> |
| <span class="nt"></anycast></span> |
| <span class="nt"></address></span> |
| <span class="nt"></addresses></span></code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| Receivers can only be matched to a local queue that already exists. |
| Therefore, if receivers are being used, ensure that queues are pre-created locally. |
| Otherwise, the broker cannot match the remote queues and addresses. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| Do not create a sender and a receiver to the same destination. |
| This creates an infinite loop of sends and receives. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="peers"><a class="anchor" href="#peers"></a><a class="link" href="#peers">8. Peers</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The broker can be configured as a peer which connects to the <a href="https://qpid.apache.org/components/dispatch-router/">Apache Qpid Dispatch Router</a> and instructs it that the broker will act as a store-and-forward queue for a given AMQP waypoint address configured on the router. |
| In this scenario, clients connect to a router to send and receive messages using a waypointed address, and the router routes these messages to or from the queue on the broker.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The peer configuration causes ActiveMQ Artemis to create a sender and receiver pair for each destination matched in the broker-connection configuration, with these carrying special configuration to let Qpid Dispatch know to collaborate with the broker. |
| This replaces the traditional need of a router-initiated connection and auto-links.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Qpid Dispatch Router offers a lot of advanced networking options that be used together with ActiveMQ Artemis.</p> |
| </div> |
| <div class="paragraph"> |
| <p>With a peer configuration, the same properties are present as when there are senders and receivers. |
| For example, a configuration where queues with names beginning "queue." act as storage for the matching router waypoint address would be:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://HOST:PORT"</span> <span class="na">name=</span><span class="s">"router"</span><span class="nt">></span> |
| <span class="nt"><peer</span> <span class="na">address-match=</span><span class="s">"queues.#"</span><span class="nt">/></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span> |
| |
| <span class="nt"><addresses></span> |
| <span class="nt"><address</span> <span class="na">name=</span><span class="s">"queues.A"</span><span class="nt">></span> |
| <span class="nt"><anycast></span> |
| <span class="nt"><queue</span> <span class="na">name=</span><span class="s">"queues.A"</span><span class="nt">/></span> |
| <span class="nt"></anycast></span> |
| <span class="nt"></address></span> |
| <span class="nt"><address</span> <span class="na">name=</span><span class="s">"queues.B"</span><span class="nt">></span> |
| <span class="nt"><anycast></span> |
| <span class="nt"><queue</span> <span class="na">name=</span><span class="s">"queues.B"</span><span class="nt">/></span> |
| <span class="nt"></anycast></span> |
| <span class="nt"></address></span> |
| <span class="nt"></addresses></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>There must be a matching address waypoint configuration on the router instructing it that the particular router addresses the broker attaches to should be treated as waypoints. |
| For example, a similar prefix- based router address configuration would be:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="nowrap">address { |
| prefix: queue |
| waypoint: yes |
| }</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For more information refer to the "brokered messaging" documentation for <a href="https://qpid.apache.org/components/dispatch-router/">Apache Qpid Dispatch Router</a>.</p> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| Do not use this feature to connect to another broker, otherwise any message sent will be immediately ready to consume creating an infinite echo of sends and receives. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| It is not necessary to configure the router with a connector or auto-links to communicate with the broker. |
| The brokers peer configuration replaces these aspects of the router waypoint usage. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="address-consideration"><a class="anchor" href="#address-consideration"></a><a class="link" href="#address-consideration">9. Address Consideration</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>It is highly recommended that <code>address name</code> and <code>queue name</code> are the same. |
| When a queue with its distinct name (as in the following example) is used, senders and receivers will always use the <code>address name</code> when creating the remote endpoint.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://HOST:PORT"</span> <span class="na">name=</span><span class="s">"other-server"</span><span class="nt">></span> |
| <span class="nt"><sender</span> <span class="na">address-match=</span><span class="s">"queues.#"</span><span class="nt">/></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span> |
| <span class="nt"><addresses></span> |
| <span class="nt"><address</span> <span class="na">name=</span><span class="s">"queues.A"</span><span class="nt">></span> |
| <span class="nt"><anycast></span> |
| <span class="nt"><queue</span> <span class="na">name=</span><span class="s">"distinctNameQueue.A"</span><span class="nt">/></span> |
| <span class="nt"></anycast></span> |
| <span class="nt"></address></span> |
| <span class="nt"></addresses></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the above example the <code>broker connection</code> would create an AMQP sender towards "queues.A".</p> |
| </div> |
| <div class="admonitionblock important"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-important" title="Important"></i> |
| </td> |
| <td class="content"> |
| To avoid confusion it is recommended that <code>address name</code> and <code>queue name</code> are kept the same. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="federation"><a class="anchor" href="#federation"></a><a class="link" href="#federation">10. Federation</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Broker federation allows the local broker to create remote receivers for addresses or queues that have local demand, conversely the broker connection can send federation configuration to the remote broker causing it to create receivers on the local broker based on remote demand on an address or queue over this same connection.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Add a <code><federation></code> element within the <code><amqp-connection></code> element to configure federation to the broker instance, the <code><amqp-connection></code> contains all the configuration for authentication and reconnection handling, see the above sections to configure those values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The broker connection federation configuration consists of one or more policies that define either local or remote federation configurations for addresses or queues.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://HOST:PORT"</span> <span class="na">name=</span><span class="s">"federation-example"</span><span class="nt">></span> |
| <span class="nt"><federation></span> |
| <span class="nt"><local-address-policy</span> <span class="na">name=</span><span class="s">"example-local-address-policy"</span><span class="nt">></span> |
| <span class="nt"><include</span> <span class="na">address-match=</span><span class="s">"local-address.#"</span> <span class="nt">/></span> |
| <span class="nt"><exclude</span> <span class="na">address-match=</span><span class="s">"local-address.excluded"</span> <span class="nt">/></span> |
| <span class="nt"></local-address-policy></span> |
| <span class="nt"><local-queue-policy</span> <span class="na">name=</span><span class="s">"example-local-queue-policy"</span><span class="nt">></span> |
| <span class="nt"><include</span> <span class="na">address-match=</span><span class="s">"address"</span> <span class="na">queue-match=</span><span class="s">"local-queue"</span> <span class="nt">/></span> |
| <span class="nt"></local-queue-policy></span> |
| <span class="nt"><remote-address-policy</span> <span class="na">name=</span><span class="s">"example-remote-address-policy"</span><span class="nt">></span> |
| <span class="nt"><include</span> <span class="na">address-match=</span><span class="s">"remote-address"</span> <span class="nt">/></span> |
| <span class="nt"></remote-address-policy></span> |
| <span class="nt"><remote-queue-policy</span> <span class="na">name=</span><span class="s">"example-remote-queue-policy"</span><span class="nt">></span> |
| <span class="nt"><include</span> <span class="na">address-match=</span><span class="s">"#"</span> <span class="na">queue-match=</span><span class="s">"remote-queue"</span> <span class="nt">/></span> |
| <span class="nt"><exclude</span> <span class="na">address-match=</span><span class="s">"excluded.#"</span> <span class="na">queue-match=</span><span class="s">"remote-queue-excluded"</span> <span class="nt">/></span> |
| <span class="nt"></remote-queue-policy></span> |
| <span class="nt"></federation></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span></code></pre> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="local-and-remote-address-federation"><a class="anchor" href="#local-and-remote-address-federation"></a><a class="link" href="#local-and-remote-address-federation">Local and remote address federation</a></h5> |
| <div class="paragraph"> |
| <p>Local or Remote address federation configures the local or remote broker to watch for demand on addresses and when demand exists it will create a consumer on the matching address on the opposing broker. Because the consumers are created on addresses on the opposing broker the authentication credentials supplied to the broker connection must have sufficient access to read from (local address federation) or write to the matching address (remote address federation) on the opposing broker.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An example of address federation configuration is shown below, the local and remote address policies have identical configuration parameters only the policy element names are different.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://HOST:PORT"</span> <span class="na">name=</span><span class="s">"federation-example"</span><span class="nt">></span> |
| <span class="nt"><federation></span> |
| <span class="nt"><local-address-policy</span> <span class="na">name=</span><span class="s">"example-local-address-policy"</span> |
| <span class="na">auto-delete=</span><span class="s">"false"</span> |
| <span class="na">auto-delete-delay=</span><span class="s">"1"</span> |
| <span class="na">auto-delete-message-count=</span><span class="s">"12"</span> |
| <span class="na">max-hops=</span><span class="s">"1"</span> |
| <span class="na">enable-divert-bindings=</span><span class="s">"true"</span><span class="nt">></span> |
| <span class="nt"><include</span> <span class="na">address-match=</span><span class="s">"local-address.#"</span> <span class="nt">/></span> |
| <span class="nt"><exclude</span> <span class="na">address-match=</span><span class="s">"local-address.excluded"</span> <span class="nt">/></span> |
| <span class="nt"></local-address-policy></span> |
| <span class="nt"></federation></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span></code></pre> |
| </div> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">name</dt> |
| <dd> |
| <p>The name of the policy, these names should be unique within a broker connection’s federation policy elements.</p> |
| </dd> |
| <dt class="hdlist1">include</dt> |
| <dd> |
| <p>The address-match pattern to use to match included addresses, multiple of these can be set. If none are set all addresses are matched.</p> |
| </dd> |
| <dt class="hdlist1">exclude</dt> |
| <dd> |
| <p>The address-match pattern to use to match excluded addresses, multiple of these can be set or it can be omitted if no excludes are needed.</p> |
| </dd> |
| <dt class="hdlist1">max-hops</dt> |
| <dd> |
| <p>The number of hops that a message can have made for it to be federated, the default value is zero and will work for most simple federatio0n deployments however is certain topologies a higher value may be required to prevent looping.</p> |
| </dd> |
| <dt class="hdlist1">auto-delete</dt> |
| <dd> |
| <p>For address federation, a durable queue is created on the opposing broker for the matching address. This option is used to mark if the queue should be deleted once the initiating broker disconnects, and the delay and message count parameters have been met. This is useful if you want to automate the clean up, though you may wish to disable this if you want messages to queued for the opposing broker when it disconnects. The default value is <code>false</code> and the federation consumer queue will not be auto deleted.</p> |
| </dd> |
| <dt class="hdlist1">auto-delete-delay</dt> |
| <dd> |
| <p>The amount of time in milliseconds after the initiating broker has disconnected before the created queue can be eligible for <code>auto-delete</code>. The default value is zero if the option is omitted.</p> |
| </dd> |
| <dt class="hdlist1">auto-delete-message-count</dt> |
| <dd> |
| <p>The amount number messages in the remote queue that the message count must be equal or below before the initiating broker has disconnected before the queue can be eligible for auto deletion. The default value is zero if the option is omitted.</p> |
| </dd> |
| <dt class="hdlist1">enable-divert-bindings</dt> |
| <dd> |
| <p>Setting to true will enable divert bindings to be listened for demand. If there is a divert binding with an address that matches the included addresses for the federation, any queue bindings that match the forward address of the divert will create demand. The default value for this option is <code>false</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="local-and-remote-queue-federation"><a class="anchor" href="#local-and-remote-queue-federation"></a><a class="link" href="#local-and-remote-queue-federation">Local and remote queue federation</a></h5> |
| <div class="paragraph"> |
| <p>Local or Remote queue federation configures the local or remote broker to watch for demand on queues and when demand exists it will create a consumer on the matching queue on the opposing broker. Because the consumers are created on queues on the opposing broker the authentication credentials supplied to the broker connection must have sufficient access to read from (local queue federation) or write to the matching queue (remote queue federation) on the opposing broker.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An example of queue federation configuration is shown below, the local and remote queue policies have identical configuration parameters only the policy element names are different.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><broker-connections></span> |
| <span class="nt"><amqp-connection</span> <span class="na">uri=</span><span class="s">"tcp://HOST:PORT"</span> <span class="na">name=</span><span class="s">"federation-example"</span><span class="nt">></span> |
| <span class="nt"><federation></span> |
| <span class="nt"><local-queue-policy</span> <span class="na">name=</span><span class="s">"example-local-queue-policy"</span><span class="nt">></span> |
| <span class="nt"><include</span> <span class="na">address-match=</span><span class="s">"#"</span> <span class="na">queue-match=</span><span class="s">"remote-queue"</span> <span class="nt">/></span> |
| <span class="nt"><exclude</span> <span class="na">address-match=</span><span class="s">"excluded.#"</span> <span class="na">queue-match=</span><span class="s">"remote-queue-excluded"</span> <span class="nt">/></span> |
| <span class="nt"></local-queue-policy></span> |
| <span class="nt"></federation></span> |
| <span class="nt"></amqp-connection></span> |
| <span class="nt"></broker-connections></span></code></pre> |
| </div> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">name</dt> |
| <dd> |
| <p>The name of the policy, these names should be unique within a broker connection’s federation policy elements.</p> |
| </dd> |
| <dt class="hdlist1">include</dt> |
| <dd> |
| <p>The queue-match pattern to use to match included queues, multiple of these can be set. If none are set all queues are matched.</p> |
| </dd> |
| <dt class="hdlist1">exclude</dt> |
| <dd> |
| <p>The queue-match pattern to use to match excluded queues, multiple of these can be set or it can be omitted if no excludes are needed.</p> |
| </dd> |
| <dt class="hdlist1">priority-adjustment</dt> |
| <dd> |
| <p>When federation consumers are created this value can be used to ensure that those federation consumers have a lower priority value than other local consumers on the same queue. The default value for this configuration option if not set is <code>-1</code>.</p> |
| </dd> |
| <dt class="hdlist1">include-federated</dt> |
| <dd> |
| <p>Controls if consumers on a queue which come from federation instances should be counted when observing a queue for demand, by default this value is <code>false</code> and federation consumers are not counted.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
