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: