General installation information
This guide explains the default installation, if you want to try and evaluate HiveMQ without installation you can follow the Getting Started Guide instead.
HiveMQ comes as a zip file which contains the executables, init scripts and sample configurations.
The zip contains the following directories:
The folder with start scripts and binary files.
The folder with the configurations.
Persistent client data and cluster data are located here.
The folder where the HiveMQ License file(s) resides.
All log files can be found here.
The folder where extensions reside.
Information about the licenses of third party libraries can be found here.
Example configurationsHiveMQ comes with many example configuration files in the
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
Login as root
Some of the following commands need root privileges, please login as root or use sudo to execute the commands.
Change directory to where you want to download and install HiveMQ. By default we prefer
Get your evaluation version from our website.
Copy the provided download link and download HiveMQ
wget --content-disposition <your download link>
curl -O -L <your download link>
Extract the files
Create hivemq symlink
ln -s /opt/hivemq-<version> /opt/hivemq
Create HiveMQ user
useradd -d /opt/hivemq hivemq
Make scripts executable and change 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.
See chapter Configuration for detailed instructions how to configure HiveMQ.
Install the init script (optional)
For Debian-based linux like Debian, Ubuntu, Raspbian using init.d scripts
cp /opt/hivemq/bin/init-script/hivemq-debian /etc/init.d/hivemq chmod +x /etc/init.d/hivemq
For linux systems using systemd
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 variable to the correct values for your system.
By default this would be:
If you installed HiveMQ to a different directory than
/opt/hivemqplease point the HIVEMQ_HOME in your init script to the correct directory. Otherwise the daemon will not start correctly.
Start HiveMQ on boot (optional)
For Debian-based linux like Debian, Ubuntu, Raspbian
update-rc.d hivemq defaults
For Debian-based linux like Debian, Ubuntu, Raspbian using 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’re running 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
Extract the file hivemq.zip to C:\hivemq using your favorite Zip unpack utility.
The steps to install HiveMQ as a Windows Service are:
Download the hivemq-windows-service.zip file from here
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.
|Make sure you have the permission to install a service. Therefore it might be necessary to right click the installService.bat and select Run as administrator.|
The following instructions show how to start HiveMQ after installing:
Double click on the run.bat file.
|Please 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" is displayed, the HiveMQ start up is interrupted and needs to be continued via a click of the right mouse button. A click after the HiveMQ start up has no impact on 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:
############## 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 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.|
Installing a HiveMQ license is as simple as moving the
hivemq.lic file provided with your purchases into the
license folder of your HiveMQ installation.
Licenses can be added during run time and will be automatically and dynamically recognized by HiveMQ.
When a valid license file is found, HiveMQ logs a statement similar to the following:
2018-08-20 20:49:44,322 INFO - Found valid site license (hivemq.lic) issued to XXX for max XXX connections, valid until XXX.
A newly obtained license can be added during runtime. When multiple valid license files are recognized by HiveMQ, the license allowing the higher number of concurrent connections will automatically be selected.
In case multiple valid licenses for the same amount of concurrent connections are found HiveMQ will select the license that has a longer validity.
A restart of HiveMQ is not necessary for switching or adding licenses during runtime.
Obtaining a HiveMQ licenseIf you want to obtain a HiveMQ license, please contact firstname.lastname@example.org.