volantmq

command module
Version: v0.4.0-rc.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 1, 2020 License: Apache-2.0 Imports: 0 Imported by: 6

README

VolantMQ

CircleCI Codacy Badge codecov.io License

VolantMQ image *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

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>
    
  • Build status HTTP

Monitoring
Persistence
  • In-Memory server built in
  • Build status BBolt
Debug
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

docker run --rm -p 1883:1883 -p 8080:8080 -v $(pwd)/examples/config.yaml:/etc/volantmq/config.yaml \
--env VOLANTMQ_CONFIG=/etc/volantmq/config.yaml volantmq/volantmq
Contributing guidelines
Credits

Appreciate JetBrains for granted license

Documentation

Overview

Package volantmq is a high performance MQTT broker and client library that aims to be fully compliant with MQTT 3.1 and 3.1.1 specs.

The primary package that's of interest is package service. It provides the MQTT Server and Client services in a library form.

MQTT is a Client Server publish/subscribe messaging transport protocol. It is
light weight, open, simple, and designed so as to be easy to implement. These
characteristics make it ideal for use in many situations, including constrained
environments such as for communication in Machine to Machine (M2M) and Internet
of Things (IoT) contexts where a small code footprint is required and/or network
bandwidth is at a premium.

The protocol runs over TCP/IP, or over other network protocols that provide
ordered, lossless, bi-directional connections. Its features include:

- Use of the publish/subscribe message pattern which provides one-to-many
  message distribution and decoupling of applications.
- A messaging transport that is agnostic to the content of the payload.
- Three qualities of service for message delivery:
- "At most once", where messages are delivered according to the best efforts
  of the operating environment. Message loss can occur. This level could be
  used, for example, with ambient sensor data where it does not matter if an
  individual reading is lost as the next one will be published soon after.
  - "At least once", where messages are assured to arrive but duplicates can occur.
  - "Exactly once", where message are assured to arrive exactly once. This
    level could be used, for example, with billing systems where duplicate or
    lost messages could lead to incorrect charges being applied.
- A small transport overhead and protocol exchanges minimized to reduce
  network traffic.
- A mechanism to notify interested parties when an abnormal disconnection occurs.

Current performance benchmark of VolantMQ, running all publishers, subscribers and broker on a single 4-core (2.8Ghz i7) MacBook Pro, is able to achieve:

  • over 400,000 MPS in a 1:1 single publisher and single producer configuration
  • over 450,000 MPS in a 20:1 fan-in configuration
  • over 750,000 MPS in a 1:20 fan-out configuration
  • over 700,000 MPS in a full mesh configuration with 20 clients

In addition, VolantMQ has been tested with the following client libraries and it _seems_ to work:

  • libmosquitto 1.3.5 (C)
  • Tested with the bundled test programs msgsps_pub and msgsps_sub
  • Paho MQTT Conformance/Interoperability Testing Suite (Python)
  • Tested with all 10 test cases.
  • Paho Go Client Library (Go)
  • Tested with one of the tests in the library, in fact, that tests is now part of the tests for VolantMQ
  • Paho C Client library (C)
  • Tested with most of the test cases and failed the same ones as the conformance test because the features are not yet implemented.
  • Actually I think there's a bug in the test suite as it calls the PUBLISH handler function for non-PUBLISH messages.

Source Files

Directories

Path Synopsis
cmd
Package topics deals with MQTT topic names, topic filters and subscriptions.
Package topics deals with MQTT topic names, topic filters and subscriptions.
mem

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL