Skip to main content
Version: 4.0

RabbitMQ Web MQTT Plugin

Overview​

The Web MQTT plugin makes it possible to use MQTT over a WebSocket connection.

The goal of this plugin is to enable MQTT messaging in Web applications.

A similar plugin, Web STOMP plugin, makes it possible to use STOMP over WebSockets.

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.

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:

ws://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 an 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 15675 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 for production systems.

To change the listener port, 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 9001 would look like:

web_mqtt.tcp.port = 9001

See RabbitMQ Networking guide for more information.

TLS (WSS)​

The plugin supports WebSockets with TLS (WSS) connections. See TLS guide to learn more about TLS support in RabbitMQ.

TLS configuration parameters are provided in the web_mqtt.ssl section:

web_mqtt.ssl.port       = 15676
web_mqtt.ssl.backlog    = 1024
web_mqtt.ssl.cacertfile = /path/to/ca_certificate.pem
web_mqtt.ssl.certfile   = /path/to/server_certificate.pem
web_mqtt.ssl.keyfile    = /path/to/server_key.pem
# needed when private key has a passphrase
# web_mqtt.ssl.password   = changeme

The TLS listener port, server certificate file, private key and CA certificate bundle are mandatory options. Password is also mandatory if the private key uses one. An extended list of TLS settings is largely identical to those for the core server. Full list of options accepted by this plugin can be found in Ranch documentation.

A separate guide on troubleshooting TLS is also available.

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 plugin:

web_mqtt.ssl.port       = 15676
web_mqtt.ssl.backlog    = 1024
web_mqtt.ssl.certfile   = /path/to/server_certificate.pem
web_mqtt.ssl.keyfile    = /path/to/server_key.pem
web_mqtt.ssl.cacertfile = /path/to/ca_certificate_bundle.pem
web_mqtt.ssl.password   = changeme

web_mqtt.ssl.honor_cipher_order   = true
web_mqtt.ssl.honor_ecc_order      = true
web_mqtt.ssl.client_renegotiation = false
web_mqtt.ssl.secure_renegotiate   = true

web_mqtt.ssl.versions.1 = tlsv1.2
web_mqtt.ssl.versions.2 = tlsv1.1
web_mqtt.ssl.ciphers.1 = ECDHE-ECDSA-AES256-GCM-SHA384
web_mqtt.ssl.ciphers.2 = ECDHE-RSA-AES256-GCM-SHA384
web_mqtt.ssl.ciphers.3 = ECDHE-ECDSA-AES256-SHA384
web_mqtt.ssl.ciphers.4 = ECDHE-RSA-AES256-SHA384
web_mqtt.ssl.ciphers.5 = ECDH-ECDSA-AES256-GCM-SHA384
web_mqtt.ssl.ciphers.6 = ECDH-RSA-AES256-GCM-SHA384
web_mqtt.ssl.ciphers.7 = ECDH-ECDSA-AES256-SHA384
web_mqtt.ssl.ciphers.8 = ECDH-RSA-AES256-SHA384
web_mqtt.ssl.ciphers.9 = DHE-RSA-AES256-GCM-SHA384

Troubleshooting TLS (WSS)​

See RabbitMQ TLS and TLS Troubleshooting for additional information.

Proxy Protocol​

The Web MQTT plugin supports the proxy protocol. This feature is deactivated by default, to enable it for MQTT clients:

web_mqtt.proxy_protocol = true

See the Networking Guide for more information about the proxy protocol.

Advanced 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.

Some settings are generic HTTP ones, others are specific to WebSockets.

HTTP Options​

Generic HTTP server settings can be specified using web_mqtt.cowboy_opts.* keys, for example:

# connection inactivity timeout
web_mqtt.cowboy_opts.idle_timeout = 60000
# max number of pending requests allowed on a connection
web_mqtt.cowboy_opts.max_keepalive = 200
# max number of headers in a request
web_mqtt.cowboy_opts.max_headers   = 100
# max number of empty lines before request body
web_mqtt.cowboy_opts.max_empty_lines = 5
# max request line length allowed in requests
web_mqtt.cowboy_opts.max_request_line_length

WebSocket Options​

# WebSocket traffic compression is enabled by default
web_mqtt.ws_opts.compress = true

# WebSocket connection inactivity timeout
web_mqtt.ws_opts.idle_timeout = 60000

web_mqtt.ws_opts.max_frame_size = 50000