|
| 1 | +<!-- |
| 2 | +
|
| 3 | + Licensed to the Apache Software Foundation (ASF) under one |
| 4 | + or more contributor license agreements. See the NOTICE file |
| 5 | + distributed with this work for additional information |
| 6 | + regarding copyright ownership. The ASF licenses this file |
| 7 | + to you under the Apache License, Version 2.0 (the |
| 8 | + "License"); you may not use this file except in compliance |
| 9 | + with the License. You may obtain a copy of the License at |
| 10 | + |
| 11 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 12 | + |
| 13 | + Unless required by applicable law or agreed to in writing, |
| 14 | + software distributed under the License is distributed on an |
| 15 | + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 16 | + KIND, either express or implied. See the License for the |
| 17 | + specific language governing permissions and limitations |
| 18 | + under the License. |
| 19 | +
|
| 20 | +--> |
| 21 | + |
| 22 | +# Black White List |
| 23 | + |
| 24 | +## 1. Introduction |
| 25 | + |
| 26 | +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 in edge-cloud collaborative scenarios, preventing unauthorized access, SQL injection, brute‑force attacks, DDoS, and other threats, thereby providing continuous and stable security for data transmission. |
| 27 | + |
| 28 | +> Note: This feature is available starting from version 2.0.6. |
| 29 | +
|
| 30 | +## 2. Whitelist |
| 31 | + |
| 32 | +### 2.1 Function Description |
| 33 | + |
| 34 | +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. |
| 35 | + |
| 36 | +### 2.2 Configuration Parameters |
| 37 | + |
| 38 | +Administrators can enable/disable the whitelist function and add, modify, or delete whitelist IPs/IP segments in the following two ways: |
| 39 | + |
| 40 | +* Edit the configuration file `iotdb‑system.properties`. |
| 41 | +* Use the `set configuration` statement. |
| 42 | + * Table model reference: [set configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-update-configuration-items) |
| 43 | + |
| 44 | +Related parameters are as follows: |
| 45 | + |
| 46 | +| Name | Description | Default Value | Effective Mode | Example | |
| 47 | +| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------------- | ------------------------------------------------------------------- | |
| 48 | +| `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'` | |
| 49 | +| `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.*'` | |
| 50 | + |
| 51 | +## 3. Blacklist |
| 52 | + |
| 53 | +### 3.1 Function Description |
| 54 | + |
| 55 | +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. |
| 56 | + |
| 57 | +### 3.2 Configuration Parameters |
| 58 | + |
| 59 | +Administrators can enable/disable the blacklist function and add, modify, or delete blacklist IPs/IP segments in the following two ways: |
| 60 | + |
| 61 | +* Edit the configuration file `iotdb‑system.properties`. |
| 62 | +* Use the `set configuration`statement. |
| 63 | + * Table model reference:[set configuration](../SQL-Manual/SQL-Maintenance-Statements.md#_2-2-update-configuration-items) |
| 64 | + |
| 65 | +Related parameters are as follows: |
| 66 | + |
| 67 | +| Name | Description | Default Value | Effective Mode | Example | |
| 68 | +|---------------------| ----------------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------------- | ------------------------------------------------------------------- | |
| 69 | +| `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'` | |
| 70 | +| `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.*'` | |
| 71 | + |
| 72 | +## 4. Notes |
| 73 | + |
| 74 | +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. |
| 75 | +2. When the same IP appears in both the whitelist and blacklist, the blacklist takes precedence. |
| 76 | +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. |
| 77 | +4. Duplicate IPs in the configuration are supported; they are automatically deduplicated in memory without notification. For manual deduplication, edit the configuration accordingly. |
| 78 | +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. |
0 commit comments