Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
519 lines (345 sloc) 12.2 KB


The EMQ X broker is cross-platform, which could be deployed on Linux, FreeBSD, Mac, Windows and even Raspberry Pi.


Linux, FreeBSD Recommended.

Download Packages

Download binary packages from:

The following OS types are supported:

Mac OS X

The package name consists of platform, version and release time.

For example:

Installing on Linux

Select Linux group from, download CentOS zip package, and then unzip:


Start the broker in console mode:

cd emqx && ./bin/emqx console

If the broker is started successfully, console will print:

starting emqx on node 'emqx@'
emqx ctl is starting...[done]
emqx trace is starting...[done]
emqx pubsub is starting...[done]
emqx stats is starting...[done]
emqx metrics is starting...[done]
emqx retainer is starting...[done]
emqx pooler is starting...[done]
emqx client manager is starting...[done]
emqx session manager is starting...[done]
emqx session supervisor is starting...[done]
emqx broker is starting...[done]
emqx alarm is starting...[done]
emqx mod supervisor is starting...[done]
emqx bridge supervisor is starting...[done]
emqx access control is starting...[done]
emqx system monitor is starting...[done]
http listen on with 4 acceptors.
mqtt listen on with 16 acceptors.
mqtts listen on with 4 acceptors.
http listen on with 4 acceptors.
Erlang MQTT Broker 3.0 is running now
Eshell V6.4  (abort with ^G)

CTRL+C to close the console and stop the broker.

Start the broker in daemon mode:

./bin/emqx start

Check the running status of the broker:

$ ./bin/emqx_ctl status
Node 'emqx@' is started
emqx 3.0 is running

Or check the status by URL:


Stop the broker:

./bin/emqx stop

Install via RPM

Select Linux group from, and download the RPM packages.


Install the package:

rpm -ivh emqx-centos7-v3.0-el7.centos.x86_64.rpm


Erlang/OTP R19 depends on lksctp-tools library

yum install lksctp-tools

Configuration, Data and Log Files:

/etc/emqx/emqx.conf Configuration file for the EMQ X Broker
/etc/emqx/plugins/*.conf Configuration files for the EMQ X Plugins
/var/lib/emqx/ Data files
/var/log/emqx Log files

Start/Stop the broker:

systemctl start|stop|restart emqx.service

Install via DEB

Select Linux group from, and download the DEB packages.


Install the package:

sudo dpkg -i emqx-ubuntu12.04-v3.0_amd64.deb


Erlang/OTP R19 depends on lksctp-tools library

apt-get install lksctp-tools

Configuration, Data and Log Files:

/etc/emqx/emqx.conf Configuration file for the EMQ X Broker
/etc/emqx/plugins/*.conf Configuration files for the EMQ X Plugins
/var/lib/emqx/ Data files
/var/log/emqx Log files

Start/Stop the broker:

service emqx start|stop|restart

Installing on Mac OS X

We could install the broker on Mac OS X to develop and debug MQTT applications.

Select OSX group from, and download Mac package.

Configure log level in etc/emqx.conf, all MQTT messages recevied/sent will be printed on console:

## Console log. Enum: off, file, console, both
log.console = both

## Console log level. Enum: debug, info, notice, warning, error, critical, alert, emergency
log.console.level = debug

## Console log file
log.console.file = log/console.log

The install and boot process on Mac are same to Linux.

Installing on Windows

Select Windows group from, and download the package.

Unzip the package to install folder. Open the command line window and 'cd' to the folder.

Start the broker in console mode:

bin\emqx console

If the broker started successfully, a Erlang console window will popup.

Close the console window and stop the emqx broker. Prepare to register emqx as window service.


EMQ X-3.0 cannot be registered as a windows service.

Install emqx serivce:

bin\emqx install

Start emqx serivce:

bin\emqx start

Stop emqx serivce:

bin\emqx stop

Uninstall emqx service:

bin\emqx uninstall

Install via Docker Image

Select Docker group from, and download EMQ X 3.0 Docker Image.

unzip emqx-docker image:


Load Docker Image:

docker load < emqx-docker-v3.0

Run the Container:

docker run -tid --name emq30 -p 1883:1883 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 8080:8080 -p 18083:18083 emqx-docker-v3.0

Stop the broker:

docker stop emq30

Start the broker:

docker start emq30

Enter the running container:

docker exec -it emq30 /bin/sh

Installing From Source

The EMQ X broker 3.0 requires Erlang/OTP R21+ and git client to build:

Install Erlang:

Install Git Client:

Could use apt-get on Ubuntu, yum on CentOS/RedHat and brew on Mac to install Erlang and Git.

When all dependencies are ready, clone the emqx project from and build:

git clone

cd emqx-rel && make

cd _rel/emqx && ./bin/emqx console

The binary package output in folder:


Build on Windows

Install Erlang:

Install MSYS2:

Use pacman of MSYS2 to install git and make:

pacman -S git make

Clone and build the `emqx-rel`_ project:

git clone -b windows

cd emqx-rel && make

Start the EMQ X in console mode:

cd _rel/emqx && ./bin/emqx console

TCP Ports Used

1883 MQTT Port
8883 MQTT/SSL Port
8083 MQTT/WebSocket Port
8084 MQTT/WebSocket/SSL Port
8080 HTTP Management API Port
18083 Web Dashboard Port

The TCP ports used can be configured in etc/emqx.config:

## TCP Listener: 1883,, ::1:1883
listener.tcp.external =

## SSL Listener: 8883,, ::1:8883
listener.ssl.external = 8883

## External MQTT/WebSocket Listener = 8083

## HTTP Management API Listener
listener.api.mgmt =

The 18083 port is used by Web Dashboard of the broker. Default login: admin, Password: public

Quick Setup

Two main configuration files of the EMQ X broker:

etc/emqx.conf EMQ X Broker Config
etc/plugins/*.conf EMQ X Plugins' Config

Two important parameters in etc/emqx.conf:

node.process_limit Max number of Erlang proccesses. A MQTT client consumes two proccesses. The value should be larger than max_clients * 2
node.max_ports Max number of Erlang Ports. A MQTT client consumes one port. The value should be larger than max_clients.


node.process_limit > maximum number of allowed concurrent clients * 2 node.max_ports > maximum number of allowed concurrent clients

The maximum number of allowed MQTT clients:

listener.tcp.external =

listener.tcp.external.acceptors = 8

listener.tcp.external.max_clients = 1024


# emqx       Startup script for emqx.
# chkconfig: 2345 90 10
# description: emqx is mqtt broker.

# source function library
. /etc/rc.d/init.d/functions

# export HOME=/root

start() {
    echo "starting emqx..."
    cd /opt/emqx && ./bin/emqx start

stop() {
    echo "stopping emqx..."
    cd /opt/emqx && ./bin/emqx stop

restart() {

case "$1" in
        echo $"Usage: $0 {start|stop}"


chmod +x /etc/init.d/emqx
chkconfig --add emqx
chkconfig --list

boot test:

service emqx start


## erlexec: HOME must be set uncomment '# export HOME=/root' if "HOME must be set" error.