Mosca as a standalone service.

Install

Install the library using npm.

$ npm install mosca bunyan -g

Install the library using git.

$ git clone git://github.com/mcollina/mosca.git
$ cd mosca
$ npm install

Usage

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

$ mosca -v | bunyan

Configuration

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

$ mosca --help

  Usage: mosca [options] [command]

  Commands:

    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)

  Options:

    -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: "127.0.0.1", // 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).

Authorization

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.

Persistence

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.

• Redis
• MongoDB
• LevelUp
• Memory

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.