.. _configuration: ============= Configuration ============= The main configuration files of the EMQ broker are under 'etc/' folder: +----------------------+-----------------------------------+ | File | Description | +----------------------+-----------------------------------+ | etc/emq.conf | EMQ 2.0 Configuration File | +----------------------+-----------------------------------+ | etc/acl.conf | The default ACL File | +----------------------+-----------------------------------+ | etc/plugins/\*.conf | Config Files of Plugins | +----------------------+-----------------------------------+ --------------------- 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: .. code-block:: properties ## Node name node.name = emqttd@127.0.0.1 ... ## Max ClientId Length Allowed. mqtt.max_clientid_len = 1024 ... The configuration files will be preprocessed and translated to Erlang `app.config` before the EMQ broker started:: ---------------------- 2.0/schema/*.schema ------------------- | etc/emq.conf | ----------------- \|/ | data/app.config | | + | --> mergeconf --> | data/app.conf | --> cuttlefish generate --> | | | etc/plugins/*.conf | ----------------- | data/vm.args | ---------------------- ------------------- ------------------------ OS Environment Variables ------------------------ +-------------------+----------------------------------------+ | EMQ_NODE_NAME | Erlang node name | +-------------------+----------------------------------------+ | EMQ_NODE_COOKIE | Cookie for distributed erlang node | +-------------------+----------------------------------------+ | EMQ_MAX_PORTS | Maximum number of opened sockets | +-------------------+----------------------------------------+ | EMQ_TCP_PORT | MQTT TCP Listener Port, Default: 1883 | +-------------------+----------------------------------------+ | EMQ_SSL_PORT | MQTT SSL Listener Port, Default: 8883 | +-------------------+----------------------------------------+ | EMQ_HTTP_PORT | HTTP/WebSocket Port, Default: 8083 | +-------------------+----------------------------------------+ | EMQ_HTTPS_PORT | HTTPS/WebSocket Port, Default: 8084 | +-------------------+----------------------------------------+ ------------------- EMQ Node and Cookie ------------------- The node name and cookie of *EMQ* should be configured when clustering: .. code-block:: properties ## Node name node.name = emqttd@127.0.0.1 ## Cookie for distributed node node.cookie = emq_dist_cookie ------------------- Erlang VM Arguments ------------------- Configure and Optimize Erlang VM: .. code-block:: properties ## SMP support: enable, auto, disable node.smp = auto ## Enable kernel poll node.kernel_poll = on ## async thread pool node.async_threads = 32 ## Erlang Process Limit node.process_limit = 256000 ## Sets the maximum number of simultaneously existing ports for this system node.max_ports = 65536 ## Set the distribution buffer busy limit (dist_buf_busy_limit) node.dist_buffer_size = 32MB ## Max ETS Tables. ## Note that mnesia and SSL will create temporary ets tables. node.max_ets_tables = 256000 ## Tweak GC to run more often node.fullsweep_after = 1000 ## Crash dump node.crash_dump = log/crash.dump ## Distributed node ticktime node.dist_net_ticktime = 60 ## Distributed node port range ## node.dist_listen_min = 6000 ## node.dist_listen_max = 6999 The two most important parameters for Erlang VM: +--------------------------+---------------------------------------------------------------------------+ | node.process_limit | Max number of Erlang proccesses. A MQTT client consumes two proccesses. | | | The value should be larger than max_clients * 2 | +--------------------------+---------------------------------------------------------------------------+ | node.max_ports | Max number of Erlang Ports. A MQTT client consumes one port. | | | The value should be larger than max_clients. | +--------------------------+---------------------------------------------------------------------------+ ------------------ Log Level and File ------------------ Console Log ----------- .. code-block:: properties ## Console log. Enum: off, file, console, both log.console = console ## Console log level. Enum: debug, info, notice, warning, error, critical, alert, emergency log.console.level = error ## Console log file ## log.console.file = log/console.log Error Log --------- .. code-block:: properties ## Error log file log.error.file = log/error.log Crash Log --------- .. code-block:: properties ## Enable the crash log. Enum: on, off log.crash = on log.crash.file = log/crash.log ------------------------ MQTT Protocol Parameters ------------------------ Maximum ClientId Length ----------------------- .. code-block:: properties ## Max ClientId Length Allowed. mqtt.max_clientid_len = 1024 Maximum Packet Size ------------------- .. code-block:: properties ## Max Packet Size Allowed, 64K by default. mqtt.max_packet_size = 64KB MQTT Client Idle Timeout ------------------------ .. code-block:: properties ## Client Idle Timeout (Second) mqtt.client_idle_timeout = 30 ---------------------------- Allow Anonymous and ACL File ---------------------------- Allow Anonymous --------------- .. code-block:: properties ## Allow Anonymous authentication mqtt.allow_anonymous = true Default ACL File ---------------- Enable the default ACL module: .. code-block:: properties ## Default ACL File mqtt.acl_file = etc/acl.conf Define ACL rules in etc/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 *EMQ* 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 ----------------------- MQTT Session Parameters ----------------------- .. code-block:: properties ## Max number of QoS 1 and 2 messages that can be “inflight” at one time. ## 0 means no limit mqtt.session.max_inflight = 100 ## Retry interval for redelivering QoS1/2 messages. mqtt.session.retry_interval = 60 ## Awaiting PUBREL Timeout mqtt.session.await_rel_timeout = 20 ## Max Packets that Awaiting PUBREL, 0 means no limit mqtt.session.max_awaiting_rel = 0 ## Statistics Collection Interval(seconds) mqtt.session.collect_interval = 0 ## Expired after 1 day: ## w - week ## d - day ## h - hour ## m - minute ## s - second mqtt.session.expired_after = 1d +------------------------------+----------------------------------------------------------+ | session.max_inflight | Max number of QoS1/2 messages that can be delivered in | | | the same time | +------------------------------+----------------------------------------------------------+ | session.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:: properties ## Type: simple | priority mqtt.queue.type = simple ## Topic Priority: 0~255, Default is 0 ## mqtt.queue.priority = topic/1=10,topic/2=8 ## Max queue length. Enqueued messages when persistent client disconnected, ## or inflight window is full. mqtt.queue.max_length = infinity ## Low-water mark of queued messages mqtt.queue.low_watermark = 20% ## High-water mark of queued messages mqtt.queue.high_watermark = 60% ## Queue Qos0 messages? mqtt.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? | +----------------------+---------------------------------------------------+ ---------------------- Sys Interval of Broker ---------------------- .. code-block:: properties ## System Interval of publishing broker $SYS Messages mqtt.broker.sys_interval = 60 ----------------- PubSub Parameters ----------------- .. code-block:: properties ## PubSub Pool Size. Default should be scheduler numbers. mqtt.pubsub.pool_size = 8 mqtt.pubsub.by_clientid = true ##TODO: Subscribe Asynchronously mqtt.pubsub.async = true ---------------------- MQTT Bridge Parameters ---------------------- .. code-block:: properties ## Bridge Queue Size mqtt.bridge.max_queue_len = 10000 ## Ping Interval of bridge node. Unit: Second mqtt.bridge.ping_down_interval = 1 ------------------- Plugins' Etc Folder ------------------- .. code-block:: properties ## Dir of plugins' config mqtt.plugins.etc_dir = etc/plugins/ ## File to store loaded plugin names. mqtt.plugins.loaded_file = data/loaded_plugins ---------------- Extended Modules ---------------- Enable `Retainer` Module ------------------------ .. code-block:: properties ## Enable retainer module mqtt.module.retainer = on ## disc: disc_copies, ram: ram_copies mqtt.module.retainer.storage_type = ram ## Max number of retained messages mqtt.module.retainer.max_message_num = 100000 ## Max Payload Size of retained message mqtt.module.retainer.max_payload_size = 64KB ## Expired after seconds, never expired if 0 mqtt.module.retainer.expired_after = 0 Enable `Presence` Module ------------------------ `Presence` module will publish presence message to $SYS topic when a client connected or disconnected: .. code-block:: properties ## Enable presence module ## Publish presence messages when client connected or disconnected. mqtt.module.presence = on mqtt.module.presence.qos = 0 Enable `Subscription` Module ---------------------------- `Subscription` module forces the client to subscribe some topics when connected to the broker: .. code-block:: properties # Enable subscription module mqtt.module.subscription = on mqtt.module.subscription.topics = $client/%c=1,$user/%u=1 -------------- MQTT Listeners -------------- Configure the TCP listeners for MQTT, MQTT(SSL), HTTP and HTTPS Protocols. The most important parameter for MQTT listener is `max_clients`: max concurrent clients allowed. The TCP Ports occupied by the *EMQ* broker by default: +-----------+-----------------------------------+ | 1883 | MQTT Port | +-----------+-----------------------------------+ | 8883 | MQTT(SSL) Port | +-----------+-----------------------------------+ | 8083 | MQTT(WebSocket), HTTP API Port | +-----------+-----------------------------------+ Listener Parameters: +-----------------------------+-------------------------------------------------------+ | mqtt.listener.*.acceptors | TCP Acceptor Pool | +-----------------------------+-------------------------------------------------------+ | mqtt.listener.*.max_clients | Maximum number of concurrent TCP connections allowed | +-----------------------------+-------------------------------------------------------+ | mqtt.listener.*.rate_limit | Maximum number of concurrent TCP connections allowed | +-----------------------------+-------------------------------------------------------+ TCP Listener - 1883 ------------------- .. code-block:: properties ## TCP Listener: 1883, 127.0.0.1:1883, ::1:1883 mqtt.listener.tcp = 1883 ## Size of acceptor pool mqtt.listener.tcp.acceptors = 8 ## Maximum number of concurrent clients mqtt.listener.tcp.max_clients = 1024 ## Rate Limit. Format is 'burst,rate', Unit is KB/Sec ## mqtt.listener.tcp.rate_limit = 100,10 ## TCP Socket Options mqtt.listener.tcp.backlog = 1024 ## mqtt.listener.tcp.recbuf = 4096 ## mqtt.listener.tcp.sndbuf = 4096 ## mqtt.listener.tcp.buffer = 4096 ## mqtt.listener.tcp.nodelay = true SSL Listener - 8883 ------------------- .. code-block:: properties ## SSL Listener: 8883, 127.0.0.1:8883, ::1:8883 mqtt.listener.ssl = 8883 ## Size of acceptor pool mqtt.listener.ssl.acceptors = 4 ## Maximum number of concurrent clients mqtt.listener.ssl.max_clients = 512 ## Rate Limit. Format is 'burst,rate', Unit is KB/Sec ## mqtt.listener.ssl.rate_limit = 100,10 ## SSL Options mqtt.listener.ssl.handshake_timeout = 15 mqtt.listener.ssl.keyfile = etc/certs/key.pem mqtt.listener.ssl.certfile = etc/certs/cert.pem mqtt.listener.ssl.cacertfile = etc/certs/cacert.pem ## mqtt.listener.ssl.verify = verify_peer ## mqtt.listener.ssl.failed_if_no_peer_cert = true HTTP/WS Listener - 8083 ----------------------- .. code-block:: properties ## HTTP and WebSocket Listener mqtt.listener.http = 8083 mqtt.listener.http.acceptors = 4 mqtt.listener.http.max_clients = 64 HTTPS/WSS Listener - 8084 ------------------------- .. code-block:: properties ## HTTP(SSL) Listener mqtt.listener.https = 8084 mqtt.listener.https.acceptors = 4 mqtt.listener.https.max_clients = 64 mqtt.listener.https.handshake_timeout = 10 mqtt.listener.https.certfile = etc/certs/cert.pem mqtt.listener.https.keyfile = etc/certs/key.pem mqtt.listener.https.cacertfile = etc/certs/cacert.pem ## 开启双向认证 ## mqtt.listener.https.verify = verify_peer ## mqtt.listener.https.failed_if_no_peer_cert = true -------------- System Monitor -------------- .. code-block:: properties ## Long GC, don't monitor in production mode for: sysmon.long_gc = false ## Long Schedule(ms) sysmon.long_schedule = 240 ## 8M words. 32MB on 32-bit VM, 64MB on 64-bit VM. sysmon.large_heap = 8MB ## Busy Port sysmon.busy_port = false ## Busy Dist Port sysmon.busy_dist_port = true -------------------------- Plugin Configuration Files -------------------------- +----------------------------------------+-----------------------------------+ | File | Description | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_auth_username.conf | Username/Password Auth Plugin | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_auth_clientid.conf | ClientId Auth Plugin | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_auth_http.conf | HTTP Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_auth_mongo.conf | MongoDB Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_auth_mysql.conf | MySQL Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_auth_pgsql.conf | Postgre Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_auth_redis.conf | Redis Auth/ACL Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_coap.conf | CoAP Protocol Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_dashboard.conf | Dashboard Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_plugin_template.conf | Template Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_recon.conf | Recon Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_reloader.conf | Reloader Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_sn.conf | MQTT-SN Protocal Plugin Config | +----------------------------------------+-----------------------------------+ | etc/plugins/emq_stomp.conf | Stomp Protocl Plugin Config | +----------------------------------------+-----------------------------------+