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

docs: changes desc to ?DESC

This commit is contained in:
Shawn 2022-04-23 03:59:50 +08:00
parent 86863690ce
commit 093d121bb2
1 changed files with 84 additions and 292 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -102,11 +102,6 @@
-elvis([{elvis_style, god_modules, disable}]). -elvis([{elvis_style, god_modules, disable}]).
-define(IDLE_TIMOUT_DESC,
"Close transport-layer connections from the clients that have not sent MQTT CONNECT\n"
"message within this interval."
).
namespace() -> undefined. namespace() -> undefined.
roots() -> roots() ->
@ -295,12 +290,7 @@ fields("authorization") ->
default => allow, default => allow,
required => true, required => true,
%% TODO: make sources a reference link %% TODO: make sources a reference link
desc_id => fields_authorization_no_match, desc => ?DESC(fields_authorization_no_match)
desc =>
"Default access control action if the user or client matches no ACL rules,\n"
"or if no such user or client is found by the configurable authorization\n"
"sources such as built_in_database, an HTTP API, or a query against PostgreSQL.\n"
"Find more details in 'authorization.sources' config."
} }
)}, )},
{"deny_action", {"deny_action",
@ -309,8 +299,7 @@ fields("authorization") ->
#{ #{
default => ignore, default => ignore,
required => true, required => true,
desc_id => fields_authorization_deny_action, desc => ?DESC(fields_authorization_deny_action)
desc => "The action when the authorization check rejects an operation."
} }
)}, )},
{"cache", {"cache",
@ -326,8 +315,7 @@ fields("cache") ->
boolean(), boolean(),
#{ #{
default => true, default => true,
desc_id => fields_cache_enable, desc => ?DESC(fields_cache_enable)
desc => "Enable or disable the authorization cache."
} }
)}, )},
{"max_size", {"max_size",
@ -335,8 +323,7 @@ fields("cache") ->
range(1, 1048576), range(1, 1048576),
#{ #{
default => 32, default => 32,
desc_id => fields_cache_max_size, desc => ?DESC(fields_cache_max_size)
desc => "Maximum number of cached items."
} }
)}, )},
{"ttl", {"ttl",
@ -344,8 +331,7 @@ fields("cache") ->
duration(), duration(),
#{ #{
default => "1m", default => "1m",
desc_id => fields_cache_ttl, desc => ?DESC(fields_cache_ttl)
desc => "Time to live for the cached data."
} }
)} )}
]; ];
@ -586,8 +572,7 @@ fields("rate_limit") ->
hoconsc:union([infinity, integer()]), hoconsc:union([infinity, integer()]),
#{ #{
default => 1000, default => 1000,
desc_id => fields_rate_limit_max_conn_rate, desc => ?DESC(fields_rate_limit_max_conn_rate)
desc => "Maximum connections per second."
} }
)}, )},
{"conn_messages_in", {"conn_messages_in",
@ -595,8 +580,7 @@ fields("rate_limit") ->
hoconsc:union([infinity, comma_separated_list()]), hoconsc:union([infinity, comma_separated_list()]),
#{ #{
default => infinity, default => infinity,
desc_id => fields_rate_limit_conn_messages_in, desc => ?DESC(fields_rate_limit_conn_messages_in)
desc => "Message limit for the external MQTT connections."
} }
)}, )},
{"conn_bytes_in", {"conn_bytes_in",
@ -604,10 +588,7 @@ fields("rate_limit") ->
hoconsc:union([infinity, comma_separated_list()]), hoconsc:union([infinity, comma_separated_list()]),
#{ #{
default => infinity, default => infinity,
desc_id => fields_rate_limit_conn_bytes_in, desc => ?DESC(fields_rate_limit_conn_bytes_in)
desc =>
"Limit the rate of receiving packets for a MQTT connection.\n"
"The rate is counted by bytes of packets per second."
} }
)} )}
]; ];
@ -766,8 +747,7 @@ fields("listeners") ->
sc( sc(
map(name, ref("mqtt_tcp_listener")), map(name, ref("mqtt_tcp_listener")),
#{ #{
desc_id => fields_listeners_tcp, desc => ?DESC(fields_listeners_tcp),
desc => "TCP listeners",
required => {false, recursively} required => {false, recursively}
} }
)}, )},
@ -775,8 +755,7 @@ fields("listeners") ->
sc( sc(
map(name, ref("mqtt_ssl_listener")), map(name, ref("mqtt_ssl_listener")),
#{ #{
desc_id => fields_listeners_ssl, desc => ?DESC(fields_listeners_ssl),
desc => "SSL listeners",
required => {false, recursively} required => {false, recursively}
} }
)}, )},
@ -784,8 +763,7 @@ fields("listeners") ->
sc( sc(
map(name, ref("mqtt_ws_listener")), map(name, ref("mqtt_ws_listener")),
#{ #{
desc_id => fields_listeners_ws, desc => ?DESC(fields_listeners_ws),
desc => "HTTP websocket listeners",
required => {false, recursively} required => {false, recursively}
} }
)}, )},
@ -793,8 +771,7 @@ fields("listeners") ->
sc( sc(
map(name, ref("mqtt_wss_listener")), map(name, ref("mqtt_wss_listener")),
#{ #{
desc_id => fields_listeners_wss, desc => ?DESC(fields_listeners_wss),
desc => "HTTPS websocket listeners",
required => {false, recursively} required => {false, recursively}
} }
)}, )},
@ -802,8 +779,7 @@ fields("listeners") ->
sc( sc(
map(name, ref("mqtt_quic_listener")), map(name, ref("mqtt_quic_listener")),
#{ #{
desc_id => fields_listeners_quic, desc => ?DESC(fields_listeners_quic),
desc => "QUIC listeners",
required => {false, recursively} required => {false, recursively}
} }
)} )}
@ -866,23 +842,20 @@ fields("mqtt_quic_listener") ->
sc( sc(
boolean(), boolean(),
#{ default => true #{ default => true
, desc_id => fields_mqtt_quic_listener_enabled , desc => ?DESC(fields_mqtt_quic_listener_enabled)
, desc => "Enable QUIC listener."
} }
)}, )},
%% TODO: ensure cacertfile is configurable %% TODO: ensure cacertfile is configurable
{"certfile", {"certfile",
sc( sc(
string(), string(),
#{ desc => "Path to the certificate file." #{ desc => ?DESC(fields_mqtt_quic_listener_certfile)
, desc_id => fields_mqtt_quic_listener_certfile
} }
)}, )},
{"keyfile", {"keyfile",
sc( sc(
string(), string(),
#{ desc => "Path to the secret key file." #{ desc => ?DESC(fields_mqtt_quic_listener_keyfile)
, desc_id => fields_mqtt_quic_listener_keyfile
} }
)}, )},
{"ciphers", ciphers_schema(quic)}, {"ciphers", ciphers_schema(quic)},
@ -890,8 +863,7 @@ fields("mqtt_quic_listener") ->
sc( sc(
duration(), duration(),
#{ default => "15s" #{ default => "15s"
, desc_id => fields_mqtt_quic_listener_idle_timeout , desc => ?DESC(fields_mqtt_quic_listener_idle_timeout)
, desc => ?IDLE_TIMOUT_DESC
} }
)} )}
] ++ base_listener(); ] ++ base_listener();
@ -902,10 +874,7 @@ fields("ws_opts") ->
string(), string(),
#{ #{
default => "/mqtt", default => "/mqtt",
desc_id => fields_ws_opts_mqtt_path, desc => ?DESC(fields_ws_opts_mqtt_path)
desc =>
"WebSocket's MQTT protocol path. So the address of\n"
" EMQX Broker's WebSocket is: <code>ws://{ip}:{port}/mqtt</code>"
} }
)}, )},
{"mqtt_piggyback", {"mqtt_piggyback",
@ -913,9 +882,7 @@ fields("ws_opts") ->
hoconsc:enum([single, multiple]), hoconsc:enum([single, multiple]),
#{ #{
default => multiple, default => multiple,
desc_id => fields_ws_opts_mqtt_piggyback, desc => ?DESC(fields_ws_opts_mqtt_piggyback)
desc =>
"Whether a WebSocket message is allowed to contain multiple MQTT packets."
} }
)}, )},
{"compress", {"compress",
@ -923,11 +890,7 @@ fields("ws_opts") ->
boolean(), boolean(),
#{ #{
default => false, default => false,
desc_id => fields_ws_opts_compress, desc => ?DESC(fields_ws_opts_compress)
desc =>
"If <code>true</code>, compress WebSocket messages using <code>zlib</code>.<br/>\n"
"The configuration items under <code>deflate_opts</code> "
"belong to the compression-related parameter configuration."
} }
)}, )},
{"idle_timeout", {"idle_timeout",
@ -935,8 +898,7 @@ fields("ws_opts") ->
duration(), duration(),
#{ #{
default => "15s", default => "15s",
desc_id => fields_ws_opts_idle_timeout, desc => ?DESC(fields_mqtt_quic_listener_idle_timeout)
desc => ?IDLE_TIMOUT_DESC
} }
)}, )},
{"max_frame_size", {"max_frame_size",
@ -944,8 +906,7 @@ fields("ws_opts") ->
hoconsc:union([infinity, integer()]), hoconsc:union([infinity, integer()]),
#{ #{
default => infinity, default => infinity,
desc_id => fields_ws_opts_max_frame_size, desc => ?DESC(fields_ws_opts_max_frame_size)
desc => "The maximum length of a single MQTT packet."
} }
)}, )},
{"fail_if_no_subprotocol", {"fail_if_no_subprotocol",
@ -953,11 +914,7 @@ fields("ws_opts") ->
boolean(), boolean(),
#{ #{
default => true, default => true,
desc_id => fields_ws_opts_fail_if_no_subprotocol, desc => ?DESC(fields_ws_opts_fail_if_no_subprotocol)
desc =>
"If <code>true</code>, the server will return an error when\n"
" the client does not carry the <code>Sec-WebSocket-Protocol</code> field.\n"
" <br/>Note: WeChat applet needs to disable this verification."
} }
)}, )},
{"supported_subprotocols", {"supported_subprotocols",
@ -965,8 +922,7 @@ fields("ws_opts") ->
comma_separated_list(), comma_separated_list(),
#{ #{
default => "mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5", default => "mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5",
desc_id => fields_ws_opts_supported_subprotocols, desc => ?DESC(fields_ws_opts_supported_subprotocols)
desc => "Comma-separated list of supported subprotocols."
} }
)}, )},
{"check_origin_enable", {"check_origin_enable",
@ -974,11 +930,7 @@ fields("ws_opts") ->
boolean(), boolean(),
#{ #{
default => false, default => false,
desc_id => fields_ws_opts_check_origin_enable, desc => ?DESC(fields_ws_opts_check_origin_enable)
desc =>
"If <code>true</code>, <code>origin</code> HTTP header will be\n"
" validated against the list of allowed origins configured in <code>check_origins</code>\n"
" parameter."
} }
)}, )},
{"allow_origin_absence", {"allow_origin_absence",
@ -986,11 +938,7 @@ fields("ws_opts") ->
boolean(), boolean(),
#{ #{
default => true, default => true,
desc_id => fields_ws_opts_allow_origin_absence, desc => ?DESC(fields_ws_opts_allow_origin_absence)
desc =>
"If <code>false</code> and <code>check_origin_enable</code> is\n"
" <code>true</code>, the server will reject requests that don't have <code>origin</code>\n"
" HTTP header."
} }
)}, )},
{"check_origins", {"check_origins",
@ -998,8 +946,7 @@ fields("ws_opts") ->
hoconsc:array(binary()), hoconsc:array(binary()),
#{ #{
default => [], default => [],
desc_id => fields_ws_opts_check_origins, desc => ?DESC(fields_ws_opts_check_origins)
desc => "List of allowed origins.<br/>See <code>check_origin_enable</code>."
} }
)}, )},
{"proxy_address_header", {"proxy_address_header",
@ -1007,10 +954,7 @@ fields("ws_opts") ->
string(), string(),
#{ #{
default => "x-forwarded-for", default => "x-forwarded-for",
desc_id => fields_ws_opts_proxy_address_header, desc => ?DESC(fields_ws_opts_proxy_address_header)
desc =>
"HTTP header used to pass information about the client IP address.\n"
" Relevant when the EMQX cluster is deployed behind a load-balancer."
} }
)}, )},
{"proxy_port_header", {"proxy_port_header",
@ -1018,10 +962,7 @@ fields("ws_opts") ->
string(), string(),
#{ #{
default => "x-forwarded-port", default => "x-forwarded-port",
desc_id => fields_ws_opts_proxy_port_header, desc => ?DESC(fields_ws_opts_proxy_port_header)
desc =>
"HTTP header used to pass information about the client port.\n"
" Relevant when the EMQX cluster is deployed behind a load-balancer."
} }
)}, )},
{"deflate_opts", {"deflate_opts",
@ -1037,10 +978,7 @@ fields("tcp_opts") ->
integer(), integer(),
#{ #{
default => 100, default => 100,
desc_id => fields_tcp_opts_active_n, desc => ?DESC(fields_tcp_opts_active_n)
desc =>
"Specify the {active, N} option for this Socket.<br/>\n"
" See: https://erlang.org/doc/man/inet.html#setopts-2"
} }
)}, )},
{"backlog", {"backlog",
@ -1048,10 +986,7 @@ fields("tcp_opts") ->
integer(), integer(),
#{ #{
default => 1024, default => 1024,
desc_id => fields_tcp_opts_backlog, desc => ?DESC(fields_tcp_opts_backlog)
desc =>
"TCP backlog defines the maximum length that the queue of\n"
" pending connections can grow to."
} }
)}, )},
{"send_timeout", {"send_timeout",
@ -1059,8 +994,7 @@ fields("tcp_opts") ->
duration(), duration(),
#{ #{
default => "15s", default => "15s",
desc_id => fields_tcp_opts_send_timeout, desc => ?DESC(fields_tcp_opts_send_timeout)
desc => "The TCP send timeout for the connections."
} }
)}, )},
{"send_timeout_close", {"send_timeout_close",
@ -1068,29 +1002,25 @@ fields("tcp_opts") ->
boolean(), boolean(),
#{ #{
default => true, default => true,
desc_id => fields_tcp_opts_send_timeout_close, desc => ?DESC(fields_tcp_opts_send_timeout_close)
desc => "Close the connection if send timeout."
} }
)}, )},
{"recbuf", {"recbuf",
sc( sc(
bytesize(), bytesize(),
#{ desc => "The TCP receive buffer (OS kernel) for the connections." #{ desc => ?DESC(fields_tcp_opts_recbuf)
, desc_id => fields_tcp_opts_recbuf
} }
)}, )},
{"sndbuf", {"sndbuf",
sc( sc(
bytesize(), bytesize(),
#{ desc => "The TCP send buffer (OS kernel) for the connections." #{ desc => ?DESC(fields_tcp_opts_sndbuf)
, desc_id => fields_tcp_opts_sndbuf
} }
)}, )},
{"buffer", {"buffer",
sc( sc(
bytesize(), bytesize(),
#{ desc => "The size of the user-space buffer used by the driver." #{ desc => ?DESC(fields_tcp_opts_buffer)
, desc_id => fields_tcp_opts_buffer
} }
)}, )},
{"high_watermark", {"high_watermark",
@ -1098,10 +1028,7 @@ fields("tcp_opts") ->
bytesize(), bytesize(),
#{ #{
default => "1MB", default => "1MB",
desc_id => fields_tcp_opts_high_watermark, desc => ?DESC(fields_tcp_opts_high_watermark)
desc =>
"The socket is set to a busy state when the amount of data queued internally\n"
" by the VM socket implementation reaches this limit."
} }
)}, )},
{"nodelay", {"nodelay",
@ -1109,8 +1036,7 @@ fields("tcp_opts") ->
boolean(), boolean(),
#{ #{
default => false, default => false,
desc_id => fields_tcp_opts_nodelay, desc => ?DESC(fields_tcp_opts_nodelay)
desc => "The TCP_NODELAY flag for the connections."
} }
)}, )},
{"reuseaddr", {"reuseaddr",
@ -1118,8 +1044,7 @@ fields("tcp_opts") ->
boolean(), boolean(),
#{ #{
default => true, default => true,
desc_id => fields_tcp_opts_reuseaddr, desc => ?DESC(fields_tcp_opts_reuseaddr)
desc => "The SO_REUSEADDR flag for the connections."
} }
)} )}
]; ];
@ -1150,8 +1075,7 @@ fields("deflate_opts") ->
{"level", {"level",
sc( sc(
hoconsc:enum([none, default, best_compression, best_speed]), hoconsc:enum([none, default, best_compression, best_speed]),
#{ desc => "Compression level." #{ desc => ?DESC(fields_deflate_opts_level)
, desc_id => fields_deflate_opts_level
} }
)}, )},
{"mem_level", {"mem_level",
@ -1159,55 +1083,43 @@ fields("deflate_opts") ->
range(1, 9), range(1, 9),
#{ #{
default => 8, default => 8,
desc_id => fields_deflate_opts_mem_level, desc => ?DESC(fields_deflate_opts_mem_level)
desc =>
"Specifies the size of the compression state.<br/>\n"
" Lower values decrease memory usage per connection."
} }
)}, )},
{"strategy", {"strategy",
sc( sc(
hoconsc:enum([default, filtered, huffman_only, rle]), hoconsc:enum([default, filtered, huffman_only, rle]),
#{ desc => "Specifies the compression strategy." #{ desc => ?DESC(fields_deflate_opts_strategy)
, desc_id => fields_deflate_opts_strategy
} }
)}, )},
{"server_context_takeover", {"server_context_takeover",
sc( sc(
hoconsc:enum([takeover, no_takeover]), hoconsc:enum([takeover, no_takeover]),
#{ #{
desc_id => fields_deflate_opts_server_context_takeover, desc => ?DESC(fields_deflate_opts_server_context_takeover)
desc =>
"Takeover means the compression state is retained\n"
" between server messages."
} }
)}, )},
{"client_context_takeover", {"client_context_takeover",
sc( sc(
hoconsc:enum([takeover, no_takeover]), hoconsc:enum([takeover, no_takeover]),
#{ #{
desc_id => fields_deflate_opts_client_context_takeover, desc => ?DESC(fields_deflate_opts_client_context_takeover)
desc =>
"Takeover means the compression state is retained\n"
" between client messages."
} }
)}, )},
{"server_max_window_bits", {"server_max_window_bits",
sc( sc(
range(8, 15), range(8, 15),
#{ #{
desc_id => fields_deflate_opts_server_max_window_bits, desc => ?DESC(fields_deflate_opts_server_max_window_bits),
default => 15, default => 15
desc => "Specifies the size of the compression context for the server."
} }
)}, )},
{"client_max_window_bits", {"client_max_window_bits",
sc( sc(
range(8, 15), range(8, 15),
#{ #{
desc_id => fields_deflate_opts_client_max_window_bits, desc => ?DESC(fields_deflate_opts_client_max_window_bits),
default => 15, default => 15
desc => "Specifies the size of the compression context for the client."
} }
)} )}
]; ];
@ -1583,14 +1495,7 @@ fields("trace") ->
{"payload_encode", {"payload_encode",
sc(hoconsc:enum([hex, text, hidden]), #{ sc(hoconsc:enum([hex, text, hidden]), #{
default => text, default => text,
desc_id => fields_trace_payload_encode, desc => ?DESC(fields_trace_payload_encode)
desc =>
"Determine the format of the payload format in the trace file.<br>\n"
"`text`: Text-based protocol or plain text protocol.\n"
" It is recommended when payload is JSON encoded.<br>\n"
"`hex`: Binary hexadecimal encode. It is recommended when payload is "
"a custom binary protocol.<br>\n"
"`hidden`: payload is obfuscated as `******`\n"
})} })}
]. ].
@ -1601,10 +1506,7 @@ mqtt_listener() ->
sc( sc(
hoconsc:array(string()), hoconsc:array(string()),
#{ #{
desc_id => mqtt_listener_access_rules, desc => ?DESC(mqtt_listener_access_rules),
desc =>
"The access control rules for this listener.<br/>"
"See: https://github.com/emqtt/esockd#allowdeny",
default => [<<"allow all">>] default => [<<"allow all">>]
} }
)}, )},
@ -1612,22 +1514,15 @@ mqtt_listener() ->
sc( sc(
boolean(), boolean(),
#{ #{
desc_id => mqtt_listener_proxy_protocol, desc => ?DESC(mqtt_listener_proxy_protocol),
default => false, default => false
desc =>
"Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed\n"
" behind HAProxy or Nginx.<br/>"
"See: https://www.haproxy.com/blog/haproxy/proxy-protocol/"
} }
)}, )},
{"proxy_protocol_timeout", {"proxy_protocol_timeout",
sc( sc(
duration(), duration(),
#{ #{
desc_id => mqtt_listener_proxy_protocol_timeout, desc => ?DESC(mqtt_listener_proxy_protocol_timeout),
desc =>
"Timeout for proxy protocol. EMQX will close the TCP connection "
"if proxy protocol packet is not received within the timeout.",
default => "3s" default => "3s"
} }
)}, )},
@ -1641,9 +1536,8 @@ base_listener() ->
sc( sc(
hoconsc:union([ip_port(), integer()]), hoconsc:union([ip_port(), integer()]),
#{ #{
desc_id => base_listener_bind, desc => ?DESC(base_listener_bind),
required => true, required => true
desc => "IP address and port for the listening socket."
} }
)}, )},
{"acceptors", {"acceptors",
@ -1651,8 +1545,7 @@ base_listener() ->
integer(), integer(),
#{ #{
default => 16, default => 16,
desc_id => base_listener_acceptors, desc => ?DESC(base_listener_acceptors)
desc => "The size of the listener's receiving pool."
} }
)}, )},
{"max_connections", {"max_connections",
@ -1660,8 +1553,7 @@ base_listener() ->
hoconsc:union([infinity, integer()]), hoconsc:union([infinity, integer()]),
#{ #{
default => infinity, default => infinity,
desc_id => base_listener_max_connections, desc => ?DESC(base_listener_max_connections)
desc => "The maximum number of concurrent connections allowed by the listener."
} }
)}, )},
{"mountpoint", {"mountpoint",
@ -1669,41 +1561,23 @@ base_listener() ->
binary(), binary(),
#{ #{
default => <<>>, default => <<>>,
desc_id => base_listener_mountpoint, desc => ?DESC(base_listener_mountpoint)
desc =>
"When publishing or subscribing, prefix all topics with a mountpoint string.\n"
" The prefixed string will be removed from the topic name when the message\n"
" is delivered to the subscriber. The mountpoint is a way that users can use\n"
" to implement isolation of message routing between different listeners.\n"
" For example if a client A subscribes to `t` with `listeners.tcp.<name>.mountpoint`\n"
" set to `some_tenant`, then the client actually subscribes to the topic\n"
" `some_tenant/t`. Similarly, if another client B (connected to the same listener\n"
" as the client A) sends a message to topic `t`, the message is routed\n"
" to all the clients subscribed `some_tenant/t`, so client A will receive the\n"
" message, with topic name `t`.<br/>\n"
" Set to `\"\"` to disable the feature.<br/>\n"
"\n"
" Variables in mountpoint string:\n"
" - <code>${clientid}</code>: clientid\n"
" - <code>${username}</code>: username"
} }
)}, )},
{"zone", {"zone",
sc( sc(
atom(), atom(),
#{ #{
desc_id => base_listener_zone, desc => ?DESC(base_listener_zone),
default => 'default', default => 'default'
desc => "The configuration zone to which the listener belongs."
} }
)}, )},
{"limiter", {"limiter",
sc( sc(
map("ratelimit's type", emqx_limiter_schema:bucket_name()), map("ratelimit's type", emqx_limiter_schema:bucket_name()),
#{ #{
desc_id => base_listener_limiter, desc => ?DESC(base_listener_limiter),
default => #{}, default => #{}
desc => "Type of the rate limit."
} }
)} )}
]. ].
@ -1881,8 +1755,7 @@ common_ssl_opts_schema(Defaults) ->
boolean(), boolean(),
#{ #{
default => Df("enable", false), default => Df("enable", false),
desc_id => common_ssl_opts_schema_enable, desc => ?DESC(common_ssl_opts_schema_enable)
desc => "Enable TLS."
} }
)}, )},
{"cacertfile", {"cacertfile",
@ -1891,15 +1764,7 @@ common_ssl_opts_schema(Defaults) ->
#{ #{
default => D("cacertfile"), default => D("cacertfile"),
required => false, required => false,
desc_id => common_ssl_opts_schema_cacertfile, desc => ?DESC(common_ssl_opts_schema_cacertfile)
desc =>
"Trusted PEM format CA certificates bundle file.<br>\n"
"The certificates in this file are used to verify the TLS peer's certificates.\n"
"Append new certificates to the file if new CAs are to be trusted.\n"
"There is no need to restart EMQX to have the updated file loaded, because\n"
"the system regularly checks if file has been updated (and reload).<br>\n"
"NOTE: invalidating (deleting) a certificate from the file will not affect\n"
"already established connections.\n"
} }
)}, )},
{"certfile", {"certfile",
@ -1908,14 +1773,7 @@ common_ssl_opts_schema(Defaults) ->
#{ #{
default => D("certfile"), default => D("certfile"),
required => false, required => false,
desc_id => common_ssl_opts_schema_certfile, desc => ?DESC(common_ssl_opts_schema_certfile)
desc =>
"PEM format certificates chain file.<br>\n"
"The certificates in this file should be in reversed order of the certificate\n"
"issue chain. That is, the host's certificate should be placed in the beginning\n"
"of the file, followed by the immediate issuer certificate and so on.\n"
"Although the root CA certificate is optional, it should be placed at the end of\n"
"the file if it is to be added."
} }
)}, )},
{"keyfile", {"keyfile",
@ -1924,9 +1782,7 @@ common_ssl_opts_schema(Defaults) ->
#{ #{
default => D("keyfile"), default => D("keyfile"),
required => false, required => false,
desc_id => common_ssl_opts_schema_keyfile, desc => ?DESC(common_ssl_opts_schema_keyfile)
desc =>
"PEM format private key file."
} }
)}, )},
{"verify", {"verify",
@ -1934,9 +1790,7 @@ common_ssl_opts_schema(Defaults) ->
hoconsc:enum([verify_peer, verify_none]), hoconsc:enum([verify_peer, verify_none]),
#{ #{
default => Df("verify", verify_none), default => Df("verify", verify_none),
desc_id => common_ssl_opts_schema_verify, desc => ?DESC(common_ssl_opts_schema_verify)
desc =>
"Enable or disable peer verification."
} }
)}, )},
{"reuse_sessions", {"reuse_sessions",
@ -1944,9 +1798,7 @@ common_ssl_opts_schema(Defaults) ->
boolean(), boolean(),
#{ #{
default => Df("reuse_sessions", true), default => Df("reuse_sessions", true),
desc_id => common_ssl_opts_schema_reuse_sessions, desc => ?DESC(common_ssl_opts_schema_reuse_sessions)
desc =>
"Enable TLS session reuse."
} }
)}, )},
{"depth", {"depth",
@ -1954,13 +1806,7 @@ common_ssl_opts_schema(Defaults) ->
integer(), integer(),
#{ #{
default => Df("depth", 10), default => Df("depth", 10),
desc_id => common_ssl_opts_schema_depth, desc => ?DESC(common_ssl_opts_schema_depth)
desc =>
"Maximum number of non-self-issued intermediate certificates that can follow "
"the peer certificate in a valid certification path. "
"So, if depth is 0 the PEER must be signed by the trusted ROOT-CA directly; "
"if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, ROOT-CA, "
"and so on. The default value is 10."
} }
)}, )},
{"password", {"password",
@ -1969,10 +1815,7 @@ common_ssl_opts_schema(Defaults) ->
#{ #{
sensitive => true, sensitive => true,
required => false, required => false,
desc_id => common_ssl_opts_schema_password, desc => ?DESC(common_ssl_opts_schema_password)
desc =>
"String containing the user's password. Only used if the private\n"
"key file is password-protected."
} }
)}, )},
{"versions", {"versions",
@ -1980,12 +1823,7 @@ common_ssl_opts_schema(Defaults) ->
hoconsc:array(typerefl:atom()), hoconsc:array(typerefl:atom()),
#{ #{
default => default_tls_vsns(maps:get(versions, Defaults, tls_all_available)), default => default_tls_vsns(maps:get(versions, Defaults, tls_all_available)),
desc_id => common_ssl_opts_schema_versions, desc => ?DESC(common_ssl_opts_schema_versions),
desc =>
"All TLS/DTLS versions to be supported.<br>\n"
"NOTE: PSK ciphers are suppressed by 'tlsv1.3' version config<br>\n"
"In case PSK cipher suites are intended, make sure to configured\n"
"<code>['tlsv1.2', 'tlsv1.1']</code> here.",
validator => fun validate_tls_versions/1 validator => fun validate_tls_versions/1
} }
)}, )},
@ -1996,9 +1834,7 @@ common_ssl_opts_schema(Defaults) ->
#{ #{
default => <<"emqx_tls_psk:lookup">>, default => <<"emqx_tls_psk:lookup">>,
converter => fun ?MODULE:parse_user_lookup_fun/1, converter => fun ?MODULE:parse_user_lookup_fun/1,
desc_id => common_ssl_opts_schema_user_lookup_fun, desc => ?DESC(common_ssl_opts_schema_user_lookup_fun)
desc =>
"EMQX-internal callback that is used to lookup pre-shared key (PSK) identity."
} }
)}, )},
{"secure_renegotiate", {"secure_renegotiate",
@ -2006,12 +1842,7 @@ common_ssl_opts_schema(Defaults) ->
boolean(), boolean(),
#{ #{
default => Df("secure_renegotiate", true), default => Df("secure_renegotiate", true),
desc_id => common_ssl_opts_schema_secure_renegotiate, desc => ?DESC(common_ssl_opts_schema_secure_renegotiate)
desc =>
"SSL parameter renegotiation is a feature that allows a client and a server\n"
"to renegotiate the parameters of the SSL connection on the fly.\n"
"RFC 5746 defines a more secure way of doing this. By enabling secure renegotiation,\n"
"you drop support for the insecure renegotiation, prone to MitM attacks."
} }
)} )}
]. ].
@ -2036,13 +1867,7 @@ server_ssl_opts_schema(Defaults1, IsRanchListener) ->
#{ #{
default => D("dhfile"), default => D("dhfile"),
required => false, required => false,
desc_id => server_ssl_opts_schema_dhfile, desc => ?DESC(server_ssl_opts_schema_dhfile)
desc =>
"Path to a file containing PEM-encoded Diffie-Hellman parameters\n"
"to be used by the server if a cipher suite using Diffie-Hellman\n"
"key exchange is negotiated. If not specified, default parameters\n"
"are used.<br>\n"
"NOTE: The <code>dhfile</code> option is not supported by TLS 1.3."
} }
)}, )},
{"fail_if_no_peer_cert", {"fail_if_no_peer_cert",
@ -2050,13 +1875,7 @@ server_ssl_opts_schema(Defaults1, IsRanchListener) ->
boolean(), boolean(),
#{ #{
default => Df("fail_if_no_peer_cert", false), default => Df("fail_if_no_peer_cert", false),
desc_id => server_ssl_opts_schema_fail_if_no_peer_cert, desc => ?DESC(server_ssl_opts_schema_fail_if_no_peer_cert)
desc =>
"Used together with {verify, verify_peer} by an TLS/DTLS server.\n"
"If set to true, the server fails if the client does not have a\n"
"certificate to send, that is, sends an empty certificate.\n"
"If set to false, it fails only if the client sends an invalid\n"
"certificate (an empty certificate is considered valid)."
} }
)}, )},
{"honor_cipher_order", {"honor_cipher_order",
@ -2064,12 +1883,7 @@ server_ssl_opts_schema(Defaults1, IsRanchListener) ->
boolean(), boolean(),
#{ #{
default => Df("honor_cipher_order", true), default => Df("honor_cipher_order", true),
desc_id => server_ssl_opts_schema_honor_cipher_order, desc => ?DESC(server_ssl_opts_schema_honor_cipher_order)
desc =>
"An important security setting, it forces the cipher to be set based\n"
" on the server-specified order instead of the client-specified order,\n"
" hence enforcing the (usually more properly configured) security\n"
" ordering of the server administrator."
} }
)}, )},
{"client_renegotiation", {"client_renegotiation",
@ -2077,18 +1891,7 @@ server_ssl_opts_schema(Defaults1, IsRanchListener) ->
boolean(), boolean(),
#{ #{
default => Df("client_renegotiation", true), default => Df("client_renegotiation", true),
desc_id => server_ssl_opts_schema_client_renegotiation, desc => ?DESC(server_ssl_opts_schema_client_renegotiation)
desc =>
"In protocols that support client-initiated renegotiation,\n"
"the cost of resources of such an operation is higher for the "
"server than the client.\n"
"This can act as a vector for denial of service attacks.\n"
"The SSL application already takes measures to counter-act such attempts,\n"
"but client-initiated renegotiation can be strictly disabled by setting "
"this option to false.\n"
"The default value is true. Note that disabling renegotiation can result in\n"
"long-lived connections becoming unusable due to limits on\n"
"the number of messages the underlying cipher suite can encipher."
} }
)} )}
| [ | [
@ -2097,8 +1900,7 @@ server_ssl_opts_schema(Defaults1, IsRanchListener) ->
duration(), duration(),
#{ #{
default => Df("handshake_timeout", "15s"), default => Df("handshake_timeout", "15s"),
desc_id => server_ssl_opts_schema_handshake_timeout, desc => ?DESC(server_ssl_opts_schema_handshake_timeout)
desc => "Maximum time duration allowed for the handshake to complete"
} }
)} )}
|| IsRanchListener || IsRanchListener
@ -2123,19 +1925,7 @@ client_ssl_opts_schema(Defaults1) ->
hoconsc:union([disable, string()]), hoconsc:union([disable, string()]),
#{ #{
required => false, required => false,
desc_id => client_ssl_opts_schema_server_name_indication, desc => ?DESC(client_ssl_opts_schema_server_name_indication)
desc =>
"Specify the host name to be used in TLS Server Name Indication extension.<br>\n"
"For instance, when connecting to \"server.example.net\", the genuine server\n"
"which accepts the connection and performs TLS handshake may differ from the\n"
"host the TLS client initially connects to, e.g. when connecting to an IP address\n"
"or when the host has multiple resolvable DNS records <br>\n"
"If not specified, it will default to the host name string which is used\n"
"to establish the connection, unless it is IP addressed used.<br>\n"
"The host name is then also used in the host name verification of the peer\n"
"certificate.<br> The special value 'disable' prevents the Server Name\n"
"Indication extension from being sent and disables the hostname\n"
"verification check."
} }
)} )}
]. ].
@ -2164,8 +1954,11 @@ ciphers_schema(Default) ->
true -> undefined; true -> undefined;
false -> fun validate_ciphers/1 false -> fun validate_ciphers/1
end, end,
desc_id => ciphers_schema_0, desc_id => "ciphers_schema_" ++ case Default of
desc => quic -> "quic";
_ -> "0"
end,
desc_en =>
"This config holds TLS cipher suite names separated by comma,\n" "This config holds TLS cipher suite names separated by comma,\n"
"or as an array of strings. e.g.\n" "or as an array of strings. e.g.\n"
"<code>\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\"</code> or\n" "<code>\"TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256\"</code> or\n"
@ -2246,7 +2039,6 @@ ref(Module, Field) -> hoconsc:ref(Module, Field).
mk_duration(Desc, OverrideMeta) -> mk_duration(Desc, OverrideMeta) ->
DefaultMeta = #{ DefaultMeta = #{
desc_id => mk_duration_0,
desc => Desc ++ desc => Desc ++
" Time interval is a string that contains a number followed by time unit:<br/>\n" " Time interval is a string that contains a number followed by time unit:<br/>\n"
"- `ms` for milliseconds,\n" "- `ms` for milliseconds,\n"