General Installation Information

This guide walks you through basic installation and optimization steps for HiveMQ.

For more ways to try out and evaluate HiveMQ such as Docker and AWS, see Getting Started with HiveMQ.

You can download HiveMQ in a convenient ZIP package with all the executable files, initialization scripts, and example configurations you need to successfully install HiveMQ.

The HiveMQ download package contains the following directories:

The conf/examples directory of your HiveMQ installation contains several useful example configuration files.
Folder name Description

bin

Startup scripts and binary files.

conf

Configuration files.

data

Persistent client data and cluster data.

license

One or more HiveMQ license files.

log

All HiveMQ log files.

extensions

All extensions to the HiveMQ installation.

third-party-licenses

License information for third-party libraries.
HiveMQ Enterprise Extensions are preinstalled in your HiveMQ platform release bundle and disabled by default. To enable a HiveMQ extension, locate the desired extension folder in the extensions directory of your HiveMQ installation and remove the DISABLED file (if present). For more information, see HiveMQ Enterprise Extensions and Enable or Disable a HiveMQ Extension.

Installation on Unix-based systems (Linux, BSD, macOS, Unix)

The default installation directory for HiveMQ is /opt/hivemq. The default HiveMQ username is hivemq.

Some of the following commands require root privileges, log in as root user or use sudo to execute the commands.

  1. Log in as root user

  2. Go to the directory where you want to download and install HiveMQ. In this example, we use /opt.

    cd /opt

  3. On the HiveMQ website, select Download HiveMQ ZIP Archive to get a trial version of HiveMQ.

  4. Copy the provided download link and download HiveMQ

    wget --content-disposition <your download link>

    or

    curl -O -L <your download link>

  5. Extract the files

    unzip hivemq-<version>.zip

  6. Create a HiveMQ symbolic link (symlink)

    ln -s /opt/hivemq-<version> /opt/hivemq

  7. Create a HiveMQ user

    useradd -d /opt/hivemq hivemq

  8. Make scripts executable and change the 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

  9. Adjust the configuration properties to your needs.

    For more information, see Configuration.

  10. Install the Init script (optional)

    For Debian-based Linux distributions such as Debian, Ubuntu, or Raspbian that use init.d scripts

    cp /opt/hivemq/bin/init-script/hivemq-debian /etc/init.d/hivemq
chmod +x /etc/init.d/hivemq

    For Linux systems that use a systemd service

    cp /opt/hivemq/bin/init-script/hivemq.service /etc/systemd/system/hivemq.service

    For all other Linux systems

    cp /opt/hivemq/bin/init-script/hivemq /etc/init.d/hivemq
chmod +x /etc/init.d/hivemq

  11. Modify /etc/init.d/hivemq (optional)

    Set the HIVEMQ_HOME and the HIVEMQ_USER variables to the correct values for your system.

    The default values are as follows:

    HIVEMQ_HOME=/opt/hivemq

    HIVEMQ_USER=hivemq

    If you installed HiveMQ on a directory other than /opt/hivemq, point the HIVEMQ_HOME in your Init script to the correct directory. Otherwise, the daemon cannot start correctly.

  12. Start HiveMQ on boot (optional)

    For Debian-based linux such as Debian, Ubuntu, Raspbian

    update-rc.d hivemq defaults

    For Debian-based Linux such Debian, Ubuntu, Raspbian that use systemd

    systemctl enable hivemq

    Debian > 6.0

    insserv hivemq

    CentOS or RHEL

    chkconfig hivemq on

Start HiveMQ

The following instructions show how to start HiveMQ after the installation.

Start HiveMQ manually

  1. Change directory to HiveMQ directory

    cd /opt/hivemq

  2. Execute startup script

    ./bin/run.sh

Start HiveMQ as daemon

  1. Start the daemon

    /etc/init.d/hivemq start

Verify that HiveMQ is running

Check if HiveMQ is listening to the default port for MQTT

netstat -an | grep 1883

If you run HiveMQ as daemon:

/etc/init.d/hivemq status

If you run HiveMQ with systemd:

systemctl status hivemq.service

To debug the HiveMQ startup with systemd, you can inspect the output:

journalctl | grep -i hivemq

Windows systems

Manual installation

  1. Download the latest HiveMQ version from our website

  2. Unpack the hivemq.zip file to C:\hivemq.

Install HiveMQ as a Windows service

Follow these steps to install HiveMQ as a Windows service:

  1. Download the hivemq-windows-service.zip.

  2. Unzip the hivemq-windows-service.zip file.

  3. Copy the windows-service folder to your HiveMQ home folder.

  4. Open the windows-service folder.

  5. Double-click the installService.bat file.

  6. Restart your system.

To install a service, you need administrative rights.
If you currently lack the correct permission level, right-click the installService.bat file and select Run as administrator.

Start HiveMQ

The following instructions show how to start HiveMQ after installing:

Double-click the run.bat file.

Keep in mind that a click with the left mouse button (QuickEdit) stops the output of the command line. When you click the command line before "Started HiveMQT in xxx ms" displays, the HiveMQ start up process pauses. To resume the start up, click the right mouse button. Clicks that occur after the HiveMQ start up is complete do not impact the execution of HiveMQ.

Verify that HiveMQ is running

Check whether HiveMQ is listening on the default port for MQTT, 1883.

Open cmd.exe and run:

netstat -an | findstr "1883"

Set the heap that HiveMQ uses

The heap that the HiveMQ process uses can be set as a variable in the run.sh file (run.bat on Windows). Add a line with -Xmx to the variables.

Example configuration with a 4 GB heap:

############## VARIABLES
JAVA_OPTS="$JAVA_OPTS -Xmx4g"

Make the same changes to the recovery.sh file (recovery.bat on Windows).

We recommended that you configure the JVM heap with 50% of the RAM that is available on the system on which you run HiveMQ.

The HiveMQ process can use more RAM than the amount of RAM that you allocate to the JVM heap.

Install a HiveMQ License

To install a HiveMQ license, move the hivemq.lic file that you received with your purchase into the license folder of your HiveMQ installation.

HiveMQ automatically and dynamically recognizes licenses during runtime. There is no need to restart HiveMQ when you add or change your HiveMQ license.

When HiveMQ detects a valid license file, HiveMQ logs a statement similar to the following:

2020-08-20 20:49:44,322 INFO  - Found valid site license (hivemq.lic) issued to XXX for max XXX CPU cores, valid until XXX.

Multiple HiveMQ Licenses

New HiveMQ licenses can be added during runtime. When multiple valid license files are available in a HiveMQ installation, HiveMQ automatically selects the license that allows the highest CPU count.

If multiple valid licenses that allow the same CPU count are present, HiveMQ automatically selects the license that is valid longest.

You do not need to restart HiveMQ when you switch or add licenses during runtime.

Get a HiveMQ license
To obtain a HiveMQ license, contact sales@hivemq.com.

HiveMQ Sanity Checks

To quickly identify critical issues that can prevent your HiveMQ implementation from functioning as expected, HiveMQ automatically runs a brief set of tests to evaluate your current system configuration.
This type of testing is known as a sanity check.

HiveMQ runs an initial sanity check at startup and repeats testing every 12 hours (to catch configuration changes that are made during runtime). Each completed sanity check consists of several individual tests. For example, a test to verify the current open-file limits on your system and a test to verify if necessary file-access permissions are correctly configured.

HiveMQ logs a warning for each individual test in the completed sanity check that fails. The WARN log statement gives you detailed information about the test result and recommendations on how to correct the issue.

The presence of a failed sanity check does not prevent HiveMQ startup. The purpose of the HiveMQ log statements that a sanity check generates for failed tests is to help you identify inadequate or incorrect HiveMQ configurations and suggest appropriate action.

Open File Limit Test

The open file limit is the maximum number of files or network connections a process can open in the current active session. When an insufficient open file limit is specified for HiveMQ, a Too many open files error (or similar) can occur and prevent HiveMQ from functioning properly.

The open file limit test in the HiveMQ sanity check verifies whether the currently configured open file limits for HiveMQ are sufficient. The recommended hard and soft open file limits for HiveMQ are 1,000,000 each.

If your current open file soft-limit configuration is insufficient, HiveMQ prints the following warning to your HiveMQ log file:
Soft limit for open files ({your-current-soft-limit}) is lower than the recommended limit (1000000). Please increase the open file limit to at least the recommended limit.

If your current open file hard-limit configuration is insufficient, HiveMQ prints the following warning to your HiveMQ log file:
Hard limit for open files ({your-current-hard-limit}) is lower than the recommended limit (1000000). Please increase the open file limit to at least the recommended limit.

For information on how to increase your open file limit, see Increase open file limit.

You can view the open file limits that are currently configured for HiveMQ in the com.hivemq.system.os.process.open-file-limit.hard.current and com.hivemq.system.os.process.open-file-limit.soft.current metrics.
For more information, see Standard HiveMQ Metrics.

System Access Permissions Test

To operate correctly, HiveMQ requires access to various files and directories on your infrastructure. Your operating system controls access to files and directories with permissions that specify what users or processes are allowed to do in a particular file or directory.

HiveMQ sanity checks verify three types of Linux directory permissions:

  • Read (r): Allows the user or process to view the list of files a directory contains.

  • Write (w): Allows the user or process to edit, remove, or rename files that are stored in a directory.

  • Execute (x): Allows a user or process to change to a directory and use the files that the directory contains.

The system-access permissions test in the HiveMQ sanity check verifies whether your currently configured system permissions grant HiveMQ sufficient access to necessary files and directories.

If your currently configured system permissions lack a required permission, HiveMQ prints the following warning to your HiveMQ log file for the appropriate directory:
{file-name|directory-name} ({path}) is not {readable/writable/executable}. Please make sure that the {file|directory} has the correct {read/write/execute} permission.

Table 1. Sanity check for recommended HiveMQ directory permissions
Folder name Read Write Execute Behavior the lack of permission causes

data

HiveMQ cannot start
Persistence does not work

log

Logging is not available

license

HiveMQ license is not read
HiveMQ must start in trial mode

extensions

HiveMQ extensions cannot be discovered
HiveMQ extensions do not start

extensions/{extension}

Unexpected extension behavior can occur

backup

Backups cannot be retrieved with the REST API

audit

Audit logs cannot be written

java temporary directory
(java.io.tmpdir)

Unexpected behavior occurs

RocksDB tmp folder
(if ROCKSDB_SHAREDLIB_DIR environment variable is set)

RocksDB is unavailable
If RocksDB is used for persistence, HiveMQ cannot start

heap dump folder
(if HIVEMQ_HEAPDUMP_FOLDER environment variable is set)

Heap dumps cannot be created
HiveMQ increments the com.hivemq.system.sanity-checks.failed.count metric when one or more tests in a sanity check fails. For example, if two tests in a sanity check generate warnings, the com.hivemq.system.sanity-checks.failed.count increases by 1. For more information, see Standard HiveMQ Metrics.