From a17fae30e2fe58ad2cbc42d75b09fa95a5c62c6c Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Wed, 3 Jan 2018 22:44:54 +0800 Subject: [PATCH] Add more documentation for MQTT listeners --- etc/emq.conf | 375 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 299 insertions(+), 76 deletions(-) diff --git a/etc/emq.conf b/etc/emq.conf index 74f2b8a88..4cb8fc04b 100644 --- a/etc/emq.conf +++ b/etc/emq.conf @@ -492,50 +492,76 @@ mqtt.mqueue.type = simple ## ## mqtt.mqueue.priority = topic/1=10,topic/2=8 -## Max queue length. Enqueued messages when persistent client disconnected, +## Maximum queue length. Enqueued messages when persistent client disconnected, ## or inflight window is full. 0 means no limit. +## +## Value: Number >= 0 mqtt.mqueue.max_length = 1000 -## Low-water mark of queued messages +## Low-water mark of queued messages. +## +## Value: Percent mqtt.mqueue.low_watermark = 20% -## High-water mark of queued messages +## High-water mark of queued messages. +## +## Value: Percent mqtt.mqueue.high_watermark = 60% ## Queue Qos0 messages? +## +## Value: false | true mqtt.mqueue.store_qos0 = true ##-------------------------------------------------------------------- ## MQTT Broker and PubSub ##-------------------------------------------------------------------- -## System Interval of publishing broker $SYS Messages -mqtt.broker.sys_interval = 60 +## System Interval of publishing $SYS Messages. +## +## Value: Duration +## +## Default: 1m, 1 minute +mqtt.broker.sys_interval = 1m -## PubSub Pool Size. Default should be scheduler numbers. +## The PubSub pool size. Default value should be scheduler numbers. +## +## Value: Number > 1 mqtt.pubsub.pool_size = 8 -## Subscribe Asynchronously +## TODO: Subscribe Asynchronously. +## +## Value: true | false mqtt.pubsub.async = true ##-------------------------------------------------------------------- ## MQTT Bridge ##-------------------------------------------------------------------- -## Bridge Queue Size +## The pending message queue size of bridge. +## +## Value: Number mqtt.bridge.max_queue_len = 10000 -## Ping Interval of bridge node. Unit: Second -mqtt.bridge.ping_down_interval = 1 +## Ping interval of bridge node. +## +## Value: Duration +## +## Default: 1s, 1 second +mqtt.bridge.ping_down_interval = 1s ##------------------------------------------------------------------- ## MQTT Plugins ##------------------------------------------------------------------- -## Dir of plugins' config +## The etc dir for plugins' config. +## +## Value: Folder mqtt.plugins.etc_dir ={{ platform_etc_dir }}/plugins/ -## File to store loaded plugin names. +## The file to store loaded plugin names. +## +## Value: File mqtt.plugins.loaded_file = {{ platform_data_dir }}/loaded_plugins ##-------------------------------------------------------------------- @@ -543,134 +569,276 @@ mqtt.plugins.loaded_file = {{ platform_data_dir }}/loaded_plugins ##-------------------------------------------------------------------- ##-------------------------------------------------------------------- -## External TCP Listener +## MQTT/TCP - External TCP Listener for MQTT Protocol -## External TCP Listener: 1883, 127.0.0.1:1883, ::1:1883 +## listener.tcp. is the IP address and port that the MQTT/TCP +## listener will bind. +## +## Value: IP:Port | Port +## +## Examples: 1883, 127.0.0.1:1883, ::1:1883 listener.tcp.external = 0.0.0.0:1883 -## Size of acceptor pool +## The acceptor pool for external MQTT/TCP listener. +## +## Value: Number listener.tcp.external.acceptors = 16 -## Maximum number of concurrent clients +## Maximum number of concurrent MQTT/TCP connections. +## +## Value: Number listener.tcp.external.max_clients = 102400 -## TODO: +## TODO: Zone of the external MQTT/TCP listener belonged to. +## +## Value: String ## listener.tcp.external.zone = external -#listener.tcp.external.mountpoint = external/ +## Mountpoint of the MQTT/TCP Listener. All the topics of this +## listener will be prefixed with the mount point if this option +## is enabled. +## +## Value: String +## listener.tcp.external.mountpoint = external/ -## Rate Limit. Format is 'burst,rate', Unit is KB/Sec -#listener.tcp.external.rate_limit = 100,10 - -#listener.tcp.external.access.1 = allow 192.168.0.0/24 +## Rate limit for the external MQTT/TCP connections. +## Format is 'burst,rate'. +## +## Value: burst,rate +## Unit: KB/sec +## listener.tcp.external.rate_limit = 100,10 +## The access control rules for the MQTT/TCP listener. +## More information at: https://github.com/emqtt/esockd#allowdeny +## +## Value: ACL Rule +## listener.tcp.external.access.1 = allow 192.168.0.0/24 listener.tcp.external.access.2 = allow all -## Proxy Protocol V1/2 +## Enable the Proxy Protocol V1/2 if the EMQ cluster is deployed behind +## HAProxy or Nginx. +## More information at: https://www.haproxy.com/blog/haproxy/proxy-protocol/ +## +## Value: on | off ## listener.tcp.external.proxy_protocol = on + +## Sets the timeout for proxy protocol. EMQ will close the TCP connection +## if no proxy protocol packet recevied within the timeout. +## +## Value: Duration ## listener.tcp.external.proxy_protocol_timeout = 3s -### Use the PP2_SUBTYPE_SSL_CN field from Proxy Protocol V2 as a username. +## Enable the option for X.509 certificate based authentication. +## EMQ will Use the PP2_SUBTYPE_SSL_CN field in Proxy Protocol V2 +## as MQTT username. +## +## Value: cn ## listener.tcp.external.peer_cert_as_username = cn -## TCP Socket Options +## TCP socket options for the MQTT listener. + +## The TCP backlog defines the maximum length that the queue of pending +## connections can grow to. +## +## Value: Number >= 0 listener.tcp.external.backlog = 1024 +## The TCP send timeout for external MQTT connections. +## +## Value: Duration listener.tcp.external.send_timeout = 15s +## Close the TCP connection if send timeout. +## +## Value: on | off listener.tcp.external.send_timeout_close = on -#listener.tcp.external.recbuf = 4KB +## The TCP receive buffer(os kernel) for MQTT connections. +## More information at: http://erlang.org/doc/man/inet.html +## +## Value: Bytes +## listener.tcp.external.recbuf = 4KB -#listener.tcp.external.sndbuf = 4KB +## The TCP send buffer(os kernel) for MQTT connections. +## More information at: http://erlang.org/doc/man/inet.html +## +## Value: Bytes +## listener.tcp.external.sndbuf = 4KB -listener.tcp.external.buffer = 4KB +## The size of the user-level software buffer used by the driver. +## Not to be confused with options sndbuf and recbuf, which correspond +## to the Kernel socket buffers. It is recommended to have val(buffer) +## >= max(val(sndbuf),val(recbuf)) to avoid performance issues because +## of unnecessary copying. val(buffer) is automatically set to the above +## maximum when values sndbuf or recbuf are set. +## More information at: http://erlang.org/doc/man/inet.html +## +## Value: Bytes +## listener.tcp.external.buffer = 4KB +## Sets the 'buffer = max(sndbuf, recbuf)' if this option is enabled. +## +## Value: on | off +listener.tcp.external.tune_buffer = on + +## The TCP_NODELAY flag for MQTT connections. Small amounts of data are +## sent immediately if the option is enabled. +## +## Value: true | false listener.tcp.external.nodelay = true ##-------------------------------------------------------------------- -## Internal TCP Listener +## Internal TCP Listener for MQTT Protocol -## Internal TCP Listener: 11883, 127.0.0.1:11883, ::1:11883 +## The IP address and port that the internal MQTT/TCP protocol listener will +## bind. +## +## Value: IP:Port, Port +## +## Examples: 11883, 127.0.0.1:11883, ::1:11883 listener.tcp.internal = 127.0.0.1:11883 -## Size of acceptor pool -listener.tcp.internal.acceptors = 16 +## The acceptor pool for internal MQTT/TCP listener. +## +## Value: Number +listener.tcp.internal.acceptors = 4 -## Maximum number of concurrent clients +## Maximum number of concurrent MQTT/TCP connections. +## +## Value: Number listener.tcp.internal.max_clients = 102400 -#listener.tcp.internal.zone = internal +## TODO: Zone of the internal MQTT/TCP listener belonged to. +## +## Value: String +## listener.tcp.internal.zone = internal -#listener.tcp.external.mountpoint = internal/ +## Mountpoint of the MQTT/TCP Listener. All the topics will +## be prefixed with the mount point if this option is enabled. +## +## Value: String +## listener.tcp.external.mountpoint = internal/ -## Rate Limit. Format is 'burst,rate', Unit is KB/Sec +## Rate limit for the internal MQTT/TCP connections. +## Format is 'burst,rate'. +## +## Value: burst,rate +## Unit: KB/sec ## listener.tcp.internal.rate_limit = 1000,100 -## TCP Socket Options +## The TCP backlog defines the maximum length that the queue of +## pending connections can grow to. +## +## Value: Number >= 0 listener.tcp.internal.backlog = 512 -listener.tcp.internal.send_timeout = 15s +## The TCP send timeout for internal MQTT connections. +## +## Value: Duration +listener.tcp.internal.send_timeout = 5s +## Close the MQTT/TCP connection if send timeout. +## +## Value: on | off listener.tcp.external.send_timeout_close = on +## The TCP receive buffer(os kernel) for MQTT connections. +## More information at: http://erlang.org/doc/man/inet.html +## +## Value: Bytes +listener.tcp.internal.recbuf = 16KB + +## The TCP send buffer(os kernel) for MQTT connections. +## More information at: http://erlang.org/doc/man/inet.html +## +## Value: Bytes +listener.tcp.internal.sndbuf = 16KB + +## The size of the user-level software buffer used by the driver. +## See: listener.tcp.external.buffer +## +## Value: Bytes +listener.tcp.internal.buffer = 16KB + +## Sets the 'buffer = max(sndbuf, recbuf)' if this option is enabled. +## +## Value: on | off listener.tcp.internal.tune_buffer = on -listener.tcp.internal.buffer = 1MB - -listener.tcp.internal.recbuf = 4KB - -listener.tcp.internal.sndbuf = 1MB - -listener.tcp.internal.nodelay = true +## The TCP_NODELAY flag for MQTT connections. +## See: listener.tcp.external.nodelay +# +## Value: true | false +listener.tcp.internal.nodelay = false ##-------------------------------------------------------------------- -## External SSL Listener +## MQTT/SSL - External SSL Listener for MQTT Protocol -## SSL Listener: 8883, 127.0.0.1:8883, ::1:8883 +## listener.ssl. is the IP address and port that the MQTT/SSL +## listener will bind. +## +## Value: IP:Port | Port +## +## Examples: 8883, 127.0.0.1:8883, ::1:8883 listener.ssl.external = 8883 -## Size of acceptor pool +## The acceptor pool for external MQTT/SSL listener. +## +## Value: Number listener.ssl.external.acceptors = 16 -## Maximum number of concurrent clients +## Maximum number of concurrent MQTT/SSL connections. +## +## Value: Number listener.ssl.external.max_clients = 1024 -## Authentication Zone +## TODO: Zone of the external MQTT/SSL listener belonged to. +## +## Value: String ## listener.ssl.external.zone = external +## Mountpoint of the MQTT/SSL Listener. All the topics of this +## listener will be prefixed with the mount point if this option +## is enabled. +## +## Value: String ## listener.ssl.external.mountpoint = inbound/ -## Rate Limit. Format is 'burst,rate', Unit is KB/Sec +## Rate limit for the external MQTT/SSL connections. +## Format is 'burst,rate'. +## +## Value: burst,rate +## Unit: KB/sec ## listener.ssl.external.rate_limit = 100,10 -## Proxy Protocol V1/2 +## Enable the Proxy Protocol V1/2 if the EMQ cluster is deployed behind +## HAProxy or Nginx. +## More information at: https://www.haproxy.com/blog/haproxy/proxy-protocol/ +## +## Value: on | off ## listener.ssl.external.proxy_protocol = on + +## Sets the timeout for proxy protocol. EMQ will close the TCP connection +## if no proxy protocol packet recevied within the timeout. +## +## Value: Duration ## listener.ssl.external.proxy_protocol_timeout = 3s +## The access control rules for the MQTT/SSL listener. +## More information at: https://github.com/emqtt/esockd#allowdeny +## +## Value: ACL Rule listener.ssl.external.access.1 = allow all -### SSL Options. See http://erlang.org/doc/man/ssl.html - -## Configuring SSL Options. See http://erlang.org/doc/man/ssl.html -### TLS only for POODLE attack +## TLS versions only to protect from POODLE attack. +## See http://erlang.org/doc/man/ssl.html +## +## Value: String ## listener.ssl.external.tls_versions = tlsv1.2,tlsv1.1,tlsv1 -### The Ephemeral Diffie-Helman key exchange is a very effective way of -### ensuring Forward Secrecy by exchanging a set of keys that never hit -### the wire. Since the DH key is effectively signed by the private key, -### it needs to be at least as strong as the private key. In addition, -### the default DH groups that most of the OpenSSL installations have -### are only a handful (since they are distributed with the OpenSSL -### package that has been built for the operating system it’s running on) -### and hence predictable (not to mention, 1024 bits only). - -### In order to escape this situation, first we need to generate a fresh, -### strong DH group, store it in a file and then use the option above, -### to force our SSL application to use the new DH group. Fortunately, -### OpenSSL provides us with a tool to do that. Simply run: -### openssl dhparam -out dh-params.pem 2048 - +## TLS Handshake timeout. +## +## Value: Duration listener.ssl.external.handshake_timeout = 15s listener.ssl.external.keyfile = {{ platform_etc_dir }}/certs/key.pem @@ -679,6 +847,19 @@ listener.ssl.external.certfile = {{ platform_etc_dir }}/certs/cert.pem ## listener.ssl.external.cacertfile = {{ platform_etc_dir }}/certs/cacert.pem +## The Ephemeral Diffie-Helman key exchange is a very effective way of +## ensuring Forward Secrecy by exchanging a set of keys that never hit +## the wire. Since the DH key is effectively signed by the private key, +## it needs to be at least as strong as the private key. In addition, +## the default DH groups that most of the OpenSSL installations have +## are only a handful (since they are distributed with the OpenSSL +## package that has been built for the operating system it’s running on) +## and hence predictable (not to mention, 1024 bits only). +## In order to escape this situation, first we need to generate a fresh, +## strong DH group, store it in a file and then use the option above, +## to force our SSL application to use the new DH group. Fortunately, +## OpenSSL provides us with a tool to do that. Simply run: +## openssl dhparam -out dh-params.pem 2048 ## listener.ssl.external.dhfile = {{ platform_etc_dir }}/certs/dh-params.pem ## listener.ssl.external.verify = verify_peer @@ -816,37 +997,79 @@ listener.wss.external.send_timeout_close = on ##-------------------------------------------------------------------- ## HTTP Management API Listener +## The IP Address and Port that the EMQ HTTP API will bind. +## +## Value: IP:Port | Port +## +## Default: 0.0.0.0:8080 listener.api.mgmt = 0.0.0.0:8080 +## The TCP Acceptor pool size. +## +## Value: Number listener.api.mgmt.acceptors = 4 +## Maximum concurrent HTTP clients allowed. +## +## Value: Number listener.api.mgmt.max_clients = 64 +## The access control rules for the listener. +## More information at: https://github.com/emqtt/esockd#allowdeny +## +## Value: ACL Rule listener.api.mgmt.access.1 = allow all +## The TCP backlog defines the maximum length that the queue of pending +## connections can grow to. +## +## Value: Number >= 0 listener.api.mgmt.backlog = 512 +## The TCP send timeout. +## +## Value: Duration listener.api.mgmt.send_timeout = 15s +## Close the TCP connection if send timeout. +## +## Value: on | off listener.api.mgmt.send_timeout_close = on ##------------------------------------------------------------------- ## System Monitor ##------------------------------------------------------------------- -## Long GC, don't monitor in production mode for: +## Enable Long GC monitoring. +## Notice: don't enable the monitor in production for: ## https://github.com/erlang/otp/blob/feb45017da36be78d4c5784d758ede619fa7bfd3/erts/emulator/beam/erl_gc.c#L421 +## +## Value: true | false sysmon.long_gc = false -## Long Schedule(ms) +## Enable Long Schedule(ms) monitoring. +## More information at: http://erlang.org/doc/man/erlang.html#system_monitor-2 +## +## Value: Number sysmon.long_schedule = 240 -## 8M words. 32MB on 32-bit VM, 64MB on 64-bit VM. +## Enable Large Heap monitoring. +## More information at: http://erlang.org/doc/man/erlang.html#system_monitor-2 +## +## Value: bytes +## +## Default: 8M words. 32MB on 32-bit VM, 64MB on 64-bit VM. sysmon.large_heap = 8MB -## Busy Port +## Enable Busy Port monitoring. +## More information at: http://erlang.org/doc/man/erlang.html#system_monitor-2 +## +## Value: true | false sysmon.busy_port = false -## Busy Dist Port +## Enable Busy Dist Port monitoring. +## More information at: http://erlang.org/doc/man/erlang.html#system_monitor-2 +## +## Value: true | false sysmon.busy_dist_port = true