aedes-cli

aedes-cli

Aedes MQTT broker CLI plugin

• aedes-cli
  • Install
  • Usage
  • Programmatically
  • Docker
  • Authorization
  • Persistence and Emitters

Install

Install the library using npm.

npm install aedes-cli -g

Usage

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

$ aedes -h

 ______   ________  _______   ________   ______  
/      \ |        \|       \ |        \ /      \
|  $$$$$$\| $$$$$$$$| $$$$$$$\| $$$$$$$$|  $$$$$$\
| $$__| $$| $$__    | $$  | $$| $$__    | $$___\$$
| $$    $$| $$  \   | $$  | $$| $$  \    \$$    \
| $$$$$$$$| $$$$$   | $$  | $$| $$$$$    _\$$$$$$\
| $$  | $$| $$_____ | $$__/ $$| $$_____ |  \__| $$
| $$  | $$| $$     \| $$    $$| $$     \ \$$    $$
\$$   \$$ \$$$$$$$$ \$$$$$$$  \$$$$$$$$  \$$$$$$

Usage: aedes [command] [options]

Commands:
  aedes adduser <user> <password>  Add a user to given credentials file
  aedes rmuser <user>              Removes a user from given credentials file
  aedes start                      Starts Aedes broker with given options
                                                                       [default]

Options:
  --port, -p             the port to listent to         [number] [default: 1883]
  --host                 the host to listen to   [string] [default: "127.0.0.1"]
  --protos               protocols to use
                 [array] [choices: "tcp", "tls", "ws", "wss"] [default: ["tcp"]]
  --credentials          <file> the file containing the credentials     [string]
  --authorize-publish    <pattern> the pattern for publishing to topics for the
                         added user                                     [string]
  --authorize-subscribe  <pattern> the pattern for subscribing to topics for the
                         added user                                     [string]
  --concurrency          broker maximum number of concurrent messages delivered
                         by mqemitter                    [number] [default: 100]
  --queueLimit           broker maximum number of queued messages before client
                         session is established           [number] [default: 42]
  --maxClientsIdLength   broker option to override MQTT 3.1.0 clients Id length
                         limit                            [number] [default: 23]
  --heartbeatInterval    interval in millisconds at which broker beats its
                         health signal in $SYS/<broker.id>/heartbeat
                                                       [number] [default: 60000]
  --connectTimeout       maximum waiting time in milliseconds waiting for a
                         CONNECT packet                [number] [default: 30000]
  --key                  <file> the server's private key                [string]
  --cert                 <file> the certificate issued to the server    [string]
  --reject-unauthorized  reject clients using self signed certificates
                                                       [boolean] [default: true]
  --tls-port             the TLS port to listen to      [number] [default: 8883]
  --ws-port              mqtt-over-websocket server port[number] [default: 3000]
  --wss-port             mqtt-over-secure-websocket server port
                                                        [number] [default: 4000]
  --stats                enable publish of stats under $SYS
                                                      [boolean] [default: false]
  --stats-interval       interval between aedes stats pubs
                                                        [number] [default: 5000]
  --broker-id            the id of the broker in the $SYS/<id> namespace
                                                 [string] [default: "aedes-cli"]
  --config, -c           <file> the config file to use (overrides every other
                         option)                                        [string]
  --verbose, -v          set the log level to INFO    [boolean] [default: false]
  --very-verbose         set the log level to DEBUG   [boolean] [default: false]
  --no-pretty            JSON logs                    [boolean] [default: false]
  -V, --version          Show version number                           [boolean]
  -h, --help             Show help                                     [boolean]

Examples:
  aedes --protos tcp ws                     Starts Aedes broker with TCP and WS
                                            servers
  aedes --config myConfig.js                Starts Aedes broker with custom
                                            config file
  aedes --stats -v --statsInterval 2000     Starts Aedes broker with stats
                                            enabled
  aedes --credentials ./credentials.json    Add/Modify user1 with password1 to
  adduser user1 password1                   credentials
  aedes --credentials ./credentials.json    Removes user1 from credentials
  rmuser user1

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

A configuration file is structured in the following way:

module.exports = {
  protos: ['tcp'],
  host: '0.0.0.0',
  port: 1883,
  wsPort: 3000,
  wssPort: 4000,
  tlsPort: 8883,
  brokerId: 'aedes-cli',
  credentials: './credentials.json',
  persistence: {
    name: 'mongodb',
    options: {
      url: 'mongodb://127.0.0.1/aedes'
    }
  },
  mq: {
    name: 'mongodb',
    options: {
      url: 'mongodb://127.0.0.1/aedes'
    }
  },
  key: null,
  cert: null,
  rejectUnauthorized: true,
  verbose: false,
  veryVerbose: false,
  noPretty: false
}

Programmatically

You can also use aedes-cli programmatically:

const { start, adduser, rmuser } = require('aedes-cli')

start({
  protos: ['tcp'],
})

Docker

aedes-cli is available on Docker-Hub for amd64, arm64v8, arm32v6, arm32v7, i386 archs. If you want to use a local credentials.json file and/or a custom config file to pass using --config option you have to use docker volumes and map the local folder containing those files to a folder inside the container.

Minimal example:

docker run --rm -it -p 1883:1883 moscajs/aedes:latest

Example with custom config file:

docker run --rm -it -p 1883:1883 -v $(pwd):/data moscajs/aedes:latest --config /data/myConfig.js

• -v $(pwd):/data will map the local folder from where you are running this command to /data folder of the container
• --config /data/myConfig.js will tell aedes to use the configuration file that is in your local folder

Here there is an example with docker-compose that runs aedes with mongodb as persistence

version: '3.7'
services:
 aedes:
   container_name: aedes
   image: moscajs/aedes:latest
   restart: always
   stop_signal: SIGINT
   networks:
     - mqtt
   command: --config /data/mongodbConfig.js # add here the options to pass to aedes
   volumes:
     - ./:/data # map the local folder to aedes
   ports:
     - '1883:1883'
     - '3000:3000'
     - '4000:4000'
     - '8883:8883'
 mongo:
   container_name: mongo
   networks:
     - mqtt
   logging:
     driver: none
   image: mvertes/alpine-mongo
   volumes:
     - db-data:/data/db
   ports:
     - "27017:27017"
volumes:
 db-data:
   name: db-data
networks:
 mqtt:

When using persistences with docker-compose file remember that the database url will be the name of the service in docker-compose, in the mongo example it will be: mongodb://mongo/dbName.

Authorization

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

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

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

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

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

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

Persistence and Emitters

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

Supported persistences are:

• aedes-persistence: In-memory implementation of an Aedes persistence
• aedes-persistence-mongodb: MongoDB persistence for Aedes
• aedes-persistence-redis: Redis persistence for Aedes

Emitters are needed to deliver messages to subscribed clients. In a cluster environment it is used also to share messages between brokers instances

All of them can be configured from the configuration file, under the persistence and mq key.

Supported mqemitters are:

• mqemitter: An opinionated memory Message Queue with an emitter-style API
• mqemitter-redis: Redis-powered mqemitter
• mqemitter-mongodb: Mongodb based mqemitter