VolantMQ

*VolantMQ image by Marina Troian, licensed under [Creative Commons Attribution 4.0 International License][cc-by]

VolantMQ is a high performance MQTT broker that aims to be fully compliant with MQTT specs

##Features ###MQTT Specs

• MQTT v3.1 - V3.1.1 full support
• MQTT V5.0 limited support. see details below
  • Properties
  • Publish expire
  • Session expire
  • Shared topics
  • Subscription id
  • Subscription options
  • Enhanced authentication
  • Topic alias
  • Server disconnect
  • Flow control
  • Maximum Packet Size
  • Server Keep Alive
  • Assigned ClientID

Network Transports

• TCP
• TLS
• WebSocket
• WebSocket+TLS

Persistence

By default server starts with in-memory persistence which means all sessions and messages lost after server restart.

Plugins

Auth

• Server built-in basic auth.Key-value pairs in format user: sha256 of password provided by any of the following options

  • Users and their password hashes in config file

    - name: internal  # authenticator name, used by listeners
      backend: simpleAuth # authenticator type
      config:
        users:
          testuser: "9f735e0df9a1ddc702bf0a1a7b83033f9f7153a00c29de82cedadc9957289b05" # testpassword

  • Users and their password hashes in separate file

    - name: internal  # authenticator name, used by listeners
      backend: simpleAuth # authenticator type
      config:
        users: # both can be used simultaneously
          testuser: "9f735e0df9a1ddc702bf0a1a7b83033f9f7153a00c29de82cedadc9957289b05" # testpassword
        usersFile: <some path>

• HTTP

Monitoring

• Systree
• Prometheus
  • Grafana dashboard

Persistence

• In-Memory server built in
• BBolt

Debug

• PProf

Health

• Health

Configuring

Server starts with default config from here. Any further configurations applied on top

Environment variables

• VOLANTMQ_CONFIG - path to configuration file described in [this section](#Config file).
• VOLANTMQ_PLUGIN_AUTH_HTTP_<NAME>_TOKEN - API token for auth plugins For example to supply auth token into auth plugin http1 from config below variable should be declared as VOLANTMQ_PLUGIN_AUTH_HTTP_HTTP1_TOKEN

Config file

File divided in a few sections Complete example can be found here

System

system:
  log:
    console:
      level: info # available levels: debug, info, warn, error, dpanic, panic, fatal
  http:
    defaultPort: 8080 # default HTTP listener assigned. Assigned to plugins like debug/health/metrics if they dont specify own port

Plugins

plugins:
    enabled: # list of plugins server will load on startup
      - systree
      - prometheus
      - debug
      - health
      - auth_http
      - persistence_bbolt
    config: # configuration of each plugin
      <plugin type>:
        - backed: systree # plugin name, allowed: systree, prometheus, http, prof.profiler, health, bbolt
          name: http1     # required by auth plugins only. Value used in auth.order
          config:         # configuration passed to plugin on load stage. refer to particular plugin for configuration

Default auth config

auth:
  anonymous: false # anonymous auth is prohibited. Listener can override
  order: # default auth order. Authenticators invoked in the order they present in the config. Listener can override
    - internal

MQTT specs

mqtt:
  version: // list of supported MQTT specifications
    - v3.1.1
    - v5.0
  keepAlive:
    period: 60 # KeepAlive The number of seconds to keep the connection live if there's no data.
    # Default is 60 seconds
    force: false # Force connection to use server keep alive interval (MQTT 5.0 only)
    # Default is false
  options:
    connectTimeout: 10 # The number of seconds to wait for the CONNACK message before disconnecting.
    # If not set then default to 2 seconds.
    offlineQoS0: true # OfflineQoS0 tell server to either persist (true) or not persist (false) QoS 0 messages for non-clean sessions
    # If not set than default is false
    sessionPreempt: true # AllowDuplicates Either allow or deny replacing of existing session if there new client with same clientID
    # If not set than default is false
    retainAvail: true # don't set to use default
    subsOverlap: false # tells server how to handle overlapping subscriptions from within one client
                       # - true server will send only one publish with max subscribed QoS even there are n subscriptions
                       # - false server will send as many publishes as amount of subscriptions matching publish topic exists
                       # Default is false
    subsId: false # don't set to use default
    subsShared: false # don't set to use default
    subsWildcard: true # don't set to use default
    receiveMax: 65535 # don't set to use default
    maxPacketSize: 268435455 # don't set to use default
    maxTopicAlias: 65535 # don't set to use default
    maxQoS: 2

Listeners

listeners:
  defaultAddr: "0.0.0.0" # default 127.0.0.1
  mqtt: # there are two types of listeners allowed tcp and ws (aka WebSocket) 
    tcp:
      1883:                # port number. can be as many ports configurations as needed
        host: 127.0.0.1    # optional. listen address. defaultAddr is used if omitted
        auth:              # optional. default auth configuration is used if omitted
          anonymous: true  # optional. default auth configuration is used if omitted
          order:           # optional. default auth configuration is used if omitted
            - internal
      1884:
        auth:
          anonymous: false
          order:
            - http1
        tls:               # TLS configuration
          cert:            # path to certificate file
          key:             # path to key file
    ws:
      8883:
        path: mqtt
        auth:
          order:
            - http1
      8884:
        path: mqtt
        auth:
          order:
            - http1
        tls:               # TLS configuration
          cert:            # path to certificate file
          key:             # path to key file

Reason to have multiple listeners comes from performance impact of TLS as well as authentication Internal to system users can omit entire auth and TLS

   ┌──────────────┐                                
   │              │                                
   │ MQTT process │                                
   │              │                                
   └───────▲──────┘                                
           │                                       
           │             ╔════════════════════════╗
           │             ║ VolantMQ               ║
           │             ║                        ║
      ╔════▼═══╗         ║                        ║
      ║intranet◀═════════▶ 1883  # no auth, no TLS║
      ╚════════╝         ║                        ║
      ╔════════╗         ║                        ║
      ║internet◀═════════▶ 1884  # auth and TLS   ║
      ╚═▲══▲══▲╝         ║                        ║
        │  │  │          ╚════════════════════════╝
        │  │  │                                    
   ┌────┘  │  └───┐                                
   │       │      │                                
   │       │      │                                
   │       │      │                                
┌──▼─┐  ┌──▼─┐  ┌─▼──┐                             
│IoT1│  │IoT2│  │IoTn│                             
└────┘  └────┘  └────┘                             

Distribution

• Docker image contains prebuilt plugins listed in this [section][#Plugins]
• Helm

How to use

script.sh file installs all the plugins [section][#Plugins]. It has to be changed GOPATH (line 7) and the local path where is quic-go (line 22).

Then, to run the broker:

• cd $GOPATH/src/github.com/fatimafp95/volantmq_2/cmd/volantmq
• sudo ./volantmq --config=../../examples/config.yaml

Contributing guidelines

Credits

Appreciate JetBrains for granted license