MQTT Adapter

I've written a plugin for RabbitMQ that adds support for the MQTT 3.1 protocol. MQ Telemetry Transport is a light-weight PUB/SUB protocol designed for resource-constrained devices and limited bandwidth situations, making it ideally suited to sensors and mobile devices. The implementation is a protocol adapter  plugin, allowing MQTT clients to connect to a RabbitMQ broker simultaneously with clients implementing other protocols. We encourage projects that demand the combination of a low-overhead protocol on a robust, scalable broker with high reliability and enterprise features to consider this option.

Supported features

QoS 0 and QoS 1
The MQTT adapter supports QoS 0 (at most once) and QoS 1 (at least once) semantics. In MQTT QoS relates to transport assurance as well as persistence - the plugin honours both. While clients are permitted to request QoS 2 subscriptions, the adapter will only grant subscriptions up to QoS 1.
Last Will and Testament (LWT)
Clients can provide a LWT message during connection that will only be published if the client disconnects unexpectedly, e.g. due to a network failure.
Sticky sessions
Clients can make use of sticky (or non-clean) sessions to ensure they receive messages that were published whilst they were disconnected.
Default logins
Default authentication details can be optionally be configured so that the MQTT adapter authenticates to the RabbitMQ broker as a default user in case a connecting MQTT client provides no login details.

Extended features

While not explicitly enumerated, all core broker features are available to MQTT clients.

MQTT subscription wildcards are limited in that they may only appear as a suffix. AMQP topics are not limited in this way, so wildcards can appear in any position. The MQTT adapter implements the more flexible AMQP patterns, but with MQTT syntax.

The MQTT specification does not mention SSL or any interaction between SSL and authentication. The MQTT adapter includes SSL capability now, with the possibility of integrating  certificates with authentication on the future.

The MQTT concept of "bridging" can be realised with RabbitMQ's federation by federating the exchanges that the MQTT adapter publishes to.

Future features

AMQP 0-9-1 does not define "exactly once" semantics for message delivery. For this reason the MQTT adapter does not support publishing messages at the QoS 2 (exactly once) level, or exchanging PUBREC, PUBREL or PUBCOMP messages with clients.

"Retained  messages" is an MQTT feature where the broker retains flagged messages and delivers them to future subscribing clients. E.g. in a topic for sensor readings, a retained message allows a client to receive the last reading without  needing to wait for the next reading. By default AMQP 0-9-1 exchanges do not retain any message state. Therefore the MQTT adapter makes no attempt to honour the "Retained" flag, which will be silently ignored.

These are areas where we are especially interested in obtaining feedback from the community. There is scope to enhance the core broker with these features not only for MQTT clients, but potentially for (extended) AMQP and other clients as well - provided there is sufficient demand.

Interoperability with other MQTT implementations

The MQTT adapter has been successfully tested with the MQTT clients of the following products, when restricting operation to the supported features:

  • Really Small Message Broker
  • Mosquitto
  • Paho
  • WebSphere MQ

Interoperability with other protocols

The MQTT adapter uses one configurable exchange for publishing, and subscriptions are implemented as AMQP bindings. In combination these allow interoperability with any clients that know the name of the exchange or the topics used by MQTT clients.


First make sure you have  rabbitmq-server 2.8.6 installed. (The plugin should also be compatible with other v2.8.x releases.)

The MQTT adapter is currently available as a preview release. You must download and install the plugin manually until it  is included as a regular plugin in a future release. The plugin can be downloaded from the preview release downloads, e.g.


The *.ez file must be copied to the plugins directory. On my Debian-based workstation this is in /usr/lib/rabbitmq/lib/rabbitmq_server-2.8.6/plugins:

 sudo cp rabbitmq_mqtt-2.8.6.ez /usr/lib/rabbitmq/lib/rabbitmq_server-2.8.6/plugins

Enable the plugin using rabbitmq-plugins:

 sudo rabbitmq-plugins enable rabbitmq_mqtt

Restart the rabbitmq server

 sudo /etc/init.d/rabbitmq-server restart 

The broker logfile should now include a new line indicating that it is ready to accept MQTT connections:

  =INFO REPORT==== 12-Sep-2012::14:21:26 ===
  started MQTT TCP Listener on [::]:1883

The default configuration options should work fine  in most cases. A description of all configuration options is included in the readme. You will need to provide further configuration if you wish to set up SSL, or define a different exchange in order to facilitate federation.

You can now try to execute the included tests (based on the Java Paho client library), or your own MQTT application.

See the contact page for details on how to provide feedback.

17 Responses to “MQTT Adapter”

  1. KongNan Says:

    For safety, hope rabbitmqmqtt can be configured as rabbitmq Write Read permissions.Currently rabbitmqmqtt unsafe, have a user name and password can easily be exploited, malicious push spam.

  2. Emile Joubert Says:

    The MQTT adapter inherits access control features from the broker. This makes it possible to grant read permission without write permission.

  3. TM Says:

    Regarding the 'Future Features' - these would be a huge win for RabbitMQ. Currently MQTT is one of the best protocols for exchanging data with field devices over low bandwidth/high latency links, being able to stream that data to enterprise systems through Rabbit makes it a much more powerful contender...

  4. Emile Joubert Says:

    UPDATE: The MQTT plugin is included in the official release since release 3.0.0 and can be enabled in same way as any other released plugin. The installation steps described in this blog post are only necessary if you are using version 2.8.x of the broker.

  5. Michel Says:

    Hello from Paris,

    I tested the 'included tests' , all is green when I run junit but no message arrive to Rabbitmq server and the server log file gives :

    =ERROR REPORT==== 12-Jan-2013::01:08:13 ===
    connection <0.5360.0>, channel 1 - soft error:
    "no queue 'mqtt-subscription-MqttTest7856-2qos1' in vhost '/'",

    Thanks in advance.


  6. Emile Joubert Says:

    I'm not able to reproduce. Can you please post details of your environment to the rabbitmq-discuss mailing list? Thanks

  7. Pritesh Patel Says:

    I'm getting this same error. Has there been any progress in figuring out what causes this?

  8. Pritesh Patel Says:

    This is what my logs show. I'm using the Paho client.

    =INFO REPORT==== 14-Mar-2013::22:18:40 ===
    accepting MQTT connection ( ->

    =ERROR REPORT==== 14-Mar-2013::22:18:40 ===
    connection <0.559.0>, channel 1 - soft error:
    "no queue 'mqtt-subscription-SampleJavaV3_publishqos1' in vhost '/'",

    =WARNING REPORT==== 14-Mar-2013::22:18:40 ===
    MQTT disconnect from "SampleJavaV3_publish"

  9. Andrew Ralston Says:

    I had to create my rabbitmq.config to get this example working. Look at the configuration closely - I had accidentally put amp.topic instead of amq.topic when I was typing this config... oops!

    Config is available here:

  10. Andrew Ralston Says:

    Is there any way to guarantee messages are written to disk with MQTT? I understand that QoS level 1 or 2 will cause RabbitMQ to persist the message. From above: "In MQTT QoS relates to transport assurance as well as persistence - the plugin honours both."

    However, as indicated on the Publisher Confirms page: "In RabbitMQ, a persistent message is one that should survive a broker restart. The operative word here is should, since the message can still be lost if broker goes down before it's had a chance to write the message to disk." Reference:

    Given this, is it possible to truly guarantee a message is persisted to disk when using MQTT? I don't see MQTT providing a mechanism to enable publisher confirms or transactions like AMQP. If this is right, perhaps all MQTT messages could be transactional? Possibly this is a potential use of the PUBREC, PUBREL or PUBCOMP messages if the RabbitMQ would want to deviate from the MQTT spec? I know there are a few other subtle differences in the RabbitMQ implementation...

    However it's done, I need to be able to guarantee that a message is persisted to disk before the client removes their copy of the message.

  11. Emile Joubert Says:

    QoS1 messages are persisted to disk. The MQTT adapter makes use of publisher confirms internally to make this guarantee. QoS2 and the related messages types are not supported and not required to guarantee persistence.

  12. error Says:

    =INFO REPORT==== 15-Apr-2013::12:55:01 ===
    accepting MQTT connection ( ->

    =ERROR REPORT==== 15-Apr-2013::12:55:01 ===
    connection <0.330.0>, channel 1 - soft error:
    "no queue 'mqtt-subscription-MQTT_Utilityqos1' in vhost '/'",

    User: guest
    RabbitMQ 3.0.4, Erlang R16B

    Error from windows7 64bit And windows server 2003

    but CentOS6.4 not error!

  13. error Says:

    After repeated version is replaced

    User: guest
    RabbitMQ 3.0.4, Erlang R15B01

    mqtt-adapter Normal operation by Erlang R15B01!

  14. Axium Says:

    I'm getting this error also. Did you guys find out a solution ?

  15. Emile Joubert Says:

    You can ignore soft channel errors generated by the adapter. Please direct further questions to the rabbitmq-discuss mailing list.

  16. Kiesha Corazza Says:

    thanks for the help, I like many others on here was getting errors too but managed to sort it finally.

  17. Simon Says:

    thanks for the post! Are there any news about the future feature "Retained messages"?