Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Description and Configuration of the built-in Monitoring mechanism
VerneMQ can be monitored in several ways. We implemented native support for Graphite, MQTT $SYS tree, and Prometheus.
The metrics are also available via the command line tool:
Or with:
Which will output the metrics together with a short description describing what the metric is about. An example looks like:
Notice that the metrics:
Are no longer used (always 0) and will be removed in the future. They were replaced with mqtt_connack_sent
using the return_code
label. For MQTT 5.0 the reason_code
label is used instead.
The output on the command line are aggregated by default, but details for a label can be shown as well, for example all metrics with the not_authorized
label:
All available labels can be show using vmq-admin metrics show --help
.
As well as being available as packages that can be installed directly into the operating systems, VerneMQ is also available as a Docker image. Below is an example of how to set up a couple of VerneMQ
To use the provided docker images the VerneMQ EULA must be accepted. See Accepting the VerneMQ EULA for more information.
Sometimes you need to configure a forwarding for ports (on a Mac for example):
This starts a new node that listens on 1883 for MQTT connections and on 8080 for MQTT over websocket connections. However, at this moment the broker won't be able to authenticate the connecting clients. To allow anonymous clients use the DOCKER_VERNEMQ_ALLOW_ANONYMOUS=on
environment variable.
Warning: Setting allow_anonymous=on
completely disables authentication in the broker and plugin authentication hooks are never called! See more information about the authentication hooks here.
This allows a newly started container to automatically join a VerneMQ cluster. Assuming you started your first node like the example above you could autojoin the cluster (which currently consists of a single container 'vernemq1') like the following:
(Note, you can find the IP of a docker container using docker inspect <CONTAINER_NAME> | grep \"IPAddress\"
).
To check if the above containers have successfully clustered you can issue the vmq-admin
command:
VerneMQ can be installed on CentOS-based systems using the binary package we provide.
Once you have downloaded the binary package, execute the following command to install VerneMQ:
or:
To use the provided binary packages the VerneMQ EULA must be accepted. See Accepting the VerneMQ EULA for more information.
Once you've installed VerneMQ, start it on your node:
You can verify that VerneMQ is successfully installed by running:
If VerneMQ has been installed successfully vernemq
is returned.
Now that you've installed VerneMQ, check out How to configure VerneMQ.
Welcome to the VerneMQ documentation! This is a reference guide for most of the available features and options of VerneMQ. The Getting Started guide might be a good entry point.
The VerneMQ documentation is based on the VerneMQ Documentation project. Any changes on Github are automatically deployed to the VerneMQ online Documentation.
For a more general overview on VerneMQ and MQTT, you might want to start with the introduction.
For downloading the subscription-based binary VerneMQ packages and/or a quick description on how to compile VerneMQ from sources, see Downloads.
The VerneMQ Documentation project is an open-source effort, and your contributions are very welcome and appreciated. You can contribute on all levels:
Language, style and typos
Fixing obvious documentation errors and gaps
Providing more details and/or examples for specific topics
Extending the documentation where you find this useful to do
Note that the documentation is versioned according to the VerneMQ releases. You can click the "Edit on Github" button in the upper right corner of every page to check what branch and document you are on. You can then create a Pull Request (PR) against that branch from your fork of the VerneMQ documentation repository. (Direct edits on Github are possible for members of the documentation repository).
A quick and simple guide to get started with VerneMQ
VerneMQ is a high-performance, distributed MQTT message broker. It scales horizontally and vertically on commodity hardware to support a high number of concurrent publishers and consumers while maintaining low latency and fault tolerance. To use it, all you need to do is install the VerneMQ package.
Choose your OS and follow the instructions:
It is also possible to run VerneMQ using our Docker image:
If you built VerneMQ from sources, you can add the /bin
directory of your VerneMQ release to PATH
. For example, if you compiled VerneMQ in the /home/vernemq
directory, then add the binary directory (/home/vernemq/_build/default/rel/vernemq/bin
) to your PATH, so that VerneMQ commands can be used in the same manner as with a packaged installation.
To start a VerneMQ broker, use the vernemq start command in your Shell:
A successful start will return no output. If there is a problem starting the broker, an error message is printed to STDERR
.
To run VerneMQ with an attached interactive Erlang console:
A VerneMQ broker is typically started in console mode for debugging or troubleshooting purposes. Note that if you start VerneMQ in this manner, it is running as a foreground process that will exit when the console is closed.
You can close the console by issuing this command at the Erlang prompt:
Once your broker has started, you can initially check that it is running with the vernemq ping command:
The command will respond with pong
if the broker is running or Node <NodeName> not responding to pings
in case it’s not.
As you may have noticed, VerneMQ will warn you at startup when your system’s open files limit (ulimit -n
) is too low. You’re advised to increase the OS default open files limit when running VerneMQ. Read more about why and how in the Open Files Limit documentation.
If you use a systemd
service file (as in the binary packages), you can start VerneMQ using the systemctl
interface to systemd
:
Other systemctl
commands work as well:
VerneMQ supports multiple ways to authenticate and authorize new client connections using a database.
VerneMQ supports authentication and authorization using a number of popular databases and the below sections describe how to configure the different databases.
The database drivers are handled using the vmq_diversity
plugin and it therefore needs to be enabled:
The vmq_diversity
plugin makes it possible to extend VerneMQ using Lua. The documentation can be found .
When using database based authentication/authorization the enabled-by-default file based authentication and authorization are most likely not needed and should be disabled:
You must set allow_anonymous = off
, otherwise VerneMQ won't use the database plugin for authentication and authorization.
In order to use a database for authentication and authorization the database must be properly configured and the auth-data (username, clientid, password, acls) to be present. The following sections show some sample requests that can be used to insert such data.
While the handling of authentication differs among the different databases, the handling of ACLs is roughly identical and make use of a JSON array containing one or many ACL objects per configured client.
The database integrations will cache the ACLs when the client connects avoiding expensive database lookups for each publish or subscribe message. The cache entries are evicted when the client disconnects.
A minimal publish & subscribe ACL JSON object takes the following form:
General ACL
The pattern is a MQTT topic string that can contain MQTT wildcards, but also the template variables %m
(mountpoint), %u
(username), and %c
(client id) which are automatically substituted with the auth data provided.
Publish ACL
The publish ACL makes it possible to control the maximum QoS and payload size that is allowed, and if the message is allowed to be retained.
Moreover, the publish ACL makes it possible to modify the properties of a published message through specifying one or multiple modifiers
. Please note that the modified message isn't re-validated by the ACL.
Subscribe ACL
The subscribe ACL makes it possible to control the maxium QoS a client is allowed to subscribe to.
Like the publish ACL, the subscribe ACL makes it possible to change the current subscription request by returning a custom set of topic/qos pairs. Please note that the modified subscription isn't re-validated by the ACL.
When deciding on which database to use one has to consider which kind of password hashing and key derivation functions are available and required. Different databases provide different mechanisms, for example PostgreSQL provides the pgcrypto
module which supports verifying hashed and salted passwords, while Redis has no such features. VerneMQ therefore also provides client-side password verification mechanisms such as bcrypt
.
There is a trade-off between verifying passwords on the client-side versus on the server-side. Verifying passwords client-side of course means doing the computations on the VerneMQ broker and this takes away resources from other tasks such as routing messages. With hashing functions such as bcrypt
which are designed specifically to be slow (proportional to the number of rounds) in order to make brute-force attacks infeasible, this can become a problem. For example, if verifying a password with bcrypt
takes 0.5 seconds then on a single threaded core 2 verifications/second are possible and using 4 single threaded cores 8 verifications/second. So, the number of rounds/security paramenters have a direct impact on the max number of verifications/second and hence also the maximum arrival rate of new clients per second.
For each database it is specified which password verification mechanisms are available and if they are client-side or server-side.
Note that currently bcrypt version `2a` (prefix `$2a$`) is supported.
To enable PostgreSQL authentication and authorization the following need to be configured in the vernemq.conf
file:
In case your Postgresql database requires SSL, you'll have to tell the plugin:
Consult the vernemq.conf
file for more info about additional options:
PostgreSQL hashing methods:
The following SQL DDL must be applied, the pgcrypto
extension is required if using the server-side crypt
hashing method:
To enter new ACL entries use a query similar to the following:
To enable CockroachDB authentication and authorization the following need to be configured in the vernemq.conf
file:
Notice that if the CockroachDB installation is secure, then TLS is required. If using an insecure installation without TLS, then vmq_diversity.cockroachdb.ssl
can be set to off
.
CockroachDB hashing methods:
The following SQL DDL must be applied:
To enter new ACL entries use a query similar to the following, the example is for the bcrypt
hashing method:
For MySQL authentication and authorization configure the following in vernemq.conf
:
MySQL hashing methods:
It should be noted that all the above options stores unsalted passwords which are vulnerable to rainbow table attacks, so the threat-model should be considered carefully when using these. Also note the methods marked with *
are no longer considered secure hashes.
The following SQL DDL must be applied:
To enter new ACL entries use a query similar to the following, the example uses PASSWWORD
to for password hashing:
The default password
method has been deprecated since MySQL 5.7.6 and not usable with MySQL 8.0.11+. Also, the MySQL authentication method caching_sha2_password
is not supported. This is the default in MySQL 8.0.4 and later, so you need to add: default_authentication_plugin=mysql_native_password
under [mysqld] in e.g. /etc/mysql/my.cnf.
For MongoDB authentication and authorization configure the following in vernemq.conf
:
VerneMQ supports MongoDB's DNS SRV record lookup to fetch a seed list. Specify the hostname of hosted database as a srv
option instead of host
and port
. VerneMQ will randomly choose a host/port combination from the seed list returned in the DNS SRV record. MongoDB SRV connections use TLS by default. You will need to configure TLS support for MongoDB for most SRV connections.
MongoDB supports a number of node types in replica sets. The built-in MongoDB support simply connects to the host and port specified. It does not differentiate between primary or secondary nodes in MongoDB replica sets.
MongoDB hashing methods:
Insert the ACL using the mongo
shell or any software library. The passhash
property contains the bcrypt hash of the clients password.
For Redis authentication and authorization configure the following in vernemq.conf
:
Redis hashing methods:
Insert the ACL using the redis-cli
shell or any software library. The passhash
property contains the bcrypt hash of the clients password. The key is an encoded JSON array containing the mountpoint, username, and client id. Note that no spaces are allowed between the array items.
Note, the PASSWORD()
hashing method needs to be changed according to the configuration set in vmq_diversity.mysql.password_hash_method
, it supports the options password
, md5
, sha1
and sha256
. Learn more about the MySQL equivalent for those methods on .