Menu

RabbitMQ Web MQTT Plugin

The Web MQTT plugin is a simple bridge exposing the MQTT protocol over HTML5 WebSockets.

The main intention of Web MQTT is to make it possible to use RabbitMQ from web browsers. It was heavily inspired by the Web STOMP plugin.

How It Works

RabbitMQ Web MQTT plugin is rather simple. It takes the MQTT protocol, as provided by RabbitMQ MQTT plugin and exposes it using WebSockets. Note that unlike Web STOMP, this plugin does not provide WebSocket emulation via SockJS.

Installation and Enabling the Plugin

rabbitmq_web_mqtt plugin ships with RabbitMQ as of 3.6.7.

To enable the plugin run rabbitmq-plugins:

rabbitmq-plugins enable rabbitmq_web_mqtt

Usage

In order to use MQTT in a Web browser context, a JavaScript MQTT library is required. We've tested it against Paho JavaScript client. It is included as part of RabbitMQ Web MQTT example plugin.

By default the Web MQTT plugin exposes a WebSocket endpoint on port 15675. The WebSocket endpoint is available on the /ws path:

http://127.0.0.1:15675/ws

In order to establish connection from the browser using WebSocket you may use code like:

<!-- include the client library -->
<script src="mqttws31.js"></script>
<script>

    var wsbroker = location.hostname;  // mqtt websocket enabled broker
    var wsport = 15675; // port for above
    var client = new Paho.MQTT.Client(wsbroker, wsport, "/ws",
        "myclientid_" + parseInt(Math.random() * 100, 10));
    client.onConnectionLost = function (responseObject) {
        debug("CONNECTION LOST - " + responseObject.errorMessage);
    };
    client.onMessageArrived = function (message) {
        debug("RECEIVE ON " + message.destinationName + " PAYLOAD " + message.payloadString);
        print_first(message.payloadString);
    };
...

Once you have the client object you can follow API's exposed by Paho JavaScript library. The next step is usually to establish a MQTT connection with the broker:

[...]

var options = {
    timeout: 3,
    onSuccess: function () {
        debug("CONNECTION SUCCESS");
        client.subscribe('/topic/test', {qos: 1});
    },
    onFailure: function (message) {
        debug("CONNECTION FAILURE - " + message.errorMessage);
    }
};
if (location.protocol == "https:") {
    options.useSSL = true;
}
debug("CONNECT TO " + wsbroker + ":" + wsport);
client.connect(options);
[...]

Web MQTT Examples

A few simple Web MQTT examples are provided as a RabbitMQ Web MQTT examples plugin. To get it running follow the installation instructions for that plugin and enable the plugin:

rabbitmq-plugins enable rabbitmq_web_mqtt_examples

The examples will be available under http://127.0.0.1:15670/ url. You will see two examples:

  • "echo" - shows how to use MQTT to do simple message broadcasting
  • "bunny" - example of a simple collaboration canvas painting app

We encourage you to take a look at the source code.

Configuration

When no configuration is specified the Web MQTT plugin will listen on all interfaces on port 15674 and have a default user login and password of guest/guest. Note that this user is only allowed to connect from localhost by default. We highly recommend creating a separate user production systems.

To change this, edit your Configuration file, to contain a port variable for the rabbitmq_web_mqtt application.

For example, a complete configuration file which changes the listener port to 12345 would look like:

[
  {rabbitmq_web_mqtt, [{port, 12345}]}
].

This is a shorthand for the following:

[
  {rabbitmq_web_mqtt,
      [{tcp_config, [{port, 12345}]}]}
].

You can use the tcp_config section to specify any TCP option you need. When both a port and a tcp_config sections exist, the plugin will use the former as a port number, ignoring the one in tcp_config.

See RabbitMQ Networking guide for more information.

TLS (SSL)

The plugin supports WebSockets with TLS (WSS) connections. That requires Erlang/OTP 17.5 or a later version.

TLS (SSL) configuration parameters are provided in the ssl_config section:

[
  {rabbitmq_web_mqtt,
      [{ssl_config, [{port,       15671},
                     {backlog,    1024},
                     {certfile,   "path/to/certs/client/cert.pem"},
                     {keyfile,    "path/to/certs/client/key.pem"},
                     {cacertfile, "path/to/certs/testca/cacert.pem"},
                     %% needed when private key has a passphrase
                     {password,   "changeme"}]}]}
].

Note that port, certfile, keyfile and password are all mandatory. See the Cowboy documentation for details about accepted parameters.

See RabbitMQ TLS and TLS Troubleshooting for details.

WebSocket Options

The Web MQTT plugin uses the Cowboy web server under the hood. Cowboy provides a number of options that can be used to customize the behavior of the server w.r.t. WebSocket connection handling. You can specify those in the Web MQTT plugin configuration, in the cowboy_opts section:

[
  {rabbitmq_web_mqtt,
      [{cowboy_opts, [{max_keepalive, 10}]}]}
].