Build an EMQ X cluster based on HAProxy

HAProxy is free, open source software that provides a high availability load balancer and proxy server for TCP and HTTP-based applications that spreads requests across multiple servers. It is written in C and has a reputation for being fast and efficient (in terms of processor and memory usage). 1


Software versions

  • Ubuntu 18.04
  • EMQ X Broker v4.2.5
  • HAProxy 2.2+

Machine allocation

  • HAProxy
  • EMQ X Node 1
  • EMQ X Node 2



Refer to EMQ X Broker




sudo apt-get update
sudo apt-get install software-properties-common -y
sudo add-apt-repository -y ppa:vbernat/haproxy-2.2
sudo apt-get update
sudo apt-get install -y haproxy=2.2.\*



Modify emqx/etc/emqx.conf configuration file, and same for the other machine.

## Modify the node name = emqx@

## Modify the cluster strategy to static, and no need to add nodes manually any more
cluster.discovery = static

## All cluster nodes
cluster.static.seeds = emqx@, emqx@

## To obtain an IP address, you need to set the proxy_protocol
listener.tcp.external.proxy_protocol = on


Modify /etc/haproxy/haproxy.cfg.

Add TCP backend configuration.

backend backend_emqx_tcp
    mode tcp
    balance roundrobin
    server emqx_node_1 check-send-proxy send-proxy-v2 check inter 10s fall 2 rise 5
    server emqx_node_2 check-send-proxy send-proxy-v2 check inter 10s fall 2 rise 5

Add dashboard backend configuration.

backend backend_emqx_dashboard
    balance roundrobin
    server emqx_node_1 check
    server emqx_node_2 check

Add TCP frontend configuration.

frontend frontend_emqx_tcp
    bind *:1883
    option tcplog
    mode tcp
    default_backend backend_emqx_tcp

Add dashboard frontend configuration.

frontend frontend_emqx_dashboard
    bind *:18083
    option tcplog
    mode tcp
    default_backend backend_emqx_dashboard



$ ./bin/emqx start

## Check the cluster status
$ ./bin/emqx_ctl cluster status

Cluster status: #{running_nodes =>
                  stopped_nodes => []}


$ sudo service haproxy start

You can access the dashboard via 18083 now.


Connect to the cluster via 1883. The connection status can be checked in the dashboard or by executing the command on the node.

$ ./bin/emqx_ctl clients list


If you need TLS termination, you need to prepare the emqx.key and emqx.crt files first and then merge them to produce the emqx.pem file.

$ cat emqx.crt emqx.key > emqx.pem

Then just add the following configuration.

frontend frontend_emqx_tcp
    bind *:8883 ssl crt /opt/certs/emqx.pem no-sslv3
    option tcplog
    mode tcp
    default_backend backend_emqx_tcp

So far, we have completed the build and use of the EMQ X cluster based on HAProxy. For more detailed use of HAProxy, see HAProxy Documentation.

Zhiwei Yu

Zhiwei Yu

Backend engineer.

The streaming database built for IoT data storage and real-time processing.

Fully managed MQTT 5.0 IoT cloud, start a 30-day free trial.

Related Links

EMQ X project newsletter 202101

Hello! This is our very first newsletter to share what’s happening in EMQ X open-source team.

Set up EMQ X Cloud MQTT Broker with openHAB

In this article, we will introduce to you the process of integrating openHAB with EMQ X MQTT Cloud, a Cloud-Native fully managed MQTT service.

EMQ X rule engine series (7) store messages to the MongoDB database

MongoDB is a product between relational database and non-relational database. Among non-relational databases, MongoDB has the most abundant functions and most resembles relational database. MongoDB is written in C++ and is an open source database system based on distributed file storage. MongoDB is designed to provide a scalable, high-performance data storage solution for data storage. It can easily add more nodes under high load to ensure service performance.