# Get Started

# Overview

EMQ (Erlang MQTT Broker) is an open source MQTT broker written in Erlang/OTP. Erlang/OTP is a concurrent, fault-tolerant, soft-realtime and distributed programming platform. MQTT is an extremely lightweight publish/subscribe messaging protocol powering IoT, M2M and Mobile applications.

The EMQ project is aimed to implement a scalable, distributed, extensible open-source MQTT broker for IoT, M2M and Mobile applications that hope to handle millions of concurrent MQTT clients.

Highlights of the EMQ broker:

  • Full MQTT V3.1/3.1.1 Protocol Specifications Support
  • Easy to Install - Quick Install on Linux, FreeBSD, Mac and Windows
  • Massively scalable - Scaling to 1 million connections on a single server
  • Cluster and Bridge Support
  • Easy to extend - Hooks and plugins to customize or extend the broker
  • Pluggable Authentication - LDAP, MySQL, PostgreSQL, Redis Authentication Plugins

# Features

  • Full MQTT V3.1/V3.1.1 protocol specification support
  • QoS0, QoS1, QoS2 Publish and Subscribe
  • Session Management and Offline Messages
  • Retained Message
  • Last Will Message
  • TCP/SSL Connection
  • MQTT Over WebSocket(SSL)
  • HTTP Publish API
  • STOMP protocol
  • MQTT-SN Protocol
  • CoAP Protocol
  • STOMP over SockJS
  • $SYS/# Topics
  • ClientID Authentication
  • IpAddress Authentication
  • Username and Password Authentication
  • Access control based on IpAddress, ClientID, Username
  • Authentication with LDAP, Redis, MySQL, PostgreSQL and HTTP API
  • Cluster brokers on several servers
  • Bridge brokers locally or remotely
  • mosquitto, RSMB bridge
  • Extensible architecture with Hooks, Modules and Plugins
  • Passed eclipse paho interoperability tests
  • Local subscription
  • Shared subscription

# Quick Start

# Download and Install

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

Download binary package from: https://www.emqx.io/downloads (opens new window) .

Installing on Mac, for example:

unzip emqttd-macosx-v2.0.zip && cd emqttd

# Start emqttd
./bin/emqttd start

# Check Status
./bin/emqttd_ctl status

# Stop emqttd
./bin/emqttd stop

# Installing from Source


The EMQ broker requires Erlang R18+ to build since 1.1 release.

git clone https://github.com/emqtt/emqttd.git

cd emqttd && make rel

cd rel/emqttd && ./bin/emqttd console

# Web Dashboard

A Web Dashboard will be loaded when the EMQ broker is started successfully.

The Dashboard helps check running status of the broker, monitor statistics and metrics of MQTT packets, query clients, sessions, topics and subscriptions.

Default Addresshttp://localhost:18083 (opens new window)
Default Useradmin
Default Passwordpublic


# Plugins

The EMQ broker could be extended by Plugins. A plugin is an Erlang application that adds extra feature to the EMQ broker:

emq_retainer (opens new window)Store Retained Messages
emq_dashboard (opens new window)Web Dashboard
emq_modules (opens new window)Presence, Subscription, Rewrite Modules
emq_auth_clientid (opens new window)Authentication with ClientId
emq_auth_username (opens new window)Authentication with Username and Password
emq_plugin_template (opens new window)Plugin template and demo
emq_auth_ldap (opens new window)LDAP Auth Plugin
emq_auth_http (opens new window)Authentication/ACL with HTTP API
emq_auth_mysql (opens new window)Authentication with MySQL
emq_auth_pgsql (opens new window)Authentication with PostgreSQL
emq_auth_redis (opens new window)Authentication with Redis
emq_auth_mongo (opens new window)Authentication with MongoDB
emq_sn (opens new window)MQTT-SN Protocol Plugin
emq_coap (opens new window)CoAP Protocol Plugin
emq_stomp (opens new window)STOMP Protocol Plugin
emq_sockjs (opens new window)SockJS(Stomp) Plugin
emq_recon (opens new window)Recon Plugin
emq_reloader (opens new window)Reloader Plugin

A plugin could be enabled by 'bin/emqttd_ctl plugins load' command.

For example, enable 'emq_auth_pgsql' plugin:

./bin/emqttd_ctl plugins load emq_auth_pgsql

# One Million Connections

Latest release of the EMQ broker is scaling to 1.3 million MQTT connections on a 12 Core, 32G CentOS server.


The emqttd broker only allows 512 concurrent connections by default, for 'ulimit -n' limit is 1024 on most platform.

We need tune the OS Kernel, TCP Stack, Erlang VM and emqttd broker for one million connections benchmark.

# Linux Kernel Parameters

# 2M:
sysctl -w fs.file-max=2097152
sysctl -w fs.nr_open=2097152
echo 2097152 > /proc/sys/fs/nr_open

# 1M:
ulimit -n 1048576

# TCP Stack Parameters

# backlog
sysctl -w net.core.somaxconn=65536

# Erlang VM


## Erlang Process Limit
node.process_limit = 2097152

## Sets the maximum number of simultaneously existing ports for this system
node.max_ports = 1048576

# Max Allowed Connections

emqttd/etc/emq.conf 'listeners':

## Size of acceptor pool
listener.tcp.acceptors = 64

## Maximum number of concurrent clients
listener.tcp.max_clients = 1000000

# Test Client

sysctl -w net.ipv4.ip_local_port_range="500 65535"
echo 1000000 > /proc/sys/fs/nr_open
ulimit -n 100000

# MQTT Client Libraries

GitHub: https://github.com/emqtt (opens new window)

emqttc (opens new window)Erlang MQTT Client
emqtt_benchmark (opens new window)MQTT benchmark Tool
CocoaMQTT (opens new window)Swift MQTT Client
QMQTT (opens new window)QT MQTT Client

Eclipse Paho: https://www.eclipse.org/paho/ (opens new window)

MQTT.org: https://github.com/mqtt/mqtt.github.io/wiki/libraries (opens new window)