Pro Mosquitto

How to Install Mosquitto MQTT Broker on Windows

Serhii Orlivskyi24.03.202324.03.2023

Eclipse Mosquitto is one of the world’s most popular open-source MQTT brokers. This article will tell you how to install and configure the Mosquitto MQTT Broker on Windows and how to install Mosquitto as a Windows service. Then we will explain how to test the Mosquitto MQTT broker using the popular command line tools: mosquitto_sub and mosquitto_pub.

How to install Mosquitto MQTT Broker on Windows

To quickly install Mosquitto on Windows, select the desired installation file from mosquitto.org and download it. Then run the saved executable.

The Eclipse Mosquitto Setup wizard will start. Click Next to continue the installation.

Select the components to install. If you want Mosquitto to start automatically when Windows starts, then install the Service component. It will use the 1883 port by default.

You will also need the Visual Studio runtime because Mosquitto is built using this runtime and depends on certain libraries and components provided by it. You might not want to install it if you already have it, but if unsure, leave it as is and continue to the next step.

Select the installation directory for Eclipse Mosquitto or leave the default value (C:\Program Files\mosquitto for 64-bit executable and C:\Program Files (x86)\mosquitto for 32-bit) and click Install.

After the installation process is complete, you will see a corresponding message. All required files for Mosquitto will be automatically downloaded to the installation directory.

Click Finish in the setup wizard and start using the MQTT Mosquitto broker on Windows.

If you want to install Mosquitto broker without running the graphical part of the installer, you can do so by running the installer from the command line (cmd) with the ‘/S’ switch (silent mode):

mosquitto-2.0.15-install-windows-x64.exe /S

Alternatively, you can use PowerShell. Note that PowerShell uses a slightly different syntax than the command line. For example, running the “mosquitto” command in cmd (inside of the Mosquitto installation directory) has its equivalent in PowerShell, which is: “.\mosquitto”.

Use the ‘/D’ switch to change the installation directory:

mosquitto-2.0.15-install-windows-x64.exe /S /D=:\"Program Files"\mosquitto

After installing Mosquitto broker, you can check which command line options are supported. To do this, navigate inside the installation directory and run the following command:

mosquitto -h

Note that Mosquitto is not automatically globally visible in cmd. To work with it, you must either be inside the installation directory or add the installation directory to the PATH environment variable and restart the command prompt.

How to Run Mosquitto MQTT Broker as a Service on Windows

It is possible to install Mosquitto as a Windows service so that it runs in the background and automatically starts on Windows startup.

To install Mosquitto as a Windows service, run PowerShell or the command line as administrator (by right-clicking on their icon and choosing the “Run as administrator” option) and change the working directory to one where Mosquitto is installed. After that, run the following command:

mosquitto install

If you want to remove the Mosquitto on Windows service, later on, you can run the following command:

mosquitto uninstall

To start the Mosquitto broker as a service, open the Services application first. To do this, open Windows search and type “services.msc” or “Services” and press enter. Then find the service named Mosquitto Broker, and start it. By default, this service is configured to start automatically when Windows starts.

Alternatively, you can start Mosquitto using ‘sc’ or ‘net’ commands from the command line. Examples of using ‘sc’:

sc start mosquitto

To stop Mosquitto broker run:

sc stop mosquitto

To delete Mosquitto broker service run:

sc delete mosquitto or mosquitto uninstall

You can also view Mosquitto service status using the command:

sc query mosquitto

Also, you can run these commands in PowerShell, but use “sc.exe” instead of “sc”.

To check if the Mosquitto Broker service is running on port 1883, run the following command:

netstat -an | findstr 1883

If Mosquitto MQTT server has opened an IPv4 and IPv6 listening socket on port 1883, the output of this command will be the following two lines:

How to run Mosquitto as a Service on Windows in the Foreground

There is an alternative way to run Mosquitto which will, however, run in the foreground rather than the background as in the case with services.

Open the installation directory in the command line and use ‘mosquitto -v -c <path to mosquitto.conf>’ command to run the broker in verbose mode will allow you to debug messages. Note that when running from cmd, the default mosquitto.conf file will not be automatically picked up by the broker, so you have to specify it manually using the ‘-c’ option.”

Option -d (that allows us to run Mosquitto in the background) is unusable in Windows because Windows needs a daemon process manager. So, on Windows, we use services instead, as described above.

To stop Mosquitto from running in the foreground, press Ctrl + C in the cmd window where the broker is running.

In this article, we use the open-source Eclipse Mosquitto broker. However, the Pro Edition for Eclipse Mosquitto is also available. It provides cloud hosting, reliable support, high availability, and protects your data.

Check out the 14-day free trial of the Pro Edition for Eclipse Mosquitto broker and try its advanced features.

How to Configure the Mosquitto MQTT Broker on Windows

You can configure the operation of the Mosquitto broker using the configuration file mosquitto.conf located in the Mosquitto installation directory. This file is used only for Mosquitto running as a service. If you run Mosquitto from cmd, the mosquitto.conf file is not used, and it has to be manually specified with -c flag:

mosquitto -c

Note that if you want to start Mosquitto as a service and use a non-default configuration file, execute the following command when you start the service for the first time (instead of the aforementioned ‘sc start mosquitto’):

sc start mosquitto -c

mosquitto.conf file contains commented-out (with # symbol) parameters with default values. To change them, you need to uncomment the required parameter and specify a different value or add your configuration options anywhere in the file.

Authentication settings

You can allow anonymous connections from any host (without using a username and password) by adding the following options to your configuration file:

allow_anonymous true
listener 1883 0.0.0.0

This will allow any device on the network to connect to the broker, post messages and subscribe to topics. However, we recommend allowing only authenticated clients to connect for security reasons.

To do this, first, create a password file containing usernames and passwords in the format: “username:password”. That looks like the following (take a look at pwfile.example):

roger:$6$clQ4Ocu312S0qWgl$Cv2wUxgEN73c6C6jlBkswqR4AkHsvDLWvtEXZZ8NpsBLgP1WAo/qA+WXcmEN/mjDNgdUwcxRAveqNMs2xUVQYA==
sub_client:$6$U+qg0/32F0g2Fh+n$fBPSkq/rfNyEQ/TkEjRgwGTTVBpvNhKSyGShovH9KHewsvJ731tD5Zx26IHhR5RYCICt0L9qBW0/KK31UkCliw==
pub_client:$6$vxQ89y+7WrsnL2yn$fSPMmEZn9TSrC8s/jaPmxJ9NijWpkP2e7bMJLz78JXR1vW2x8+T3FZ23byJA6xs5Mt+LeOybAHwcUv0OCl40rA==

This can be done using the mosquitto_passwd command. To create a password file with an initial Mosquitto user, use the following command from the installation directory:

mosquitto_passwd -c <path where you want your password file to be created> <user_name>

For example:

mosquitto_passwd -c C:\"Program Files"\mosquitto\passwd test_user

This will create a password file with the initial user test_user.

To add another user to a password file, run the command:

mosquitto_passwd -b C:\"Program Files"\mosquitto\passwd user_name password

Note that if you want to delete a user from the file, you can use -D flag and specify the name of the user to be removed. 

After you have created a password file with all the needed users, add the following lines to the configuration file:

password_file C:\Program Files\mosquitto\passwd
allow_anonymous false
listener 1883

How to Handle Persistent Data and Logs

Mosquitto broker allows you to save two different types of logs:

• Information and debug logs.
• Broker system data (persistent data feature).

To configure the logging of your Mosquitto broker, you need to use the logging options located in the Logging section of the configuration file.

Add the following parameter to specify which file to store logs. Also, you need to make sure that this path exists, so create a log directory (‘C:\Program Files\mosquitto\log’ in the example below) manually.

log_dest file C:\Program Files\mosquitto\log\mosquitto.log

You can also choose the events to log: debug, error, warning, notice, information, etc. To save logs for all types of events, use the following option:

log_type all

Add the following settings to the configuration file to save the persistence data and adjust persistence_location as needed. You need to ensure this path exists, so manually create a data directory (‘C:\Program Files\mosquitto\data\’ in the example).

persistence true
persistence_file mosquitto.db
persistence_location C:\Program Files\mosquitto\data\
autosave_interval 60

Persistence data will only be saved to the file on Mosquitto shutdown or at certain intervals controlled by the autosave_interval config option.

When Mosquitto runs as a service, all the files it creates will only have permissions for the SYSTEM Windows account. To access these files from your user account, you must go into the properties of those files and, on the Security tab, add your Windows user.

There are also a lot of other Mosquitto broker settings in the configuration file. For example, you can configure Mosquitto to listen on multiple ports, configure TLS certificates, limit message size, and more.

You can find a complete list of Mosquitto broker settings here.

Note that you need to restart the broker for the changes made in the configuration file to take effect. Use the command ‘sc stop mosquitto’ to stop the Mosquitto service and then execute ‘sc start mosquitto’ to start it up again.

How to Test an Installed Mosquitto MQTT Broker on Windows

To test the correct operation of the Mosquitto broker, we will use mosquitto_sub and mosquitto_pub commands. You can also use any MQTT client, like MQTT Explorer.

Subscribe to Topics Using mosquitto_sub Windows

Mosquitto_sub Windows MQTT client allows you to subscribe to topics and print received messages. To receive a message, you should subscribe to a topic before a message is published. In this example, we subscribe and listen to a topic using mosquitto_sub while publishing the messages with mosquitto_pub.

To subscribe to the topic named “Test topic”, run the following command:

mosquitto_sub -i mosq_sub1 -t "Test topic" -d

This command uses the following options:

• i – Client id. If this parameter is not passed, the server generates the client ID automatically.
• t – Name of the topic to subscribe to.
• d – Enables printing of debug messages.

After that, the MQTT client will be launched, which will notify about new messages in the “Test topic” topic and print them.

Mosquitto_sub uses localhost and 1883 port by default. Use option ‘-h’ to change the host and option ‘-p’ to change the port.

If you use authentication to connect to the broker, specify a username and a password using -u and -P options:

mosquitto_sub -i mosq_sub1 -t "Test topic" -u <username> - P <password> -d

You can also unsubscribe from topics. The -U option is used for this.

mosquitto_sub -U “Test topic”

For unsubscribing from topics to make sense, the clean-session parameter must be set to false.

Publish Messages with mosquitto_pub Windows

Mosquitto_pub is a simple MQTT client that publishes one message to a topic and exits.

To publish a message, run the following command inside of the Mosquitto installation directory in a new cmd window:

mosquitto_pub -i mosq_pub1 -t "Test topic" -m "Test message" -d

This command uses the following options:

• i – Client id. If this parameter is not passed, the server generates client ID automatically.
• t – Name of the topic to which the message is published.
• m – Text payload of the message to be published.
• d – Enables printing of debug messages.

Below is the output of the command.

By default, messages are sent to the broker at localhost, port 1883. To publish them to a different host, use the ‘-h’ option. Use the ‘-p’ parameter to connect to a different port.

To specify a username and password for user authentication use -u and -P options:

mosquitto_pub -i mosq_pub1 -t "Test topic" -m "Test message" -u <username> - P <password> -d

Ensure that the publish token is the same as the topic you have previously subscribed to (-t “Test topic”). If you did everything correctly, you would see the published messages (“Test message”) in the window where you executed the ‘mosquitto_sub’ command.

Uninstalling Mosquitto MQTT Server on Windows

If you installed Mosquitto as a service and want to uninstall it, you first need to stop it using the command ‘sc stop mosquitto’. Then run ‘sc delete mosquitto’ or, alternatively, ‘mosquitto uninstall’ to uninstall the Mosquitto Windows service.

The “Uninstall.exe” file is inside the installation directory, which you need to run to uninstall Mosquitto. After that, you just need to delete the installation directory, and everything is done.

Uninstall.exe /S

Troubleshooting Mosquitto MQTT Server on Windows

Only one user is allowed per socket address

Receive the error message “Normally only one user is allowed per socket address (protocol/network address/port).” You may already have another application running that is listening on port 1883.

Possible Solution

Run ‘netstat -ano | findstr :1883’ (or use a different port instead of 1883 if it was configured) command and check if the specified port is already in use by another program. The occupying process’s process id (PID) will be in the last column. You can copy it and then run ‘taskkill /F /PID ’ replacing the with the value from ‘netstat’. You may also free up the port in any other way after identifying which application occupies it. Then killing the process with ‘taskkill’ is not necessary.

Can’t Connect to Mosquitto Broker with Local IP Address

When connecting to the Mosquitto broker using a local IP address other than localhost, a connect ECONNREFUSED error occurs.

Possible Solution

To listen on addresses other than localhost, you need to edit the configuration file. Add the listener parameter and specify the port on which you want to listen for incoming network connections, or you can specify just the desired IP addresses/hostnames.

listener 1883 192.168.1.100 

192.168.1.100 is the desired IP address to listen on (but you can also specify a hostname there instead). This option can also be specified multiple times to bind multiple different addresses. If we omit it, Mosquitto will be listening on localhost.

Note that having at least one listen in your config file is always a good idea. This will help avoid some problems down the road.

Additionally, to allow anonymous connections from remote addresses, you can add the option:

allow_anonymous true

However, you should be careful with this option as it is not recommended to allow anyone to access the broker because of security considerations.

If you are using the open-source version of Eclipse Mosquitto broker for a commercial project and need advice or help to solve a problem, we offer open-source Mosquitto support. This can help you quickly solve your problems, ensure your system’s stability and security, get quick access to new patches and fixes, and be the first to receive information about new releases.

Summary

In this article, we described MQTT Mosquitto Broker and how to install, configure, and test Mosquitto on Windows. In addition, we considered the most common problems and their solutions when using the Mosquitto broker.

Let’s summarize the main points:

• Use the executable file for Mosquitto MQTT broker Windows installation.
• You can also install Mosquitto as a Windows Service to run it in the background or automatically when the system starts.
• To configure Mosquitto broker (including authentication settings, logging, etc.), use mosquitto.conf configuration file.
• You can test Mosquitto using popular MQTT clients mosquitto_pub and mosquitto_sub, which are bundled into the installation.