General installation information (HiveMQ 3.4)

This documentation is for the HiveMQ 3.4 legacy version. For up-to-date information on the current version of HiveMQ, please switch to the latest version of our HiveMQ Platform documentation and update your bookmarks as needed.

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:

Folder name Description

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.
`license`	The folder where the HiveMQ License file(s) resides.
`log`	All log files can be found here.
`plugins`	The folder where plugins reside.
`third-party-licenses`	Information about the licenses of third party libraries can be found here.

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.

license

The folder where the HiveMQ License file(s) resides.

log

All log files can be found here.

plugins

The folder where plugins reside.

third-party-licenses

Information about the licenses of third party libraries can be found here.

Example configurations

HiveMQ comes with many example configuration files in the conf/examples directory.

Installation on Unix based systems (Linux, BSD, MacOS X, Unix)

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

Download HiveMQ from the official HiveMQ website.

wget https://www.hivemq.com/releases/hivemq-3.4.7.zip

Log in to your system as root user.
Move the downloaded ZIP file to the directory where you want to install HiveMQ.
In this example, we use /opt.
```
mv hivemq-3.4.7.zip /opt
cd /opt
```
Extract the files from the ZIP archive:
```
unzip hivemq-3.4.7.zip
```
Create a HiveMQ symbolic link (symlink):
```
ln -s /opt/hivemq-3.4.7 /opt/hivemq
```
Create HiveMQ user
```
useradd -d /opt/hivemq hivemq
```

Make scripts executable and change the owner to hivemq user:

chown -R hivemq:hivemq /opt/hivemq-3.4.7
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.

If you just want to try HiveMQ you can skip this part now and proceed with Starting 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 linux systems using systemd and java 9

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

For Debian 8 systems using systemd

wget "https://www.hivemq.com/releases/tools/debian8_systemd.zip"
unzip debian8_systemd.zip
cp hivemq.service /opt/hivemq/bin/init-script/hivemq.service
cp stop_gracefully.sh /opt/hivemq/bin/init-script/stop_gracefully.sh
chmod +x /opt/hivemq/bin/init-script/stop_gracefully.sh
cp /opt/hivemq/bin/init-script/hivemq.service /etc/systemd/system/hivemq.service
rm debian8_systemd.zip
rm hivemq.service
rm stop_gracefully.sh

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:

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.
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
```
insserv hivemq
```
CentOS or RHEL
```
chkconfig hivemq on
```

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 (Linux, macOS, Unix)

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

Starting manually

Change directory to HiveMQ directory
```
cd /opt/hivemq
```
Execute startup script
```
./bin/run.sh
```

Starting as daemon

Start the daemon
```
/etc/init.d/hivemq start
```

Verify if HiveMQ is running

Check if HiveMQ is listening to the default port for MQTT

netstat -an | grep 1883

If you’re running HiveMQ as daemon:

/etc/init.d/hivemq status

Windows systems

Installation

Manual installation

Download HiveMQ from the official HiveMQ website.
Extract the hivemq-3.4.7.zip file to C:\hivemq using your favorite Zip unpack utility.

Installation as Windows Service

Download HiveMQ from the official HiveMQ website.
Extract the hivemq-3.4.7.zip to the C:\ drive.
For example, C:\hivemq-3.4.7.
Rename the folder so the file path is C:\hivemq.
For example, files in the folder have the following structure: C:\hivemq\bin.
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.
Reboot

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.

Starting HiveMQ

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.

Verify if HiveMQ is running

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

Open cmd.exe and run:

netstat -an | find "1883"

Installing a HiveMQ license

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.

Multiple license files

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 license

If you want to obtain a HiveMQ license, please contact sales@hivemq.com.