| <div class="wiki-content maincontent"><p>ActiveMQ supports the <a shape="rect" href="http://mqtt.org/">MQTT</a> protocol and will automatically map between JMS/NMS and MQTT clients. MQTT is a machine-to-machine (M2M) publish/subscribe messaging transport.</p><p>Please see the <a shape="rect" href="http://mqtt.org/">MQTT site</a> for more details</p><h3>Enabling the ActiveMQ Broker for MQTT</h3><p>Its very easy to enable ActiveMQ for MQTT. Just add a connector to the broker using the MQTT URL.</p><structured-macro ac:macro-id="5ca47482-4078-4d5b-8aa5-c5d38fd2ce38" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body><transportConnectors> |
| <transportConnector name="mqtt" uri="mqtt://localhost:1883"/> |
| </transportConnectors> |
| </plain-text-body></structured-macro><h3>The MQTT Wire Format</h3><p>MQTT uses a compact binary format that can be configured with the following options.  All options can be configured on a Brokers transport bind URI.</p><table><tbody><tr><th colspan="1" rowspan="1"><p>Parameter Name</p></th><th colspan="1" rowspan="1"><p>Default Value</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p>maxFrameSize</p></td><td colspan="1" rowspan="1"><p>268435456</p></td><td colspan="1" rowspan="1"><p>(v5.12.0) Maximum frame size that can be sent. The protocol limit is 256 megabytes and his value cannot be set higher. Can help help prevent OOM DOS attacks</p></td></tr></tbody></table><p>All options must be prepended with <code>wireFormat</code> in order to take effect. Without this proper formatting, the option will have zero effect.</p><h4>Example Wire Format Configuration<br clear="none"> </h4><structured-macro ac:macro-id="f4b97772-e19f-4dcd-953f-1e24e1cdcddb" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body> <transportConnector name="mqtt" uri="mqtt://localhost:61612?wireFormat.maxFrameSize=100000"/></plain-text-body></structured-macro><h3>Security</h3><p>The ActiveMQ MQTT Transport implementation fully supports an <link><page ri:content-title="Security"></page><plain-text-link-body>ActiveMQ security</plain-text-link-body></link> mechanism. Also, the authorization policies will be applied when you try to access (read/write) certain destinations.</p><h3>Enabling MQTT over NIO</h3><p>For better scalability (and performance) you might want to run the MQTT protocol over NIO transport. To do that just use <code>mqtt+nio</code> transport prefix instead of <code>matt</code>. For example, add the following transport configuration in your XML file</p><structured-macro ac:macro-id="3f6debc9-051a-489c-8da4-bf2aa33a92e6" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body> <transportConnector name="mqtt+nio" uri="mqtt+nio://localhost:1883"/> |
| </plain-text-body></structured-macro><p>This transport use <a shape="rect" href="http://activemq.apache.org/configuring-transports.html#ConfiguringTransports-TheNIOTransport">NIO transport</a> underneath and will generally use much less threads than standard connector.</p><h3>Enabling MQTT over NIO + SSL</h3><p>The MQTT transport also supports using NIO and SSL. To enable this option, use the mqtt+nio+ssl protocol - e.g.</p><structured-macro ac:macro-id="83b650b0-944c-44ec-b16f-b19f9a4d7a91" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body> <transportConnector name="mqtt+nio" uri="mqtt+nio+ssl://localhost:1883"/> |
| </plain-text-body></structured-macro><ul><li>For more details on using SSL with ActiveMQ see the following article (<a shape="rect" href="http://activemq.apache.org/how-do-i-use-ssl.html">How do I use SSL</a>).</li></ul><h3>Working with Destinations with MQTT</h3><p>MQTT supports hierarchies and wildcards, though the delimiters and characters are different: - Here's the mapping:</p><table><tbody><tr><th colspan="1" rowspan="1"><p>function</p></th><th colspan="1" rowspan="1"><p>ActiveMQ</p></th><th colspan="1" rowspan="1"><p>MQTT</p></th></tr><tr><td colspan="1" rowspan="1"><p>separator</p></td><td colspan="1" rowspan="1"><p><code>.</code></p></td><td colspan="1" rowspan="1"><p><code>/</code></p></td></tr><tr><td colspan="1" rowspan="1"><p>element</p></td><td colspan="1" rowspan="1"><p><code>*</code></p></td><td colspan="1" rowspan="1"><p><code>+<br clear="none"></code></p></td></tr><tr><td colspan="1" rowspan="1"><p>sub tree</p></td><td colspan="1" rowspan="1"><p><code>></code></p></td><td colspan="1" rowspan="1"><p><code>#<br clear="none"></code></p></td></tr></tbody></table><p>These values are automatically transposed between clients using JMS/NMS/Stomp and clients using MQTTT. For example - a client subscribing to "foo/#/bar" would receive messages published on a JMS Topic of foo.blah.bar.</p><h3>Message transformations</h3><p>MQTT messages are transformed into an JMS ByteMessage. Conversely, the body of any JMS Message is converted to a byte buffer to be the payload of an MQTT message.</p><h3>Keep Alive</h3><p>When a client connects, it will send a keep-alive duration, usually defaulting to 10s. ActiveMQ will honor the keep-alive duration by setting up an Inactivity Monitor that allows a grace period of 1.5 * duration. After that grace period duration elapses a connection could be closed if there is no activity. A broker receiving a PINGREQ and sending PINGRESP is considered activity to keep the connection opened.</p><p>If a client sends a keep-alive value of 0, ActiveMQ will not set up an <a shape="rect" href="http://activemq.apache.org/activemq-inactivitymonitor.html">Inactivity Monitor</a> and connections will not be auto-shutdown due to inactivity. This however can lead to potentially leaky connections, so a default keep alive can be set on the server side (by an admin, for example) to not allow inactive connections to hang. This default keep alive would only be used if specified and if the client requests a keep-alive value of 0. The unit for the keep-alive value is milliseconds.</p><p>To enable a default, server-side MQTT keep alive:</p><structured-macro ac:macro-id="a20c277a-bf57-4cc0-99b0-0cd758bd8ba0" ac:name="code" ac:schema-version="1"><parameter ac:name="">xml</parameter><plain-text-body><transportConnector name="mqtt" uri="mqtt://localhost:1883?transport.defaultKeepAlive=60000"/></plain-text-body></structured-macro><h3>Message Prefetch</h3><p>When MQTT client connects, it locally create JMS-like consumer to the broker. In older versions this consumer was created with the prefetch size of 1 (message prefetching is explained <link><page ri:content-title="What is the Prefetch Limit For?"></page><plain-text-link-body>here</plain-text-link-body></link> in more details). Starting with 5.11.0 release, the prefetch size is adjusted to the default value for the appropriate JMS subscription. QoS=0 subscriptions have default prefetch of regular non-persistent topic subscriptions, while QoS=1 and QoS=2 are assigned prefetch size of durable subscribers or the queue subscriptions depending on the subscription strategy used (see the next section for more details). Default prefetch values are listed <link><page ri:content-title="What is the Prefetch Limit For?"></page><plain-text-link-body>here</plain-text-link-body></link>.</p><p>To change default value of the prefetch size, you can use <em>activeMQSubscriptionPrefetch</em> transport option, like</p><structured-macro ac:macro-id="69dfafe2-0ff1-4fdd-9d14-90f22a1fd44f" ac:name="code" ac:schema-version="1"><plain-text-body><transportConnector name="mqtt" uri="mqtt://localhost:1883?transport.activeMQSubscriptionPrefetch=32766"/></plain-text-body></structured-macro><h3>Subscription Strategy</h3><p>ActiveMQ is a JMS broker in its core, so there needs to be some mapping between MQTT subscriptions and JMS semantics. Subscriptions with QoS=0 (At Most Once) are directly mapped to plain JMS non-persistent topics. For reliable messaging, QoS=1 and QoS=2, by default subscriptions are transformed to JMS durable topic subscribers. This behaviour is desired in most scenarios. For some use cases, it is useful to map these subscriptions to <link><page ri:content-title="Virtual Destinations"></page><plain-text-link-body>virtual topics</plain-text-link-body></link>. Virtual topics provide a better scalability and are generally better solution if you want to use you MQTT subscribers over network of brokers. To change subscription strategy to use virtual topic, use the following settings:</p><structured-macro ac:macro-id="cd76f597-a8ac-46b9-94ed-9ea6ed141e6b" ac:name="code" ac:schema-version="1"><plain-text-body><transportConnector name="mqtt" uri="mqtt://localhost:1883?transport.subscriptionStrategy=mqtt-virtual-topic-subscriptions"/></plain-text-body></structured-macro><h3>Retained Messages</h3><p>If a message has been published with the <em>retain</em> flag set, then the message will be 'remembered' by the topic so that if a new subscription arrives, the last retained message is sent to the subscription. Underneath, the broker uses <link><page ri:content-title="Subscription Recovery Policy"></page><plain-text-link-body>retained message subscription recovery policy</plain-text-link-body></link> to retain messages with <em>ActiveMQ.Retain</em> property set. During the message conversion, MQTT messages with retain flag become JMS message with the <em>ActiveMQ.Retain </em>property set and retained by the broker.</p></div> |
