Setting Up HiveMQ for MQTT Device Brokering

Before you begin

Ensure you have the following:

  • Latest version of HiveMQ server
  • Installed SOTI Connect
  • Installed MQTT Certificates (these are installed during SOTI Connectinstallation)
  • Text editor software (Notepad ++ or similar)
  • Keystore creation tool (Portecle or similar)
  • Java Runtime Environment (JRE) 8+
  • Java SE Development 11+
  • Open JDK11(GA) (https://jdk.java.net/archive/)
Note: SOTI recommends that HiveMQ be installed on a separate machine for optimal performance.

About this task

HiveMQ is an enterprise-ready, publically hosted MQTT broker that acts as a connection tool between your MQTT devices and SOTI Connect. Other than the trial version, there are three versions of HiveMQ that users can download. For more information on HiveMQ, visit https://www.hivemq.com/hivemq/editions/. Contact sales for more information on installing an enterprise solution of HiveMQ.

We recommend using Hive MQ Professional edition for long-term use or using the HiveMQ Community edition if you want to test the broker first.

There are three security options that you leverage for communication between SOTI Connect, HiveMQ, and OEM Devices:

  • Insecure TCP: no security features
  • Server-side TLS: client only validates if server certificate is correct. For SOTI Connect, the certificate signed by the Root CA provided when adding the MQTT PA will be validated.
    Important: The sample procedure documented in this topic demonstrates server-side TLS.
  • TLS with Client Certificates: the server certificate is validated and the client must provide a valid certificate signed by the same authority as the server certificate.

Procedure

  1. Download and install HiveMQ.

    For manual installation, you can download HiveMQ files at https://github.com/hivemq/hivemq-community-edition. Scroll to the Quick Start section of the page and download the binary package:

    Binary package location.

    For installation as a Windows service, you can download HiveMQ files at https://hivemq.com/additional-software/hivemq-windows-service.zip.

  2. Navigate to your SOTI Connect Certificate folder (this can be found in Program Files\SOTI\Connect\MQTT Certificates)
  3. Run Portecle as an Administrator.
    Running Portcele application as an administrator
  4. Click the New Keystore Type button and ensure you select JKS as the Keystore. Click OK.

    Creating a new keystore in PortceleSelecting JKS as the keystore type in Portcele

  5. Click the Import Key Pair button and navigate to the SOTI Connect Certificates folder. Select the file called server-cert.pfx, then click Choose.
    Clicking the Import Key Pair button in PortceleSelecting the server-cert.pfx key pair file
  6. Enter the password for your MQTT certificate. You established this in the SOTI Connect install process, then click OK.

    Entering the key store password in Portcele

  7. Confirm the password and Key Pair.
  8. Enter an Alias for your Key Pair, then click OK.
    Entering a key pair alias in Portcele
  9. Enter a new password for this Key Pair.

    Changing key pair password

  10. Select the Key Pair and select the Keystore password. Write your desired password (this password will be used by the HiveMQ Server).

    Portcele save button

  11. Name the Keystore, then click Save.

    Portcele save as dialog box for Keystore

  12. Navigate to your SOTI Connect MQTT Certificates directory. Find the Keystore file and copy it.

    The Connect MQTT Certificates directory

  13. Navigate to your HiveMQ\conf folder and paste the copied file into the folder.

    The Hive conf directory

  14. Open the config.xml file in the conf directory with Notepad++ or a similar app that allows you to edit the xml. Inside the xml file, you will see the default configuration and the file that only contains the unsecured TCP listener on port 1883.

    Hive config xml showing default configuration

  15. 15. Create a TLS Listener on Port 8883. This will use the Java Keystore you previously created.

    Confix xml file with new TLS Listener defined

    
<tls-tcp-listener>
	<port>8883</port>
	<bind-address>0.0.0.0</bind-address>
	<tls>
		<keystore>
			<path>.conf/HiveMQ_MQTT.jks</path>
			<password>JKS_Password</password>
			<private-key-password>PrivateKey_Password</private-key-password>
		</keystore>
		<truststore>
			<path>.conf/HiveMQ_MQTT.jks</path>
			<password>JKS_Password</password>
		</truststore>
		<client-authentication-mode>NONE</client-authentication-mode>
	</tls>
</tls-tcp-listener>
  16. Ensure that the path is accurate and enter the password for the Java Keystore and the password for the Connect servers’ Private Key. Client authentication mode should be set to None as this is only used for TLS with client. Save the config file.
  17. Navigate to the HiveMQ directory and open the bin sub-directory.

    Hive bin directory location for run.bat file

  18. Run the run.bat file as administrator to start the server.

    Run as administrator right-click Windows menu

    Your HiveMQ server is now connected to your SOTI Connect instance.

    Batch file running to connect HiveMQ and Connect

    See also:

    SOTI Connect Installer

    System Requirements

    Updating SOTI Connect

    Uninstalling SOTI Connect

    Installing the Failover Instance

    Installing and Setting Up SQL Server