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.

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,
    keepAliveInterval: 30,
    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:

web_mqtt.tcp.port = 15675

Or using the classic config format:

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

This is a shorthand for the following:

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

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 (WSS)

The plugin supports WebSocket connections with TLS encryption (WSS connections).

TLS configuration parameters for the plugin use the web_mqtt.ssl prefix:

web_mqtt.ssl.port       = 12345
web_mqtt.ssl.backlog    = 1024
web_mqtt.ssl.certfile   = path/to/certs/client/cert.pem
web_mqtt.ssl.keyfile    = path/to/certs/client/key.pem
web_mqtt.ssl.cacertfile = path/to/certs/testca/cacert.pem
# needed when private key has a passphrase
# web_mqtt.ssl.password   = changeme

Or using the classic config format:

[
  {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"}
                    ]}]}
].

TLS listener port, server certificate file and private key file are mandatory options. An extended list of TLS settings is largely identical to those for the core server but there are some minor differences. Full list of options accepted by this plugin can be found in Ranch documentation.

Enabled TLS Versions and Cipher Suites

It is possible to configure what TLS versions and cipher suites will be used by RabbitMQ. Note that not all suites will be available on all systems.

RabbitMQ TLS guide has a section on TLS versions and another one on cipher suites. Below is an example in the advanced config format that configures cipher suites and a number of other TLS options for the Web MQTT plugin:

{rabbitmq_web_mqtt,
  [{ssl_config,
    [{cacertfile,           "/path/to/ca_certificate.pem"},
     {certfile,             "/path/to/server_certificate.pem"},
     {keyfile,              "/path/to/private_key.pem"},
     {verify,               verify_peer},
     {fail_if_no_peer_cert, true},
     {versions,             ['tlsv1.2']},
     {honor_cipher_order,   true},
     {honor_ecc_order,      true},
     {secure_renegotiate,   true},
     {ciphers,              [{rsa,aes_256_cbc,sha256},
                             {rsa,aes_128_cbc,sha256},
                             {rsa,aes_256_cbc,sha},
                             {rsa,'3des_ede_cbc',sha},
                             {rsa,aes_128_cbc,sha},
                             {rsa,des_cbc,sha}]}]
    ]
  }]
}

Troubleshooting TLS (WSS)

See RabbitMQ TLS and TLS Troubleshooting for additional information.

WebSocket Options

The Web MQTT plugin uses the Cowboy HTTP and WebSocket 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. Those can be specified using the advanced config file in thecowboy_opts section, for example:

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

Getting Help and Providing Feedback

If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.

Documentation feedback is also very welcome on the list. If you'd like to contribute an improvement to the site, its source is available on GitHub.