yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore(schema): reformat schema fields descriptions

This commit is contained in:
Zaiming Shi 2021-09-22 10:36:38 +02:00
parent b1cf5bc1d4
commit 5bd67a49de
1 changed files with 51 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
apps/emqx/src/emqx_schema.erl
View File

@ -88,23 +88,26 @@ roots(high) ->
} }
, {"zones", , {"zones",
sc(map("name", ref("zone")), sc(map("name", ref("zone")),
#{ desc => "A zone is a set of configs grouped by the zone <code>name</code>. <br>" #{ desc =>
"For flexible configuration mapping, the <code>name</code> " """A zone is a set of configs grouped by the zone <code>name</code>.<br>
"can be set to a listener's <code>zone</code> config.<br>" For flexible configuration mapping, the <code>name</code>
"NOTE: A builtin zone named <code>default</code> is auto created " can be set to a listener's <code>zone</code> config.<br>
"and can not be deleted." NOTE: A builtin zone named <code>default</code> is auto created
and can not be deleted."""
})} })}
, {"mqtt", , {"mqtt",
sc(ref("mqtt"), sc(ref("mqtt"),
#{ desc => "Global MQTT configuration.<br>" #{ desc =>
"The configs here work as default values which can be overriden " """Global MQTT configuration.<br>
"in <code>zone</code> configs" The configs here work as default values which can be overriden
in <code>zone</code> configs"""
})} })}
, {"authentication", , {"authentication",
sc(hoconsc:lazy(hoconsc:array(map())), sc(hoconsc:lazy(hoconsc:array(map())),
#{ desc => "Default authentication configs for all MQTT listeners.<br>" #{ desc =>
"For per-listener overrides see <code>authentication</code> " """Default authentication configs for all MQTT listeners.<br>
"in listener configs" For per-listener overrides see <code>authentication</code>
in listener configs"""
})} })}
, {"authorization", , {"authorization",
sc(ref("authorization"), sc(ref("authorization"),
@ -956,7 +959,7 @@ common_ssl_opts_schema(Defaults) ->
#{ sensitive => true #{ sensitive => true
, nullable => true , nullable => true
, desc => , desc =>
"""String containing the user's password. Only used if the private """String containing the user's password. Only used if the private
keyfile is password-protected.""" keyfile is password-protected."""
}) })
} }
@ -967,7 +970,7 @@ keyfile is password-protected."""
"""All TLS/DTLS versions to be supported.<br> """All TLS/DTLS versions to be supported.<br>
NOTE: PSK ciphers are suppresed by 'tlsv1.3' version config<br> NOTE: PSK ciphers are suppresed by 'tlsv1.3' version config<br>
In case PSK cipher suites are intended, make sure to configured In case PSK cipher suites are intended, make sure to configured
<code>['tlsv1.2', 'tlsv1.1']</code> here<br>. <code>['tlsv1.2', 'tlsv1.1']</code> here.
""" """
}) })
} }
@ -982,9 +985,9 @@ In case PSK cipher suites are intended, make sure to configured
sc(boolean(), sc(boolean(),
#{ default => Df("secure_renegotiate", true) #{ default => Df("secure_renegotiate", true)
, desc => """ , desc => """
SSL parameter renegotiation is a feature that allows a client and a server SSL parameter renegotiation is a feature that allows a client and a server
to renegotiate the parameters of the SSL connection on the fly. 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.
""" """
}) })
@ -1003,9 +1006,9 @@ server_ssl_opts_schema(Defaults, IsRanchListener) ->
#{ default => D("dhfile") #{ default => D("dhfile")
, nullable => true , nullable => true
, desc => , desc =>
"""Path to a file containing PEM-encoded Diffie Hellman parameters """Path to a file containing PEM-encoded Diffie Hellman parameters
to be used by the server if a cipher suite using Diffie Hellman to be used by the server if a cipher suite using Diffie Hellman
key exchange is negotiated. If not specified, default parameters key exchange is negotiated. If not specified, default parameters
are used.<br> are used.<br>
NOTE: The dhfile option is not supported by TLS 1.3.""" NOTE: The dhfile option is not supported by TLS 1.3."""
}) })
@ -1015,10 +1018,10 @@ NOTE: The dhfile option is not supported by TLS 1.3."""
#{ default => Df("fail_if_no_peer_cert", false) #{ default => Df("fail_if_no_peer_cert", false)
, desc => , desc =>
""" """
Used together with {verify, verify_peer} by an TLS/DTLS server. Used together with {verify, verify_peer} by an TLS/DTLS server.
If set to true, the server fails if the client does not have a If set to true, the server fails if the client does not have a
certificate to send, that is, sends an empty certificate. certificate to send, that is, sends an empty certificate.
If set to false, it fails only if the client sends an invalid If set to false, it fails only if the client sends an invalid
certificate (an empty certificate is considered valid). certificate (an empty certificate is considered valid).
""" """
}) })
@ -1032,13 +1035,13 @@ certificate (an empty certificate is considered valid).
sc(boolean(), sc(boolean(),
#{ default => Df("client_renegotiation", true) #{ default => Df("client_renegotiation", true)
, desc => """ , desc => """
In protocols that support client-initiated renegotiation, In protocols that support client-initiated renegotiation,
the cost of resources of such an operation is higher for the server than the client. the cost of resources of such an operation is higher for the server than the client.
This can act as a vector for denial of service attacks. This can act as a vector for denial of service attacks.
The SSL application already takes measures to counter-act such attempts, The SSL application already takes measures to counter-act such attempts,
but client-initiated renegotiation can be strictly disabled by setting this option to false. but client-initiated renegotiation can be strictly disabled by setting this option to false.
The default value is true. Note that disabling renegotiation can result in The default value is true. Note that disabling renegotiation can result in
long-lived connections becoming unusable due to limits on long-lived connections becoming unusable due to limits on
the number of messages the underlying cipher suite can encipher. the number of messages the underlying cipher suite can encipher.
""" """
}) })
@ -1060,15 +1063,15 @@ client_ssl_opts_schema(Defaults) ->
#{ default => disable #{ default => disable
, desc => , desc =>
"""Specify the host name to be used in TLS Server Name Indication extension.<br> """Specify the host name to be used in TLS Server Name Indication extension.<br>
For instance, when connecting to \"server.example.net\", the genuine server For instance, when connecting to \"server.example.net\", the genuine server
which accedpts the connection and performs TSL handshake may differ from the which accedpts the connection and performs TSL handshake may differ from the
host the TLS client initially connects to, e.g. when connecting to an IP address host the TLS client initially connects to, e.g. when connecting to an IP address
or when the host has multiple resolvable DNS records <br> or when the host has multiple resolvable DNS records <br>
If not specified, it will default to the host name string which is used If not specified, it will default to the host name string which is used
to establish the connection, unless it is IP addressed used.<br> to establish the connection, unless it is IP addressed used.<br>
The host name is then also used in the host name verification of the peer The host name is then also used in the host name verification of the peer
certificate.<br> The special value 'disable' prevents the Server Name certificate.<br> The special value 'disable' prevents the Server Name
Indication extension from being sent and disables the hostname Indication extension from being sent and disables the hostname
verification check.""" verification check."""
})} })}
]. ].
@ -1090,22 +1093,22 @@ ciphers_schema(Default) ->
end end
, validator => fun validate_ciphers/1 , validator => fun validate_ciphers/1
, desc => , desc =>
"""TLS cipher suite names separated by comma, or as an array of strings """TLS cipher suite names separated by comma, or as an array of strings
<code>\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\"</code> or <code>\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\"</code> or
<code>[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"]</code]. <code>[\"TLS_AES_256_GCM_SHA384\",\"TLS_AES_128_GCM_SHA256\"]</code].
<br> <br>
Ciphers (and their ordering) define the way in which the Ciphers (and their ordering) define the way in which the
client and server encrypts information over the wire. client and server encrypts information over the wire.
Selecting a good cipher suite is critical for the Selecting a good cipher suite is critical for the
application's data security, confidentiality and performance. application's data security, confidentiality and performance.
The names should be in OpenSSL sting format (not RFC format). The names should be in OpenSSL sting format (not RFC format).
Default values and examples proveded by EMQ X config Default values and examples proveded by EMQ X config
documentation are all in OpenSSL format.<br> documentation are all in OpenSSL format.<br>
NOTE: Certain cipher suites are only compatible with NOTE: Certain cipher suites are only compatible with
specific TLS <code>versions</code> ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3') specific TLS <code>versions</code> ('tlsv1.1', 'tlsv1.2' or 'tlsv1.3')
incompatible cipher suites will be silently dropped. incompatible cipher suites will be silently dropped.
For instance, if only 'tlsv1.3' is given in the <code>versions</code>, For instance, if only 'tlsv1.3' is given in the <code>versions</code>,
configuring cipher suites for other versions will have no effect. configuring cipher suites for other versions will have no effect.
<br> <br>