Add documenation for SSL configurations

etc/emq.conf

@@ -841,10 +841,21 @@ listener.ssl.external.access.1 = allow all
 ## Value: Duration
 listener.ssl.external.handshake_timeout = 15s
 
+## Path to the file containing the user's private PEM-encoded key.
+## More information at: http://erlang.org/doc/man/ssl.html
+##
+## Value: File
 listener.ssl.external.keyfile = {{ platform_etc_dir }}/certs/key.pem
 
+## Path to a file containing the user certificate.
+##
+## Value: File
 listener.ssl.external.certfile = {{ platform_etc_dir }}/certs/cert.pem
 
+## Path to a file containing PEM-encoded CA certificates. The CA certificates
+## are used during server authentication and when building the client certificate chain.
+##
+## Value: File
 ## listener.ssl.external.cacertfile = {{ platform_etc_dir }}/certs/cacert.pem
 
 ## The Ephemeral Diffie-Helman key exchange is a very effective way of
@@ -860,114 +871,238 @@ listener.ssl.external.certfile = {{ platform_etc_dir }}/certs/cert.pem
 ## 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
+##
+## Value: File
 ## listener.ssl.external.dhfile = {{ platform_etc_dir }}/certs/dh-params.pem
 
+## A server only does x509-path validation in mode verify_peer,
+## as it then sends a certificate request to the client (this
+## message is not sent if the verify option is verify_none).
+## You can then also want to specify option fail_if_no_peer_cert.
+## More information at: http://erlang.org/doc/man/ssl.html
+##
+## Value: verify_peer | verify_none
 ## listener.ssl.external.verify = verify_peer
 
+## Used together with {verify, verify_peer} by an SSL server. If set to true,
+## the server fails if the client does not have a certificate to send, that is,
+## sends an empty certificate.
+##
+## Value: true | false
 ## listener.ssl.external.fail_if_no_peer_cert = true
 
-### This is the single most important configuration option of an Erlang SSL application.
+## This is the single most important configuration option of an Erlang SSL application.
-### Ciphers (and their ordering) define the way the client and server encrypt information
+## Ciphers (and their ordering) define the way the client and server encrypt information
-### over the wire, from the initial Diffie-Helman key exchange, the session key encryption
+## over the wire, from the initial Diffie-Helman key exchange, the session key encryption
-### algorithm and the message digest algorithm. Selecting a good cipher suite is critical
+## algorithm and the message digest algorithm. Selecting a good cipher suite is critical
-### for the application’s data security, confidentiality and performance.
+## for the application’s data security, confidentiality and performance.
-### The cipher list above offers:
+## The cipher list above offers:
-###
+##
-### A good balance between compatibility with older browsers. It can get stricter for Machine-To-Machine scenarios.
+## A good balance between compatibility with older browsers. It can get stricter for Machine-To-Machine scenarios.
-### Perfect Forward Secrecy.
+## Perfect Forward Secrecy.
-### No old/insecure encryption and HMAC algorithms
+## No old/insecure encryption and HMAC algorithms
-###
+##
-### Most of it was copied from Mozilla’s Server Side TLS article
+## Most of it was copied from Mozilla’s Server Side TLS article
+##
+## Value: Ciphers
 ## listener.ssl.external.ciphers = ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-ECDSA-AES256-SHA384,ECDHE-RSA-AES256-SHA384,ECDHE-ECDSA-DES-CBC3-SHA,ECDH-ECDSA-AES256-GCM-SHA384,ECDH-RSA-AES256-GCM-SHA384,ECDH-ECDSA-AES256-SHA384,ECDH-RSA-AES256-SHA384,DHE-DSS-AES256-GCM-SHA384,DHE-DSS-AES256-SHA256,AES256-GCM-SHA384,AES256-SHA256,ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES128-SHA256,ECDHE-RSA-AES128-SHA256,ECDH-ECDSA-AES128-GCM-SHA256,ECDH-RSA-AES128-GCM-SHA256,ECDH-ECDSA-AES128-SHA256,ECDH-RSA-AES128-SHA256,DHE-DSS-AES128-GCM-SHA256,DHE-DSS-AES128-SHA256,AES128-GCM-SHA256,AES128-SHA256,ECDHE-ECDSA-AES256-SHA,ECDHE-RSA-AES256-SHA,DHE-DSS-AES256-SHA,ECDH-ECDSA-AES256-SHA,ECDH-RSA-AES256-SHA,AES256-SHA,ECDHE-ECDSA-AES128-SHA,ECDHE-RSA-AES128-SHA,DHE-DSS-AES128-SHA,ECDH-ECDSA-AES128-SHA,ECDH-RSA-AES128-SHA,AES128-SHA
 
-### SSL parameter renegotiation is a feature that allows a client and 
+## SSL parameter renegotiation is a feature that allows a client and
-### a server to renegotiate the parameters of the SSL connection on the fly.
+## a server to renegotiate the parameters of the SSL connection on the fly.
-### RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,
+## RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,
-### you drop support for the insecure renegotiation, prone to MitM attacks. 
+## you drop support for the insecure renegotiation, prone to MitM attacks.
+##
+## Value: on | off
 ## listener.ssl.external.secure_renegotiate = off
 
-### A performance optimization setting, it allows clients to reuse 
+## A performance optimization setting, it allows clients to reuse
-### pre-existing sessions, instead of initializing new ones.
+## pre-existing sessions, instead of initializing new ones.
-### Read more about it here.
+## Read more about it here.
+## More information at: http://erlang.org/doc/man/ssl.html
+##
+## Value: on | off
 ## listener.ssl.external.reuse_sessions = on
 
-### An important security setting, it forces the cipher to be set based on
+## An important security setting, it forces the cipher to be set based
-### the server-specified order instead of the client-specified order,
+## on the server-specified order instead of the client-specified order,
-### hence enforcing the (usually more properly configured) security
+## hence enforcing the (usually more properly configured) security
-### ordering of the server administrator.
+## ordering of the server administrator.
+##
+## Value: on | off
 ## listener.ssl.external.honor_cipher_order = on
 
-### Use the CN or DN value from the client certificate as a username.
+## Use the CN or DN value from the client certificate as a username.
-### Notice: 'verify' should be configured as 'verify_peer'
+## Notice that 'verify' should be set as 'verify_peer'.
+##
+## Value: cn | dn
 ## listener.ssl.external.peer_cert_as_username = cn
 
-## SSL Socket Options
+## TCP backlog for the SSL connection.
+## See 'listener.tcp.external.backlog'
+##
+## Value: Number >= 0
 ## listener.ssl.external.backlog = 1024
 
+## The TCP send timeout for the SSL connection.
+## See 'listener.tcp.external.send_timeout'
+##
+## Value: Duration
 ## listener.ssl.external.send_timeout = 15s
 
+## See 'listener.tcp.external.send_timeout_close'
+##
+## Value: on | off
 ## listener.ssl.external.send_timeout_close = on
 
+## See 'listener.tcp.external.recbuf'
+##
+## Value: Bytes
 ## listener.ssl.external.recbuf = 4KB
 
+## See 'listener.tcp.external.sndbuf'
+##
+## Value: Bytes
 ## listener.ssl.external.sndbuf = 4KB
 
+## See 'listener.tcp.external.buffer'
+##
+## Value: Bytes
 ## listener.ssl.external.buffer = 4KB
 
+## See 'listener.tcp.external.nodelay'
+##
+## Value: true | false
 ## listener.ssl.external.nodelay = true
 
 ##--------------------------------------------------------------------
-## External MQTT/WebSocket Listener
+## External WebSocket Listener for MQTT Protocol
 
+## listener.ws.<name> is the IP address and port that the MQTT/Websocket
+## listener will bind.
+##
+## Value: IP:Port | Port
+##
+## Examples: 8083, 127.0.0.1:8083, ::1:8083
 listener.ws.external = 8083
 
+## The acceptor pool for external MQTT/Websocket listener.
+##
+## Value: Number
 listener.ws.external.acceptors = 4
 
+## Maximum number of concurrent MQTT/Websocket connections.
+##
+## Value: Number
 listener.ws.external.max_clients = 64
 
+## TODO: Zone of the external MQTT/Websocket listener belonged to.
+##
+## Value: String
 ## listener.ws.external.zone = external
 
+## Mountpoint of the MQTT/Websocket Listener. All the topics of
+## this listener will be prefixed with the mount point if this
+## option is enabled.
+##
+## Value: String
+## listener.ws.external.mountpoint = external/
+
+## The access control rules for the MQTT/Websocket listener.
+##
+## Value: ACL Rule
 listener.ws.external.access.1 = allow all
 
-## Proxy Protocol V1/2
+## Enable the Proxy Protocol V1/2 if the EMQ cluster is deployed behind
+## HAProxy or Nginx.
+##
+## Value: on | off
 ## listener.ws.external.proxy_protocol = on
+
+## See 'listener.tcp.external.proxy_protocol_timeout'
+##
+## Value: Duration
 ## listener.ws.external.proxy_protocol_timeout = 3s
 
 ## TCP Options
 listener.ws.external.backlog = 1024
 
+## See 'listener.tcp.external.send_timeout'
+##
+## Value: Duration
 listener.ws.external.send_timeout = 15s
 
+## See 'listener.tcp.external.send_timeout_close'
+##
+## Value: on | off
 listener.ws.external.send_timeout_close = on
 
-listener.ws.external.recbuf = 4KB
+## See 'listener.tcp.external.recbuf'
+##
+## Value: Bytes
+## listener.ws.external.recbuf = 4KB
 
-listener.ws.external.sndbuf = 4KB
+## See 'listener.tcp.external.sndbuf'
+##
+## Value: Bytes
+## listener.ws.external.sndbuf = 4KB
 
-listener.ws.external.buffer = 4KB
+## See 'listener.tcp.external.buffer'
+##
+## Value: Bytes
+## listener.ws.external.buffer = 4KB
 
+## See 'listener.tcp.external.nodelay'
+##
+## Value: true | false
 listener.ws.external.nodelay = true
 
 ##--------------------------------------------------------------------
-## External MQTT/WebSocket/SSL Listener
+## External WebSocket/SSL listener for MQTT Protocol
 
+## listener.wss.<name> is the IP address and port that the MQTT/Websocket/SSL
+## listener will bind.
+##
+## Value: IP:Port | Port
+##
+## Examples: 8084, 127.0.0.1:8084, ::1:8084
 listener.wss.external = 8084
 
+## The acceptor pool for external MQTT/Websocket/SSL listener.
+##
+## Value: Number
 listener.wss.external.acceptors = 4
 
+## Maximum number of concurrent MQTT/Webwocket/SSL connections.
+##
+## Value: Number
 listener.wss.external.max_clients = 64
 
+## TODO: Zone of the external MQTT/Websocket/SSL listener belonged to.
+##
+## Value: String
 ## listener.wss.external.zone = external
 
+## See 'listener.ssl.external.mountpoint'
+##
+## Value: String
+## listener.wss.external.mountpoint = inbound/
+
+## See 'listener.ssl.external.acess.1'
+##
+## Value: ACL Rule
 listener.wss.external.access.1 = allow all
 
-## Proxy Protocol V1/2
+## See 'listener.ssl.external.proxy_protocol'
+##
+## Value: on | off
 ## listener.wss.external.proxy_protocol = on
+
+## See 'listener.ssl.external.proxy_protocol_timeout'
+##
+## Value: Duration
 ## listener.wss.external.proxy_protocol_timeout = 3s
 
-## SSL Option
+## SSL Options. Same to 'listener.ssl.*'
-### SSL Options. See http://erlang.org/doc/man/ssl.html
-
 listener.wss.external.handshake_timeout = 15s
 
 listener.wss.external.keyfile = {{ platform_etc_dir }}/certs/key.pem
@@ -976,10 +1111,23 @@ listener.wss.external.certfile = {{ platform_etc_dir }}/certs/cert.pem
 
 ## listener.wss.external.cacertfile = {{ platform_etc_dir }}/certs/cacert.pem
 
+## listener.ssl.external.dhfile = {{ platform_etc_dir }}/certs/dh-params.pem
+
 ## listener.wss.external.verify = verify_peer
 
 ## listener.wss.external.fail_if_no_peer_cert = true
 
+## listener.wss.external.ciphers =
+
+## listener.wss.external.secure_renegotiate = off
+
+## listener.wss.external.reuse_sessions = on
+
+## listener.wss.external.honor_cipher_order = on
+
+## listener.wss.external.peer_cert_as_username = cn
+
+## TCP Options. Same to 'listener.tcp.*'
 listener.wss.external.backlog = 1024
 
 listener.wss.external.send_timeout = 15s

priv/emq.schema

@@ -702,8 +702,8 @@ end}.
 %%--------------------------------------------------------------------
 
 {mapping, "mqtt.broker.sys_interval", "emqttd.broker_sys_interval", [
-  {default, 60},
+  {datatype, {duration, ms}},
-  {datatype, integer}
+  {default, "1m"}
 ]}.
 
 %%--------------------------------------------------------------------
@@ -735,8 +735,8 @@ end}.
 ]}.
 
 {mapping, "mqtt.bridge.ping_down_interval", "emqttd.bridge", [
-  {default, 1},
+  {datatype, {duration, ms}},
-  {datatype, integer}
+  {default, "1s"}
 ]}.
 
 {translation, "emqttd.bridge", fun(Conf) ->