Add more documentation for emq.conf

etc/emq.conf

@@ -6,12 +6,12 @@
 ## Cluster
 ##--------------------------------------------------------------------
 
-## Cluster name
+## Cluster name.
 cluster.name = emqcl
 
 ## Cluster auto-discovery strategy.
 ##
-## Enum Values:
+## Value: Enum
 ## - manual: Manual join command
 ## - static: Static node list
 ## - mcast:  IP Multicast
@@ -22,106 +22,229 @@ cluster.name = emqcl
 ## Default: manual
 cluster.discovery = manual
 
-## Cluster Autoheal: on | off
+## Enable cluster autoheal from network partition.
+##
+## Value: on | off
+##
+## Default: on
 cluster.autoheal = on
 
-## Clean down node of the cluster
+## AutoClean down node after this duration.
+##
+## Value: time duration with units
+## -h: hour, e.g. '2h' for 2 hours
+## -m: minute, e.g. '5m' for 5 minutes
+## -s: second, e.g. '30s' for 30 seconds
+##
+## Default: 5m
 cluster.autoclean = 5m
 
 ##--------------------------------------------------------------------
-## Cluster with static node list
+## Cluster using static node list
 
+## Node list of the cluster.
+##
+## Value: String
 ## cluster.static.seeds = emq1@127.0.0.1,emq2@127.0.0.1
 
 ##--------------------------------------------------------------------
-## Cluster with multicast
+## Cluster using IP Multicast.
 
+## IP Multicast Address.
+##
+## Value: IP Address
 ## cluster.mcast.addr = 239.192.0.1
 
+## Multicast Ports.
+##
+## Value: Port List
 ## cluster.mcast.ports = 4369,4370
 
+## Multicast Iface.
+##
+## Value: Iface Address
+##
+## Default: 0.0.0.0
 ## cluster.mcast.iface = 0.0.0.0
 
+## Multicast Ttl.
+##
+## Value: 0-255
+##
+## Default: 255
 ## cluster.mcast.ttl = 255
 
+## Multicast loop.
+##
+## Value: on | off
 ## cluster.mcast.loop = on
 
 ##--------------------------------------------------------------------
-## Cluster with DNS
+## Cluster using DNS A records.
 
+## DNS name.
+##
+## Value: String
 ## cluster.dns.name = localhost
 
+## The App name is used to build 'node.name' with IP address.
+##
+## Value: String
 ## cluster.dns.app = emq
 
 ##--------------------------------------------------------------------
-## Cluster with Etcd
+## Cluster using etcd
 
+## Etcd server list, seperated by ','.
+##
+## Value: String
 ## cluster.etcd.server = http://127.0.0.1:2379
 
+## The prefix helps build nodes path in etcd. Each node in the cluster
+## will create a path in etcd: v2/keys/{prefix}/{cluster.name}/{node.name}
+##
+## Value: String
 ## cluster.etcd.prefix = emqcl
 
+## The TTL for node's path in etcd.
+##
+## Value: Duration
+##
+## Default: 1m, 1 minute
 ## cluster.etcd.node_ttl = 1m
 
 ##--------------------------------------------------------------------
-## Cluster with k8s
+## Cluster using Kubernates
 
+## Kubernates API server list, seperated by ','.
+##
+## Value: String
 ## cluster.k8s.apiserver = http://10.110.111.204:8080
 
+## The service name helps build node name: {service_name}@{ip}
+##
+## Value: String
 ## cluster.k8s.service_name = emq
 
-## Address Type: ip | dns
+## The address type is used to extract host from k8s service.
+##
+## Value: ip | dns
 ## cluster.k8s.address_type = ip
 
-## The Erlang application name 
+## The app name helps build 'node.name'.
+##
+## Value: String
 ## cluster.k8s.app_name = emq
 
 ##--------------------------------------------------------------------
 ## Node Args
 ##--------------------------------------------------------------------
 
-## Node name
+## Node name.
+##
+## Value: {name}@{host}
+##
+## Default: emq@127.0.0.1
 node.name = emq@127.0.0.1
 
-## Cookie for distributed node
+## Cookie for distributed node communication.
+##
+## Value: String
 node.cookie = emqsecretcookie
 
-## SMP support: enable, auto, disable
+## Enable SMP support of Erlang VM.
+##
+## Value: enable | auto | disable
 node.smp = auto
 
+## Heartbeat monitoring of an Erlang runtime system. Comment the line to disable
+## heartbeat, or set the value as 'on'
+## or the line comment.
+##
+## Value: on
+##
 ## vm.args: -heart
-## Heartbeat monitoring of an Erlang runtime system
-## Value should be 'on' or comment the line
 ## node.heartbeat = on
 
-## Enable kernel poll
+## Enable Kernel Poll.
+##
+## Value: on | off
+##
+## Default: on
 node.kernel_poll = on
 
-## async thread pool
+## Sets the number of threads in async thread pool. Valid range is 0-1024.
+## More information at: http://erlang.org/doc/man/erl.html
+##
+## Value: 0-1024
+##
+## vm.args: +A Number
 node.async_threads = 32
 
-## Erlang Process Limit
+## Sets the maximum number of simultaneously existing processes for this
+## system if a Number is passed as value.
+## More information at: http://erlang.org/doc/man/erl.html
+##
+## Value: Number [1024-134217727]
+##
+## vm.args: +P Number
 node.process_limit = 256000
 
 ## Sets the maximum number of simultaneously existing ports for this system
+## if a Number is passed as value.
+## More information at: http://erlang.org/doc/man/erl.html
+##
+## Value: Number [1024-134217727]
+##
+## vm.args: +Q Number
 node.max_ports = 65536
 
-## Set the distribution buffer busy limit (dist_buf_busy_limit)
+## Set the distribution buffer busy limit (dist_buf_busy_limit).
-node.dist_buffer_size = 32MB
+## More information at: http://erlang.org/doc/man/erl.html
+##
+## Value: Number [1KB-2GB]
+##
+## vm.args: +zdbbl size
+node.dist_buffer_size = 16MB
 
-## Max ETS Tables.
+## Sets the maximum number of ETS tables. Note that mnesia and SSL
-## Note that mnesia and SSL will create temporary ets tables.
+## will create temporary ETS tables.
+##
+## Value: Number
+##
+## vm.args: +e Number
 node.max_ets_tables = 256000
 
-## Tweak GC to run more often
+## Tweak GC to run more often.
+##
+## Value: Number [0-65535]
+##
+## vm.args: -env ERL_FULLSWEEP_AFTER Number
 node.fullsweep_after = 1000
 
-## Crash dump
+## Crash dump log file.
+##
+## Value: Log file
 node.crash_dump = {{ platform_log_dir }}/crash.dump
 
-## Distributed node ticktime
+## Specifies the net_kernel tick time. TickTime is specified in seconds.
+## Notice that all communicating nodes are to have the same TickTime
+## value specified.
+##
+## More information at: http://www.erlang.org/doc/man/kernel_app.html#net_ticktime
+##
+## Value: Number
+##
+## vm.args: -kernel net_ticktime Number
 node.dist_net_ticktime = 60
 
-## Distributed node port range
+## Sets the port range for the listener socket of a distributed Erlang node.
+## Note that if there is a firewall between clustered nodes, this port segment
+## for nodes’ communication should be allowed.
+##
+## More information at: http://www.erlang.org/doc/man/kernel_app.html
+##
+## Value: Port [1024-65535]
 node.dist_listen_min = 6369
 node.dist_listen_max = 6379
 
@@ -129,150 +252,244 @@ node.dist_listen_max = 6379
 ## Log
 ##--------------------------------------------------------------------
 
-## Set the log dir
+## Sets the log dir.
+##
+## Value: Folder
 log.dir = {{ platform_log_dir }}
 
-## Console log. Enum: off, file, console, both
+## Where to emit the console logs.
+##
+## Value: off | file | console | both
+## - off: disabled
+## - file: write to file
+## - console: write to stdout
+## - both: file and stdout
 log.console = console
 
-## Console log level. Enum: debug, info, notice, warning, error, critical, alert, emergency
+## Sets the severity level of console log.
+##
+## Value: debug | info | notice | warning | error | critical | alert | emergency
+##
+## Default: error
 log.console.level = error
 
-## Console log file
+## The file where console logs will be writed to, when 'log.console' is set to 'file'.
+##
+## Value: File Name 
 ## log.console.file = {{ platform_log_dir }}/console.log
 
-## Console log file size
+## Maximum file size for console log.
+##
+## Value: Number(bytes)
 ## log.console.size = 10485760
 
-## Console log count size
+## The rotation count for console log.
+##
+## Value: Number
 ## log.console.count = 5
 
-## Info log file
+## The file where info logs will be writed to.
+##
+## Value: File Name
 ## log.info.file = {{ platform_log_dir }}/info.log
 
-## Info log file size
+## Maximum file size for info log.
+##
+## Value: Number(bytes)
 ## log.info.size = 10485760
 
-## Info log file count
+## The rotation count for info log.
+##
+## Value: Number
 ## log.info.count = 5
 
-## Error log file
+## The file where error logs will be writed to.
+##
+## Value: File Name
 log.error.file = {{ platform_log_dir }}/error.log
 
-## Error log file size
+## Maximum file size for error log.
+##
+## Value: Number(bytes)
 log.error.size = 10485760
 
-## Error log file count
+## The rotation count for error log.
+##
+## Value: Number
 log.error.count = 5
 
-## Enable the crash log. Enum: on, off
+## Enable the crash log.
+##
+## Value: on | off
 log.crash = on
 
+## The file for crash log.
+##
+## Value: File Name
 log.crash.file = {{ platform_log_dir }}/crash.log
 
-## Syslog. Enum: on, off
+## Enable Syslog.
+##
+## Values: on | off
 log.syslog = on
 
-##  syslog level. Enum: debug, info, notice, warning, error, critical, alert, emergency
+## The severity level for syslog.
+##
+## Value: debug | info | notice | warning | error | critical | alert | emergency
 log.syslog.level = error
 
 ##--------------------------------------------------------------------
-## Allow Anonymous and Default ACL
+## Allow Anonymous Authentication and Default ACL
 ##--------------------------------------------------------------------
 
-## Allow Anonymous authentication
+## Allow Anonymous Authentication.
+## !!! Notice: Should disable the config for production deployment.
+##
+## Value: true | false
 mqtt.allow_anonymous = true
 
-## ACL nomatch
+## Default behaviour when ACL nomatch.
+##
+## Value: allow | deny
 mqtt.acl_nomatch = allow
 
-## Default ACL File
+## Default ACL File.
+##
+## Value: File Name
 mqtt.acl_file = {{ platform_etc_dir }}/acl.conf
 
-## Cache ACL for PUBLISH
+## Cache ACL for PUBLISH Messages.
+##
+## Value: true | false
 mqtt.cache_acl = true
 
 ##--------------------------------------------------------------------
 ## MQTT Protocol
 ##--------------------------------------------------------------------
 
-## Max ClientId Length Allowed.
+## Maximum MQTT clientId length allowed.
+##
+## Value: Number [23-65535]
 mqtt.max_clientid_len = 1024
 
-## Max Packet Size Allowed, 64K by default.
+## Maximum MQTT packet size allowed.
+##
+## Value: Bytes
+##
+## Default: 64K
 mqtt.max_packet_size = 64KB
 
-## Check Websocket Protocol Header. Enum: on, off
+## Check if the websocket protocol header is valid.
+## Turn off the config when developing WeChat App.
+##
+## Value: on | off
 mqtt.websocket_protocol_header = on
 
-## The Keepalive timeout: Keepalive * backoff * 2
+## The backoff for MQTT keepalive timeout.
+## The broker will kick a MQTT connection out until 'Keepalive * backoff * 2' timeout.
+##
+## Value: Float > 0.5
 mqtt.keepalive_backoff = 0.75
 
 ##--------------------------------------------------------------------
 ## MQTT Connection
 ##--------------------------------------------------------------------
 
-## Force GC: integer. Value 0 disabled the Force GC.
+## Force GC the MQTT connection. Value 0 will disable the Force GC.
+##
+## Value: Number >= 0 
 mqtt.conn.force_gc_count = 100
 
 ##--------------------------------------------------------------------
 ## MQTT Client
 ##--------------------------------------------------------------------
 
-## Client Idle Timeout (Second)
+## MQTT client idle timeout, specified in seconds.
+##
+## Value: Duration
 mqtt.client.idle_timeout = 30s
 
-## Max publish rate of Messages
+## Maximum publish rate of MQTT messages per second.
+## TODO: R2.4 release
+##
+## Value: Number
 ## mqtt.client.max_publish_rate = 5
 
-## Enable client Stats: on | off
+## Enable per client statistics.
+##
+## Value:  on | off
 mqtt.client.enable_stats = off
 
 ##--------------------------------------------------------------------
 ## MQTT Session
 ##--------------------------------------------------------------------
 
-## Max Number of Subscriptions, 0 means no limit.
+## Maximum number of subscriptions allowed, 0 means no limit.
+##
+## Value: Number
 mqtt.session.max_subscriptions = 0
 
-## Upgrade QoS?
+## Force to upgrade QoS according to subscription.
+##
+## Value: on | off
 mqtt.session.upgrade_qos = off
 
-## Max Size of the Inflight Window for QoS1 and QoS2 messages
+## Maximum size of the Inflight Window storing QoS1/2 messages delivered but unacked.
-## 0 means no limit
+##
+## Value: Number
 mqtt.session.max_inflight = 32
 
-## Retry Interval for redelivering QoS1/2 messages.
+## Retry interval for QoS1/2 message redelivering.
+##
+## Value: Duration
 mqtt.session.retry_interval = 20s
 
-## Client -> Broker: Max Packets Awaiting PUBREL, 0 means no limit
+## Maximum QoS2 packets (Client -> Broker) awaiting PUBREL, 0 means no limit.
-mqtt.session.max_awaiting_rel = 100
+##
+## Value: Number
+mqtt.session.max_awaiting_rel = 1000
 
-## Awaiting PUBREL Timeout
+## The QoS2 messages (Client -> Broker) will be dropped if awaiting PUBREL timeout.
-mqtt.session.await_rel_timeout = 20s
+##
+## Value: Duration
+mqtt.session.await_rel_timeout = 30s
 
-## Enable Statistics: on | off
+## Enable per session statistics.
+##
+## Value: on | off
 mqtt.session.enable_stats = on
 
-## Expired after 1 day:
+## Session expiration time.
-## w - week
+##
-## d - day
+## Value: Duration
-## h - hour
+## -d: day
-## m - minute
+## -h: hour
-## s - second
+## -m: minute
+## -s: second
+##
+## Default: 2h, 2 hours
 mqtt.session.expiry_interval = 2h
 
-## Ignore message from self publish
+## Ignore loop delivery of messages.
+##
+## Value: true | false
+##
+## Default: false
 mqtt.session.ignore_loop_deliver = false
 
 ##--------------------------------------------------------------------
 ## MQTT Message Queue
 ##--------------------------------------------------------------------
 
-## Type: simple | priority
+## Message Queue Type.
+##
+## Value: simple | priority
 mqtt.mqueue.type = simple
 
-## Topic Priority: 0~255, Default is 0
+## Topic Priority. Default is 0.
+##
+## Value: Number [0-255]
+##
 ## mqtt.mqueue.priority = topic/1=10,topic/2=8
 
 ## Max queue length. Enqueued messages when persistent client disconnected,
@@ -474,7 +691,7 @@ listener.ssl.external.certfile = {{ platform_etc_dir }}/certs/cert.pem
 ### algorithm and the message digest algorithm. Selecting a good cipher suite is critical
 ### for the application’s data security, confidentiality and performance.
 ### The cipher list above offers:
-### 
+###
 ### A good balance between compatibility with older browsers. It can get stricter for Machine-To-Machine scenarios.
 ### Perfect Forward Secrecy.
 ### No old/insecure encryption and HMAC algorithms