General HiveMQ Platform Installation Information

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

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.
If you do not have a HiveMQ license, HiveMQ automatically runs in trial mode.
For more information on HiveMQ trial options, see Getting Started with HiveMQ. For information on how to install your license, see Install a HiveMQ License.

The HiveMQ platform download package contains the following directories:

The conf/examples directory of your HiveMQ installation contains several useful example configuration files.
HiveMQ directory structure
└─ hivemq-<version-number>
├── audit
├── backup
├── bin
│   ├── init-script
├── conf
│   ├── examples
├── data
├── extensions
│   ├── hivemq-allow-all-extension
│   ├── hivemq-enterprise-extensions-list
├── license
├── log
├── third-party-licenses
└── tools
│   ├── hivemq-swarm
│   ├── mqtt-cli
│   ├── rest-api
Directory Content

audit

HiveMQ audit log files.

backup

HiveMQ backup files

bin

Startup scripts and binary files:

  • diagnostics.bat

  • diagnostics.sh

  • hivemq.jar

  • recovery.bat

  • run.bat

  • windows-service.txt

  • init-script

    • hivemq

    • hivemq-debian

    • hivemq.service

conf

HiveMQ configuration files:

  • config.xml

  • config.xsd

  • declared-shared-subscriptions.xsd

  • examples A wide range of example configuration files to help you configure your HiveMQ deployment:

    • configuration

    • logging

  • logback.xml

  • README.txt

  • tracing.xml

  • tracing.xsd

data

Persistent client data and cluster data.

extensions

All HiveMQ Enterprise Extensions(disabled, by default), custom extensions to the HiveMQ installation, and the hivemq-allow-all-extension (enabled, by default).

license

One or more HiveMQ license files.

log

All HiveMQ log files.

third-party-licenses

License information for all third-party libraries HiveMQ uses.

tools

HiveMQ Swarm, MQTT CLI, and HiveMQ REST API.
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.
By default, HiveMQ only allows MQTT clients to connect if a security extension is present. For testing purposes, HiveMQ includes a hivemq-allow-all-extension that authorizes all MQTT clients to connect to HiveMQ. Before you use HiveMQ in production, you must add an appropriate security extension and remove the hivemq-allow-all-extension. You can download the HiveMQ Enterprise Security Extension from the HiveMQ website or develop your own custom security extension to fit your business needs.

HiveMQ Platform Installation on Unix-based systems (Linux, 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. On the HiveMQ Download page of the official HiveMQ website, enter your email address, read and accept the terms of service, and select Download.zip to download the latest version of HiveMQ.

  2. Log in to your system as root user.

  3. Move the ZIP download file to the directory where you want to install HiveMQ.
    In this example, we use /opt.

    cd /opt

  4. Extract the files from the ZIP archive:

    unzip hivemq-<version>.zip

  5. Create a HiveMQ symbolic link (symlink):

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

  6. Create a HiveMQ user:

    useradd -d /opt/hivemq hivemq

  7. Make scripts executable and change the owner to hivemq user.
    The chmod 775 command gives the user/owner and groups read, write, and execute rights. All others have read only access:

    chown -R hivemq:hivemq /opt/hivemq-<version>
chown -R hivemq:hivemq /opt/hivemq
cd /opt/hivemq
chmod +x ./bin/run.sh

  8. Adjust the HiveMQ configuration properties to fit your business needs.

    For detailed information and configuration examples, see HiveMQ Configuration.

  9. Register HiveMQ as a systemd service (optional):

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

  10. To start the HiveMQ systemd service on boot, run:

    systemctl enable hivemq

Set the heap that HiveMQ uses (Linux, macOS, Unix)

The heap that the HiveMQ process uses can be set as a variable in the run.sh file.
To set the heap value, add a line with the desired -Xmx to the VARIABLES configuration.

Example configuration with a 4 GB heap:

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

Make the same changes to the recovery.sh file.

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.

Start HiveMQ Platform (Linux, macOS, Unix)

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

Start HiveMQ Platform manually (Linux, macOS, Unix)

  1. Change to the HiveMQ directory.
    In this example, opt/hivemq:

    cd /opt/hivemq

  2. Execute the startup script:

    ./bin/run.sh

Start HiveMQ as daemon

  1. Start the daemon

    /etc/init.d/hivemq start

Verify HiveMQ is running

  1. 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

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

    journalctl | grep -i hivemq

HiveMQ Platform Installation on Windows Server

Automated Installation of HiveMQ Platform as a Windows Service (PowerShell Script)

HiveMQ provides a PowerShell script to automate the download, installation, and configuration of all the necessary components needed to set up your HiveMQ Platform on a Windows operating system.

The HiveMQ PowerShell script for Windows Server automates the following actions:

  • Download link validation: Checks all required software download links to ensure the necessary components can be downloaded during the installation process.
    Your Windows machine must have outbound internet access and be able to reach the following domains:

    • hivemq.com: Required for downloading the HiveMQ Broker software.

    • adoptium.net: Required for downloading the Eclipse Temurin OpenJDK JRE.

    • github.com: Required for downloading the HiveMQ MQTT CLI.

    • nssm.cc: Required for downloading the NSSM tool.

  • Java Runtime Environment (JRE) installation: Downloads and installs the appropriate Eclipse Temurin OpenJDK JRE version. Based on the HiveMQ version specified, the script determines the appropriate JDK version:

    • For HiveMQ versions 4.28.0 and above, OpenJDK 21.

    • For older HiveMQ versions, OpenJDK 11.

  • HiveMQ Broker installation: Downloads and installs the specified version of HiveMQ to the default installation directory C:\hivemq.

  • HiveMQ Broker configuration: Creates a basic configuration file for HiveMQ with default settings. The default HiveMQ config.xml file includes the following port settings:

    • TCP listener on port 1883 to allow MQTT clients to connect.

    • Control Center listener on port 8080 to enable access to the HiveMQ Control Center.

  • MQTT CLI installation: Downloads and installs the executable Windows version of the open-source MQTT CLI tool for testing and interaction.

  • Firewall rule configuration: Opens the necessary ports (1883 and 8080) in Microsoft Defender Firewall to allow external MQTT clients and users to connect to the HiveMQ Broker and the HiveMQ Control Center.

  • Port availability verification: Checks whether essential ports (1883 and 8080) are open and not in use to ensure that HiveMQ can bind to the required ports without conflicts.

  • JVM heap size configuration: Based on the available system memory, sets the Java Virtual Machine (JVM) heap size to allocate 50% of available memory RAM resources to HiveMQ for optimal operation.

  • HiveMQ Service creation and startup: Sets up HiveMQ to run as a Windows service using the NSSM tool to ensure HiveMQ runs continuously in the background and starts automatically with the system.

The following procedure guides you through all the steps needed to install HiveMQ on Windows Server with a PowerShell Script.

  1. Download the PowerShell script from the HiveMQ support GitHub repository:
    Install-HiveMQ-WindowsServer-Standalone.ps1

  2. Right-click the Windows PowerShell icon and select Run as administrator:

    Run as administrator

  3. Open a terminal window and enter the following command to temporarily set the current PowerShell session execution policy to Bypass:

    Set-ExecutionPolicy Bypass -Scope Process -Force

  4. To install HiveMQ and observe the execution output in the terminal, navigate to the folder where you downloaded the PowerShell script and enter the following command to execute the Install-HiveMQ-WindowsServer-Standalone.ps1 script:

    .\Install-HiveMQ-WindowsServer-Standalone.ps1

    Optionally, you can define -hivemqVersion and -installationFolder parameters directly in the command line to specify a different version of HiveMQ or a different installation folder:

    .\Install-HiveMQ-WindowsServer-Standalone.ps1 -hivemqVersion "4.32.0" -installationFolder "C:\hivemq"

    If HiveMQ is successfully installed, output similar to the following example displays:

    HiveMQ Installation Output Example

  5. To verify access to the HiveMQ Control Center on your Windows machine, open a browser window and navigate to http://localhost:8080.. The default username is admin and the default password is hivemq.

    HiveMQ Control Center Login

  6. To verify that HiveMQ starts as expected upon reboot, restart your Windows machine.

  7. At this point, you can Start and Stop the HiveMQ application with the installed Windows service:

    Start and Stop HiveMQ service
    You can use the following PowerShell cmdlet to display your hivemq.log files in the console: 
    Get-Content C:\hivemq\log\hivemq.log -Wait

Automated Uninstallation of HiveMQ Platform (PowerShell Script)

The following procedure guides you through all the steps needed to uninstall HiveMQ on Windows Server, which was installed using the previous PowerShell installation script.

The HiveMQ PowerShell uninstall script renames the HiveMQ installation directory instead of deleting it. This method allows you to retain your configurations and data for future use.

  1. Download the PowerShell uninstall script from the HiveMQ support GitHub repository: Uninstall-HiveMQ-WindowsServer-Standalone.ps1.

    If you are using the default HiveMQ installation folder, C:\hivemq, you can execute the following commands in the PowerShell console to uninstall HiveMQ.

  2. Open a terminal window and enter the following command to temporarily set the current PowerShell session execution policy to Bypass:

    Set-ExecutionPolicy Bypass -Scope Process -Force

  3. To uninstall HiveMQ and observe the execution output in the terminal, navigate to the folder where you downloaded the PowerShell script and enter the following command to execute the Uninstall-HiveMQ-WindowsServer-Standalone.ps1 script:

    .\Uninstall-HiveMQ-WindowsServer-Standalone.ps1
    If you are not using the default installation folder, C:\hivemq, specify the -installationFolder parameter directly in the command line and set where the HiveMQ installation folder is located in your environment:
    .\Uninstall-HiveMQ-WindowsServer-Standalone.ps1 -installationFolder "F:\hivemq"

    If HiveMQ is successfully uninstalled, output similar to the following example displays:

    HiveMQ Uninstallation Ouput Example

Manual Setup of HiveMQ on Windows Server

Requirements

  • Running Windows environment

  • Minimum HiveMQ system hardware requirements

  • OpenJDK 11 or higher is required. OpenJDK 21 is recommended.

    1. On the HiveMQ Download page of the official HiveMQ website, enter your email address, read and accept the terms of service, and select Download.zip to download the latest version of HiveMQ.

    2. Extract the hivemq-<version>.zip to the C:\ drive.
      For example, C:\hivemq-4.27.0.

    3. Rename the folder so the file path is C:\hivemq.
      For example, files in the folder have the following structure: C:\hivemq\bin.

Set the heap that HiveMQ uses (Windows)

The heap that the HiveMQ process uses can be set as a variable in the run.bat file.

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

To set the heap value, add a line with the desired -Xmx to the VARIABLES configuration as follows:

  1. Go to C:\hivemq\bin

  2. Open the run.bat file with notepad or the text editor of your choice.

  3. In the VARIABLES section of the run.bat file, add the heap configuration.
    The following code example sets the heap size to the recommended 50% of the available RAM:
    set "JAVA_OPTS=%JAVA_OPTS% -XX:+UnlockExperimentalVMOptions -XX:InitialRAMPercentage=40 -XX:MaxRAMPercentage=50 -XX:MinRAMPercentage=30"

  4. Save the file.

Make the same changes to the recovery.bat file.

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

Start HiveMQ Platform manually (Windows)

  1. Go to C:\hivemq\bin

  2. Right-click the run.bat file and run the file as an administrator.

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

Verify that HiveMQ is running

To check whether HiveMQ is listening on the default port for MQTT, 1883, open cmd.exe and run:

netstat -an | findstr "1883"

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.

If no valid HiveMQ license is present, HiveMQ starts in trial mode. HiveMQ trials are for evaluation and testing purposes only. Production usage without a valid production license is strictly prohibited.
Our standard trial supports 25 connections. If your evaluation requires more connections, please contact us.

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.