# Installation

The EMQ 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: https://www.emqx.io/downloads (opens new window)

Debianhttps://www.emqx.io/downloads/v2/latest/emqttd-debian.zip (opens new window)
Ubuntu12.04https://www.emqx.io/downloads/v2/latest/emqttd-ubuntu12.04.zip (opens new window)
Ubuntu14.04https://www.emqx.io/downloads/v2/latest/emqttd-ubuntu14.04.zip (opens new window)
Ubuntu16.04https://www.emqx.io/downloads/v2/latest/emqttd-ubuntu16.04.zip (opens new window)
CentOS7https://www.emqx.io/downloads/v2/latest/emqttd-centos7.zip (opens new window)
Debian7https://www.emqx.io/downloads/v2/latest/emqttd-debian7.zip (opens new window)
Debian8https://www.emqx.io/downloads/v2/latest/emqttd-debian7.zip (opens new window)
FreeBSDhttps://www.emqx.io/downloads/v2/latest/emqttd-freebsd.zip (opens new window)
Windows7https://www.emqx.io/downloads/v2/latest/emqttd-windows7.zip (opens new window)
Windows10https://www.emqx.io/downloads/v2/latest/emqttd-windows10.zip (opens new window)
Mac OS Xhttps://www.emqx.io/downloads/v2/latest/emqttd-macosx.zip (opens new window)
Dockerhttps://www.emqx.io/downloads/v2/latest/emqttd-docker.zip (opens new window)

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

For example: emqttd-centos64-v2.0.zip

# Installing on Linux

Download CentOS Package from: https://www.emqx.io/downloads/v2/latest/emqttd-centos7 (opens new window) , and then unzip.zip:

unzip emqttd-centos64-v2.0.zip

Start the broker in console mode:

cd emqttd && ./bin/emqttd console

If the broker is started successfully, console will print:

starting emqttd on node 'emqttd@'
emqttd ctl is starting...[done]
emqttd trace is starting...[done]
emqttd pubsub is starting...[done]
emqttd stats is starting...[done]
emqttd metrics is starting...[done]
emqttd retainer is starting...[done]
emqttd pooler is starting...[done]
emqttd client manager is starting...[done]
emqttd session manager is starting...[done]
emqttd session supervisor is starting...[done]
emqttd broker is starting...[done]
emqttd alarm is starting...[done]
emqttd mod supervisor is starting...[done]
emqttd bridge supervisor is starting...[done]
emqttd access control is starting...[done]
emqttd 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 2.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/emqttd start

Check the running status of the broker:

$ ./bin/emqttd_ctl status
Node 'emqttd@' is started
emqttd 2.0 is running

Or check the status by URL:


Stop the broker:

./bin/emqttd stop

# Install via RPM

Download the RPM packages:

CentOS6.8https://www.emqx.io/downloads/v2/latest/emqttd-centos6.rpm (opens new window)
CentOS7https://www.emqx.io/downloads/v2/latest/emqttd-centos7.rpm (opens new window)

Install the package:

rpm -ivh emqttd-centos7-v2.1.2-1.el7.centos.x86_64.rpm


Erlang/OTP R19 depends on lksctp-tools library

yum install lksctp-tools

Configuration, Data and Log Files:

/etc/emqttd/emq.confConfiguration file for the EMQ Broker
/etc/emqttd/plugins/*.confConfiguration files for the EMQ Plugins
/var/lib/emqttd/Data files
/var/log/emqttdLog files

Start/Stop the broker:

systemctl start|stop|restart emqttd.service

# Install via DEB

Download the DEB packages:

Ubuntu12.04https://www.emqx.io/downloads/v2/latest/emqttd-ubuntu12.04.deb (opens new window)
Ubuntu14.04https://www.emqx.io/downloads/v2/latest/emqttd-ubuntu14.04.deb (opens new window)
Ubuntu16.04https://www.emqx.io/downloads/v2/latest/emqttd-ubuntu16.04.deb (opens new window)
Debian7https://www.emqx.io/downloads/v2/latest/emqttd-debian7.deb (opens new window)
Debian8https://www.emqx.io/downloads/v2/latest/emqttd-debian7.deb (opens new window)

Install the package:

sudo dpkg -i emqttd-ubuntu16.04_v2.0_amd64.deb


Erlang/OTP R19 depends on lksctp-tools library

apt-get install lksctp-tools

Configuration, Data and Log Files:

/etc/emqttd/emq.confConfiguration file for the EMQ Broker
/etc/emqttd/plugins/*.confConfiguration files for the EMQ Plugins
/var/lib/emqttd/Data files
/var/log/emqttdLog files

Start/Stop the broker:

service emqttd start|stop|restart

# Installing on FreeBSD

Download FreeBSD Package from: https://www.emqx.io/downloads/v2/latest/emqttd-freebsd.zip (opens new window)

The installing process is same to Linux.

# Installing on Mac OS X

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

Download Mac Package from: https://www.emqx.io/downloads/v2/latest/emqttd-macosx.zip (opens new window)

Configure log level in etc/emq.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

Download Package from: https://www.emqx.io/downloads/v2/latest/emqttd-windows.zip (opens new window) .

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

Start the broker in console mode:

bin\emqttd console

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

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


Cannot register EMQ-2.0 as a windows service.

Install emqttd serivce:

bin\emqttd install

Start emqttd serivce:

bin\emqttd start

Stop emqttd serivce:

bin\emqttd stop

Uninstall emqttd service:

bin\emqttd uninstall

# Install via Docker Image

Download EMQ 2.0 Docker Image:

https://www.emqx.io/downloads/v2/latest/emqttd-docker.zip (opens new window)

unzip emqttd-docker image:

unzip emqttd-docker-v2.0.zip

Load Docker Image:

docker load < emqttd-docker-v2.0

Run the Container:

docker run -tid --name emq20 -p 1883:1883 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 18083:18083 emqttd-docker-v2.0

Stop the broker:

docker stop emq20

Start the broker:

docker start emq20

Enter the running container:

docker exec -it emq20 /bin/sh

# Installing From Source

The EMQ broker requires Erlang/OTP R20+ and git client to build:

Install Erlang: http://www.erlang.org/ (opens new window)

Install Git Client: http://www.git-scm.com/ (opens new window)

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 emqttd project from github.com and build:

git clone https://github.com/emqtt/emq-relx.git

cd emq-relx && make

cd _rel/emqttd && ./bin/emqttd console

The binary package output in folder:


# Build on Windows

Install Erlang: http://www.erlang.org/ (opens new window)

Install MSYS2: http://www.msys2.org/ (opens new window)

Use pacman of MSYS2 to install git and make:

pacman -S git make

Clone and build the emq-relx (opens new window) project:

git clone -b windows https://github.com/emqtt/emqttd-relx.git

cd emqttd-relx && make

Start the EMQ in console mode:

cd _rel/emqttd && ./bin/emqttd console

# TCP Ports Used

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

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

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

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

## External MQTT/WebSocket Listener
listener.ws.external = 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 broker:

etc/emq.confEMQ Broker Config
etc/plugins/*.confEMQ Plugins' Config

Two important parameters in etc/emq.conf:

node.process_limitMax number of Erlang proccesses. A MQTT client consumes two proccesses. The value should be larger than max_clients * 2
node.max_portsMax 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

# /etc/init.d/emqttd

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

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

# export HOME=/root

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

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

restart() {

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


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

boot test:

service emqttd start


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