Episode 19: Setup custom MQTT broker for Windows

[kl3m3n]

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

Prerequisites

• OpenSSL software library:

Download light version here and install. Install OpenSSL directly to the main partition (e.g., "C:\OpenSSL-Win64"). When prompted copy DLLs to OpenSSL binaries directory.

• 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: Download and install Mosquitto broker

1. Download Mosquitto broker here and perform full installation directly to the main partition (e.g., "C:\mosquitto")

Step 2: Determine your external IP address

1. Open the command prompt (cmd) and enter the following command:

curl ifconfig.me

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)

1. Navigate to Mosquitto folder:

cd C:\mosquitto

2. Create a new folder:

mkdir certs

3. Navigate to newly created folder

cd certs

4. Create a private key and CA certificate:

C:\OpenSSL-Win64\bin\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.

5. (Optionally) check the certificate info:

C:\OpenSSL-Win64\bin\openssl x509 -noout -text -in ca.crt

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

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

cd. > 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

2. Create a private key:

C:\OpenSSL-Win64\bin\openssl genrsa -out server.key 2048

3. Create certificate signing request:

C:\OpenSSL-Win64\bin\openssl req -new -key server.key -out server.csr -config server.cnf

4. Create self-signed certificate using the signing request

C:\OpenSSL-Win64\bin\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).

Step 5: Copy the certificate to your Android device

1. 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: Setup broker configuration

1. Use any text editor to open "mosquitto.conf" file located under "C:\mosquitto" (you can alternatively download the file here) :

Find the "Listeners" section and set:

listener 8883

Find the "Certificate based SSL/TLS support" section and set:

cafile C:\mosquitto\certs\ca.crt

certfile C:\mosquitto\certs\server.crt

keyfile C:\mosquitto\certs\server.key

require_certificate false

use_identity_as_username false

tls_version tlsv1.2

Find the "Security" section and set:

allow_anonymous false

password_file C:\mosquitto\pwfile.example

Save the file.

2. 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):

C:\mosquitto\mosquitto_passwd -b C:\mosquitto\pwfile.example USER PASS

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

3. Restart Windows

4. If the Mosquitto service is not started after the restart, open the cmd as administrator and run:

C:\mosquitto\mosquitto install

Step 7: Configure port forwarding rules for your router

1. Open cmd and determine the MAC (hardware) address of your device, where the Mosquitto broker is running:

ipconfig /all

This command will output the MAC address / "Physical Address" (formatted as xx-xx-xx-xx-xx-xx).

2. 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.

3. 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.

4. 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 43520 to 43520). Use TCP protocol and save the settings, making sure that the newly added port forwarding rule is enabled.

5. Reboot the router.

6. 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 "ipconfig" command).

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

1. Open GUI-O application on your Android device and navigate to "Settings -> Connections IoT -> IoT Settings".

2. Tap on "Server name" and set the value to your external IP, which was determined in Step 2.

3. Tap on "SSL port number" and set the value to your external port number, which was set in Step 7 (e.g., 43520).

4. Tap on "User name" and set the user name for authentication, which was created in Step 6.

5. Tap on "User password" and set the password for authentication, which was created in Step 6.

6. Tap on "Import certificate" and select the "ca.crt", which was transferred to the device in Step 5.

7. 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 9: Setup ESP32 and connect to Mosquitto broker

1. Download BasicMQTT_Mosquitto.ino sketch and open it in Arduino IDE.

2. Open the "ca.crt" file using a text editor and copy / replace the certificate with the one in BasicMQTT_Mosquitto.ino source code (keep same certificate formatting)

3. 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 8.

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