Account Security

About 4 min

Account Security

TimechoDB protects database accounts through mechanisms such as password policies, login failure lockout, user connection quotas, and stale connection eviction. Unless otherwise specified, related parameters are configured in iotdb-system.properties.

The features described on this page are available starting from V2.0.11.1. For user, role, and permission management, see Authority Management.

1. Password Policy

1.1 Configuration Parameters

Parameter	Description
`enforce_strong_password`	Whether to enable the strong password policy. When enabled, the password must be 12~32 characters long and contain uppercase letters, lowercase letters, digits, and the special characters `!@#$%^&*()_+-=`. The password cannot be the same as the username.
`password_expiration_days`	Password validity period, in days. When the value is greater than 0, login is rejected after the password expires; before expiration, the login process prompts the password expiration time.
`password_reuse_interval_days`	Historical password restriction period, in days. When the value is greater than 0, recorded historical passwords cannot be reused within the restriction period.
`password_stale_warning_days`	Threshold for reminding that a password has not been changed for a long time, in days. The default value is `30`; a value less than or equal to 0 disables the reminder.

An already logged-in session is not immediately disconnected solely because the password has expired. For how related connections are handled when the password is actively changed, see 4.3 Deleting a User or Changing a Password.

1.2 Strong Password Example

After enforce_strong_password is enabled, weak passwords are rejected:

CREATE USER user1 'userpw';

An example that meets the strong password requirements:

CREATE USER user1 'User1@Password';

1.3 Password Expiration and Historical Password Restrictions

Once a password exceeds the password_expiration_days validity period, normal login is no longer possible. An already logged-in session is not kicked out due to password expiration. You can change the password via ALTER USER according to the login prompt. When changing the password, if the new password matches a historical password within the password_reuse_interval_days restriction period, the change is rejected.

1.4 Interactive Password Input

When starting the CLI, you can provide only the -pw parameter without supplying the password value directly. The CLI then reads the password interactively and hides the input:

./sbin/start-cli.sh -u user1 -pw

It is recommended to use this interactive method to enter the password to avoid saving it in the command history.

TimechoDB uses two-level login failure counting — "user" and "user + client IP" — to limit consecutive password attempts. After the threshold is reached, the account or the corresponding account/IP combination is temporarily locked. Existing connections are not affected.

2.1 Configuration Parameters

Parameter	Default Value	Description
`failed_login_attempts`	`5`	The maximum number of consecutive failed logins from the same address for the same user. `-1` disables this limit. When enabled, `failed_login_attempts_per_user` must also be enabled.
`failed_login_attempts_per_user`	`1000`	The maximum number of cumulative failed logins for the same user from any address. `-1` completely disables the user-level limit; `0` is adjusted to the minimum value `1`; a value greater than or equal to `1` indicates a custom threshold.
`password_lock_time_minutes`	`10`	The lock duration after the failure threshold is reached, in minutes.

The system supports the following two lockout modes:

Specified IP lockout (user + IP): After the same user consecutively fails from the same address and reaches failed_login_attempts, the combination of the user and the address is locked.
User global lockout (user): After the same user cumulatively fails from any address and reaches failed_login_attempts_per_user, the user is locked globally.

The root user and the security administrator in the separation-of-powers mode are not subject to the login failure lockout policy when logging in from the local machine.

2.2 Unlocking an Account

After the lock time expires, the system automatically releases the lock. The root user or the security administrator in the separation-of-powers mode can also manually unlock the account.

To release the global lock of a user:

ALTER USER <USERNAME> ACCOUNT UNLOCK;
eg: ALTER USER user1 ACCOUNT UNLOCK;

To release the lock of a user at a specified IP address:

ALTER USER <USERNAME> @ <IP ADDRESS> ACCOUNT UNLOCK;
eg: ALTER USER user1 @ '127.0.0.1' ACCOUNT UNLOCK;

3. User Connection Management

The system administrator can set the maximum and minimum number of concurrent connections for each user. After the maximum number of connections is reached, the system rejects new connections from that user; after the minimum number of connections is set, the system reserves the corresponding number of connection resources for that user to prevent them from being occupied by other users.

3.1 Setting the Number of Connections

Set the maximum number of concurrent connections:

ALTER USER username SET MAX_SESSION_PER_USER n;
eg: ALTER USER user3 SET MAX_SESSION_PER_USER 10;

Set the minimum number of concurrent connections:

ALTER USER username SET MIN_SESSION_PER_USER n;
eg: ALTER USER user3 SET MIN_SESSION_PER_USER 1;

Set the value to -1 to remove the corresponding limit:

ALTER USER user3 SET MAX_SESSION_PER_USER -1;
ALTER USER user3 SET MIN_SESSION_PER_USER -1;

3.2 Viewing Connection Configuration

Use the following statement to view users and their connection limits:

LIST USER;

In the result, MaxSessionPerUser and MinSessionPerUser indicate the maximum and minimum number of connections, respectively. A value of -1 means no limit.

+------+--------------+-----------------+-----------------+
|UserId|          User|MaxSessionPerUser|MinSessionPerUser|
+------+--------------+-----------------+-----------------+
|     0|          root|               -1|               -1|
| 10000|         user3|               10|                1|
+------+--------------+-----------------+-----------------+

3.3 Notes

After setting or modifying the user connection limit, it takes effect immediately without restarting the instance.
When the maximum or minimum number of connections is not set, the corresponding result is displayed as -1.
The total number of concurrent client connections of the system is controlled by dn_rpc_max_concurrent_client_num. The user-level connection configuration cannot exceed the system total connection limit.
In the separation-of-powers mode, the connection configuration permission is restricted by the administrator identity. For details, see the "Separation of Powers" feature.

4. Session Connection Management

TimechoDB may disconnect related connections in the following cases: the session idle time exceeds the limit, the blacklist/whitelist changes, the user is deleted, or the password is changed.

4.1 Idle Connection Eviction

You can use idle_session_timeout_in_minutes to limit the maximum continuous idle time allowed for a session. After the threshold is exceeded, the system automatically disconnects idle connections and reclaims resources.

Parameter	Data Type	Value Range	Default Value	Effective Mode
`idle_session_timeout_in_minutes`	Integer	`-1`, or a number of minutes greater than or equal to `1`	`-1`	Restart or hot reload

Value description:

-1: Disables automatic idle session timeout.
0: Automatically adjusted to the minimum value 1.
Greater than or equal to 1: The maximum continuous idle time allowed for a session, in minutes.

Configuration file example:

idle_session_timeout_in_minutes=10

Modify via SQL:

SET CONFIGURATION "idle_session_timeout_in_minutes" = "10";

4.2 Blacklist/Whitelist Update

After hot-reloading the blacklist/whitelist, the system disconnects existing connections that do not comply with the latest rules. For the configuration method of the blacklist/whitelist, see Black White List.

4.3 Deleting a User or Changing a Password

After a user is deleted or a user's password is changed, the system disconnects the user's existing connections. After the password is changed, the client needs to reconnect with the new password; after a user is deleted, the user cannot establish a connection again.