Skip to content

VolantMQ/volantmq

Folders and files

NameName
Last commit message
Last commit date

Latest commit

a2de8e2 · Sep 28, 2021
Apr 8, 2020
Jan 24, 2020
Dec 26, 2019
Jul 24, 2018
Oct 19, 2020
May 17, 2018
Oct 19, 2020
Oct 19, 2020
Sep 28, 2021
Oct 19, 2020
Jan 25, 2020
Jan 25, 2020
Oct 19, 2020
Oct 19, 2020
Oct 19, 2020
Oct 19, 2020
Jan 19, 2020
Oct 19, 2020
Oct 19, 2020
Oct 19, 2020
Apr 22, 2018
Oct 19, 2020
Dec 8, 2017
Sep 4, 2017
Nov 20, 2018
Sep 19, 2017
Sep 4, 2017
Oct 19, 2020
Jun 11, 2017
Nov 7, 2020
Feb 24, 2018
Oct 19, 2020
Nov 7, 2019
Sep 28, 2021
Sep 28, 2021
Jan 24, 2020
Jan 24, 2020
Jan 24, 2020

Repository files navigation

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:
  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
          order:           # optional. default auth configuration is used if omitted
            - internal
      1884:
        auth:
          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

Credits

This project is heavily inspired by surgemq. As it was unmaintained it was forked to here, redesigned and packed with features since then

Appreciate JetBrains for granted license