HiveMQ Edge General Installation Information

HiveMQ Edge is available for download in a ZIP archive that includes executables files, init scripts, and sample configurations.

The HiveMQ Edge download contains the following directories:

Folder name Description


HiveMQ Edge startup scripts and binary files.


HiveMQ Edge configuration files.


Persistent client data and cluster data.


One of more HiveMQ license files.


All log files can be found here.


All extensions to the HiveMQ Edge installation.


License information for third-party libraries.

Example configurations
HiveMQ Edge comes several example configuration files in the conf/examples directory.

HiveMQ Edge Installation on Unix-based systems (Linux, BSD, MacOS, Unix)

The default installation directory for HiveMQ Edge is /opt/hivemq. The default user to run HiveMQ Edge is named hivemq.

If you need to install HiveMQ to a custom directory or run it under a custom user, you must update the $HIVEMQ_DIRECTORY and/or the HIVEMQ_USER in the $HIVEMQ_DIRECTORY/bin/ script.
  1. Download HiveMQ Edge from the official HiveMQ website.

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

  2. Move the downloaded ZIP file to the directory where you want to install HiveMQ Edge and extract the file with the following command. In this procedure we use the recommended directory /opt.

  3. Check out the HiveMQ Edge GitHub repository and build the binary package:

    git clone
    cd hivemq-edge
    ./gradlew :hivemqEdgeZip
  4. Go to the folder containing the zip file

    cd build/distributions/
  5. Extract the files:

  6. Create a HiveMQ symbolic link (symlink):

    ln -s /opt/hivemq-edge-<version> /opt/hivemq
  7. Create a HiveMQ user:

    useradd -d /opt/hivemq hivemq
  8. Make scripts executable and change owner to hivemq user:

    chown -R hivemq:hivemq /opt/hivemq-edge-<version>
    chown -R hivemq:hivemq /opt/hivemq
    cd /opt/hivemq
    chmod +x ./bin/
  9. Adjust the configuration properties to your needs.
    For detailed information and configuration examples, see HiveMQ Edge 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:



    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 distributions such as Debian, Ubuntu, or Raspbian:

    update-rc.d hivemq defaults

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

    systemctl enable hivemq

    Debian > 6.0

    insserv hivemq

    CentOS or RHEL

    chkconfig hivemq on

Start HiveMQ Edge

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

Start HiveMQ Edge manually

  1. Change to the HiveMQ directory:

    cd /opt/hivemq
  2. Execute the startup script:


Start HiveMQ Edge as daemon

  1. Start the daemon:

    /etc/init.d/hivemq start

Verify that HiveMQ Edge is running

Check if HiveMQ Edge is listening to the default port for MQTT:

netstat -an | grep 1883

If you run HiveMQ Edge as daemon:

/etc/init.d/hivemq status

Open Web UI

Once you start a HiveMQ Edge instance, you can access the HiveMQ Edge administrative console in your browser at http://localhost:8080. The default username is admin and the default password is hivemq.

HiveMQ Edge Installation on Windows Systems

HiveMQ Edge Manual Installation on Windows

  1. Download HiveMQ Edge from the official HiveMQ website.

  2. Use your preferred utility to extract the hivemq-edge-<version>.zip file to C:\hivemq .

HiveMQ Edge Installation as Windows Service

The steps to install HiveMQ Edge as a Windows Service are:

  1. Download the file.

  2. Unzip the 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. Reboot

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.

HiveMQ Edge Startup

The following instructions show how to start HiveMQ Edge after installation:

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 HiveMQ in xxx ms displays, the HiveMQ startup is interrupted and needs to be continued via a click of the right mouse button. Clicks after the HiveMQ startup finishes have no impact on the execution of HiveMQ.

Check whether HiveMQ Edge is running

To verify that HiveMQ Edge is listening to the default port for MQTT, open the cmd.exe file and enter the following command:

netstat -an | find "1883"