Introduction

HiveMQ is a MQTT broker tailored specifically for enterprises which find themself in the emerging age of Machine-to-Machine communication (M2M) and the Internet of Things. It was built from the ground up with maximum scalability and enterprise-ready security concepts in mind. HiveMQ implements the Message Queue Telemetry Transport protocol, the de-facto M2M messaging standard, and through its 100% compliance to the specification, it is leading when it comes to professional adoption of all possibilities of the Internet of Things for companies.

Pre Installation Requirements

Hardware
  • At least 128MB of RAM. 512MB or more is recommended

  • 20MB of free disk space for HiveMQ itself. At least 50MB for persistence features are recommended.

Operating Systems
  • Windows, Mac OS X or Linux. It is recommended to use a Linux distribution for production use.

Environment
  • OpenJDK 1.7 or newer must be installed.

Installation

This guide explains the default installation, if you want to try and review HiveMQ you can follow the getting started guide instead: http://www.hivemq.com/documentations/getting-started/

General installation information

HiveMQ comes as a zip file which contains the executables, init scripts and sample configurations.

The zip contains the following directories:

Folder name Description

bin

The folder with start scripts and binary files

conf

The folder with the configurations

data

Persistent client data and cluster data are located here.

plugins

The folder where plugins reside

license

The folder where the hivemq.lic license file resides.

log

All log files can be found here

Installation for specific Operating Systems

This procedure shows how to install the most recent HiveMQ version. To install older HiveMQ versions please visit http://www.hivemq.com/downloads/

Installation instructions for Unix based systems (Linux,BSD,MacOS X,Unix)

The default installation directory is /opt/hivemq and the default user to run HiveMQ is named hivemq. If you need to install HiveMQ to a custom directory or run it under a custom user please be aware of changing the $HIVEMQ_DIRECTORY and/or the HIVEMQ_USER in the $HIVEMQ_DIRECTORY/bin/start.sh script.

  1. Login as root

    Some of the following commands need root privileges, please login as root or use sudo to execute the commands.

  2. Change directory to where you want to download and install HiveMQ. By default we prefer /opt

    cd /opt
  3. Download latest HiveMQ version from the website

    wget --content-disposition http://www.hivemq.com/downloads/releases/latest

    or

    curl -O -L http://www.hivemq.com/downloads/releases/latest
  4. Extract the files

    unzip hivemq-<version>.zip
  5. Create hivemq symlink

    ln -s /opt/hivemq-<version> /opt/hivemq
  6. Create HiveMQ user

    useradd -d /opt/hivemq hivemq
  7. Make scripts executeable and change owner to hivemq user

    chown -R hivemq.hivemq /opt/hivemq-<version>
    chown -R hivemq.hivemq /opt/hivemq
    cd /opt/hivemq
    chmod +x ./bin/run.sh
  8. Adjust the configuration properties to your needs.

    See chapter Configuration for detailed instructions how to configure HiveMQ.

    If you just want to try HiveMQ you can skip this part now and proceed with Starting HiveMQ.

  9. Install the init script (optional)

    cp /opt/hivemq/bin/init-script/hivemq /etc/init.d/hivemq
    chmod +x /etc/init.d/hivemq
  10. Modify /etc/init.d/hivemq (optional)

    Set the HIVEMQ_HOME and the HIVEMQ_USER variable to the correct vaules for your system.

    By default this would be:

    HIVEMQ_HOME=/opt/hivemq

    HIVEMQ_USER=hivemq

If you installed HiveMQ to a different directory than /opt/hivemq please point the HIVEMQ_HOME in your init script to the correct directory. Otherwise the daemon will not start correctly.

Installation instructions for Windows based systems

  1. Download latest HiveMQ version from here: http://www.hivemq.com/downloads/releases/latest

  2. Extract the file hivemq.zip to C:\hivemq using your favorite Zip util.

Starting HiveMQ

The following instructions show how to start HiveMQ

Starting HiveMQ on Unix based systems (Linux,BSD,Mac OS X,Unix)

  1. Change directory to HiveMQ directory

    cd /opt/hivemq
  2. Execute startup script

    ./bin/run.sh
  3. (optional) Start daemon

    /etc/init.d/hivemq start

Starting HiveMQ on Windows based systems

Double click on the run.bat file.

Testing the installation

The following instructions show how to verify that HiveMQ is up and running

Verifying HiveMQ is running on a Unix based systems (Linux,BSD,Mac OS X,Unix)

  1. Check if HiveMQ is listening to the default port for MQTT

    netstat -an|grep 1883

Verifying HiveMQ is running on a Windows based systems

  1. Check if HiveMQ is listening to the default port for MQTT. Open cmd.exe and run:

    netstat -an|find "1883"

Configuration

Configuration Files

HiveMQ is configured with sensible default settings. Therefore most users will find it sufficient to use the default values to get started. All configuration files are located in the conf folder of the HiveMQ directory. In the following the different configuration files are explained:

Table 1. HiveMQ configuration files
Property file name Purpose

configuration.properties

Static broker configuration properties which are needed for HiveMQ to start.

application.properties

Dynamic application specific properties which can be edited at

infinispan.xml

Configurations for the replicated session and data layer (only needed for clustering)

cluster.xml

Configurations for the cluster transport and protocol communication (only needed for clustering)

If you want all properties to be static, it is possible to copy all settings from the application.properties file to the configuration.properties file. HiveMQ will pick these values up at startup time and these values cannot be modified at runtime anymore.

Configuration files
The configuration.properties file is read only once during the HiveMQ startup and you have to restart HiveMQ before any changes made during runtime are coming into effect. The properties in the application.properties are updated automatically every minute.

Configuration Options

The following tables list the available configuration options for HiveMQ. When a property is not defined in one of the configuration files the default value will be used.

application.properties

The properties defined here can be changed at runtime. HiveMQ reloads this configuration file once a minute.

Table 2. Dynamic properties
Property Name Default Value Description

plugin.performanceMonitoring

false

Enable to monitor the performance of plugins. When enabled this will result in a significant performance loss.

global.outgoingLimit

0

Maximum kb/s for outgoing traffic. Use 0 if you don’t want to throttle outgoing traffic

global.maxConnections

-1

Maximum allowed concurrent connections. Use -1 for unlimited connections

global.maxMessageSize

268435456

Maximum message size. The MQTT default for a message is 256MB. If clients must publish messages which are smaller, a saner message size limit should be configured.

global.ingoingLimit

0

Maximum kb/s for ingoing traffic. Use 0 if you don’t want to throttle ingoing traffic

configuration.properties

The properties defined here are applied once during the startup of HiveMQ and cannot be changed at runtime.

Table 3. Static properties
Property Name Default Value Description

global.ipAddress

0.0.0.0

The IP address on which HiveMQ will be bound

global.port

1883

The port on which HiveMQ will listen

global.retryInterval

10

Time in seconds to wait before resending an outgoing QoS=1 or QoS=2 message

global.maxClientIdLength

23

The maximum length of client ID. The MQTT v3.1 spec defines a limit of 23. If this is not enough for your use case, set it to a higher limit

global.checkForUpdates

true

If enabled, HiveMQ checks if a new HiveMQ version is available once a day

graphite.enabled

false

Enable the monitoring with Graphite

graphite.interval

10

The interval for publishing metrics to Graphite in seconds. Too low intervals could results in possible performance losses.

graphite.url

localhost:2003

The Graphite URL. Must be in the format "hostname:port"

graphite.metricPrefix

A prefix for every metric which is sent to the Graphite instance. Useful for distinguishing between different HiveMQ servers or when using a hosted Graphite service to prefix the API Key

keystore.location

The location of the servers key store

keystore.password

The password for the keystore of the server. Defaults to no password

measureResourceConsumption.enabled

false

Enables the resource consumption logging

measureResourceConsumption.interval

60

Time in seconds between logging of the resource consumption

messages.maxInflight

20

The maximum number of QoS 1 or 2 messages that can be in the process of being transmitted simultaneously. This includes messages currently going through handshakes and messages that are being retried. Set to 0 for no maximum. If set to 1, this will guarantee in-order delivery of messages for QoS1 und QoS2.

plugin.LowLevelCallbacksEnabled

false

Low level callbacks are callbacks which include all existing MQTT command messages, like PubRec, PubRel, etc. If your plugin needs to react to each individual MQTT command message, set this to true and all callbacks are available. In most cases the low level callbacks are not needed, only activate them if you really use them, otherwise this is influencing the performance.

ssl.applicationClientAuthentication

false

Enables or disables SSL client certificate authentication on the application layer. This does NOT affect transport client authentication. Essentially this enables HiveMQ plugins to provide permissions for users with specific client certificates.

ssl.clientAuthenticationMode

none

Sets the client authentication mode. Allowed values are: none, optional and required

ssl.enabled

false

Enables or disables SSL support

ssl.handshakeTimeout

0

The timeout for a SSL handshake. All clients which need longer for a handshake than the specified timeout will be disconnected. If not specified, no timeout is set.

ssl.hybridMode

false

If the hybrid mode is enabled and SSL is activated, SSL and standard TCP connections are supported simultaneously

ssl.port

8883

The port where HiveMQ will expect SSL encrypted connections

statistics.callbackInterval

60

Interval in seconds for the statistics callback. Used for the callback of plugins which are interested in HiveMQ statistics.

statistics.enabled

true

If statistics are enabled or not. If you disable statistics, the $SYS topic is also disabled.

statistics.updateInterval

30

Interval in seconds for updating statistics internally. Too low intervals could result in performance loss. It is recommended, that the statistics_update_interval is smaller than the sys_interval and the statistics_callback_interval

sys.enabled

true

If the $SYS tree should be available or not. Use true if you want to enable statistics

sys.interval

60

Time in seconds between publishes of the $SYS tree

truststore.location

The location of the trust store

truststore.password

The password for the truststore. Defaults to no password.

websockets.enabled

false

This property enables websocket support for HiveMQ when set to true

websockets.port

80

The port used for websockets. Defaults to 80.

websockets.subProtocol

mqttv3.1

The subprotocol used for websockets. When using Paho.js this should be mqttv3.1

websockets.path

/mqtt

The path of the websocket

websockets.allowExtensions

false

Defines if websocket extensions are allowed.

websockets.maxHttpChunkContentLength

65536

The maximum content length of a chunked HTTP request

websockets.secure.enabled

false

When set to true, enables secure websockets for HiveMQ

websockets.secure.port

443

The port for the secure websockets.

Security

From the ground up, HiveMQ was designed with maximum security in mind. It is mission critical for many M2M scenarios to enable secure, encrypted end-to-end communication and advanced authentication and authorization features. HiveMQ gives you the flexibility to enable specific security features for your concrete use. The following shows how to enable and configure these security features.

SSL/TLS

Transport Layer Security (TLS) is a cryptographic protocol which allows a secure and encrypted communication at transport layer between a client application and a server. If TLS is enabled in HiveMQ, every client connection is encrypted and secured by TLS. It is also possible to use X.509 certificate client authentication, please see the chapter X.509 Certificate Authentication for more details.

Hybrid Mode
You can configure HiveMQ to use a hybrid mode which means that HiveMQ can handle encrypted and unencrypted connections simultaneously. See the Hybrid Mode chapter for more details.

For usage scenarios where sensitive information is published via MQTT it is strongly recommended to enable TLS. When configured correctly it is very very hard [1] for an attacker to break the encryption and read the packets on the wire. Since TLS is a proofen technology and the whole transport is encrypted, TLS could be a better choice than a hand-rolled payload encryption when security is more important for your scenario than package overhead. See the Infobox for more details.

As in most cases, added security comes with some disadvantages. The most important disadvantage is, that SSL/TLS comes with a signifcant increase in used bandwidth. While we are talking of tens of bytes here, it can make a huge difference in scenarios where small bandwidth usage is key. Please note that the SSL handshake (which takes place when a connection is established) comes with an additonal overhead in terms of bandwidth and CPU. This is very important to consider when you have to deal with many unreliable connections which could easily drop.

Encryption at Transport Layer vs Encryption at Application Layer

Encryption at transport layer [2] has the advantage that the whole connection is encrypted, including all MQTT messages sent from the client to the server and from the server to the client. This ensures that nobody but the client which is connected to HiveMQ can read any message of the communication. Since the payload of the MQTT message remain unencrypted raw bytes in this case, fully interoperability with other MQTT clients (even if they do not use TLS) is ensured. All MQTT messages (not only PUBLISHes) are secured with this technique.

Encryption at application layer means that the payload of a MQTT PUBLISH message is encrypted with an application specific encryption and only clients who know how to encrypt the payload can read the original message. When not used together with TLS the transport is unencrypted and attackers could read the raw message on the wire. If the attacker does not know how to decrypt the payload, the payload of the MQTT PUBLISH message is secure. It is important to understand that only the payload of a MQTT PUBLISH can be encrypted, all other information like the topic of the message is unencrypted. Only PUBLISH payloads can be encrypted, all other MQTT messages like CONNECT cannot be secured with this technique

Of course both encryption techniques can be used together. If it is important for your scenario that only few trusted clients can decrypt the contents of specific MQTT publishes and you want to secure your complete communication, this could be a great fit.

Configuration

To enable SSL/TLS, the following properties have to be modified in the configuration.properties file. Please see the Configuration chapter for more details.

Table 4. Configurations for SSL/TLS
Property Description

ssl.enabled

You have to set this property to true to enable SSL

ssl.port

The port where SSL connections are received. Defaults to 8883

ssl.handshakeTimeout

The timeout in seconds for a SSL handshake. All clients which need longer for a SSL handshake than the specified timeout will be disconnected. Set to 0 if you do not want to set a timeout

keystore.location

The location of the servers Java Key Store

keystore.password

The password for the Java Key Store. Leave empty if no password is set.

truststore.location

The location of the Java Trust Store

truststore.password

The password for the truststore. Leave empty if no password is set.

At the moment only Keystores in the JKS format can be used. Also make sure that the password of your keypair is the same as the password of the keystore.

Java Key Stores & Trust Stores

Java Keystores and Java Truststores are containers which contain information needed for SSL like X.509 certificates and keys. Typically each truststore and each keystore is persisted in one single file and they are protected by a master password.

Keystores and Truststores are conceptually similar but there is a difference in duty. In a SSL context, Keystores provide credentials and Truststores verify credentials. That means, a Keystore contains a public key certificate and the corresponding private key. [3] Servers (like HiveMQ) typically use keystores to protect the private key for their SSL connections.

Truststores contain trusted certificates or certificates signed by a CA in order to identify the partner of the SSL connection. Typically clients which want to connect to a server have to store the certificate of the server (or the trusted CA when the server certificate was signed by a CA) to identify the server as a trusted server. When using client certificate authentication on the server side, the trusted certificates of the client also have to be in the truststore.

It is possible to use the same file as Keystore and Truststore. However, we recommend strongly to separate the Keystore and Truststore when using HiveMQ.

If you are not sure how to create a Keystore, you can find some useful information in the Appendix of this document.

Hybrid Mode

HiveMQ can be configured to run in Hybrid Mode. That means that HiveMQ is able to handle standard TCP connections on one port and SSL/TLS connections on another port. This is completely transparent and all clients can communicate among themselves via Publish/Subscribe regardless how they are connected to the broker. Clients can decide if they want to use SSL/TLS or a "standard" TCP, non SSL connection. This is extremely useful when some clients only have a unreliable network connectivity and/or very limited available bandwidth where every additional byte overhead matters and bandwidth efficiency is more important than a secure connection. In this case, these clients can connect to HiveMQ via the unsecured port while other clients can use a secure connection via the SSL enabled port.

Table 5. Relevant properties for enabling the hybrid mode in the configuration.properties file
Property Name Description

ssl.enabled

You have to set this property to true to enable SSL

ssl.hybridMode

If the hybrid mode is enabled and SSL is activated, SSL and standard TCP connections are supported simultaneously

A prerequisite for enabling the hybrid mode is that SSL is enabled. Set the property ssl.enabled in the configuration.properties file to true. To enable the hybrid mode, also set the property ssl.hybridMode to true.

Enable SSL to enable the hybrid mode
Do not forget to enable SSL, otherwise the property ssl.hybridMode will have no effect.

Of course it is also possible to allow different kinds of Authentication in such scenarios where hybrid mode is used. It is possible to allow X.509 Client Certificate Authentication for SSL secured connections to authenticate and authorize clients and Username/Password Authentication for connections which are not secured by SSL.

Since HiveMQs hybrid mode is very powerful, it is possible to implement a scenario where SSL clients gain more permissions than non-SSL clients. So standard TCP connections could be implemented as anonymous clients while SSL clients could be implemented as authenticated clients. This comes in very handy when you are for instance providing MQTT services to other customers and you have to differentiate between different kind of clients.

The standard TCP connection port and the SSL port must be different ports. It is important to understand that it is not possible to connect to the standard TCP port with an SSL enabled client and it is not allowed to connect to the SSL port with clients who do not initiate a SSL handshake (= non-SSL clients).

Secure Websockets

HiveMQ has native support for secure websockets. Secure Websockets use the same keystore for the TLS encryption as standard MQTT over SSL. After making sure the keystore location and password are correct and secure websockets are enabled, you can transparently use MQTT over secure websockets in web applications.

Authentication, Authorization & Permissions

HiveMQ offers several ways to implement authentication and authorization for your concrete use case. HiveMQ allows everything for every client by default. That means, if you don’t need any authentication or authorization for your scenario, you can skip this chapter. Even when you provide an username and password in the MQTT CONNECT message, HiveMQ ignores it and gives a client, which provides credentials the same permissions as a client, which do not provide any credentials.

You can use HiveMQs powerful plugin system to add authentication and authorization behaviour.

Authentication

It is important to understand that there are two levels of authentication which can occur. The first type is the authentication with X.509 client certificates on the transport layer. The second type is Username/Password authentication. This takes place when a MQTT CONNECT message is sent by the client and recognized on the application layer.

Authorization & Permissions

All authorization and permission logic has to be added to HiveMQ by plugins. For typical use cases, many plugins already exist, so it is sufficient in most cases to select your authorization plugin of choice and plug it into HiveMQ. A list of plugins can be found here.

Since X.509 client certificate authentication happens when the SSL Handshake occurs, there is no application context because this happens on the transport. Classically no application authorization logic can be performed at this stage, because this happens on the transport layer. Fortunately HiveMQ offers authorization based on SSL certificates via its powerful plugin system. This enables you to authenticate and authorize the client with X.509 client certificates.

When authentication via the MQTT CONNECT message is enabled, you can implement an authorization based on the credentials provided here. We experienced that for many use cases this is sufficient and easier to implement than SSL client certificate authentication. The credentials provided in the CONNECT message are username/password combinations which you can validate. Many plugins exits, which enable HiveMQ to read credentials from a file or database.

X.509 Client Certificate Authentication

To activate X.509 client certificate authentication at transport layer in HiveMQ, there are a few prerequisites. Optionally it is possible to add additional application level authentication and authorization with the client certificate to implement more advanced scenarios where it is not sufficient enough to have authentication on the transport level.

Prerequisites
  1. SSL must be enabled in the configuration.properties file.

  2. A keystore and a truststore file must be configured in the configuration.properties file. The keystore must contain the server certificate and the server certificates private key. The truststore must contain all the client certificates or valid root certificates for the client certificates. See the Configuration Chapter for more details.

  3. You have to set ssl.clientAuthenticationMode to optional or required in the configuration.properties file.

  4. (optional) ssl.applicationClientAuthentication must be set to true in the configuration.properties file if you want application level authentication & authorization additionally to transport level authentication.

  5. (optional) If you need application level authentication & authorization based on the X.509 client certificates, you need a HiveMQ plugin which implements this.

Distinguish application and transport layer authentication
It is very important to understand the difference between application layer authentication and transport layer authentication. Transport layer authentication is not a concept introduced by HiveMQ but a concept from the TLS-Handshake. Application layer authentication is a security implementation of HiveMQ and is — as you could have guessed — application specific. It is absolutely possible to reuse your keystore and truststore for your transport layer client authentication in other server applications which support this concept, too.

The following diagram shows the schematic X.509 client certificate authentication flow. Especially the SSL part of the diagram is technically not 100% correct but for the sake of grasping the concept this should be sufficient.

4_schematic_certificate_flow
Figure 1. A schematic overview of the X.509 certificate authentication flow

Username and Password Authentication and Authorization

The most common practice for authentication when using MQTT is by far classic username/password credential matching. In the official MQTT specification, the MQTT CONNECT message defines username and password sections in the message payload. HiveMQ utilizes these credential fields to enable application level authentication & authorization.

Prerequisites
  1. Install a plugin which handles credential matching.

In general, all clients whose credentials are invalid (the plugin decides if they match or not) are disconnected with the corresponding MQTT CONNACK message, which returns code 4 (bad username or password).

You have to install a plugin, which enables the functionality to handle usernames and passwords. By default all username/password combinations (even anonymous) are allowed and all permissions are gained automatically.

The following diagram shows a schematic overview how the authentication is performed.

4_schematic_username_password_flow
Figure 2. A schematic overview of the Username/Password authentication flow

There are many plugins for authentication available and it is easy to create one at your own if you need something more fancy.

Client ID Authentication and Authorization

Additional to classic username/password authentication it is possible to add authentication and authorization logic with client identifiers. In principle this is exactly the same as username/password authentication with the difference that only the client identifier field of the MQTT CONNECT message is used.

Prerequisites
  1. Install a plugin which handles credentials authentication & authorization.

For a list of plugins see the plugin directory.

The following diagram shows a schematic overview how the authentication is performed.

4_schematic_clientid_flow
Figure 3. A schematic overview of the Username/Password authentication flow
Use cases

There are several use cases for client identifier authentication and authorization logic. Some popular are:

  • You want to make sure that only client identifiers with a specific pattern can connect. Like myapp-client1. Only clients which start with myapp should connect.

  • You want to make sure that only a subset of clients connect to this HiveMQ cluster node based on the client identifier.

  • The client identifiers are MAC adresses of your devices and you cannot use username/password authentication because it is not possible to deploy a different username/password combination on every device.

Logging

Per default, HiveMQ writes all log data to the log subfolder. For every day an archived log file is created with the name hivemq.$DATE.log.

The most current logfile is always named hivemq.log. The current log has a log rolling policy which means that it will always be archived on midnight. A file will be archived for 30 days before it is deleted. It is recommended manually backup the log files if you want to archive them longer.

The following example shows typical entries of the +log+subfolder.

Example 1. log folder contents
hivemq.log
hivemq.2013-05-11.log
hivemq.2013-05-12.log
hivemq.2013-05-13.log

Monitoring

The ability to monitor server applications is very important for operating these applications. HiveMQ is no exception, in fact HiveMQ was designed to enable different kinds of monitoring easily. When using HiveMQ in critical infrastructure, it is strongly recommended to enable monitoring and use a decent application for displaying the relevant information you need for your operations.

Table 6. Relevant properties for monitoring in the configuration.properties file
Property Name Description

statistics.enabled

If statistics are enabled or not. If you disable statistics, the $SYS topic is also disabled.

statistics.updateInterval

Interval in seconds for updating statistics internally. Too low intervals could result in performance loss. It is recommended, that the statistics_update_interval is smaller than the sys_interval and the statistics_callback_interval

Enable Statistics

To enable statistics, the statistics.enabled property has to be set to true in the configuration.properties file. It is important to set a reasonable statistics.updateInterval value (the default is 30 seconds). All counter statistics [4] are only updated once in an update interval while other statistics are updated all the time. If it is important for you to have up-to-date counter statistics, set the the update interval to a low value. Please be aware that when the update interval is too low, significant performance loss can occur. A too high update interval will result in old statistics.

Disabling statistics for performance
You can disable statistics completely by setting statistics.enabled to false in the configuration.properties file. If you want to sacrifice monitoring abilities for maximum performance, this option is for you. Be sure to measure if you really gain significant performance wins when disabling statistics. It is not possible to enable or disable statistics without restarting HiveMQ.

If statistics are enabled, you can choose between several integrated monitoring options.

JMX

HiveMQ has extensive support for Java Management Extensions (JMX) to monitor HiveMQ. JMX is a proofen standard and many external tools support JMX natively or via extensions.

Enabling JMX

To enable JMX, open the bin/run.sh script and uncomment the line which begins with:

#JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote

Be sure to set all JMX options properly according to Oracles official JMX documentation

MBeans

When JMX is activated, There are a few MBeans which can be used for monitoring

MBean Name Description

com.dcsquare.hivemq

This is the most important MBean for monitoring HiveMQ itself. All statistics can be monitored here.

Speed4j

All Plugin Monitoring Information can be monitored here.

java.lang

All information about the Java Virtual Machine can be monitored here.

org.infinispan

All information about the Infinispan Cache can be monitored here.

It can be very dangerous to use JMX Operations (especially on the org.infinispan MBean) because damage your running HiveMQ instance. Be sure to use JMX only to monitor and not to reconfigure HiveMQ at runtime.

Graphite

Graphite is a graphing system which is awesome for monitoring and displaying statistics of different data sources. It’s highly scalable and a perfect fit when monitoring many HiveMQ cluster nodes. Even for single HiveMQ instances it’s worth taking a look when the built-in JMX Monitoring is not sufficient for your use case or when you want to preserve statistics history.

Graphite Server
It is strongly recommended that Graphite is installed on a different server than HiveMQ.
Table 7. Relevant properties for Graphite in the configuration.properties file
Property Name Description

graphite.enabled

Enable the monitoring with Graphite

graphite.interval

The interval for publishing metrics to Graphite in seconds. Too low intervals could results in possible performance losses.

graphite.url

The Graphite URL. Must be in the format "hostname:port"

graphite.metricPrefix

A prefix for every metric which is sent to the Graphite instance. Useful for distinguishing between different HiveMQ servers or when using a hosted Graphite service to prefix the API Key

HiveMQ picks up the changes everytime it is (re)started. It is important to set a sane graphite.interval. It is recommended that this interval is at least as high as the statistics.updateInterval.

If you are using a hosted Graphite solution which requires a prefixed API Key, you can use the property graphite.metricPrefix for setting your API key.

Mixing HiveMQ statistics with other system statistics
You can mix datasources in Graphite. Besides HiveMQ you can monitor the system resources like CPU or memory usage of a HiveMQ machine with tools like collectl.

$SYS Topic

Like many MQTT message brokers HiveMQ supports a special MQTT topic (with subtopics) called $SYS Topic. MQTT clients can subscribe to this topic and receive system information and statistics of the HiveMQ MQTT broker. The following $SYS suptopics are exposed:

Table 8. $SYS subtopics
Topic Description

$SYS/broker/bytes/per second/received

The average bytes received per second

$SYS/broker/bytes/per second/sent

The average bytes sent per second

$SYS/broker/bytes/received

The total bytes received

$SYS/broker/bytes/sent

The total bytes sent

$SYS/broker/changeset

The changeset number. Deprecated.

$SYS/broker/clients/active

The currently connected clients.

$SYS/broker/clients/inactive

The clients which are not connected at the moment but connected with cleanSession=false.

$SYS/broker/clients/maximum

The maximum number of active clients which were connected simultaneously.

$SYS/broker/clients/total

The total count of active and inactive clients.

$SYS/broker/heap/current size

The current JVM heap size

$SYS/broker/heap/maximum size

The maximum JVM heap size

$SYS/broker/heap/maximum used size

The used JVM heap size.

$SYS/broker/messages/per second/received

The average received MQTT messages per second.

$SYS/broker/messages/per second/sent

The average sent MQTT messages per second.

$SYS/broker/messages/received

The total received MQTT messages.

$SYS/broker/messages/sent

The total sent MQTT messages.

$SYS/broker/messages/stored

The sum of all retained messages and all messages which are queued but not published yet. Refreshed all 30 seconds.

$SYS/broker/publish/messages/received

The total MQTT PUBLISH messages received.

$SYS/broker/publish/messages/sent

The total MQTT PUBLISH messages sent.

$SYS/broker/retained messages/count

The amount of all retained messages.

$SYS/broker/subscriptions/count

The total count of subscriptions

$SYS/broker/timestamp

The current timestamp on the broker. Only published on subscription.

$SYS/broker/uptime

The uptime of the broker in seconds. Only published on subscription

$SYS/broker/version

The HiveMQ version. Only published on subscription

$SYS Topic standard
There is no standardization or common definition of what $SYS topics should exist. These special topics are not fully interoperable between MQTT message brokers and clients must not rely on these topics.

It is not possible for any client to publish to the $SYS topic or one of its subtopics. These values are published exclusively by HiveMQ.

Table 9. Relevant properties for the $SYS topics in the configuration.properties file
Property Name Description

sys.enabled

If the $SYS tree should be available or not.

sys.interval

Time in seconds between publishes of the $SYS tree

$SYS topics are enabled by default. To disable the publishing of the $SYS topic tree, set the sys.enabled property to false.

Be sure to set the sys.interval property to a value which is at least the value of statistics.updateInterval.

Disabled statistics
The $SYS topic values are not published when statistics are disabled. Be sure to set statistics.enabled to true when you want to use the $SYS topics.

Resource Consumption Logging

For basic resource logging purposes like logging CPU and memory consumption, HiveMQ is able to append system resource information to the log file frequently. This is useful in scenarios where you do not need a full monitoring solution like Graphite.

Resource monitoring
For serious use cases it is recommended to use a monitoring solution like Graphite to monitor the resource consumption of a system. Collectl works very good as data source for Graphite in such cases.
Table 10. Relevant properties for resource consumption logging in the configuration.properties file
Property Name Description

measureResourceConsumption.enabled

Enables the resource consumption logging.

measureResourceConsumption.interval

Time in seconds between logging of the resource consumption

Resource consumption logging is disabled by default. To enable the resource consumption logging, set the property measureResourceConsumption.enabled to true. To avoid too many log entries, set the measureResourceConsumption.interval to a sane number.

It is probably hard to identify performance peaks when using this technique for monitoring HiveMQ because the resource consumption statistics are collected once every interval and are only snapshot.

Monitoring of Plugins

With the powerful HiveMQ Plugin System it is possible to add integration plugins for virtually everyting you can imagine. A common pitfall when writing plugins is that these plugins block the HiveMQ communication threads in some way and the HiveMQ overall performance can decrease dramatically. Fortunately HiveMQ offers a way to monitor the execution time of plugins on specific callbacks via JMX.

Table 11. Relevant properties for plugin monitoring in the application.configuration files
Property Name Description

plugin.performanceMonitoring

Enable to monitor the performance of plugins. When enabled this will result in a significant performance loss.

The plugin.performanceMonitoring property must be set to true when you want to enable the plugin performance monitoring. Since the property resides in the application.properties file, the monitoring can be enabled and disabled at runtime. It is however good practice to only enable the performance monitoring when needed or when developing plugins.

Performance Considerations
Enabling plugin performance monitoring should only be enabled for debugging and should not be activated in production as the plugin monitoring can decrease the HiveMQ performance dramatically under high load.

To inspect the different plugin, open JConsole or JVisualVM (with the MBean Plugin) and look at the MBean "Speed4j". All callbacks which are implemented by the plugins are shown and you can inspect different statistics for the callback. The relevant values are:

Table 12. JMX Plugin Performance Monitoring attribute values
Attribute Name Description

callback/95

The average execution time of the callback in ms after applying a 95th percentile

callback/avg

The absolute average execution time of the callback in ms

callback/count

The execution count of the callback

callback/max

The slowest execution time of the callback in ms

callback/min

The fastest execution time of the callback in ms

callback/stddev

The average execution time of the callback in ms after applying standard deviation

Clustering

One of the outstanding features of HiveMQ is the ability to form a MQTT Broker cluster. It is easy to implement High Availability Services with HiveMQ as well as high performance clusters with massive message throughput. The elastic cluster functionality makes it easy to add cluster nodes at runtime. HiveMQ utilizes Infinispan and JGroups for the transport and so it is possible to implement even very complex scenarios.

Using MQTT broker clusters has advantages over broker bridging, which is essentially just a broker acting as a client. Although bridging is not an official part of the MQTT spec and there are many disadvantages compared to clustering, HiveMQ will support bridging natively as an alternative to clustering soon. [5]

Cluster vs Bridging
Bridging has some disadvantages when it comes to reliability and performance. Although MQTT is a very lightweight protocol, you bear the whole protocol overhead with you with every message when using bridging. To guarantee that a message arrives at the bridged broker only once, bridging has to be configured with MQTT QoS 2, which is a massive overhead compared to the cluster communication mechanisms. Bridges only allow point-to-point broker connections which makes it harder to scale with many brokers. Also, hot standby scenarios with loadbalancers in front are trickier with bridges due to the lack of a replicated client sessions across the brokers.

Prerequisites

Clustering is disabled by default. To enable clustering you need two additional files in your conf folder:

  • infinispan.xml

  • cluster.xml

These are the concrete steps you should follow to enable clustering:

  1. Copy the infinispan.xml file from the conf/examples folder to the conf folder

  2. Choose a cluster-*.xml file from the conf/examples which suits your use case best. Copy it to the conf folder and rename it to cluster.xml.

  3. (optional and for experts only!) Modify the relevant parts of the cluster.xml to optimize the cluster communication for your concrete use case. Use the JGroups Protocol Documentation for that.

For most cases you don’t need to modify the infinispan.xml file. If you need to modify the configuration of the persistent client session and information cluster, be sure to preserve the distribution and replication configurations, otherwise HiveMQ will not work as expected or even break.

Misconfiguration
When modifying the infinispan.xml file, you will most likely break something when you are not 100% sure what you are doing. No guarantees can be made for data integrity or message broker functionality when misconfiguring the infinispan.xml file.

Elastic Cluster with UDP Multicast

When you have control over your network infrastructure or you need a true autodiscovery mechanism which detects cluster nodes when they start up in the same network, then UDP multicast is a perfect fit. This is no master-slave scenario, so there is no single point of failure on the HiveMQ node side and you can scale out quickly by just starting up a new HiveMQ node. It’s also a good starting point for playing around with HiveMQs cluster functionality if you are new to these topic.

Please follow these steps to get your UDP cluster up and running. These steps must be made for every HiveMQ cluster node.

  1. Copy the infinispan.xml file from the conf/examples folder to the conf folder

  2. Copy the cluster-udp.xml file from the conf/examples folder to the conf folder and rename it to cluster.xml.

  3. (optional) Modify the cluster.xml and adjust the parameters to your need.

HiveMQ instances will automatically form a cluster now when they find themselves.

It doesn’t work!!!

Although we do our best do give you the smoothest cluster setup experience, cluster configuration is a complex subject and there are many error sources. Here a few things you could check if something doesn’t work:

  • Is your firewall enabled and not configured accordingly (Tip: Disable the firewall for testing)

  • Are your cluster nodes in the same network?

  • Is multicast enabled on your machine? Is multicast supported by your switch/router?

Be sure to read the JGroups Documentation to help troubleshooting.

Fixed size cluster with TCP

There are some scenarios where you probably do not want the HiveMQ cluster to be elastic, can’t or don’t want to use multicast, or you don’t want autodiscovery because you already know all your cluster nodes. This is often the case when you want to build something like a High Availability MQTT Cluster [6] for example.

Please follow these steps to get your TCP cluster up and running. You will get a cluster which uses TCP for transport and has a list of servers hardcoded. These steps have to be one for every HiveMQ cluster node.

  1. Copy the infinispan.xml file from the conf/examples folder to the conf folder

  2. Copy the cluster-tcp.xml file from the conf/examples folder to the conf folder and rename it to cluster.xml.

  3. Modify the cluster.xml and add the server IPs to initial_hosts in the TCPPING section.

  4. (optional) Modify the cluster.xml and adjust the parameters to your need.

You can of course use TCP for the node communication transport and use UDP multicast autodiscovering new nodes like in the previous chapter. For detailled information, please see the JGroups Documentation.

EC2 Cluster

HiveMQ works perfectly on EC2.

This section is currently under review and will be available soon.

Need help?
If you need professional support for your HiveMQ cluster, dc-square GmbH offers consulting for configuring, optimizing and managing HiveMQ clusters for you. Contact us to find out how we can help you.

Plugins

One of the outstanding features of HiveMQ is its ability to extend HiveMQ with virtually every functionality you can imagine. HiveMQs plugin system is highly event and callback oriented, which allows a deep integration of HiveMQ into your already existing application- and IT infrastructure.

Different kind of plugins

There are two kinds of plugins available for HiveMQ:

  • Service Integration Plugins

  • Security Plugins

Service Integration Plugins are plugins which aim to provide additional business functionality to HiveMQ. Examples for this kind of plugin are for example: MQTT message logging plugins, database persistence plugins, billing plugins for clients, Enterprise Service Bus (ESB) plugins, Complex Event Processing (CEP) plugins and many more.

Security Plugins are plugins which enable HiveMQ to use your existing user, device and permission data models or services for authentication and authorization. The security plugins are the glue between your authentication and authorization data and the HiveMQ MQTT message broker. Example plugins are: database authentication & authorization plugins, LDAP plugins, X.509 client certificate authentication plugins, password list plugins and many more.

A list of officially supported plugins can be found here.

Installing Plugins

The installation of plugins is very simple: Download the zip archive of your desired plugin and drop the contents into the HiveMQ plugins folder.

Instructions for installing plugins
  1. Download a plugin from the HiveMQ plugin store

  2. Unzip the contents of your download.

  3. Copy the contents of the zip file to $HIVEMQ_DIRECTORY/plugins.

  4. Modify the properties of the plugin according to the plugins installation guide or readme file.

Validating if the plugin works

HiveMQ will log every plugin it uses when starting up. A typical log entry with a plugin enabled looks like the following listing

Startup log with an enabled plugin
 21:55:48.140 [HiveMQServer STARTING] I com.dcsquare.hivemq.HiveMQServer - Starting on port 1883
 21:55:48.157 [HiveMQServer STARTING] I com.dcsquare.hivemq.HiveMQServer - Loaded Plugin Access Log Plugin - v1.0-SNAPSHOT
 21:55:48.158 [main] I com.dcsquare.hivemq.HiveMQServer - Started HiveMQ in 2051ms

Configuring Plugins

Every plugin comes with its own configuration file (if it needs any). Please read the installation guide or the readme which comes with every officially supported plugin.

Developing Plugins

HiveMQ can can be deeply integrated in your existing application- and IT infrastructure. For complex or unique scenarios there is often no one-size-fits-all plugin. HiveMQ gives the ability to write your own plugins for your very own integration scenarios.

The public SDK is available for free and open source on Github. For more information about developing HiveMQ plugins, please refer to our extensive Plugin Documentation.

Professional plugin development

For individually developed and fully supported HiveMQ plugins which are guaranteed to scale with the HiveMQ MQTT broker, don’t hesitate to contact us. Of course, plugin development trainings are available on demand, too.

Throttling & Limits

When hosting HiveMQ in environments where your resources in form of CPU, memory or bandwidth are limited it can be crucial to limit the bandwidth or the maximum TCP connections HiveMQ can accept to save resources and avoid abuse of malicious clients.

All throttling and limit properties reside in the application.properties file and they can be adjusted at runtime, which means you don’t have to restart HiveMQ when applying throttling parameters.

Limiting connections

You can apply a global connection limit to HiveMQ. That means, after a defined number of open TCP connections, HiveMQ automatically inhibits new client TCP connections. Limiting the connections can be pretty handy if your server hardware resources are limited.

Table 13. Relevant properties for limiting connections in the application.properties file
Property Name Description

global.maxConnections

Maximum allowed concurrent connections. Use -1 for unlimited connections.

By default, the global.maxConnections property is set to -1, which means HiveMQ can handle unlimited connections. [7].

If you set the value of global.maxConnections to a lower number than the amount of currently connected clients, the currently connected clients will not be disconnected.

If you run HiveMQ in Hybrid Mode, be aware that the concurrent connections are globally for this HiveMQ instance and there is no differentiation between SSL and standard TCP connections when using a global connection limit.

Connection Limits
If you set a connection limit which is higher than the connection limit defined by your license, the higher limit will have no effect and the lower of the two limit will be used.

Throttling bandwidth

You can configure HiveMQ to globally throttle the incoming and outgoing network traffic for MQTT clients if you don’t want to reserve all your bandwidth for HiveMQ or if you want to artificially slow down all clients.

Throttling message throughput
A convenient way of limiting the message throughput of HiveMQ when you have many subscribers is to throttle the incoming traffic. If your system resources such as CPU and RAM are almost exhausted this is an efficient and quick way to limit the maximum incoming messages. A sane global throttling by default can prevent performance peaks.
Table 14. Relevant properties for limiting bandwidth in the application.properties file
Property Name Description

global.outgoingLimit

Maximum kb/s for outgoing traffic. Use 0 if you don’t want to throttle outgoing traffic

global.ingoingLimit

Maximum kb/s for ingoing traffic. Use 0 if you don’t want to throttle ingoing traffic

These properties reside in the application.properties file, which allows you to modify the values of the properties at runtime so you do not have to restart HiveMQ for enabling or disabling throttling. These values are reloaded once a minute.

Throttling incoming traffic

To throttle incoming traffic, you can set the property global.ingoingLimit to a value higher than 0. A zero value means that throttling is disabled. All values mean kilobyte per second (kb/s).

Throttling outgoing traffic

To throttle outgoing traffic, you can set the property global.outgoingLimit to a value higher than 0. A zero value means that throttling is disabled. All values mean kilobyte per second (kb/s).

Throttling individual clients
With HiveMQs powerful Plugin System it is possible to throttle individual clients based on credentials, quotas or other characteristics.

Limiting MQTT message sizes

The MQTT protocol itself defines a MQTT PUBLISH payload size limit of 256MB. For a majority of the M2M scenarios this is a very high limit and most clients will probably never send a message with a payload which is that huge.

An convenient way set an upper message size limit is to use HiveMQs global message size limit which does not only restrict the MQTT PUBLISH payload but any message sent to the server.

Table 15. Relevant properties for limiting the message sizes in the application.properties file
Property Name Description

global.maxMessageSize

Maximum message size. The MQTT default for a message is 256MB. If clients must publish messages which are smaller, a saner message size limit should be configured.

To limit the upper size of incoming messages, set the property global.maxMessageSize in the application.properties file. The of the property is the maximum message size in bytes. 256MB is the default value to be in conformity with the MQTT specification.

If a client sends a message which is bigger than the defined value, the server will discard the message after the threshold was exceeded. It is not possible for HiveMQ to detect that a message size in bytes is higher than the defined value before that many bytes were really sent by the client.

Malicious Clients
When you don’t limit the MQTT message size, it is very easy for attackers or malicious clients to steal your bandwidth and exhaust your servers memory when sending tens or hundreds of that huge messages at once for a longer period. You should strongly consider using a upper limit which suits your use case best.

Websockets

HiveMQ offers native support for all major websocket versions. All major browsers support are supported. Here is an exhaustive list of all supported browsers.

When using websockets with HiveMQ, there is no need to use a separate webserver for handling the HTTP requests and the websocket upgrade, HiveMQ handles this transparently.

There is also support for secure websockets out of the box. Secure Websockets allow secure communication over websockets and are a great way to increase security for your application. See the secure websockets configuration chapter for more information.

  1. Usages Essentially websockets enable every web application to be a full-fledged MQTT client. With the usage of a a supported MQTT Javascript library you can deliver MQTT messages to your web application with real push or publish messages to other MQTT clients. Every websocket connection gets treated like a "normal" TCP connection and HiveMQ does not differentiate between websocket and standard TCP connections.

Supported MQTT Javascript Libraries

In general, HiveMQ should support any MQTT v3.1 compliant Javascript library which utilizes websockets. We strongly recommend using the Eclipse Paho Javascript library.

Enabling Websockets

Websockets are disabled by default. The following properties have to be configured properly to enable websockets:

Table 16. Relevant properties for enabling websockets in the configuration.properties file
Property Name Description

websockets.enabled

This property enables websocket support for HiveMQ when set to true

websockets.port

The port used for websockets. Defaults to 80.

websockets.subProtocol

The subprotocol used for websockets. When using Paho.js this should be mqttv3.1

websockets.path

The path of the websocket

websockets.allowExtensions

Defines if websocket extensions are allowed.

websockets.maxHttpChunkContentLength

The maximum content length of a chunked HTTP request

To enable websockets, set websockets.enabled to true. If you don’t want to use 80 as the standard port for incoming HTTP requests, you can set another port via websockets.port.

If you are using Eclipse Paho, you probably don’t need to change the other websocket configurations.

To change the path of the websocket, set websockets.path to a value you like. If you want to allow websocket extensions, set websockets.allowExtensions to true.

The subprotocol defaults to mqttv3.1. If you really want to use another websocket subprotocol than mqttv3.1, set websockets.subProtocol to any value you like. Please bear in mind that HiveMQ only implements MQTT v3.1, so things could break.

If you want to adjust the HTTP Chunk Content Length, set websockets.maxHttpChunkContentLength to any value in bytes you like.

Enabling secure Websockets

To enable secure websockets, it is important that the properties keystore.location and keystore.password are configured properly. Most properties of Enabling Websockets also apply for secure websockets.

Table 17. Relevant properties for enabling secure websockets in the configuration.properties file
Property Name Description

websockets.secure.enabled

When set to true, enables secure websockets for HiveMQ

websockets.secure.port

The port for the secure websockets.

To enable the secure websockets, set websockets.secure.enabled to true. By default, secure websockets use port 443. To use another port, set websockets.secure.port to a value you like.

You can use standard websockets and secure websockets simultaneously. Just set websockets.enabled and websockets.secure.enabled both to true

Gotchas

Although a connection over websockets is not much different to standard TCP connections for HiveMQ, there are some gotchas because of the added complexity with websockets which you should be aware of:

  • HiveMQ expects that each MQTT message is aligned to one Websocket Frame. The Paho Javascript library supports this out of the box.

  • Only binary websocket frames are supported. All MQTT Javascript libraries should support Binary Websockets [8]

  • If you are using Secure Websockets, make sure that you don’t use a self signed certificate or that your browser accepts the certificate. In most cases you can browse directly to the Endpoint (use https!) and accept the certificate. Unfortunately most browsers do not support accepting untrusted certificates for websockets out of the box.

  • Client Certificate Authentication *should* work in theory but most browsers have severe bugs in this area at the time of writing. Although client certificate authentication is a great way to increase security, it is recommended to test thoroughly if your targeted browsers work for you.

Running HiveMQ in the Cloud

Infrastructure as a Service (IaaS) providers like Amazon Webservices (AWS) and Microsoft Windows Azure are excellent choices for building reliable and scalable infrastructures for your services or platforms. HiveMQ runs perfectly on any cloud infrastructure provider. This chapters covers step-by-step example configurations for popular IaaS providers. The prerequisites for every IaaS provider listed here are that you have a valid account for the desired service.

Running HiveMQ on Amazon Webservices (AWS)

This will explain how to install HiveMQ on a Amazon EC2 instance. The steps may vary when using Windows as operating system.

  1. Navigate to Instances on your EC2 Dashboard in the AWS Management Console.

  2. Click Launch Instance and start the wizard to launch a new instance. Select the Ubuntu 12.04 LTS AMI. [9]

  3. Follow the wizard and configure your EC2 instance.

  4. Create a new Security Group called MQTT with a custom TCP Rule with port 1883.

  5. Enable SSH Access: Create a Security Rule with a custom TCP Rule with port 22.

  6. Finish the wizard to start the EC2 instance creation.

  7. Now connect to your server instance via SSH.

  8. Execute the following command to install all required dependencies:

    sudo apt-get install unzip openjdk-7-jdk
  9. Download the latest HiveMQ version with the following command:

    wget --content-disposition http://www.hivemq.com/downloads/releases/latest
  10. Unzip HiveMQ:

    unzip hivemq-1.x.x.zip
  11. Start HiveMQ:

    cd hivemq-1.x.x
    ./bin/run.sh

Running HiveMQ on Microsoft Windows Azure

This will explain how to install HiveMQ on an Azure Linux VM. The steps may vary when using Windows as operating system.

  1. Create a new Virtual Machine via the Azure Web Interface. Select Ubuntu 12.04 LTS as Image. [9]

  2. After the Virtual Machine was created, we have to open the standard MQTT port which happens to be 1883. Go to the Endpoint Settings of your VM in the Azure Web Interface and create a new Endpoint. Use TCP as protocol and set the public and private port to 1883.

  3. Now connect to your server instance via SSH.

  4. Execute the following command to install all required dependencies:

    sudo apt-get install unzip openjdk-7-jdk
  5. Download the latest HiveMQ version with the following command:

    wget --content-disposition http://www.hivemq.com/downloads/releases/latest
  6. Unzip HiveMQ:

    unzip hivemq-1.x.x.zip
  7. Start HiveMQ:

    cd hivemq-1.x.x
    ./bin/run.sh

Appendix

Appendix A: HowTo configure SSL with HiveMQ and Keytool

  • Generate the server keystore

    keytool -genkey -keyalg RSA -alias HiveMQ -keystore server.jks -storepass hivemqServer -validity 360 -keysize 4096

    Enter all prompted information for the certificate and confirm with yes. Press Enter to use the same password as for the keystore.

  • Export certificate for client truststore

    keytool -export -alias HiveMQ -file hivemq-server.crt -keystore server.jks

    Enter the server keystore password before the certificate can be exported

  • Generate client truststore

    keytool -import -file hivemq-server.crt -alias HiveMQ -keystore client.jks

    The certificate will be shown and must be confirmed with yes, before the truststore is successfully created. Also there is the possibility to specify a password.

  • Place the server.jks in the HiveMQ directory and also create the following configuration and save it as configuration.properties

    ssl.enabled=true
    keystore.location=server.jks
    keystore.password=hivemqServer
  • Use client.jks to connect with a client

Appendix B: HowTo configure SSL with HiveMQ and Portecle

  • Download the newest version of Portecle from here and unzip it

  • Start Portecle with a double-click on the jar or java -jar portecle.jar in the console

    Portectl after start
    Figure 4. Portecle after start
  • Firstly create the server Keystore

    • Choose File → New Keystore from the menu and select JKS as Keystore type in the popup window

      Choose Java Keystore
      Figure 5. Choose Java Keystore
    • Create a new Key Pair: Tools → Generate Key Pair

    • Choose a Key Alogrithm and Key Size

      Common Key Algorithm and Size
      Figure 6. Common Key Algorithm and Size
    • Enter the Signature Algorithm (recommended is SHA512withRSA) and the Certificate Details

      Certificate Signature Algorithm and Details
      Figure 7. Certificate Signature Algorithm and Details
    • Choose a Key Pair Entry Alias.

      An alias for the key pair
      Figure 8. An alias for the key pair
    • Set a password for the Key Pair Entry

      A password to protect the private key
      Figure 9. A password to protect the private key
      Successful Generation of Key Pair
      Figure 10. Successful Generation of Key Pair
    • Save the Keystore: File → Save Keystore As…

      Save the Keystore
      Figure 11. Save the Keystore
    • Export the certificate for the client: Right Click on the certificate key pair and click Export

    • Select Head Certificate as Export Type and choose an export format (recommended is PEM)

      Export Details
      Figure 12. Export Details
    • Choose directory to save the certificate

      Export Successful
      Figure 13. Export Successful
  • Secondly create the client Keystore

    • Choose File → New Keystore from the menu and also select JKS as Keystore Type

    • Import the just saved certificate via Tools → Import Trusted Certificate

    • Select the previous exported certificate

      Import server head certificate
      Figure 14. Import server head certificate
    • Confirm the message that the trust path could not be established. This is because the certificate is self-signed and no certificate chain can verify it.

      Warning because of the self-signed certificate
      Figure 15. Warning because of the self-signed certificate
    • Confirm the showed certificate details

      Certificate Details
      Figure 16. Certificate Details
    • Trust the certificate with clicking Yes.

      Accept to trust our created self-signed certificate for the server
      Figure 17. Accept to trust our created self-signed certificate for the server
    • Enter an alias

      Alias for the server certificate in the client keystore
      Figure 18. Alias for the server certificate in the client keystore
      Successful import of ther server certificate in the client keystore
      Figure 19. Successful import of ther server certificate in the client keystore
    • Save the Keystore as client.jks with File → Save Keystore As…

  • Place the server.jks in the HiveMQ directory and also create the following configuration and save it as configuration.properties

    ssl.enabled=true
    keystore.location=server.jks
    keystore.password=yourSpecifiedPassword
  • Use client.jks to connect with a client


1. at the time of writing, most attacks on TLS are of theoretical nature
2. Technically TLS works at OSI Layer 5 and 6. For the sake of simplicity we call it transport layer through the document
3. We strongly recommend to refresh your knowledge about private and public key cryptography if you are not sure what this means. This link provides useful information.
4. Counter statistics are Ingoing/Outgoing bytes, Ingoing/Outgoing (MQTT) messages and Ingoing/Outgoing MQTT PUBLISHES
5. The same functionality could be built easily with a plguin, though.
6. see this blog post
7. This is only true if your license allows unlimited connections. Otherwise you are restricted to the maximum connections which is defined by your license
8. It would hardly make sense to use Text Websocket Frames for a binary protocol like MQTT.
9. You can of course use other Linux distributions or Windows. In this case you most likely have to use other tools than apt-get to install the dependencies like Java.