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 download package for the HiveMQ platform contains the following directories:
conf/examples directory of your HiveMQ installation contains several useful example configuration files.
Startup scripts and binary files.
Persistent client data and cluster data.
One or more HiveMQ license files.
All HiveMQ log files.
All extensions to the HiveMQ installation.
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.
The default installation directory for HiveMQ is
/opt/hivemq. The default HiveMQ username is
|Some of the following commands require root privileges, log in as root user or use sudo to execute the commands.
Log in as root user
Go to the directory where you want to download and install HiveMQ. In this example, we use
On the HiveMQ website, select Download HiveMQ ZIP Archive to get a trial version of HiveMQ.
Copy the provided download link and download HiveMQ
wget --content-disposition <your download link>
curl -O -L <your download link>
Extract the files
Create a HiveMQ symbolic link (symlink)
ln -s /opt/hivemq-<version> /opt/hivemq
Create a HiveMQ user
useradd -d /opt/hivemq hivemq
Make scripts executable and change the owner to
chown -R hivemq:hivemq /opt/hivemq-<version> chown -R hivemq:hivemq /opt/hivemq cd /opt/hivemq chmod +x ./bin/run.sh
Adjust the configuration properties to your needs.
For more information, see Configuration.
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
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:
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.
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
CentOS or RHEL
chkconfig hivemq on
The following instructions show how to start HiveMQ after the installation.
Change directory to HiveMQ directory
Execute startup script
Check if HiveMQ is listening to the default port for MQTT
netstat -an | grep 1883
If you run HiveMQ as daemon:
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
Download the latest HiveMQ version from our website
Unpack the hivemq.zip file to C:\hivemq.
Follow these steps to install HiveMQ as a Windows service:
Download the hivemq-windows-service.zip.
Unzip the hivemq-windows-service.zip file.
Copy the windows-service folder to your HiveMQ home folder.
Open the windows-service folder.
Double-click the installService.bat file.
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.
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.
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:
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.
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.
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 licenseTo obtain a HiveMQ license, contact firstname.lastname@example.org.