Add more documentation for MQTT listeners

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
+## System Interval of publishing $SYS Messages.
-mqtt.broker.sys_interval = 60
+##
+## 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
+## Ping interval of bridge node.
-mqtt.bridge.ping_down_interval = 1
+##
+## 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.<name> 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
+## Rate limit for the external MQTT/TCP connections.
-#listener.tcp.external.rate_limit = 100,10
+## Format is 'burst,rate'.
-
+##
-#listener.tcp.external.access.1 = allow 192.168.0.0/24
+## 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
+## The acceptor pool for internal MQTT/TCP listener.
-listener.tcp.internal.acceptors = 16
+##
+## 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
+## The TCP_NODELAY flag for MQTT connections.
-
+## See: listener.tcp.external.nodelay
-listener.tcp.internal.recbuf = 4KB
+#
-
+## Value: true | false
-listener.tcp.internal.sndbuf = 1MB
+listener.tcp.internal.nodelay = false
-
-listener.tcp.internal.nodelay = true
 
 ##--------------------------------------------------------------------
-## External SSL Listener
+## MQTT/SSL - External SSL Listener for MQTT Protocol
 
-## SSL Listener: 8883, 127.0.0.1:8883, ::1:8883
+## listener.ssl.<name> 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
+## TLS versions only to protect from POODLE attack.
-
+## See http://erlang.org/doc/man/ssl.html
-## Configuring SSL Options. See http://erlang.org/doc/man/ssl.html
+##
-### TLS only for POODLE attack
+## Value: String
 ## listener.ssl.external.tls_versions = tlsv1.2,tlsv1.1,tlsv1
 
-### The Ephemeral Diffie-Helman key exchange is a very effective way of
+## TLS Handshake timeout.
-### 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,
+## Value: Duration
-### 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.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