As a large-scale distributed MQTT broker for IoT with more than 10 million downloads worldwide, EMQX, since it open-sourced in GitHub in 2013, has been widely adopted by more than 20,000 enterprise users from more than 50 countries and regions, and has connected more than 100 million IoT-critical devices in total.
Recently, EMQX released version 5.0 , which has also been greatly optimized and upgraded in terms of reliability of message transfer and ease of use experience, making it a milestone in the MQTT field. In the pre-launch performance test, the EMQX team reached 100 million MQTT connections +1 million message throughput per second with a 23-node cluster, which makes EMQX 5.0 the most scalable MQTT broker in the world by far.
EMQX supports running on Linux, Windows, macOS, Raspbian and other operating systems, and also supports deployment with Docker, Kubernetes and Terraform. This article will take EMQX 5.0.4 as an example to introduce how to build a single-node MQTT broker on Ubuntu, and demonstrate the common problems encountered during the building process.
The operating system used for this demonstration is Ubuntu 20.04 64-bit.
Installing EMQX with APT
APT is the package manager that comes with Ubuntu. It is recommended to prefer to install EMQX with APT. At the same time, EMQX also provides the official APT source and one click configuration script to help users quickly install EMQX.
Configure the EMQX APT source.
curl -s https://assets.emqx.com/scripts/install-emqx-deb.sh | sudo bash
Copy the above command to the Ubuntu terminal and execute it. The following figure indicates successful configuration.
Install the latest version of EMQX.
sudo apt-get install emqx
After successful installation, use the following command to start EMQX.
sudo emqx start
As shown in the figure below,
EMQX 5.0.4 is started successfully!will pop up if the startup is successful. If there is no response to the command for a long time, please check whether the relevant port is occupied against the description in the section EMQX operation check.
EMQX management command
EMQX provides command line tools to help users start, close and enter the console. As shown in the figure below, execute
sudo emqxon the terminal to view all management commands.
Installing EMQX with tar.gz package
When the server has no public network access or needs to quickly deploy and verify the EMQX function,
tag.gz package can be used for installation, which is independent of any third party and easy to manage.
Download the installation package
Visit the EMQX download address. Select the
Package tag, select
Ubuntu20.04 amd64/tag.gz for the installation package type, and then click the “copy” icon on the right (this will copy the whole line of wget download command).
Paste the download command to the ubuntu terminal and perform the download operation.
Unzip and install
Execute the following command on the server terminal, extracting the compressed package to the
emqx directory under the current directory.
This demonstration will be installed under the current user's home directory, that is
mkdir -p emqx && tar -zxvf emqx-5.0.4-ubuntu20.04-amd64.tar.gz -C emqx
Next, use the following command to start EMQX
If the startup is successful,
EMQX 5.0.4 is started successfully! will pop up. If there is no response to the command for a long time, please check whether the relevant port is occupied against the description in the section EMQX operation check.
EMQX Operation Check
Use the command
netstat -tunlp to check the operation of the EMQX port. By default, EMQX will start the following ports. Check the port occupancy in case of exceptions.
This command can also be executed before the EMQX installation to ensure that the relevant port is not occupied.
|18083||EMQX Dashboard port|
|4370||Erlang distributed transmission port|
|5370||Cluster RPC port. By default, each EMQX node has a RPC listening port.|
Access to Dashboard
EMQX provides a Dashboard for users to manage and monitor EMQX and configure required functions through Web pages. The Dashboard can be accessed via a browser at
http://localhost:18083/ (Replace the localhost with the actual IP address) after EMQX has been successfully started.
Before accessing Dashboard, make sure that port 18083 is opened in the server firewall
The default user name of Dashboard is
admin, and the password is
public. After the first successful login, you will be prompted to change the password.
MQTT Connection Test
Next, click the
WebSocket Client in the left menu bar, which can test MQTT over Websocket to verify whether the MQTT broker has been successfully deployed.
It is required that the firewall should have opened the right for access to port 8083
As shown in the figure below, the tool has automatically filled in the host according to the access address. We can click the
Connect button directly.
The figure below indicates successful connection.
Subscribe to a
testtopic as shown in the figure below.
As shown in the figure below, we have published two messages to
testtopic which have been received successfully, indicating that the MQTT broker has been successfully deployed and is running normally.
So far, we have completed the building and connection test of the MQTT broker, but the server can be used for testing only. To deploy the MQTT broker available in the production environment, we also need to perform the most important authentication configuration.
By default, EMQX will allow any client connection until the user creates an authenticator which will authenticate a client according to the authentication information provided by the client. A client can connect successfully only when it passes the authentication. Next, we will demonstrate how to use the built-in database of EMQX for authentication of username and password.
EMQX also provides authentication integration support with a variety of back-end databases, including MySQL, PostgreSQL, MongoDB, and Redis.
Check the documentation for more authentication methods: https://www.emqx.io/docs/en/v5.0/security/authn/authn.html
EMQX has supported the authentication configuration in Dashboard since version 5.0, allowing users to create secure MQTT services more conveniently and quickly. Click
Authentication under the
Access Control menu to enter the Authentication Configuration page, and then click the
Create button on the far right.
Password-Based option, and then click
Built-in Database for the database and click
Next, select the
Password Hash and
Salt Position, then click
Here the default configuration is used, while readers may make selection according to the actual business needs.
Add a user
The figure below shows the successful creation of the authentication. Next, click
Users to add a user.
After entering the User Management page, click the
Add button on the far right, set the
Password in the pop-up box, and then click
The figure below shows the successful creation.
Next, we use the Websocket tool provided by Dashboard to test whether the authentication has been successfully configured. Enter the username and password you just created in the Connect configuration, and then click
Connect. A pop-up window on the right indicates that it is connected.
Next, use the user name
test1 that has not been created. Click Connect, and you will see the following Connection Failed information.
So far, we have completed the authentication configuration for EMQX and set up a single-node MQTT broker available in the production environment. To ensure the high availability of the MQTT broker, you need to create a multi-node EMQX cluster. The cluster creation will not be detailed in this document. You may refer to the EMQX Cluster documentation for configuration.