aws-mqtt-broker

Overview

Local MQTT broker

In order to relay messages to the AWS IoT endpoint, a MQTT broker has to be set up. However, it seems that Home Assistant doesn't fully support ActiveMQ nor RabbitMQ, so the safer (and recommended by HA) alternative would be using eclipse-mosquitto which is an open source message broker that implements MQTT on its versions 3.1, 3.1.1 and 5.0.

More info:

• Project page
• Github repo

Bridge config

• connection <connection_name> will help identify the bridge in case there are more than one, both in Cloudwatch and the local mosquitto logs.
• aws_iot_data_endpoint is the AWS IoT MQTT endpoint our local bridge will connect to. Should be of the following shape <random_prefix>-ats.iot.<aws_region>.amazonaws.com. Can be retrieved through Terraform outputs.
• client_id is just a unique identifier for each client connected to the broker.
• bridge_(ca|cert|key)file are the SSL/TLS certificates used to connect to AWS IoT. The setup requires 3 files. An Amazon public Root CA certificate, and the IoT Certificate (and Private Key) created with Terraform.

# ============================================================
# Bridge to AWS IOT
# ============================================================

connection <connection_name>

address <aws_iot_data_endpoint>:8883

<list_of_topics_to_bridge>

bridge_protocol_version mqttv311
bridge_insecure false

cleansession true
clientid <client_id>
start_type automatic
notifications false
log_type all

# ============================================================
# Certificate based SSL/TLS support
# ============================================================

bridge_cafile <root_ca_certificate_file>
bridge_certfile <aws_iot_created_certificate_file>
bridge_keyfile <aws_iot_created_certificate_private_key_file>

#END of bridge.conf

Terraform stack

Requirements

Name	Version
terraform	~> 1.3
aws	~> 4.0

Providers

Name	Version
aws	4.53.0
http	3.2.1

Resources

Name	Type
aws_dynamodb_table.iot_topic_data	resource
aws_iam_role.iot_logging	resource
aws_iam_role.iot_push_to_dynamo	resource
aws_iot_certificate.cert	resource
aws_iot_logging_options.logging_config	resource
aws_iot_policy.pubsub	resource
aws_iot_policy_attachment.policy_attachment	resource
aws_iot_thing.home_assistant	resource
aws_iot_topic_rule.push_to_dynamo	resource
aws_caller_identity.current	data source
aws_iam_policy_document.assume_role_policydoc	data source
aws_iam_policy_document.iot_thing	data source
aws_iam_policy_document.logging_role_policydoc	data source
aws_iam_policy_document.push_to_dynamo_policydoc	data source
aws_iot_endpoint.endpoint	data source
http_http.aws_iot_root_ca_cert	data source

Inputs

Name	Description	Type	Default	Required
aws_iot_ca_cert_url	URL for the AWS IoT Root CA Certificate	string	"https://www.amazontrust.com/repository/AmazonRootCA1.pem"	no
aws_region	n/a	string	"eu-west-1"	no
iot_loglevel	n/a	string	"WARN"	no
iot_thing_name	n/a	any	n/a	yes
iot_topic_name	Name of the topic (allows wildcards) for the query that gets data into DynamoDB	string	n/a	yes

Outputs

Name	Description
aws_iot_root_ca_certificate	n/a
iot_certificate	n/a
iot_endpoint	n/a

Tips

Check connection against AWS IoT endpoint

mosquitto_pub -h "${IOT_HOST}" -p 8883 \
  --key /mosquitto/certs/private.key \
  --cert /mosquitto/certs/cert.crt \
  --cafile /mosquitto/ca_certificates/rootCA.pem \
  -t "${IOT_TOPIC}" -m '{"hello" : "test"}' -i myclientid -d

Get IoT and Root CA certificates from Terraform

Use terraform output -raw <output_key> or terraform output -json to retrieve individual keys from the Terraform outputs.

Example:

# get the AWS IoT CA Root certificate
terraform output -raw aws_iot_root_ca_certificate

# get the PEM certificate
terraform output -json iot_certificate | jq -r '.cert'

# get the public key
terraform output -json iot_certificate | jq -r '.public_key'

# get the private key
terraform output -json iot_certificate | jq -r '.private_key'

Check the available outputs here.

Validate certificates

openssl s_client -connect custom_endpoint.iot.aws-region.amazonaws.com:8443 \
  -CAfile CA.pem \
  -cert cert.pem \
  -key privateKey.pem

Create mosquitto password file

mosquitto_passwd -c <password_file> <username>