Merge pull request #2868 from emqx/20250318-sync-release-5.8

sync release-5.8

Author: Meggielqk

current-version.env

@@ -1,4 +1,4 @@
-EE_VERSION=5.8.4
-CE_VERSION=5.8.4
+EE_VERSION=5.8.5
+CE_VERSION=5.8.5
 EE_MINOR_VERSION=5.8
 CE_MINOR_VERSION=5.8

dir.yaml

@@ -190,15 +190,15 @@
         - title_en: EMQX 企业版 API 文档
           title_cn: EMQX 企业版 API 文档
           lang: cn
-          path: https://docs.emqx.com/zh/enterprise/v${EE_MINOR_VERSION}/admin/api-docs.html
+          path: https://docs.emqx.com/en/enterprise/v${EE_MINOR_VERSION}/admin/api-docs.html
         - title_en: EMQX Open Source API Docs
           title_cn: EMQX Open Source API Docs
           lang: en
           path: https://docs.emqx.com/en/emqx/v${CE_MINOR_VERSION}/admin/api-docs.html
         - title_en: EMQX 开源版 API 文档
           title_cn: EMQX 开源版 API 文档
           lang: cn
-          path: https://docs.emqx.com/zh/emqx/v${CE_MINOR_VERSION}/admin/api-docs.html
+          path: https://docs.emqx.com/en/emqx/v${CE_MINOR_VERSION}/admin/api-docs.html
 
 - title_en: EMQX Clustering
   title_cn: 构建集群
@@ -223,7 +223,6 @@
       children:
         - performance/tune
         - performance/benchmark-emqtt-bench
-        - performance/benchmark-xmeter
         - performance/performance-reference
 
 - title_en: Security Guide
@@ -561,21 +560,21 @@
         - observability/datadog
         - title_en: Integrate with OpenTelemetry
           title_cn: 集成 OpenTelemetry
-          path: observability/open-telemetry/open-telemetry
+          path: observability/opentelemetry/opentelemetry
           collapsed: true
           children:
             - title_en: Metrics
               title_cn: 指标
-              path: observability/open-telemetry/metrics
+              path: observability/opentelemetry/metrics
             - title_en: Logs
               title_cn: 日志
-              path: observability/open-telemetry/logs
+              path: observability/opentelemetry/logs
             - title_en: Traces
               title_cn: 追踪
-              path: observability/open-telemetry/traces
+              path: observability/opentelemetry/traces
             - title_en: End-to-end Traces
               title_cn: 端到端追踪
-              path: observability/open-telemetry/e2e-traces
+              path: observability/opentelemetry/e2e-traces
     - title_en: Backup and Restore
       title_cn: 备份与恢复
       path: operations/backup-restore

en_US/access-control/authn/acl.md

@@ -1,8 +1,8 @@
 # Access Control List
 
-EMQX allows presetting client permissions during the authentication phase to control the publish-subscribe permission checks after the client logs in. Currently, both JWT authentication and HTTP authentication support permission presets, using Access Control Lists (ACL) as an optional extension of the authentication result. For example, this can be a private claim `acl` defined in JWT, or an `acl` JSON property returned as part of the HTTP authentication response. After a client connects, its publish and subscribe actions are restricted by these ACL rules.
+This page introduces Access Control Lists (ACL) rules embedded in JWT and HTTP authentication responses. Currently, JWT authentication and HTTP authentication support permission presets, using ACL as an optional extension of the authentication result. For example, this can be a private claim `acl` defined in JWT, or an `acl` JSON property returned as part of the HTTP authentication response. After a client connects, its publish and subscribe actions are restricted by these ACL rules.
 
-This page introduces the ACL rules for presetting client permissions. Authorizing a client using the ACL rules included in the authentication response is concise, efficient, and generally sufficient for most use cases. For more comprehensive but generic authorization methods, refer to [Authorization](../authz/authz.md).
+General ACL rules are stored in `acl.conf`. For details, see [acl.conf](../authz/file.md). For more comprehensive authorization methods, refer to [Authorization](../authz/authz.md).
 
 ::: tip
 

en_US/access-control/authn/assets/authn-MongoDB_ee.png

@@ -67,9 +67,7 @@ On [EMQX Dashboard](http://127.0.0.1:18083/#/authentication), click **Access Con
 
 <img src="./assets/authn-http.png" alt="HTTP" style="zoom:67%;" />
 
-
-
-**HTTP**:
+Follow the instructions below on how to configure the authentication:
 
 - **Method**: Select HTTP request method, optional values: `get`, `post`
 
@@ -79,20 +77,20 @@ On [EMQX Dashboard](http://127.0.0.1:18083/#/authentication), click **Access Con
    :::
 
 - **URL**: Enter the URL address of the HTTP service.
-- **Headers** (optional): HTTP request header. You can add several headers.
+- **Headers** (optional): HTTP request header. You can add several headers. Keys and values support using [placeholders](./authn.md#authentication-placeholders).
+- **Enable TLS**: Turn on the toggle switch if you want to enable TLS. For more information on enabling TLS, see [Network and TLS](../../network/overview.md).
+
+- **Body**: Request template; for `POST` requests, it is sent as a JSON in the request body; for `GET` requests, it is encoded as a Query String in the URL. Mapping keys and values support using [placeholders](./authn.md#authentication-placeholders).
 
-**Connection Configuration**:
+- **Advanced Settings**:
 
-- **Pool size** (optional): Input an integer value to define the number of concurrent connections from an EMQX node to an HTTP server. Default: **8**. <!--有范围吗？-->
-- **Connect Timeout** (optional): Specify the waiting period before EMQX assumes the connection is timed out. Units supported include milliseconds, second, minute, and hour.
-- **HTTP Pipelining** (optional): Input a positive integer to specify the maximum number of HTTP requests that can be sent without waiting for a response; default value: **100**.
-- **Request Timeout** (optional): Specify the waiting period before EMQX assumes the request is timed out. Units supported include milliseconds, second, minute, and hour.
+  - **Pool size** (optional): Input an integer value to define the number of concurrent connections from an EMQX node to an HTTP server. Default: `8`. 
 
-**TLS Configuration**: Turn on the toggle switch if you want to enable TLS. For more information on enabling TLS, see [Network and TLS](../../network/overview.md).
+  - **Connect Timeout** (optional): Specify the waiting period before EMQX assumes the connection is timed out. Units supported include milliseconds, second, minute, and hour.
 
-**Authentication configuration**:
+  - **HTTP Pipelining** (optional): Input a positive integer to specify the maximum number of HTTP requests that can be sent without waiting for a response; default value: `100`.
 
-- **Body**: Request template; for `POST` requests, it is sent as a JSON in the request body; for `GET` requests, it is encoded as a Query String in the URL. Mapping keys and values support using [placeholder](./authn.md#authentication-placeholders).
+  - **Request Timeout** (optional): Specify the waiting period before EMQX assumes the request is timed out. Units supported include milliseconds, second, minute, and hour.
 
 After you finish the settings, click **Create**.
 

en_US/access-control/authn/assets/authn-http.png

@@ -20,16 +20,20 @@ In the EMQX Dashboard, click **Access Control** -> **Authentication** from the l
 
 **UserID Type**: Specify the fields for client ID authentication; Options:  `username`, `clientid`（corresponding to the `Username` or `Client Identifier` fields in the `CONNECT` message sent by the MQTT client).
 
-**Password Hash**: Select the hashing function to store passwords in the database. Available options are `plain`, `md5`, `sha`, `bcrypt`, and `pbkdf2`. Additional configuration depends on your selected function:
+**Password Hash**: Select the password hashing algorithm applied to plain-text passwords before results are stored in the database. Available options are `plain`, `md5`, `sha`, `sha256`, `sha512`, `bcrypt`, and `pbkdf2`. Additional configurations depend on the selected algorithm:
 
-- For `plain`, `md5`, `sha`, `sha256` or `sha512`:
-   - **Salt Position**: Determines how salt (random data) is added to the password. Options are `suffix`, `prefix`, or `disable`.  You can keep the default value unless you migrate user credentials from external storage into the EMQX built-in database. Note: Set **Salt Position** to `disable` if `plain` is selected.
+- For `md5`, `sha`, `sha256` or `sha512`:
+   - **Salt Position**: Determines how salt (random data) is mixed with the password. Options are `suffix`, `prefix`, or `disable`.  You can keep the default value unless you migrate user credentials from external storage into the EMQX built-in database.
+   - Resulting hash is represented as a string of hexadecimal characters, and compared case-insensitively with the stored credential.
+- For `plain`:
+   - **Salt Position**: should be `disable`.
 - For `bcrypt`:
-   - **Salt Rounds**: Defines the number of times the hash function is applied, expressed as 2^Salt Rounds, also known as the "cost factor". The default value is `10`, with a permissible range of `5` to `10`. A higher value is recommended for enhanced security. Note: Increasing the cost factor by 1 doubles the necessary time for authentication.
-- For `pbkdf2`: 
+   - **Salt Rounds**: Defines the number of times the hash function is applied, expressed as _2<sup>Salt Rounds</sup>_, also known as the "cost factor". The default value is `10`, with a permissible range of `5` to `10`. A higher value is recommended for enhanced security. Note: Increasing the cost factor by 1 doubles the necessary time for authentication.
+- For `pbkdf2`:
    - **Pseudorandom Function**: Selects the hash function that generates the key, such as `sha256`.
    - **Iteration Count**: Sets the number of times the hash function is executed. The default is `4096`.
-   - **Derived Key Length** (optional): Specifies the length of the generated key. If left blank, the length will default to that determined by the selected pseudorandom function.
+   - **Derived Key Length** (optional): Specifies the length in bytes of the generated key. If left blank, the length will default to that determined by the selected pseudorandom function.
+   - Resulting hash is represented as a string of hexadecimal characters, and compared case-insensitively with the stored credential.
 
 After you finish the settings, click **Create**.
 

en_US/access-control/authn/assets/authn-mongodb-1.png

@@ -55,7 +55,7 @@ You can use EMQX Dashboard to configure how to use MongoDB for password authenti
 
 In the EMQX Dashboard, click **Access Control** -> **Authentication** from the left navigation menu. On the **Authentication** page, click **Create** at the top right corner. Click to select **Password-Based** as **Mechanism**, and **MongoDB** as **Backend** to go to the **Configuration** tab, as shown below. 
 
-<img src="./assets/authn-mongodb-1.png" alt="Authenticate with MondoDB" style="zoom:67%;" />
+![authn-MongoDB_ee](./assets/authn-MongoDB_ee.png)
 
 Follow the instructions below on how to configure the authentication:
 
@@ -84,15 +84,19 @@ Follow the instructions below on how to configure the authentication:
 **Authentication configuration**: Configure settings related to authentication:
 
 - **Password Hash Field**: Specify the field name of the password.
-- **Password Hash**: Select the hashing function for password storage, such as `plain`, `md5`, `sha`, `bcrypt`, or `pbkdf2`. Additional configurations depend on the selected function:
-  - For `plain`, `md5`, `sha`, `sha256`, or `sha512`:
-    - **Salt Position**: Define how salt (random data) is added to the password. Options are`suffix`, `prefix`, or `disable`. You can keep the default value unless you migrate user credentials from external storage into the EMQX built-in database. Note: Set **Salt Position** to `disable` if `plain` is selected.
+- **Password Hash**: Select the password hashing algorithm applied to plain-text passwords before results are stored in the database. Available options are `plain`, `md5`, `sha`, `sha256`, `sha512`, `bcrypt`, and `pbkdf2`. Additional configurations depend on the selected algorithm:
+  - For `md5`, `sha`, `sha256` or `sha512`:
+    - **Salt Position**: Determines how salt (random data) is mixed with the password. Options are `suffix`, `prefix`, or `disable`. You can keep the default value unless you migrate user credentials from external storage into the EMQX built-in database.
+    - Resulting hash is represented as a string of hexadecimal characters, and compared case-insensitively with the stored credential.
+  - For `plain`:
+    - **Salt Position**: should be `disable`.
   - For `bcrypt`:
-    - **Salt Rounds**: Set the number of hash function applications, expressed as 2^Salt Rounds, also known as the "cost factor". Default: `10`; Range: `5-10`. Higher values are recommended for better security. Note: Increasing the cost factor by 1 doubles the necessary time for authentication.
+    - **Salt Rounds**: Defines the number of times the hash function is applied, expressed as _2<sup>Salt Rounds</sup>_, also known as the "cost factor". The default value is `10`, with a permissible range of `5` to `10`. A higher value is recommended for enhanced security. Note: Increasing the cost factor by 1 doubles the necessary time for authentication.
   - For `pbkdf2`:
-    - **Pseudorandom Function**: Specify the hash functions to generate the key, such as `sha256`. 
-    - **Iteration Count**: Specify the iteration times; Default: `4096`.
-    - **Derived Key Length** (optional): Specify the generated key length. You can leave this field blank, then the key length will be determined by the pseudorandom function you selected.  
+    - **Pseudorandom Function**: Selects the hash function that generates the key, such as `sha256`.
+    - **Iteration Count**: Sets the number of times the hash function is executed. The default is `4096`.
+    - **Derived Key Length** (optional): Specifies the length in bytes of the generated key. If left blank, the length will default to that determined by the selected pseudorandom function.
+    - Resulting hash is represented as a string of hexadecimal characters, and compared case-insensitively with the stored credential. 
 - **Salt Field**: Specify the salt field in MongoDB.
 - **is_superuser Field**: Determine if the user is a super user. 
 - **Filter**: A map interpreted as MongoDB selector for credential lookup. [Placeholders](./authn.md#authentication-placeholders) are supported. 

en_US/access-control/authn/http.md

@@ -84,15 +84,19 @@ Follow the instructions below on how to configure the authentication:
 
 **Authentication configuration**: Configure settings related to authentication:
 
-- **Password Hash**: Select the hash function for storing passwords in the database, such as `plain`, `md5`, `sha`, `bcrypt`, or `pbkdf2`. Additional configuration depends on your selected function:
-  - For `plain`, `md5`, `sha`, `sha256`, or `sha512`:
-    - **Salt Position**: Determines how salt (random data) is added to the password. Options are `suffix`, `prefix`, or `disable`. Retain the default setting unless migrating credentials from external storage to the EMQX built-in database. Note: Set to `disable` if `plain` is chosen.
+- **Password Hash**: Select the password hashing algorithm applied to plain-text passwords before results are stored in the database. Available options are `plain`, `md5`, `sha`, `sha256`, `sha512`, `bcrypt`, and `pbkdf2`. Additional configurations depend on the selected algorithm:
+  - For `md5`, `sha`, `sha256` or `sha512`:
+    - **Salt Position**: Determines how salt (random data) is mixed with the password. Options are `suffix`, `prefix`, or `disable`.  You can keep the default value unless you migrate user credentials from external storage into the EMQX built-in database.
+    - Resulting hash is represented as a string of hexadecimal characters, and compared case-insensitively with the stored credential.
+  - For `plain`:
+    - **Salt Position**: should be `disable`.
   - For `bcrypt`:
-    - **Salt Rounds**: Set the number of times the hash function executes, denoted as 2^Salt Rounds, also known as the "cost factor". The default is `10`, with a range of `5` to `10`. A higher value is recommended for enhanced security. Note: Increasing the cost factor by 1 doubles the necessary time for authentication.
+    - **Salt Rounds**: Defines the number of times the hash function is applied, expressed as _2<sup>Salt Rounds</sup>_, also known as the "cost factor". The default value is `10`, with a permissible range of `5` to `10`. A higher value is recommended for enhanced security. Note: Increasing the cost factor by 1 doubles the necessary time for authentication.
   - For `pbkdf2`:
-    - **Pseudorandom Function**: Specify the Hash functions to generate the key, such as `sha256`. 
-    - **Iteration Count**: Specify the iteration times; Default: `4096`.
-    - **Derived Key Length** (optional): Specify the length of the generated password. You can leave this field blank, then the key length will be determined by the pseudorandom function you selected. 
+    - **Pseudorandom Function**: Selects the hash function that generates the key, such as `sha256`.
+    - **Iteration Count**: Sets the number of times the hash function is executed. The default is `4096`.
+    - **Derived Key Length** (optional): Specifies the length in bytes of the generated key. If left blank, the length will default to that determined by the selected pseudorandom function.
+    - Resulting hash is represented as a string of hexadecimal characters, and compared case-insensitively with the stored credential.
 - **SQL**: Fill in the query statement according to the data schema. For more information, see [SQL data schema and query statement](#sql-table-structure-and-query-statement). 
 
 After you finish the settings, click **Create**.