yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

getstarted

This commit is contained in:
Feng Lee 2016-02-26 19:35:02 +08:00
parent 09ab8bc446
commit f63b826521
1 changed files with 90 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
docs/source/getstarted.rst
View File

@ -13,7 +13,7 @@ emqttd(Erlang MQTT Broker) is an open source MQTT broker written in Erlang/OTP.
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:
Highlights of the emqttd broker:
* Full MQTT V3.1/3.1.1 Protocol Specifications Support
* Easy to Install - Quick Install on Linux, FreeBSD, Mac and Windows
@ -21,7 +21,6 @@ The emqttd broker is:
* Easy to extend - Hooks and plugins to customize or extend the broker
* Pluggable Authentication - LDAP, MySQL, PostgreSQL, Redis Authentication Plugins
--------
Features
--------
@ -47,7 +46,6 @@ Features
* Extensible architecture with Hooks, Modules and Plugins
* Passed eclipse paho interoperability tests
-----------
Quick Start
-----------
@ -55,7 +53,9 @@ Quick Start
Download and Install
--------------------
Download binary package for Linux, Mac, FreeBSD and Windows platform from http://emqtt.io/downloads.
The emqttd broker is cross-platform, could be deployed on Linux, Mac, FreeBSD, Windows and Raspberry Pi.
Download binary package from: http://emqtt.io/downloads. Installing on Mac, For example:
.. code:: console
@ -71,7 +71,7 @@ Download binary package for Linux, Mac, FreeBSD and Windows platform from http:/
./bin/emqttd stop
Installing from Source
-----------------------
----------------------
.. NOTE:: emqttd requires Erlang R17+ to build.
@ -81,39 +81,56 @@ Installing from Source
cd emqttd && make && make dist
--------------------
-------------
Web Dashboard
--------------------
-------------
A Web Dashboard will be loaded automatically when the emqttd broker is started successfully.
The Dashboard helps to 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 emqttd broker could be extended by modules and plugins.
The emqttd broker could be extended by Modules and Plugins.
The authentication and ACL mechanism is usally implemented by a module or plugin.
Modules
-------
+-------------------------+-----------------------------------+
| emqttd_auth_clientid | ClientId认证 |
+-------------------------+-----------------------------------+
| emqttd_auth_username | 用户名密码认证 |
+-------------------------+-----------------------------------+
| emqttd_auth_ldap | LDAP认证 |
+-------------------------+-----------------------------------+
| emqttd_mod_presence | 客户端上下线状态消息发布 |
+-------------------------+-----------------------------------+
| emqttd_mod_subscription | 客户端上线自动主题订阅 |
+-------------------------+-----------------------------------+
| emqttd_mod_rewrite | 重写客户端订阅主题(Topic) |
+-------------------------+-----------------------------------+
+-------------------------+--------------------------------------------+
| emqttd_auth_clientid | Authentication with ClientId |
+-------------------------+--------------------------------------------+
| emqttd_auth_username | Authentication with Username and Password |
+-------------------------+--------------------------------------------+
| emqttd_auth_ldap | Authentication with LDAP |
+-------------------------+--------------------------------------------+
| emqttd_mod_presence | Publish presence message to $SYS topics |
| | when client connected or disconnected |
+-------------------------+--------------------------------------------+
| emqttd_mod_subscription | Subscribe topics automatically when client |
| | connected |
+-------------------------+--------------------------------------------+
| emqttd_mod_rewrite | Topics rewrite like HTTP rewrite module |
+-------------------------+--------------------------------------------+
扩展模块通过'etc/emqttd.config'配置文件的auth, modules段落启用。
Configure the 'auth', 'module' paragraph in 'etc/emqttd.config' to enable a module.
例如启用用户名密码认证::
Enable 'emqttd_auth_username' module::
{access, [
%% Authetication. Anonymous Default
@ -123,7 +140,7 @@ Modules
...
启用客户端状态发布模块::
Enable 'emqttd_mod_presence' module::
{modules, [
%% Client presence management module.
@ -131,71 +148,70 @@ Modules
{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优化调测插件 |
+-------------------------+-----------------------------------+
A plugin is an Erlang application to extend the emqttd broker.
扩展插件通过'bin/emqttd_ctl'管理命令行，加载启动运行。
+----------------------------+-----------------------------------+
| `emqttd_plugin_template`_ | Plugin template and demo |
+----------------------------+-----------------------------------+
| `emqttd_dashboard`_ | Web Dashboard |
+----------------------------+-----------------------------------+
| `emqttd_plugin_mysql`_ | Authentication with MySQL |
+----------------------------+-----------------------------------+
| `emqttd_plugin_pgsql`_ | Authentication with PostgreSQL |
+----------------------------+-----------------------------------+
| `emqttd_plugin_redis`_ | Authentication with Redis |
+----------------------------+-----------------------------------+
| `emqttd_plugin_mongo`_ | Authentication with MongoDB |
+----------------------------+-----------------------------------+
| `emqttd_stomp`_ | STOMP Protocol Plugin |
+----------------------------+-----------------------------------+
| `emqttd_sockjs`_ | SockJS(Stomp) Plugin |
+----------------------------+-----------------------------------+
| `emqttd_recon`_ | Recon Plugin |
+----------------------------+-----------------------------------+
例如启用PostgreSQL认证插件::
A plugin could be enabled by 'bin/emqttd_ctl plugins load' command.
For example, enable 'emqttd_plugin_pgsql' plugin::
./bin/emqttd_ctl plugins load emqttd_plugin_pgsql
----------------------------------
-----------------------
One million Connections
----------------------------------
-----------------------
Latest release of the emqttd broker is scaling to 1.3 million MQTT connections on a 12 Core, 32G CentOS server.
.. NOTE::
emqttd消息服务器默认设置，允许最大客户端连接是512，因为大部分操作系统'ulimit -n'限制为1024。
The emqttd broker only allows 512 concurrent connections by default, for 'ulimit -n' limit is 1024 on most platform.
emqttd消息服务器当前版本，连接压力测试到130万线，8核心/32G内存的CentOS云服务器。
操作系统内核参数、TCP协议栈参数、Erlang虚拟机参数、emqttd最大允许连接数设置简述如下：
We need tune the OS Kernel, TCP Stack, Erlang VM and emqttd broker for one million connections benchmark.
Linux Kernel Parameters
-----------------------
# 2M - 系统所有进程可打开的文件数量::
.. code::
# 2M:
sysctl -w fs.file-max=2097152
sysctl -w fs.nr_open=2097152
# 1M - 系统允许当前进程打开的文件数量::
# 1M:
ulimit -n 1048576
TCP Stack Parameters
-----------------------
# backlog - Socket监听队列长度::
--------------------
.. code::
# backlog
sysctl -w net.core.somaxconn=65536
Erlang VM
-----------------
---------
emqttd/etc/vm.args::
@ -210,8 +226,8 @@ emqttd/etc/vm.args::
-env ERTS_MAX_PORTS 1048576
emqttd.config
-----------------
emqttd broker
-------------
emqttd/etc/emqttd.config::
@ -239,6 +255,7 @@ Test Client
sysctl -w net.ipv4.ip_local_port_range="500 65535"
echo 1000000 > /proc/sys/fs/nr_open
ulimit -n 100000
----------------------
emqtt Client Libraries
@ -261,3 +278,13 @@ GitHub: https://github.com/emqtt
.. _CocoaMQTT: https://github.com/emqtt/CocoaMQTT
.. _QMQTT: https://github.com/emqtt/qmqtt
.. _emqttd_plugin_template: https://github.com/emqtt/emqttd_plugin_template
.. _emqttd_dashboard: https://github.com/emqtt/emqttd_dashboard
.. _emqttd_plugin_mysql: https://github.com/emqtt/emqttd_plugin_mysql
.. _emqttd_plugin_pgsql: https://github.com/emqtt/emqttd_plugin_pgsql
.. _emqttd_plugin_redis: https://github.com/emqtt/emqttd_plugin_redis
.. _emqttd_plugin_mongo: https://github.com/emqtt/emqttd_plugin_mongo
.. _emqttd_stomp: https://github.com/emqtt/emqttd_stomp
.. _emqttd_sockjs: https://github.com/emqtt/emqttd_sockjs
.. _emqttd_recon: https://github.com/emqtt/emqttd_recon