.. _configuration: ============= Configuration ============= The two main configuration files of the broker are under 'etc/' folder: +----------------------+-----------------------------------+ | File | Description | +----------------------+-----------------------------------+ | releases/2.0/vm.args | Erlang VM Arguments | +----------------------+-----------------------------------+ | etc/emqttd.conf | emqttd broker Config | +----------------------+-----------------------------------+ ---------------------------- Plugins' Configuration Files ---------------------------- +----------------------------------------+-----------------------------------+ | File | Description | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_auth_http.conf | HTTP Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_auth_mongo.conf | MongoDB Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_auth_mysql.conf | MySQL Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_auth_pgsql.conf | Postgre Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_auth_redis.conf | Redis Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_coap.conf | CoAP Protocol Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_dashboard.conf | Dashboard Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_plugin_template.conf| Template Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_recon.conf | Recon Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_reloader.conf | Reloader Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_sn.conf | MQTT-SN Protocal Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emqttd_stomp.conf | Stomp Protocl Plugin Config | +----------------------------------------+-----------------------------------+ ---------------------------- Modules' Configuration Files ---------------------------- The modules' configuration files are in etc/modules/ folder, and referrenced by etc/emqttd.conf: +----------------------------+-----------------------------------+ | File | Description | +----------------------------+-----------------------------------+ | etc/modules/acl.config | Internal ACL Rules | +----------------------------+-----------------------------------+ | etc/modules/client.config | Config for ClientId Auth Module | +----------------------------+-----------------------------------+ | etc/modules/rewrite.config | Config for Rewrite Module | +----------------------------+-----------------------------------+ | etc/ssl/* | SSL Certfile and Keyfile | +-----------------------------+----------------------------------+ -------------------- releases/2.0/vm.args -------------------- Configure and Optimize Erlang VM:: ##------------------------------------------------------------------------- ## Name of the node: Name@Host ##------------------------------------------------------------------------- -name emqttd@127.0.0.1 # or #-name emqttd@localhost. ## 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 releases/2.0/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 ------------------ Log Level and File ------------------ Logger of emqttd broker is implemented by 'lager' application, which is configured in releases/2.0/sys.config: .. code-block:: erlang {lager, [ ... ]}, Configure log handlers: .. code-block:: erlang {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} ]} ]} --------------- etc/emqttd.conf --------------- This is the main configuration file for emqttd broker. File Syntax ----------- The file uses the Erlang term syntax which is like rebar.config or relx.config: 1. [ ]: List, seperated by comma 2. { }: Tuple, Usually {Env, Value} 3. % : comment MQTT Protocol Parameters ------------------------ Maximum ClientId Length ....................... .. code-block:: erlang %% Max ClientId Length Allowed. {mqtt_max_clientid_len, 512}. Maximum Packet Size ................... .. code-block:: erlang %% Max Packet Size Allowed, 64K by default. {mqtt_max_packet_size, 65536}. MQTT Client Idle Timeout ........................ .. code-block:: erlang %% Client Idle Timeout. {mqtt_client_idle_timeout, 30}. % Second 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: .. code-block:: erlang %%-------------------------------------------------------------------- %% Authentication %%-------------------------------------------------------------------- %% Anonymous: Allow all {auth, anonymous, []}. %% Authentication with username, password {auth, username, [{passwd, "etc/modules/passwd.conf"}]}. %% Authentication with clientId {auth, clientid, [{config, "etc/modules/client.conf"}, {password, no}]}. The modules enabled at the same time compose an authentication chain:: ---------------- ---------------- -------------- Client --> | Anonymous | -ignore-> | Username | -ignore-> | ClientID | ---------------- ---------------- -------------- | | | \|/ \|/ \|/ allow | deny allow | deny allow | deny .. NOTE:: There are also MySQL, Postgre, Redis, MongoDB and HTTP Authentication Plugins. Username Authentication ....................... .. code-block:: erlang %% Authentication with username, password {auth, username, [{passwd, "etc/modules/passwd.conf"}]}. Two ways to configure users: 1. Configure username and plain password in etc/modules/passwd.conf:: {"user1", "passwd1"}. {"user2", "passwd2"}. 2. Add user by './bin/emqttd_ctl users' command:: $ ./bin/emqttd_ctl users add ClientID Authentication ....................... .. code-block:: erlang %% Authentication with clientId {auth, clientid, [{config, "etc/modules/client.conf"}, {password, no}]}. Configure ClientIDs in etc/clients.config:: "testclientid0". {"testclientid1", "127.0.0.1"}. {"testclientid2", "192.168.0.1/24"}. Anonymous Authentication ........................ Allow any client to connect to the broker:: %% Anonymous: Allow all {auth, anonymous, []}. ACL(Authorization) ------------------ Enable the default ACL module: .. code-block:: erlang %% Internal ACL config {acl, internal, [{config, "etc/modules/acl.conf"}, {nomatch, allow}]}. Define ACL rules in etc/modules/acl.conf. The rules by default: .. code-block:: erlang %% 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 Sys Interval of Broker ---------------------- .. code-block:: erlang %% System interval of publishing $SYS messages {broker_sys_interval, 60}. Retained Message Configuration ------------------------------ Expiration of Retained Message ............................... .. code:: erlang %% Expired after seconds, never expired if 0 {retained_expired_after, 0}. Maximum Number of Retained Message ................................... .. code:: erlang %% Max number of retained messages {retained_max_message_num, 100000}. Maximum Size of Retained Message ................................ .. code:: erlang %% Max Payload Size of retained message {retained_max_playload_size, 65536}. MQTT Session ------------ .. code-block:: erlang %% Max number of QoS 1 and 2 messages that can be “inflight” at one time. %% 0 means no limit {session_max_inflight, 100}. %% Retry interval for redelivering QoS1/2 messages. {session_unack_retry_interval, 60}. %% Awaiting PUBREL Timeout {session_await_rel_timeout, 20}. %% Max Packets that Awaiting PUBREL, 0 means no limit {session_max_awaiting_rel, 0}. %% Statistics Collection Interval(seconds) {session_collect_interval, 0}. %% Expired after 2 day (unit: minute) {session_expired_after, 2880}. Session parameters: +------------------------------+----------------------------------------------------------+ | session_max_inflight | Max number of QoS1/2 messages that can be delivered in | | | the same time | +------------------------------+----------------------------------------------------------+ | session_unack_retry_interval | Retry interval for unacked QoS1/2 messages. | +------------------------------+----------------------------------------------------------+ | session_await_rel_timeout | Awaiting PUBREL Timeout | +------------------------------+----------------------------------------------------------+ | session_max_awaiting_rel | Max number of Packets that Awaiting PUBREL | +------------------------------+----------------------------------------------------------+ | session_collect_interval | Interval of Statistics Collection | +------------------------------+----------------------------------------------------------+ | session_expired_after | Expired after (unit: minute) | +------------------------------+----------------------------------------------------------+ 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: .. code-block:: erlang %% Type: simple | priority {queue_type, simple}. %% Topic Priority: 0~255, Default is 0 %% {queue_priority, [{"topic/1", 10}, {"topic/2", 8}]}. %% Max queue length. Enqueued messages when persistent client disconnected, %% or inflight window is full. {queue_max_length, infinity}. %% Low-water mark of queued messages {queue_low_watermark, 0.2}. %% High-water mark of queued messages {queue_high_watermark, 0.6}. %% Queue Qos0 messages? {queue_qos0, true}. +----------------------+---------------------------------------------------+ | queue_type | Queue type: simple or priority | +----------------------+---------------------------------------------------+ | queue_priority | Topic priority | +----------------------+---------------------------------------------------+ | queue_max_length | Max Queue size, infinity means no limit | +----------------------+---------------------------------------------------+ | queue_low_watermark | Low watermark | +----------------------+---------------------------------------------------+ | queue_high_watermark | High watermark | +----------------------+---------------------------------------------------+ | queue_qos0 | If Qos0 message queued? | +----------------------+---------------------------------------------------+ PubSub and Router ----------------- PubSub Pool Size ................ .. code-block:: erlang %% PubSub Pool Size. Default should be scheduler numbers. {pubsub_pool_size, 8}. MQTT Bridge Parameters ---------------------- Max MQueue Size of Bridge ......................... .. code:: erlang %% TODO: Bridge Queue Size {bridge_max_queue_len, 10000}. Ping Interval of Bridge ....................... .. code:: erlang %% Ping Interval of bridge node {bridge_ping_down_interval, 1}. % second Extended Modules ---------------- Presence Module ............... 'presence' module will publish presence message to $SYS topic when a client connected or disconnected: .. code:: erlang %% Client presence management module. Publish presence messages when %% client connected or disconnected. {module, presence, [{qos, 0}]}. Subscription Module ................... 'subscription' module forces the client to subscribe some topics when connected to the broker: .. code:: erlang %% Subscribe topics automatically when client connected {module, subscription, [{"$client/$c", 1}]}. Rewrite Module .............. 'rewrite' module supports to rewrite the topic path: .. code:: erlang %% [Rewrite](https://github.com/emqtt/emqttd/wiki/Rewrite) {module, rewrite, [{config, "etc/modules/rewrite.conf"}]}. Configure rewrite rules in etc/modules/rewrite.conf:: {topic, "x/#", [ {rewrite, "^x/y/(.+)$", "z/y/$1"}, {rewrite, "^x/(.+)$", "y/$1"} ]}. {topic, "y/+/z/#", [ {rewrite, "^y/(.+)/z/(.+)$", "y/z/$2"} ]}. Plugins Folder -------------- .. code:: erlang %% Dir of plugins' config {plugins_etc_dir, "etc/plugins/"}. %% File to store loaded plugin names. {plugins_loaded_file, "data/loaded_plugins"}. TCP Listeners ------------- Configure 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-block:: erlang 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 | +-------------+----------------------------------------------------------------+ 1883 - Plain MQTT ................. .. code-block:: erlang %% Plain MQTT {listener, mqtt, 1883, [ %% Size of acceptor pool {acceptors, 16}, %% Maximum number of concurrent clients {max_clients, 512}, %% Mount point prefix %% {mount_point, "prefix/"}, %% 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} ]} ]}. 8883 - MQTT(SSL) ................ .. code-block:: erlang %% MQTT/SSL {listener, mqtts, 8883, [ %% Size of acceptor pool {acceptors, 4}, %% Maximum number of concurrent clients {max_clients, 512}, %% Mount point prefix %% {mount_point, "secure/"}, %% 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}, ]} ]}. 8083 - MQTT(WebSocket) ...................... .. code-block:: erlang %% HTTP and WebSocket Listener {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}, ]} ]}. Erlang VM Monitor ----------------- .. code:: erlang %% Long GC, don't monitor in production mode for: %% https://github.com/erlang/otp/blob/feb45017da36be78d4c5784d758ede619fa7bfd3/erts/emulator/beam/erl_gc.c#L421 {sysmon_long_gc, false}. %% Long Schedule(ms) {sysmon_long_schedule, 240}. %% 8M words. 32MB on 32-bit VM, 64MB on 64-bit VM. %% 8 * 1024 * 1024 {sysmon_large_heap, 8388608}. %% Busy Port {sysmon_busy_port, false}. %% Busy Dist Port {sysmon_busy_dist_port, true}.