Episode 18: Setup custom MQTT broker for Linux

kl3m3n

The following tutorial shows how to setup Mosquitto broker on Linux based devices.

Prerequisites:

OpenSSL software library (should be preinstalled by default on all Linux distributions)
Access to your router (via IP address using the administrator username and password)
External (static) IP provided by your internet service provider (ISP)
GUI-O application version 1.0.47 or higher

IMPORTANT NOTE #1: It is necessary to ask your ISP for static IP configuration. The certificate in the following steps will be issued for a specific IP. If you do not use static IP configuration, your ISP can change the IP address without notice and the connection to the MQTT broker will not work.

IMPORTANT NOTE #2: It is generally recommended that a host name is used instead of IP address, but this requires registering the host name with a domain name registrar and setting up some additional settings.

Step 1: Install Mosquitto broker

Open the terminal and install Mosquitto broker:

sudo apt install mosquitto

Step 2: Determine your external IP address

Enter the following command:

curl ifconfig.me; echo

This will output your external IP, which is needed when issuing the server certificate. You can alternatively navigate to: https://whatismyipaddress.com/.

Step 3: Create self-signed certificate for certificate authority (CA)

Create a private key and CA certificate:

openssl req -new -x509 -days 365 -extensions v3_ca -keyout ca.key -out ca.crt

IMPORTANT NOTE: The "ca.key" file should be kept secure and not shared with anyone.

The "days" value is in this case set to 365 (1 year) and denotes the certificate validity. This value can be changed based on your requirements. After the command is executed, you will be prompted to enter a pass phrase and additional certificate information such as country code, state name, city, etc.

(Optionally) check the certificate info:

openssl x509 -noout -text -in ca.crt

Step 4: Create a server certificate and sign it with CA

Create "server.cnf" file (you can alternatively download the file here) :

nano server.cnf

Add the following content and replace the "[dn]" and "[alt_names]" sections with your information (use the external IP address obtained in Step 2):

[req]

default_bits = 2048

prompt = no

default_md = sha256

distinguished_name = dn

req_extensions = req_ext


[dn]

C = COUNTRY_CODE_HERE

ST = STATE_HERE

L = CITY_HERE

O = ORGANIZATION_HERE

OU = ORGANIZATION_UNIT_HERE

CN = IP_ADDRESS_HERE


[req_ext]

subjectAltName = @alt_names


[alt_names]

IP.1 = IP_ADDRESS_HERE

NOTE: To save and exit "nano" text editor, press "Ctrl+x", then "y" and "Enter" key.

Create a private key:

openssl genrsa -out server.key 2048

Create certificate signing request:

openssl req -new -key server.key -out server.csr -config server.cnf

Create self-signed certificate using the signing request

openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -sha256

The "days" value is in this case set to 365 (1 year) and denotes the certificate validity. This value can be changed based on your requirements. After the command is executed, you will be prompted to enter the pass phrase for "ca.key" (this is the pass phrase that was set in Step 3).

Change the permissions for "server.key" file:

sudo chmod a+r server.key

Step 5: Copy the certificate to your Android device

Copy the "ca.crt" to your Android device (e.g., Documents folder), where GUI-O application is installed. You can send the certificate via email, transfer it via USB cable, etc.

Step 6: Move the files to proper locations

Move the "ca.key" and "ca.crt" file to "/etc/mosquitto/ca_certificates" folder:

sudo mv ca.crt ca.key /etc/mosquitto/ca_certificates/

Move the "server.key" and "server.crt" file to "/etc/mosquitto/certs" folder:

sudo mv server.crt server.key /etc/mosquitto/certs/

Step 7: Setup broker configuration

Create "default.conf" file in "/etc/mosquitto/conf.d" (you can alternatively download the file here) :

sudo nano /etc/mosquitto/conf.d/default.conf

Add the following content:

# Listener

listener 8883

cafile /etc/mosquitto/ca_certificates/ca.crt

certfile /etc/mosquitto/certs/server.crt

keyfile /etc/mosquitto/certs/server.key

require_certificate false

use_identity_as_username false


# TLS

tls_version tlsv1.2


# Security

allow_anonymous false

password_file /etc/mosquitto/passwd


# Logging

#log_type error

#log_type warning

log_type all

NOTE: To save and exit "nano" text editor, press "Ctrl+x", then "y" and "Enter" key.

Create user name and password for authentication when connecting to the broker (replace the "USER" and "PASS" with your user name and password - both will be required by the GUI-O application when connecting to the broker):

sudo mosquitto_passwd -b /etc/mosquitto/passwd USER PASS

NOTE: You can add more users with different credentials using this command.

Restart the Mosquitto service:

sudo systemctl restart mosquitto.service

(Optionally) check the status of the Mosquitto service:

sudo systemctl status mosquitto.service

Step 8: Configure port forwarding rules for your router

Determine the MAC (hardware) address of your device, where the Mosquitto broker is running:

ifconfig

This command will output the MAC address after the "ether" keyword (formatted as xx:xx:xx:xx:xx:xx).

Open your browser and enter the router IP address into the address bar (the router IP is usually printed on the back of the router). Enter router user name and password when prompted.
Set a local static IP based on the MAC address of the device. Note that the procedure for setting a local static IP varies depending on the make and model of your router.
Setup port forwarding by using the local static IP and setting the internal port range from 8883 to 8883 (this is the port that the Mosquitto service is listening on). Set the external port range to any valid value based on your preferences (e.g., from 43519 to 43519). Use TCP protocol and save the settings, making sure that the newly added port forwarding rule is enabled.
Reboot the router.
Restart the device, where the Mosquitto broker is running. After the restart, the device should have obtained the local static IP (you can check this by running the "ifconfig" command).

Step 9: Setup GUI-O application and connect to Mosquitto broker

Open GUI-O application on your Android device and navigate to "Settings -> Connections IoT -> IoT Settings".
Tap on "Server name" and set the value to your external IP, which was determined in Step 2.
Tap on "SSL port number" and set the value to your external port number, which was set in Step 8 (e.g., 43519).
Tap on "User name" and set the user name for authentication, which was created in Step 7.
Tap on "User password" and set the password for authentication, which was created in Step 7.
Tap on "Import certificate" and select the "ca.crt", which was transferred to the device in Step 5.
Return to the previous menu and tap "Connect". If everything was setup correctly, the connection to the Mosquitto broker should be established successfully.

(Optional) Step 10: Setup ESP32 and connect to Mosquitto broker

Download BasicMQTT_Mosquitto.ino sketch and open it in Arduino IDE.
Get the "ca.crt" data in plain text format. Open the terminal on the device where the Mosquitto broker is running and run the following command:

cat /etc/mosquitto/ca_certificates/ca.crt

Copy the certificate displayed in the terminal and replace the one in BasicMQTT_Mosquitto.ino source code (keep same certificate formatting).

Finally, refer to ESP32 MQTT video example, while using the BasicMQTT_Mosquitto.ino sketch. Make sure that the external IP (mqttIP), external port number (mqttPort), user name (mqttUser) and password (mqttPass) variables are set according to Step 9.

NOTE: Do not forget to generate and set the publish and subscribe topics!

If you have any questions or run into any problems, please let me know!

Best regards,
kl3m3n