yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
emqx/docs/source/getstarted.rst

307 lines
10 KiB
ReStructuredText
Raw Permalink Blame History

.. _getstarted:
===========
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: http://emqtt.io/downloads.
Installing on Mac, for example:
.. code-block:: bash
unzip emqttd-macosx-v2.0-rc.2-20161019.zip && cd emqttd
# Start emqttd
./bin/emqttd start
# Check Status
./bin/emqttd_ctl status
# Stop emqttd
./bin/emqttd stop
Installing from Source
----------------------
.. NOTE:: emqttd broker requires Erlang R18+ to build since 1.1 release.
.. code-block:: bash
git clone https://github.com/emqtt/emqttd.git
cd emqttd && make && make dist
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 Address | http://localhost:18083 |
+------------------+---------------------------+
| Default User | admin |
+------------------+---------------------------+
| Default Password | public |
+------------------+---------------------------+
.. image:: ./_static/images/dashboard.png
-------------------
Modules and Plugins
-------------------
The *EMQ* broker could be extended by Modules ofr Plugins.
Modules
-------
+-------------------------+--------------------------------------------+
| emqttd_mod_retainer | Retained Messages Storage |
+-------------------------+--------------------------------------------+
| emqttd_mod_presence | Publish presence message to $SYS topics |
| | when client connected or disconnected |
+-------------------------+--------------------------------------------+
| emqttd_mod_subscription | Subscribe topics automatically when client |
| | connected |
+-------------------------+--------------------------------------------+
Modules could enabled by configuring 'etc/emq.conf':
.. code-block:: properties
##-------------------------------------------------------------------
## MQTT Modules
##-------------------------------------------------------------------
## Enable presence module
mqtt.module.presence = on
mqtt.module.presence.qos = 0
## Enable subscription module
mqtt.module.subscription = on
mqtt.module.subscription.topics = $client/%c=1,$user/%u=1
Plugins
-------
A plugin is an Erlang application to extend the *EMQ* broker.
+-------------------------+--------------------------------------------+
| `emq_auth_clientid`_ | Authentication with ClientId |
+-------------------------+--------------------------------------------+
| `emq_auth_username`_ | Authentication with Username and Password |
+-------------------------+--------------------------------------------+
| `emq_plugin_template`_ | Plugin template and demo |
+-------------------------+--------------------------------------------+
| `emq_dashboard`_ | Web Dashboard |
+-------------------------+--------------------------------------------+
| `emq_auth_ldap`_ | LDAP Auth Plugin |
+-------------------------+--------------------------------------------+
| `emq_auth_http`_ | Authentication/ACL with HTTP API |
+-------------------------+--------------------------------------------+
| `emq_auth_mysql` _ | Authentication with MySQL |
+-------------------------+--------------------------------------------+
| `emq_auth_pgsql`_ | Authentication with PostgreSQL |
+-------------------------+--------------------------------------------+
| `emq_auth_redis`_ | Authentication with Redis |
+-------------------------+--------------------------------------------+
| `emq_mod_rewrite`_ | Topics rewrite like HTTP rewrite module |
+-------------------------+--------------------------------------------+
| `emq_mod_mongo`_ | Authentication with MongoDB |
+-------------------------+--------------------------------------------+
| `emq_sn`_ | MQTT-SN Protocol Plugin |
+-------------------------+--------------------------------------------+
| `emq_coap`_ | CoAP Protocol Plugin |
+-------------------------+--------------------------------------------+
| `emq_stomp`_ | STOMP Protocol Plugin |
+-------------------------+--------------------------------------------+
| `emq_sockjs`_ | SockJS(Stomp) Plugin |
+-------------------------+--------------------------------------------+
| `emq_recon`_ | Recon Plugin |
+-------------------------+--------------------------------------------+
| `emq_reloader`_ | 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.
.. NOTE::
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
-----------------------
.. code-block:: bash
# 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
--------------------
.. code-block:: bash
# backlog
sysctl -w net.core.somaxconn=65536
Erlang VM
---------
emqttd/etc/emq.conf:
.. code-block:: properties
## 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':
.. code-block:: properties
## Size of acceptor pool
mqtt.listener.tcp.acceptors = 64
## Maximum number of concurrent clients
mqtt.listener.tcp.max_clients = 1000000
Test Client
-----------
.. code-block:: bash
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
+--------------------+----------------------+
| `emqttc`_ | Erlang MQTT Client |
+--------------------+----------------------+
| `emqtt_benchmark`_ | MQTT benchmark Tool |
+--------------------+----------------------+
| `CocoaMQTT`_ | Swift MQTT Client |
+--------------------+----------------------+
| `QMQTT`_ | QT MQTT Client |
+--------------------+----------------------+
Eclipse Paho: https://www.eclipse.org/paho/
MQTT.org: https://github.com/mqtt/mqtt.github.io/wiki/libraries
.. _emqttc: https://github.com/emqtt/emqttc
.. _emqtt_benchmark: https://github.com/emqtt/emqtt_benchmark
.. _CocoaMQTT: https://github.com/emqtt/CocoaMQTT
.. _QMQTT: https://github.com/emqtt/qmqtt
.. _emq_plugin_template: https://github.com/emqtt/emq_plugin_template
.. _emq_dashboard: https://github.com/emqtt/emq_dashboard
.. _emq_mod_rewrite: https://github.com/emqtt/emq_mod_rewrite
.. _emq_auth_clientid: https://github.com/emqtt/emq_auth_clientid
.. _emq_auth_username: https://github.com/emqtt/emq_auth_username
.. _emq_auth_ldap: https://github.com/emqtt/emq_auth_ldap
.. _emq_auth_http: https://github.com/emqtt/emq_auth_http
.. _emq_auth_mysql: https://github.com/emqtt/emq_plugin_mysql
.. _emq_auth_pgsql: https://github.com/emqtt/emq_plugin_pgsql
.. _emq_auth_redis: https://github.com/emqtt/emq_plugin_redis
.. _emq_auth_mongo: https://github.com/emqtt/emq_plugin_mongo
.. _emq_reloader: https://github.com/emqtt/emq_reloader
.. _emq_stomp: https://github.com/emqtt/emq_stomp
.. _emq_sockjs: https://github.com/emqtt/emq_sockjs
.. _emq_recon: https://github.com/emqtt/emq_recon
.. _emq_sn: https://github.com/emqtt/emq_sn
.. _emq_coap: https://github.com/emqtt/emq_coap
Reference in New Issue View Git Blame Copy Permalink