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...
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.
For a more general overview on VerneMQ and MQTT, you might want to start with the introduction.
For downloading VerneMQ see Downloads.
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.
Everything you must know to properly configure VerneMQ
Every VerneMQ node has to be configured. Depending on the installation method and chosen platform the configuration file vernemq.conf
resides at different locations. If VerneMQ was installed through a Linux package the default location for the configuration file is /etc/vernemq/vernemq.conf
.
A single setting is handled on one line.
Lines are structured Key = Value
Any line starting with # is a comment, and will be ignored
You certainly want to try out VerneMQ right away. For that you could disable authentication like so:
Set allow_anonymous = on
By default the vmq_acl
authorization plugin is enabled and configured to allow publishing and subscribing to any topic, see here for more information.
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. Further, in a production system you should configure vmq_acl
to be less permissive or configure some other plugin to handle authorization.
VerneMQ can be installed on Debian or Ubuntu-based systems using the binary package we provide.
Once you have downloaded the binary package, execute the following command to install VerneMQ:
You can verify that VerneMQ is successfully installed by running:
If VerneMQ has been installed successfully Status: install ok installed
is returned.
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:
The whereis vernemq
command will give you a couple of directories:
Now that you've installed VerneMQ, check out How to configure VerneMQ.
VerneMQ comes with a simple file-based password authentication mechanism which is enabled by default. If you don't need this it can be disabled by setting:
Per default VerneMQ doesn't accept any client that hasn't been configured using vmq-passwd
. If you want to change this and accept any client connection you can set:
In a production setup we recommend to use the provided password based authentication mechanism or implement your own authentication plugins.
VerneMQ periodically checks the specified password file.
The check interval defaults to 10 seconds and can also be defined in the vernemq.conf
.
Setting the password_reload_interval = 0
disables automatic reloading.
Both configuration parameters can also be changed at runtime using the vmq-admin
script.
How to use vmq-passwd
Options
-c
Creates a new password file. If the file already exists, it will be overwritten.
-D
Deletes the specified user from the password file.
-U
This option can be used to upgrade/convert a password file with plain text passwords into one using hashed passwords. It will modify the specified file. It does not detect whether passwords are already hashed, so using it on a password file that already contains hashed passwords will generate new hashes based on the old hashes and render the password file unusable. Note, with this option neither usernames or passwords may contain
":"
.
passwordfile
The password file to modify.
username
The username to add/update/delete.
Examples
Add a user to a new password file: (you can choose an arbitrary name for the password file, it only has to match the configuration in the VerneMQ configuration file).
Delete a user from a password file
Acknowledgements
The original version of vmq-passwd
was developed by Roger Light (roger@atchoo.org).
vmq-passwd
includes :
software developed by the [OpenSSL
cryptographic software written by Eric Young
(eay@cryptsoft.com)
software written by Tim Hudson (tjh@cryptsoft.com)
VerneMQ comes with a simple ACL based authorization mechanism which is enabled by default. If you don't need this it can be disabled by setting:
VerneMQ periodically checks the specified ACL file.
The check interval defaults to 10 seconds and can also be defined in the vernemq.conf
.
Setting the acl_reload_interval = 0
disables automatic reloading.
Both configuration parameters can also be changed at runtime using the vmq-admin
script.
Topic access is added with lines of the format:
Only one space should be put between the topic and the preceeding keyword. Extra spaces will be interpreted as part of the topic! Also note that the ACL parser doesn't accept empty lines between entries.
The access type is controlled using read
or write
. If not provided then read and write access is granted for the topic
. The topic
can use the MQTT subscription wildcards +
or #
.
The first set of topics are applied to all anonymous clients (assuming allow_anonymous = on
). User specific ACLs are added after a user line as follows (this is the username not the client id):
It is also possible to define ACLs based on pattern substitution within the topic. The form is the same as for the topic keyword, but using pattern as the keyword.
The patterns available for substitution are:
%c
to match the client id of the client
%u
to match the username of the client
The substitution pattern must be the only text for that level of hierarchy. Pattern ACLs apply to all users even if the user keyword has previously been given.
Example:
VerneMQ currently doesn't cancel active subscriptions in case the ACL file revokes access for a topic.
Anonymous users are allowed to
publish & subscribe to topic bar.
publish to topic foo.
subscribe to topic all.
User john is allowed to
publish & subscribe to topic foo.
subscribe to topic baz.
publish to topic all.
Accepting the EULA for OS packages can be done by either changing the accept_eula
line in the vernemq.conf
file from no
to yes
or accepting the EULA the first time starting VerneMQ. In general, the installation of VerneMQ OS packages is now a 3 step process:
If you install the package with tools like dpkg
(example: sudo dpkg -i vernemq-1.10.0.xenial.x86_64.deb
), VerneMQ will install but will fail to start due to the missing EULA acceptance.
Accept the EULA by running sudo vernemq chkconfig
or by adding the following line to your vernemq.conf file
: accept_eula = yes
.
Start/restart VerneMQ with: sudo systemctl restart vernemq.
For Docker images the EULA can be accepted by setting the environment variableDOCKER_VERNEMQ_ACCEPT_EULA=yes
, for Docker Swarm add DOCKER_VERNEMQ_ACCEPT_EULA: yes
to the environment.
For the Helm chart the EULA for the Docker images can be accepted by extending the additionalEnv
section with:
additionalEnv:
- name: DOCKER_VERNEMQ_ACCEPT_EULA
value: "yes"
env:
- name: DOCKER_VERNEMQ_ACCEPT_EULA
value: "yes"
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 .
vmq-passwd
is a tool for managing password files for the VerneMQ broker. Usernames must not contain ":"
, passwords are stored in similar format to .
Project]() for use in the OpenSSL Toolkit.
To use the VerneMQ pre-built packages and Docker images you have to accept the . Make sure to read and understand the EULA before accepting it.
and similarly for the , to accept the EULA for the Docker images, the env
can be extended with: