rumqttd MQTT Broker on AWS User Guide

Overview

This guide covers the deployment and configuration of rumqttd using the cloudimg AWS Marketplace image. rumqttd is a lightweight, high performance MQTT broker written in Rust, from the rumqtt project. It implements the MQTT v3.1.1 protocol over plain TCP and is a single self contained static binary with no runtime and no external services, so it is a minimal, fast message backbone for IoT fleets, device telemetry and real time, event driven applications.

The image installs the official rumqttd binary (pinned and checksum verified at build) and runs it under systemd as an unprivileged user, so an MQTT broker is listening within minutes of launch.

Security by design - no baked MQTT password. There is no default MQTT password inside the image. The shipped broker configuration carries only a placeholder. A unique broker username and password are generated on this machine's first boot, rendered into the broker configuration and written to a root only credentials file. No two instances share it and none ships inside the image.

Security by design - authentication required. The broker enforces a username and password on every connection using a constant time credential comparison. Anonymous connections and wrong credential connections are rejected by the broker.

What is included:

• rumqttd (official pinned binary), run under systemd as the unprivileged rumqttd user (rumqttd.service)

• The standard MQTT port 1883 (MQTT/TCP), listening on all interfaces so the broker is reachable inside your VPC

• A per instance MQTT password generated on first boot and never baked into the image

• Anonymous access rejected and wrong credential connections refused, out of the box

• Unattended security upgrades left enabled so the broker keeps receiving patches

Connecting to your instance

Connect over SSH on port 22 using the private key you selected at launch and the login user for your image variant:

Prerequisites

• An AWS account, an EC2 key pair, and a VPC + subnet in the target region

• Subscription to the rumqttd listing on AWS Marketplace

• A security group allowing TCP 22 (admin) and TCP 1883 (MQTT) from the clients that will connect

Recommended instance type: m5.large (2 vCPU, 8 GB RAM) for a small to medium fleet. Busy brokers should use a larger m5 size.

Step 1: Launch from the AWS Marketplace console

Find rumqttd Lightweight MQTT Broker by cloudimg in the AWS Marketplace, click Continue to Subscribe, accept the terms, then Continue to Launch. Choose the m5.large instance type, select your VPC, subnet and key pair, and attach a security group that opens TCP 22 for administration plus TCP 1883 (MQTT) from your client networks. Treat plaintext 1883 as VPC internal only where you can, and front it with TLS or a private subnet for production.

Step 2: Launch from the AWS CLI

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --associate-public-ip-address \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=rumqttd}]'

Open the MQTT and admin ports on the instance's security group (source-restrict them to your client networks in production):

for p in 22 1883; do
  aws ec2 authorize-security-group-ingress --group-id <security-group-id> \
    --protocol tcp --port "$p" --cidr <your-mgmt-cidr>
done

Step 3: First boot

On first boot the image resolves the instance public IP (via the EC2 instance metadata service, IMDSv2), generates a per instance MQTT password, renders it into the broker configuration and a root only credentials file, and starts the broker. This completes within a minute. SSH in as ubuntu and read the per instance details, including the MQTT username and password:

sudo cat /stage/scripts/rumqttd-credentials.log

Step 4: Confirm the broker is running

rumqttd.service is active and the broker listens on 1883 (MQTT/TCP) on all interfaces.

systemctl is-active rumqttd.service
ss -tln | grep ':1883'

Step 5: Prove a full MQTT round trip

Authenticate with the per instance credential and complete a publish and subscribe message round trip on 1883. The commands below read the password from the root only credentials file, subscribe in the background, then publish a message and read it back:

PW="$(sudo grep '^RUMQTTD_PASSWORD=' /stage/scripts/rumqttd-credentials.log | cut -d= -f2-)"
timeout 8 mosquitto_sub -h 127.0.0.1 -p 1883 -u cloudimg -P "$PW" -t 'demo/status' -C 1 &
sleep 1
mosquitto_pub -h 127.0.0.1 -p 1883 -u cloudimg -P "$PW" -t 'demo/status' -m 'online'
wait

Step 6: Confirm the broker is secure by default

Anonymous connections and wrong credential connections are rejected by the broker. Both of the commands below should fail with a non zero exit and a lost connection error, proving no client can reach the broker without the per instance credential:

mosquitto_pub -h 127.0.0.1 -p 1883 -t 'demo/anon' -m 'x'; echo "anonymous exit code: $?"
mosquitto_pub -h 127.0.0.1 -p 1883 -u cloudimg -P 'wrong-password' -t 'demo/anon' -m 'x'; echo "wrong password exit code: $?"

Step 7: Publish and subscribe from a remote MQTT client

Any standard MQTT client can connect with the per instance username (cloudimg) and password. From a remote client, use your instance's address (the RUMQTTD_HOST value in the credentials file), pass the same username and password, and make sure the security group opens TCP 1883.

mosquitto_sub -h <public-ip> -p 1883 -u cloudimg -P '<RUMQTTD_PASSWORD>' -t '#' -v

mosquitto_pub -h <public-ip> -p 1883 -u cloudimg -P '<RUMQTTD_PASSWORD>' -t 'demo/topic' -m 'hello from my app'

Connections that present no credentials, or the wrong password, are refused: anonymous access is rejected on the broker.

Step 8: Manage MQTT users

The broker configuration lives at /etc/rumqttd/rumqttd.toml (readable by the rumqttd group). The per connection credential is defined in the [v4.1.connections.auth] table, where each entry is an MQTT username mapped to its password. To add or change a user, edit that table, then restart the broker:

sudo systemctl restart rumqttd

Keep the configuration file readable only by root and the rumqttd group, and keep the credentials file (/stage/scripts/rumqttd-credentials.log) root only.

Step 9: Security recommendations

• Restrict the security group. Allow TCP 1883 only from the client networks that need to connect, and TCP 22 for administration only.

• Front the broker with TLS. rumqttd listens with plaintext MQTT on 1883. Treat it as internal or VPC only, or terminate TLS in front of it (for example with a reverse proxy or load balancer) for traffic that crosses untrusted networks.

• Keep authentication enabled. The broker requires the per instance username and password on every connection. Add per client credentials as your fleet grows.

• Keep the MQTT password secret. It lives in /stage/scripts/rumqttd-credentials.log (root only) and in the broker configuration, and is unique to this instance. Rotate it by editing the [v4.1.connections.auth] table and restarting rumqttd.

• Keep the OS and rumqttd patched. Unattended security upgrades remain enabled on the running instance.

Step 10: Support and Licensing

rumqttd is developed by the rumqtt project and distributed under the Apache-2.0 license. This cloudimg image bundles the unmodified official rumqttd binary. cloudimg provides the packaging, the secure by default first boot (per instance MQTT password, anonymous access rejected), the systemd integration, and 24/7 support.

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

Need Help?

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