Mosquitto

Sign in to the AWS Management Console and open the EC2 service. Select Launch instance.

Under Application and OS Images, choose AWS Marketplace AMIs and search for Eclipse Mosquitto. Select the SecureAnyCloud listing, choose Select, then choose Continue on the subscription summary.

Choose an instance type of m5.large or larger. This is a balanced default, so size it to the publish and subscribe load you expect. Choose your EC2 key pair under Key pair (login).

Under Network settings, select your VPC and subnet. Create or select a security group that allows inbound port 22 from your management network and inbound port 1883 from the clients that will connect to the broker. Leave the root volume at the default size or larger.

Select Launch instance. After the instance state becomes Running and the status checks pass, first boot takes only a few seconds. The firstboot service generates the per-instance MQTT password and starts the broker.

Run the following command to launch an instance from the SecureAnyCloud Eclipse Mosquitto Marketplace AMI into an existing subnet and security group. Replace these values:

• <ami-id> with the AMI ID shown on the Marketplace listing
• <key-name> with your EC2 key pair name
• <subnet-id> with your subnet ID
• <security-group-id> with a security group that opens port 22 from your management network and port 1883 from your client networks

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> \
  --block-device-mappings '{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}' \
  --metadata-options 'HttpTokens=required,HttpEndpoint=enabled' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=mosquitto-broker}]'

Connect with SSH as the default login user for the operating system variant you launched. The login user is ubuntu on Ubuntu 24.04.

Replace <key-file> with the path to your private key file and <instance-public-ip> with the public IP address or DNS name of the instance.

ssh -i <key-file> ubuntu@<instance-public-ip>

The first boot service writes the generated MQTT password to /root/mosquitto-credentials.txt. The file is mode 0600 and owned by root, so read it with sudo. It also records the MQTT user name and port for reference.

sudo cat /root/mosquitto-credentials.txt

The MOSQUITTO_PASSWORD line holds the password generated for this instance. Keep it safe. By default, it is the only credential that can connect to the broker.

Check that the broker and the healthcheck shim are running and that the MQTT listener is bound.

systemctl is-active mosquitto.service nginx.service ss -tln | grep -E ':(1883|80) '

Check the installed version of Mosquitto.

dpkg-query -W -f='${Package} ${Version}\n' mosquitto

The HTTP healthcheck shim serves a static OK on port 80. The Marketplace scanner uses this endpoint. To verify it yourself, run:

curl -fsS http://127.0.0.1/

The mosquitto-clients package provides mosquitto_sub for subscribing and mosquitto_pub for publishing. Read the password into a shell variable, then run a subscriber in one terminal and a publisher in another. This confirms the broker is delivering messages.

Subscribe to a topic. This command blocks and waits for messages.

PASS=$(sudo grep '^MOSQUITTO_PASSWORD=' /root/mosquitto-credentials.txt | cut -d= -f2-) mosquitto_sub -h 127.0.0.1 -u sac -P "$PASS" -t 'hello/#' -v

In a second SSH session on the same instance, read the password the same way and publish a message.

PASS=$(sudo grep '^MOSQUITTO_PASSWORD=' /root/mosquitto-credentials.txt | cut -d= -f2-) mosquitto_pub -h 127.0.0.1 -u sac -P "$PASS" -t hello/world -m 'first message from mosquitto'

The subscriber prints hello/world first message from mosquitto. The # wildcard subscribes to every topic under hello/, so messages on any other hello/... topic are delivered too.

If no subscriber is attached when the publisher runs, the message is dropped on delivery (MQTT QoS 0). To retain a message for new subscribers, add -r to the publish command. Mosquitto stores the last retained message on the topic and delivers it immediately to every subsequent subscriber.

To stop the subscriber, press Ctrl+C.

The MQTT listener binds 0.0.0.0:1883, so any host that can reach the instance on port 1883 can connect with the same credentials.

Install the mosquitto-clients package on the remote host (for example, sudo apt-get install -y mosquitto-clients on Ubuntu). Then connect to the instance's public IP address or DNS name.

mosquitto_sub -h <instance-public-ip> -u sac -P '<password>' -t 'hello/#' -v

mosquitto_pub -h <instance-public-ip> -u sac -P '<password>' -t hello/world -m 'message from a remote client'

Make sure your security group allows inbound TCP 1883 from the source network. For production deployments, restrict port 1883 to known client networks, or front the broker with TLS on port 8883 (see Step 9).

The image ships with one MQTT user, SecureAnyCloud. To add another user, run mosquitto_passwd against the broker's password file. Then reload the service so the broker picks up the change.

sudo mosquitto_passwd /etc/mosquitto/passwd <new-username>
sudo systemctl reload mosquitto.service

mosquitto_passwd prompts twice for the new user's password and appends the user to the file. To delete a user, edit /etc/mosquitto/passwd as root, remove the line for that user, and reload the service.

Plain MQTT on port 1883 is the default. For deployments exposed to the internet, add a TLS listener on the standard MQTTS port 8883.

Place a certificate and private key on the instance (for example, under /etc/mosquitto/certs/). Then create a drop-in configuration file and reload the broker.

sudo install -d -o root -g mosquitto -m 0750 /etc/mosquitto/certs
# Copy your certificate, private key and CA bundle into /etc/mosquitto/certs/
# fullchain.pem (certificate + intermediates)
# privkey.pem (private key, mode 0640 root:mosquitto)
# ca.pem (your CA chain, optional for client cert auth)
sudo tee /etc/mosquitto/conf.d/tls.conf >/dev/null <<'CONF' listener 8883 0.0.0.0 certfile /etc/mosquitto/certs/fullchain.pem keyfile /etc/mosquitto/certs/privkey.pem
# Uncomment to require client certificates:
# cafile /etc/mosquitto/certs/ca.pem
# require_certificate true CONF
sudo systemctl reload mosquitto.service

Open inbound TCP 8883 on the security group from your client networks. Then connect with the mqtts:// or --cafile form of your MQTT client.

Mosquitto persists retained messages, queued messages for offline subscribers, and subscription state under /var/lib/mosquitto/. The default /etc/mosquitto/mosquitto.conf sets persistence true and persistence_location /var/lib/mosquitto/. The SecureAnyCloud overlay in /etc/mosquitto/conf.d/sac.conf does not change those values.

For high message rate workloads, review and tune the broker for your deployment. The full list of broker options is documented at https://mosquitto.org/man/mosquitto-conf-5.html.

Place additional configuration in a new file under /etc/mosquitto/conf.d/, then reload the broker.

sudo systemctl reload mosquitto.service

Keep the operating system patched with the standard package manager. The official Mosquitto PPA is already configured on the image, so broker upgrades arrive through the normal package update process.

sudo apt-get update
sudo apt-get -y upgrade

After a Mosquitto package upgrade, restart the broker if the package post-installation step does not do so automatically.

sudo systemctl restart mosquitto.service

To diagnose connection or routing issues, inspect the broker logs with journalctl.

sudo journalctl -u mosquitto.service -n 200 --no-pager