Skip to content
This repository has been archived by the owner on Feb 11, 2020. It is now read-only.

Mosca as a standalone service.

Evan Summers edited this page Aug 30, 2018 · 3 revisions


Install the library using npm.

$ npm install mosca bunyan -g

Install the library using git.

$ git clone git://
$ cd mosca
$ npm install


Mosca offers an executable for running it standalone. Run it and connect your preferred MQTT client.

$ mosca -v | bunyan


Here you can see the options accepted by the command line tool:

$ mosca --help

  Usage: mosca [options] [command]


    adduser <user> <pass>  Add a user to the given credentials file
    rmuser <user>          Removes a user from the given credentials file
    start                  start the server (optional)


    -h, --help                       output usage information
    -V, --version                    output the version number
    -p, --port <n>                   the port to listen to
    --host <IP>                      the host to listen to
    --parent-port <n>                the parent port to connect to
    --parent-host <s>                the parent host to connect to
    --parent-prefix <s>              the prefix to use in the parent broker
    --credentials <file>             the file containing the credentials
    --authorize-publish <pattern>    the pattern for publishing to topics for the added user
    --authorize-subscribe <pattern>  the pattern for subscribing to topics for the added user
    --key <file>                     the server's private key
    --cert <file>                    the certificate issued to the server
    --secure-port <n>                the TLS port to listen to
    --non-secure                     start both a secure and non-secure server
    --http-port <n>                  start an mqtt-over-websocket server on the specified port
    --https-port <n>                 start an mqtt-over-secure-websocket server on the specified port
    --http-static <directory>        serve some static files alongside the websocket client
    --https-static <directory>       serve some static files alongside the secure websocket client
    --http-bundle                    serve a MQTT.js-based client at /mqtt.js on HTTP
    --https-bundle                   serve a MQTT.js-based client at /mqtt.js on HTTPS
    --only-http                      start only an mqtt-over-websocket server
    --disable-stats                  disable the publishing of stats under $SYS
    --broker-id <id>                 the id of the broker in the $SYS/<id> namespace
    -c, --config <c>                 the config file to use (override every other option)
    -d, --db <path>                  the path were to store the database
    -v, --verbose                    set the bunyan log to INFO
    --very-verbose                   set the bunyan log to DEBUG

To fully use mosca you need to define a configuration file where the communication broker is defined. Here follows an example using Redis.

A configuration file is structured in the following way:

var mosca = require('mosca');

module.exports = {
  port: 4883,
  // host: "", // specify an host to bind to a single interface
  id: 'mymosca', // used to publish in the $SYS/<id> topicspace
  stats: true, // publish stats in the $SYS/<id> topicspace
  logger: {
    level: 'info'
  backend: {
    type: 'redis',
    port: 6379,
    host: 'localhost',
    return_buffers: true
  persistence: {
    factory: mosca.persistence.Redis,
    port: 6379,
    host: 'localhost'
  secure: {
    keyPath: "/path/to/key",
    certPath: "/path/to/cert"

As Mosca is based on Ascoltatori, here you can find configuration examples covering Redis, MongoDB, AMQP, ZeroMQ and and MQTT brokers (e.g Mosquitto).


Mosca supports user authentication through the use of a specific json file. In order to create one run the following command.

// add a user
$ mosca adduser <user> <pass> --credentials ./credentials.json

// add a user specifying the authorized topics
$ mosca adduser myuser mypass --credentials ./credentials.json \
  --authorize-publish 'hello/*' --authorize-subscribe 'hello/*'

// remove a user
$ mosca rmuser myuser --credentials ./credentials.json

// start Mosca with a specific set of credentials:
$ mosca --credentials ./credentials.json

The patterns are checked and validated using Minimatch. The credentials file is automatically reloaded by Mosca when it receives a SIGHUP.


The MQTT specification requires a persistent storage for offline QoS 1 subscription that has been done by an unclean client. Mosca offers several persitance options.

All of them can be configured from the configuration file, under the persistence key. The only exception is LevelUp, which can be specified by using the --db option from the command line.