From 2e0bbef62fa46178e51e3a8b5ebcf7b046838030 Mon Sep 17 00:00:00 2001 From: Ivan Dyachkov Date: Wed, 18 Jan 2023 17:27:25 +0100 Subject: [PATCH] update emqx docs --- emqx/content.md | 135 ++++-------------------------------------------- 1 file changed, 11 insertions(+), 124 deletions(-) diff --git a/emqx/content.md b/emqx/content.md index 5c1f4b0a9..97327c0cf 100644 --- a/emqx/content.md +++ b/emqx/content.md @@ -30,7 +30,7 @@ The EMQX broker runs as Linux user `emqx` in the docker container. ### Configuration -Use the environment variable to configure the EMQX docker container. +All EMQX Configuration in [`etc/emqx.conf`](https://github.com/emqx/emqx/blob/master/apps/emqx/etc/emqx.conf) can be configured via environment variables. By default, the environment variables with `EMQX_` prefix are mapped to key-value pairs in configuration files. @@ -52,142 +52,27 @@ If `HOCON_ENV_OVERRIDE_PREFIX=DEV_` is set: ```bash DEV_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors DEV_MQTT__MAX_PACKET_SIZE <--> mqtt.max_packet_size +DEV_LISTENERS__TCP__DEFAULT__BIND <--> listeners.tcp.default.bind ``` -Non mapped environment variables: +For example, set MQTT TCP port to 1883 -```bash -EMQX_NAME -EMQX_HOST +```console +$ docker run -d --name emqx -e DEV_LISTENERS__TCP__DEFAULT__BIND=1883 -p 18083:18083 -p 1883:1883 %%IMAGE%%:latest ``` -These environment variables will ignore for configuration file. +Please read more about EMQX configuration in the [official documentation](https://www.emqx.io/docs/en/v5.0/admin/cfg.html). -#### EMQX Configuration - -> NOTE: All EMQX Configuration in [`etc/emqx.conf`](https://github.com/emqx/emqx/blob/master/apps/emqx/etc/emqx.conf) can be configured via environment variables. The following list is just an example, not a complete configuration. +#### EMQX node name configuration | Options | Default | Mapped | Description | |-------------|----------------|--------|----------------------------| | `EMQX_NAME` | container name | none | EMQX node short name | | `EMQX_HOST` | container IP | none | EMQX node host, IP or FQDN | -The list is incomplete and may be changed with [`etc/emqx.conf`](https://github.com/emqx/emqx/blob/master/apps/emqx/etc/emqx.conf) and plugin configuration files. But the mapping rule is similar. +These environment variables are used during container startup phase only in [docker-entrypoint.sh](./docker-entrypoint.sh). -If set `EMQX_NAME` and `EMQX_HOST`, and unset `EMQX_NODE_NAME`, `EMQX_NODE_NAME=$EMQX_NAME@$EMQX_HOST`. - -For example, set MQTT TCP port to 1883 - -```console -$ docker run -d --name emqx -e EMQX__LISTENERS__TCP__DEFAULT__BIND=1883 -p 18083:18083 -p 1883:1883 %%IMAGE%%:latest -``` - -#### EMQX Loaded Modules Configuration - -| Options | Default | Description | -|-----------------------|-------------------|-----------------------------| -| `EMQX_LOADED_MODULES` | see content below | default EMQX loaded modules | - -Default environment variable `EMQX_LOADED_MODULES`, including - -- `emqx_mod_presence` - -```bash -# The default EMQX_LOADED_MODULES env -EMQX_LOADED_MODULES="emqx_mod_presence" -``` - -For example, set `EMQX_LOADED_MODULES=emqx_mod_delayed,emqx_mod_rewrite` to load these two modules. - -You can use comma, space or other separator that you want. - -All the modules defined in env `EMQX_LOADED_MODULES` will be loaded. - -```bash -EMQX_LOADED_MODULES="emqx_mod_delayed,emqx_mod_rewrite" -EMQX_LOADED_MODULES="emqx_mod_delayed emqx_mod_rewrite" -EMQX_LOADED_MODULES="emqx_mod_delayed | emqx_mod_rewrite" -``` - -#### EMQX Loaded Plugins Configuration - -| Options | Default | Description | -|-----------------------|-------------------|-----------------------------| -| `EMQX_LOADED_PLUGINS` | see content below | default EMQX loaded plugins | - -Default environment variable `EMQX_LOADED_PLUGINS`, including - -- `emqx_recon` -- `emqx_retainer` -- `emqx_rule_engine` -- `emqx_management` -- `emqx_dashboard` - -```bash -# The default EMQX_LOADED_PLUGINS env -EMQX_LOADED_PLUGINS="emqx_recon,emqx_retainer,emqx_management,emqx_dashboard" -``` - -For example, set `EMQX_LOADED_PLUGINS= emqx_retainer,emqx_rule_engine` to load these two plugins. - -You can use comma, space or other separator that you want. - -All the plugins defined in `EMQX_LOADED_PLUGINS` will be loaded. - -```bash -EMQX_LOADED_PLUGINS="emqx_retainer,emqx_rule_engine" -EMQX_LOADED_PLUGINS="emqx_retainer emqx_rule_engine" -EMQX_LOADED_PLUGINS="emqx_retainer | emqx_rule_engine" -``` - -#### EMQX Plugins Configuration - -The environment variables which with `EMQX_` prefix are mapped to all EMQX plugins' configuration file, `.` get replaced by `__`. - -Example: - -```bash -EMQX_RETAINER__STORAGE_TYPE <--> retainer.storage_type -EMQX_RETAINER__MAX_PAYLOAD_SIZE <--> retainer.max_payload_size -``` - -Don't worry about where to find the configuration file of EMQX plugins, this docker image will find and configure them automatically using some magic. - -All EMQX plugins can be configured this way, following the environment variables mapping rule above. - -Assume you are using Redis auth plugin, for example: - -```bash -#EMQX_RETAINER__STORAGE_TYPE = "ram" -#EMQX_RETAINER.MAX_PAYLOAD_SIZE = 1MB - -docker run -d --name emqx -p 18083:18083 -p 1883:1883 \ - -e EMQX_LISTENERS__TCP__DEFAULT=1883 \ - -e EMQX_LOADED_PLUGINS="emqx_retainer" \ - -e EMQX_RETAINER__STORAGE_TYPE = "ram" \ - -e EMQX_RETAINER__MAX_PAYLOAD_SIZE = 1MB \ - %%IMAGE%%:latest -``` - -For numbered configuration options where the number is next to a `.` such as: - -- backend.redis.pool1.server -- backend.redis.hook.message.publish.1 - -You can configure an arbitrary number of them as long as each has a unique number for its own configuration option: - -```bash -docker run -d --name emqx -p 18083:18083 -p 1883:1883 -p 4369:4369 \ - -e EMQX_BACKEND_REDIS_POOL1__SERVER=127.0.0.1:6379 \ - [...] - -e EMQX_BACKEND__REDIS__POOL5__SERVER=127.0.0.5:6379 \ - -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__1='{"topic": "persistent/topic1", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \ - -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__2='{"topic": "persistent/topic2", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \ - -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__3='{"topic": "persistent/topic3", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \ - [...] - -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__13='{"topic": "persistent/topic13", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \ - %%IMAGE%%:latest -``` +If `EMQX_NAME` and `EMQX_HOST` are set, and `EMQX_NODE_NAME` is not set, `EMQX_NODE_NAME=$EMQX_NAME@$EMQX_HOST`. Otherwise `EMQX_NODE_NAME` is taken verbatim. ### Cluster @@ -278,6 +163,8 @@ services: - vol-emqx-log:/opt/emqx/log ``` +Note that `/opt/emqx/etc` contains some essential configuration files. If you want to mount a host directory in the container to persist configuration overrides, you will need to bootstrap it with [default configuration files](https://github.com/emqx/emqx/tree/master/apps/emqx/etc). + ### Kernel Tuning Under Linux host machine, the easiest way is [Tuning guide](https://www.emqx.io/docs/en/latest/deploy/tune.html).