This is an automated email from the ASF dual-hosted git repository.
haonan pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 4508df87 update black white list (#951)
4508df87 is described below
commit 4508df8735abc8cf7aee3c03f34f6aa8d3d33f1c
Author: leto-b <[email protected]>
AuthorDate: Mon Jan 5 10:39:14 2026 +0800
update black white list (#951)
---
src/.vuepress/sidebar/V2.0.x/en-Table.ts | 2 +-
src/.vuepress/sidebar/V2.0.x/en-Tree.ts | 2 +-
src/.vuepress/sidebar/V2.0.x/zh-Table.ts | 2 +-
src/.vuepress/sidebar/V2.0.x/zh-Tree.ts | 2 +-
src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts | 3 +-
src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts | 4 +-
src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts | 7 +-
src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts | 4 +-
.../Table/User-Manual/Black-White-List_timecho.md | 78 ++++++++++++++++++++++
.../Master/Tree/QuickStart/QuickStart_timecho.md | 2 +-
.../Tree/User-Manual/Black-White-List_timecho.md | 78 ++++++++++++++++++++++
.../Master/Tree/User-Manual/White-List_timecho.md | 70 -------------------
.../User-Manual/Black-White-List_timecho.md | 78 ++++++++++++++++++++++
.../latest/QuickStart/QuickStart_timecho.md | 2 +-
.../latest/User-Manual/Black-White-List_timecho.md | 78 ++++++++++++++++++++++
.../latest/User-Manual/White-List_timecho.md | 70 -------------------
.../Table/User-Manual/Black-White-List_timecho.md | 78 ++++++++++++++++++++++
.../Master/Tree/QuickStart/QuickStart_timecho.md | 2 +-
.../Tree/User-Manual/Black-White-List_timecho.md | 78 ++++++++++++++++++++++
.../Master/Tree/User-Manual/White-List_timecho.md | 70 -------------------
.../User-Manual/Black-White-List_timecho.md | 78 ++++++++++++++++++++++
.../latest/QuickStart/QuickStart_timecho.md | 2 +-
.../latest/User-Manual/Black-White-List_timecho.md | 78 ++++++++++++++++++++++
.../latest/User-Manual/White-List_timecho.md | 70 -------------------
24 files changed, 643 insertions(+), 295 deletions(-)
diff --git a/src/.vuepress/sidebar/V2.0.x/en-Table.ts
b/src/.vuepress/sidebar/V2.0.x/en-Table.ts
index a7a75a2c..3cd9b729 100644
--- a/src/.vuepress/sidebar/V2.0.x/en-Table.ts
+++ b/src/.vuepress/sidebar/V2.0.x/en-Table.ts
@@ -108,7 +108,7 @@ export const enSidebar = {
{ text: 'Data Sync', link: 'Data-Sync_apache' },
{ text: 'UDF', link: 'User-defined-function' },
{
- text: 'Security Permissions',
+ text: 'Security Management',
collapsible: true,
children: [
{ text: 'Authority Management', link:
'Authority-Management_apache' },
diff --git a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts
b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts
index 93bde953..cd18177a 100644
--- a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts
+++ b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts
@@ -127,7 +127,7 @@ export const enSidebar = {
},
{ text: 'UDF', link: 'User-defined-function_apache' },
{
- text: 'Security Permissions',
+ text: 'Security Management',
collapsible: true,
children: [{ text: 'Permission Management', link:
'Authority-Management_apache' }],
},
diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts
b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts
index 6d555172..6b35195b 100644
--- a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts
+++ b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts
@@ -108,7 +108,7 @@ export const zhSidebar = {
{ text: '数据同步', link: 'Data-Sync_apache' },
{ text: 'UDF', link: 'User-defined-function' },
{
- text: '安全权限',
+ text: '安全管理',
collapsible: true,
children: [{ text: '权限管理', link: 'Authority-Management_apache' }],
},
diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts
b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts
index 499781c1..cd66f816 100644
--- a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts
+++ b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts
@@ -118,7 +118,7 @@ export const zhSidebar = {
},
{ text: 'UDF', link: 'User-defined-function_apache' },
{
- text: '安全权限',
+ text: '安全管理',
collapsible: true,
children: [{ text: '权限管理', link: 'Authority-Management_apache' }],
},
diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts
b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts
index d651f24d..58b7ccd8 100644
--- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts
+++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts
@@ -125,10 +125,11 @@ export const enSidebar = {
{ text: 'Data Sync', link: 'Data-Sync_timecho' },
{ text: 'UDF', link: 'User-defined-function' },
{
- text: 'Security Permissions',
+ text: 'Security Management',
collapsible: true,
children: [
{ text: 'Authority Management', link:
'Authority-Management_timecho' },
+ { text: 'Black White List', link: 'Black-White-List_timecho' },
],
},
{ text: 'Tiered Storage', link: 'Tiered-Storage_timecho' },
diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts
b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts
index 438a6ac4..46f077ac 100644
--- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts
+++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts
@@ -147,11 +147,11 @@ export const enSidebar = {
{ text: 'UDF', link: 'User-defined-function_timecho' },
{ text: 'View', link: 'IoTDB-View_timecho' },
{
- text: 'Security Permissions',
+ text: 'Security Management',
collapsible: true,
children: [
{ text: 'Permission Management', link:
'Authority-Management_timecho' },
- { text: 'White List', link: 'White-List_timecho' },
+ { text: 'Black White List', link: 'Black-White-List_timecho' },
{ text: 'Security Audit', link: 'Audit-Log_timecho' },
],
},
diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts
b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts
index 58806ccc..8471a946 100644
--- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts
+++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts
@@ -116,9 +116,12 @@ export const zhSidebar = {
{ text: '数据同步', link: 'Data-Sync_timecho' },
{ text: 'UDF', link: 'User-defined-function' },
{
- text: '安全权限',
+ text: '安全管理',
collapsible: true,
- children: [{ text: '权限管理', link: 'Authority-Management_timecho' }],
+ children: [
+ { text: '权限管理', link: 'Authority-Management_timecho' },
+ { text: '黑白名单', link: 'Black-White-List_timecho' },
+ ],
},
{ text: '多级存储', link: 'Tiered-Storage_timecho' },
{ text: '树转表视图', link: 'Tree-to-Table' },
diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts
b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts
index 7251ea16..778c5783 100644
--- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts
+++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts
@@ -129,11 +129,11 @@ export const zhSidebar = {
{ text: 'UDF', link: 'User-defined-function_timecho' },
{ text: '视图', link: 'IoTDB-View_timecho' },
{
- text: '安全权限',
+ text: '安全管理',
collapsible: true,
children: [
{ text: '权限管理', link: 'Authority-Management_timecho' },
- { text: '白名单', link: 'White-List_timecho' },
+ { text: '黑白名单', link: 'Black-White-List_timecho' },
{ text: '安全审计', link: 'Audit-Log_timecho' },
],
},
diff --git a/src/UserGuide/Master/Table/User-Manual/Black-White-List_timecho.md
b/src/UserGuide/Master/Table/User-Manual/Black-White-List_timecho.md
new file mode 100644
index 00000000..dceab568
--- /dev/null
+++ b/src/UserGuide/Master/Table/User-Manual/Black-White-List_timecho.md
@@ -0,0 +1,78 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# Black White List
+
+## 1. Introduction
+
+IoTDB is a time-series database designed for IoT scenarios, supporting
efficient data storage, query, and analysis. With the widespread application of
IoT technology, data security and access control have become critical. In open
environments, ensuring secure data access for legitimate users presents a key
challenge. The whitelist mechanism allows only trusted IPs or users to connect,
reducing the attack surface at the source. The blacklist function can block
malicious IPs in real time i [...]
+
+> Note: This feature is available starting from version 2.0.6.
+
+## 2. Whitelist
+
+### 2.1 Function Description
+
+By enabling the whitelist function and configuring the whitelist, client
addresses allowed to connect to IoTDB are specified. Only clients within the
whitelist can access IoTDB, achieving security control.
+
+### 2.2 Configuration Parameters
+
+Administrators can enable/disable the whitelist function and add, modify, or
delete whitelist IPs/IP segments in the following two ways:
+
+* Edit the configuration file `iotdb‑system.properties`.
+* Use the `set configuration` statement.
+ * Table model reference: [set
configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-update-configuration-items)
+
+Related parameters are as follows:
+
+| Name | Description
|
Default Value | Effective Mode | Example
|
+| ----------------- |
-----------------------------------------------------------------------------------------------------------------------------------
| --------------- | ---------------- |
------------------------------------------------------------------- |
+| `enable_white_list` | Whether to enable the whitelist function. true:
enable; false: disable. The value is case‑insensitive.
| false | Hot reload | `set enable_white_list = 'true'`
|
+| `white_ip_list` | Add, modify, or delete whitelist IPs/IP segments.
Supports exact match and the \* wildcard. Multiple IPs are separated by commas.
| empty | Hot reload | `set
white_ip_list='192.168.1.200,192.168.1.201,192.168.1.*'` |
+
+## 3. Blacklist
+
+### 3.1 Function Description
+
+By enabling the blacklist function and configuring the blacklist, certain
specific IP addresses are prevented from accessing the database, guarding
against unauthorized access, SQL injection, brute‑force attacks, DDoS attacks,
and other security threats, thereby ensuring the security and stability of data
transmission.
+
+### 3.2 Configuration Parameters
+
+Administrators can enable/disable the blacklist function and add, modify, or
delete blacklist IPs/IP segments in the following two ways:
+
+* Edit the configuration file `iotdb‑system.properties`.
+* Use the `set configuration`statement.
+ * Table model reference:[set
configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-update-configuration-items)
+
+Related parameters are as follows:
+
+| Name | Description
|
Default Value | Effective Mode | Example
|
+|---------------------|
-----------------------------------------------------------------------------------------------------------------------------------
| --------------- | ---------------- |
------------------------------------------------------------------- |
+| `enable_black_list` | Whether to enable the blacklist function. true:
enable; false: disable. The value is case‑insensitive.
| false | Hot reload | `set enable_black_list = 'true'`
|
+| `black_ip_list` | Add, modify, or delete blacklist IPs/IP segments.
Supports exact match and the \* wildcard. Multiple IPs are separated by commas.
| empty | Hot reload | `set
black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*'` |
+
+## 4. Notes
+
+1. After the whitelist is enabled, if the list is empty, all connections are
denied. If the local IP is not included, local login is denied.
+2. When the same IP appears in both the whitelist and blacklist, the blacklist
takes precedence.
+3. The system validates the IP format. Invalid entries will cause an error
when the user connects and be skipped, without affecting the loading of other
valid IPs.
+4. Duplicate IPs in the configuration are supported; they are automatically
deduplicated in memory without notification. For manual deduplication, edit the
configuration accordingly.
+5. Blacklist/whitelist rules only apply to new connections. Existing
connections before enabling the function are not affected; they will be
intercepted only upon subsequent reconnection.
diff --git a/src/UserGuide/Master/Tree/QuickStart/QuickStart_timecho.md
b/src/UserGuide/Master/Tree/QuickStart/QuickStart_timecho.md
index 4b86833e..ab5818ef 100644
--- a/src/UserGuide/Master/Tree/QuickStart/QuickStart_timecho.md
+++ b/src/UserGuide/Master/Tree/QuickStart/QuickStart_timecho.md
@@ -70,7 +70,7 @@ This guide will assist you in quickly installing and
deploying IoTDB. You can qu
- Stream Framework: [Stream Framework](../User-Manual/Streaming_timecho.md)
- - Security Management: [Security
Management](../User-Manual/White-List_timecho.md)
+ - Security Management: [Security
Management](../User-Manual/Black-White-List_timecho.md)
- Database Administration: [Database
Administration](../User-Manual/Authority-Management_timecho.md)
diff --git a/src/UserGuide/Master/Tree/User-Manual/Black-White-List_timecho.md
b/src/UserGuide/Master/Tree/User-Manual/Black-White-List_timecho.md
new file mode 100644
index 00000000..2692edd4
--- /dev/null
+++ b/src/UserGuide/Master/Tree/User-Manual/Black-White-List_timecho.md
@@ -0,0 +1,78 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# Black White List
+
+## 1. Introduction
+
+IoTDB is a time-series database designed for IoT scenarios, supporting
efficient data storage, query, and analysis. With the widespread application of
IoT technology, data security and access control have become critical. In open
environments, ensuring secure data access for legitimate users presents a key
challenge. The whitelist mechanism allows only trusted IPs or users to connect,
reducing the attack surface at the source. The blacklist function can block
malicious IPs in real time i [...]
+
+> Note: This feature is available starting from version 2.0.6.
+
+## 2. Whitelist
+
+### 2.1 Function Description
+
+By enabling the whitelist function and configuring the whitelist, client
addresses allowed to connect to IoTDB are specified. Only clients within the
whitelist can access IoTDB, achieving security control.
+
+### 2.2 Configuration Parameters
+
+Administrators can enable/disable the whitelist function and add, modify, or
delete whitelist IPs/IP segments in the following two ways:
+
+* Edit the configuration file `iotdb‑system.properties`.
+* Use the `set configuration` statement.
+ * Tree model reference: [set
configuration](../Reference/Modify-Config-Manual.md)
+
+Related parameters are as follows:
+
+| Name | Description
|
Default Value | Effective Mode | Example
|
+| ----------------- |
-----------------------------------------------------------------------------------------------------------------------------------
| --------------- | ---------------- |
------------------------------------------------------------------- |
+| `enable_white_list` | Whether to enable the whitelist function. true:
enable; false: disable. The value is case‑insensitive.
| false | Hot reload | `set enable_white_list = 'true'`
|
+| `white_ip_list` | Add, modify, or delete whitelist IPs/IP segments.
Supports exact match and the \* wildcard. Multiple IPs are separated by commas.
| empty | Hot reload | `set
white_ip_list='192.168.1.200,192.168.1.201,192.168.1.*'` |
+
+## 3. Blacklist
+
+### 3.1 Function Description
+
+By enabling the blacklist function and configuring the blacklist, certain
specific IP addresses are prevented from accessing the database, guarding
against unauthorized access, SQL injection, brute‑force attacks, DDoS attacks,
and other security threats, thereby ensuring the security and stability of data
transmission.
+
+### 3.2 Configuration Parameters
+
+Administrators can enable/disable the blacklist function and add, modify, or
delete blacklist IPs/IP segments in the following two ways:
+
+* Edit the configuration file `iotdb‑system.properties`.
+* Use the `set configuration`statement.
+ * Tree model reference:[set
configuration](../Reference/Modify-Config-Manual.md)
+
+Related parameters are as follows:
+
+| Name | Description
|
Default Value | Effective Mode | Example
|
+|---------------------|
-----------------------------------------------------------------------------------------------------------------------------------
| --------------- | ---------------- |
------------------------------------------------------------------- |
+| `enable_black_list` | Whether to enable the blacklist function. true:
enable; false: disable. The value is case‑insensitive.
| false | Hot reload | `set enable_black_list = 'true'`
|
+| `black_ip_list` | Add, modify, or delete blacklist IPs/IP segments.
Supports exact match and the \* wildcard. Multiple IPs are separated by commas.
| empty | Hot reload | `set
black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*'` |
+
+## 4. Notes
+
+1. After the whitelist is enabled, if the list is empty, all connections are
denied. If the local IP is not included, local login is denied.
+2. When the same IP appears in both the whitelist and blacklist, the blacklist
takes precedence.
+3. The system validates the IP format. Invalid entries will cause an error
when the user connects and be skipped, without affecting the loading of other
valid IPs.
+4. Duplicate IPs in the configuration are supported; they are automatically
deduplicated in memory without notification. For manual deduplication, edit the
configuration accordingly.
+5. Blacklist/whitelist rules only apply to new connections. Existing
connections before enabling the function are not affected; they will be
intercepted only upon subsequent reconnection.
diff --git a/src/UserGuide/Master/Tree/User-Manual/White-List_timecho.md
b/src/UserGuide/Master/Tree/User-Manual/White-List_timecho.md
deleted file mode 100644
index ae49c164..00000000
--- a/src/UserGuide/Master/Tree/User-Manual/White-List_timecho.md
+++ /dev/null
@@ -1,70 +0,0 @@
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
--->
-
-# White List
-
-## 1. **Function Description**
-
-Allow which client addresses can connect to IoTDB
-
-## 2. **Configuration File**
-
-conf/iotdb-system.properties
-
-conf/white.list
-
-## 3. **Configuration Item**
-
-iotdb-system.properties:
-
-Decide whether to enable white list
-
-```YAML
-
-# Whether to enable white list
-enable_white_list=true
-```
-
-white.list:
-
-Decide which IP addresses can connect to IoTDB
-
-```YAML
-# Support for annotation
-# Supports precise matching, one IP per line
-10.2.3.4
-
-# Support for * wildcards, one ip per line
-10.*.1.3
-10.100.0.*
-```
-
-## 4. **Note**
-
-1. If the white list itself is cancelled via the session client, the current
connection is not immediately disconnected. It is rejected the next time the
connection is created.
-2. If white.list is modified directly, it takes effect within one minute. If
modified via the session client, it takes effect immediately, updating the
values in memory and the white.list disk file.
-3. Enable the whitelist function, there is no white.list file, start the DB
service successfully, however, all connections are rejected.
-4. while DB service is running, the white.list file is deleted, and all
connections are denied after up to one minute.
-5. whether to enable the configuration of the white list function, can be hot
loaded.
-6. Use the Java native interface to modify the whitelist, must be the root
user to modify, reject non-root user to modify; modify the content must be
legal, otherwise it will throw a StatementExecutionException.
-
-
-
diff --git a/src/UserGuide/latest-Table/User-Manual/Black-White-List_timecho.md
b/src/UserGuide/latest-Table/User-Manual/Black-White-List_timecho.md
new file mode 100644
index 00000000..dceab568
--- /dev/null
+++ b/src/UserGuide/latest-Table/User-Manual/Black-White-List_timecho.md
@@ -0,0 +1,78 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# Black White List
+
+## 1. Introduction
+
+IoTDB is a time-series database designed for IoT scenarios, supporting
efficient data storage, query, and analysis. With the widespread application of
IoT technology, data security and access control have become critical. In open
environments, ensuring secure data access for legitimate users presents a key
challenge. The whitelist mechanism allows only trusted IPs or users to connect,
reducing the attack surface at the source. The blacklist function can block
malicious IPs in real time i [...]
+
+> Note: This feature is available starting from version 2.0.6.
+
+## 2. Whitelist
+
+### 2.1 Function Description
+
+By enabling the whitelist function and configuring the whitelist, client
addresses allowed to connect to IoTDB are specified. Only clients within the
whitelist can access IoTDB, achieving security control.
+
+### 2.2 Configuration Parameters
+
+Administrators can enable/disable the whitelist function and add, modify, or
delete whitelist IPs/IP segments in the following two ways:
+
+* Edit the configuration file `iotdb‑system.properties`.
+* Use the `set configuration` statement.
+ * Table model reference: [set
configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-update-configuration-items)
+
+Related parameters are as follows:
+
+| Name | Description
|
Default Value | Effective Mode | Example
|
+| ----------------- |
-----------------------------------------------------------------------------------------------------------------------------------
| --------------- | ---------------- |
------------------------------------------------------------------- |
+| `enable_white_list` | Whether to enable the whitelist function. true:
enable; false: disable. The value is case‑insensitive.
| false | Hot reload | `set enable_white_list = 'true'`
|
+| `white_ip_list` | Add, modify, or delete whitelist IPs/IP segments.
Supports exact match and the \* wildcard. Multiple IPs are separated by commas.
| empty | Hot reload | `set
white_ip_list='192.168.1.200,192.168.1.201,192.168.1.*'` |
+
+## 3. Blacklist
+
+### 3.1 Function Description
+
+By enabling the blacklist function and configuring the blacklist, certain
specific IP addresses are prevented from accessing the database, guarding
against unauthorized access, SQL injection, brute‑force attacks, DDoS attacks,
and other security threats, thereby ensuring the security and stability of data
transmission.
+
+### 3.2 Configuration Parameters
+
+Administrators can enable/disable the blacklist function and add, modify, or
delete blacklist IPs/IP segments in the following two ways:
+
+* Edit the configuration file `iotdb‑system.properties`.
+* Use the `set configuration`statement.
+ * Table model reference:[set
configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-update-configuration-items)
+
+Related parameters are as follows:
+
+| Name | Description
|
Default Value | Effective Mode | Example
|
+|---------------------|
-----------------------------------------------------------------------------------------------------------------------------------
| --------------- | ---------------- |
------------------------------------------------------------------- |
+| `enable_black_list` | Whether to enable the blacklist function. true:
enable; false: disable. The value is case‑insensitive.
| false | Hot reload | `set enable_black_list = 'true'`
|
+| `black_ip_list` | Add, modify, or delete blacklist IPs/IP segments.
Supports exact match and the \* wildcard. Multiple IPs are separated by commas.
| empty | Hot reload | `set
black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*'` |
+
+## 4. Notes
+
+1. After the whitelist is enabled, if the list is empty, all connections are
denied. If the local IP is not included, local login is denied.
+2. When the same IP appears in both the whitelist and blacklist, the blacklist
takes precedence.
+3. The system validates the IP format. Invalid entries will cause an error
when the user connects and be skipped, without affecting the loading of other
valid IPs.
+4. Duplicate IPs in the configuration are supported; they are automatically
deduplicated in memory without notification. For manual deduplication, edit the
configuration accordingly.
+5. Blacklist/whitelist rules only apply to new connections. Existing
connections before enabling the function are not affected; they will be
intercepted only upon subsequent reconnection.
diff --git a/src/UserGuide/latest/QuickStart/QuickStart_timecho.md
b/src/UserGuide/latest/QuickStart/QuickStart_timecho.md
index 4b86833e..ab5818ef 100644
--- a/src/UserGuide/latest/QuickStart/QuickStart_timecho.md
+++ b/src/UserGuide/latest/QuickStart/QuickStart_timecho.md
@@ -70,7 +70,7 @@ This guide will assist you in quickly installing and
deploying IoTDB. You can qu
- Stream Framework: [Stream Framework](../User-Manual/Streaming_timecho.md)
- - Security Management: [Security
Management](../User-Manual/White-List_timecho.md)
+ - Security Management: [Security
Management](../User-Manual/Black-White-List_timecho.md)
- Database Administration: [Database
Administration](../User-Manual/Authority-Management_timecho.md)
diff --git a/src/UserGuide/latest/User-Manual/Black-White-List_timecho.md
b/src/UserGuide/latest/User-Manual/Black-White-List_timecho.md
new file mode 100644
index 00000000..2692edd4
--- /dev/null
+++ b/src/UserGuide/latest/User-Manual/Black-White-List_timecho.md
@@ -0,0 +1,78 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# Black White List
+
+## 1. Introduction
+
+IoTDB is a time-series database designed for IoT scenarios, supporting
efficient data storage, query, and analysis. With the widespread application of
IoT technology, data security and access control have become critical. In open
environments, ensuring secure data access for legitimate users presents a key
challenge. The whitelist mechanism allows only trusted IPs or users to connect,
reducing the attack surface at the source. The blacklist function can block
malicious IPs in real time i [...]
+
+> Note: This feature is available starting from version 2.0.6.
+
+## 2. Whitelist
+
+### 2.1 Function Description
+
+By enabling the whitelist function and configuring the whitelist, client
addresses allowed to connect to IoTDB are specified. Only clients within the
whitelist can access IoTDB, achieving security control.
+
+### 2.2 Configuration Parameters
+
+Administrators can enable/disable the whitelist function and add, modify, or
delete whitelist IPs/IP segments in the following two ways:
+
+* Edit the configuration file `iotdb‑system.properties`.
+* Use the `set configuration` statement.
+ * Tree model reference: [set
configuration](../Reference/Modify-Config-Manual.md)
+
+Related parameters are as follows:
+
+| Name | Description
|
Default Value | Effective Mode | Example
|
+| ----------------- |
-----------------------------------------------------------------------------------------------------------------------------------
| --------------- | ---------------- |
------------------------------------------------------------------- |
+| `enable_white_list` | Whether to enable the whitelist function. true:
enable; false: disable. The value is case‑insensitive.
| false | Hot reload | `set enable_white_list = 'true'`
|
+| `white_ip_list` | Add, modify, or delete whitelist IPs/IP segments.
Supports exact match and the \* wildcard. Multiple IPs are separated by commas.
| empty | Hot reload | `set
white_ip_list='192.168.1.200,192.168.1.201,192.168.1.*'` |
+
+## 3. Blacklist
+
+### 3.1 Function Description
+
+By enabling the blacklist function and configuring the blacklist, certain
specific IP addresses are prevented from accessing the database, guarding
against unauthorized access, SQL injection, brute‑force attacks, DDoS attacks,
and other security threats, thereby ensuring the security and stability of data
transmission.
+
+### 3.2 Configuration Parameters
+
+Administrators can enable/disable the blacklist function and add, modify, or
delete blacklist IPs/IP segments in the following two ways:
+
+* Edit the configuration file `iotdb‑system.properties`.
+* Use the `set configuration`statement.
+ * Tree model reference:[set
configuration](../Reference/Modify-Config-Manual.md)
+
+Related parameters are as follows:
+
+| Name | Description
|
Default Value | Effective Mode | Example
|
+|---------------------|
-----------------------------------------------------------------------------------------------------------------------------------
| --------------- | ---------------- |
------------------------------------------------------------------- |
+| `enable_black_list` | Whether to enable the blacklist function. true:
enable; false: disable. The value is case‑insensitive.
| false | Hot reload | `set enable_black_list = 'true'`
|
+| `black_ip_list` | Add, modify, or delete blacklist IPs/IP segments.
Supports exact match and the \* wildcard. Multiple IPs are separated by commas.
| empty | Hot reload | `set
black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*'` |
+
+## 4. Notes
+
+1. After the whitelist is enabled, if the list is empty, all connections are
denied. If the local IP is not included, local login is denied.
+2. When the same IP appears in both the whitelist and blacklist, the blacklist
takes precedence.
+3. The system validates the IP format. Invalid entries will cause an error
when the user connects and be skipped, without affecting the loading of other
valid IPs.
+4. Duplicate IPs in the configuration are supported; they are automatically
deduplicated in memory without notification. For manual deduplication, edit the
configuration accordingly.
+5. Blacklist/whitelist rules only apply to new connections. Existing
connections before enabling the function are not affected; they will be
intercepted only upon subsequent reconnection.
diff --git a/src/UserGuide/latest/User-Manual/White-List_timecho.md
b/src/UserGuide/latest/User-Manual/White-List_timecho.md
deleted file mode 100644
index ae49c164..00000000
--- a/src/UserGuide/latest/User-Manual/White-List_timecho.md
+++ /dev/null
@@ -1,70 +0,0 @@
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
--->
-
-# White List
-
-## 1. **Function Description**
-
-Allow which client addresses can connect to IoTDB
-
-## 2. **Configuration File**
-
-conf/iotdb-system.properties
-
-conf/white.list
-
-## 3. **Configuration Item**
-
-iotdb-system.properties:
-
-Decide whether to enable white list
-
-```YAML
-
-# Whether to enable white list
-enable_white_list=true
-```
-
-white.list:
-
-Decide which IP addresses can connect to IoTDB
-
-```YAML
-# Support for annotation
-# Supports precise matching, one IP per line
-10.2.3.4
-
-# Support for * wildcards, one ip per line
-10.*.1.3
-10.100.0.*
-```
-
-## 4. **Note**
-
-1. If the white list itself is cancelled via the session client, the current
connection is not immediately disconnected. It is rejected the next time the
connection is created.
-2. If white.list is modified directly, it takes effect within one minute. If
modified via the session client, it takes effect immediately, updating the
values in memory and the white.list disk file.
-3. Enable the whitelist function, there is no white.list file, start the DB
service successfully, however, all connections are rejected.
-4. while DB service is running, the white.list file is deleted, and all
connections are denied after up to one minute.
-5. whether to enable the configuration of the white list function, can be hot
loaded.
-6. Use the Java native interface to modify the whitelist, must be the root
user to modify, reject non-root user to modify; modify the content must be
legal, otherwise it will throw a StatementExecutionException.
-
-
-
diff --git
a/src/zh/UserGuide/Master/Table/User-Manual/Black-White-List_timecho.md
b/src/zh/UserGuide/Master/Table/User-Manual/Black-White-List_timecho.md
new file mode 100644
index 00000000..740828f9
--- /dev/null
+++ b/src/zh/UserGuide/Master/Table/User-Manual/Black-White-List_timecho.md
@@ -0,0 +1,78 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# 黑白名单
+
+## 1. 引言
+
+IoTDB
是一款针对物联网场景设计的时间序列数据库，支持高效的数据存储、查询和分析。随着物联网技术的广泛应用，数据安全性和访问控制变得至关重要。在开放环境中，如何保证合法用户对数据的安全访问成为了一项关键挑战。白名单机制仅允许可信
IP 或用户接入，从源头缩小攻击面；黑名单功能则能在边缘与云端协同场景下实时拦截恶意 IP，阻断非法访问、SQL 注入、暴力破解及 DDoS
等威胁，为数据传输提供持续、稳定的安全保障。
+
+> 注意：该功能从 V2.0.6 版本开始提供。
+
+## 2. 白名单
+
+### 2.1 功能描述
+
+通过开启白名单功能、配置白名单列表，指定允许连接 IoTDB 的客户端地址，来限制仅在白名单范围内的客户端才能够访问 IoTDB，从而实现安全控制。
+
+### 2.2 配置参数
+
+管理员可以通过以下两种方式来启用/禁用白名单功能以及添加、修改、删除白名单ip/ip段。
+
+* 编辑配置文件 `iotdb-system.properties`进行维护
+* 通过 set configuration 语句进行维护
+ * 表模型请参考：[set
configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-更新配置项)
+
+相关参数如下：
+
+| 名称 | 描述
| 默认值 | 生效方式 | 示例
|
+| ------------------------- |
-----------------------------------------------------------------------------------
| -------- | ---------- |
------------------------------------------------------------------- |
+| `enable_white_list` | 是否启用白名单功能。true：启用；false：禁用。字段值不区分大小写。
| false | 热加载 | `set enable_white_list = 'true' `
|
+| `white_ip_list` | 添加、修改、删除白名单ip/ip段。支持精确匹配，支持\*通配符，多个ip之间以逗号分隔。 | 空
| 热加载 | `set white_ip_list='192.168.1.200,192.168.1.201,192.168.1.*`' |
+
+## 3. 黑名单
+
+### 3.1 功能描述
+
+通过开启黑名单功能、配置黑名单列表，阻止某些特定 IP
地址访问数据库，来防止非法访问、SQL注入、暴力破解、DDoS攻击等安全威胁，从而确保数据传输过程中的安全性和稳定性。
+
+### 3.2 配置参数
+
+管理员可以通过以下两种方式来启用/禁用黑名单功能以及添加、修改、删除黑名单 ip/ip 段。
+
+* 编辑配置文件 `iotdb-system.properties`进行维护
+* 通过 set configuration 语句进行维护
+ * 表模型请参考：[set
configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-更新配置项)
+
+相关参数如下：
+
+| 名称 | 描述
| 默认值 | 生效方式 | 示例
|
+| ------------------------- |
-----------------------------------------------------------------------------------
| -------- | ---------- |
------------------------------------------------------------------- |
+| `enable_black_list` | 是否启用黑名单功能。true：启用；false：禁用。字段值不区分大小写。
| false | 热加载 | `set enable_black_list = 'true' `
|
+| `black_ip_list` | 添加、修改、删除黑名单ip/ip段。支持精确匹配，支持\*通配符，多个ip之间以逗号分隔。 | 空
| 热加载 | `set black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*`' |
+
+## 4. 注意事项
+
+1. 开启白名单后，若列表为空将拒绝所有连接，若未包含本机 IP 则拒绝本机登录。
+2. 当同一 IP 同时存在于黑白名单时，黑名单优先级更高。
+3. 系统会校验 IP 格式，无效条目将在用户连接时报错并被跳过，不影响其他有效IP的加载。
+4. 配置支持重复IP，内存中会自动去重且无提示。如需去重请手动修改。
+5. 黑/白名单规则仅对新连接生效，功能开启前的现有连接不受影响，其后续重连才会被拦截。
diff --git a/src/zh/UserGuide/Master/Tree/QuickStart/QuickStart_timecho.md
b/src/zh/UserGuide/Master/Tree/QuickStart/QuickStart_timecho.md
index 1d83e08a..bbae5359 100644
--- a/src/zh/UserGuide/Master/Tree/QuickStart/QuickStart_timecho.md
+++ b/src/zh/UserGuide/Master/Tree/QuickStart/QuickStart_timecho.md
@@ -69,7 +69,7 @@
- 流处理框架：[流处理框架](../User-Manual/Streaming_timecho.md)
- - 安全控制：[安全控制](../User-Manual/White-List_timecho.md)
+ - 安全控制：[安全控制](../User-Manual/Black-White-List_timecho.md)
- 权限管理：[权限管理](../User-Manual/Authority-Management_timecho.md)
diff --git
a/src/zh/UserGuide/Master/Tree/User-Manual/Black-White-List_timecho.md
b/src/zh/UserGuide/Master/Tree/User-Manual/Black-White-List_timecho.md
new file mode 100644
index 00000000..66d99c27
--- /dev/null
+++ b/src/zh/UserGuide/Master/Tree/User-Manual/Black-White-List_timecho.md
@@ -0,0 +1,78 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# 黑白名单
+
+## 1. 引言
+
+IoTDB
是一款针对物联网场景设计的时间序列数据库，支持高效的数据存储、查询和分析。随着物联网技术的广泛应用，数据安全性和访问控制变得至关重要。在开放环境中，如何保证合法用户对数据的安全访问成为了一项关键挑战。白名单机制仅允许可信
IP 或用户接入，从源头缩小攻击面；黑名单功能则能在边缘与云端协同场景下实时拦截恶意 IP，阻断非法访问、SQL 注入、暴力破解及 DDoS
等威胁，为数据传输提供持续、稳定的安全保障。
+
+> 注意：该功能从 V2.0.6 版本开始提供。
+
+## 2. 白名单
+
+### 2.1 功能描述
+
+通过开启白名单功能、配置白名单列表，指定允许连接 IoTDB 的客户端地址，来限制仅在白名单范围内的客户端才能够访问 IoTDB，从而实现安全控制。
+
+### 2.2 配置参数
+
+管理员可以通过以下两种方式来启用/禁用白名单功能以及添加、修改、删除白名单ip/ip段。
+
+* 编辑配置文件 `iotdb-system.properties`进行维护
+* 通过 set configuration 语句进行维护
+ * 树模型请参考：[set configuration](../Reference/Modify-Config-Manual.md)
+
+相关参数如下：
+
+| 名称 | 描述
| 默认值 | 生效方式 | 示例
|
+| ------------------------- |
-----------------------------------------------------------------------------------
| -------- | ---------- |
------------------------------------------------------------------- |
+| `enable_white_list` | 是否启用白名单功能。true：启用；false：禁用。字段值不区分大小写。
| false | 热加载 | `set enable_white_list = 'true' `
|
+| `white_ip_list` | 添加、修改、删除白名单ip/ip段。支持精确匹配，支持\*通配符，多个ip之间以逗号分隔。 | 空
| 热加载 | `set white_ip_list='192.168.1.200,192.168.1.201,192.168.1.*`' |
+
+## 3. 黑名单
+
+### 3.1 功能描述
+
+通过开启黑名单功能、配置黑名单列表，阻止某些特定 IP
地址访问数据库，来防止非法访问、SQL注入、暴力破解、DDoS攻击等安全威胁，从而确保数据传输过程中的安全性和稳定性。
+
+### 3.2 配置参数
+
+管理员可以通过以下两种方式来启用/禁用黑名单功能以及添加、修改、删除黑名单 ip/ip 段。
+
+* 编辑配置文件 `iotdb-system.properties`进行维护
+* 通过 set configuration 语句进行维护
+ * 树模型请参考：[set configuration](../Reference/Modify-Config-Manual.md)
+
+相关参数如下：
+
+| 名称 | 描述
| 默认值 | 生效方式 | 示例
|
+| ------------------------- |
-----------------------------------------------------------------------------------
| -------- | ---------- |
------------------------------------------------------------------- |
+| `enable_black_list` | 是否启用黑名单功能。true：启用；false：禁用。字段值不区分大小写。
| false | 热加载 | `set enable_black_list = 'true' `
|
+| `black_ip_list` | 添加、修改、删除黑名单ip/ip段。支持精确匹配，支持\*通配符，多个ip之间以逗号分隔。 | 空
| 热加载 | `set black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*`' |
+
+## 4. 注意事项
+
+1. 开启白名单后，若列表为空将拒绝所有连接，若未包含本机 IP 则拒绝本机登录。
+2. 当同一 IP 同时存在于黑白名单时，黑名单优先级更高。
+3. 系统会校验 IP 格式，无效条目将在用户连接时报错并被跳过，不影响其他有效IP的加载。
+4. 配置支持重复IP，内存中会自动去重且无提示。如需去重请手动修改。
+5. 黑/白名单规则仅对新连接生效，功能开启前的现有连接不受影响，其后续重连才会被拦截。
diff --git a/src/zh/UserGuide/Master/Tree/User-Manual/White-List_timecho.md
b/src/zh/UserGuide/Master/Tree/User-Manual/White-List_timecho.md
deleted file mode 100644
index e5176f31..00000000
--- a/src/zh/UserGuide/Master/Tree/User-Manual/White-List_timecho.md
+++ /dev/null
@@ -1,70 +0,0 @@
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
--->
-
-
-# 白名单
-
-## 1. 功能描述
-
-允许哪些客户端地址能连接 IoTDB
-
-## 2. 配置文件
-
-conf/iotdb-system.properties
-
-conf/white.list
-
-## 3. 配置项
-
-iotdb-system.properties:
-
-决定是否开启白名单功能
-
-```YAML
-# 是否开启白名单功能
-enable_white_list=true
-```
-
-white.list:
-
-决定哪些IP地址能够连接IoTDB
-
-```YAML
-# 支持注释
-# 支持精确匹配，每行一个ip
-10.2.3.4
-
-# 支持*通配符，每行一个ip
-10.*.1.3
-10.100.0.*
-```
-
-**注意事项**
-
-1. 如果通过session客户端取消本身的白名单，当前连接并不会立即断开。在下次创建连接的时候拒绝。
-2. 如果直接修改white.list，一分钟内生效。如果通过session客户端修改，立即生效，更新内存中的值和white.list磁盘文件
-3. 开启白名单功能，没有white.list 文件，启动DB服务成功，但是，拒绝所有连接。
-4. DB服务运行中，删除 white.list 文件，至多一分钟后，拒绝所有连接。
-5. 是否开启白名单功能的配置，可以热加载。
-6. 使用Java
原生接口修改白名单，必须是root用户才能修改，拒绝非root用户修改；修改内容必须合法，否则会抛出StatementExecutionException异常。
-
-
-
diff --git
a/src/zh/UserGuide/latest-Table/User-Manual/Black-White-List_timecho.md
b/src/zh/UserGuide/latest-Table/User-Manual/Black-White-List_timecho.md
new file mode 100644
index 00000000..740828f9
--- /dev/null
+++ b/src/zh/UserGuide/latest-Table/User-Manual/Black-White-List_timecho.md
@@ -0,0 +1,78 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# 黑白名单
+
+## 1. 引言
+
+IoTDB
是一款针对物联网场景设计的时间序列数据库，支持高效的数据存储、查询和分析。随着物联网技术的广泛应用，数据安全性和访问控制变得至关重要。在开放环境中，如何保证合法用户对数据的安全访问成为了一项关键挑战。白名单机制仅允许可信
IP 或用户接入，从源头缩小攻击面；黑名单功能则能在边缘与云端协同场景下实时拦截恶意 IP，阻断非法访问、SQL 注入、暴力破解及 DDoS
等威胁，为数据传输提供持续、稳定的安全保障。
+
+> 注意：该功能从 V2.0.6 版本开始提供。
+
+## 2. 白名单
+
+### 2.1 功能描述
+
+通过开启白名单功能、配置白名单列表，指定允许连接 IoTDB 的客户端地址，来限制仅在白名单范围内的客户端才能够访问 IoTDB，从而实现安全控制。
+
+### 2.2 配置参数
+
+管理员可以通过以下两种方式来启用/禁用白名单功能以及添加、修改、删除白名单ip/ip段。
+
+* 编辑配置文件 `iotdb-system.properties`进行维护
+* 通过 set configuration 语句进行维护
+ * 表模型请参考：[set
configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-更新配置项)
+
+相关参数如下：
+
+| 名称 | 描述
| 默认值 | 生效方式 | 示例
|
+| ------------------------- |
-----------------------------------------------------------------------------------
| -------- | ---------- |
------------------------------------------------------------------- |
+| `enable_white_list` | 是否启用白名单功能。true：启用；false：禁用。字段值不区分大小写。
| false | 热加载 | `set enable_white_list = 'true' `
|
+| `white_ip_list` | 添加、修改、删除白名单ip/ip段。支持精确匹配，支持\*通配符，多个ip之间以逗号分隔。 | 空
| 热加载 | `set white_ip_list='192.168.1.200,192.168.1.201,192.168.1.*`' |
+
+## 3. 黑名单
+
+### 3.1 功能描述
+
+通过开启黑名单功能、配置黑名单列表，阻止某些特定 IP
地址访问数据库，来防止非法访问、SQL注入、暴力破解、DDoS攻击等安全威胁，从而确保数据传输过程中的安全性和稳定性。
+
+### 3.2 配置参数
+
+管理员可以通过以下两种方式来启用/禁用黑名单功能以及添加、修改、删除黑名单 ip/ip 段。
+
+* 编辑配置文件 `iotdb-system.properties`进行维护
+* 通过 set configuration 语句进行维护
+ * 表模型请参考：[set
configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-更新配置项)
+
+相关参数如下：
+
+| 名称 | 描述
| 默认值 | 生效方式 | 示例
|
+| ------------------------- |
-----------------------------------------------------------------------------------
| -------- | ---------- |
------------------------------------------------------------------- |
+| `enable_black_list` | 是否启用黑名单功能。true：启用；false：禁用。字段值不区分大小写。
| false | 热加载 | `set enable_black_list = 'true' `
|
+| `black_ip_list` | 添加、修改、删除黑名单ip/ip段。支持精确匹配，支持\*通配符，多个ip之间以逗号分隔。 | 空
| 热加载 | `set black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*`' |
+
+## 4. 注意事项
+
+1. 开启白名单后，若列表为空将拒绝所有连接，若未包含本机 IP 则拒绝本机登录。
+2. 当同一 IP 同时存在于黑白名单时，黑名单优先级更高。
+3. 系统会校验 IP 格式，无效条目将在用户连接时报错并被跳过，不影响其他有效IP的加载。
+4. 配置支持重复IP，内存中会自动去重且无提示。如需去重请手动修改。
+5. 黑/白名单规则仅对新连接生效，功能开启前的现有连接不受影响，其后续重连才会被拦截。
diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart_timecho.md
b/src/zh/UserGuide/latest/QuickStart/QuickStart_timecho.md
index 1d83e08a..bbae5359 100644
--- a/src/zh/UserGuide/latest/QuickStart/QuickStart_timecho.md
+++ b/src/zh/UserGuide/latest/QuickStart/QuickStart_timecho.md
@@ -69,7 +69,7 @@
- 流处理框架：[流处理框架](../User-Manual/Streaming_timecho.md)
- - 安全控制：[安全控制](../User-Manual/White-List_timecho.md)
+ - 安全控制：[安全控制](../User-Manual/Black-White-List_timecho.md)
- 权限管理：[权限管理](../User-Manual/Authority-Management_timecho.md)
diff --git a/src/zh/UserGuide/latest/User-Manual/Black-White-List_timecho.md
b/src/zh/UserGuide/latest/User-Manual/Black-White-List_timecho.md
new file mode 100644
index 00000000..66d99c27
--- /dev/null
+++ b/src/zh/UserGuide/latest/User-Manual/Black-White-List_timecho.md
@@ -0,0 +1,78 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# 黑白名单
+
+## 1. 引言
+
+IoTDB
是一款针对物联网场景设计的时间序列数据库，支持高效的数据存储、查询和分析。随着物联网技术的广泛应用，数据安全性和访问控制变得至关重要。在开放环境中，如何保证合法用户对数据的安全访问成为了一项关键挑战。白名单机制仅允许可信
IP 或用户接入，从源头缩小攻击面；黑名单功能则能在边缘与云端协同场景下实时拦截恶意 IP，阻断非法访问、SQL 注入、暴力破解及 DDoS
等威胁，为数据传输提供持续、稳定的安全保障。
+
+> 注意：该功能从 V2.0.6 版本开始提供。
+
+## 2. 白名单
+
+### 2.1 功能描述
+
+通过开启白名单功能、配置白名单列表，指定允许连接 IoTDB 的客户端地址，来限制仅在白名单范围内的客户端才能够访问 IoTDB，从而实现安全控制。
+
+### 2.2 配置参数
+
+管理员可以通过以下两种方式来启用/禁用白名单功能以及添加、修改、删除白名单ip/ip段。
+
+* 编辑配置文件 `iotdb-system.properties`进行维护
+* 通过 set configuration 语句进行维护
+ * 树模型请参考：[set configuration](../Reference/Modify-Config-Manual.md)
+
+相关参数如下：
+
+| 名称 | 描述
| 默认值 | 生效方式 | 示例
|
+| ------------------------- |
-----------------------------------------------------------------------------------
| -------- | ---------- |
------------------------------------------------------------------- |
+| `enable_white_list` | 是否启用白名单功能。true：启用；false：禁用。字段值不区分大小写。
| false | 热加载 | `set enable_white_list = 'true' `
|
+| `white_ip_list` | 添加、修改、删除白名单ip/ip段。支持精确匹配，支持\*通配符，多个ip之间以逗号分隔。 | 空
| 热加载 | `set white_ip_list='192.168.1.200,192.168.1.201,192.168.1.*`' |
+
+## 3. 黑名单
+
+### 3.1 功能描述
+
+通过开启黑名单功能、配置黑名单列表，阻止某些特定 IP
地址访问数据库，来防止非法访问、SQL注入、暴力破解、DDoS攻击等安全威胁，从而确保数据传输过程中的安全性和稳定性。
+
+### 3.2 配置参数
+
+管理员可以通过以下两种方式来启用/禁用黑名单功能以及添加、修改、删除黑名单 ip/ip 段。
+
+* 编辑配置文件 `iotdb-system.properties`进行维护
+* 通过 set configuration 语句进行维护
+ * 树模型请参考：[set configuration](../Reference/Modify-Config-Manual.md)
+
+相关参数如下：
+
+| 名称 | 描述
| 默认值 | 生效方式 | 示例
|
+| ------------------------- |
-----------------------------------------------------------------------------------
| -------- | ---------- |
------------------------------------------------------------------- |
+| `enable_black_list` | 是否启用黑名单功能。true：启用；false：禁用。字段值不区分大小写。
| false | 热加载 | `set enable_black_list = 'true' `
|
+| `black_ip_list` | 添加、修改、删除黑名单ip/ip段。支持精确匹配，支持\*通配符，多个ip之间以逗号分隔。 | 空
| 热加载 | `set black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*`' |
+
+## 4. 注意事项
+
+1. 开启白名单后，若列表为空将拒绝所有连接，若未包含本机 IP 则拒绝本机登录。
+2. 当同一 IP 同时存在于黑白名单时，黑名单优先级更高。
+3. 系统会校验 IP 格式，无效条目将在用户连接时报错并被跳过，不影响其他有效IP的加载。
+4. 配置支持重复IP，内存中会自动去重且无提示。如需去重请手动修改。
+5. 黑/白名单规则仅对新连接生效，功能开启前的现有连接不受影响，其后续重连才会被拦截。
diff --git a/src/zh/UserGuide/latest/User-Manual/White-List_timecho.md
b/src/zh/UserGuide/latest/User-Manual/White-List_timecho.md
deleted file mode 100644
index e5176f31..00000000
--- a/src/zh/UserGuide/latest/User-Manual/White-List_timecho.md
+++ /dev/null
@@ -1,70 +0,0 @@
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
--->
-
-
-# 白名单
-
-## 1. 功能描述
-
-允许哪些客户端地址能连接 IoTDB
-
-## 2. 配置文件
-
-conf/iotdb-system.properties
-
-conf/white.list
-
-## 3. 配置项
-
-iotdb-system.properties:
-
-决定是否开启白名单功能
-
-```YAML
-# 是否开启白名单功能
-enable_white_list=true
-```
-
-white.list:
-
-决定哪些IP地址能够连接IoTDB
-
-```YAML
-# 支持注释
-# 支持精确匹配，每行一个ip
-10.2.3.4
-
-# 支持*通配符，每行一个ip
-10.*.1.3
-10.100.0.*
-```
-
-**注意事项**
-
-1. 如果通过session客户端取消本身的白名单，当前连接并不会立即断开。在下次创建连接的时候拒绝。
-2. 如果直接修改white.list，一分钟内生效。如果通过session客户端修改，立即生效，更新内存中的值和white.list磁盘文件
-3. 开启白名单功能，没有white.list 文件，启动DB服务成功，但是，拒绝所有连接。
-4. DB服务运行中，删除 white.list 文件，至多一分钟后，拒绝所有连接。
-5. 是否开启白名单功能的配置，可以热加载。
-6. 使用Java
原生接口修改白名单，必须是root用户才能修改，拒绝非root用户修改；修改内容必须合法，否则会抛出StatementExecutionException异常。
-
-
-
