Merge pull request #3221 from emqx/251030-sync-release-5.8

251030 sync release 5.8

Author: Meggielqk

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

@@ -1,6 +1,6 @@
 # Integrate with Redis
 
-EMQX supports integrating with Redis for password authentication. EMQX Redis authenticator currently supports connecting to running in three different modes, which are Single, [Redis Sentinel](https://redis.io/docs/manual/sentinel/) and [Redis Cluster](https://redis.io/docs/manual/scaling/). This section gives detailed instructions on the data schema supported and on how to configure with EMQX Dashboard and configuration file. 
+EMQX supports integrating with Redis for password authentication. EMQX Redis authenticator currently supports connecting to Redis running in three different modes, which are Single, [Redis Sentinel](https://redis.io/docs/manual/sentinel/), and [Redis Cluster](https://redis.io/docs/manual/scaling/). This section gives detailed instructions on the data schema supported and on how to configure with EMQX Dashboard and the configuration file. 
 
 ::: tip Prerequisite:
 
@@ -51,37 +51,56 @@ You can use EMQX Dashboard to configure how to use Redis for password authentica
 
 <img src="./assets/authn-redis.png" alt="Authentication with redis" style="zoom:67%;" />
 
-4. Follow the instructions below to configure the authentication backend:
-
-   - Enter the information for connecting to Redis.
-
-     - **Redis Mode**: Select how Redis is deployed, including `Single`, `Sentinel` and `Cluster`. 
-     - **Server(s)**: Specify the Redis server address that EMQX is to connect, if **Redis Mode** is set to `Sentinel` or `Cluster`, you will need to input all Redis servers (separated with a `,`) that EMQX is to connect.
-     - **Sentinel Name**: Specify the name to use; type: strings; only needed if you set **Redis Mode** to `Sentinel`.
-     - **Database**: Redis database name; Data type: strings.
-     - **Password**: Specify Redis user password. 
-   - Configure settings related to authentication:
-
-     - **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**: 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 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.
-   - **Precondition**: A [Variform expression](../../configuration/configuration.md#variform-expressions) used to control whether this Redis authenticator should be applied to a client connection. The expression is evaluated against attributes from the client (such as `username`, `clientid`, `listener`, etc.). The authenticator will only be invoked if the expression evaluates to the string `"true"`. Otherwise, it will be skipped. For more information about the precondition, see [Authenticator Preconditions](./authn.md#authenticator-preconditions).
-   - **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).
-   - **CMD**: Redis query command. 
-   - **Advanced Settings**: 
-     - **Pool size** (optional): Specify the number of concurrent connections from an EMQX node to a Redis server. Default: `8`. 
-
-5. After you finish the settings, click **Create**.
+Follow the instructions below on how to configure the authentication:
+
+**Connect**: Enter the information for connecting to Redis.
+
+- **Redis Mode**: Select how Redis is deployed, including `Single`, `Sentinel` and `Cluster`. 
+
+- **Server(s)**: Specify the Redis server address that EMQX is to connect, if **Redis Mode** is set to `Sentinel` or `Cluster`, you will need to input all Redis servers (separated with a `,`) that EMQX is to connect.
+
+- **Sentinel Name**: Specify the name to use; type: strings; only needed if you set **Redis Mode** to `Sentinel`.
+
+- **Database**: Redis database name; Data type: strings.
+
+- **Username**: Specify the Redis username to connect with. This field is required if your Redis instance uses [Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/#create-and-edit-user-acls-with-the-acl-setuser-command) (introduced in Redis 6.0) for authentication. If your Redis server uses the default user (with ACLs disabled or not enforced), you can leave this field blank.
+
+  ::: tip
+
+  The `username` field is supported starting from EMQX 5.2.0. Ensure your deployment is running this version or later to use Redis ACL.
+
+  :::
+
+- **Password**: Specify the password for the Redis user. The field is required for connecting to Redis instances with authentication enabled.
+
+  - If you have entered a username, this password must match the credentials configured in your Redis ACL settings.
+  - If no username is provided, this password will be used to authenticate as the `default` user (if enabled).
+
+
+**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).
+
+**Connection Configuration**: Set the concurrent connections.
+
+- **Pool size** (optional): Specify the number of concurrent connections from an EMQX node to a Redis server. Default: `8`. 
+
+**Authentication configuration**: Configure settings related to authentication:
+
+- **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**: 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 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.
+- **CMD**: Redis query command. 
+
+After you finish the settings, click **Create**.
 
 ## Configure with Configuration Items
 

en_US/access-control/authn/redis.md

@@ -55,31 +55,36 @@ All rules added in Redis Authorizer are **allow** rules, which means Redis Autho
 
 You can use EMQX Dashboard to configure how to use Redis for user authorization.
 
-1. On [EMQX Dashboard](http://127.0.0.1:18083/#/authentication), click **Access Control** -> **Authorization** on the left navigation tree to enter the **Authorization** page. 
+1. On the EMQX Dashboard, click **Access Control** -> **Authorization** on the left navigation tree to enter the **Authorization** page. 
 
 2. Click **Create** at the top right corner, then click to select **Redis** as **Backend**. Click **Next**. The **Configuration** tab is shown as below.
 
-   <img src="./assets/authz-Redis_ee.png" alt="authz-Redis_ee" style="zoom:67%;" />
+   <img src="./assets/authz-redis.png" alt="authz-Redis_ee" style="zoom:67%;" />
 
-3. Follow the instructions below to do the configuration.
+3. Follow the instructions below to configure the settings.
 
-   **Connect**: Fill in the information needed to connect Redis.
-
-   - **Redis Mode**: Select how Redis is deployed, including **Single**, **Sentinel** and **Cluster**.
+   - **Redis Mode**: Select how Redis is deployed, including `Single`, `Sentinel` and `Cluster`.
    - **Server**: Specify the server address that EMQX is to connect (`host:port`).
    - **Database**: Redis database name.
-   - **Password**: Specify user password. 
+   - **Username**: Specify the Redis username to connect with. This field is required if your Redis instance uses [Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/#create-and-edit-user-acls-with-the-acl-setuser-command) (introduced in Redis 6.0) for authentication. If your Redis server uses the default user (with ACLs disabled or not enforced), you can leave this field blank.
+
+     ::: tip
 
-   **TLS Configuration**: Turn on the toggle switch if you want to enable TLS. 
+     The `username` field is supported starting from EMQX 5.2.0. Ensure your deployment is running this version or later to use Redis ACL.
 
-   **Connection Configuration**: Set the concurrent connections and waiting time before a connection is timed out.
+     :::
+   - **Password**: Specify the password for the Redis user. The field is required for connecting to Redis instances with authentication enabled.
 
-   - **Pool size** (optional): Input an integer value to define the number of concurrent connections from an EMQX node to Redis. Default: **8**. 
+     - If you have entered a username, this password must match the credentials configured in your Redis ACL settings.
+     - If no username is provided, this password will be used to authenticate as the `default` user (if enabled).
 
-   **Authorization configuration**: Fill in the authorization-related settings:
+   - **Enable TLS**: Turn on the toggle switch if you want to enable TLS. 
 
    - **CMD**: Fill in the query command according to the data schema.
 
+   - **Advanced Settings**: Set the concurrent connections and waiting time before a connection is timed out.
+     - **Pool size** (optional): Input an integer value to define the number of concurrent connections from an EMQX node to Redis. Default: `8`. 
+
 4. Click **Create** to finish the settings.
 
 ## Configure with Configuration Items

en_US/access-control/authz/assets/authz-Redis_ee.png

@@ -62,7 +62,9 @@ EMQX supports Amazon S3 and other S3-compatible storage services. You can use AW
 
 1. In the [AWS S3 Console](https://console.amazonaws.cn/s3/home), click the **Create bucket** button. Follow the instructions to enter the relevant information, such as bucket name and region, to create an S3 bucket. For detailed operations, refer to the [AWS Documentation](https://docs.amazonaws.cn/AmazonS3/latest/userguide/creating-bucket.html).
 2. Set bucket permissions. After the bucket is created successfully, select the bucket and click the **Permissions** tab. Based on your needs, you can set the bucket to public read/write, private, or other permissions.
-3. Obtain access keys. In the AWS Console, search for and select the **IAM** service. Create a new user for S3 and obtain the Access Key and Secret Key.
+3. Obtain access keys.
+   - **Manual Configuration**: In the AWS Console, search for and select the **IAM** service. Create a new user for S3 and obtain the Access Key ID and Secret Access Key. See [AWS guide: Managing access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
+   - **Automatic Retrieval (EC2 only)**: If EMQX is running on **AWS EC2**, [attach an **IAM role**](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) with sufficient permissions. EMQX can automatically fetch temporary credentials from Instance Metadata via [**IMDSv2** API](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-metadata-security-credentials.html).
 
 With the Amazon S3 bucket created and configured, you are now ready to create an Amazon S3 Sink in EMQX.
 
@@ -103,13 +105,18 @@ Before adding the S3 Sink, you need to create the corresponding connector.
 
 1. Go to the Dashboard **Integration** -> **Connector** page.
 2. Click the **Create** button in the top right corner.
-3. Select **Amazon S3** as the connector type and click next.
-4. Enter the connector name, a combination of upper and lowercase letters and numbers. Here, enter `my-s3`.
+3. Select **Amazon S3** as the connector type and click **Next**.
+4. Enter a name for the connector. The name must start with a letter or number and can contain letters, numbers, hyphens, or underscores. In this example, enter `my-s3`.
 5. Enter the connection information.
    - If you are using the Amazon S3 bucket, enter the following information:
      - **Host**: The host varies by region and is formatted as `s3.{region}.amazonaws.com`.
      - **Port**: Enter `443`.
-     - **Access Key ID** and **Secret Access Key**: Enter the access keys created in AWS.
+     - **Access Key ID** and **Secret Access Key**:
+     
+       - Enter the access keys created in AWS, or
+       - Leave blank if running EMQX on EC2 with an attached IAM role.
+     
+       See the "Amazon S3" tab in [Prepare S3 Bucket](#prepare-s3-bucket) for details.
    - If you are using MinIO, enter the following information:
      - **Host**: Enter `127.0.0.1`. If you are running MinIO remotely, enter the actual host address.
      - **Port**: Enter `9000`.

en_US/access-control/authz/assets/authz-redis.png

@@ -47,11 +47,26 @@ Redis 认证器支持使用 [Redis hashes](https://redis.io/docs/manual/data-typ
 
    - Redis 数据库的连接设置：
 
-     - **部署模式**：选择 Redis 数据库的部署模式，可选值：**单节点**、**Sentinel**、**Cluster**
-     - **服务**（**列表**）：填入 Redis 服务器地址 (`host:port`) ；当部署模式选为 Sentinel 或 Cluster，您需在此提供所有相关 Redis 服务器的地址，不同地址之间以 `,` 分隔，格式为 `host1:port1,host2:port2,...`
-     - **Sentinel 名字**：指定 Redis Sentinel 配置需要的[主服务器名称](https://redis.io/docs/manual/sentinel/#configuring-sentinel)，仅需在**部署模式**设置为 **Sentinel** 时设置。
-     - **数据库**：整数，用于指定 Redis 数据库的 Index。
-     - **密码**：填入认证密码。
+- **部署模式**：选择 Redis 数据库的部署模式，可选值：**单节点**、**Sentinel**、**Cluster**。
+
+- **服务器地址**：填入 Redis 服务器地址 (`host:port`) ；当部署模式选为 Sentinel 或 Cluster，您需在此提供所有相关 Redis 服务器的地址，不同地址之间以 `,` 分隔，格式为 `host1:port1,host2:port2,...`。
+
+- **Sentinel 名字**（仅需在**部署模式**设置为 **Sentinel** 时设置）：指定 Redis Sentinel 配置需要的[主服务器名称](https://redis.io/docs/manual/sentinel/#configuring-sentinel)。
+
+- **数据库**：整数，用于指定 Redis 数据库的 Index。
+
+- **用户名**：指定用于连接 Redis 的用户名。如果您的 Redis 实例启用了 [Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/#create-and-edit-user-acls-with-the-acl-setuser-command)（在 Redis 6.0 引入）进行身份验证，则此字段为必填项。如果您的 Redis 使用默认用户（未启用或未强制使用 ACL），则可以留空此字段。
+
+  ::: tip 提示
+
+  `username` 字段从 EMQX 5.2.0 版本开始支持。请确保您的部署版本为 5.2.0 或更高，以使用 Redis ACL 功能。
+
+  :::
+
+- **密码**：指定用于连接 Redis 的用户密码。若 Redis 实例启用了身份验证，该字段为必填项。
+
+  - 如果填写了用户名，则此密码必须与 Redis ACL 配置中的凭据匹配。
+  - 如果未填写用户名，则此密码将用于以 Redis 的 `default` 用户身份进行身份验证（前提是默认用户已启用）。
 
    - 认证加密算法相关的配置：
 
@@ -73,7 +88,20 @@ Redis 认证器支持使用 [Redis hashes](https://redis.io/docs/manual/data-typ
 
    - **启用 TLS**：如果要启用TLS，请打开切换按钮。有关启用 TLS 的更多信息，请参见[网络和 TLS](../../network/overview.md)。
 
-   - **命令**：Redis 查询命令。
+- **密码加密方式**：选择应用于明文密码的哈希算法，在将结果存储到数据库之前对密码进行加密。可选算法包括 `plain`、`md5`、`sha`、`sha256`、`sha512`、`bcrypt` 和 `pbkdf2`。具体配置取决于所选择的算法：
+  - 选择 `md5`、`sha`、`sha256` 或 `sha512` 算法，需配置：
+    - **加盐方式**：用于指定盐和密码的组合方式，可选值：`suffix`（在密码尾部加盐）、`prefix`（在密码头部加盐）、`disable`（不启用）。如果您不需要将用户凭据从外部存储迁移到 EMQX 内置数据库，可以保持默认值。
+    - 生成的哈希值以十六进制字符串表示，并与存储的凭据进行不区分大小写的比对。
+  - 选择 `plain`：
+    - **加盐值方式**：应设置为 `disable`。
+  - 选择 `bcrypt` 算法，需配置:
+    - **Salt Rounds**：指定散列需要的计算次数（2^Salt Rounds），也称成本因子。默认值：`10`，可选值：`5` 到 `10`；数值越高，加密的安全性越高，因此建议采用较大的值，但相应的用户验证的耗时也会增加，您可根据业务需求进行配置。
+  - 选择 `pbkdf2` 算法，需配置：
+    - **伪随机函数**：指定生成密钥使用的散列函数，如 `sha256` 等。
+    - **迭代次数**：指定散列次数，默认值：`4096`。<!--后续补充取值范围-->
+    - **密钥长度**（可选）：指定希望得到的密钥长度。如不指定，密钥长度将由**伪随机函数**确定。
+    - 生成的哈希值以十六进制字符串表示，并与存储的凭据进行不区分大小写的比对。
+- **命令**：Redis 查询命令。
 
    - **高级设置**：在此部分设置并发连接。
      - **连接池大小**（可选）：填入一个整数用于指定从 EMQX 节点到 Redis 数据库的并发连接数；默认值：`8`。