Merge pull request #2819 from emqx/250212-add-base-hocon-config

docs: promote base.hocon for mutable configs

Author: zmstone

en_US/access-control/authn/authn.md

@@ -220,7 +220,7 @@ You can also configure EMQX authenticators with our configuration file.
 For example, as shown in the `authentication` field below, we have created an authentication chain with multiple authenticators, these authenticators will run in the order as they are in the configuration file. 
 
 ```
-# emqx.conf
+# base.hocon
 
 # Specific global authentication chain for all MQTT listeners
 authentication = [

en_US/access-control/authn/x509.md

@@ -57,8 +57,8 @@ You can use fields from the peer certificate like CN, DN, or the entire certific
 
 ### Configure via Configuration File
 
-1. Open the configuration file `emqx.conf`, which may be located in `./etc` or `/etc/emqx/etc` directory, depending on your installation.
-2. By default, MQTT configuration is not in `emqx.conf`. Add the following configuration to override the default values:
+1. Open the configuration file which may be located in `./etc` or `/etc/emqx/etc` directory, depending on your installation.
+2. MQTT configuration is not explicitly defined in any configuration file. Add the following to override the default values:
 
 ```bash
 mqtt {

en_US/access-control/authz/authz.md

@@ -205,7 +205,7 @@ EMQX Dashboard is an intuitive way to configure EMQX authorizer, where you can c
 
 ### Configure with Configuration File
 
-You can also configure authorization in the `authorization` fields in the configuration file `emqx.conf`. The general config structure is the following:
+You can also configure authorization in the `authorization` fields in the configuration file. The general config structure is the following:
 
 ```bash
 authorization {

en_US/access-control/flapping-detect.md

@@ -26,7 +26,7 @@ Click **Save Changes** to finish the setting.
 
 ## Enable Flapping Detect in Configuration File
 
-You can also enable the flapping detect feature by adding the following configuration to the `emqx.conf` file:
+You can also enable the flapping detect feature by adding the following configuration:
 
 ```bash
 flapping_detect {

en_US/admin/api.md

@@ -48,7 +48,7 @@ For security reasons, starting from EMQX 5.0.0, you cannot use Dashboard user cr
 
 You can manually create API keys for authentication on the Dashboard by navigating to **System** -> **API Key**. For instructions, see [System - API Keys](../dashboard/system.md#api-keys).
 
-You can also create API keys using the bootstrap file method. Add the following configuration to the `emqx.conf` file to specify the file location:
+You can also create API keys using the bootstrap file method. Add the following configuration file to specify the file location:
 
 ```bash
 api_key = {

en_US/changes/gateway-4.4-to-5.1-incompatibility.md

@@ -78,7 +78,7 @@ lwm2m.bind.dtls.1 = 0.0.0.0:5684
 In EMQX 5.x, all protocol gateways have the same format for the listener configuration. Take the Exproto gateway as an example:
 
 ```
-## etc/emqx.conf
+## etc/emqx.conf or base.hocon (since EMQX 5.9)
 gateway.exproto {
     listeners.tcp.default {
         bind = "0.0.0.0:7993"
@@ -200,4 +200,4 @@ gateway.lwm2m {
     update {qos = 0, topic = "up/update"}
   }
 }
-```
+```

en_US/configuration/configuration.md

@@ -290,7 +290,7 @@ The following configuration items can be overridden at the zone level:
 
 In EMQX version 5, the default configuration file does not include any zones, which differs from version 4, where there are two default zones: `internal` and `external`.
 
-To create a zone, you need to define it in `emqx.conf`, for example:
+To create a zone, you need to define it in the config file, for example:
 
 ```bash
 zones {

en_US/configuration/flapping.md

@@ -21,12 +21,12 @@ Where, <!--did not add the dashboard UI as it seems that most configurations lis
 
 ::: tip
 
-You can also customize the settings via the Dashboard by clicking **Access Control** -> **Flapping Detect** on the left navigation menu. Once you have configured these items with Dashboard, your settings will override the same configuration items in `emqx.conf`.
+You can also customize the settings via the Dashboard by clicking **Access Control** -> **Flapping Detect** on the left navigation menu. Once you have configured these items with Dashboard, your settings will override the same configuration items in the config file.
 
 :::
 
 ::: tip
 
 EMQX offers more configuration items to better serve customized needs. For details, see the [EMQX Open Source Configuration Manual](https://docs.emqx.com/en/emqx/v@CE_VERSION@/hocon/) and [EMQX Enterprise Configuration Manual for Enterprise](https://docs.emqx.com/en/enterprise/v@EE_VERSION@/hocon/).
 
-:::
+:::

en_US/configuration/license.md

@@ -26,7 +26,7 @@ Where,
 
 If the license is configured via `'file://<license_file_path>'` notation, EMQX will be automatically reloading it every 2 minutes.
 
-Additionally, you can configure the settings for the license connection quota usage in the configuration file `emqx.conf`.
+Additionally, you can configure the settings for the license connection quota usage in the configuration file as follows:
 
 ```bash
 license {
@@ -46,7 +46,7 @@ After execution, you can run `emqx ctl license info` to confirm that the new lic
 
 ::: tip
 
-You can also configure the license file through the EMQX Dashboard. For how to configure the license via Dashboard, see [Work with License](../deploy/license.md). Once you have configured these items with the Dashboard, your settings will override the same configuration items in `emqx.conf`.
+You can also configure the license file through the EMQX Dashboard. For how to configure the license via Dashboard, see [Work with License](../deploy/license.md). Once you have configured these items with the Dashboard, your settings will override the same configuration items in the config file.
 
 :::
 

en_US/configuration/listener.md

@@ -10,7 +10,8 @@ In EMQX, listener is configured to receive requests from MQTT clients. EMQX supp
 ::: tip
 
 You can also configure listeners via Dashboard by clicking **Management** -> **Listeners** on the left navigation menu of the Dashboard.
-However if the listeners are configured from `emqx.conf`, the changes made from the Dashboard will only take effect temporarily until EMQX restarts.
+If you want to configure listeners from config files, it is recommended to use `base.hocon` instead of `emqx.conf`.
+This is because if the configuration is set in emqx.conf, any changes made through the Dashboard will only be temporary and will be lost upon EMQX restart.
 
 :::
 
@@ -24,7 +25,7 @@ EMQX offers more configuration items to better serve customized needs. For detai
 
 TCP listener is a network service that listens for incoming TCP connections on a specific network port. It plays an essential role in establishing and managing connections between clients and EMQX over TCP/IP networks. 
 
-To configure the TCP listener in EMQX, you can add the `listeners.tcp` configuration items in the `emqx.conf` file within the `etc` folder of the EMQX installation directory.
+To configure the TCP listener in EMQX, you can add the `listeners.tcp` configuration items in the `base.hocon` file within the `etc` folder of the EMQX installation directory.
 
 For example, to enable the TCP listener on port `1883`, with a maximum 1,024,000 of concurrent connections allowed by the listener, you can work the code below:
 
@@ -46,7 +47,7 @@ where,
 
 SSL listener is a network service that listens for incoming SSL (Secure Sockets Layer) connections. In EMQX, it is used to secure network traffic between a client and EMQX by encrypting the data that is transmitted between them.
 
-To configure the SSL listener in EMQX, you can add the `listeners.ssl` configuration items in the `emqx.conf` file within the `etc` folder of the EMQX installation directory.
+To configure the SSL listener in EMQX, you can add the `listeners.ssl` configuration items in the `base.hocon` file within the `etc` folder of the EMQX installation directory.
 
 For example, to enable the SSL listener on port `8883`, with a maximum 1,024,000 of concurrent connections allowed by the listener:
 
@@ -81,7 +82,7 @@ where:
 
 WebSocket listener is a network service that receives and processes messages over WebSocket. WebSocket support in EMQX allows clients to use the WebSocket protocol to connect to EMQX and exchange data in real-time.
 
-To configure the WebSocket listener in EMQX, you can add the `listeners.ws` configuration items in the `emqx.conf` file within the `etc` folder of the EMQX installation directory.
+To configure the WebSocket listener in EMQX, you can add the `listeners.ws` configuration items in the `base.hocon` file within the `etc` folder of the EMQX installation directory.
 
 For example, to enable the WebSocket listener on port `8083`, with a maximum 1,024,000 of concurrent connections allowed by the listener:
 
@@ -105,7 +106,7 @@ where:
 
 A secure WebSocket listener is a WebSocket listener that uses the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocol to encrypt the data exchanged between a WebSocket client and the broker. In EMQX, the secure WebSocket listener is an important security measure to protect sensitive data exchanged between WebSocket clients and EMQX> 
 
-To configure the secure WebSocket listener in EMQX, you can add the `listeners.wss` configuration items in the `emqx.conf` file within the `etc` folder of the EMQX installation directory.
+To configure the secure WebSocket listener in EMQX, you can add the `listeners.wss` configuration items in the `base.hocon` file within the `etc` folder of the EMQX installation directory.
 
 For example, to enable the Secure WebSocket listener on port `8084`, with a maximum 1,024,000 of concurrent connections allowed by the listener: