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

Install HiveMQ Edge as a Service on Window OS

To run HiveMQ Edge as a Windows service, we offer an alternative Windows service installation method using the NSSM tool.

We recommend installing HiveMQ Edge in the C:\hivemq directory. The following procedure assume this directory is used.

# HiveMQ Edge installation folder
$installationFolder = "C:\hivemq"
If you extract HiveMQ Edge to a different directory on your Windows OS, you must update the $installationFolder variable in the PowerShell script accordingly.

Install HiveMQ Edge as a Windows Service

  1. Download and install the HiveMQEdge-WindowsService.ps1 PowerShell Script from the HiveMQ support examples on GitHub.

  2. Open Windows PowerShell and select Run as administrator:

    Run as Administrator

  3. Enter the following command to temporarily set the execution policy of the current PowerShell session to Bypass:

    Set-ExecutionPolicy Bypass -Scope Process -Force

  4. To install the HiveMQ Edge service, navigate to the folder where you downloaded the PowerShell script, enter the following command to execute the Install-HiveMQEdge-WindowsService.ps1 script:

    .\Install-HiveMQEdge-WindowsService.ps1

    When the HiveMQ Edge Windows service installs successfully, output similar to the following example displays:

    Powershell Administration Window

  5. To confirm that HiveMQ Edge is up and running, check that the service is installed and shows a status of Running:

    Windows Service Status

  6. Next, open http://localhost:8080 in your browser and verify you can access the HiveMQ Edge administrative console. The default username is admin and the default password is hivemq:

    Edge Service Login

  7. To complete the installation, restart your machine.
    Upon reboot, HiveMQ Edge starts automatically.

Uninstall HiveMQ Edge Windows Service

To remove the HiveMQ Edge service, execute the following commands in a command prompt or PowerShell window:

C:\hivemq\windows-service\nssm.exe stop HiveMQEdgeService

and

C:\hivemq\windows-service\nssm.exe remove HiveMQEdgeService confirm

Uninstall Windows Service

Install HiveMQ Edge on Kubernetes with Helm

We provide the HiveMQ Edge Helm chart to simplify installation and management of your HiveMQ Edge deployments in a Kubernetes environment.

Prerequisites

  • Running Kubernetes cluster version 1.23.x or higher

  • The Kubernetes command line tool kubectl

  • Helm version 3.10.x or higher installed locally on your machine

To help you get started quickly, we also offer a KIND tutorial that shows you how to run HiveMQ Edge locally.

Getting Started with the HiveMQ Helm Charts

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

  1. To add the HiveMQ Helm chart repository and pull the metadata of our available charts, enter the following shell command:

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

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

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

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

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

Handling of configuration fragments

There are two big parts of the HiveMQ Edge configuration:

  • Core broker functionality (e.g., MQTT listeners, persistence, …​)

  • Dynamic functionality layered on top of the broker (e.g., protocol adapters, bridges, …​)

Changes to the first group - core broker functionality - require a container restart. These are foundational settings, such as listener configurations or persistence options, that cannot be modified at runtime.

The second group, by contrast, operates on top of the core functionality and can be managed much more flexibly. This flexibility enables hot reloading, allowing changes to be applied directly within the running containers and eliminating the need for time-consuming restarts.

When a configuration change is detected, HiveMQ Edge evaluates whether the change can be hot reloaded or if it necessitates a container restart.

All hot-reloadable configurations are defined in config.xml, which represents a subset of the overall HiveMQ configuration. Specific XML fragments can be added to this file, and HiveMQ Edge will apply the changes without restarting the container.

The following fragments are currently supported:

Description XML behavior

MQTT Bridges

 
<mqtt-bridges>
    <mqtt-bridge>
    </mqtt-bridge>
</mqtt-bridges>

May cause a short interruption

Protocol Adapters (including tags,northbound and southbound)

 
<protocol-adapters>
    <protocol-adapter>
    </protocol-adapter>
</protocol-adapters>

May cause a short interruption

Protocol Adapters

 
<data-combiners>
    <data-combiner>
    </data-combiner>
</data-combiners>

Changes are instant

UNS ISA 95

 
<uns>
    <isa95>
    </isa95>
</uns>

Changes are instant

On top of that HiveMQ Edge can also hot reload the initialization of DataHub. Updating the file via Helm will cause DataHub to reapply the configuration.

Reloading the DataHub configuration will cause a brief interruption in the processing of DataHub policies and transformations. While MQTT message delivery itself is not affected, any edge processing, such as calculations or validations, required for further consumption may be skipped during this period.

Adding Protocol Adapters

When running HiveMQ Edge outside of Kubernetes, you can add protocol adapters via the UI or by directly modifying the broker configuration.

However, this approach conflicts with GitOps principles, which require all configurations to be managed through a Git repository.

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

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

For a quick start, add the following XML snipped to your 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, enter: `

kubectl logs -f hivemq-edge-0`.

In a few moments, look for the following output:

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.

Configuration of the security contexts

The pod security context is a crucial security feature in Kubernetes that allows you to define user and group settings for processes running inside the containers of a Pod.

HiveMQ Edge supports all features of the podSecurityContext, which can be configured in your values.yaml file as follows:```

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

This configuration ensures: * The container runs as user ID 1000. * The primary group for the container is set to 3000. * The container also belongs to the supplemental group 4000. ==== Container Security Context HiveMQ Edge also supports the container security context, allowing you to define security settings at the container level. For example, you can prevent privilege escalation using the following configuration:

containerSecurityContext:
  allowPrivilegeEscalation: false

Service Account Configuration

In some cases, it may be necessary to connect the HiveMQ Edge Pod to an existing Kubernetes service account (e.g. for accessing persistent volumes or interacting with other Kubernetes resources).

To specify a service account, add the serviceAccountName property in your values.yaml file:

serviceAccountName: myServiceAccountName

With the entry above the pod will use myServiceAccountName as a service account.

Commercial Features

HiveMQ Edge includes a set of commercial features, which can be enabled and configured using the Helm chart.

The following sections provide details on how to enable and customize these features.

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"

Enabling Persistence

Persistence in HiveMQ Edge is essential for:

  • Durable messaging: Ensuring that messages are not lost during container restarts.

  • Stateful transformations in DataHub: Allowing DataHub to retain its state across restarts.

Stateful transformations in DataHub: Allowing DataHub to retain its state across restarts.

Configuration Example:

modules:
  persistence:
    enabled: true (1)
    storageClassName: "local-storage" (2)
    size: 2Gi (3)
1 Activate persistence
2 Define the storage class to be used (check your volume manager how these are named in your case)
3 Specify the amount of storage to request
If a service account is required for persistence, refer to the Service Account Configuration section above.

Enabling DataHub functionality

DataHub requires persistence to also be enabled.

To activate DataHub, simply add the following entry to your values.yaml file:

modules:
  dataHub:
    enabled: true

Providing a DataHub Initialization File

To fully configure DataHub, you must provide an initialization file (i.e. dh.json). Pass this file to the Helm CLI using: --set-file modules.dataHub.init=dh.json.

For details on the contents of the DataHub initialization file and how DataHub operates, refer to the DataHub on Edge documentation.

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.