HiveMQ Community Edition on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of HiveMQ Community Edition on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. HiveMQ Community Edition is an open source, production grade single node MQTT broker. It implements the full MQTT 3.1, 3.1.1 and 5.0 specifications and provides reliable publish and subscribe messaging with quality of service delivery guarantees, making it a common backbone for IoT telemetry, device command and control, and event driven communication between applications and services.

The image installs HiveMQ Community Edition 2026.5 from the official release, run under systemd as an unprivileged hivemq user on the Java 21 runtime. HiveMQ answers MQTT on port 1883 on all interfaces. It is a headless broker: there is no web interface (the HiveMQ Control Center is part of the commercial Enterprise edition), so you operate it with any standard MQTT client such as mosquitto_pub and mosquitto_sub, which ship in the image.

Secure by default — authentication required, no default credentials. HiveMQ Community Edition by itself ships with no authentication, which means an out of the box broker accepts anonymous connections. This image closes that gap: it bundles the official HiveMQ File RBAC Authentication Extension, and on the very first boot of every VM it generates a unique MQTT admin password, stores it as a salted PBKDF2 hash in the extension's credentials file, and records the login in /root/hivemq-credentials.txt (mode 0600, root only). As a result an anonymous or wrong credential connection is rejected, and no two instances share a credential.

What is included:

• HiveMQ Community Edition 2026.5 from the official release, run under systemd as the unprivileged hivemq user (hivemq.service) on OpenJDK 21

• An MQTT endpoint on 0.0.0.0:1883 supporting MQTT 3.1, 3.1.1 and 5.0 clients

• The HiveMQ File RBAC Authentication Extension, configured with password-type HASHED so passwords are stored as salted PBKDF2 hashes, never in plain text

• A single admin MQTT user, cimgadmin, with a per instance password generated on first boot and documented in /root/hivemq-credentials.txt (0600)

• mosquitto-clients (mosquitto_pub / mosquitto_sub) preinstalled so you can publish and subscribe from the broker VM immediately

Prerequisites

• Active Azure subscription, SSH public key, VNet + subnet in target region

• Subscription to the HiveMQ Community Edition listing on Azure Marketplace

• Network Security Group rules allowing TCP 22 (admin) and TCP 1883 (MQTT) from the client networks and devices that will connect to the broker

Recommended virtual machine size: Standard_B2s (2 vCPU, 4 GB RAM) is ample for development and small production workloads; the broker runs with a 1500 MB JVM heap on this size. Scale to a larger size for high connection counts or message throughput.

Step 1: Deploy from the Azure Portal

Search HiveMQ Community Edition in Marketplace, select the cloudimg publisher, and click Create. Configure the Network Security Group to allow TCP 1883 (MQTT) from the device and application networks that will connect, and TCP 22 for administration. Keep 1883 restricted to your own client subnets rather than the whole internet.

Step 2: Deploy from the Azure CLI

RG="mqtt-prod"; LOCATION="eastus"; VM_NAME="hivemq1"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/hivemq-ce-ubuntu-24-04/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 1883 --priority 1001
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1002

Step 3: First boot

On first boot the image generates a unique MQTT admin password, hashes it with the File RBAC extension, renders the extension credentials file, and starts hivemq. This completes within a minute or two while the JVM warms up. SSH in as azureuser and read the details:

sudo cat /root/hivemq-credentials.txt

The file records the admin username (cimgadmin), the generated password, and the MQTT URI for this VM. Store the password somewhere safe: it is unique to this instance and is the only credential that can connect to the broker.

Step 4: Confirm the service is running

hivemq.service is active, the runtime is OpenJDK 21, and ss confirms the broker is listening on :1883 on all interfaces.

systemctl is-active hivemq.service
java -version
ss -tlnp | grep ':1883 '

Step 5: Publish and subscribe with the per instance credential

Read the admin password from the credentials file into a shell variable, publish a retained message, and subscribe to receive it. Both the publish and the subscribe present the cimgadmin username and the per instance password; the broker delivers the message end to end.

PW=$(sudo grep '^HIVEMQ_ADMIN_PASSWORD=' /root/hivemq-credentials.txt | cut -d= -f2-)
mosquitto_pub -h 127.0.0.1 -p 1883 -u cimgadmin -P "$PW" -t demo/hello -m 'hello from cloudimg' -q 1 -r
mosquitto_sub -h 127.0.0.1 -p 1883 -u cimgadmin -P "$PW" -t 'demo/#' -v -C 1 -W 8

The subscriber prints demo/hello hello from cloudimg and exits, confirming an authenticated publish and subscribe round trip.

Step 6: Confirm anonymous and wrong credentials are rejected

The File RBAC extension enforces authentication. A connection with no credentials, or with a wrong password, is refused by the broker, so each command below exits non zero and prints the confirmation. The exact client message (Connection Refused: bad user name or password for anonymous, Connection Refused: not authorised for a wrong password) is shown in the screenshot.

mosquitto_pub -h 127.0.0.1 -p 1883 -t demo/x -m nope 2>/dev/null && echo 'UNEXPECTED: anonymous accepted' || echo 'anonymous connect refused by the broker (expected)'
mosquitto_pub -h 127.0.0.1 -p 1883 -u cimgadmin -P wrong-password -t demo/x -m nope 2>/dev/null && echo 'UNEXPECTED: wrong password accepted' || echo 'wrong password refused by the broker (expected)'

Step 7: Review the secure by default configuration

No default or shared credentials ship in the image. The credentials file is 0600 root:root, the admin password is unique to this VM, and the File RBAC extension stores the password as a salted PBKDF2 hash (password-type HASHED), never in plain text.

sudo stat -c '%n %a %U:%G' /root/hivemq-credentials.txt
sudo grep -E '<password-type>' /opt/hivemq/current/extensions/hivemq-file-rbac-extension/conf/config.xml
sudo grep -c '<password>' /opt/hivemq/current/extensions/hivemq-file-rbac-extension/conf/credentials.xml

Step 8: Add your own MQTT users and topic permissions

You manage users and their topic permissions in the File RBAC credentials file, /opt/hivemq/current/extensions/hivemq-file-rbac-extension/conf/credentials.xml. Passwords are stored as salted PBKDF2 hashes; generate a hash for a new user's password with the extension's own generator (the -q flag prints only the hash string). This example uses <new-password> as a placeholder for a real password you choose.

sudo java -jar /opt/hivemq/current/extensions/hivemq-file-rbac-extension/hivemq-file-rbac-extension-4.6.15.jar -p '<new-password>' -q

Add a <user> entry (referencing a <role> you define) to the <users> section of credentials.xml, pasting the hash above into <password>. The role's <permission> blocks scope what topics the user may publish or subscribe to. The following role grants publish and subscribe only under a per device prefix:

<user>
    <name>device01</name>
    <password>PASTE_THE_HASH_HERE</password>
    <roles>
        <id>device</id>
    </roles>
</user>
<!-- add this role under the <roles> section -->
<role>
    <id>device</id>
    <permissions>
        <permission>
            <topic>devices/device01/#</topic>
            <activity>ALL</activity>
        </permission>
    </permissions>
</role>

The File RBAC extension reloads credentials.xml automatically within 60 seconds, so changes take effect without restarting the broker. For production, create a narrowly scoped role per device or application rather than reusing the superuser admin.

Step 9: Connect an application or IoT device

Any standard MQTT client can connect using the broker IP, port 1883, and the username and password from the credentials file. The values below map directly onto /root/hivemq-credentials.txt. This example uses the Eclipse Paho Python client; the same host, port, username and password apply to any MQTT 3.1.1 or 5.0 library.

import paho.mqtt.client as mqtt

client = mqtt.Client(protocol=mqtt.MQTTv5)
client.username_pw_set("cimgadmin", "the-password-from-the-credentials-file")
client.connect("<hivemq-vm-ip>", 1883)
client.publish("telemetry/sensor1", payload="23.4", qos=1)
client.loop_forever()

For production, create a dedicated per application MQTT user (Step 8) rather than reusing the admin account.

Step 10: Enable TLS on port 8883 (optional hardening)

By default the image serves plain MQTT on port 1883, which is appropriate inside a trusted VNet. To carry credentials and payloads over the public internet, add an encrypted tls-tcp-listener on the standard MQTTS port 8883 in /opt/hivemq/current/conf/config.xml, referencing a Java keystore that contains a certificate for your server's hostname. Restart the broker after editing the config, and open TCP 8883 in the NSG. Keeping TLS optional lets you run plain MQTT for local development while adding MQTTS for exposed deployments.

Step 11: Security recommendations

• Restrict the NSG. Allow TCP 1883 only from the device and application subnets that connect to the broker, and TCP 22 for administration only. Do not expose the MQTT port to the public internet without TLS.

• Use TLS for untrusted networks. Add an 8883 tls-tcp-listener (Step 10) for any traffic that leaves a trusted VNet, so credentials and payloads are encrypted in transit.

• Use scoped per client users. Create a narrowly scoped File RBAC role and user per device or application (Step 8) rather than reusing the superuser admin, so a compromised client cannot read or write every topic.

• Protect the credentials. /root/hivemq-credentials.txt is 0600 root:root and credentials.xml stores only salted PBKDF2 hashes. Keep both root owned and back up your credentials.xml, which is the source of truth for who may connect.

• Keep the OS patched. Unattended security upgrades remain enabled on the running VM.

Step 12: Support and Licensing

HiveMQ Community Edition is an open source project distributed under the Apache License 2.0. This cloudimg image bundles the unmodified official HiveMQ Community Edition release and the official HiveMQ File RBAC Authentication Extension. cloudimg provides the packaging, the systemd hardening, the File RBAC secure by default configuration, the per instance credential automation, the paired deploy guide, and 24/7 support with a guaranteed 24 hour response SLA.

cloudimg is not affiliated with or endorsed by HiveMQ GmbH. HiveMQ is a mark of its respective owner and is used here only to identify the software.

Deploy on Azure

Find HiveMQ Community Edition on Ubuntu 24.04 LTS on the Azure Marketplace, published by cloudimg. Deploy from the Portal or the Azure CLI as shown above.

Need Help?

Email support@cloudimg.co.uk for deployment help, configuration questions, or licensing enquiries.