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

2.0-rc.2 - update docs

This commit is contained in:
Feng 2016-10-19 20:50:01 +08:00
parent f84bb58f3f
commit 79176c5224
7 changed files with 1005 additions and 777 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/source/config.rst
View File

@ -21,7 +21,7 @@ The main configuration files of the EMQ broker are under 'etc/' folder:
EMQ 2.0 Config Syntax EMQ 2.0 Config Syntax
--------------------- ---------------------
The EMQ 2.0-rc.2 release integrated with `cuttlefish` library, and adopt a more user-friendly '`k = v` syntax for configuration file: The *EMQ* 2.0-rc.2 release integrated with `cuttlefish` library, and adopt a more user-friendly `k = v` syntax for configuration file:
.. code-block:: properties .. code-block:: properties
@ -64,7 +64,7 @@ OS Environment Variables
EMQ Node and Cookie EMQ Node and Cookie
------------------- -------------------
The node name and cookie of *EMQ* should be configured when clustering:: The node name and cookie of *EMQ* should be configured when clustering:
.. code-block:: properties .. code-block:: properties
@ -117,7 +117,7 @@ Configure and Optimize Erlang VM:
## node.dist_listen_min = 6000 ## node.dist_listen_min = 6000
## node.dist_listen_max = 6999 ## node.dist_listen_max = 6999
The two most important parameters in releases/2.0/vm.args: The two most important parameters for Erlang VM:
+--------------------------+---------------------------------------------------------------------------+ +--------------------------+---------------------------------------------------------------------------+
| node.process_limit | Max number of Erlang proccesses. A MQTT client consumes two proccesses. | | node.process_limit | Max number of Erlang proccesses. A MQTT client consumes two proccesses. |
@ -229,7 +229,7 @@ Define ACL rules in etc/acl.conf. The rules by default:
%% Allow all by default %% Allow all by default
{allow, all}. {allow, all}.
An ACL rule is an Erlang tuple. The Access control module of emqttd broker matches the rule one by one from top to bottom:: An ACL rule is an Erlang tuple. The Access control module of *EMQ* broker matches the rule one by one from top to bottom::
--------- --------- --------- --------- --------- ---------
Client -> | Rule1 | --nomatch--> | Rule2 | --nomatch--> | Rule3 | --> Default Client -> | Rule1 | --nomatch--> | Rule2 | --nomatch--> | Rule3 | --> Default
@ -433,7 +433,7 @@ MQTT Listeners
Configure the TCP listeners for MQTT, MQTT(SSL), HTTP and HTTPS Protocols. Configure the TCP listeners for MQTT, MQTT(SSL), HTTP and HTTPS Protocols.
The most important parameter is 'max_clients' - max concurrent clients allowed. The most important parameter for MQTT listener is `max_clients`: max concurrent clients allowed.
The TCP Ports occupied by the *EMQ* broker by default: The TCP Ports occupied by the *EMQ* broker by default:
@ -552,9 +552,9 @@ System Monitor
## Busy Dist Port ## Busy Dist Port
sysmon.busy_dist_port = true sysmon.busy_dist_port = true
---------------------------- --------------------------
Plugins' Configuration Files Plugin Configuration Files
---------------------------- --------------------------
+----------------------------------------+-----------------------------------+ +----------------------------------------+-----------------------------------+
| File | Description | | File | Description |

36
docs/source/design.rst
View File

@ -11,11 +11,11 @@ Design
Architecture Architecture
------------ ------------
The emqttd broker 1.0 is more like a network Switch or Router, not a traditional enterprise message queue. Compared to a network router that routes packets based on IP or MPLS label, the emqttd broker routes MQTT messages based on topic trie. The *EMQ* broker 1.0 is more like a network Switch or Router, not a traditional enterprise message queue. Compared to a network router that routes packets based on IP or MPLS label, the *EMQ* broker routes MQTT messages based on topic trie.
.. image:: _static/images/concept.png .. image:: _static/images/concept.png
The EMQ 2.0 seperated the Message Flow Plane and Monitor/Control Plane, the Architecture is something like:: The *EMQ* 2.0 seperated the Message Flow Plane and Monitor/Control Plane, the Architecture is something like::
Control Plane Control Plane
-------------------- --------------------
@ -200,7 +200,7 @@ The routing design follows two rules:
Authentication and ACL Authentication and ACL
---------------------- ----------------------
The emqttd broker supports an extensible authentication/ACL mechanism, which is implemented by emqttd_access_control, emqttd_auth_mod and emqttd_acl_mod modules. The *EMQ* broker supports an extensible authentication/ACL mechanism, which is implemented by emqttd_access_control, emqttd_auth_mod and emqttd_acl_mod modules.
emqttd_access_control module provides two APIs that help register/unregister auth or ACL module: emqttd_access_control module provides two APIs that help register/unregister auth or ACL module:
@ -241,18 +241,26 @@ The emqttd_auth_mod defines an Erlang behaviour for authentication module:
-endif. -endif.
The authentication modules implemented by default: The authentication modules implemented by plugins:
+-----------------------+--------------------------------+ +-----------------------+--------------------------------+
| Module | Authentication | | Plugin | Authentication |
+-----------------------+--------------------------------+ +-----------------------+--------------------------------+
| emqttd_auth_username | Username and Password | | emq_auth_username | Username and Password |
+-----------------------+--------------------------------+ +-----------------------+--------------------------------+
| emqttd_auth_clientid | ClientID | | emq_auth_clientid | ClientID and Password |
+-----------------------+--------------------------------+ +-----------------------+--------------------------------+
| emqttd_auth_ldap | LDAP | | emq_auth_ldap | LDAP |
+-----------------------+--------------------------------+ +-----------------------+--------------------------------+
| emqttd_auth_anonymous | Anonymous | | emq_auth_http | HTTP API |
+-----------------------+--------------------------------+
| emq_auth_mysql | MySQL |
+-----------------------+--------------------------------+
| emq_auth_pgsql | PostgreSQL |
+-----------------------+--------------------------------+
| emq_auth_redis | Redis |
+-----------------------+--------------------------------+
| emq_auth_mongo | MongoDB |
+-----------------------+--------------------------------+ +-----------------------+--------------------------------+
Authorization(ACL) Authorization(ACL)
@ -290,7 +298,7 @@ The emqttd_acl_mod defines an Erlang behavihour for ACL module:
-endif. -endif.
emqttd_acl_internal implements the default ACL based on etc/acl.config file: emqttd_acl_internal implements the default ACL based on etc/acl.conf file:
.. code-block:: erlang .. code-block:: erlang
@ -326,9 +334,9 @@ emqttd_acl_internal implements the default ACL based on etc/acl.config file:
Hooks Design Hooks Design
------------ ------------
The emqttd broker implements a simple but powerful hooks mechanism to help users develop plugin. The broker would run the hooks when a client is connected/disconnected, a topic is subscribed/unsubscribed or a MQTT message is published/delivered/acked. The *EMQ* broker implements a simple but powerful hooks mechanism to help users develop plugin. The broker would run the hooks when a client is connected/disconnected, a topic is subscribed/unsubscribed or a MQTT message is published/delivered/acked.
Hooks defined by the emqttd 1.0 broker: Hooks defined by the *EMQ* 2.0 broker:
+------------------------+------------------------------------------------------+ +------------------------+------------------------------------------------------+
| Hook | Description | | Hook | Description |
@ -352,7 +360,7 @@ Hooks defined by the emqttd 1.0 broker:
| client.disconnected | Run when client disconnected from broker | | client.disconnected | Run when client disconnected from broker |
+------------------------+------------------------------------------------------+ +------------------------+------------------------------------------------------+
The emqttd broker uses the `Chain-of-responsibility_pattern`_ to implement hook mechanism. The callback functions registered to hook will be executed one by one:: The *EMQ* broker uses the `Chain-of-responsibility_pattern`_ to implement hook mechanism. The callback functions registered to hook will be executed one by one::
-------- ok | {ok, NewAcc} -------- ok | {ok, NewAcc} -------- -------- ok | {ok, NewAcc} -------- ok | {ok, NewAcc} --------
(Args, Acc) --> | Fun1 | -------------------> | Fun2 | -------------------> | Fun3 | --> {ok, Acc} | {stop, Acc} (Args, Acc) --> | Fun1 | -------------------> | Fun2 | -------------------> | Fun3 | --> {ok, Acc} | {stop, Acc}
@ -455,7 +463,7 @@ The `emqttd_plugin_template`_ project provides the examples for hook usage:
Plugin Design Plugin Design
------------- -------------
Plugin is a normal erlang application that can be started/stopped dynamically by a running emqttd broker. Plugin is a normal erlang application that can be started/stopped dynamically by a running *EMQ* broker.
emqttd_plugins Module emqttd_plugins Module
--------------------- ---------------------

192
docs/source/getstarted.rst
View File

@ -9,11 +9,11 @@ Get Started
Overview 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 an extremely lightweight publish/subscribe messaging protocol powering IoT, M2M and Mobile applications. *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 emqttd 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. 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 emqttd broker: Highlights of the *EMQ* broker:
* Full MQTT V3.1/3.1.1 Protocol Specifications Support * Full MQTT V3.1/3.1.1 Protocol Specifications Support
* Easy to Install - Quick Install on Linux, FreeBSD, Mac and Windows * Easy to Install - Quick Install on Linux, FreeBSD, Mac and Windows
@ -49,6 +49,8 @@ Features
* mosquitto, RSMB bridge * mosquitto, RSMB bridge
* Extensible architecture with Hooks, Modules and Plugins * Extensible architecture with Hooks, Modules and Plugins
* Passed eclipse paho interoperability tests * Passed eclipse paho interoperability tests
* Local subscription
* Shared subscription
----------- -----------
Quick Start Quick Start
@ -57,7 +59,7 @@ Quick Start
Download and Install Download and Install
-------------------- --------------------
The emqttd broker is cross-platform, which could be deployed on Linux, FreeBSD, Mac, Windows and even Raspberry Pi. 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. Download binary package from: http://emqtt.io/downloads.
@ -65,7 +67,7 @@ Installing on Mac, for example:
.. code-block:: bash .. code-block:: bash
unzip emqttd-macosx-v2.0-rc.2-20160910.zip && cd emqttd unzip emqttd-macosx-v2.0-rc.2-20161019.zip && cd emqttd
# Start emqttd # Start emqttd
./bin/emqttd start ./bin/emqttd start
@ -93,7 +95,7 @@ Installing from Source
Web Dashboard Web Dashboard
------------- -------------
A Web Dashboard will be loaded when the emqttd broker is started successfully. 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. The Dashboard helps check running status of the broker, monitor statistics and metrics of MQTT packets, query clients, sessions, topics and subscriptions.
@ -111,15 +113,13 @@ The Dashboard helps check running status of the broker, monitor statistics and m
Modules and Plugins Modules and Plugins
------------------- -------------------
The Authentication and Authorization(ACL) are usually implemented by a Module or Plugin. The *EMQ* broker could be extended by Modules ofr Plugins.
Modules Modules
------- -------
+-------------------------+--------------------------------------------+ +-------------------------+--------------------------------------------+
| emqttd_auth_clientid | Authentication with ClientId | | emqttd_mod_retainer | Retained Messages Storage |
+-------------------------+--------------------------------------------+
| emqttd_auth_username | Authentication with Username and Password |
+-------------------------+--------------------------------------------+ +-------------------------+--------------------------------------------+
| emqttd_mod_presence | Publish presence message to $SYS topics | | emqttd_mod_presence | Publish presence message to $SYS topics |
| | when client connected or disconnected | | | when client connected or disconnected |
@ -127,68 +127,77 @@ Modules
| emqttd_mod_subscription | Subscribe topics automatically when client | | emqttd_mod_subscription | Subscribe topics automatically when client |
| | connected | | | connected |
+-------------------------+--------------------------------------------+ +-------------------------+--------------------------------------------+
| emqttd_mod_rewrite | Topics rewrite like HTTP rewrite module |
+-------------------------+--------------------------------------------+
Configure the 'auth', 'module' paragraph in 'etc/emqttd.config' to enable a module. Modules could enabled by configuring 'etc/emq.conf':
Enable 'emqttd_auth_username' module: .. code-block:: properties
.. code-block:: erlang ##-------------------------------------------------------------------
## MQTT Modules
##-------------------------------------------------------------------
%% Authentication with username, password ## Enable presence module
{auth, username, [{passwd, "etc/modules/passwd.conf"}]}. mqtt.module.presence = on
Enable 'emqttd_mod_presence' module: mqtt.module.presence.qos = 0
.. code-block:: erlang ## Enable subscription module
mqtt.module.subscription = on
%% Client presence management module. Publish presence messages when mqtt.module.subscription.topics = $client/%c=1,$user/%u=1
%% client connected or disconnected.
{module, presence, [{qos, 0}]}.
Plugins Plugins
------- -------
A plugin is an Erlang application to extend the emqttd broker. A plugin is an Erlang application to extend the *EMQ* broker.
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_plugin_template`_ | Plugin template and demo | | `emq_auth_clientid`_ | Authentication with ClientId |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_dashboard`_ | Web Dashboard | | `emq_auth_username`_ | Authentication with Username and Password |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_auth_ldap`_ | LDAP Auth Plugin | | `emq_plugin_template`_ | Plugin template and demo |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_auth_http`_ | Authentication/ACL with HTTP API | | `emq_dashboard`_ | Web Dashboard |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_auth_mysql` _ | Authentication with MySQL | | `emq_auth_ldap`_ | LDAP Auth Plugin |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_auth_pgsql`_ | Authentication with PostgreSQL | | `emq_auth_http`_ | Authentication/ACL with HTTP API |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_auth_redis`_ | Authentication with Redis | | `emq_auth_mysql` _ | Authentication with MySQL |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_plugin_mongo`_ | Authentication with MongoDB | | `emq_auth_pgsql`_ | Authentication with PostgreSQL |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_sn`_ | MQTT-SN Protocol Plugin | | `emq_auth_redis`_ | Authentication with Redis |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_stomp`_ | STOMP Protocol Plugin | | `emq_mod_rewrite`_ | Topics rewrite like HTTP rewrite module |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_sockjs`_ | SockJS(Stomp) Plugin | | `emq_plugin_mongo`_ | Authentication with MongoDB |
+----------------------------+-----------------------------------+ +----------------------------+--------------------------------------------+
| `emqttd_recon`_ | Recon Plugin | | `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. A plugin could be enabled by 'bin/emqttd_ctl plugins load' command.
For example, enable 'emqttd_auth_pgsql' plugin:: For example, enable 'emqttd_auth_pgsql' plugin::
./bin/emqttd_ctl plugins load emqttd_auth_pgsql ./bin/emqttd_ctl plugins load emq_auth_pgsql
----------------------- -----------------------
One Million Connections One Million Connections
----------------------- -----------------------
Latest release of emqttd broker is scaling to 1.3 million MQTT connections on a 12 Core, 32G CentOS server. Latest release of the *EMQ* broker is scaling to 1.3 million MQTT connections on a 12 Core, 32G CentOS server.
.. NOTE:: .. NOTE::
@ -220,43 +229,28 @@ TCP Stack Parameters
Erlang VM Erlang VM
--------- ---------
emqttd/release/2.0/vm.args:: emqttd/etc/emq.conf:
## max process numbers .. code-block:: properties
+P 2097152
## Erlang Process Limit
node.process_limit = 2097152
## Sets the maximum number of simultaneously existing ports for this system ## Sets the maximum number of simultaneously existing ports for this system
+Q 1048576 node.max_ports = 1048576
## Increase number of concurrent ports/sockets Max Allowed Connections
-env ERL_MAX_PORTS 1048576 -----------------------
-env ERTS_MAX_PORTS 1048576 emqttd/etc/emq.conf 'listeners':
emqttd broker .. code-block:: properties
-------------
emqttd/etc/emqttd.conf: ## Size of acceptor pool
mqtt.listener.tcp.acceptors = 64
.. code-block:: erlang ## Maximum number of concurrent clients
mqtt.listener.tcp.max_clients = 1000000
{listener, 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 Test Client
----------- -----------
@ -283,22 +277,30 @@ GitHub: https://github.com/emqtt
| `QMQTT`_ | QT MQTT Client | | `QMQTT`_ | QT MQTT Client |
+--------------------+----------------------+ +--------------------+----------------------+
.. _emqttc: https://github.com/emqtt/emqttc 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 .. _emqtt_benchmark: https://github.com/emqtt/emqtt_benchmark
.. _CocoaMQTT: https://github.com/emqtt/CocoaMQTT .. _CocoaMQTT: https://github.com/emqtt/CocoaMQTT
.. _QMQTT: https://github.com/emqtt/qmqtt .. _QMQTT: https://github.com/emqtt/qmqtt
.. _emqttd_plugin_template: https://github.com/emqtt/emqttd_plugin_template .. _emq_plugin_template: https://github.com/emqtt/emqttd_plugin_template
.. _emqttd_dashboard: https://github.com/emqtt/emqttd_dashboard .. _emq_dashboard: https://github.com/emqtt/emqttd_dashboard
.. _emqttd_auth_ldap: https://github.com/emqtt/emqttd_auth_ldap .. _emq_mod_rewrite: https://github.com/emqtt/emq_mod_rewrite
.. _emqttd_auth_http: https://github.com/emqtt/emqttd_auth_http .. _emq_auth_clientid: https://github.com/emqtt/emq_auth_clientid
.. _emqttd_auth_mysql: https://github.com/emqtt/emqttd_plugin_mysql .. _emq_auth_username: https://github.com/emqtt/emq_auth_username
.. _emqttd_auth_pgsql: https://github.com/emqtt/emqttd_plugin_pgsql .. _emq_auth_ldap: https://github.com/emqtt/emqttd_auth_ldap
.. _emqttd_auth_redis: https://github.com/emqtt/emqttd_plugin_redis .. _emq_auth_http: https://github.com/emqtt/emqttd_auth_http
.. _emqttd_auth_mongo: https://github.com/emqtt/emqttd_plugin_mongo .. _emq_auth_mysql: https://github.com/emqtt/emqttd_plugin_mysql
.. _emqttd_reloader: https://github.com/emqtt/emqttd_reloader .. _emq_auth_pgsql: https://github.com/emqtt/emqttd_plugin_pgsql
.. _emqttd_stomp: https://github.com/emqtt/emqttd_stomp .. _emq_auth_redis: https://github.com/emqtt/emqttd_plugin_redis
.. _emqttd_sockjs: https://github.com/emqtt/emqttd_sockjs .. _emq_auth_mongo: https://github.com/emqtt/emqttd_plugin_mongo
.. _emqttd_recon: https://github.com/emqtt/emqttd_recon .. _emq_reloader: https://github.com/emqtt/emqttd_reloader
.. _emqttd_sn: https://github.com/emqtt/emqttd_sn .. _emq_stomp: https://github.com/emqtt/emqttd_stomp
.. _emq_sockjs: https://github.com/emqtt/emqttd_sockjs
.. _emq_recon: https://github.com/emqtt/emqttd_recon
.. _emq_sn: https://github.com/emqtt/emqttd_sn
.. _emq_coap: https://github.com/emqtt/emqttd_coap

565
docs/source/guide.rst
View File

@ -9,43 +9,11 @@ User Guide
Authentication Authentication
-------------- --------------
The emqttd broker supports to authenticate MQTT clients with ClientID, Username/Password, IpAddress and even HTTP Cookies. The *EMQ* broker supports to authenticate MQTT clients with ClientID, Username/Password, IpAddress and even HTTP Cookies.
The authentication is provided by a list of extended modules, or MySQL, PostgreSQL and Redis Plugins. The authentication is provided by a list of plugins such as MySQL, PostgreSQL and Redis...
Enable an authentication module in etc/emqttd.config: If we enable several authentication plugins at the same time, the authentication process::
.. code-block:: erlang
%% Authentication and Authorization
{access, [
%% Authetication. Anonymous Default
{auth, [
%% Authentication with username, password
%{username, []},
%% Authentication with clientid
%{clientid, [{password, no}, {file, "etc/clients.config"}]},
%% Authentication with LDAP
% {ldap, [
% {servers, ["localhost"]},
% {port, 389},
% {timeout, 30},
% {user_dn, "uid=$u,ou=People,dc=example,dc=com"},
% {ssl, fasle},
% {sslopts, [
% {"certfile", "ssl.crt"},
% {"keyfile", "ssl.key"}]}
% ]},
%% Allow all
{anonymous, []}
]},
.. NOTE:: "%" comments the line.
If we enable several modules at the same time, the authentication process::
---------------- ---------------- ------------- ---------------- ---------------- -------------
Client --> | Username | -ignore-> | ClientID | -ignore-> | Anonymous | Client --> | Username | -ignore-> | ClientID | -ignore-> | Anonymous |
@ -54,77 +22,123 @@ If we enable several modules at the same time, the authentication process::
\|/ \|/ \|/ \|/ \|/ \|/
allow | deny allow | deny allow | deny allow | deny allow | deny allow | deny
The authentication plugins developed by emqttd: The authentication plugins implemented by default:
+---------------------------+---------------------------+ +---------------------------+---------------------------+
| Plugin | Description | | Plugin | Description |
+===========================+===========================+ +===========================+===========================+
| `emqttd_plugin_mysql`_ | MySQL Auth/ACL Plugin | | `emq_auth_clientid`_ | ClientId Auth Plugin |
+---------------------------+---------------------------+ +---------------------------+---------------------------+
| `emqttd_plugin_pgsql`_ | PostgreSQL Auth/ACL Plugin| | `emq_auth_username`_ | Username Auth Plugin |
+---------------------------+---------------------------+ +---------------------------+---------------------------+
| `emqttd_plugin_redis`_ | Redis Auth/ACL Plugin | | `emq_auth_ldap`_ | LDAP Auth Plugin |
+---------------------------+---------------------------+
| `emq_auth_http`_ | HTTP Auth/ACL Plugin |
+---------------------------+---------------------------+
| `emq_auth_mysql`_ | MySQL Auth/ACL Plugin |
+---------------------------+---------------------------+
| `emq_auth_pgsql`_ | Postgre Auth/ACL Plugin |
+---------------------------+---------------------------+
| `emq_auth_redis`_ | Redis Auth/ACL Plugin |
+---------------------------+---------------------------+
| `emq_auth_mongo`_ | MongoDB Auth/ACL Plugin |
+---------------------------+---------------------------+ +---------------------------+---------------------------+
.. NOTE:: If we load an authentication plugin, the authentication modules will be disabled. ---------------
Allow Anonymous
---------------
Username Configure etc/emq.conf to allow anonymous authentication:
--------
.. code-block:: properties
## Allow Anonymous authentication
mqtt.allow_anonymous = true
Username/Password
-----------------
Authenticate MQTT client with Username/Password:: Authenticate MQTT client with Username/Password::
{username, [{client1, "passwd1"}, {client1, "passwd2"}]}, Configure default users in etc/plugins/emq_auth_username.conf:
Two ways to add users: .. code-block:: properties
1. Configure username and plain password directly:: auth.username.$name=$password
{username, [{client1, "passwd1"}, {client1, "passwd2"}]}, Enable `emq_auth_username`_ plugin:
2. Add user by './bin/emqttd_ctl users' command:: .. code-block:: bash
./bin/emqttd_ctl plugins load emq_auth_username
Add user by './bin/emqttd_ctl users' command::
$ ./bin/emqttd_ctl users add <Username> <Password> $ ./bin/emqttd_ctl users add <Username> <Password>
ClientId ClientId
-------- --------
.. code-block:: erlang Authentication with MQTT ClientId.
{clientid, [{password, no}, {file, "etc/clients.config"}]}, Configure Client Ids in etc/plugins/emq_auth_clientid.conf:
Configure ClientIDs in etc/clients.config:: .. code-block:: properties
testclientid0 auth.clientid.$id=$password
testclientid1 127.0.0.1
testclientid2 192.168.0.1/24 Enable `emq_auth_clientid`_ plugin:
.. code-block:: bash
./bin/emqttd_ctl plugins load emq_auth_clientid
LDAP LDAP
---- ----
.. code-block:: erlang etc/plugins/emq_auth_ldap.conf:
{ldap, [ .. code-block:: properties
{servers, ["localhost"]},
{port, 389},
{timeout, 30},
{user_dn, "uid=$u,ou=People,dc=example,dc=com"},
{ssl, fasle},
{sslopts, [
{"certfile", "ssl.crt"},
{"keyfile", "ssl.key"}]}
]},
Anonymous auth.ldap.servers = 127.0.0.1
---------
Allow any client to connect to the broker:: auth.ldap.port = 389
{anonymous, []} auth.ldap.timeout = 30
auth.ldap.user_dn = uid=%u,ou=People,dc=example,dc=com
auth.ldap.ssl = false
Enable LDAP plugin::
./bin/emqttd_ctl plugins load emq_auth_ldap
HTTP
----
etc/plugins/emq_auth_http.conf:
.. code-block:: properties
## Variables: %u = username, %c = clientid, %a = ipaddress, %P = password, %t = topic
auth.http.auth_req = http://127.0.0.1:8080/mqtt/auth
auth.http.auth_req.method = post
auth.http.auth_req.params = clientid=%c,username=%u,password=%P
auth.http.super_req = http://127.0.0.1:8080/mqtt/superuser
auth.http.super_req.method = post
auth.http.super_req.params = clientid=%c,username=%u
Enable HTTP Plugin::
./bin/emqttd_ctl plugins load emq_auth_http
MySQL MySQL
----- -----
Authenticate against MySQL database. Support we create a mqtt_user table: Authenticate with MySQL database. Suppose that we create a mqtt_user table:
.. code-block:: sql .. code-block:: sql
@ -138,36 +152,46 @@ Authenticate against MySQL database. Support we create a mqtt_user table:
UNIQUE KEY `mqtt_username` (`username`) UNIQUE KEY `mqtt_username` (`username`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8; ) ENGINE=MyISAM DEFAULT CHARSET=utf8;
Configure the 'authquery' and 'password_hash' in emqttd_plugin_mysql/etc/plugin.config: Configure the 'auth_query' and 'password_hash' in etc/plugins/emq_auth_mysql.conf:
.. code-block:: erlang .. code-block:: properties
[ ## Mysql Server
auth.mysql.server = 127.0.0.1:3306
{emqttd_plugin_mysql, [ ## Mysql Pool Size
auth.mysql.pool = 8
... ## Mysql Username
## auth.mysql.username =
%% select password only ## Mysql Password
{authquery, "select password from mqtt_user where username = '%u' limit 1"}, ## auth.mysql.password =
%% hash algorithm: md5, sha, sha256, pbkdf2? ## Mysql Database
{password_hash, sha256}, auth.mysql.database = mqtt
... ## Variables: %u = username, %c = clientid
]} ## Authentication Query: select password only
]. auth.mysql.auth_query = select password from mqtt_user where username = '%u' limit 1
Load the plugin:: ## Password hash: plain, md5, sha, sha256, pbkdf2
auth.mysql.password_hash = sha256
./bin/emqttd_ctl plugins load emqttd_plugin_mysql ## %% Superuser Query
auth.mysql.super_query = select is_superuser from mqtt_user where username = '%u' limit 1
Enable MySQL plugin:
.. code-block:: bash
./bin/emqttd_ctl plugins load emq_plugin_mysql
PostgreSQL PostgreSQL
---------- ----------
Authenticate against PostgreSQL database. Create a mqtt_user table: Authenticate with PostgreSQL database. Create a mqtt_user table:
.. code-block:: sql .. code-block:: sql
@ -178,71 +202,152 @@ Authenticate against PostgreSQL database. Create a mqtt_user table:
salt character varying(40) salt character varying(40)
); );
Configure the 'authquery' and 'password_hash' in emqttd_plugin_pgsql/etc/plugin.config: Configure the 'auth_query' and 'password_hash' in etc/plugins/emq_auth_pgsql.conf:
.. code-block:: erlang .. code-block:: properties
[ ## Postgre Server
auth.pgsql.server = 127.0.0.1:5432
{emqttd_plugin_pgsql, [ auth.pgsql.pool = 8
... auth.pgsql.username = root
%% select password only #auth.pgsql.password =
{authquery, "select password from mqtt_user where username = '%u' limit 1"},
%% hash algorithm: md5, sha, sha256, pbkdf2? auth.pgsql.database = mqtt
{password_hash, sha256},
... auth.pgsql.encoding = utf8
]} auth.pgsql.ssl = false
].
Load the plugin:: ## Variables: %u = username, %c = clientid, %a = ipaddress
./bin/emqttd_ctl plugins load emqttd_plugin_pgsql ## Authentication Query: select password only
auth.pgsql.auth_query = select password from mqtt_user where username = '%u' limit 1
## Password hash: plain, md5, sha, sha256, pbkdf2
auth.pgsql.password_hash = sha256
## sha256 with salt prefix
## auth.pgsql.password_hash = salt sha256
## sha256 with salt suffix
## auth.pgsql.password_hash = sha256 salt
## Superuser Query
auth.pgsql.super_query = select is_superuser from mqtt_user where username = '%u' limit 1
Enable the plugin:
.. code-block:: bash
./bin/emqttd_ctl plugins load emq_plugin_pgsql
Redis Redis
----- -----
Authenticate against Redis. MQTT users could be stored in redis HASH, the key is "mqtt_user:<Username>". Authenticate with Redis. MQTT users could be stored in redis HASH, the key is "mqtt_user:<Username>".
Configure 'authcmd' and 'password_hash' in emqttd_plugin_redis/etc/plugin.config: Configure 'auth_cmd' and 'password_hash' in etc/plugins/emq_auth_redis.conf:
.. code-block:: erlang .. code-block:: properties
[ ## Redis Server
{emqttd_plugin_redis, [ auth.redis.server = 127.0.0.1:6379
... ## Redis Pool Size
auth.redis.pool = 8
%% HMGET mqtt_user:%u password ## Redis Database
{authcmd, ["HGET", "mqtt_user:%u", "password"]}, auth.redis.database = 0
%% Password hash algorithm: plain, md5, sha, sha256, pbkdf2? ## Redis Password
{password_hash, sha256}, ## auth.redis.password =
... ## Variables: %u = username, %c = clientid
]} ## Authentication Query Command
]. auth.redis.auth_cmd = HGET mqtt_user:%u password
Load the plugin:: ## Password hash: plain, md5, sha, sha256, pbkdf2
auth.redis.password_hash = sha256
./bin/emqttd_ctl plugins load emqttd_plugin_redis ## Superuser Query Command
auth.redis.super_cmd = HGET mqtt_user:%u is_superuser
Enable the plugin:
.. code-block:: bash
./bin/emqttd_ctl plugins load emq_auth_redis
MongoDB
-------
Create a `mqtt_user` collection::
{
username: "user",
password: "password hash",
is_superuser: boolean (true, false),
created: "datetime"
}
Configure `super_query`, `auth_query` in etc/plugins/emq_auth_mongo.conf:
.. code-block:: properties
## Mongo Server
auth.mongo.server = 127.0.0.1:27017
## Mongo Pool Size
auth.mongo.pool = 8
## Mongo User
## auth.mongo.user =
## Mongo Password
## auth.mongo.password =
## Mongo Database
auth.mongo.database = mqtt
## auth_query
auth.mongo.auth_query.collection = mqtt_user
auth.mongo.auth_query.password_field = password
auth.mongo.auth_query.password_hash = sha256
auth.mongo.auth_query.selector = username=%u
## super_query
auth.mongo.super_query.collection = mqtt_user
auth.mongo.super_query.super_field = is_superuser
auth.mongo.super_query.selector = username=%u
Enable the plugin:
.. code-block:: bash
./bin/emqttd_ctl plugins load emq_auth_mongo
.. _acl:
--- ---
ACL ACL
--- ---
The ACL of emqttd broker is responsbile for authorizing MQTT clients to publish/subscribe topics. The ACL of *EMQ* broker is responsbile for authorizing MQTT clients to publish/subscribe topics.
The ACL rules define:: The ACL rules define::
Allow|Deny Who Publish|Subscribe Topics Allow|Deny Who Publish|Subscribe Topics
Access Control Module of emqttd broker will match the rules one by one:: Access Control Module of *EMQ* broker will match the rules one by one::
--------- --------- --------- --------- --------- ---------
Client -> | Rule1 | --nomatch--> | Rule2 | --nomatch--> | Rule3 | --> Default Client -> | Rule1 | --nomatch--> | Rule2 | --nomatch--> | Rule3 | --> Default
@ -255,18 +360,16 @@ Access Control Module of emqttd broker will match the rules one by one::
Internal Internal
-------- --------
The default ACL of emqttd broker is implemented by an 'internal' module. The default ACL of *EMQ* broker is implemented by an 'internal' module.
Enable the 'internal' ACL module in etc/emqttd.config: Enable the 'internal' ACL module in etc/emq.conf:
.. code-block:: erlang .. code-block:: properties
{acl, [ ## Default ACL File
%% Internal ACL module mqtt.acl_file = etc/acl.conf
{internal, [{file, "etc/acl.config"}, {nomatch, allow}]}
]}
The ACL rules of 'internal' module are defined in 'etc/acl.config' file: The ACL rules of 'internal' module are defined in 'etc/acl.conf' file:
.. code-block:: erlang .. code-block:: erlang
@ -282,10 +385,26 @@ The ACL rules of 'internal' module are defined in 'etc/acl.config' file:
%% Allow all by default %% Allow all by default
{allow, all}. {allow, all}.
HTTP API
--------
ACL by HTTP API: https://github.com/emqtt/emq_auth_http
Configure etc/plugins/emq_auth_http.conf and enable the plugin:
.. code-block:: properties
## 'access' parameter: sub = 1, pub = 2
auth.http.acl_req = http://127.0.0.1:8080/mqtt/acl
auth.http.acl_req.method = get
auth.http.acl_req.params = access=%A,username=%u,clientid=%c,ipaddr=%a,topic=%t
auth.http.acl_nomatch = deny
MySQL MySQL
----- -----
ACL against MySQL database. The mqtt_acl table and default data: ACL with MySQL database. The `mqtt_acl` table and default data:
.. code-block:: sql .. code-block:: sql
@ -309,29 +428,20 @@ ACL against MySQL database. The mqtt_acl table and default data:
(6,1,'127.0.0.1',NULL,NULL,2,'#'), (6,1,'127.0.0.1',NULL,NULL,2,'#'),
(7,1,NULL,'dashboard',NULL,1,'$SYS/#'); (7,1,NULL,'dashboard',NULL,1,'$SYS/#');
Configure 'aclquery' and 'acl_nomatch' in emqttd_plugin_mysql/etc/plugin.config: Configure 'acl-query' and 'acl_nomatch' in etc/plugins/emq_auth_mysql.conf:
.. code-block:: erlang .. code-block:: properties
[ ## ACL Query Command
auth.mysql.acl_query = select allow, ipaddr, username, clientid, access, topic from mqtt_acl where ipaddr = '%a' or username = '%u' or username = '$all' or clientid = '%c'
{emqttd_plugin_mysql, [ ## ACL nomatch
auth.mysql.acl_nomatch = deny
...
%% comment this query, the acl will be disabled
{aclquery, "select allow, ipaddr, username, clientid, access, topic from mqtt_acl where ipaddr = '%a' or username = '%u' or username = '$all' or clientid = '%c'"},
%% If no rules matched, return...
{acl_nomatch, allow}
]}
].
PostgreSQL PostgreSQL
---------- ----------
ACL against PostgreSQL database. The mqtt_acl table and default data: ACL with PostgreSQL database. The mqtt_acl table and default data:
.. code-block:: sql .. code-block:: sql
@ -354,52 +464,66 @@ ACL against PostgreSQL database. The mqtt_acl table and default data:
(6,1,'127.0.0.1',NULL,NULL,2,'#'), (6,1,'127.0.0.1',NULL,NULL,2,'#'),
(7,1,NULL,'dashboard',NULL,1,'$SYS/#'); (7,1,NULL,'dashboard',NULL,1,'$SYS/#');
Configure 'aclquery' and 'acl_nomatch' in emqttd_plugin_pgsql/etc/plugin.config: Configure 'acl_query' and 'acl_nomatch' in etc/plugins/emq_auth_pgsql.conf:
.. code-block:: erlang .. code-block:: properties
[ ## ACL Query. Comment this query, the acl will be disabled.
auth.pgsql.acl_query = select allow, ipaddr, username, clientid, access, topic from mqtt_acl where ipaddr = '%a' or username = '%u' or username = '$all' or clientid = '%c'
{emqttd_plugin_pgsql, [ ## If no rules matched, return...
auth.pgsql.acl_nomatch = deny
...
%% Comment this query, the acl will be disabled. Notice: don't edit this query!
{aclquery, "select allow, ipaddr, username, clientid, access, topic from mqtt_acl
where ipaddr = '%a' or username = '%u' or username = '$all' or clientid = '%c'"},
%% If no rules matched, return...
{acl_nomatch, allow}
...
]}
].
Redis Redis
----- -----
ACL against Redis. We store ACL rules for each MQTT client in a Redis List by defualt. The key is "mqtt_acl:<Username>", the value is a list of "publish <Topic>", "subscribe <Topic>" or "pubsub <Topic>". ACL with Redis. The ACL rules are stored in a Redis HashSet::
Configure 'aclcmd' and 'acl_nomatch' in emqttd_plugin_redis/etc/plugin.config: HSET mqtt_acl:<username> topic1 1
HSET mqtt_acl:<username> topic2 2
HSET mqtt_acl:<username> topic3 3
.. code-block:: erlang Configure `acl_cmd` and `acl_nomatch` in etc/plugins/emq_auth_redis.conf:
[ .. code-block:: properties
{emqttd_plugin_redis, [
... ## ACL Query Command
auth.redis.acl_cmd = HGETALL mqtt_acl:%u
%% SMEMBERS mqtt_acl:%u ## ACL nomatch
{aclcmd, ["SMEMBERS", "mqtt_acl:%u"]}, auth.redis.acl_nomatch = deny
%% If no rules matched, return... MongoDB
{acl_nomatch, deny}, -------
... Store ACL Rules in a `mqtt_acl` collection:
]} .. code-block:: json
].
{
username: "username",
clientid: "clientid",
publish: ["topic1", "topic2", ...],
subscribe: ["subtop1", "subtop2", ...],
pubsub: ["topic/#", "topic1", ...]
}
For example, insert rules into `mqtt_acl` collection::
db.mqtt_acl.insert({username: "test", publish: ["t/1", "t/2"], subscribe: ["user/%u", "client/%c"]})
db.mqtt_acl.insert({username: "admin", pubsub: ["#"]})
Configure `acl_query` and `acl_nomatch` in etc/plugins/emq_auth_mongo.conf:
.. code-block:: properties
## acl_query
auth.mongo.acl_query.collection = mqtt_user
auth.mongo.acl_query.selector = username=%u
## acl_nomatch
auth.mongo.acl_nomatch = deny
---------------------- ----------------------
MQTT Publish/Subscribe MQTT Publish/Subscribe
@ -409,7 +533,7 @@ MQTT is a an extremely lightweight publish/subscribe messaging protocol desgined
.. image:: _static/images/pubsub_concept.png .. image:: _static/images/pubsub_concept.png
Install and start the emqttd broker, and then any MQTT client could connect to the broker, subscribe topics and publish messages. Install and start the *EMQ* broker, and then any MQTT client could connect to the broker, subscribe topics and publish messages.
MQTT Client Libraries: https://github.com/mqtt/mqtt.github.io/wiki/libraries MQTT Client Libraries: https://github.com/mqtt/mqtt.github.io/wiki/libraries
@ -420,67 +544,39 @@ For example, we use mosquitto_sub/pub commands::
MQTT V3.1.1 Protocol Specification: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html MQTT V3.1.1 Protocol Specification: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
MQTT Listener of emqttd broker is configured in etc/emqttd.config: MQTT Listener of emqttd broker is configured in etc/emq.conf:
.. code-block:: erlang .. code-block:: erlang
{mqtt, 1883, [ .. code-block:: properties
%% Size of acceptor pool
{acceptors, 16},
%% Maximum number of concurrent clients ## TCP Listener: 1883, 127.0.0.1:1883, ::1:1883
{max_clients, 512}, mqtt.listener.tcp = 1883
%% Socket Access Control ## Size of acceptor pool
{access, [{allow, all}]}, mqtt.listener.tcp.acceptors = 8
%% Connection Options ## Maximum number of concurrent clients
{connopts, [ mqtt.listener.tcp.max_clients = 1024
%% Rate Limit. Format is 'burst, rate', Unit is KB/Sec
%% {rate_limit, "100,10"} %% 100K burst, 10K rate
]},
%% Socket Options
{sockopts, [
%Set buffer if hight thoughtput
%{recbuf, 4096},
%{sndbuf, 4096},
%{buffer, 4096},
%{nodelay, true},
{backlog, 512}
]}
]},
MQTT(SSL) Listener, Default Port is 8883: MQTT(SSL) Listener, Default Port is 8883:
.. code-block:: erlang .. code-block:: properties
{mqtts, 8883, [ ## SSL Listener: 8883, 127.0.0.1:8883, ::1:8883
%% Size of acceptor pool mqtt.listener.ssl = 8883
{acceptors, 4},
%% Maximum number of concurrent clients ## Size of acceptor pool
{max_clients, 512}, mqtt.listener.ssl.acceptors = 4
%% Socket Access Control ## Maximum number of concurrent clients
{access, [{allow, all}]}, mqtt.listener.ssl.max_clients = 512
%% SSL certificate and key files
{ssl, [{certfile, "etc/ssl/ssl.crt"},
{keyfile, "etc/ssl/ssl.key"}]},
%% Socket Options
{sockopts, [
{backlog, 1024}
%{buffer, 4096},
]}
]},
---------------- ----------------
HTTP Publish API HTTP Publish API
---------------- ----------------
The emqttd broker provides a HTTP API to help application servers publish messages to MQTT clients. The *EMQ* broker provides a HTTP API to help application servers publish messages to MQTT clients.
HTTP API: POST http://host:8083/mqtt/publish HTTP API: POST http://host:8083/mqtt/publish
@ -524,30 +620,20 @@ The Dashboard plugin provides a test page for WebSocket::
Listener of WebSocket and HTTP Publish API is configured in etc/emqttd.config: Listener of WebSocket and HTTP Publish API is configured in etc/emqttd.config:
.. code-block:: erlang .. code-block:: properties
%% HTTP and WebSocket Listener ## HTTP and WebSocket Listener
{http, 8083, [ mqtt.listener.http = 8083
%% Size of acceptor pool mqtt.listener.http.acceptors = 4
{acceptors, 4}, mqtt.listener.http.max_clients = 64
%% Maximum number of concurrent clients
{max_clients, 64},
%% Socket Access Control
{access, [{allow, all}]},
%% Socket Options
{sockopts, [
{backlog, 1024}
%{buffer, 4096},
]}
]}
----------- -----------
$SYS Topics $SYS Topics
----------- -----------
The emqttd broker periodically publishes internal status, MQTT statistics, metrics and client online/offline status to $SYS/# topics. The *EMQ* broker periodically publishes internal status, MQTT statistics, metrics and client online/offline status to $SYS/# topics.
For emqttd broker is clustered, the $SYS topic path is started with:: For the *EMQ* broker could be clustered, the $SYS topic path is started with::
$SYS/brokers/${node}/ $SYS/brokers/${node}/
@ -760,7 +846,6 @@ Topic path started with: '$SYS/brokers/${node}/sysmon/'
| busy_dist_port | Busy Dist Port | | busy_dist_port | Busy Dist Port |
+------------------+--------------------+ +------------------+--------------------+
----- -----
Trace Trace
----- -----
@ -785,6 +870,12 @@ Stop a Trace::
./bin/emqttd_ctl trace topic "topic" off ./bin/emqttd_ctl trace topic "topic" off
.. _emqttd_plugin_mysql: https://github.com/emqtt/emqttd_plugin_mysql .. _emq_auth_clientid: https://github.com/emqtt/emq_auth_clientid
.. _emqttd_plugin_pgsql: https://github.com/emqtt/emqttd_plugin_pgsql .. _emq_auth_username: https://github.com/emqtt/emq_auth_username
.. _emqttd_plugin_redis: https://github.com/emqtt/emqttd_plugin_redis .. _emq_auth_ldap: https://github.com/emqtt/emqttd_auth_ldap
.. _emq_auth_http: https://github.com/emqtt/emqttd_auth_http
.. _emq_auth_mysql: https://github.com/emqtt/emqttd_plugin_mysql
.. _emq_auth_pgsql: https://github.com/emqtt/emqttd_plugin_pgsql
.. _emq_auth_redis: https://github.com/emqtt/emqttd_plugin_redis
.. _emq_auth_mongo: https://github.com/emqtt/emqttd_plugin_mongo

94
docs/source/install.rst
View File

@ -5,7 +5,7 @@
Installation Installation
============ ============
The emqttd broker is cross-platform, which could be deployed on Linux, FreeBSD, Mac, Windows and even Raspberry Pi. The *EMQ* broker is cross-platform, which could be deployed on Linux, FreeBSD, Mac, Windows and even Raspberry Pi.
.. NOTE:: .. NOTE::
@ -32,10 +32,12 @@ Download binary packages from: http://emqtt.io/downloads
+-----------+------------------------------------------+ +-----------+------------------------------------------+
| Windows | http://emqtt.io/downloads/latest/windows | | Windows | http://emqtt.io/downloads/latest/windows |
+-----------+------------------------------------------+ +-----------+------------------------------------------+
| Docker | http://emqtt.com/downloads/latest/docker |
+-----------+------------------------------------------+
The package name consists of platform, version and release time. The package name consists of platform, version and release time.
For example: emqttd-centos64-v2.0-beta.2-20160910.zip For example: emqttd-centos64-v2.0-rc.2-20161019.zip
.. _install_on_linux: .. _install_on_linux:
@ -47,7 +49,7 @@ Download CentOS Package from: http://emqtt.io/downloads/latest/centos, and then
.. code-block:: bash .. code-block:: bash
unzip emqttd-centos64-v2.0-beta.2-20160910.zip unzip emqttd-centos64-v2.0-rc.2-20161019.zip
Start the broker in console mode: Start the broker in console mode:
@ -92,8 +94,6 @@ Start the broker in daemon mode:
./bin/emqttd start ./bin/emqttd start
The boot logs in log/emqttd_sasl.log file.
Check the running status of the broker: Check the running status of the broker:
.. code-block:: bash .. code-block:: bash
@ -130,17 +130,18 @@ 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 Download Mac Package from: http://emqtt.io/downloads/latest/macosx
Configure 'lager' log level in 'releases/2.0/sys.config', all MQTT messages recevied/sent will be printed on console: Configure log level in `etc/emq.conf`, all MQTT messages recevied/sent will be printed on console:
.. code-block:: erlang .. code-block::
{lager, [ ## Console log. Enum: off, file, console, both
... log.console = both
{handlers, [
{lager_console_backend, info}, ## Console log level. Enum: debug, info, notice, warning, error, critical, alert, emergency
... log.console.level = debug
]}
]}, ## Console log file
log.console.file = log/console.log
The install and boot process on Mac are same to Linux. The install and boot process on Mac are same to Linux.
@ -186,7 +187,7 @@ Uninstall emqttd service::
Installing From Source Installing From Source
---------------------- ----------------------
The emqttd broker requires Erlang/OTP R17+ and git client to build: The *EMQ* broker requires Erlang/OTP R18+ and git client to build:
Install Erlang: http://www.erlang.org/ Install Erlang: http://www.erlang.org/
@ -226,22 +227,16 @@ TCP Ports Used
The TCP ports used can be configured in etc/emqttd.config: The TCP ports used can be configured in etc/emqttd.config:
.. code-block:: erlang .. code-block:: properties
%% Plain MQTT ## TCP Listener: 1883, 127.0.0.1:1883, ::1:1883
{listener, mqtt, 1883, [ mqtt.listener.tcp = 1883
...
]}.
%% MQTT/SSL ## SSL Listener: 8883, 127.0.0.1:8883, ::1:8883
{listener, mqtts, 8883, [ mqtt.listener.ssl = 8883
...
]}.
%% HTTP and WebSocket Listener ## HTTP and WebSocket Listener
{listener, http, 8083, [ mqtt.listener.http = 8083
...
]}.
The 18083 port is used by Web Dashboard of the broker. Default login: admin, Password: public The 18083 port is used by Web Dashboard of the broker. Default login: admin, Password: public
@ -251,45 +246,38 @@ The 18083 port is used by Web Dashboard of the broker. Default login: admin, Pas
Quick Setup Quick Setup
----------- -----------
Two main configuration files of the emqttd broker: Two main configuration files of the *EMQ* broker:
+-----------------------+-----------------------------------+ +-----------------------+-----------------------------------+
| releases/2.0/vm.args | Erlang VM Arguments | | etc/emq.conf | EMQ Broker Config |
+-----------------------+-----------------------------------+ +-----------------------+-----------------------------------+
| etc/emqttd.conf | emqttd broker Config | | etc/plugins/\*.conf | EMQ Plugins' Config |
+-----------------------+-----------------------------------+ +-----------------------+-----------------------------------+
Two important parameters in releases/2.0/vm.args: Two important parameters in etc/emq.conf:
+-------+---------------------------------------------------------------------------+ +--------------------+-------------------------------------------------------------------------+
| +P | Max number of Erlang proccesses. A MQTT client consumes two proccesses. | | node.process_limit | Max number of Erlang proccesses. A MQTT client consumes two proccesses. |
| | The value should be larger than max_clients * 2 | | | The value should be larger than max_clients * 2 |
+-------+---------------------------------------------------------------------------+ +--------------------+-------------------------------------------------------------------------+
| +Q | Max number of Erlang Ports. A MQTT client consumes one port. | | node.max_ports | Max number of Erlang Ports. A MQTT client consumes one port. |
| | The value should be larger than max_clients. | | | The value should be larger than max_clients. |
+-------+---------------------------------------------------------------------------+ +--------------------+-------------------------------------------------------------------------+
.. NOTE:: .. NOTE::
+Q > maximum number of allowed concurrent clients node.process_limit > maximum number of allowed concurrent clients * 2
+P > maximum number of allowed concurrent clients * 2 node.max_ports > maximum number of allowed concurrent clients
The maximum number of allowed MQTT clients: The maximum number of allowed MQTT clients:
.. code-block:: erlang .. code-block:: properties
%% Plain MQTT mqtt.listener.tcp = 1883
{listener, mqtt, 1883, [
%% Size of acceptor pool mqtt.listener.tcp.acceptors = 8
{acceptors, 16},
%% Maximum number of concurrent clients mqtt.listener.tcp.max_clients = 1024
{max_clients, 8192},
...
]}.
.. _init_d_emqttd: .. _init_d_emqttd:
@ -357,4 +345,6 @@ boot test::
## erlexec: HOME must be set ## erlexec: HOME must be set
uncomment '# export HOME=/root' if "HOME must be set" error. uncomment '# export HOME=/root' if "HOME must be set" error.
.. _emq_dashboard: https://github.com/emqtt/emqttd_dashboard

824
docs/source/plugins.rst
View File

File diff suppressed because it is too large Load Diff

55
docs/source/tune.rst
View File

@ -5,7 +5,7 @@
Tuning Guide Tuning Guide
============ ============
Tuning the Linux Kernel, Networking, Erlang VM and emqttd broker for one million concurrent MQTT connections. Tuning the Linux Kernel, Networking, Erlang VM and the *EMQ* broker for one million concurrent MQTT connections.
------------------- -------------------
Linux Kernel Tuning Linux Kernel Tuning
@ -89,55 +89,36 @@ Timeout for FIN-WAIT-2 sockets::
Erlang VM Tuning Erlang VM Tuning
---------------- ----------------
Tuning and optimize the Erlang VM in releases/2.0/vm.args file:: Tuning and optimize the Erlang VM in etc/emq.conf file:
## max number of erlang processes .. code-block:: properties
+P 2097152
## Erlang Process Limit
node.process_limit = 2097152
## Sets the maximum number of simultaneously existing ports for this system ## Sets the maximum number of simultaneously existing ports for this system
+Q 1048576 node.max_ports = 1048576
## Increase number of concurrent ports/sockets, deprecated in R17 --------------
-env ERL_MAX_PORTS 1048576 The EMQ Broker
--------------
-env ERTS_MAX_PORTS 1048576
## Mnesia and SSL will create temporary ets tables.
-env ERL_MAX_ETS_TABLES 1024
## Tweak GC to run more often
-env ERL_FULLSWEEP_AFTER 1000
-------------
emqttd broker
-------------
Tune the acceptor pool, max_clients limit and sockopts for TCP listener in etc/emqttd.config: Tune the acceptor pool, max_clients limit and sockopts for TCP listener in etc/emqttd.config:
.. code-block:: erlang .. code-block:: properties
{mqtt, 1883, [ ## TCP Listener
%% Size of acceptor pool mqtt.listener.tcp = 1883
{acceptors, 64}, mqtt.listener.tcp.acceptors = 64
mqtt.listener.tcp.max_clients = 1000000
%% 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
]},
...
-------------- --------------
Client Machine Client Machine
-------------- --------------
Tune the client machine to benchmark emqttd broker:: Tune the client machine to benchmark emqttd broker:
.. code-block:: bash
sysctl -w net.ipv4.ip_local_port_range="500 65535" sysctl -w net.ipv4.ip_local_port_range="500 65535"
sysctl -w fs.file-max=1000000 sysctl -w fs.file-max=1000000