From d5c54276e212e14128002a803e96c365874548d1 Mon Sep 17 00:00:00 2001 From: HeeeJianBo Date: Wed, 27 Dec 2017 14:55:36 +0800 Subject: [PATCH 01/16] Fix issue #1398 --- src/emqttd_topic.erl | 8 ++++---- test/emqttd_topic_SUITE.erl | 16 ++++++++++------ 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/src/emqttd_topic.erl b/src/emqttd_topic.erl index 458a41f7d..934362499 100644 --- a/src/emqttd_topic.erl +++ b/src/emqttd_topic.erl @@ -61,18 +61,18 @@ wildcard([_H|T]) -> -spec(match(Name, Filter) -> boolean() when Name :: topic() | words(), Filter :: topic() | words()). +match(<<"$", _/binary>>, <<"+", _/binary>>) -> + false; +match(<<"$", _/binary>>, <<"#", _/binary>>) -> + false; match(Name, Filter) when is_binary(Name) and is_binary(Filter) -> match(words(Name), words(Filter)); match([], []) -> true; match([H|T1], [H|T2]) -> match(T1, T2); -match([<<$$, _/binary>>|_], ['+'|_]) -> - false; match([_H|T1], ['+'|T2]) -> match(T1, T2); -match([<<$$, _/binary>>|_], ['#']) -> - false; match(_, ['#']) -> true; match([_H1|_], [_H2|_]) -> diff --git a/test/emqttd_topic_SUITE.erl b/test/emqttd_topic_SUITE.erl index b1ea4d8ed..9ec7736bd 100644 --- a/test/emqttd_topic_SUITE.erl +++ b/test/emqttd_topic_SUITE.erl @@ -73,10 +73,10 @@ t_match2(_) -> t_match3(_) -> true = match(<<"device/60019423a83c/fw">>, <<"device/60019423a83c/#">>), - false = match(<<"device/60019423a83c/$fw">>, <<"device/60019423a83c/#">>), + true = match(<<"device/60019423a83c/$fw">>, <<"device/60019423a83c/#">>), true = match(<<"device/60019423a83c/$fw/fw">>, <<"device/60019423a83c/$fw/#">>), true = match(<<"device/60019423a83c/fw/checksum">>, <<"device/60019423a83c/#">>), - false = match(<<"device/60019423a83c/$fw/checksum">>, <<"device/60019423a83c/#">>), + true = match(<<"device/60019423a83c/$fw/checksum">>, <<"device/60019423a83c/#">>), true = match(<<"device/60019423a83c/dust/type">>, <<"device/60019423a83c/#">>). t_sigle_level_match(_) -> @@ -86,7 +86,9 @@ t_sigle_level_match(_) -> true = match(<<"sport/">>, <<"sport/+">>), true = match(<<"/finance">>, <<"+/+">>), true = match(<<"/finance">>, <<"/+">>), - false = match(<<"/finance">>, <<"+">>). + false = match(<<"/finance">>, <<"+">>), + true = match(<<"/devices/$dev1">>, <<"/devices/+">>), + true = match(<<"/devices/$dev1/online">>, <<"/devices/+/online">>). t_sys_match(_) -> true = match(<<"$SYS/broker/clients/testclient">>, <<"$SYS/#">>), @@ -95,9 +97,11 @@ t_sys_match(_) -> false = match(<<"$SYS/broker">>, <<"#">>). 't_#_match'(_) -> - true = match(<<"a/b/c">>, <<"#">>), - true = match(<<"a/b/c">>, <<"+/#">>), - false = match(<<"$SYS/brokers">>, <<"#">>). + true = match(<<"a/b/c">>, <<"#">>), + true = match(<<"a/b/c">>, <<"+/#">>), + false = match(<<"$SYS/brokers">>, <<"#">>), + true = match(<<"a/b/$c">>, <<"a/b/#">>), + true = match(<<"a/b/$c">>, <<"a/#">>). t_match_perf(_) -> true = match(<<"a/b/ccc">>, <<"a/#">>), From 4c8b43e05d2c2666a079f3b385606f11544cbf61 Mon Sep 17 00:00:00 2001 From: HeeeJianBo Date: Wed, 27 Dec 2017 15:11:55 +0800 Subject: [PATCH 02/16] Improve impletament of emqttd_topic:match/2 --- src/emqttd_topic.erl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/emqttd_topic.erl b/src/emqttd_topic.erl index 934362499..91cd0ff08 100644 --- a/src/emqttd_topic.erl +++ b/src/emqttd_topic.erl @@ -61,9 +61,9 @@ wildcard([_H|T]) -> -spec(match(Name, Filter) -> boolean() when Name :: topic() | words(), Filter :: topic() | words()). -match(<<"$", _/binary>>, <<"+", _/binary>>) -> +match(<<$$, _/binary>>, <<$+, _/binary>>) -> false; -match(<<"$", _/binary>>, <<"#", _/binary>>) -> +match(<<$$, _/binary>>, <<$#, _/binary>>) -> false; match(Name, Filter) when is_binary(Name) and is_binary(Filter) -> match(words(Name), words(Filter)); From ed5e4d185763977b17bd95094d579fac85c2c115 Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Wed, 27 Dec 2017 21:30:17 +0800 Subject: [PATCH 03/16] Change the default value of mqtt.keepalive_backoff to 0.75 --- etc/emq.conf | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/etc/emq.conf b/etc/emq.conf index 68cf8b6b7..677eca905 100644 --- a/etc/emq.conf +++ b/etc/emq.conf @@ -1,5 +1,5 @@ ##==================================================================== -## EMQ Configuration R2.3.0 +## EMQ Configuration R2.3.3 ##==================================================================== ##-------------------------------------------------------------------- @@ -196,7 +196,7 @@ mqtt.max_packet_size = 64KB mqtt.websocket_protocol_header = on ## The Keepalive timeout: Keepalive * backoff * 2 -mqtt.keepalive_backoff = 1.25 +mqtt.keepalive_backoff = 0.75 ##-------------------------------------------------------------------- ## MQTT Connection From 953a7628a305c8745fed2a1445dac51ee71a6148 Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Thu, 28 Dec 2017 11:34:29 +0800 Subject: [PATCH 04/16] Version 2.3.3 --- Makefile | 8 ++++---- src/emqttd.app.src | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index b0fac24b8..8ad0dbe5b 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ PROJECT = emqttd PROJECT_DESCRIPTION = Erlang MQTT Broker -PROJECT_VERSION = 2.3.2 +PROJECT_VERSION = 2.3.3 DEPS = goldrush gproc lager esockd ekka mochiweb pbkdf2 lager_syslog bcrypt clique jsx @@ -8,14 +8,14 @@ dep_goldrush = git https://github.com/basho/goldrush 0.1.9 dep_gproc = git https://github.com/uwiger/gproc dep_getopt = git https://github.com/jcomellas/getopt v0.8.2 dep_lager = git https://github.com/basho/lager master -dep_esockd = git https://github.com/emqtt/esockd v5.2 -dep_ekka = git https://github.com/emqtt/ekka v0.2.1 +dep_esockd = git https://github.com/emqtt/esockd develop +dep_ekka = git https://github.com/emqtt/ekka develop dep_mochiweb = git https://github.com/emqtt/mochiweb develop dep_pbkdf2 = git https://github.com/emqtt/pbkdf2 2.0.1 dep_lager_syslog = git https://github.com/basho/lager_syslog dep_bcrypt = git https://github.com/smarkets/erlang-bcrypt master dep_clique = git https://github.com/emqtt/clique -dep_jsx = git https://github.com/talentdeficit/jsx +dep_jsx = git https://github.com/talentdeficit/jsx ERLC_OPTS += +debug_info ERLC_OPTS += +'{parse_transform, lager_transform}' diff --git a/src/emqttd.app.src b/src/emqttd.app.src index e321b73f1..4ff79090a 100644 --- a/src/emqttd.app.src +++ b/src/emqttd.app.src @@ -1,6 +1,6 @@ {application,emqttd, [{description,"Erlang MQTT Broker"}, - {vsn,"2.3.2"}, + {vsn,"2.3.3"}, {modules,[]}, {registered,[emqttd_sup]}, {applications,[kernel,stdlib,gproc,lager,esockd,mochiweb, From 10ed4219dbd1f5dcdbe7f5a80b8b6a53070115a0 Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Sun, 31 Dec 2017 15:10:45 +0800 Subject: [PATCH 05/16] Update documentation for R2 configurations --- etc/emq.conf | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/etc/emq.conf b/etc/emq.conf index 677eca905..898a94576 100644 --- a/etc/emq.conf +++ b/etc/emq.conf @@ -1,5 +1,5 @@ ##==================================================================== -## EMQ Configuration R2.3.3 +## EMQ Configuration R2 ##==================================================================== ##-------------------------------------------------------------------- @@ -9,7 +9,17 @@ ## Cluster name cluster.name = emqcl -## Cluster discovery strategy: manual | static | mcast | dns | etcd | k8s +## Cluster auto-discovery strategy. +## +## Enum Values: +## - manual: Manual join command +## - static: Static node list +## - mcast: IP Multicast +## - dns: DNS A Record +## - etcd: etcd +## - k8s: Kubernates +## +## Default: manual cluster.discovery = manual ## Cluster Autoheal: on | off @@ -557,7 +567,9 @@ listener.wss.external.access.1 = allow all ## listener.wss.external.proxy_protocol = on ## listener.wss.external.proxy_protocol_timeout = 3s -## SSL Options +## SSL Option +### 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 From 052f9638cb907d58c786a953a50de73ed312a50f Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Tue, 2 Jan 2018 20:47:25 +0800 Subject: [PATCH 06/16] Add more documentation for emq.conf --- etc/emq.conf | 367 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 292 insertions(+), 75 deletions(-) diff --git a/etc/emq.conf b/etc/emq.conf index 898a94576..74f2b8a88 100644 --- a/etc/emq.conf +++ b/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) -node.dist_buffer_size = 32MB +## Set the distribution buffer busy limit (dist_buf_busy_limit). +## 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. -## Note that mnesia and SSL will create temporary ets tables. +## Sets the maximum number of ETS tables. Note that mnesia and SSL +## 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 -## 0 means no limit +## Maximum size of the Inflight Window storing QoS1/2 messages delivered but unacked. +## +## 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 -mqtt.session.max_awaiting_rel = 100 +## Maximum QoS2 packets (Client -> Broker) awaiting PUBREL, 0 means no limit. +## +## Value: Number +mqtt.session.max_awaiting_rel = 1000 -## Awaiting PUBREL Timeout -mqtt.session.await_rel_timeout = 20s +## The QoS2 messages (Client -> Broker) will be dropped if awaiting PUBREL timeout. +## +## 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: -## w - week -## d - day -## h - hour -## m - minute -## s - second +## Session expiration time. +## +## Value: Duration +## -d: day +## -h: hour +## -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 From ad26eff4215e9ab9ce66fa34a59c0c2a8fe9b552 Mon Sep 17 00:00:00 2001 From: turtled Date: Wed, 3 Jan 2018 10:27:51 +0800 Subject: [PATCH 07/16] Format print log --- src/emqttd_ws.erl | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/src/emqttd_ws.erl b/src/emqttd_ws.erl index 35a7f9852..798c4d69b 100644 --- a/src/emqttd_ws.erl +++ b/src/emqttd_ws.erl @@ -45,14 +45,22 @@ handle_request('GET', "/mqtt", Req) -> Proto = check_protocol_header(Req), case {is_websocket(Upgrade), Proto} of {true, "mqtt" ++ _Vsn} -> - {ok, ProtoEnv} = emqttd:env(protocol), - PacketSize = get_value(max_packet_size, ProtoEnv, ?MAX_PACKET_SIZE), - Parser = emqttd_parser:initial_state(PacketSize), - %% Upgrade WebSocket. - {ReentryWs, ReplyChannel} = mochiweb_websocket:upgrade_connection(Req, fun ?MODULE:ws_loop/3), - {ok, ClientPid} = emqttd_ws_client_sup:start_client(self(), Req, ReplyChannel), - ReentryWs(#wsocket_state{peername = Req:get(peername), parser = Parser, - max_packet_size = PacketSize, client_pid = ClientPid}); + case Req:get(peername) of + {ok, Peername} -> + {ok, ProtoEnv} = emqttd:env(protocol), + PacketSize = get_value(max_packet_size, ProtoEnv, ?MAX_PACKET_SIZE), + Parser = emqttd_parser:initial_state(PacketSize), + %% Upgrade WebSocket. + {ReentryWs, ReplyChannel} = mochiweb_websocket:upgrade_connection(Req, fun ?MODULE:ws_loop/3), + {ok, ClientPid} = emqttd_ws_client_sup:start_client(self(), Req, ReplyChannel), + ReentryWs(#wsocket_state{peername = Peername, + parser = Parser, + max_packet_size = PacketSize, + client_pid = ClientPid}); + {error, Reason} -> + lager:error("Get peername with error ~s", [Reason]), + Req:respond({400, [], <<"Bad Request">>}) + end; {false, _} -> lager:error("Not WebSocket: Upgrade = ~s", [Upgrade]), Req:respond({400, [], <<"Bad Request">>}); From 0a7e93ea9076719c112990a14b3871935060f8fb Mon Sep 17 00:00:00 2001 From: turtled Date: Wed, 3 Jan 2018 10:29:51 +0800 Subject: [PATCH 08/16] Export funtion fix #1428 --- src/emqttd_mgmt.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/emqttd_mgmt.erl b/src/emqttd_mgmt.erl index 01dd50b1e..1a608968e 100644 --- a/src/emqttd_mgmt.erl +++ b/src/emqttd_mgmt.erl @@ -45,7 +45,7 @@ -export([publish/1, subscribe/1, unsubscribe/1]). --export([kick_client/1, clean_acl_cache/2]). +-export([kick_client/1, kick_client/2, clean_acl_cache/2, clean_acl_cache/3]). -export([modify_config/2, modify_config/3, modify_config/4, get_configs/0, get_config/1, get_plugin_config/1, get_plugin_config/2, modify_plugin_config/2, modify_plugin_config/3]). From a17fae30e2fe58ad2cbc42d75b09fa95a5c62c6c Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Wed, 3 Jan 2018 22:44:54 +0800 Subject: [PATCH 09/16] Add more documentation for MQTT listeners --- etc/emq.conf | 375 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 299 insertions(+), 76 deletions(-) diff --git a/etc/emq.conf b/etc/emq.conf index 74f2b8a88..4cb8fc04b 100644 --- a/etc/emq.conf +++ b/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 -mqtt.broker.sys_interval = 60 +## System Interval of publishing $SYS Messages. +## +## 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 -mqtt.bridge.ping_down_interval = 1 +## Ping interval of bridge node. +## +## 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. 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 -#listener.tcp.external.rate_limit = 100,10 - -#listener.tcp.external.access.1 = allow 192.168.0.0/24 +## Rate limit for the external MQTT/TCP connections. +## Format is 'burst,rate'. +## +## 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 -listener.tcp.internal.acceptors = 16 +## The acceptor pool for internal MQTT/TCP listener. +## +## 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 - -listener.tcp.internal.recbuf = 4KB - -listener.tcp.internal.sndbuf = 1MB - -listener.tcp.internal.nodelay = true +## The TCP_NODELAY flag for MQTT connections. +## See: listener.tcp.external.nodelay +# +## Value: true | false +listener.tcp.internal.nodelay = false ##-------------------------------------------------------------------- -## External SSL Listener +## MQTT/SSL - External SSL Listener for MQTT Protocol -## SSL Listener: 8883, 127.0.0.1:8883, ::1:8883 +## listener.ssl. 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 - -## Configuring SSL Options. See http://erlang.org/doc/man/ssl.html -### TLS only for POODLE attack +## TLS versions only to protect from POODLE attack. +## See http://erlang.org/doc/man/ssl.html +## +## Value: String ## listener.ssl.external.tls_versions = tlsv1.2,tlsv1.1,tlsv1 -### 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 - +## TLS Handshake timeout. +## +## Value: Duration 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 From b2b78c178cd73583c1d3760c38de39d04084f10c Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Thu, 4 Jan 2018 12:25:05 +0800 Subject: [PATCH 10/16] Add documenation for SSL configurations --- etc/emq.conf | 220 ++++++++++++++++++++++++++++++++++++++++-------- priv/emq.schema | 8 +- 2 files changed, 188 insertions(+), 40 deletions(-) diff --git a/etc/emq.conf b/etc/emq.conf index 4cb8fc04b..ef16ecc6b 100644 --- a/etc/emq.conf +++ b/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. -### 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 -### 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 -### -### Most of it was copied from Mozilla’s Server Side TLS article +## 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 +## 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 +## 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 +## +## 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 -### 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, -### you drop support for the insecure renegotiation, prone to MitM attacks. +## SSL parameter renegotiation is a feature that allows a client and +## 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, +## 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 -### pre-existing sessions, instead of initializing new ones. -### Read more about it here. +## A performance optimization setting, it allows clients to reuse +## pre-existing sessions, instead of initializing new ones. +## 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 -### the server-specified order instead of the client-specified order, -### hence enforcing the (usually more properly configured) security -### ordering of the server administrator. +## An important security setting, it forces the cipher to be set based +## on the server-specified order instead of the client-specified order, +## hence enforcing the (usually more properly configured) security +## 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. -### Notice: 'verify' should be configured as 'verify_peer' +## Use the CN or DN value from the client certificate as a username. +## 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. 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. 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. See http://erlang.org/doc/man/ssl.html - +## SSL Options. Same to 'listener.ssl.*' 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 diff --git a/priv/emq.schema b/priv/emq.schema index aaefce4c2..ca242c4c7 100644 --- a/priv/emq.schema +++ b/priv/emq.schema @@ -702,8 +702,8 @@ end}. %%-------------------------------------------------------------------- {mapping, "mqtt.broker.sys_interval", "emqttd.broker_sys_interval", [ - {default, 60}, - {datatype, integer} + {datatype, {duration, ms}}, + {default, "1m"} ]}. %%-------------------------------------------------------------------- @@ -735,8 +735,8 @@ end}. ]}. {mapping, "mqtt.bridge.ping_down_interval", "emqttd.bridge", [ - {default, 1}, - {datatype, integer} + {datatype, {duration, ms}}, + {default, "1s"} ]}. {translation, "emqttd.bridge", fun(Conf) -> From b98a320124f4053a47b16ce03ae993abdd4d8e6c Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Thu, 4 Jan 2018 15:32:21 +0800 Subject: [PATCH 11/16] Improve documentation for all options --- etc/emq.conf | 442 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 303 insertions(+), 139 deletions(-) diff --git a/etc/emq.conf b/etc/emq.conf index ef16ecc6b..4d37515aa 100644 --- a/etc/emq.conf +++ b/etc/emq.conf @@ -29,9 +29,10 @@ cluster.discovery = manual ## Default: on cluster.autoheal = on -## AutoClean down node after this duration. +## Autoclean down node. A down node will be removed from the cluster +## if this value > 0. ## -## Value: time duration with units +## Value: Duration ## -h: hour, e.g. '2h' for 2 hours ## -m: minute, e.g. '5m' for 5 minutes ## -s: second, e.g. '30s' for 30 seconds @@ -70,8 +71,6 @@ cluster.autoclean = 5m ## Multicast Ttl. ## ## Value: 0-255 -## -## Default: 255 ## cluster.mcast.ttl = 255 ## Multicast loop. @@ -101,7 +100,7 @@ cluster.autoclean = 5m ## 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} +## will create a path in etcd: v2/keys/// ## ## Value: String ## cluster.etcd.prefix = emqcl @@ -121,7 +120,7 @@ cluster.autoclean = 5m ## Value: String ## cluster.k8s.apiserver = http://10.110.111.204:8080 -## The service name helps build node name: {service_name}@{ip} +## The service name helps lookup EMQ nodes in the cluster. ## ## Value: String ## cluster.k8s.service_name = emq @@ -142,7 +141,9 @@ cluster.autoclean = 5m ## Node name. ## -## Value: {name}@{host} +## See: http://erlang.org/doc/reference_manual/distributed.html +## +## Value: @ ## ## Default: emq@127.0.0.1 node.name = emq@127.0.0.1 @@ -159,14 +160,13 @@ 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 ## node.heartbeat = on -## Enable Kernel Poll. +## Enable kernel poll. ## ## Value: on | off ## @@ -174,7 +174,8 @@ node.smp = auto node.kernel_poll = on ## Sets the number of threads in async thread pool. Valid range is 0-1024. -## More information at: http://erlang.org/doc/man/erl.html +## +## See: http://erlang.org/doc/man/erl.html ## ## Value: 0-1024 ## @@ -183,7 +184,8 @@ node.async_threads = 32 ## 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 +## +## See: http://erlang.org/doc/man/erl.html ## ## Value: Number [1024-134217727] ## @@ -192,7 +194,8 @@ 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 +## +## See: http://erlang.org/doc/man/erl.html ## ## Value: Number [1024-134217727] ## @@ -200,15 +203,16 @@ node.process_limit = 256000 node.max_ports = 65536 ## Set the distribution buffer busy limit (dist_buf_busy_limit). -## More information at: http://erlang.org/doc/man/erl.html +## +## See: http://erlang.org/doc/man/erl.html ## ## Value: Number [1KB-2GB] ## ## vm.args: +zdbbl size -node.dist_buffer_size = 16MB +node.dist_buffer_size = 8MB -## Sets the maximum number of ETS tables. Note that mnesia and SSL -## will create temporary ETS tables. +## Sets the maximum number of ETS tables. Note that mnesia and SSL will +## create temporary ETS tables. ## ## Value: Number ## @@ -227,11 +231,11 @@ node.fullsweep_after = 1000 ## Value: Log file node.crash_dump = {{ platform_log_dir }}/crash.dump -## Specifies the net_kernel tick time. TickTime is specified in seconds. +## Sets 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 +## See: http://www.erlang.org/doc/man/kernel_app.html#net_ticktime ## ## Value: Number ## @@ -239,10 +243,10 @@ node.crash_dump = {{ platform_log_dir }}/crash.dump node.dist_net_ticktime = 60 ## 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 +## Note that if there are firewalls between clustered nodes, this port segment ## for nodes’ communication should be allowed. ## -## More information at: http://www.erlang.org/doc/man/kernel_app.html +## See: http://www.erlang.org/doc/man/kernel_app.html ## ## Value: Port [1024-65535] node.dist_listen_min = 6369 @@ -273,7 +277,7 @@ log.console = console ## Default: error log.console.level = error -## The file where console logs will be writed to, when 'log.console' is set to 'file'. +## The file where console logs will be writed to, when 'log.console' is set as 'file'. ## ## Value: File Name ## log.console.file = {{ platform_log_dir }}/console.log @@ -328,12 +332,12 @@ log.crash = on ## Value: File Name log.crash.file = {{ platform_log_dir }}/crash.log -## Enable Syslog. +## Enable syslog. ## ## Values: on | off log.syslog = on -## The severity level for syslog. +## Sets the severity level for syslog. ## ## Value: debug | info | notice | warning | error | critical | alert | emergency log.syslog.level = error @@ -343,7 +347,8 @@ log.syslog.level = error ##-------------------------------------------------------------------- ## Allow Anonymous Authentication. -## !!! Notice: Should disable the config for production deployment. +## +## Notice: Disable the option for production deployment. ## ## Value: true | false mqtt.allow_anonymous = true @@ -358,7 +363,7 @@ mqtt.acl_nomatch = allow ## Value: File Name mqtt.acl_file = {{ platform_etc_dir }}/acl.conf -## Cache ACL for PUBLISH Messages. +## Whether to cache ACL for publish messages. ## ## Value: true | false mqtt.cache_acl = true @@ -367,7 +372,7 @@ mqtt.cache_acl = true ## MQTT Protocol ##-------------------------------------------------------------------- -## Maximum MQTT clientId length allowed. +## Maximum length of MQTT clientId allowed. ## ## Value: Number [23-65535] mqtt.max_clientid_len = 1024 @@ -380,13 +385,13 @@ mqtt.max_clientid_len = 1024 mqtt.max_packet_size = 64KB ## Check if the websocket protocol header is valid. -## Turn off the config when developing WeChat App. +## Turn off the option when developing WeChat App. ## ## Value: on | off mqtt.websocket_protocol_header = on ## The backoff for MQTT keepalive timeout. -## The broker will kick a MQTT connection out until 'Keepalive * backoff * 2' timeout. +## EMQ will kick a MQTT connection out until 'Keepalive * backoff * 2' timeout. ## ## Value: Float > 0.5 mqtt.keepalive_backoff = 0.75 @@ -395,7 +400,7 @@ mqtt.keepalive_backoff = 0.75 ## MQTT Connection ##-------------------------------------------------------------------- -## Force GC the MQTT connection. Value 0 will disable the Force GC. +## Force GC the MQTT connections. Value 0 will disable the Force GC. ## ## Value: Number >= 0 mqtt.conn.force_gc_count = 100 @@ -409,8 +414,7 @@ mqtt.conn.force_gc_count = 100 ## Value: Duration mqtt.client.idle_timeout = 30s -## Maximum publish rate of MQTT messages per second. -## TODO: R2.4 release +## TODO: Maximum publish rate of MQTT messages per second. ## ## Value: Number ## mqtt.client.max_publish_rate = 5 @@ -439,7 +443,7 @@ mqtt.session.upgrade_qos = off ## Value: Number mqtt.session.max_inflight = 32 -## Retry interval for QoS1/2 message redelivering. +## Retry interval for QoS1/2 message delivering. ## ## Value: Duration mqtt.session.retry_interval = 20s @@ -470,7 +474,7 @@ mqtt.session.enable_stats = on ## Default: 2h, 2 hours mqtt.session.expiry_interval = 2h -## Ignore loop delivery of messages. +## Whether to ignore loop delivery of messages. ## ## Value: true | false ## @@ -481,12 +485,12 @@ mqtt.session.ignore_loop_deliver = false ## MQTT Message Queue ##-------------------------------------------------------------------- -## Message Queue Type. +## Message queue type. ## ## Value: simple | priority mqtt.mqueue.type = simple -## Topic Priority. Default is 0. +## Topic priority. Default is 0. ## ## Value: Number [0-255] ## @@ -508,7 +512,7 @@ mqtt.mqueue.low_watermark = 20% ## Value: Percent mqtt.mqueue.high_watermark = 60% -## Queue Qos0 messages? +## Whether to enqueue Qos0 messages. ## ## Value: false | true mqtt.mqueue.store_qos0 = true @@ -517,19 +521,19 @@ mqtt.mqueue.store_qos0 = true ## MQTT Broker and PubSub ##-------------------------------------------------------------------- -## System Interval of publishing $SYS Messages. +## System interval of publishing $SYS messages. ## ## Value: Duration ## ## Default: 1m, 1 minute mqtt.broker.sys_interval = 1m -## The PubSub pool size. Default value should be scheduler numbers. +## The PubSub pool size. Default value should be same as scheduler numbers. ## ## Value: Number > 1 mqtt.pubsub.pool_size = 8 -## TODO: Subscribe Asynchronously. +## TODO: Subscribe asynchronously. ## ## Value: true | false mqtt.pubsub.async = true @@ -609,15 +613,18 @@ listener.tcp.external.max_clients = 102400 ## 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 +## +## See: 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 +## +## Example: allow 192.168.0.0/24 +listener.tcp.external.access.1 = allow all -## 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/ +## Enable the Proxy Protocol V1/2 if the EMQ cluster is deployed +## behind HAProxy or Nginx. +## +## See: https://www.haproxy.com/blog/haproxy/proxy-protocol/ ## ## Value: on | off ## listener.tcp.external.proxy_protocol = on @@ -635,8 +642,6 @@ listener.tcp.external.access.2 = allow all ## Value: cn ## listener.tcp.external.peer_cert_as_username = cn -## TCP socket options for the MQTT listener. - ## The TCP backlog defines the maximum length that the queue of pending ## connections can grow to. ## @@ -654,13 +659,15 @@ listener.tcp.external.send_timeout = 15s 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 +## +## See: http://erlang.org/doc/man/inet.html ## ## Value: Bytes ## listener.tcp.external.recbuf = 4KB ## The TCP send buffer(os kernel) for MQTT connections. -## More information at: http://erlang.org/doc/man/inet.html +## +## See: http://erlang.org/doc/man/inet.html ## ## Value: Bytes ## listener.tcp.external.sndbuf = 4KB @@ -671,7 +678,8 @@ listener.tcp.external.send_timeout_close = on ## >= 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 +## +## See: http://erlang.org/doc/man/inet.html ## ## Value: Bytes ## listener.tcp.external.buffer = 4KB @@ -690,8 +698,8 @@ listener.tcp.external.nodelay = true ##-------------------------------------------------------------------- ## Internal TCP Listener for MQTT Protocol -## The IP address and port that the internal MQTT/TCP protocol listener will -## bind. +## The IP address and port that the internal MQTT/TCP protocol listener +## will bind. ## ## Value: IP:Port, Port ## @@ -713,61 +721,73 @@ listener.tcp.internal.max_clients = 102400 ## Value: String ## listener.tcp.internal.zone = internal -## Mountpoint of the MQTT/TCP Listener. All the topics will -## be prefixed with the mount point if this option is enabled. +## Mountpoint of the MQTT/TCP Listener. +## +## See: listener.tcp..mountpoint ## ## Value: String -## listener.tcp.external.mountpoint = internal/ +## listener.tcp.internal.mountpoint = internal/ ## Rate limit for the internal MQTT/TCP connections. -## Format is 'burst,rate'. +## +## See: listener.tcp..rate_limit ## ## Value: burst,rate -## Unit: KB/sec ## listener.tcp.internal.rate_limit = 1000,100 -## The TCP backlog defines the maximum length that the queue of -## pending connections can grow to. +## The TCP backlog of internal MQTT/TCP Listener. +## +## See: listener.tcp..backlog ## ## Value: Number >= 0 listener.tcp.internal.backlog = 512 ## The TCP send timeout for internal MQTT connections. ## +## See: listener.tcp..send_timeout +## ## Value: Duration listener.tcp.internal.send_timeout = 5s ## Close the MQTT/TCP connection if send timeout. ## +## See: listener.tcp..send_timeout_close +## ## 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 +## The TCP receive buffer(os kernel) for internal MQTT connections. +## +## See: listener.tcp..recbuf ## ## 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 +## The TCP send buffer(os kernel) for internal MQTT connections. +## +## See: 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 +## +## See: listener.tcp..buffer ## ## Value: Bytes listener.tcp.internal.buffer = 16KB ## Sets the 'buffer = max(sndbuf, recbuf)' if this option is enabled. ## +## See: listener.tcp..tune_buffer +## ## Value: on | off listener.tcp.internal.tune_buffer = on -## The TCP_NODELAY flag for MQTT connections. -## See: listener.tcp.external.nodelay -# +## The TCP_NODELAY flag for internal MQTT connections. +## +## See: listener.tcp..nodelay +## ## Value: true | false listener.tcp.internal.nodelay = false @@ -797,43 +817,43 @@ listener.ssl.external.max_clients = 1024 ## 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. +## Mountpoint of the MQTT/SSL Listener. ## ## Value: String ## listener.ssl.external.mountpoint = inbound/ -## 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 - -## 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 +## +## See: listener.tcp..access ## ## Value: ACL Rule listener.ssl.external.access.1 = allow all -## TLS versions only to protect from POODLE attack. -## See http://erlang.org/doc/man/ssl.html +## Rate limit for the external MQTT/SSL connections. ## -## Value: String +## Value: burst,rate +## listener.ssl.external.rate_limit = 100,10 + +## Enable the Proxy Protocol V1/2 if the EMQ cluster is deployed behind +## HAProxy or Nginx. +## +## See: listener.tcp..proxy_protocol +## +## Value: on | off +## listener.ssl.external.proxy_protocol = on + +## Sets the timeout for proxy protocol. +## +## See: listener.tcp..proxy_protocol_timeout +## +## Value: Duration +## listener.ssl.external.proxy_protocol_timeout = 3s + +## TLS versions only to protect from POODLE attack. +## +## See: http://erlang.org/doc/man/ssl.html +## +## Value: String, seperated by ',' ## listener.ssl.external.tls_versions = tlsv1.2,tlsv1.1,tlsv1 ## TLS Handshake timeout. @@ -842,17 +862,20 @@ listener.ssl.external.access.1 = allow all 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 +## +## See: 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. ## +## See: http://erlang.org/doc/man/ssl.html +## ## Value: File listener.ssl.external.certfile = {{ platform_etc_dir }}/certs/cert.pem -## Path to a file containing PEM-encoded CA certificates. The CA certificates +## Path to the file containing PEM-encoded CA certificates. The CA certificates ## are used during server authentication and when building the client certificate chain. ## ## Value: File @@ -891,14 +914,17 @@ listener.ssl.external.certfile = {{ platform_etc_dir }}/certs/cert.pem ## 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. -## 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 -## algorithm and the message digest algorithm. Selecting a good cipher suite is critical -## for the application’s data security, confidentiality and performance. +## 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 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 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. +## 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 ## @@ -907,8 +933,8 @@ listener.ssl.external.certfile = {{ platform_etc_dir }}/certs/cert.pem ## 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 -## a server to renegotiate the parameters of the SSL connection on the fly. +## SSL parameter renegotiation is a feature that allows a client and 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, ## you drop support for the insecure renegotiation, prone to MitM attacks. ## @@ -918,7 +944,8 @@ listener.ssl.external.certfile = {{ platform_etc_dir }}/certs/cert.pem ## A performance optimization setting, it allows clients to reuse ## pre-existing sessions, instead of initializing new ones. ## Read more about it here. -## More information at: http://erlang.org/doc/man/ssl.html +## +## See: http://erlang.org/doc/man/ssl.html ## ## Value: on | off ## listener.ssl.external.reuse_sessions = on @@ -938,38 +965,57 @@ listener.ssl.external.certfile = {{ platform_etc_dir }}/certs/cert.pem ## listener.ssl.external.peer_cert_as_username = cn ## TCP backlog for the SSL connection. -## See 'listener.tcp.external.backlog' +## +## See listener.tcp..backlog ## ## Value: Number >= 0 ## listener.ssl.external.backlog = 1024 ## The TCP send timeout for the SSL connection. -## See 'listener.tcp.external.send_timeout' +## +## See listener.tcp..send_timeout ## ## Value: Duration ## listener.ssl.external.send_timeout = 15s -## See 'listener.tcp.external.send_timeout_close' +## Close the SSL connection if send timeout. +## +## See: listener.tcp..send_timeout_close ## ## Value: on | off ## listener.ssl.external.send_timeout_close = on -## See 'listener.tcp.external.recbuf' +## The TCP receive buffer(os kernel) for the SSL connections. +## +## See: listener.tcp..recbuf ## ## Value: Bytes ## listener.ssl.external.recbuf = 4KB -## See 'listener.tcp.external.sndbuf' +## The TCP send buffer(os kernel) for internal MQTT connections. +## +## See: listener.tcp..sndbuf ## ## Value: Bytes ## listener.ssl.external.sndbuf = 4KB -## See 'listener.tcp.external.buffer' +## The size of the user-level software buffer used by the driver. +## +## See: listener.tcp..buffer ## ## Value: Bytes ## listener.ssl.external.buffer = 4KB -## See 'listener.tcp.external.nodelay' +## Sets the 'buffer = max(sndbuf, recbuf)' if this option is enabled. +## +## See: listener.tcp..tune_buffer +## +## Value: on | off +## listener.ssl.external.tune_buffer = on + +## The TCP_NODELAY flag for SSL connections. +## +## See: listener.tcp..nodelay ## ## Value: true | false ## listener.ssl.external.nodelay = true @@ -993,21 +1039,23 @@ listener.ws.external.acceptors = 4 ## Maximum number of concurrent MQTT/Websocket connections. ## ## Value: Number -listener.ws.external.max_clients = 64 +listener.ws.external.max_clients = 102400 ## 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. +## Mountpoint of the MQTT/Websocket Listener. +## +## See: listener.tcp..mountpoint ## ## Value: String ## listener.ws.external.mountpoint = external/ -## The access control rules for the MQTT/Websocket listener. +## The access control for the MQTT/Websocket listener. +## +## See: listener.tcp..access ## ## Value: ACL Rule listener.ws.external.access.1 = allow all @@ -1015,43 +1063,70 @@ listener.ws.external.access.1 = allow all ## Enable the Proxy Protocol V1/2 if the EMQ cluster is deployed behind ## HAProxy or Nginx. ## +## See: listener.tcp..proxy_protocol +## ## Value: on | off ## listener.ws.external.proxy_protocol = on -## See 'listener.tcp.external.proxy_protocol_timeout' +## Sets the timeout for proxy protocol. +## +## See: listener.tcp..proxy_protocol_timeout ## ## Value: Duration ## listener.ws.external.proxy_protocol_timeout = 3s -## TCP Options +## The TCP backlog of external MQTT/Websocket Listener. +## +## See: listener.tcp..backlog +## +## Value: Number >= 0 listener.ws.external.backlog = 1024 -## See 'listener.tcp.external.send_timeout' +## The TCP send timeout for external MQTT/Websocket connections. +## +## See: listener.tcp..send_timeout ## ## Value: Duration listener.ws.external.send_timeout = 15s -## See 'listener.tcp.external.send_timeout_close' +## Close the MQTT/Websocket connection if send timeout. +## +## See: listener.tcp..send_timeout_close ## ## Value: on | off listener.ws.external.send_timeout_close = on -## See 'listener.tcp.external.recbuf' +## The TCP receive buffer(os kernel) for external MQTT/Websocket connections. +## +## See: listener.tcp..recbuf ## ## Value: Bytes ## listener.ws.external.recbuf = 4KB -## See 'listener.tcp.external.sndbuf' +## The TCP send buffer(os kernel) for external MQTT/Websocket connections. +## +## See 'listener.tcp..sndbuf' ## ## Value: Bytes ## listener.ws.external.sndbuf = 4KB -## See 'listener.tcp.external.buffer' +## The size of the user-level software buffer used by the driver. +## +## See: listener.tcp..buffer ## ## Value: Bytes ## listener.ws.external.buffer = 4KB -## See 'listener.tcp.external.nodelay' +## Sets the 'buffer = max(sndbuf, recbuf)' if this option is enabled. +## +## See: listener.tcp..tune_buffer +## +## Value: on | off +listener.ws.external.tune_buffer = on + +## The TCP_NODELAY flag for external MQTT/Websocket connections. +## +## See: listener.tcp..nodelay ## ## Value: true | false listener.ws.external.nodelay = true @@ -1082,64 +1157,149 @@ listener.wss.external.max_clients = 64 ## Value: String ## listener.wss.external.zone = external -## See 'listener.ssl.external.mountpoint' +## Mountpoint of the MQTT/Websocket/SSL Listener. +## +## See 'listener.tcp..mountpoint' ## ## Value: String ## listener.wss.external.mountpoint = inbound/ -## See 'listener.ssl.external.acess.1' +## The access control rules for the MQTT/Websocket/SSL listener. +## +## See: listener.tcp..access. ## ## Value: ACL Rule listener.wss.external.access.1 = allow all -## See 'listener.ssl.external.proxy_protocol' +## Enable the Proxy Protocol V1/2 support. +## +## See: listener.tcp..proxy_protocol ## ## Value: on | off ## listener.wss.external.proxy_protocol = on -## See 'listener.ssl.external.proxy_protocol_timeout' +## Sets the timeout for proxy protocol. +## +## See: listener.tcp..proxy_protocol_timeout ## ## Value: Duration ## listener.wss.external.proxy_protocol_timeout = 3s -## SSL Options. Same to 'listener.ssl.*' +## TLS Handshake timeout. +## +## See: listener.ssl..handshake_timeout +## +## Value: Duration listener.wss.external.handshake_timeout = 15s +## Path to the file containing the user's private PEM-encoded key. +## +## See: listener.ssl..keyfile +## +## Value: File listener.wss.external.keyfile = {{ platform_etc_dir }}/certs/key.pem +## Path to a file containing the user certificate. +## +## See: listener.ssl..certfile +## +## Value: File listener.wss.external.certfile = {{ platform_etc_dir }}/certs/cert.pem +## Path to the file containing PEM-encoded CA certificates. +## +## See: listener.ssl..cacert +## +## Value: File ## listener.wss.external.cacertfile = {{ platform_etc_dir }}/certs/cacert.pem +## See: listener.ssl..dhfile +## +## Value: File ## listener.ssl.external.dhfile = {{ platform_etc_dir }}/certs/dh-params.pem +## See: listener.ssl..vefify +## +## Value: vefify_peer | verify_none ## listener.wss.external.verify = verify_peer +## See: listener.ssl..fail_if_no_peer_cert +## +## Value: false | true ## listener.wss.external.fail_if_no_peer_cert = true +## See: listener.ssl..ciphers +## +## Value: Ciphers ## listener.wss.external.ciphers = +## See: listener.ssl..secure_renegotiate +## +## Value: on | off ## listener.wss.external.secure_renegotiate = off +## See: listener.ssl..reuse_sessions +## +## Value: on | off ## listener.wss.external.reuse_sessions = on +## See: listener.ssl..honor_cipher_order +## +## Value: on | off ## listener.wss.external.honor_cipher_order = on +## See: listener.ssl..peer_cert_as_username +## +## Value: cn | dn ## listener.wss.external.peer_cert_as_username = cn -## TCP Options. Same to 'listener.tcp.*' +## TCP backlog for the Websocket/SSL connection. +## +## See 'listener.tcp..backlog' +## +## Value: Number >= 0 listener.wss.external.backlog = 1024 +## The TCP send timeout for the Websocket/SSL connection. +## +## See 'listener.tcp..send_timeout' +## +## Value: Duration listener.wss.external.send_timeout = 15s +## Close the Websocket/SSL connection if send timeout. +## +## See: listener.tcp..send_timeout_close +## +## Value: on | off listener.wss.external.send_timeout_close = on +## The TCP receive buffer(os kernel) for the Websocket/SSL connections. +## +## See: listener.tcp..recbuf +## +## Value: Bytes ## listener.wss.external.recbuf = 4KB +## The TCP send buffer(os kernel) for the Websocket/SSL connections. +## +## See: listener.tcp..sndbuf +## +## Value: Bytes ## listener.wss.external.sndbuf = 4KB +## The size of the user-level software buffer used by the driver. +## +## See: listener.tcp..buffer +## +## Value: Bytes ## listener.wss.external.buffer = 4KB +## The TCP_NODELAY flag for Websocket/SSL connections. +## +## See: listener.tcp..nodelay +## +## Value: true | false ## listener.wss.external.nodelay = true ##-------------------------------------------------------------------- @@ -1163,18 +1323,18 @@ listener.api.mgmt.acceptors = 4 listener.api.mgmt.max_clients = 64 ## The access control rules for the listener. -## More information at: https://github.com/emqtt/esockd#allowdeny +## +## See: 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. +## The TCP backlog for HTTP API. ## ## Value: Number >= 0 listener.api.mgmt.backlog = 512 -## The TCP send timeout. +## The TCP send timeout for HTTP API. ## ## Value: Duration listener.api.mgmt.send_timeout = 15s @@ -1196,13 +1356,15 @@ listener.api.mgmt.send_timeout_close = on sysmon.long_gc = false ## Enable Long Schedule(ms) monitoring. -## More information at: http://erlang.org/doc/man/erlang.html#system_monitor-2 +## +## See: http://erlang.org/doc/man/erlang.html#system_monitor-2 ## ## Value: Number sysmon.long_schedule = 240 ## Enable Large Heap monitoring. -## More information at: http://erlang.org/doc/man/erlang.html#system_monitor-2 +## +## See: http://erlang.org/doc/man/erlang.html#system_monitor-2 ## ## Value: bytes ## @@ -1210,13 +1372,15 @@ sysmon.long_schedule = 240 sysmon.large_heap = 8MB ## Enable Busy Port monitoring. -## More information at: http://erlang.org/doc/man/erlang.html#system_monitor-2 +## +## See: http://erlang.org/doc/man/erlang.html#system_monitor-2 ## ## Value: true | false sysmon.busy_port = false ## Enable Busy Dist Port monitoring. -## More information at: http://erlang.org/doc/man/erlang.html#system_monitor-2 +## +## See: http://erlang.org/doc/man/erlang.html#system_monitor-2 ## ## Value: true | false sysmon.busy_dist_port = true From 3a39706d8402135b23470210262230b778e9d5ac Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Thu, 4 Jan 2018 16:05:44 +0800 Subject: [PATCH 12/16] Add more options for 'listener.wss.' --- priv/emq.schema | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/priv/emq.schema b/priv/emq.schema index ca242c4c7..11c45cecb 100644 --- a/priv/emq.schema +++ b/priv/emq.schema @@ -1007,6 +1007,10 @@ end}. {datatype, string} ]}. +{mapping, "listener.ws.$name.mountpoint", "emqttd.listeners", [ + {datatype, string} +]}. + {mapping, "listener.ws.$name.access.$id", "emqttd.listeners", [ {datatype, string} ]}. @@ -1140,6 +1144,14 @@ end}. hidden ]}. +{mapping, "listener.wss.$name.tls_versions", "emqttd.listeners", [ + {datatype, string} +]}. + +{mapping, "listener.wss.$name.ciphers", "emqttd.listeners", [ + {datatype, string} +]}. + {mapping, "listener.wss.$name.handshake_timeout", "emqttd.listeners", [ {default, "15s"}, {datatype, {duration, ms}} @@ -1165,6 +1177,23 @@ end}. {datatype, {enum, [true, false]}} ]}. +{mapping, "listener.wss.$name.secure_renegotiate", "emqttd.listeners", [ + {datatype, flag} +]}. + +{mapping, "listener.wss.$name.reuse_sessions", "emqttd.listeners", [ + {default, on}, + {datatype, flag} +]}. + +{mapping, "listener.wss.$name.honor_cipher_order", "emqttd.listeners", [ + {datatype, flag} +]}. + +{mapping, "listener.wss.$name.peer_cert_as_username", "emqttd.listeners", [ + {datatype, {enum, [cn, dn]}} +]}. + {translation, "emqttd.listeners", fun(Conf) -> Filter = fun(Opts) -> [{K, V} || {K, V} <- Opts, V =/= undefined] end, From 86fc80b9830ebae27d56ca7dabadf655e03aa9af Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Thu, 4 Jan 2018 16:09:10 +0800 Subject: [PATCH 13/16] Change the type of 'mqtt.broker.sys_interval' to ms duration --- src/emqttd_broker.erl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/emqttd_broker.erl b/src/emqttd_broker.erl index 0161720f2..9e78207ce 100644 --- a/src/emqttd_broker.erl +++ b/src/emqttd_broker.erl @@ -105,9 +105,9 @@ datetime() -> io_lib:format( "~4..0w-~2..0w-~2..0w ~2..0w:~2..0w:~2..0w", [Y, M, D, H, MM, S])). -%% @doc Start a tick timer +%% @doc Start a tick timer. start_tick(Msg) -> - start_tick(timer:seconds(emqttd:env(broker_sys_interval, 60)), Msg). + start_tick(emqttd:env(broker_sys_interval, 60000), Msg). start_tick(0, _Msg) -> undefined; From fdc55de5099b11b4f6cbd5519abe808c2cda9f58 Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Thu, 4 Jan 2018 16:09:45 +0800 Subject: [PATCH 14/16] Change the type of 'mqtt.bridge.ping_down_interval' to ms duration --- src/emqttd_bridge.erl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/emqttd_bridge.erl b/src/emqttd_bridge.erl index 49b5a95d0..6c20290bd 100644 --- a/src/emqttd_bridge.erl +++ b/src/emqttd_bridge.erl @@ -92,7 +92,7 @@ parse_opts([{topic_prefix, Prefix} | Opts], State) -> parse_opts([{max_queue_len, Len} | Opts], State) -> parse_opts(Opts, State#state{max_queue_len = Len}); parse_opts([{ping_down_interval, Interval} | Opts], State) -> - parse_opts(Opts, State#state{ping_down_interval = Interval*1000}); + parse_opts(Opts, State#state{ping_down_interval = Interval}); parse_opts([_Opt | Opts], State) -> parse_opts(Opts, State). From a779c9f9cb743b82f5127f211153e1cd7db5d8d9 Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Thu, 4 Jan 2018 20:25:26 +0800 Subject: [PATCH 15/16] Add 'listener.wss.external.tls_versions' option --- etc/emq.conf | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/etc/emq.conf b/etc/emq.conf index 4d37515aa..b8c21dc40 100644 --- a/etc/emq.conf +++ b/etc/emq.conf @@ -1185,6 +1185,13 @@ listener.wss.external.access.1 = allow all ## Value: Duration ## listener.wss.external.proxy_protocol_timeout = 3s +## TLS versions only to protect from POODLE attack. +## +## See: listener.ssl..tls_versions +## +## Value: String, seperated by ',' +## listener.wss.external.tls_versions = tlsv1.2,tlsv1.1,tlsv1 + ## TLS Handshake timeout. ## ## See: listener.ssl..handshake_timeout From 4e7a12a838ec44b8d507d28d7e5a6a3a62a55599 Mon Sep 17 00:00:00 2001 From: Feng Lee Date: Sat, 6 Jan 2018 15:46:43 +0800 Subject: [PATCH 16/16] Fix #1430 - update the link to emqx-lwm2m project --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 83fe86177..96ed87f7c 100644 --- a/README.md +++ b/README.md @@ -93,7 +93,7 @@ Plugin | Descrip [emq_sn](https://github.com/emqtt/emq_sn) | MQTT-SN Protocol Plugin [emq_coap](https://github.com/emqtt/emq_coap) | CoAP Protocol Plugin [emq_stomp](https://github.com/emqtt/emq_stomp) | Stomp Protocol Plugin -[emq_lwm2m](https://github.com/emqtt/emq-lwm2m) | LWM2M Prototol Plugin +[emq_lwm2m](https://github.com/emqx/emqx-lwm2m) | LWM2M Prototol Plugin [emq_recon](https://github.com/emqtt/emq_recon) | Recon Plugin [emq_reloader](https://github.com/emqtt/emq_reloader) | Reloader Plugin [emq_sockjs](https://github.com/emqtt/emq_sockjs) | SockJS(Stomp) Plugin @@ -109,9 +109,7 @@ Plugin | Descrip * Issues: https://github.com/emqtt/emqttd/issues * QQ Group: 12222225 -## Partners - -[QingCloud](https://qingcloud.com) is the world’s first IaaS provider that can deliver any number of IT resources in seconds and adopts a second-based billing system. QingCloud is committed to providing a reliable, secure, on-demand and real-time IT resource platform with excellent performance, which includes all components of a complete IT infrastructure system: computing, storage, networking and security. +## Test Servers The **q.emqtt.com** hosts a public Four-Node *EMQ* cluster on [QingCloud](https://qingcloud.com):