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

702 lines
19 KiB
ReStructuredText
Raw Permalink Blame History

.. _configuration:
=============
Configuration
=============
Configuration files of the broker are under 'etc/' folder, including:
+-------------------+-----------------------------------+
| File | Description |
+-------------------+-----------------------------------+
| etc/vm.args | Erlang VM Arguments |
+-------------------+-----------------------------------+
| etc/emqttd.config | emqttd broker Config |
+-------------------+-----------------------------------+
| etc/acl.config | ACL Config |
+-------------------+-----------------------------------+
| etc/clients.config| ClientId Authentication |
+-------------------+-----------------------------------+
| etc/rewrite.config| Rewrite Rules |
+-------------------+-----------------------------------+
| etc/ssl/* | SSL certificate and key files |
+-------------------+-----------------------------------+
-----------
etc/vm.args
-----------
Configure and Optimize Erlang VM::
##-------------------------------------------------------------------------
## Name of the node
##-------------------------------------------------------------------------
-name emqttd@127.0.0.1
## Cookie for distributed erlang
-setcookie emqttdsecretcookie
##-------------------------------------------------------------------------
## Flags
##-------------------------------------------------------------------------
## Heartbeat management; auto-restarts VM if it dies or becomes unresponsive
## (Disabled by default..use with caution!)
##-heart
-smp true
## Enable kernel poll and a few async threads
+K true
## 12 threads/core.
+A 48
## max process numbers
+P 8192
## Sets the maximum number of simultaneously existing ports for this system
+Q 8192
## max atom number
## +t
## Set the distribution buffer busy limit (dist_buf_busy_limit) in kilobytes.
## Valid range is 1-2097151. Default is 1024.
## +zdbbl 8192
## CPU Schedulers
## +sbt db
##-------------------------------------------------------------------------
## Env
##-------------------------------------------------------------------------
## Increase number of concurrent ports/sockets, deprecated in R17
-env ERL_MAX_PORTS 8192
-env ERTS_MAX_PORTS 8192
-env ERL_MAX_ETS_TABLES 1024
## Tweak GC to run more often
-env ERL_FULLSWEEP_AFTER 1000
The two most important parameters in etc/vm.args:
+-------+---------------------------------------------------------------------------+
| +P | Max number of Erlang proccesses. A MQTT client consumes two proccesses. |
| | The value should be larger than max_clients * 2 |
+-------+---------------------------------------------------------------------------+
| +Q | Max number of Erlang Ports. A MQTT client consumes one port. |
| | The value should be larger than max_clients. |
+-------+---------------------------------------------------------------------------+
The name and cookie of Erlang Node should be configured when clustering::
-name emqttd@host_or_ip
## Cookie for distributed erlang
-setcookie emqttdsecretcookie
-----------------
etc/emqttd.config
-----------------
This is the main emqttd broker configuration file.
File Syntax
-----------
The file users the standard Erlang config syntax, consists of a list of erlang applications and their environments.
.. code:: erlang
[{kernel, [
{start_timer, true},
{start_pg2, true}
]},
{sasl, [
{sasl_error_logger, {file, "log/emqttd_sasl.log"}}
]},
...
{emqttd, [
...
]}
].
The file adopts Erlang Term Syntax:
1. [ ]: List, seperated by comma
2. { }: Tuple, Usually {Env, Value}
3. % : comment
Log Level and File
------------------
Logger of emqttd broker is implemented by 'lager' application::
{lager, [
...
]},
Configure log handlers::
{handlers, [
{lager_console_backend, info},
{lager_file_backend, [
{formatter_config, [time, " ", pid, " [",severity,"] ", message, "\n"]},
{file, "log/emqttd_info.log"},
{level, info},
{size, 104857600},
{date, "$D0"},
{count, 30}
]},
{lager_file_backend, [
{formatter_config, [time, " ", pid, " [",severity,"] ", message, "\n"]},
{file, "log/emqttd_error.log"},
{level, error},
{size, 104857600},
{date, "$D0"},
{count, 30}
]}
]}
emqttd Application
------------------
The MQTT broker is implemented by erlang 'emqttd' application::
{emqttd, [
%% Authentication and Authorization
{access, [
...
]},
%% MQTT Protocol Options
{mqtt, [
...
]},
%% Broker Options
{broker, [
...
]},
%% Modules
{modules, [
...
]},
%% Plugins
{plugins, [
...
]},
%% Listeners
{listeners, [
...
]},
%% Erlang System Monitor
{sysmon, [
]}
]}
Pluggable Authentication
------------------------
The emqttd broker supports pluggable authentication mechanism with a list of modules and plugins.
The broker provides Username, ClientId, LDAP and anonymous authentication modules by default::
%% Authetication. Anonymous Default
{auth, [
%% Authentication with username, password
%% Add users: ./bin/emqttd_ctl users add Username Password
%% {username, [{"test", "public"}]},
%% 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, []}
]},
The modules enabled at the same time compose an authentication chain:
---------------- ---------------- -------------
Client --> | Username | -ignore-> | ClientID | -ignore-> | Anonymous |
---------------- ---------------- -------------
| | |
\|/ \|/ \|/
allow | deny allow | deny allow | deny
.. NOTE:: There are also MySQL、PostgreSQL、Redis、MongoDB Authentication Plugins.
Username Authentication
.......................
.. code:: erlang
{username, [{client1, "passwd1"}, {client2, "passwd2"}]},
Two ways to configure users:
1. Configure username and plain password directly::
{username, [{client1, "passwd1"}, {client2, "passwd2"}]},
2. Add user by './bin/emqttd_ctl users' command::
$ ./bin/emqttd_ctl users add <Username> <Password>
ClientID Authentication
.......................
.. code:: erlang
{clientid, [{password, no}, {file, "etc/clients.config"}]},
Configure ClientIDs in etc/clients.config::
testclientid0
testclientid1 127.0.0.1
testclientid2 192.168.0.1/24
LDAP Authentication
...................
.. code:: erlang
{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"}]}
]},
Anonymous Authentication
........................
Allow any client to connect to the broker::
{anonymous, []}
ACL
---
Enable the default ACL module::
{acl, [
%% Internal ACL module
{internal, [{file, "etc/acl.config"}, {nomatch, allow}]}
]}
MQTT Packet and ClientID
------------------------
.. code::
{packet, [
%% Max ClientId Length Allowed
{max_clientid_len, 1024},
%% Max Packet Size Allowed, 64K default
{max_packet_size, 65536}
]},
MQTT Client Idle Timeout
------------------------
.. code::
{client, [
%% Socket is connected, but no 'CONNECT' packet received
{idle_timeout, 10}
]},
MQTT Session
------------
.. code::
{session, [
%% Max number of QoS 1 and 2 messages that can be “in flight” at one time.
%% 0 means no limit
{max_inflight, 100},
%% Retry interval for unacked QoS1/2 messages.
{unack_retry_interval, 20},
%% Awaiting PUBREL Timeout
{await_rel_timeout, 20},
%% Max Packets that Awaiting PUBREL, 0 means no limit
{max_awaiting_rel, 0},
%% Interval of Statistics Collection(seconds)
{collect_interval, 20},
%% Expired after 2 days
{expired_after, 48}
]},
Session parameters:
+----------------------+----------------------------------------------------------+
| max_inflight | Max number of QoS1/2 messages that can be delivered in |
| | the same time |
+----------------------+----------------------------------------------------------+
| unack_retry_interval | Retry interval for unacked QoS1/2 messages. |
+----------------------+----------------------------------------------------------+
| await_rel_timeout | Awaiting PUBREL Timeout |
+----------------------+----------------------------------------------------------+
| max_awaiting_rel | Max number of Packets that Awaiting PUBREL |
+----------------------+----------------------------------------------------------+
| collect_interval | Interval of Statistics Collection |
+----------------------+----------------------------------------------------------+
| expired_after | Expired after |
+----------------------+----------------------------------------------------------+
MQTT Message Queue
------------------
The message queue of session stores:
1. Offline messages for persistent session.
2. Pending messages for inflight window is full
Queue parameters::
{queue, [
%% simple | priority
{type, simple},
%% Topic Priority: 0~255, Default is 0
%% {priority, [{"topic/1", 10}, {"topic/2", 8}]},
%% Max queue length. Enqueued messages when persistent client disconnected,
%% or inflight window is full.
{max_length, infinity},
%% Low-water mark of queued messages
{low_watermark, 0.2},
%% High-water mark of queued messages
{high_watermark, 0.6},
%% Queue Qos0 messages?
{queue_qos0, true}
]}
+----------------------+---------------------------------------------------+
| type | Queue type: simple or priority |
+----------------------+---------------------------------------------------+
| priority | Topic priority |
+----------------------+---------------------------------------------------+
| max_length | Max Queue size, infinity means no limit |
+----------------------+---------------------------------------------------+
| low_watermark | Low watermark |
+----------------------+---------------------------------------------------+
| high_watermark | High watermark |
+----------------------+---------------------------------------------------+
| queue_qos0 | If Qos0 message queued? |
+----------------------+---------------------------------------------------+
Sys Interval of Broker
-----------------------
.. code::
%% System interval of publishing $SYS messages
{sys_interval, 60},
Retained messages
-----------------
.. code::
{retained, [
%% Expired after seconds, never expired if 0
{expired_after, 0},
%% Maximum number of retained messages
{max_message_num, 100000},
%% Max Payload Size of retained message
{max_playload_size, 65536}
]},
PubSub and Router
-----------------
.. code:: erlang
{pubsub, [
%% PubSub Pool
{pool_size, 8},
%% Subscription: true | false
{subscription, true},
%% Route aging time(seconds)
{route_aging, 5}
]},
Bridge Parameters
-----------------
.. code:: erlang
{bridge, [
%% Bridge Queue Size
{max_queue_len, 10000},
%% Ping Interval of bridge node
{ping_down_interval, 1}
]}
Enable Modules
--------------
'presence' module will publish presence message to $SYS topic when a client connected or disconnected::
{presence, [{qos, 0}]},
'subscription' module forces the client to subscribe some topics when connected to the broker::
%% Subscribe topics automatically when client connected
{subscription, [
%% Subscription from stored table
stored,
%% $u will be replaced with username
{"$Q/username/$u", 1},
%% $c will be replaced with clientid
{"$Q/client/$c", 1}
]}
'rewrite' module supports to rewrite the topic path::
%% Rewrite rules
{rewrite, [{file, "etc/rewrite.config"}]}
Plugins Folder
--------------
.. code:: erlang
{plugins, [
%% Plugin App Library Dir
{plugins_dir, "./plugins"},
%% File to store loaded plugin names.
{loaded_file, "./data/loaded_plugins"}
]},
TCP Listeners
-------------
Congfigure the TCP listeners for MQTT, MQTT(SSL) and HTTP Protocols.
The most important parameter is 'max_clients' - max concurrent clients allowed.
The TCP Ports occupied by emqttd broker by default:
+-----------+-----------------------------------+
| 1883 | MQTT Port |
+-----------+-----------------------------------+
| 8883 | MQTT(SSL) Port |
+-----------+-----------------------------------+
| 8083 | MQTT(WebSocket), HTTP API Port |
+-----------+-----------------------------------+
.. code:: erlang
{listeners, [
{mqtt, 1883, [
%% Size of acceptor pool
{acceptors, 16},
%% Maximum number of concurrent clients
{max_clients, 8192},
%% 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
]},
%% Socket Options
{sockopts, [
%Set buffer if hight thoughtput
%{recbuf, 4096},
%{sndbuf, 4096},
%{buffer, 4096},
%{nodelay, true},
{backlog, 1024}
]}
]},
{mqtts, 8883, [
%% Size of acceptor pool
{acceptors, 4},
%% Maximum number of concurrent clients
{max_clients, 512},
%% Socket Access Control
{access, [{allow, all}]},
%% SSL certificate and key files
{ssl, [{certfile, "etc/ssl/ssl.crt"},
{keyfile, "etc/ssl/ssl.key"}]},
%% Socket Options
{sockopts, [
{backlog, 1024}
%{buffer, 4096},
]}
]},
%% WebSocket over HTTPS Listener
%% {https, 8083, [
%% %% Size of acceptor pool
%% {acceptors, 4},
%% %% Maximum number of concurrent clients
%% {max_clients, 512},
%% %% Socket Access Control
%% {access, [{allow, all}]},
%% %% SSL certificate and key files
%% {ssl, [{certfile, "etc/ssl/ssl.crt"},
%% {keyfile, "etc/ssl/ssl.key"}]},
%% %% Socket Options
%% {sockopts, [
%% %{buffer, 4096},
%% {backlog, 1024}
%% ]}
%%]},
%% HTTP and WebSocket Listener
{http, 8083, [
%% Size of acceptor pool
{acceptors, 4},
%% Maximum number of concurrent clients
{max_clients, 64},
%% Socket Access Control
{access, [{allow, all}]},
%% Socket Options
{sockopts, [
{backlog, 1024}
%{buffer, 4096},
]}
]}
]},
Listener Parameters:
+-------------+----------------------------------------------------------------+
| acceptors | TCP Acceptor Pool |
+-------------+----------------------------------------------------------------+
| max_clients | Maximum number of concurrent TCP connections allowed |
+-------------+----------------------------------------------------------------+
| access | Access Control by IP, for example: [{allow, "192.168.1.0/24"}] |
+-------------+----------------------------------------------------------------+
| connopts | Rate Limit Control, for example: {rate_limit, "100,10"} |
+-------------+----------------------------------------------------------------+
| sockopts | TCP Socket parameters |
+-------------+----------------------------------------------------------------+
.. _config_acl:
--------------
etc/acl.config
--------------
The 'etc/acl.config' is the default ACL config for emqttd broker. The rules by default::
%% Allow 'dashboard' to subscribe '$SYS/#'
{allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}.
%% Allow clients from localhost to subscribe any topics
{allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}.
%% Deny clients to subscribe '$SYS#' and '#'
{deny, all, subscribe, ["$SYS/#", {eq, "#"}]}.
%% Allow all by default
{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::
--------- --------- ---------
Client -> | Rule1 | --nomatch--> | Rule2 | --nomatch--> | Rule3 | --> Default
--------- --------- ---------
| | |
match match match
\|/ \|/ \|/
allow | deny allow | deny allow | deny
.. _config_rewrite:
------------------
etc/clients.config
------------------
Enable ClientId Authentication in 'etc/emqttd.config'::
{auth, [
%% Authentication with clientid
{clientid, [{password, no}, {file, "etc/clients.config"}]}
]},
Configure all allowed ClientIDs, IP Addresses in etc/clients.config::
testclientid0
testclientid1 127.0.0.1
testclientid2 192.168.0.1/24
------------------
etc/rewrite.config
------------------
The Rewrite Rules for emqttd_mod_rewrite::
{topic, "x/#", [
{rewrite, "^x/y/(.+)$", "z/y/$1"},
{rewrite, "^x/(.+)$", "y/$1"}
]}.
{topic, "y/+/z/#", [
{rewrite, "^y/(.+)/z/(.+)$", "y/z/$2"}
]}.
Reference in New Issue View Git Blame Copy Permalink