README
¶
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 passwordprovided 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
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 pluginhttp1from 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:
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
###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. |
Click to show internal directories.
Click to hide internal directories.