Mosquitto: Configuring Mosquitto to connect to another server (bridge)

This documentation is part of the Bridges guide. You can view the complete guide here: How to connect Mosquitto servers together (bridge).

👋 Welcome to the Stackhero documentation!

Stackhero provides you with a fully managed Mosquitto MQTT cloud environment, designed for reliability and flexibility:

• Unlimited message throughput and data transfers, so your workflows never encounter artificial limits.
• Unlimited device authentication via your own external API, making onboarding and access management straightforward.
• Advanced ACLs for precise control over topics, users, and actions.
• A custom domain name with integrated HTTPS for secure, branded endpoints (for example: https://mqtt.your-company.com).
• Effortless updates: apply improvements or security patches with a single click.
• Consistent performance and enhanced security, with every instance running on a private, dedicated infrastructure.

Accelerate your IoT projects and reduce operational overhead. You can have a secure, production-ready Mosquitto MQTT cloud hosting instance up and running in just a few minutes.

In this example, a remote server will connect to a Stackhero instance using a dedicated user with TLS encryption for maximum security.

First, create a new user on the Stackhero MQTT instance. Let us call it bridge-1, with the password secretPassword.

Next, on the remote Mosquitto server, you can edit the mosquitto.conf configuration file (usually located at /etc/mosquitto/mosquitto.conf) by adding the following lines at the end:

# TODO: replace "<XXXXXX>.stackhero-network.com" and "<PORT_TLS>" with your Stackhero instance information
connection <XXXXXX>.stackhero-network.com
address <XXXXXX>.stackhero-network.com:<PORT_TLS>

# TODO: replace "bridge-1" and "secretPassword" with the newly created user's credentials
remote_clientid bridge-1
remote_username bridge-1
remote_password secretPassword

start_type automatic
try_private true

# Topics to share, direction, and QOS.
# Note that "both" seems to not work for an unknown reason.
topic # out 2
topic # in 2

# Enable TLS connection to encrypt data between your remote Mosquitto server and your Stackhero instance.
bridge_insecure false
bridge_capath /etc/ssl/certs

Before restarting Mosquitto with its new configuration, ensure that TLS certificates exist on your remote server.

Check that the /etc/ssl/certs directory exists and contains files with the command:

ls /etc/ssl/certs

If it exists and contains files, you can simply restart your Mosquitto server.

If it does not exist, you might consider executing one of these commands:

• On Ubuntu/Debian, you can run:

  sudo apt-get install ca-certificates
  

• On Alpine Linux, you might run:

  apk add ca-certificates
  

Alternatively, you can manually download the certificate. To do this, download the CA certificate to /etc/mosquitto/isrgrootx1.pem using the following command:

wget https://letsencrypt.org/certs/isrgrootx1.pem -O /etc/mosquitto/isrgrootx1.pem

Then, edit the mosquitto.conf file to replace bridge_capath /etc/ssl/certs with bridge_cafile /etc/mosquitto/isrgrootx1.pem.

Finally, restart your Mosquitto server.

For more information on bridge configuration, you can refer to the official Mosquitto documentation.