diff --git a/.gitignore b/.gitignore
index ceb12182f..91183b48b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,7 @@ deps
*.o
*.beam
*.plt
-*.example
+#*.example
erl_crash.dump
ebin
!ebin/.placeholder
diff --git a/apps/emqx_conf/README.md b/apps/emqx_conf/README.md
index f1efe7987..d33af7ce2 100644
--- a/apps/emqx_conf/README.md
+++ b/apps/emqx_conf/README.md
@@ -5,7 +5,6 @@ This application provides configuration management capabilities for EMQX.
At compile time it reads all configuration schemas and generates the following files:
* `config-en.md`: documentation for all configuration options.
* `schema-en.json`: JSON description of all configuration schema options.
- * `emqx.conf.example`: an example of a complete configuration file.
At runtime, it provides:
- Cluster configuration synchronization capability.
diff --git a/apps/emqx_conf/etc/emqx_conf.conf b/apps/emqx_conf/etc/emqx_conf.conf
index 2d7b8d910..2f2d1a779 100644
--- a/apps/emqx_conf/etc/emqx_conf.conf
+++ b/apps/emqx_conf/etc/emqx_conf.conf
@@ -7,7 +7,7 @@
## To avoid confusion, please do not store the same configs in both files.
##
## See {{ emqx_configuration_doc }} for more details.
-## Configuration full example can be found in emqx.conf.example
+## Configuration full example can be found in etc/examples
node {
name = "emqx@127.0.0.1"
diff --git a/apps/emqx_conf/src/emqx_conf.erl b/apps/emqx_conf/src/emqx_conf.erl
index 584a10a8d..51c353edf 100644
--- a/apps/emqx_conf/src/emqx_conf.erl
+++ b/apps/emqx_conf/src/emqx_conf.erl
@@ -30,7 +30,6 @@
-export([reset/2, reset/3]).
-export([dump_schema/2]).
-export([schema_module/0]).
--export([gen_example_conf/2]).
-export([check_config/2]).
%% TODO: move to emqx_dashboard when we stop building api schema at build time
@@ -161,8 +160,7 @@ dump_schema(Dir, SchemaModule) ->
ok = gen_schema_json(Dir, SchemaModule, Lang)
end,
["en", "zh"]
- ),
- ok = gen_example_conf(Dir, SchemaModule).
+ ).
%% for scripts/spellcheck.
gen_schema_json(Dir, SchemaModule, Lang) ->
@@ -202,11 +200,6 @@ gen_config_md(Dir, SchemaModule, Lang) ->
io:format(user, "===< Generating: ~s~n", [SchemaMdFile]),
ok = gen_doc(SchemaMdFile, SchemaModule, Lang).
-gen_example_conf(Dir, SchemaModule) ->
- SchemaMdFile = filename:join([Dir, "emqx.conf.example"]),
- io:format(user, "===< Generating: ~s~n", [SchemaMdFile]),
- ok = gen_example(SchemaMdFile, SchemaModule).
-
%% @doc return the root schema module.
-spec schema_module() -> module().
schema_module() ->
@@ -250,17 +243,6 @@ gen_doc(File, SchemaModule, Lang) ->
Doc = hocon_schema_md:gen(SchemaModule, Opts),
file:write_file(File, Doc).
-gen_example(File, SchemaModule) ->
- %% we do not generate description in example files
- %% so there is no need for a desc_resolver
- Opts = #{
- title => <<"EMQX Configuration Example">>,
- body => <<"">>,
- include_importance_up_from => ?IMPORTANCE_MEDIUM
- },
- Example = hocon_schema_example:gen(SchemaModule, Opts),
- file:write_file(File, Example).
-
gen_api_schema_json_iodata(SchemaMod, SchemaInfo) ->
emqx_dashboard_swagger:gen_api_schema_json_iodata(
SchemaMod,
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 000000000..013939394
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,16 @@
+# Examples
+
+Here are examples of how to configure features In EMQX, most of them can be used directly by copy-paste content into the `emqx.conf` file, others may need to be slightly modified to use, for example, you should change the listener port or HTTP URL to what you actually used.
+
+Although we have tried to show every configurable field in the example,
+you do not need to care about each one, since most of them already have default values and can be omitted in the configuration file.
+
+If you are confused about some fields, please refer to our documents, here are just some simple configuration examples with necessary descriptions.
+
+
+## Documentation
+
+The EMQX documentation is available at [www.emqx.io/docs/en/latest/](https://www.emqx.io/docs/en/latest/).
+
+The EMQX Enterprise documentation is available at [docs.emqx.com/en/](https://docs.emqx.com/en/).
+
diff --git a/examples/alarm.conf.example b/examples/alarm.conf.example
new file mode 100644
index 000000000..537341ea2
--- /dev/null
+++ b/examples/alarm.conf.example
@@ -0,0 +1,22 @@
+##--------------------------------------------------------------------
+## Alarm
+##
+## Configuring how to handle the alarms generated from sysmon.*.conf.example
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+alarm {
+ ## The actions triggered when the alarm is activated
+ ## Type: Array of the below enum
+ ## - log :: write the alarm to log
+ ## - publish :: publish the alarm as an MQTT message to the system topics
+ actions = [log, publish]
+
+ ## Maximum total number of deactivated alarms to keep as history
+ ## Type: Range from 1 to 3000
+ size_limit = 1000
+
+ ## Retention time of deactivated alarms
+ validity_period = 24h
+}
diff --git a/examples/cluster-with-dns.conf.example b/examples/cluster-with-dns.conf.example
new file mode 100644
index 000000000..f979eb689
--- /dev/null
+++ b/examples/cluster-with-dns.conf.example
@@ -0,0 +1,33 @@
+##--------------------------------------------------------------------
+## Cluster in service discovery via DNS SRV records mode
+##
+## Configs to instruct how individual nodes can discover each other
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+cluster {
+ ## Human-friendly name of the EMQX cluster.
+ name = emqxcl
+
+ ## Service discovery method for the cluster nodes
+ discovery_strategy = dns
+
+ ## List of core nodes that the replicant will connect to
+ core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
+
+ ## Remove disconnected nodes from the cluster after this interval
+ autoclean = 5m
+
+ ## If true, the node will try to heal network partitions automatically
+ autoheal = true
+
+ dns {
+ ## The domain name from which to discover peer EMQX nodes' IP addresses
+ name = localhost
+
+ ## DNS record type
+ ## Type: enum: a | srv
+ record_type = a
+ }
+ }
diff --git a/examples/cluster-with-etcd-ssl.conf.example b/examples/cluster-with-etcd-ssl.conf.example
new file mode 100644
index 000000000..b7c642770
--- /dev/null
+++ b/examples/cluster-with-etcd-ssl.conf.example
@@ -0,0 +1,84 @@
+##--------------------------------------------------------------------
+## Cluster in service discovery using 'etcd' service mode
+##
+## Configs to instruct how individual nodes can discover each other
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+cluster {
+ ## Human-friendly name of the EMQX cluster.
+ name = emqxcl
+
+ ## Service discovery method for the cluster nodes
+ discovery_strategy = etcd
+
+ ## List of core nodes that the replicant will connect to
+ core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
+
+ ## Remove disconnected nodes from the cluster after this interval
+ autoclean = 5m
+
+ ## If true, the node will try to heal network partitions automatically
+ autoheal = true
+
+ etcd {
+ ## List of endpoint URLs of the etcd cluster
+ server = "http://ur1,http://ur2"
+
+ ## Key prefix used for EMQX service discovery
+ prefix = emqxcl
+
+ ## Expiration time of the etcd key associated with the node.
+ node_ttl = 1m
+
+ ssl_options {
+ ## Trusted PEM format CA certificates bundle file
+ cacertfile = "data/certs/cacert.pem"
+
+ ## PEM format certificates chain file
+ certfile = "data/certs/cert.pem"
+
+ ## PEM format private key file
+ keyfile = "data/certs/key.pem"
+
+ ## Enable or disable peer verification
+ verify = verify_none ## use verify_peer to enable
+
+ ## if `verify' is ebabled, whit true, the connection fails if the client does not have a certificate to send
+ fail_if_no_peer_cert = false
+
+ ## Enable TLS session reuse
+ reuse_sessions = true
+
+ ## Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path
+ depth = 10
+
+ ## Which versions are to be supported
+ versions = [tlsv1.3, tlsv1.2]
+
+ ## TLS cipher suite names
+ ## Note: By default, all available suites are supported, you do not need to set this
+ ciphers = ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
+
+ ## Allows a client and a server to renegotiate the parameters of the SSL connection on the fly
+ secure_renegotiate = true
+
+ ## Log level for SSL communication
+ ## Type: emergency | alert | critical | error | warning | notice | info | debug | none | all
+ log_level = notice
+
+ ## Hibernate the SSL process after idling for amount of time reducing its memory footprint
+ hibernate_after = 5s
+
+ ## Forces the cipher to be set based on the server-specified order instead of the client-specified order
+ honor_cipher_order = true
+
+ ## Setting this to false to disable client-initiated renegotiation
+ client_renegotiation = true
+
+ ## Maximum time duration allowed for the handshake to complete
+ handshake_timeout = 15s
+ }
+ }
+}
diff --git a/examples/cluster-with-etcd.conf.example b/examples/cluster-with-etcd.conf.example
new file mode 100644
index 000000000..17ab604d6
--- /dev/null
+++ b/examples/cluster-with-etcd.conf.example
@@ -0,0 +1,36 @@
+##--------------------------------------------------------------------
+## Cluster in service discovery using 'etcd' service mode
+##
+## Configs to instruct how individual nodes can discover each other
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+cluster {
+ ## Human-friendly name of the EMQX cluster.
+ name = emqxcl
+
+ ## Service discovery method for the cluster nodes
+ discovery_strategy = etcd
+
+ ## List of core nodes that the replicant will connect to
+ core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
+
+ ## Remove disconnected nodes from the cluster after this interval
+ autoclean = 5m
+
+ ## If true, the node will try to heal network partitions automatically
+ autoheal = true
+
+ etcd {
+ ## List of endpoint URLs of the etcd cluster
+ ## Type: Comma Separated String
+ server = "http://ur1,http://ur2"
+
+ ## Key prefix used for EMQX service discovery
+ prefix = emqxcl
+
+ ## Expiration time of the etcd key associated with the node
+ node_ttl = 1m
+ }
+}
diff --git a/examples/cluster-with-k8s.conf.example b/examples/cluster-with-k8s.conf.example
new file mode 100644
index 000000000..4fd329b24
--- /dev/null
+++ b/examples/cluster-with-k8s.conf.example
@@ -0,0 +1,42 @@
+##--------------------------------------------------------------------
+## Cluster in service discovery via Kubernetes API server mode
+##
+## Configs to instruct how individual nodes can discover each other
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+cluster {
+ ## Human-friendly name of the EMQX cluster.
+ name = emqxcl
+
+ ## Service discovery method for the cluster nodes
+ discovery_strategy = k8s
+
+ ## List of core nodes that the replicant will connect to
+ core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
+
+ ## Remove disconnected nodes from the cluster after this interval
+ autoclean = 5m
+
+ ## If true, the node will try to heal network partitions automatically
+ autoheal = true
+
+ k8s {
+ ## Kubernetes API endpoint URL
+ apiserver = "https://kubernetes.default.svc:443"
+
+ ## EMQX broker service name
+ service_name = emqx
+
+ ## Address type used for connecting to the discovered nodes
+ ## Type: ip | dns | hostname
+ address_type = ip
+
+ ## Kubernetes namespace
+ namespace = default
+
+ ## Node name suffix
+ suffix = "pod.local"
+ }
+}
diff --git a/examples/cluster-with-manual.conf.example b/examples/cluster-with-manual.conf.example
new file mode 100644
index 000000000..f075ea389
--- /dev/null
+++ b/examples/cluster-with-manual.conf.example
@@ -0,0 +1,24 @@
+##--------------------------------------------------------------------
+## Cluster in service discovery via manual join mode
+##
+## Configs to instruct how individual nodes can discover each other
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+cluster {
+ ## Human-friendly name of the EMQX cluster.
+ name = emqxcl
+
+ ## Service discovery method for the cluster nodes
+ discovery_strategy = manual
+
+ ## List of core nodes that the replicant will connect to
+ core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
+
+ ## Remove disconnected nodes from the cluster after this interval
+ autoclean = 5m
+
+ ## If true, the node will try to heal network partitions automatically
+ autoheal = true
+ }
diff --git a/examples/cluster-with-static.conf.example b/examples/cluster-with-static.conf.example
new file mode 100644
index 000000000..76a9d9980
--- /dev/null
+++ b/examples/cluster-with-static.conf.example
@@ -0,0 +1,27 @@
+##--------------------------------------------------------------------
+## Cluster in service discovery via static nodes mode
+##
+## Configs to instruct how individual nodes can discover each other
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+cluster {
+ ## Human-friendly name of the EMQX cluster.
+ name = emqxcl
+
+ ## Service discovery method for the cluster nodes
+ discovery_strategy = static
+
+ ## List of core nodes that the replicant will connect to
+ core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
+
+ ## Remove disconnected nodes from the cluster after this interval
+ autoclean = 5m
+
+ ## If true, the node will try to heal network partitions automatically
+ autoheal = true
+
+ ## List EMQX node names in the static cluster
+ static.seeds = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
+ }
diff --git a/examples/conn_congestion.conf.example b/examples/conn_congestion.conf.example
new file mode 100644
index 000000000..e6f3597d1
--- /dev/null
+++ b/examples/conn_congestion.conf.example
@@ -0,0 +1,15 @@
+##--------------------------------------------------------------------
+## Connection Congestion
+##
+## Generating alarm when MQTT connection congested
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+conn_congestion {
+ ## Enable or disable connection congestion alarm
+ enable_alarm = true
+
+ ## Minimal time before clearing the alarm
+ min_alarm_sustain_duration = 1m
+}
diff --git a/examples/dashboard-with-http.conf.example b/examples/dashboard-with-http.conf.example
new file mode 100644
index 000000000..8cf68ab33
--- /dev/null
+++ b/examples/dashboard-with-http.conf.example
@@ -0,0 +1,41 @@
+##--------------------------------------------------------------------
+## Dashboard with HTTP Listener
+##
+## Configuration for EMQX dashboard
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+dashboard {
+ ## JWT token expiration time
+ token_expired_time = 60m
+
+ ## Support Cross-Origin Resource Sharing (CORS)
+ cors = false
+
+ listeners.http {
+ ## Port or Address to listen on, 0 means disable
+ bind = "0.0.0.0:18083" ## or just a port number, e.g. 18083
+
+ ## Socket acceptor pool size for TCP protocols
+ num_acceptors = 8
+
+ ## Maximum number of simultaneous connections
+ max_connections = 512
+
+ ## Defines the maximum length that the queue of pending connections can grow to
+ backlog = 1024
+
+ ## Send timeout for the socket
+ send_timeout = 10s
+
+ ## Enable IPv6 support, default is false, which means IPv4 only
+ inet6 = false
+
+ ## Disable IPv4-to-IPv6 mapping for the listener
+ ipv6_v6only = false
+
+ ## Enable support for `HAProxy` header
+ proxy_header = false
+ }
+}
diff --git a/examples/dashboard-with-https.conf.example b/examples/dashboard-with-https.conf.example
new file mode 100644
index 000000000..5cc277e47
--- /dev/null
+++ b/examples/dashboard-with-https.conf.example
@@ -0,0 +1,86 @@
+##--------------------------------------------------------------------
+## Dashboard with HTTPS Listener
+##
+## Configuration for EMQX dashboard
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+dashboard {
+ ## JWT token expiration time
+ token_expired_time = 60m
+
+ ## Support Cross-Origin Resource Sharing (CORS)
+ cors = false
+
+ listeners.https {
+
+ ## Port or Address to listen on, 0 means disable
+ bind = "0.0.0.0:18084" ## or just a port number, e.g. 18084
+
+ ## Socket acceptor pool size for TCP protocols
+ num_acceptors = 8
+
+ ## Maximum number of simultaneous connections
+ max_connections = 512
+
+ ## Defines the maximum length that the queue of pending connections can grow to
+ backlog = 1024
+
+ ## Send timeout for the socket
+ send_timeout = 10s
+
+ ## Enable IPv6 support, default is false, which means IPv4 only
+ inet6 = false
+
+ ## Disable IPv4-to-IPv6 mapping for the listener
+ ipv6_v6only = false
+
+ ## Enable support for `HAProxy` header
+ proxy_header = false
+
+ ## Trusted PEM format CA certificates bundle file
+ cacertfile = "data/certs/cacert.pem"
+
+ ## PEM format certificates chain file
+ certfile = "data/certs/cert.pem"
+
+ ## PEM format private key file
+ keyfile = "data/certs/key.pem"
+
+ ## Enable or disable peer verification
+ verify = verify_none ## use verify_peer to enable
+
+ ## Enable TLS session reuse
+ reuse_sessions = true
+
+ ## Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path
+ depth = 10
+
+ ## Which versions are to be supported
+ versions = [tlsv1.3, tlsv1.2]
+
+ ## TLS cipher suite names
+ ## Note: By default, all available suites are supported, you do not need to set this
+ ciphers = ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
+
+ ## Allows a client and a server to renegotiate the parameters of the SSL connection on the fly
+ secure_renegotiate = true
+
+ ## Log level for SSL communication
+ ## Type: emergency | alert | critical | error | warning | notice | info | debug | none | all
+ log_level = notice
+
+ ## Hibernate the SSL process after idling for amount of time reducing its memory footprint
+ hibernate_after = 5s
+
+ ## Forces the cipher to be set based on the server-specified order instead of the client-specified order
+ honor_cipher_order = true
+
+ ## Setting this to false to disable client-initiated renegotiation
+ client_renegotiation = true
+
+ ## Maximum time duration allowed for the handshake to complete
+ handshake_timeout = 15s
+ }
+}
diff --git a/examples/delayed.conf.example b/examples/delayed.conf.example
new file mode 100644
index 000000000..7b0d243c2
--- /dev/null
+++ b/examples/delayed.conf.example
@@ -0,0 +1,15 @@
+##--------------------------------------------------------------------
+## Delayed publish
+##
+## Configuring the delayed publish feature
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+delayed {
+ enable = true ## false for disabled
+
+ ## Maximum number of delayed messages
+ ## Default: 0 (0 is no limit)
+ max_delayed_messages = 0
+}
diff --git a/examples/exhook.conf.example b/examples/exhook.conf.example
new file mode 100644
index 000000000..8adcfcab9
--- /dev/null
+++ b/examples/exhook.conf.example
@@ -0,0 +1,52 @@
+##--------------------------------------------------------------------
+## gRPC Hook Extension
+##
+## Allows users to process EMQX Hooks using other programming languages
+##--------------------------------------------------------------------
+
+exhook.servers = [
+ {
+ ## Name of the exhook server
+ name = "server_1"
+
+ ## Feature switch
+ enable = false
+
+ ## URL of gRPC server
+ url = "http://127.0.0.1:9090"
+
+ ## The timeout of request gRPC server
+ request_timeout = 5s
+
+ ## This value will be returned when the request to the gRPC server fails for any reason
+ ## Type:
+ ## - deny :: stop to execute this hook.
+ ## - ignore :: continue to execute this hook
+ failed_action = deny
+
+ ## Interval of automatically reconnecting the gRPC server when the connection is broken
+ ## Type:
+ ## - false :: Never reconnect
+ ## - Time Duration, e.g.15s, 10m, 1h :: Reconnecting Interval
+ auto_reconnect = 60s
+
+ ## The process pool size for gRPC client
+ pool_size = 8
+
+ ## Connection socket options
+ socket_options {
+ ## Whether periodic transmission on a connected socket when no other data is exchanged
+ keepalive = true
+
+ ## TCP_NODELAY switch
+ nodelay = true
+
+ ## The minimum size of receive buffer to use for the socket
+ recbuf = "64KB"
+
+ ## The minimum size of send buffer to use for the socket
+ sndbuf = "16KB"
+ }
+ },
+ {name = "server_2", url = "http://127.0.0.1:9091"}
+]
diff --git a/examples/file_transfer-with-local-exporter.conf.example b/examples/file_transfer-with-local-exporter.conf.example
new file mode 100644
index 000000000..8dbd04f66
--- /dev/null
+++ b/examples/file_transfer-with-local-exporter.conf.example
@@ -0,0 +1,50 @@
+##--------------------------------------------------------------------
+## File Transfer
+##
+## Enables the File Transfer over MQTT feature
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## Note: This configuration only works for the EMQX Enterprise version
+
+file_transfer {
+ ## Enable the File Transfer feature
+ enable = true
+
+ ## Storage backend settings
+ storage {
+ ## Local file system backend setting
+ ## Currently, it's the only available storage backend.
+ local {
+ ## Enable the backend
+ enable = true
+
+ ## Segments and temporary files storage settings
+ segments {
+ ## Directory where these files are stored
+ root = "/var/lib/emqx/transfers/segments"
+
+ ## Garbage collection settings
+ gc {
+ ## How often to run GC
+ interval = 1h
+
+ ## Maximum time to keep parts of incomplete transfers for
+ maximum_segments_ttl = 24h
+ }
+ }
+
+ ## Local filesystem exporter
+ exporter.local {
+
+ ## Enable the backend
+ ## Note: Only one backend may be enabled at a time
+ enable = true
+
+ ## Directory in the local file system where to store transferred files
+ root = "/var/lib/emqx/transfers/exports"
+ }
+ }
+ }
+}
diff --git a/examples/file_transfer-with-s3-exporter.conf.example b/examples/file_transfer-with-s3-exporter.conf.example
new file mode 100644
index 000000000..a59c7918c
--- /dev/null
+++ b/examples/file_transfer-with-s3-exporter.conf.example
@@ -0,0 +1,72 @@
+##--------------------------------------------------------------------
+## File Transfer
+##
+## Enables the File Transfer over MQTT feature
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## Note: This configuration only works for the EMQX Enterprise version
+
+file_transfer {
+ ## Enable the File Transfer feature
+ enable = true
+
+ ## Storage backend settings
+ storage {
+ ## Local file system backend setting
+ ## Currently, it's the only available storage backend.
+ local {
+ ## Enable the backend
+ enable = true
+
+ ## Segments and temporary files storage settings
+ segments {
+ ## Directory where these files are stored
+ root = "/var/lib/emqx/transfers/segments"
+
+ ## Garbage collection settings
+ gc {
+ ## How often to run GC
+ interval = 1h
+
+ ## Maximum time to keep parts of incomplete transfers for
+ maximum_segments_ttl = 24h
+ }
+ }
+
+ ## S3-compatible object storage exporter
+ exporter.s3 {
+
+ ## Disable the backend
+ ## Note: Only one backend may be enabled at a time.
+ enable = true
+
+ ## Endpoint of S3 API of the object storage service of your choice
+ host = "s3.us-east-1.amazonaws.com"
+ port = 443
+
+ ## Credentials to use to authorize with the S3 API
+ access_key_id = "AKIA27EZDDM9XLINWXFE"
+ secret_access_key = "******"
+
+ ## Which bucket to store transferred files in?
+ bucket = "my-bucket"
+
+ ## TTL of file download URLs exposed through File Transfer API
+ url_expire_time = 1h
+
+ ## Enable the HTTPS
+ transport_options {
+ ssl.enable = true
+
+ ## Timeout for connection attempts
+ connect_timeout = 15s
+
+ ## Attempt to talk through IPv6 first
+ ipv6_probe = true
+ }
+ }
+ }
+ }
+}
diff --git a/examples/flapping_detect.conf.example b/examples/flapping_detect.conf.example
new file mode 100644
index 000000000..b33a805ea
--- /dev/null
+++ b/examples/flapping_detect.conf.example
@@ -0,0 +1,21 @@
+##--------------------------------------------------------------------
+## Flapping Detect
+##
+## Ban the client when the times of connections exceed the limit in the time window
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+flapping_detect {
+ ## use false to disabled
+ enable = true
+
+ ## Time window for flapping detection
+ window_time = 1m
+
+ ## Maximum number of connects allowed for a MQTT Client in window_time
+ max_count = 15
+
+ ## How long the flapping clientid will be banned
+ ban_time = 5m
+}
diff --git a/examples/force_gc.conf.example b/examples/force_gc.conf.example
new file mode 100644
index 000000000..e682d723d
--- /dev/null
+++ b/examples/force_gc.conf.example
@@ -0,0 +1,18 @@
+##--------------------------------------------------------------------
+## Force garbage collection
+##
+## Force garbage collection in MQTT connection process after they process certain number of messages or bytes of data
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+force_gc {
+ ## set to false to disable this
+ enable = true
+
+ ## GC the process after this many received messages
+ count = 16000
+
+ ## GC the process after specified number of bytes have passed through
+ bytes = 16MB
+}
diff --git a/examples/force_shutdown.conf.example b/examples/force_shutdown.conf.example
new file mode 100644
index 000000000..b049691c6
--- /dev/null
+++ b/examples/force_shutdown.conf.example
@@ -0,0 +1,19 @@
+##--------------------------------------------------------------------
+## Force Shutdown
+##
+## Forced closing of the overloaded session
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+force_shutdown {
+ ## false to disable this
+ enable = true
+
+ ## Maximum mailbox size for each Erlang process
+ ## Note: Do not modify this unless you know what this is for
+ max_mailbox_size = 1000
+
+ ## Maximum heap size for each session process
+ max_heap_size = 32MB
+}
diff --git a/examples/gateway.coap.conf.example b/examples/gateway.coap.conf.example
new file mode 100644
index 000000000..a4d4bb267
--- /dev/null
+++ b/examples/gateway.coap.conf.example
@@ -0,0 +1,24 @@
+##--------------------------------------------------------------------
+## Gateway CoAP
+##
+## Add a CoAP gateway
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+gateway.coap {
+
+ ## When publishing or subscribing, prefix all topics with a mountpoint string.
+ ## It's a way that you can use to implement isolation of message routing between different
+ ## gateway protocols
+ mountpoint = "coap/"
+
+ ## Enable or disable connection mode.
+ ## Connection mode is a feature of non-standard protocols. When connection mode is enabled,
+ ## it is necessary to maintain the creation, authentication and alive of connection resources
+ connection_required = false
+
+ listeners.udp.default {
+ bind = "0.0.0.0:5683"
+ }
+}
diff --git a/examples/gateway.exproto.conf.example b/examples/gateway.exproto.conf.example
new file mode 100644
index 000000000..04c95d98c
--- /dev/null
+++ b/examples/gateway.exproto.conf.example
@@ -0,0 +1,31 @@
+##--------------------------------------------------------------------
+## Gateway Exproto
+##
+## Add an Exproto gateway
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+gateway.exproto {
+
+ ## When publishing or subscribing, prefix all topics with a mountpoint string.
+ ## It's a way that you can use to implement isolation of message routing between different
+ ## gateway protocols
+ mountpoint = "exproto/"
+
+ ## Configurations for starting the ConnectionAdapter service
+ server {
+ bind = "0.0.0.0:9100"
+ ssl_options {verify = "verify_none"}
+ }
+
+ ## Configurations for request to ConnectionHandler service
+ handler {
+ address = "http://127.0.0.1:9001"
+ ssl_options {enable = false}
+ }
+
+ listeners.tcp.default {
+ bind = "0.0.0.0:7993"
+ }
+}
diff --git a/examples/gateway.lwm2m.conf.example b/examples/gateway.lwm2m.conf.example
new file mode 100644
index 000000000..2c9b55c04
--- /dev/null
+++ b/examples/gateway.lwm2m.conf.example
@@ -0,0 +1,62 @@
+##--------------------------------------------------------------------
+## Gateway LwM2M
+##
+## Add a LwM2M gateway
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+gateway.lwm2m {
+
+ ## When publishing or subscribing, prefix all topics with a mountpoint string.
+ ## It's a way that you can use to implement isolation of message routing between different
+ ## gateway protocols
+ mountpoint = "lwm2m/"
+
+ ## The Directory for LwM2M Resource definition.
+ xml_dir = "etc/lwm2m_xml/"
+
+ ## Automatically observe the object list of REGISTER packet.
+ auto_observe = false
+
+ ## Minimum value of lifetime allowed to be set by the LwM2M client.
+ lifetime_min = 1s
+
+ ## Maximum value of lifetime allowed to be set by the LwM2M client.
+ lifetime_max = 86400s
+
+ ## The value of the time window during which the network link is considered valid by
+ ## the LwM2M Gateway in QMode mode.
+ qmode_time_window = 22s
+
+ ## Topic configuration for LwM2M's gateway publishing and subscription.
+ translators {
+ ## The topic for receiving downstream commands.
+ ## For each new LwM2M client that succeeds in going online, the gateway creates a
+ ## subscription relationship to receive downstream commands and send it to the LwM2M client
+ command { topic = "dn/#" }
+
+ ## The topic for gateway to publish the notify events from LwM2M client.
+ ## After succeed observe a resource of LwM2M client, Gateway will send the notify events
+ ## via this topic, if the client reports any resource changes
+ notify { topic = "up/notify" }
+
+ ## The topic for gateway to publish the register events from LwM2M client.
+ register { topic = "up/register" },
+
+ ## The topic for gateway to publish the acknowledge events from LwM2M client.
+ response { topic = "up/resp" },
+
+ ## The topic for gateway to publish the update events from LwM2M client.
+ update { topic = "up/resp" }
+ }
+
+ ## Policy for publishing UPDATE event message.
+ ## - always: send update events as long as the UPDATE request is received.
+ ## - contains_object_list: send update events only if the UPDATE request carries any Object List"""
+ update_msg_publish_condition = always
+
+ listeners.udp.default {
+ bind = "0.0.0.0:5784"
+ }
+}
diff --git a/examples/gateway.mqttsn.conf.example b/examples/gateway.mqttsn.conf.example
new file mode 100644
index 000000000..7785454f3
--- /dev/null
+++ b/examples/gateway.mqttsn.conf.example
@@ -0,0 +1,38 @@
+##--------------------------------------------------------------------
+## Gateway MQTT-SN
+##
+## Add a MQTT-SN gateway
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+gateway.mqttsn {
+
+ ## When publishing or subscribing, prefix all topics with a mountpoint string.
+ ## It's a way that you can use to implement isolation of message routing between different
+ ## gateway protocols
+ mountpoint = "mqttsn/"
+
+ ## Whether to periodically broadcast ADVERTISE messages
+ broadcast = true
+
+ ## The Gateway ID.
+ ## When the broadcast option is enabled, the gateway will broadcast ADVERTISE message with this value
+ gateway_id = 1
+
+ ## Allows connectionless clients to publish messages with a Qos of -1.
+ ## This feature is defined for very simple client implementations which do not support any other
+ ## features except this one. There is no connection setup nor tear down, no registration nor
+ ## subscription. The client just sends its 'PUBLISH' messages to a GW
+ enable_qos3 = false
+
+ ## The pre-defined topic IDs and topic names
+ predefined = [
+ {id = 1, topic = "predefined/topic1"},
+ {id = 2, topic = "predefined/topic2"}
+ ]
+
+ listeners.udp.default {
+ bind = "0.0.0.0:1884"
+ }
+}
diff --git a/examples/gateway.stomp.conf.example b/examples/gateway.stomp.conf.example
new file mode 100644
index 000000000..ab09a45f7
--- /dev/null
+++ b/examples/gateway.stomp.conf.example
@@ -0,0 +1,30 @@
+##--------------------------------------------------------------------
+## Gateway STOMP
+##
+## Add STOMP CoAP gateway
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+gateway.stomp {
+
+ ## When publishing or subscribing, prefix all topics with a mountpoint string.
+ ## It's a way that you can use to implement isolation of message routing between different
+ ## gateway protocols
+ mountpoint = "stomp/"
+
+ frame {
+ ## The maximum number of Header
+ max_headers = 10
+
+ ## The maximum string length of the Header name and value.
+ max_headers_length = 1024
+
+ ## The Maximum number of bytes of Body allowed per Stomp packet.
+ max_body_length = 65536
+ }
+
+ listeners.tcp.default {
+ bind = "0.0.0.0:61613"
+ }
+}
diff --git a/examples/license.conf.example b/examples/license.conf.example
new file mode 100644
index 000000000..7444ae795
--- /dev/null
+++ b/examples/license.conf.example
@@ -0,0 +1,19 @@
+##--------------------------------------------------------------------
+## License
+##
+## Defines the EMQX Enterprise license
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## Note: This configuration only works for the EMQX Enterprise version
+
+license {
+ ## License Key
+ key = "MjIwMTExCjAKMTAKRXZhbHVhdGlvbgpjb250YWN0QGVtcXguaW8KZGVmYXVsdAoyMDIzMDEwOQoxODI1CjEwMAo=.MEUCIG62t8W15g05f1cKx3tA3YgJoR0dmyHOPCdbUxBGxgKKAiEAhHKh8dUwhU+OxNEaOn8mgRDtiT3R8RZooqy6dEsOmDI="
+ ## Low watermark limit below which license connection quota usage alarms are deactivated
+ connection_low_watermark = "75%"
+
+ ## High watermark limit above which license connection quota usage alarms are activated
+ connection_high_watermark = "80%"
+}
diff --git a/examples/listeners.quic.conf.example b/examples/listeners.quic.conf.example
new file mode 100644
index 000000000..49d4f58a1
--- /dev/null
+++ b/examples/listeners.quic.conf.example
@@ -0,0 +1,47 @@
+##--------------------------------------------------------------------
+## QUIC Listener
+##
+## Add a QUIC Listener
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## Note: Modifying the 'quicname' to what you need
+listeners.quic.quicname {
+ ## Port or Address to listen on, 0 means disable
+ bind = 14567 ## or with an IP, e.g. "127.0.0.1:14567"
+
+ ## When publishing or subscribing, prefix all topics with a mountpoint string
+ mountpoint = "${clientid}/msg"
+
+ ## Client authentication
+ ## Type:
+ ## - true :: enable
+ ## - false :: disable
+ ## - quick_deny_anonymous :: denied immediately without if username is not provided
+ enable_authn = true
+
+ ## Socket acceptor pool size for TCP protocols
+ acceptors = 16
+
+ ## Maximum number of simultaneous connections
+ ## Type: infinity | Integer
+ max_connections = infinity
+
+ ## TLS cipher suite names
+ ciphers = ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256"]
+
+ ssl_options {
+ ## Trusted PEM format CA certificates bundle file
+ cacertfile = "data/certs/cacert.pem"
+
+ ## PEM format certificates chain file
+ certfile = "data/certs/cert.pem"
+
+ ## PEM format private key file
+ keyfile = "data/certs/key.pem"
+
+ ## Enable or disable peer verification
+ verify = verify_none ## to verify_peer to enable
+ }
+}
diff --git a/examples/listeners.ssl.conf.example b/examples/listeners.ssl.conf.example
new file mode 100644
index 000000000..11078db6c
--- /dev/null
+++ b/examples/listeners.ssl.conf.example
@@ -0,0 +1,90 @@
+##--------------------------------------------------------------------
+## SSL Listener
+##
+## Add a SSL Listener
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## The SSL listener also supports all the fields listed in listeners.tcp.conf.example
+## only the SSL-specific fields are shown here
+
+## Note: Modifying the 'sslname' to what you need
+listeners.ssl.sslname {
+ ## Port or Address to listen on, 0 means disable
+ bind = 8883 ## or with an IP e.g. "127.0.0.1:8883"
+ enabled = true
+ acceptors = 16
+ enable_authn = true
+ max_connections = infinity
+ mountpoint = ""
+ proxy_protocol = false
+ proxy_protocol_timeout = 3s
+ tcp_options {
+ active_n = 100
+ backlog = 1024
+ buffer = 4KB
+ high_watermark = 1MB
+ keepalive = none
+ nodelay = true
+ reuseaddr = true
+ send_timeout = 15s
+ send_timeout_close = true
+ }
+ ssl_options {
+ ## Trusted PEM format CA certificates bundle file
+ cacertfile = "data/certs/cacert.pem"
+
+ ## PEM format certificates chain file
+ certfile = "data/certs/cert.pem"
+
+ ## PEM format private key file
+ keyfile = "data/certs/key.pem"
+
+ ## Enable or disable peer verification
+ verify = verify_none ## use verify_peer to enable
+
+ ## if `verify' is enabled, whit true, the connection fails if the client does not have a certificate to send
+ fail_if_no_peer_cert = false
+
+ ## Enable TLS session reuse
+ reuse_sessions = true
+
+ ## Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path
+ depth = 10
+
+ ## Which versions are to be supported
+ versions = [tlsv1.3, tlsv1.2]
+
+ ## TLS cipher suite names
+ ## Note: By default, all available suites are supported, you do not need to set this
+ ciphers = ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
+
+ ## Allows a client and a server to renegotiate the parameters of the SSL connection on the fly
+ secure_renegotiate = true
+
+ ## Log level for SSL communication
+ ## Type: emergency | alert | critical | error | warning | notice | info | debug | none | all
+ log_level = notice
+
+ ## Hibernate the SSL process after idling for amount of time reducing its memory footprint
+ hibernate_after = 5s
+
+ ## Forces the cipher to be set based on the server-specified order instead of the client-specified order
+ honor_cipher_order = true
+
+ ## Setting this to false to disable client-initiated renegotiation
+ client_renegotiation = true
+
+ ## Maximum time duration allowed for the handshake to complete
+ handshake_timeout = 15s
+
+ ocsp {
+ enable_ocsp_stapling = false
+ responder_url = "http://ocsp.example.com"
+ issuer_pem = true
+ refresh_http_timeout = 15s
+ refresh_interval = 5m
+ }
+ }
+}
diff --git a/examples/listeners.tcp.conf.example b/examples/listeners.tcp.conf.example
new file mode 100644
index 000000000..42e98b071
--- /dev/null
+++ b/examples/listeners.tcp.conf.example
@@ -0,0 +1,77 @@
+##--------------------------------------------------------------------
+## TCP Listener
+##
+## Add a TCP Listener
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## Note: Modifying the 'tcpname' to what you need
+listeners.tcp.tcpname {
+ ## Port or Address to listen on, 0 means disable
+ bind = 1883 ## or with an IP e.g. "127.0.0.1:1883"
+
+ ## Enable the Proxy Protocol V1/2 if the EMQX cluster is deployed behind HAProxy or Nginx
+ proxy_protocol = false
+
+ ## Timeout for proxy protocol
+ proxy_protocol_timeout = 8
+
+ ## When publishing or subscribing, prefix all topics with a mountpoint string
+ mountpoint = "mqtt" ## Do not set this unless you know what is it for
+
+ ## Client authentication
+ ## Type:
+ ## - true :: enable
+ ## - false :: disable
+ ## - quick_deny_anonymous :: denied immediately without if username is not provided
+ enable_authn = true
+
+ ## The access control rules for this listener
+ ## Type: See: https://github.com/emqtt/esockd#allowdeny
+ access_rules = ["allow all"]
+
+ ## Socket acceptor pool size for TCP protocols
+ acceptors = 16
+
+ ## Maximum number of simultaneous connections
+ ## Type: infinity | Integer
+ max_connections = infinity
+
+ tcp_options {
+ ## TCP backlog defines the maximum length that the queue of pending connections can grow to
+ backlog = 1024
+
+ ## The TCP send timeout for the connections
+ send_timeout = 15s
+
+ ## Timeout for proxy protocol
+ send_timeout_close = true
+
+ ## The TCP receive buffer (OS kernel) for the connections
+ recbuf = 2KB
+
+ ## The TCP send buffer (OS kernel) for the connections
+ sndbuf = 4KB
+
+ ## The size of the user-space buffer used by the driver
+ buffer = 4KB
+
+ ## The socket is set to a busy state when the amount of data queued internally by the VM socket implementation reaches this limit
+ high_watermark = 1MB
+
+ ## The TCP_NODELAY flag for the connections
+ nodelay = true
+
+ ## The SO_REUSEADDR flag for the connections
+ reuseaddr = true
+
+ ## Enable TCP keepalive for MQTT connections over TCP or SSL
+ ## Type: three comma separated numbers in the format of 'Idle,Interval,Probes'
+ ## - Idle: The number of seconds a connection needs to be idle before the server begins to send out keep-alive probes (Linux default 7200).
+ ## - Interval: The number of seconds between TCP keep-alive probes (Linux default 75).
+ ## - Probes: The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end (Linux default 9).
+ ## For example "240,30,5" means: EMQX should start sending TCP keepalive probes after the connection is in idle for 240 seconds, and the probes are sent every 30 seconds until a response is received from the MQTT client, if it misses 5 consecutive responses, EMQX should close the connection
+ keepalive = "none"
+ }
+}
diff --git a/examples/listeners.ws.conf.example b/examples/listeners.ws.conf.example
new file mode 100644
index 000000000..60523ac7a
--- /dev/null
+++ b/examples/listeners.ws.conf.example
@@ -0,0 +1,76 @@
+##--------------------------------------------------------------------
+## WebSocket Listener
+##
+## Add a WebSocket Listener
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## The WebSocket listener supports all the fields listed in listeners.tcp.conf.example
+## only the WebSocket-specific fields are shown here
+
+## Note: Modifying the 'wsname' to what you need
+listeners.ws.wsname {
+ ## Port or Address to listen on, 0 means disable
+ bind = "0.0.0.0:8083" # or just a port number, e.g. 8083
+ enabled = true
+ enable_authn = true
+ max_connections = infinity
+ proxy_protocol = false
+ proxy_protocol_timeout = 3s
+ mountpoint = ""
+ tcp_options {
+ active_n = 100
+ backlog = 1024
+ buffer = 4KB
+ high_watermark = 1MB
+ keepalive = none
+ nodelay = true
+ reuseaddr = true
+ send_timeout = 15s
+ send_timeout_close = true
+ }
+
+ websocket {
+ ## WebSocket's MQTT protocol path
+ ## Type: String
+ ## For Example:
+ ## with the default value, the address of EMQX Broker's WebSocket is: ws://8083/mqtt
+ mqtt_path = "/mqtt"
+
+ ## Whether a WebSocket message is allowed to contain multiple MQTT packets
+ ## Type: single | multiple
+ mqtt_piggyback = multiple
+
+ ## If true, compress WebSocket messages using zlib
+ compress = false
+
+ ## Close transport-layer connections from the clients that have not sent MQTT CONNECT message within this interval
+ idle_timeout = 7200s
+
+ ## The maximum length of a single MQTT packet
+ ## Type: infinity | Integer
+ max_frame_size = infinity
+
+ ## If true, the server will return an error when the client does not carry the Sec-WebSocket-Protocol field
+ fail_if_no_subprotocol = true
+
+ ## Comma-separated list of supported subprotocols
+ supported_subprotocols = "mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5"
+
+ ## If true, origin HTTP header will be validated against the list of allowed origins configured in check_origins parameter
+ check_origin_enable = false
+
+ ## If false and check_origin_enable is true, the server will reject requests that don't have origin HTTP header
+ allow_origin_absence = true
+
+ ## List of allowed origins
+ check_origins = "http://localhost:18083, http://127.0.0.1:18083"
+
+ ## HTTP header used to pass information about the client IP address
+ proxy_address_header = "x-forwarded-for"
+
+ ## The maximum length of a single MQTT packet
+ proxy_port_header = "x-forwarded-port"
+ }
+}
diff --git a/examples/listeners.wss.conf.example b/examples/listeners.wss.conf.example
new file mode 100644
index 000000000..799d082d7
--- /dev/null
+++ b/examples/listeners.wss.conf.example
@@ -0,0 +1,104 @@
+##--------------------------------------------------------------------
+## WSS Listener
+##
+## Add a WSS Listener
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## The WSS listener supports all the fields listed in listeners.ws.conf.example
+## only the WSS-specific fields are shown here
+
+## Note: Modifying the 'wssname' to what you need
+listeners.wss.wssname {
+ ## Port or Address to listen on, 0 means disable
+ bind = 8084 ## or with an IP, e.g. "127.0.0.1:8084"
+ enabled = true
+ enable_authn = true
+ max_connections = infinity
+ proxy_protocol = false
+ proxy_protocol_timeout = 3s
+ mountpoint = ""
+ tcp_options {
+ active_n = 100
+ backlog = 1024
+ buffer = 4KB
+ high_watermark = 1MB
+ keepalive = none
+ nodelay = true
+ reuseaddr = true
+ send_timeout = 15s
+ send_timeout_close = true
+ }
+ websocket {
+ allow_origin_absence = true
+ check_origin_enable = false
+ check_origins = "http://localhost:18083, http://127.0.0.1:18083"
+ compress = false
+ deflate_opts {
+ client_context_takeover = "takeover"
+ client_max_window_bits = 15
+ mem_level = 8
+ server_context_takeover = "takeover"
+ server_max_window_bits = 15
+ strategy = "default"
+ }
+ fail_if_no_subprotocol = true
+ idle_timeout = "7200s"
+ max_frame_size = "infinity"
+ mqtt_path = "/mqtt"
+ mqtt_piggyback = "multiple"
+ proxy_address_header = "x-forwarded-for"
+ proxy_port_header = "x-forwarded-port"
+ supported_subprotocols = "mqtt, mqtt-v3, mqtt-v3.1.1, mqtt-v5"
+ }
+
+ ssl_options {
+ ## Trusted PEM format CA certificates bundle file
+ cacertfile = "data/certs/cacert.pem"
+
+ ## PEM format certificates chain file
+ certfile = "data/certs/cert.pem"
+
+ ## PEM format private key file
+ keyfile = "data/certs/key.pem"
+
+ ## Enable or disable peer verification
+ verify = verify_none ## use verify_peer to enable
+
+ ## if `verify' is enabled, whit true, the connection fails if the client does not have a certificate to send
+ fail_if_no_peer_cert = false
+
+ ## Enable TLS session reuse
+ reuse_sessions = true
+
+ ## Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path
+ depth = 10
+
+ ## Which versions are to be supported
+ versions = [tlsv1.3, tlsv1.2]
+
+ ## TLS cipher suite names
+ ## Note: By default, all available suites are supported, you do not need to set this
+ ciphers = ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
+
+ ## Allows a client and a server to renegotiate the parameters of the SSL connection on the fly
+ secure_renegotiate = true
+
+ ## Log level for SSL communication
+ ## Type: emergency | alert | critical | error | warning | notice | info | debug | none | all
+ log_level = notice
+
+ ## Hibernate the SSL process after idling for amount of time reducing its memory footprint
+ hibernate_after = 5s
+
+ ## Forces the cipher to be set based on the server-specified order instead of the client-specified order
+ honor_cipher_order = true
+
+ ## Setting this to false to disable client-initiated renegotiation
+ client_renegotiation = true
+
+ ## Maximum time duration allowed for the handshake to complete
+ handshake_timeout = 15s
+ }
+}
diff --git a/examples/log.console.conf.example b/examples/log.console.conf.example
new file mode 100644
index 000000000..1dd30e120
--- /dev/null
+++ b/examples/log.console.conf.example
@@ -0,0 +1,27 @@
+##--------------------------------------------------------------------
+## Log
+##
+## Configure the log output location, log level, log file storage path, and parameters
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+log.console {
+ ## set true to enable this
+ enable = false
+
+ ## Log level
+ ## Type: debug | info | notice | warning | error | critical | alert | emergency
+ level = warning
+
+ ## Log formatter, text for free text, and json for structured logging
+ ## Type: text | json
+ formatter = text
+
+ ## Time offset for formatting the timestamp
+ ## Type:
+ ## - system :: local system time
+ ## - utc :: UTC time
+ ## - +-[hh]:[mm]: user specified time offset, such as "-02:00" or "+00:00" Defaults to: system
+ time_offset = system
+}
diff --git a/examples/log.file.conf.example b/examples/log.file.conf.example
new file mode 100644
index 000000000..deb9b16b9
--- /dev/null
+++ b/examples/log.file.conf.example
@@ -0,0 +1,38 @@
+##--------------------------------------------------------------------
+## Log
+##
+## Configure the log output location, log level, log file storage path, and parameters
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## The default-enabled log handler can use all the above fields listed fields
+log.file {
+ ## use false to disable this
+ enable = true
+
+ ## Log level
+ ## Type: debug | info | notice | warning | error | critical | alert | emergency
+ level = warning
+
+ ## Log formatter, text for free text, and json for structured logging
+ ## Type: text | json
+ formatter = text
+
+ ## Time offset for formatting the timestamp
+ ## Type:
+ ## - system :: local system time
+ ## - utc :: UTC time
+ ## - +-[hh]:[mm]: user specified time offset, such as "-02:00" or "+00:00" Defaults to: system
+ time_offset = system
+
+ ## Maximum number of log files
+ ## Type: Range from 1 to 128
+ rotation_count = 10
+
+ ## This parameter controls log file rotation
+ ## Type:
+ ## - infinity :: the log file will grow indefinitely
+ ## - ByteSize :: the log file will be rotated once it reaches this value in bytes
+ rotation_size = 50MB
+}
diff --git a/examples/mqtt.conf.example b/examples/mqtt.conf.example
new file mode 100644
index 000000000..c5f81f753
--- /dev/null
+++ b/examples/mqtt.conf.example
@@ -0,0 +1,124 @@
+##--------------------------------------------------------------------
+## MQTT
+##
+## MQTT configuration
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+mqtt {
+ ## After the TCP connection is established,
+ ## if the MQTT CONNECT packet from the client is not received within the time specified by idle_timeout, the connection will be disconnected
+ ## Type:
+ ## - infinity :: Never disconnect
+ ## - Time Duration :: The idle time
+ idle_timeout = 15s
+
+ ## Maximum MQTT packet size allowed
+ max_packet_size = 1MB
+
+ ## Maximum allowed length of MQTT Client ID
+ ## Type: Rnage from 23 to 65535
+ max_clientid_len = 65535
+
+ ## Maximum topic levels allowed
+ ## Type: Range from 1 to 65535
+ max_topic_levels = 128
+
+ ## Maximum QoS allowed
+ max_qos_allowed = 2
+
+ ## Maximum topic alias, 0 means no topic alias supported
+ ## Type: Range from 0 to 65535
+ max_topic_alias = 65535
+
+ ## Whether to enable support for MQTT retained message
+ retain_available = true
+
+ ## Whether to enable support for MQTT wildcard subscription
+ wildcard_subscription = true
+
+ ## Whether to enable support for MQTT shared subscription
+ shared_subscription = true
+
+ ## Whether to enable support for MQTT exclusive subscription
+ exclusive_subscription = false
+
+ ## Ignore loop delivery of messages for MQTT v3.1.1/v3.1.0, similar to No Local subscription option in MQTT 5.0
+ ignore_loop_deliver = false
+
+ ## Parse MQTT messages in strict mode.
+ ## When set to true, invalid utf8 strings in for example client ID, topic name, etc. will cause the client to be disconnected
+ strict_mode = false
+
+ ## Specify the response information returned to the client
+ response_information = ""
+
+ ## The keep alive that EMQX requires the client to use
+ ## Type:
+ ## - disabled :: the keep alive specified by the client will be used
+ ## - Integer :: Keepalive time, only applicable to clients using MQTT 5.0 protocol
+ server_keepalive = disabled
+
+ ## Keep-Alive Timeout = Keep-Alive interval × Keep-Alive Multiplier
+ keepalive_multiplier = 1.5
+
+ ## Maximum number of subscriptions allowed per client
+ ## Type: infinity | Integer
+ max_subscriptions = infinity
+
+ ## Force upgrade of QoS level according to subscription
+ upgrade_qos = false
+
+ ## Maximum number of QoS 1 and QoS 2 messages that are allowed to be delivered simultaneously before completing the acknowledgment
+ ## Type: Range from 1 to 65535
+ max_inflight = 32
+
+ ## Retry interval for QoS 1/2 message delivering
+ retry_interval = 30s
+
+ ## For each publisher session, the maximum number of outstanding QoS 2 messages pending on the client to send PUBREL
+ ## Type: infinity | Integer
+ max_awaiting_rel = 100
+
+ ## For client to broker QoS 2 message, the time limit for the broker to wait before the PUBREL message is received
+ await_rel_timeout = 300s
+
+ ## Specifies how long the session will expire after the connection is disconnected, only for non-MQTT 5.0 connections
+ session_expiry_interval = 2h
+
+ ## Maximum queue length. Enqueued messages when persistent client disconnected, or inflight window is full
+ ## Type: infinity | Integer
+ max_mqueue_len = 1000
+
+ ## Specifies whether to store QoS 0 messages in the message queue while the connection is down but the session remains
+ mqueue_store_qos0 = true
+
+ ## Whether to user Client ID as Username
+ use_username_as_clientid = false
+
+ ## Use the CN, DN field in the peer certificate or the entire certificate content as Username
+ ## Type:
+ ## - disabled
+ ## - cn :: CN field of the certificate
+ ## - dn :: DN field of the certificate
+ ## - crt :: the content of the DER or PEM certificate
+ ## - pem :: PEM format content converted from DER certificate content
+ ## - md5 :: the MD5 value of the content of the DER or PEM certificate
+ peer_cert_as_username = disabled
+
+ ## Use the CN, DN field in the peer certificate or the entire certificate content as Client ID
+ ## Type: See the above
+ peer_cert_as_clientid = disabled
+
+ ## Dispatch strategy for shared subscription
+ ## Type:
+ ## - random :: dispatch the message to a random selected subscriber
+ ## - round_robin :: select the subscribers in a round-robin manner
+ ## - round_robin_per_group :: select the subscribers in round-robin fashion within each shared subscriber group
+ ## - local :: select random local subscriber otherwise select random cluster-wide
+ ## - sticky :: always use the last selected subscriber to dispatch, until the subscriber disconnects.
+ ## - hash_clientid :: select the subscribers by hashing the `clientIds`
+ ## - hash_topic :: select the subscribers by hashing the source topic"""
+ shared_subscription_strategy = round_robin
+ }
diff --git a/examples/node.conf.example b/examples/node.conf.example
new file mode 100644
index 000000000..65c08b337
--- /dev/null
+++ b/examples/node.conf.example
@@ -0,0 +1,43 @@
+##--------------------------------------------------------------------
+## Node
+##
+## configuring for current EMQX node
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+## Note: all fields in this section are immutable after EMQX started, and most of the time you only need to modify the value for the name and cookie.
+node {
+ ## The actions triggered when the alarm is activated
+ ## Type: Formatted String
+ ## Format: any_name@any_domain or an_name@any_ip
+ ## Note: Make sure the IP resolve from the domain is deterministic and unique and never change
+ name = "emqx@127.0.0.1"
+
+ ## Secret cookie is a random string that should be the same on all nodes in the given EMQX cluster, but unique per EMQX cluster
+ cookie = "Yzc0NGExM2RjYzYxYzM0YzQ5MWQ0NmI1NWM0MWRhMzY4NzgxYmFkMmI2MWJjZWQ5NTQzYTMxNjE1ODVmYmJmMyAgLQo="
+
+ ## Select a node role
+ ## Type:
+ ## - core :: nodes provide durability of the data, and take care of writes
+ ## - replicant :: nodes are ephemeral worker nodes
+ role = core
+
+ ## Maximum number of simultaneously existing processes for this Erlang system
+ ## Type: Range from 1024 to 134217727
+ process_limit = 2097152
+
+ ## Maximum number of simultaneously existing ports for this Erlang system
+ ## Type: Range from 1024 to 134217727
+ max_ports = 1048576
+
+ ## Erlang's distribution buffer busy limit in kilobytes
+ ## Type: Range from 1 to 2097152
+ dist_buffer_size = 8192
+
+ ## Path to the persistent data directory
+ data_dir = "var/emqx/data"
+
+ ## Type: Periodic garbage collection interval
+ global_gc_interval = 15m
+}
diff --git a/examples/plugin.conf.example b/examples/plugin.conf.example
new file mode 100644
index 000000000..d704f9981
--- /dev/null
+++ b/examples/plugin.conf.example
@@ -0,0 +1,27 @@
+##--------------------------------------------------------------------
+## Plugin
+##
+## Manage EMQX plugins
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+plugin {
+ ## Plugins declaration
+ ## Note: The plugins are started in the defined order
+ states = [
+ {
+ ## Name and version of this plugin
+ ## Type: Formatted String
+ ## Format: {name}-{version}
+ ## Note: name and version should be what it is in the plugin application
+ name_vsn = "my_acl-0.1.0",
+
+ enable = true ## enable this plugin
+ },
+ {name_vsn = "my_rule-0.1.1", enable = false}
+ ]
+
+ ## The installation directory for the external plugins
+ install_dir = "plugins"
+}
diff --git a/examples/prometheus.conf.example b/examples/prometheus.conf.example
new file mode 100644
index 000000000..645e10364
--- /dev/null
+++ b/examples/prometheus.conf.example
@@ -0,0 +1,28 @@
+##--------------------------------------------------------------------
+## Prometheus
+##
+## Settings for reporting metrics to Prometheus
+##--------------------------------------------------------------------
+
+prometheus {
+ ## URL of Prometheus server
+ push_gateway_server = "http://127.0.0.1:9091"
+
+ ## Data reporting interval
+ interval = 15s
+
+ ## A HTTP Headers when pushing to Push Gateway.
+ headers = {
+ Authorization = "some-authz-tokens",
+ Connection = "keep-alive"
+ }
+
+ ## Job Name that is pushed to the Push Gateway.
+ ## Available variable:
+ ## - ${name}: Name of EMQX node
+ ## - ${host}: Host name of EMQX node
+ job_name = "${name}/instance/${name}~${host}"
+
+ ## set to false to enable this
+ enable = true
+}
diff --git a/examples/psk_authentication.conf.example b/examples/psk_authentication.conf.example
new file mode 100644
index 000000000..272eb41b5
--- /dev/null
+++ b/examples/psk_authentication.conf.example
@@ -0,0 +1,21 @@
+##--------------------------------------------------------------------
+## Pre-Shared Keys authentication
+##
+## Config to enable TLS-PSK authentication
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+psk_authentication {
+ ## set to false to disable
+ enable = true
+
+ ## If init_file is specified, EMQX will import PSKs from the file into the built-in database at startup for use by the runtime
+ init_file = "psk"
+
+ ## The separator between PSKIdentity and SharedSecret in the PSK file
+ separator = ":"
+
+ ## The size of each chunk used to import to the built-in database from PSK file
+ chunk_size = 50
+ }
diff --git a/examples/retainer.conf.example b/examples/retainer.conf.example
new file mode 100644
index 000000000..1cef31c30
--- /dev/null
+++ b/examples/retainer.conf.example
@@ -0,0 +1,40 @@
+##--------------------------------------------------------------------
+## Retainer
+##
+## Configuration related to handling PUBLISH packets with a retain flag set to 1
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+retainer {
+ ## set to false to disable this
+ enable = true
+
+ ## Message retention time. 0 means message will never be expired
+ msg_expiry_interval = 0s
+
+ ## Periodic interval for cleaning up expired messages. Never clear if the value is 0
+ msg_clear_interval = 0s
+
+ ## Maximum retained message size
+ max_payload_size = 1MB
+
+ ## When the retained flag of the PUBLISH message is set and Payload is empty, whether to continue to publish the message
+ stop_publish_clear_msg = false
+
+ ## Maximum retained messages delivery rate per session
+ deliver_rate = "1000/s"
+
+ ## Retained messages store backend
+ backend {
+ ## Backend type
+ type = built_in_database
+
+ ## Specifies whether the messages are stored in RAM or persisted on disc
+ ## Type: enum: ram | disc
+ storage_type = ram
+
+ ## Maximum number of retained messages. 0 means no limit
+ max_retained_messages = 0
+ }
+ }
diff --git a/examples/sys_topics.conf.example b/examples/sys_topics.conf.example
new file mode 100644
index 000000000..b249efd35
--- /dev/null
+++ b/examples/sys_topics.conf.example
@@ -0,0 +1,25 @@
+##--------------------------------------------------------------------
+## System Topic
+##
+## Publishing client lifecycle events to "$SYS" topics
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+sys_topics {
+ ## Time interval of publishing `$SYS` messages
+ sys_msg_interval = 1m
+
+ ## Time interval for publishing following heartbeat messages:
+ ## - `$SYS/brokers//uptime`
+ ## - `$SYS/brokers//datetime`
+ sys_heartbeat_interval = 30s
+
+ ## Client events messages toggle
+ sys_event_messages = {
+ client_connected = true
+ client_disconnected = true
+ client_subscribed = false
+ client_unsubscribed = false
+ }
+}
diff --git a/examples/sysmon.os.conf.example b/examples/sysmon.os.conf.example
new file mode 100644
index 000000000..95e7aa1ec
--- /dev/null
+++ b/examples/sysmon.os.conf.example
@@ -0,0 +1,30 @@
+##--------------------------------------------------------------------
+## System Monitoring For System
+##
+## System monitoring and introspection
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+sysmon.os {
+ ## Time interval for the periodic CPU check
+ cpu_check_interval = 60s
+
+ ## For how much system cpu can be used before the corresponding alarm is raised
+ cpu_high_watermark = 80%
+
+ ## For how much system cpu can be used before the corresponding alarm is cleared
+ cpu_low_watermark = 60%
+
+ ## Time interval for the periodic memory check
+ ## Type:
+ ## - disabled :: Never check
+ ## - Time Duration :: The time period
+ mem_check_interval = 60s
+
+ ## For how much system memory can be allocated before the corresponding alarm is raised
+ sysmem_high_watermark = 70%
+
+ ## For how much system memory can be allocated by one Erlang process before the corresponding alarm is raised
+ procmem_high_watermark = 5%
+}
diff --git a/examples/sysmon.vm.conf.example b/examples/sysmon.vm.conf.example
new file mode 100644
index 000000000..d68141cea
--- /dev/null
+++ b/examples/sysmon.vm.conf.example
@@ -0,0 +1,42 @@
+##--------------------------------------------------------------------
+## System Monitoring For Erlang VM
+##
+## System monitoring and introspection
+##--------------------------------------------------------------------
+## Note: This is an example of how to configure this feature
+## you should copy and paste the below data into the emqx.conf for working
+
+sysmon.vm {
+ ## Time interval for the periodic process limit check
+ process_check_interval = 30s
+
+ ## For how many processes can simultaneously exist at the local node before the corresponding alarm is raised
+ process_high_watermark = 80%
+
+ ## For how many processes can simultaneously exist at the local node before the corresponding alarm is cleared
+ process_low_watermark = 60%
+
+ ## Generated an alarm when an Erlang process spends a long time to perform garbage collection
+ ## Type:
+ ## - disabled :: Never alarm
+ ## - Time During :: The maximum GC time for generating an alarm
+ long_gc = 100ms
+
+ ## Generating an alarm is generated when the Erlang VM detect a task scheduled for too long
+ ## Type:
+ ## - disabled :: Never alarm
+ ## - Time During :: The maximum schedule time for generating an alarm
+ long_schedule = 240ms
+
+ ## Generating an alarm when an Erlang process consumed a large amount of memory for its heap space
+ ## Type:
+ ## - disabled :: Never alarm
+ ## - ByteSize :: The maximum heap size for generating an alarm
+ large_heap = 32MB
+
+ ## Generating an alarm when the RPC connection is overloaded
+ busy_dist_port = true
+
+ ## Generating an alarm when a port (e.g. TCP socket) is overloaded
+ busy_port = true
+}
diff --git a/mix.exs b/mix.exs
index 1274991ff..5f60a2e34 100644
--- a/mix.exs
+++ b/mix.exs
@@ -541,9 +541,9 @@ defmodule EMQXUmbrella.MixProject do
profile = System.get_env("MIX_ENV")
- Mix.Generator.copy_file(
- "_build/docgen/#{profile}/emqx.conf.example",
- Path.join(etc, "emqx.conf.example"),
+ File.cp_r!(
+ "examples",
+ Path.join(etc, "examples"),
force: overwrite?
)
diff --git a/rebar.config.erl b/rebar.config.erl
index a0bfa8744..fc91878d9 100644
--- a/rebar.config.erl
+++ b/rebar.config.erl
@@ -524,7 +524,7 @@ etc_overlay(ReleaseType, _Edition) ->
[
{mkdir, "etc/"},
{copy, "{{base_dir}}/lib/emqx/etc/certs", "etc/"},
- {copy, "_build/docgen/" ++ profile() ++ "/emqx.conf.example", "etc/emqx.conf.example"}
+ {copy, "examples", "etc/"}
] ++
lists:map(
fun
diff --git a/rel/i18n/emqx_prometheus_schema.hocon b/rel/i18n/emqx_prometheus_schema.hocon
index d79685a4d..d68e1d418 100644
--- a/rel/i18n/emqx_prometheus_schema.hocon
+++ b/rel/i18n/emqx_prometheus_schema.hocon
@@ -4,7 +4,7 @@ enable.desc:
"""Turn Prometheus data pushing on or off"""
headers.desc:
-"""A list of HTTP Headers when pushing to Push Gateway.
+"""An HTTP Headers when pushing to Push Gateway.
For example, { Authorization = "some-authz-tokens"}
"""
interval.desc: