Skip to content

Getting started

This page takes you from the AWS Marketplace listing to your first MQTT message: subscribe, launch, connect, then publish and receive on the broker.

You need: an AWS account with permission to subscribe to AWS Marketplace products, launch EC2 instances and use AWS Systems Manager.

1. Subscribe

Open the Mosquitto listing in AWS Marketplace, choose View purchase options, review the terms and subscribe. When the subscription is confirmed, choose Launch your software.

2. Launch the instance

On the EC2 launch page:

  1. Keep the instance type at t3.medium.
  2. Under Configure storage, use an encrypted gp3 root volume of at least 16 GiB.
  3. Under Network settings, allow no inbound traffic. If you also want SSH, allow port 22 from your administrative address range only.
  4. Under Advanced details, choose an IAM instance profile that includes the AWS managed policy AmazonSSMManagedInstanceCore, so you can connect with Session Manager.
  5. Choose Launch instance.

3. Connect

In the EC2 console, select the instance, choose Connect, then Session Manager, then Connect. Switch to the ubuntu user:

sudo -iu ubuntu

4. Wait for first boot

On first boot the instance creates its TLS certificates, users and ACL, then starts Mosquitto:

cloud-init status --wait
systemctl is-active sushi-mosquitto-firstboot mosquitto

5. Run the walkthrough

bash /opt/sushi/docs/demo.sh

6. Publish and receive a message

The helper runs mosquitto_pub or mosquitto_sub as one of the example users and reads that user's password for you. In one session, wait for one message for up to 20 seconds:

sudo /opt/sushi/bin/mosquitto-as.sh subscriber sub \
  -t sushi/pilot/sensor -q 1 -C 1 -W 20

Within those 20 seconds, publish from a second session:

sudo /opt/sushi/bin/mosquitto-as.sh publisher pub \
  -t sushi/pilot/sensor -q 1 -m 'temp=21.5'

The subscriber prints temp=21.5. The helper accepts topics under sushi/ only, and stops each command after 25 seconds.

Connect your application

Setting Value
URL mqtts://127.0.0.1:8883
CA certificate /usr/local/share/sushi/mosquitto/ca.pem
User publisher or subscriber, or a user you add
Password the contents of /etc/mosquitto/credentials/<user>.password (root only)

Keep passwords out of tickets, chat and screen recordings.

From your workstation, through Session Manager

The broker listens only on the instance. To reach it from your own machine without opening a port, forward it with Session Manager. You need the AWS CLI and the Session Manager plugin installed locally:

aws ssm start-session --target <instance-id> \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["8883"],"localPortNumber":["8883"]}'

While the session is open, clients on your machine connect to mqtts://127.0.0.1:8883. Copy the public CA certificate from /usr/local/share/sushi/mosquitto/ca.pem on the instance to your machine and point your client at it. The certificate is valid for 127.0.0.1, so host name verification passes.

To serve devices or applications elsewhere in your VPC, see Reach Mosquitto from your VPC.