This add-on is operated by Stackhero

Mosquitto on dedicated instances, up-to-date versions and attractive prices.

Last updated March 25, 2022

Stackhero for MQTT Mosquitto provides a managed MQTT Mosquitto instance running on a fully dedicated instance to handle thousands devices easily.

The Stackhero for MQTT Mosquitto add-on provides the folowing:

• A private instance (dedicated VM)
• A dedicated public IP (v4)
• TLS encryption (aka SSL)
• Devices authentication and advanced ACLs via external API
• An automatic backup every 24 hours
• One click to update to new MQTT Mosquitto versions

There is an MQTT client library available for most languages including Ruby, Node.js, Java, Python, Clojure, and Erlang.

Provisioning the Add-on

You can attach Stackhero for MQTT Mosquitto via the CLI:

$ heroku addons:create ah-mosquitto-mqtt-stackhero --app <your app name>
-----> Adding ah-mosquitto-mqtt-stackhero to sharp-mountain-4005... done

After you provision Stackhero for MQTT Mosquitto, the STACKHERO_MOSQUITTO_HOST and STACKHERO_MOSQUITTO_URL_TLS config variables are available in your app’s configuration. They contain the URLs to connect to your MQTT Mosquitto instance.

If you’ve checked the Allow clear connections option in your Mosquitto service, the STACKHERO_MOSQUITTO_URL_CLEAR environment variable will also be available. We don’t recommend using clear connections.

You can see the content of those variables via the heroku config:get command:

$ heroku config:get STACKHERO_MOSQUITTO_URL_TLS
$ heroku config:get STACKHERO_MOSQUITTO_LOGIN
$ heroku config:get STACKHERO_MOSQUITTO_PASSWORD

Local Setup

After you provision the add-on, you must replicate its config variables locally.

Use the Heroku Local command-line tool to configure, run, and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from an .env file. Use heroku config to view your app’s config variables. Use the following command for each value that you want to add to your .env file:

$ heroku config:get <STACKHERO_MOSQUITTO_VARIABLE> -s  >> .env

For example:

$ heroku config:get STACKHERO_MOSQUITTO_URL_TLS -s  >> .env
$ heroku config:get STACKHERO_MOSQUITTO_LOGIN -s  >> .env
$ heroku config:get STACKHERO_MOSQUITTO_PASSWORD -s  >> .env

For more information, see Heroku Local.

Connect to Stackhero Dashboard

You can see your instance usage, restart your instance, and apply updates from the Stackhero dashboard. You can access the dashboard via the CLI:

$ heroku addons:open ah-mosquitto-mqtt-stackhero
Opening ah-mosquitto-mqtt-stackhero for sharp-mountain-4005

You can also visit the Heroku Dashboard, select your application, and then select Stackhero for MQTT Mosquitto from the Add-ons menu.

How to connect to Mosquitto/MQTT using mosquitto_pub and mosquitto_sub

Mosquitto pub/sub CLIs are useful to make some tests. If you want to use them, you will have first to disable the “Allow clear connections” option in your Mosquitto configuration (on Stackhero dashboard).

Once done, subscribe to your Mosquitto on topic #. It means that you will listen for every topics:

$ mosquitto_sub -L -d "mqtts://admin:<PASSWORD>@<STACKHERO_MOSQUITTO_HOST>:8883/#"

Then, in another console, publish the message It works to the topic /sensor/a:

$ mosquitto_pub -L -d "mqtts://admin:<PASSWORD>@<STACKHERO_MOSQUITTO_HOST>:8883/sensor/a" -m "It works"

You should see the message It works (and some debug logs because of the -d flag) appears in your first console.

Authentication

You can authenticate your users and devices connections to Mosquitto manually or with an external API.

Authenticating Manually

Manual authentication is useful when you are testing. If you want to handle more than 10 devices, you should authenticate with an external API.

You can use the manual authentication system to let your backend connect to Mosquitto and use the external API method to let your devices authenticate.

To add a new user, connect to your Stackhero dashboard, then select your Mosquitto service and choose “Configure”. For “Users”, specify a “login” and “password”. You can add up to 20 users with this method.

Authenticating using an External API

Use the external API to authenticate many devices. It can handle thousands of devices.

When a device connects to MQTT, Mosquitto makes an HTTP POST request to your API, passing a JSON string containing the username and the password for the device. If your API replies with an HTTP status code 200, the device is authorized. If it replies with a 401 (unauthorized) or another code, the device authentication is rejected.

The same mechanism is used to check if the device can connect as super user.

For ACLs, 4 parameters are be passed: username, clientId, topic, acc. Your API must confirm username is allowed to make an acc type request on topic. acc can have the following values:

• 1 - read access
• 2 - write access
• 3 - read and write access
• 4 - subscribe access

For example, if the user userA tries to subscribe to the topic sensors/temperatures, your API receives the following JSON data:

{
  "username": "userA",
  "clientId": "userA",
  "topic": "sensors/temperatures",
  "acc": 4
}

See Gettng Started with Mosquitto to see an example API authentication server written in Jode.js.

Connecting to MQTT Mosquitto

You can retrieve your MQTT Mosquitto URL, username, and password via the following environment variables:

• STACKHERO_MOSQUITTO_URL_TLS
• STACKHERO_MOSQUITTO_LOGIN
• STACKHERO_MOSQUITTO_PASSWORD

Upgrading Your Plan

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade ah-mosquitto-mqtt-stackhero:newplan
-----> Upgrading ah-mosquitto-mqtt-stackhero:newplan to sharp-mountain-4005... done
       Your plan has been updated to: ah-mosquitto-mqtt-stackhero:newplan

Removing the Add-on

You can remove Stackhero for MQTT Mosquitto via the CLI:

$ heroku addons:destroy ah-mosquitto-mqtt-stackhero
-----> Removing ah-mosquitto-mqtt-stackhero from sharp-mountain-4005... done

Support

Stackhero for MQTT Mosquitto support and runtime issues should be submitted via one of the Heroku Support channels. We recommend adding support@stackhero.io in copy for urgent issues.

Additional Resources

• MQTT Mosquitto documentation by Stackhero
• MQTT Mosquitto managed cloud