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.
RabbitMQ Web MQTT plugin is rather simple. It takes the MQTT protocol, as provided by RabbitMQ MQTT plugin and exposes it using WebSockets.
rabbitmq_web_mqtt plugin ships with RabbitMQ.
To enable the plugin run rabbitmq-plugins:
rabbitmq-plugins enable rabbitmq_web_mqtt
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);
[...]
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:
We encourage you to take a look at the source code.
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.
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.
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
See RabbitMQ TLS and TLS Troubleshooting for additional information.
The Web MQTT plugin supports the proxy protocol. This feature is disabled by default, to enable it for MQTT clients:
web_mqtt.proxy_protocol = true
See the Networking Guide for more information about the proxy protocol.
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.
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 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
