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>
Monitoring
- Systree
- Prometheus
- Grafana dashboard. Credits to Oleg Beletskyi
- Service monitor for Kubernetes. Credits to Oleg Beletskyi
Persistence
- In-Memory server built in
- 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 pluginhttp1
from config below variable should be declared asVOLANTMQ_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
###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
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