HiveMQ CE

Search the Azure Marketplace for HiveMQ Community Edition, select the SecureAnyCloud publisher, and select Create.

Configure the Network Security Group to allow TCP 1883 (MQTT) from the device and application networks that connect, and TCP 22 for administration. Restrict 1883 to your own client subnets rather than the whole internet.

RG="mqtt-prod"; LOCATION="eastus"; VM_NAME="hivemq1" IMAGE_URN="sac1647283583153:hivemq-ce-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:hivemq-ce-ubuntu-24-04:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --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

On first boot, the image generates a unique MQTT admin password and hashes it with the File RBAC extension. It then 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.

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

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

Read the admin password from the credentials file into a shell variable. Publish a retained message, then 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 sac' -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 SecureAnyCloud and exits. This confirms an authenticated publish and subscribe round trip.

The File RBAC extension enforces authentication. The broker refuses a connection with no credentials or with a wrong password. Each command below therefore exits with a non-zero status and prints the confirmation.

The screenshot shows the exact client messages: Connection Refused: bad user name or password for anonymous, and Connection Refused: not authorised for a wrong password.

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)'

No default or shared credentials ship in the image. The credentials file is 0600 root:root, and the admin password is unique to this VM. 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

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. In this example, replace <new-password> with 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. Paste the hash above into <password>.

The role's <permission> blocks scope which 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.

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.

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. Reference a Java keystore that contains a certificate for your server's hostname. Restart the broker after you edit the config, and open TCP 8883 in the NSG.

Keeping TLS optional lets you run plain MQTT for local development and add MQTTS for exposed deployments.

• 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 that 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. A compromised client then 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. 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.

HiveMQ Community Edition is an open-source project distributed under the Apache License 2.0. This SecureAnyCloud image bundles the unmodified official HiveMQ Community Edition release and the official HiveMQ File RBAC Authentication Extension.

SecureAnyCloud provides the packaging, the systemd hardening, the secure-by-default File RBAC configuration, the per-instance credential automation, the paired deploy guide, and 24/7 support with a guaranteed 24-hour response SLA.

SecureAnyCloud 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 SecureAnyCloud. Deploy from the Portal or the Azure CLI as shown above.

Need Help?

Email sales@secureanycloud.com for deployment help, configuration questions or licensing enquiries.

Deploy on Azure

Launch HiveMQ Community Edition 2026.5 on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Subscribe to the SecureAnyCloud HiveMQ Community Edition listing and launch an instance. Pick m5.large and choose your VPC and subnet. Attach a security group that allows inbound TCP 22 and 1883 from your trusted CIDR.

ssh ubuntu@<public-ip>

Confirm that the broker is running and that the MQTT listener is bound.

sudo systemctl is-active hivemq

active

sudo ss -tlnp | grep 1883 | awk '{print $1, $4}'

LISTEN 0.0.0.0:1883

The extension is what makes this broker closed rather than open. Confirm that it is installed and set to accept only hashed passwords.

ls /opt/hivemq/current/extensions/hivemq-file-rbac-extension/

LICENSE conf hivemq-extension.xml hivemq-file-rbac-extension-4.6.15.jar

sudo cat /opt/hivemq/current/extensions/hivemq-file-rbac-extension/conf/config.xml

First boot generated this instance's broker password. Read the credentials file:

sudo cat /root/hivemq-credentials.txt

Note HIVEMQ_ADMIN_USER (cimgadmin) and HIVEMQ_ADMIN_PASSWORD. These values are unique to this instance. Only the PBKDF2 hash is stored on disk, in the extension's user file.

Read the password into a shell variable rather than typing it, so that it never lands in your shell history. Then publish a retained message and read it back.

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

hello from sac

The -r flag retained the message on the broker. The subscriber therefore receives it immediately on connect rather than waiting for the next publish.

This is the check worth doing yourself. The broker must refuse both an anonymous connection and a connection with a wrong password.

Each check is written as an assertion. It succeeds when the connection is refused, and it fails loudly if the broker ever accepts the connection.

if mosquitto_pub -h 127.0.0.1 -p 1883 -t sac/demo -m anon 2>/dev/null; then echo "UNEXPECTED: anonymous connect was ACCEPTED - the broker is open"; exit 1 else echo "anonymous connect refused (exit $?) - correct" fi

anonymous connect refused (exit 4) - correct

if mosquitto_pub -h 127.0.0.1 -p 1883 -u cimgadmin -P wrong-pw -t sac/demo -m bad 2>/dev/null; then echo "UNEXPECTED: wrong password was ACCEPTED"; exit 1 else echo "wrong password refused (exit $?) - correct" fi

wrong password refused (exit 5) - correct

Run either command without the if wrapper to see the broker's own refusal on stderr. Those messages correspond to the exit codes:

Connection error: Connection Refused: bad user name or password.
# anonymous, exit 4 Connection error: Connection Refused: not authorised.
# wrong password, exit 5

If either assertion ever reports UNEXPECTED, the access control extension is not loading. Check journalctl -u hivemq.

From outside the instance, point your MQTT clients at <public-ip>:1883 with username cimgadmin and the generated password. Any MQTT 3.1, 3.1.1 or 5.0 client works: mosquitto_pub/mosquitto_sub, Eclipse Paho in Python, Java or JavaScript, or the MQTT client built into most IoT SDKs.

The broker supports quality of service 1 and 2 for at-least-once and exactly-once delivery. Retained messages give new subscribers the current value immediately. Last will and testament lets you detect ungraceful client disconnects.

The extension reads a user file that first boot created with a single account. To add more users, generate a hash with the extension's own generator and add an entry. Then reload.

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

Add the printed hash as a new <user> block in the extension's conf/credentials.xml. The extension re-reads that file on its own reload interval, so no restart is needed.

Give each application its own account rather than sharing cimgadmin.

Before exposing the broker beyond a trusted network:

• Add a TLS listener. Port 1883 is plaintext. MQTT credentials are sent in the CONNECT packet, so they are exposed on an untrusted network. Add a tls-tcp-listener on 8883 in /opt/hivemq/current/conf/config.xml with your certificate and key, then close 1883 in the security group.
• Restrict the security group. Limit 22 and 1883 (or 8883) to your device and administrator CIDRs rather than the world.
• One account per application. Add per-client users as in Step 9 and retire the shared cimgadmin account for production traffic.
• Watch the logs. journalctl -u hivemq and /opt/hivemq/current/log/ show connection, authentication and extension activity.
• Back up the configuration. /opt/hivemq/current/conf/ and the extension's conf/ hold the listener configuration and the user file. Snapshot the volume or copy them on a schedule.
• Keep it patched. Unattended upgrades is enabled for OS packages. Review the HiveMQ release notes before replacing the broker under /opt/hivemq.