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.

Installing EMQX

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 emqx on 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 ~/emqx/

mkdir -p emqx && tar -zxvf emqx-5.0.4-ubuntu20.04-amd64.tar.gz -C emqx

Next, use the following command to start EMQX

./emqx/bin/emqx start

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

Port listening

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.

MQTT Broker Port

Port	Description
1883	MQTT/TCP port
8883	MQTT/SSL port
8083	MQTT/WS port
8084	MQTT/WSS port
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 Dashboard

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

Connect

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.

Connect to MQTT Broker 1

The figure below indicates successful connection.

Connect to MQTT Broker 2

Subscribe to a testtopic as shown in the figure below.

Subscribe to MQTT topic

Publish

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.

Publish MQTT messages

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.

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://docs.emqx.com/en/emqx/v5.0/security/authn/authn.html

Create authentication

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.

MQTT Authentication

Select the Password-Based option, and then click Next.

MQTT Authentication Password-Based

Select Built-in Database for the database and click Next.

MQTT Authentication Built-in Database

Next, select the UserID Type, Password Hash and Salt Position, then click Create.

Here the default configuration is used, while readers may make selection according to the actual business needs.

MQTT Authentication

Add a user

The figure below shows the successful creation of the authentication. Next, click Users to add a user.

Add a MQTT Authentication user

After entering the User Management page, click the Add button on the far right, set the Username and Password in the pop-up box, and then click Save.

Add an MQTT Authentication user

The figure below shows the successful creation.

Add an MQTT Authentication user

Test

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.

MQTT Authentication test

Next, use the user name test1 that has not been created. Click Connect, and you will see the following Connection Failed information.

MQTT Authentication test

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.

Try EMQX Cloud for Free

A fully managed MQTT service for IoT

Get Started →

Blog

Tag: Installation

Subscribe to our blogs