emqx4.3/docs/source/getstarted.rst

.. _getstarted:

===========
Get Started
===========

--------
Overview
--------

emqttd(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 anextremely lightweight publish/subscribe messaging protocol powering IoT, M2M applications.

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

The emqttd broker is:

* 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
* 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
* STOMP over SockJS
* $SYS/# Topics
* Client Authentication with clientId, ipaddress
* Client Authentication with username, password
* Client ACL control with ipaddress, clientid, username
* LDAP, Redis, MySQL, PostgreSQL authentication
* 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


-----------
Quick Start
-----------

Download and Install
--------------------

Download binary package for Linux, Mac, FreeBSD and Windows platform from http://emqtt.io/downloads.

.. code:: console

    unzip emqttd-macosx-0.16.0-beta-20160216.zip && cd emqttd

    # Start emqttd
    ./bin/emqttd start

    # Check Status
    ./bin/emqttd_ctl status

    # Stop emqttd
    ./bin/emqttd stop

Installing from Source
-----------------------

.. NOTE:: emqttd requires Erlang R17+ to build.

.. code:: console

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

    cd emqttd && make && make dist

-------------
Web Dashboard
-------------

.. image:: ./_static/images/dashboard.png


-------------------
Modules and Plugins
-------------------

The emqttd broker could be extended by modules and plugins.

Modules
-------

+-------------------------+-----------------------------------+
| emqttd_auth_clientid    | ClientId认证                      |
+-------------------------+-----------------------------------+
| emqttd_auth_username    | 用户名密码认证                    |
+-------------------------+-----------------------------------+
| emqttd_auth_ldap        | LDAP认证                          |
+-------------------------+-----------------------------------+
| emqttd_mod_presence     | 客户端上下线状态消息发布          |
+-------------------------+-----------------------------------+
| emqttd_mod_subscription | 客户端上线自动主题订阅            |
+-------------------------+-----------------------------------+
| emqttd_mod_rewrite      | 重写客户端订阅主题(Topic)         |
+-------------------------+-----------------------------------+

扩展模块通过'etc/emqttd.config'配置文件的auth, modules段落启用。

例如启用用户名密码认证::

    {access, [
        %% Authetication. Anonymous Default
        {auth, [
            %% Authentication with username, password
            {username, []},

            ...

启用客户端状态发布模块::

    {modules, [
        %% Client presence management module.
        %% Publish messages when client connected or disconnected
        {presence, [{qos, 0}]}

Plugins
--------

+-------------------------+-----------------------------------+
| emqttd_plugin_template  | 插件模版与演示代码                |
+-------------------------+-----------------------------------+
| emqttd_dashboard        | Web管理控制台，默认加载           |
+-------------------------+-----------------------------------+
| emqttd_plugin_mysql     | MySQL认证插件                     |
+-------------------------+-----------------------------------+
| emqttd_plugin_pgsql     | PostgreSQL认证插件                |
+-------------------------+-----------------------------------+
| emqttd_plugin_redis     | Redis认证插件                     |
+-------------------------+-----------------------------------+
| emqttd_plugin_mongo     | MongoDB认证插件                   |
+-------------------------+-----------------------------------+
| emqttd_stomp            | Stomp协议插件                     |
+-------------------------+-----------------------------------+
| emqttd_sockjs           | SockJS插件                        |
+-------------------------+-----------------------------------+
| emqttd_recon            | Recon优化调测插件                 |
+-------------------------+-----------------------------------+

扩展插件通过'bin/emqttd_ctl'管理命令行，加载启动运行。

例如启用PostgreSQL认证插件::

    ./bin/emqttd_ctl plugins load emqttd_plugin_pgsql

----------------------------------
One million Connections
----------------------------------

.. NOTE::

    emqttd消息服务器默认设置，允许最大客户端连接是512，因为大部分操作系统'ulimit -n'限制为1024。

emqttd消息服务器当前版本，连接压力测试到130万线，8核心/32G内存的CentOS云服务器。

操作系统内核参数、TCP协议栈参数、Erlang虚拟机参数、emqttd最大允许连接数设置简述如下：

Linux Kernel Parameters
-----------------------

# 2M - 系统所有进程可打开的文件数量::

.. code::

    sysctl -w fs.file-max=2097152
    sysctl -w fs.nr_open=2097152

# 1M - 系统允许当前进程打开的文件数量::

    ulimit -n 1048576

TCP Stack Parameters
-----------------------

# backlog - Socket监听队列长度::

.. code::

    sysctl -w net.core.somaxconn=65536

Erlang VM
-----------------

emqttd/etc/vm.args::

    ## max process numbers
    +P 2097152

    ## Sets the maximum number of simultaneously existing ports for this system
    +Q 1048576

    ## Increase number of concurrent ports/sockets
    -env ERL_MAX_PORTS 1048576

    -env ERTS_MAX_PORTS 1048576

emqttd.config
-----------------

emqttd/etc/emqttd.config::

        {mqtt, 1883, [
            %% Size of acceptor pool
            {acceptors, 64},

            %% Maximum number of concurrent clients
            {max_clients, 1000000},

            %% Socket Access Control
            {access, [{allow, all}]},

            %% Connection Options
            {connopts, [
                %% Rate Limit. Format is 'burst, rate', Unit is KB/Sec
                %% {rate_limit, "100,10"} %% 100K burst, 10K rate
            ]},
            ...

Test Client
-----------

.. code::

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

---------------------
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       |
+--------------------+----------------------+

.. _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