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 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.

Both blacklists and whitelists support IPv4 addresses, exact IPv6 addresses, and IPv4/IPv6 CIDR subnets, while retaining the existing IPv4 asterisk (*) wildcard capability.

Note: Blacklists and whitelists are available from V2.0.6.1.

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

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 IP addresses/subnets. Supports exact matching; separate multiple entries with commas. Supports IPv4/IPv6 addresses, CIDR subnets, and compatible IPv4 asterisk wildcards. IPv4 prefix lengths range from 0–32 and IPv6 from 0–128. IPv6 supports full, compressed, and mixed-case forms. IPv4-mapped IPv6 addresses (such as ::ffff:192.0.2.10) follow IPv6 rules. Multiple entry types can be mixed. IPv6 addresses and IPv4/IPv6 CIDR subnets are supported from V2.0.12.1.	empty	Hot reload	set configuration white_ip_list='127.0.0.1,::1,192.168.32.0/24,2001:db8:200::/48' IPv4 asterisk wildcard compatibility: set configuration 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 configurationstatement.
  • Tree model reference:set configuration

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 IP addresses/subnets. Supports exact matching; separate multiple entries with commas. Supports IPv4/IPv6 addresses, CIDR subnets, and compatible IPv4 asterisk wildcards. IPv4 prefix lengths range from 0–32 and IPv6 from 0–128. IPv6 supports full, compressed, and mixed-case forms. IPv4-mapped IPv6 addresses (such as ::ffff:192.0.2.10) follow IPv6 rules. Multiple entry types can be mixed. IPv6 addresses and IPv4/IPv6 CIDR subnets are supported from V2.0.12.1.	empty	Hot reload	set configuration black_ip_list='192.0.2.10,2001:db8:bad::/48' IPv4 asterisk wildcard compatibility: set configuration black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*'

4. Notes

1. IPv6 addresses support full, compressed, and mixed-case forms. For example, 2001:0db8:0000:0000:0000:0000:0000:0001, 2001:db8::1, and 2001:DB8::1 denote the same address. :: can appear at most once in a single IPv6 address. An exact IPv6 address can omit the prefix or explicitly use /128; for example, 2001:db8:200::bad and 2001:db8:200::bad/128 both identify one address.

2. CIDR prefix lengths range from /0 to /32 for IPv4 and /0 to /128 for IPv6. Canonical network addresses with zero host bits are recommended, for example 2001:db8:200::/64. For CIDR addresses with nonzero host bits, the system follows the normalization or strict rejection policy configured in the final product.

3. IPv4 and IPv6 rules match within their own address family and do not automatically match across families. For example, 192.0.2.10 does not automatically match ::ffff:192.0.2.10. To allow both connection addresses, configure both: white_ip_list=192.0.2.10,::ffff:192.0.2.10.

4. Blacklists and whitelists support only individual IP addresses and CIDR subnets. Hostnames or DNS names (such as example.com), addresses with ports (such as [2001:db8::1]:6667), IPv6 asterisk wildcards (such as 2001:db8::*), and start/end address ranges (such as 2001:db8::1-2001:db8::ff) are invalid. When loading configuration files, the system should skip invalid entries and log errors while keeping other valid entries effective. If a set configuration statement includes an invalid entry, the command should fail and retain the previous valid configuration without clearing the whitelist. Error logs include the configuration item and invalid entry to help locate the problem.

5. After the whitelist is enabled, only matching clients can connect; an empty whitelist denies all connections. Add ::1 to the whitelist for local IPv6 loopback connections. For other local IPv6 addresses, add the corresponding address or subnet.

6. The blacklist takes precedence over the whitelist. Connections matching both are denied. Both configurations support hot reload; after rule updates, new connections and existing connections that no longer match are handled according to the existing product behavior.

7. Retain existing IPv4 asterisk wildcard examples and note that this capability applies only to IPv4. Use CIDR for IPv6 subnets, for example 2001:db8:200::/48; do not use * for address segments.

8. Duplicate IP entries are supported and automatically deduplicated in memory without notification. Edit the configuration manually if deduplication is required.

9. Blacklist/whitelist rules apply only to new connections. Existing connections established before the feature was enabled are unaffected; they are intercepted only upon subsequent reconnection.