HiveMQ Edge General Installation Information

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

OpenJDK JRE 17 or newer is required for production environments. To check the which Java version is currently installed on your system, enter java -version on your command line. For more information, see HiveMQ Edge System Requirements.

The HiveMQ Edge download contains the following directories:

Folder name Description

bin

HiveMQ Edge startup scripts and binary files.

conf

HiveMQ Edge configuration files.

data

Persistent client data and cluster data.

license

One of more HiveMQ license files.

log

All log files can be found here.

extensions

All extensions to the HiveMQ Edge installation.

third-party-licenses

License information for third-party libraries.
HiveMQ Edge provides several example configuration files in the conf/examples directory. Additionally, The HiveMQ University Introduction to HiveMQ Edge provides useful information and step-by-step instructions for installation with Docker on Windows 11.

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 Edge 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/start.sh 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. In this example we use /opt.

  3. Extract the files from the ZIP archive:

    unzip hivemq-edge-latest.zip

  4. Create a HiveMQ symbolic link (symlink):

    ln -s /opt/hivemq-edge-<version> /opt/hivemq

  5. Create a HiveMQ user:

    useradd -d /opt/hivemq hivemq

  6. 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/run.sh

  7. Adjust the configuration properties to your needs.
    For detailed information and configuration examples, see HiveMQ Edge Configuration.

  8. 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

  9. 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:

    HIVEMQ_HOME=/opt/hivemq

    HIVEMQ_USER=hivemq

    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.

  10. 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:

    ./bin/run.sh

Start HiveMQ Edge as daemon

  1. Start the daemon:

    /etc/init.d/hivemq start

Verify that HiveMQ Edge is running

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

    netstat -an | grep 1883

  2. 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 hivemq-windows-service.zip file.

  2. Unzip the hivemq-windows-service.zip 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"

Installation with Helm

We provide a Helm chart for easy installation and management in a Kubernetes environment.

Prerequisites

You will need the following things to follow through with the docs:

To get you quickly started locally we provide a KIND tutorial which includes everything for running locally.

Getting started

The first step is to add the HiveMQ Helm char repository to your local Helm setup.

Enter the following shell command to add our repository and pull the metadata of our available charts:

helm repo add hivemq https://hivemq.github.io/helm-charts && helm repo update

Next, create a file called values.yaml with the following content:

admin:
  password: secret (1)
1 set the UI password to secret.

To install and start HiveMQ Edge in your Kubernetes cluster, enter:

helm install edge hivemq/hivemq-edge -f values.yaml

This Helm command creates a StatefulSet and an associated Service. The service contains the list of ports you can now export through an Ingress or LoadBalancer.

Check the service to see the available ports using the following command:

kubectl describe service hivemq-edge-edge
Not all Kubernetes Ingress support TCP/MQTT and can require a LoadBalancer or additional configuration to forward TCP traffic. See the documentation of your Ingress Controller for further details.

To verify that everything is up and running, check the created Pod:

kubectl get pod hivemq-edge-0

The result of the command should look something like this:

NAME            READY   STATUS    RESTARTS   AGE
hivemq-edge-0   1/1     Running   0          1m

Adding protocol adapters

Adding Protocol Adapters to HiveMQ Edge running outside of Kubernetes works via the UI and them being directly written into the broker configuration.

This clashes with how GitOps is supposed to work where every bit of configuration has to come from a git-repository.

Protocol adapters are configured using XML. For more information, see Protocol Adapter Configuration.

Create the configuration for your protocol adapter in XML and put it into a file called config.xml.

As quick start use the following XML-snipped in config.xml to create a simulation adapter:

<protocol-adapters>
  <protocol-adapter>
      <adapterId>simulation</adapterId>
      <protocolId>simulation</protocolId>
      <config>
          <simulationToMqtt>
              <pollingIntervalMillis>100</pollingIntervalMillis>
              <maxPollingErrorsBeforeRemoval>-1</maxPollingErrorsBeforeRemoval>
          </simulationToMqtt>
      </config>
      <northboundMappings>
          <northboundMapping>
              <topic>test</topic>
              <tagName>t2</tagName>
              <mqttUserProperties>
                  <mqttUserProperty>
                      <name>simulation</name>
                      <value>2</value>
                  </mqttUserProperty>
              </mqttUserProperties>
          </northboundMapping>
      </northboundMappings>
  </protocol-adapter>
</protocol-adapters>

Next, enter the following command:

helm upgrade edge hivemq/hivemq-edge -f values.yaml --set-file config=config.xml

The --set-file config=config.xml command puts the content of config.xml in the key configuration into values.yaml.

This is the default way to provide content such as the XML configuration, keystores, or other non-YAML content to the templates without breaking them.

To view the logs your container produces, use: kubectl logs -f hivemq-edge-0.

After a few seconds, look for the following line:

Protocol-adapter 'test' started successfully.

MQTT Bridge Configuration

HiveMQ Edge also supports the creation of MQTT bridges. For more information, see MQTT Bridges.

MQTT bridge configuration is XML-based and goes into the same file as your protocol adapters.

The following config.xml extends the previous protocol adapter example with an added bridge:

Example HiveMQ Edge MQTT bridge configuration:
<protocol-adapters>
  <protocol-adapter>
      <adapterId>simulation</adapterId>
      <protocolId>simulation</protocolId>
      <config>
          <simulationToMqtt>
              <pollingIntervalMillis>100</pollingIntervalMillis>
              <maxPollingErrorsBeforeRemoval>-1</maxPollingErrorsBeforeRemoval>
          </simulationToMqtt>
      </config>
      <northboundMappings>
          <northboundMapping>
              <topic>test</topic>
              <tagName>t2</tagName>
              <mqttUserProperties>
                  <mqttUserProperty>
                      <name>simulation</name>
                      <value>2</value>
                  </mqttUserProperty>
              </mqttUserProperties>
          </northboundMapping>
      </northboundMappings>
  </protocol-adapter>
</protocol-adapters>
<mqtt-bridges>
    <mqtt-bridge>
        <id>my-hivemq-cloud-bridge</id>
        <remote-broker>
            <host>your.broker.host</host>
            <port>1883</port>
        </remote-broker>
        <forwarded-topics>
            <forwarded-topic>
                <filters>
                    <mqtt-topic-filter>mytopic/#</mqtt-topic-filter>
                </filters>
            </forwarded-topic>
        </forwarded-topics>
        <remote-subscriptions>
            <remote-subscription>
                <filters>
                    <mqtt-topic-filter>myothertopic/#</mqtt-topic-filter>
                </filters>
            </remote-subscription>
        </remote-subscriptions>
    </mqtt-bridge>
</mqtt-bridges>

Enable TLS over MQTT

The use of TLS-protected MQTT connections requires the following steps:

First, create a JKS keystore for the required certificate. In this example, we assume the name of the file is keystore.jks.

To facilitate testing, we use a small skript to quickly generate a keystore with a self-signed certificate. The keystore and the private key have the same password changeit. The result of this script is for local testing only. Do not use the script for production purposes.
The keystore must be base64-encoded before it can be stored in Kubernetes.

Files, especially binary ones, must be base64 encoded to be stored inside Kubernetes without causing issues. The following examples produce base64 files with no newline characters to ensure that.

There are slight differences between operating systems. The following examples show commands for macOS and Linux:

On maxOS/BSD, enter:

base64 -i keystore.jks | tr -d '\n' >  keystore.jks_b64

On Linux, enter:

base64 -i keystore.jks -o keystore.jks_b64 -w 0

Once it is created, the encoded keystore must be provided to Helm.

We do not recommend storing the required properties in your values.yaml:

  • Putting the keystore in the values.yaml significantly increases the size of the values file.

  • Storing secrets directly in the values.yaml file poses a security risk.

Instead, we recommend the use of Helm --set/--set-file functions.

First, activate MQTTS and deactivate MQTT in your values.yaml file:

mqtt:
  enabled: false
mqtts:
  enabled: true
  create:
    enabled: true

To allow secrets to be pulled from an environment variable filled via a GitHub secet or other secret manager, enter:

helm upgrade edge hivemq/hivemq-edge -f values.yaml --set-file config=config.xml --set-file mqtts.create.file=keystore.jks_b64 --set mqtts.create.keystorePassword=${KEYSTORE_PASSWORD} --set mqtts.create.privateKeyPassword=${PRIVATEKEY_PASSWORD}

This command updates the service and makes the MQTTS port 8883 available and reachable.

Enable TLS over MQTT with a Secret Manager

The HiveMQ Edge Helm chart also supports secrets provided via a Kubernetes-integrated secret manager. For more information, see External Secrets.

In that case the secret won’t be created by Helm but it has to be referenced.

To do so we have an additional set of options for the values file:

mqtt:
  enabled: false
mqtts:
  enabled: true
  keystore:
    passwordSecretName: hivemq-keystore-secret (1)
    passwordSecretKey: keystore-password (2)
    privateKeyPasswordSecretName: hivemq-keystore-secret (3)
    privateKeyPasswordSecretKey: secret-key-password (4)
    keystoreSecretName: hivemq-keystore-secret (5)
    keystoreSecretKey: keystore.jks (6)
1 The name of the secret that contains the keystore password
2 The key inside the secret that contains the password for the keystore
3 The name of the secret that contains the password for the private key in the keystore
4 The key inside the secret which contains the password for the private key
5 The name of the secret that contains the base64 encoded keystore
6 The key inside the secret that contains the keystore

This configuration makes it possible to reference secrets in the same namespace as the HiveMQ Edge deployment.

Enable MQTTS client authentication

Mutual TLS allows HiveMQ Edge to only allow clients that present a trusted certificate to connect. This process is called client authentication.

To activate client authentication, you need a working MQTTS configuration and the addition of a truststore.

The truststore contains the certificates to be trusted by HiveMQ Edge. Just like the keystore this file is expected to be in JKS format and base64 encoded.

The following example adds a few options to the MQTTS section of your values file:

mqtts:
  enabled: true
mqttsClientauth:
  clientAuthenticationMode: REQUIRED
  create:
    enabled: true

Use the --set-file/--set function in the following command:

helm upgrade edge hivemq/hivemq-edge -f values.yaml --set-file mqttsClientauth.create.file=truststore.jks_base64.xml --set mqttsClientauth.create.truststorePassword=${TRUSTSTORE_PASSWORD}

Afterward, you can only connect to MQTTS via port 8883 with a client that presents a trusted certificate.

Change the admin user password

The admin user and password can also be changed via the configuration.

In your values.yaml use the following content to change the admin username to be chef with the password secret:

admin:
  user: chef (1)
  password: secret (2)
1 set the UI admin user to chef.
2 set the admin user password to secret.

As with all other secret based options they can also be provided using a Kubernetes-Secret;

admin:
  secret:
    enabled: true (1)
    secretName: "admin-secret" (2)
    secretUserKey: "adminy" (3)
    secretPasswordKey: "passwordy" (4)
1 activate using a separate secret not maintained by the helm chart
2 HiveMQ Edge will look for a secret named admin-secret in its namespace
3 In the secret the content of the key adminy will be used for the username
4 In the secret the content of the key passwordy will be used for the password
Currently the admin user settings are not applied automatically and require a pod restart to take effect.

Activate commercial features

HiveMQ Edge offers commercial features that can be unlocked via a license. To learn more about what features are included in the commercial version and how to get a license, see the HiveMQ Edge Landing Page.

After you receive your license, add the following properties to your values.yaml file:

license:
  enabled: true

To apply the license, enter:

helm upgrade edge hivemq/hivemq-edge -f values.yaml --set-file license.file=license.edgelic

The license is put into a secret-object and used by HiveMQ Edge automatically.

When using an external secret manager the secret will be managed outside of the hivemq-edge-chart.

To reference an external secret containg the license add the following entries:

  license:
    enabled: true
    secret:
      secretName: "hivemq-license-secret"
      secretKey: "license.edgelic"

Configuration of the security contexts

The pod security context is an important security feature of Kubernetes which allows changing the user and group used to run the process inside the containers which are part of a Pod.

Edge supports all featurs of the the podSecurity context using the following entries in your values.yaml:

podSecurityContext:
  runAsUser: 1000
  runAsGroup: 3000
  supplementalGroups: [ 4000 ]

we also support the container security context:

containerSecurityContext:
  allowPrivilegeEscalation: false

Configuration Changes

The container reacts to configuration changes by restarting.

Tear down

When you are done testing, you can run the following command to clean up:

helm uninstall edge

Local Testing with Kind

A Kind (Kubernetes IN Docker) cluster is a lightweight Kubernetes cluster that runs inside Docker containers instead of virtual machines. For quick local testing, Kind offers a convenient way to run Kubernets in your local container environment.

We also recommend to install Cloud Provider KIND that adds a load balancer to Kind and makes it easier to work with the exposed services.

The following commands create a Kind cluster with a running HiveMQ Edge instance:

kind create cluster
kubectl cluster-info --context kind-kind
helm repo add hivemq https://hivemq.github.io/helm-charts && helm repo update
helm install edge hivemq/hivemq-edge

Create an lb.yaml file with the following content:

kind: Service
apiVersion: v1
metadata:
  name: hivemq-edge-lb
spec:
  type: LoadBalancer
  selector:
    app.kubernetes.io/name: "hivemq-edge"
    app.kubernetes.io/instance: "edge"
  ports:
  - port: 5678
    targetPort: 8080
    name: http
  - port: 5679
    targetPort: 1883
    name: mqtt
  - port: 5680
    targetPort: 8883
    name: mqtts

To apply the newly created lb.yaml file, enter:

kubectl apply -f lb.yaml

Now, start the LoadBalancer:

sudo cloud-provider-kind

After the LoadBalancer starts, enter the following command to get the local IP address on which the LoadBalancer is bound:

kubectl get svc/hivemq-edge-lb -o=jsonpath='{.status.loadBalancer.ingress[0].ip}'

You can now use the returned IP address and the ports provided in the lb.yaml file to access your installation locally.