How to set up Eclipse Mosquitto MQTT Broker and connect a client

In this How-to we will cover the first steps in connecting a client to your Mosquitto broker.

What you need

An installation of the Mosquitto Broker on your ctrlX CORE
A valid license
The MQTT Explorer

For a quick introduction to Mosquitto click here.

First steps

After your installation, Mosquitto is available over your Navigation Menu on the left side of your Browser. Click it and open the “Management Center”.

The Management Center (MMC) allows managing Mosquitto via a Browser UI.
Gather real time information of your broker and set up the dynamic security. If you are used to working with a terminal, there is one embedded in the MMC.

To get started with a connection, you first need to create a client. Use the left side navigation and click on “Clients”. As you can see, there are no existing clients. Create one and click “Save”.

Clients need permissions to operate. These are administered via “Roles”. Without any assigned role, a client is not able to perform any action on Mosquitto. There are a couple of prebuild roles, which you can choose from, or you can create your own.

For now, choose the role “client”, which allows full publish and subscribe capabilities. Now, we are already set to connect to Mosquitto.

Open the MQTT Explorer, use the IP of your CORE and the port 8883 to connect.
Choose TLS on and uncheck the “Validate certificate” option.
Don´t forget to use the username and password from the client you just created.

When the connection is established, you can now send data to a topic and see it arrive in your MMC topic tree. Use the right side of the MQTT Explorer to set a topic and a payload to be send. After sending it, you are able to see it in the topic tree of your MMC.

Alternative Configuration

Custom server certificates

If you just wish to use your own server certificates without changing any other
configuration, you can upload certificates to the Mosquitto Certificate Store on the ctrlX.
When uploading the server certificate, the file must be named mosquitto.pem and
uploaded to the Own category. The server certificate must contain the full chain of
certificates up to the CA certificate.

Likewise, the server key must be named mosquitto.key and uploaded to the Own
category.
After the server certificate and key are uploaded, restart Mosquitto by selecting Disable
then Enable from the Apps Settings page.

Client Certificates

If you just wish to require your clients to connect using certificates without changing any
other configuration, you can upload a certificate named client-ca.pem to the Mosquitto
Certificate Store in the CA category, then restart Mosquitto by selecting Disable then
Enable from the Apps Settings page. To use client certificates, you must also use custom
server certificates.
When client certificates are enabled, the clients must still authenticate using a
username/password and can be assigned roles with the Management Center.

Custom Configuration

If you wish to use your own Mosquitto configuration file on the ctrlX, you can add a
configuration file named mosquitto.conf to the conf.d directory in the Mosquitto section of
the App Data page on the ctrlX.
This configuration file follows the format described at the mosquitto.conf manual page.

The exceptions to this are:
• The use of the include_dir option is not possible.
• The per_listener_settings option is always set to true.
• Setting persistence to true is strongly discouraged to save flash lifetime.

The default configuration:

per_listener_settings true
persistence false
user root

listener 1884 127.0.0.1
allow_anonymous true

# Listener using in-snap certificates
listener 8883
certfile /snap/ctrlx-mosquitto/current/tls/bosch.pem
keyfile /snap/ctrlx-mosquitto/current/tls/bosch.key
plugin /snap/ctrlx-mosquitto/current/usr/lib/mosquitto_dynamic_security.so
plugin_opt_config_file /var/snap/ctrlx-mosquitto/common/solutions/activeConfiguration/mosquitto/dynamic-security.json
set_tcp_nodelay true

The Company

Cedalo AG is an IoT start-up based in Freiburg, Germany, that is truly devoted to Open Source. Our products constitute of Eclipse Foundation projects. Eclipse Streamsheets, the first product, is a no-code application platform which can easily subscribe and publish to data streams like MQTT or Apache Kafka. Business process users can build stream processing applications using a spreadsheet GUI and cell functions. A variety of diagram types provides fast dashboarding. Eclipse Mosquitto, the second product, is the most downloaded MQTT broker worldwide. Brokers orchestrate the data flow in modern IoT publish/subscribe architectures. Mosquitto excels in big installs on servers due to a high efficiency to handle a large number of parallel connections. However, its resource-friendly programming makes it ideal for usage on small ARM-based edge devices like the Raspberry Pi, as well.