Back to all

How to Enable WebSockets for Mosquitto MQTT Broker

This article explains WebSockets and configuring them for the Mosquitto MQTT Broker. We provide a detailed description of how to install, configure and test the broker.

Below you will find some rationale on the WebSockets protocol itself, what it is, how it works, and why one would want to use WebSocket with an MQTT broker.

Suppose you are already familiar with those topics and only want to know how to configure WebSockets on Mosquitto specifically. In that case, you can go directly to How to configure WebSockets for the Mosquitto broker section.

What is WebSocket?

WebSocket is a stateful communication protocol that provides a persistent full-duplex channel between the server and the client by reusing the same connection that was opened at the beginning of the communication (during the opening handshake). WebSocket works over a TCP connection and resides at layer 7 in the OSI model.

But don’t worry if this sounds complicated, we are going to explore the concepts of WebSocket in more details below.

Why not HTTP?

A widely used web communication protocol is HTTP (Hypertext Transfer Protocol). So why not always use it? The answer is always: “It depends on the use case.” HTTP was designed as a stateless connection-oriented protocol for data retrieval on request. Stateless connection-oriented implies that for every request, a new connection is opened. This connection is one-time: the connection is terminated once a request is answered with a response.

Additionally, it’s a one-sided connection. A client sends requests to the server, and the server responds to them. As a result, this connection is called an upstream connection (from the client to the server). On the contrary, the server cannot initiate a connection with a client (downstream connection) because it does not keep track of its clients.

So, the main points to take away are that HTTP initiates a new connection on every request and only allows an upstream connection (from the client to the server, which can alternatively be called a client polling of the server).

Now imagine a case where we have data updated thousands of times per second on the server’s side. We will encounter specific issues if we want to propagate these data updates to the client and use HTTP. We would have to set up a very frequent (thousand times per second) polling of the server for every client. This activity, in turn, would mean that we will have thousands of HTTP connections for every client opening and closing every second, which would put a considerable load both on the clients and the server.

Also, it’s doubtful that all our clients will receive all the data updates as frequently as they come to the server because the time it takes to create an HTTP connection might already be longer than the interval between the updates in the data on the server. And don’t forget to add a noticeable computational load on the server, which can cause response delays since the server now needs to handle thousands of requests from many clients during short time intervals.

A typical HTTP server processes work package after work package. Work packages cannot be processed simultaneously. As a result, not only would we not be able to reflect all the frequent data changes on the client’s side as soon as they appear, but we would also unnecessarily overload our entire system.

So, what do we do? It is when WebSocket protocol (sometimes simply “WebSockets”) comes to the rescue.

How does WebSocket protocol work?

WebSockets’s main philosophy is simple and can be described as “why don’t we use a single connection for the entire communication with a client?” Instead of opening and closing the connection on every request, we establish it first and reuse it whenever we want to send new data. The critical part here is that our established connection is now a duplex (two-way) which means it can be used for both upstream (client to server) and downstream (server to client) messaging.

Of course, this also means that our connection now needs to be stateful, and the server should keep track of all the established connections to every end-user/client to know where to send the data to reach a specific client. But the main benefit is that there is no connection establishment overhead on every client’s request. The server can now also push the data to the clients downstream in contrast to HTTP, which supports only the upstream connections. This is exactly what we need to do to solve our previous use case with a thousand data updates per second.

Since WebSocket protocol works over TCP, we get a secure, reliable connection where no data gets lost (no loss occurs on the transport or application layer). The application logic handles the loss of data on the application layer, not the protocol). The communication itself now happens faster than in the case of HTTP.

WebSocket connection only terminates whenever one of the communicating parties decides to terminate it or becomes unavailable/leaves the conversation. In the case of HTTP, the connection always terminates after the server’s response.

To establish a WebSocket connection, the browser issues an Upgrade HTTP response that tells the other communication party that a WebSocket channel needs to be established. This point is also an important one to remember: to establish a WebSocket connection, an initial HTTP request has to be performed.

HTTP vs WebSocket summary

In the following table we provide a short comparison of WebSocket and HTTP protocols:

Works on application layer in the OSI modelWorks on application layer in the OSI model
Works over TCP connectionWorks over TCP connection
Establishes a single persistent connectionEstablishes a new connection for every request
Terminates connection only when one of the communicating parties terminates itTerminates connection right after sending a response to the request
Bidirectional connection (both upstream and downstream)Unidirectional connection (only upstream possible)
Does not define any format for data that is being exchangedUses HTTP format with appropriate headers, (body) for every HTTP request type
Initial request to establish WebSocket is sent as an HTTP Upgrade requestPrevents the server from sending data to the client without an explicit request

If you are also interested in learning about the differences between HTTP and MQTT, check out the blog here on HTTP vs. MQTT: Choose the best Protocol for your IoT Project.

When to use WebSockets?

As we have seen in the sections above, WebSockets appear to be a fitting solution whenever we need to frequently and reliably update data (that comes from the server) on the client and/or exchange the messages between a client and server in both directions. You can think of the frequently changing data as real-time data. Just imagine some meteorological station that takes many measurements per second in many locations in the real world and sends this data to the server. It’s a bit of a contrived example because such stations don’t operate like that, but for the sake of an intuitive analogy, let’s take this for granted. Notably, a data visualization application for such a station would be an excellent example of using WebSockets.

In short, the WebSocket protocol is a good solution for interactive, dynamically updated services and real-time web applications. However, there is no point in using it for data that is not updated or is rarely updated and does not need to be immediately pushed to the client. Online catalogs, articles, and this blog you are currently reading are not being updated in real-time. Therefore, in all these cases, one will get no speed up from a WebSocket connection (since, as we have seen, to establish a WebSocket channel, an HTTP request has to be issued first anyway).

On the other hand, some well-known real-world examples of WebSocket applications include: 

  • Browser push notifications: browsers only use HTTP or WebSocket. We would need to establish a WebSocket connection to connect downstream and push some messages to the client from the server. For example, we can display notifications about incoming messages in a personal cabinet of a ticketing system or an online store;
  • Online chats / real-time comment sections, including customer support services, hold the same rationale as above. Note that we are also dealing with systems that are liable to frequent updates: new messages/comments and so on;
  • In online games, especially in multiplayer: the user receives data about the new actions and the state changes of the other players on the map. Then the client part of the game renders the changes;
  • Exchanges, trading platforms, and other commercial services with rapidly changing statistics, prices, etc. Dealing with dashboards and graphs with real-time data;
  • Social networks and blogs: Facebook Messenger, Instagram, or Telegram use WebSocket for sending, receiving, and updating messages (especially in the browser, since mobile devices also implement different protocols).

So, now that we know about the WebSocket technology and its applications, let’s explore why we might need this protocol for an MQTT broker and how we can configure Mosquitto MQTT over WebSockets.

Why use WebSockets for an MQTT broker?

Imagine a scenario where we want to visualize or get the data from the MQTT broker directly into the client web application (web app running in the browser). We might want to create a graphic browser interface for the MQTT broker. Unfortunately, we wouldn’t be able to achieve direct communication between the broker and the web browser using the MQTT protocol itself because web browsers don’t implement (speak) MQTT. However, since the data in the MQTT broker might change frequently and we need a downstream connection (from the broker to the client), it is a perfect use case for WebSockets.

The following scheme shows how one can use WebSockets with a client application in the browser:

WebSockets with Client Application MQTT

Here we can see a web server that, upon the user’s request, issues a client web application (you can think of this application as some HTML web pages with javascript code for handling the logic). This application then runs in the browser and opens a WebSocket connection to the Mosquitto MQTT broker over the WebSockets. After that, the web app can freely and quickly receive and visualize the latest data from the broker.

Also, for those looking into commercial use of an MQTT broker for their IoT project, don’t forget to check out the Pro Edition for Eclipse Mosquitto. If you want to test the product first, please sign up for a free 14 day trial here.

How to configure WebSockets for the Mosquitto broker (Unix systems)

For Linux

Step 1: Initial installation of dependencies

First of all, you need to make sure that our environment has the necessary build tools to complete the setup:

Use to keep all of your packages up to date in Debian or a Debian-based Linux distribution: sudo apt-get update

Use to keep all of your packages up to date in Debian or a Debian-based Linux distribution: sudo apt-get update

Use to install all important dependencies to install WebSocket and the Mosquitto MQTT broker:

sudo apt-get install --yes build-essential libssl-dev libcjson-dev libwebsockets-dev

Information about CMake:

CMake is a build automation system that generates build control files from CMakeLists.txt files but does not directly deal with building.


– Make sure you are root as «cmake» requires it.
– On error cmake can’t find openssl or related to openssl, use the following command:

sudo apt-get install libssl-dev

Information about SSL:

SSL is a protocol that provides secure data transfer between a server and a client.


– Using the command in the terminal dpkg –get-selections | grep libssl make sure that the libssl version is 1.1, if not, then enter the following command:

sudo apt install libssl1.1

Step 2: Download and set up Mosquitto

After installing all the necessary dependencies, we can move on to the second step.

tar zxvf mosquitto-2.0.9.tar.gz
cd mosquitto-2.0.9

Step 3: Build Mosquitto and enable WebSocket

In order to install Mosquitto insert the following command into your terminal and enter:

sudo make install
sudo cp mosquitto.conf /etc/mosquitto

Step 4: Configure Mosquitto over WebSocket

Now open mosquitto.conf file with the following command:

sudo nano /etc/mosquitto/mosquitto.conf 

Of course, you can use another text editor like vim or can always search for the file on your system and open it manually too.

The file will open in your text editor and is separated into different sections.

You can also find all these commands already in config but commented out – though there might be slight differences. We recommend you simply add the new commands.

Search for the “Persistence” section. In this section add:

autosave_interval 1800
persistence true
persistence_file mosquitto.db
persistence_location /var/lib/mosquitto/

Search for the “Logging” section. In this section add the following:

connection_messages true
log_timestamp true

You will need the above commands only to show the Mosquitto logs in the console. You may not want to touch them, but we will enable the logs for testing later.

Search for the “Listeners” section. In this section add:

listener 1883
listener 8080
protocol websockets
allow_anonymous true

The last line is only needed for simple testing and is often not used in the end.

Step 5: Add a user to mosquitto

Enter the following command into your terminal:

sudo adduser mosquitto

You will be asked for a username and a password you created in step 2.

Step 6: Test WebSocket

To test, you can run Mosquitto with flag “-c” which should point to the configuration file you just created.

Insert in the terminal and enter:

mosquitto -c /etc/mosquitto/mosquitto.conf

As a result, you should see that the MQTT broker starts with a standard MQTT protocol listener (port 1883) and a WebSockets listener running on port 8080:

1658680400: mosquitto version 2.0.9 starting
1658680400: Config loaded from /etc/mosquitto/mosquitto.conf.
1658680400: Opening websockets listen socket on port 8080.
1658680400: Opening ipv4 listen socket on port 1883.
1658680400: Opening ipv6 listen socket on port 1883.
1658680400: mosquitto version 2.0.9 running.

For MacOS

Step 1: Install the “Homebrew” packet manager.

Enter the following command:

/bin/bash -c "$(curl -fsSL"

Info about Homebrew: Homebrew is an open-source software that allows you to install packages and applications. 


– You must have the Xcode command line components installed and/or updated. Use the following command:

xcode-select –install

– After updating MacOS, you can observe the following errors:

  • dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib
  • configure: error: Cannot find libz

You can solve this by entering the following commands in the terminal:

xcode-select --install
brew upgrade

– If, after running brew upgrade, you receive an Error: undefined method `include?’ for nil:NilClass, then you will need to run the following commands in the terminal:

cd "$(brew --repository)/Library/Contributions/examples"
git clean -n # if this doesn't list anything that you want to keep, then git clean -f # this will remove untracked files

Step 2: Install “cmake”.

Run the following command:

brew install cmake

Information about CMake:

CMake is a build automation system that generates build control files from CMakeLists.txt files but does not directly deal with building.


– Make sure you are root as «cmake» requires it.
– On error cmake can’t find openssl or related to openssl, run the following commands:

brew install openssl
cmake -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl -DOPENSSL_LIBRARIES=/usr/local/opt/openssl/lib

Step 3: Download and set up Mosquitto

Use the following commands:

tar zpxpvf mosquitto-2.0.15.tar.gz
cd mosquitto-2.0.15

Step 4: Enable WebSocket

Edit the Mosquitto file. Search for “mosquitto-2.0.9”, open the folder, and open in a typical text editor.

1. Search for WITH_WEBSOCKETS:=no

2. Change the “no” to “yes”, like this: WITH_WEBSOCKETS:=yes

3. Save the file.

Step 5: Install Mosquitto

Enter these commands:

cmake -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl -DOPENSSL_LIBRARIES=/usr/local/opt/openssl/lib

wait for the commands above to finish and then run:


Then run:

make install 
sudo cp mosquitto.conf /etc/mosquitto

Step 6: Configure Mosquitto to use WebSockets

Edit the Mosquitto mosquitto.conf file. Search for “mosquitto-2.0.9”, open the folder, and open mosquitto.conf in a text editor.

Search for the “Persistence” section. In this section, add the following:

autosave_interval 1800
persistence true
persistence_file mosquitto.db
persistence_location /var/lib/mosquitto/

Search for the “Logging” section. In this section, add:

connection_messages true
log_timestamp true

Search for the “Listeners” section. Within this section, add:

listener 1883
listener 8080 
protocol websockets
allow_anonymous true

Allowing unauthenticated access. Also it is the end user’s responsibility to provide authentication appropriate to their needs.

Step 7: Test WebSocket

To test, you can run Mosquitto and point it to the configuration file you just created.

Run the following:

mosquitto -c /etc/mosquitto/mosquitto.conf

And as a result, you should see that the MQTT broker starts with a standard MQTT protocol listener (port 1883) and a WebSockets listener running on port 8080.

1663084872: mosquitto version 2.0.9 starting
1663084872: Config loaded from /etc/mosquitto/mosquitto.conf.
1663084872: Opening websockets listen socket on port 8080.
1663084872: Opening ipv4 listen socket on port 1883.
1663084872: Opening ipv6 listen socket on port 1883.
1663084872: mosquitto version 2.0.9 running.

Testing with MQTT Explorer

Now that we have configured the MQTT broker to use WebSockets let’s test it and see if it works. For that, we can use an excellent visual interface of the MQTT Explorer.

To start working with MQTT Explorer, you need to install it. You can find all information on installing this program on the official website of MQTT Explorer in the Download section.

MQTT Explorer WebSocket Mosquitto

You can open your terminal window with a running Mosquitto instance beside the MQTT Explorer like this:

Terminal window alongside a running Mosquitto

Let’s establish a connection to publish MQTT messages and create/subscribe to MQTT topics. To do this, click on the yellow button with a plus sign in the upper left corner, enter the Host field:, and in the Port field: 1883 (default), and click the CONNECT button.

Once it connects, you will see it in the Mosquitto output:

1663085440: New connection from on port 1883.
1663085440: New client connected from as mqtt-explorer-079b58b5 (p2, c1, k60).
Establishing a connection WebSocket Mosquitto

After establishing the connection, we can create topics and publish messages to the topics. To do this, fill in the fields in the Publish tab and click the PUBLISH button.

MQTT Publish message with Mosquitto

On the left panel, you can see all the published Topics and their values.

MQTT published topics

By clicking on a specific topic, you will see the added and removed values and the post history.

MQTT Topic History

After pressing the DISCONNECT button or closing the MQTT Explorer application, you can see in the terminal that the connection disconnects with the client.

1663086849: Client mqtt-explorer-079b58b5 disconnected.
MQTT Explorer Disconnect


In this article, you have learned about the WebSocket protocol and gained practical knowledge of the installation and configuration of WebSockets for the Mosquitto MQTT broker. Mosquitto is flexible and customizable, so you can easily configure it to your needs using the simple steps described in this article.

As a summary, let us revise the most important. The main takeaway points are:

1) WebSocket is a protocol that creates a single stateful persіstant two-way connection between the server and the client.

2) WebSocket protocol is a good solution whenever we have to work with rapidly changing data or whenever we want to establish a secure two-way persistent connection for exchanging messages back and forth.

3) We might need to open a WebSockets connection on the MQTT broker whenever we need to forward the data from the broker directly into the browser.

4) To enable WebSockets in Mosquitto MQTT broker, the main things that you need to do are to build Mosquitto with WebSockets and add listener and protocol properties to the config file.

Newsletters icon

Subscribe for monthly updates