Installation

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

Note

Linux, FreeBSD Recommended.

Download Packages

Download binary packages from: http://emqtt.io/downloads

Debian http://emqtt.io/downloads/latest/debian
Ubuntu http://emqtt.io/downloads/latest/ubuntu
CentOS http://emqtt.io/downloads/latest/centos
FreeBSD http://emqtt.io/downloads/latest/freebsd
Mac OS X http://emqtt.io/downloads/latest/macosx
Windows http://emqtt.io/downloads/latest/windows

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

For example: emqttd-centos64-1.1-beta-20160601.zip

Installing on Linux

Download CentOS Package from: http://emqtt.io/downloads/latest/centos, and then unzip:

unzip emqttd-centos64-1.1-beta-20160601.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@127.0.0.1'
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 0.0.0.0:18083 with 4 acceptors.
mqtt listen on 0.0.0.0:1883 with 16 acceptors.
mqtts listen on 0.0.0.0:8883 with 4 acceptors.
http listen on 0.0.0.0:8083 with 4 acceptors.
Erlang MQTT Broker 1.1 is running now
Eshell V6.4  (abort with ^G)
(emqttd@127.0.0.1)1>

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

Start the broker in daemon mode:

./bin/emqttd start

The boot logs in log/emqttd_sasl.log file.

Check the running status of the broker:

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

Or check the status by URL:

http://localhost:8083/status

Stop the broker:

./bin/emqttd stop

Installing on FreeBSD

Download FreeBSD Package from: http://emqtt.io/downloads/latest/freebsd

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: http://emqtt.io/downloads/latest/macosx

Configure ‘lager’ log level in ‘etc/emqttd.config’, all MQTT messages recevied/sent will be printed on console:

{lager, [
    ...
    {handlers, [
        {lager_console_backend, info},
        ...
    ]}
]},

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

Installing on Windows

Download Package from: http://emqtt.io/downloads/latest/windows.

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.

Install emqttd serivce:

.\bin\emqttd install

Start emqttd serivce:

.\bin\emqttd start

Stop emqttd serivce:

.\bin\emqttd stop

Uninstall emqttd service:

.\bin\emqttd uninstall

Warning

‘./bin/emqttd_ctl’ command line cannot work on Windows.

Installing From Source

The emqttd broker requires Erlang/OTP R17+ and git client to build:

Install Erlang: http://www.erlang.org/

Install Git Client: http://www.git-scm.com/

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/emqttd.git

cd emqttd

make && make dist

The binary package output in folder:

rel/emqttd

TCP Ports Used

1883 MQTT Port
8883 MQTT Over SSL Port
8083 MQTT(WebSocket), HTTP API Port
18083 Dashboard Port

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

{listeners, [
    {mqtt, 1883, [
        ...
    ]},

    {mqtts, 8883, [
        ...
    ]},
    %% HTTP and WebSocket Listener
    {http, 8083, [
        ...
    ]}
]},

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

Quick Setup

Two main configuration files of the emqttd broker:

etc/vm.args Erlang VM Arguments
etc/emqttd.config emqttd broker Config

Two important parameters in etc/vm.args:

+P Max number of Erlang proccesses. A MQTT client consumes two proccesses. The value should be larger than max_clients * 2
+Q Max number of Erlang Ports. A MQTT client consumes one port. The value should be larger than max_clients.

Note

+Q > maximum number of allowed concurrent clients +P > maximum number of allowed concurrent clients * 2

The maximum number of allowed MQTT clients:

{listeners, [
    {mqtt, 1883, [
        %% TCP Acceptor Pool
        {acceptors, 16},

        %% Maximum number of concurrent MQTT clients
        {max_clients, 8192},

        ...

    ]},

/etc/init.d/emqttd

#!/bin/sh
#
# 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() {
    stop
    start
}

case "$1" in
    start)
        start
        ;;
    stop)
        stop
        ;;
    restart)
        restart
        ;;
    *)
        echo $"Usage: $0 {start|stop}"
        RETVAL=2
esac

chkconfig:

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

boot test:

service emqttd start

Note

## erlexec: HOME must be set uncomment ‘# export HOME=/root’ if “HOME must be set” error.