Skip to content

Commit f29db4f

Browse files
leto-bbqleto-bbq
authored
update audit log from 208 (#992)
1 parent 5366abe commit f29db4f

12 files changed

Lines changed: 844 additions & 254 deletions

File tree

‎src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,7 @@ export const enSidebar = {
140140
children: [
141141
{ text: 'Authority Management', link: 'Authority-Management_timecho' },
142142
{ text: 'Black White List', link: 'Black-White-List_timecho' },
143+
{ text: 'Security Audit', link: 'Audit-Log_timecho' },
143144
],
144145
},
145146
{ text: 'Tiered Storage', link: 'Tiered-Storage_timecho' },

‎src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,6 @@ export const enSidebar = {
145145
{ text: 'Trigger', link: 'Trigger' },
146146
],
147147
},
148-
{ text: 'Tiered Storage', link: 'Tiered-Storage_timecho' },
149148
{ text: 'UDF', link: 'User-defined-function_timecho' },
150149
{ text: 'View', link: 'IoTDB-View_timecho' },
151150
{
@@ -157,6 +156,7 @@ export const enSidebar = {
157156
{ text: 'Security Audit', link: 'Audit-Log_timecho' },
158157
],
159158
},
159+
{ text: 'Tiered Storage', link: 'Tiered-Storage_timecho' },
160160
{
161161
text: 'System Maintenance',
162162
collapsible: true,

‎src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,7 @@ export const zhSidebar = {
131131
children: [
132132
{ text: '权限管理', link: 'Authority-Management_timecho' },
133133
{ text: '黑白名单', link: 'Black-White-List_timecho' },
134+
{ text: '安全审计', link: 'Audit-Log_timecho' },
134135
],
135136
},
136137
{ text: '多级存储', link: 'Tiered-Storage_timecho' },

‎src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,6 @@ export const zhSidebar = {
127127
{ text: '触发器', link: 'Trigger' },
128128
],
129129
},
130-
{ text: '多级存储', link: 'Tiered-Storage_timecho' },
131130
{ text: 'UDF', link: 'User-defined-function_timecho' },
132131
{ text: '视图', link: 'IoTDB-View_timecho' },
133132
{
@@ -139,6 +138,7 @@ export const zhSidebar = {
139138
{ text: '安全审计', link: 'Audit-Log_timecho' },
140139
],
141140
},
141+
{ text: '多级存储', link: 'Tiered-Storage_timecho' },
142142
{
143143
text: '系统运维',
144144
collapsible: true,

‎src/UserGuide/Master/Table/User-Manual/Audit-Log_timecho.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
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+
23+
# Security Audit
24+
25+
## 1. Introduction
26+
27+
Audit logs provide a documented record of database activities. Through the audit log feature, you can track operations like data creation, deletion, modification, and querying to ensure information security. IoTDB's audit log functionality supports the following features:
28+
29+
* Configurable enable/disable of audit logging
30+
* Configurable auditable operation types and privilege levels
31+
* Configurable audit log retention periods using TTL (time-based rolling) and SpaceTL (space-based rolling)
32+
* Default encryption storage for audit logs
33+
34+
> Note: This feature is available from version V2.0.8 onwards.
35+
36+
## 2. Configuration Parameters
37+
38+
Edit the `iotdb-system.properties` file to enable audit logging using the following parameters:
39+
40+
| Parameter Name | Description | Data Type | Default Value | Application Method |
41+
|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|----------------------------|--------------------|
42+
| `enable_audit_log` | Enable audit logging. true: enabled. false: disabled. | Boolean | false | Restart Required |
43+
| `auditable_operation_type` | Operation type selection. DML: All DML operations; DDL: All DDL operations; QUERY: All queries; CONTROL: All control statements; | String | DML,DDL,QUERY,CONTROL | Restart Required |
44+
| `auditable_operation_level` | Privilege level selection. global: Record all audit logs; object: Only record audit logs for data instances; Containment relationship: object < global. | String | global | Restart Required |
45+
| `auditable_operation_result` | Audit result selection. success: Only record successful events; fail: Only record failed events; | String | success, fail | Restart Required |
46+
| `audit_log_ttl_in_days` | Audit log TTL (Time To Live) in days. Logs older than this threshold will expire. | Double | -1.0 (never deleted) | Restart Required |
47+
| `audit_log_space_tl_in_GB` | Audit log SpaceTL in GB. When total audit log size exceeds this threshold, log rotation starts deleting oldest files. | Double | 1.0 | Restart Required |
48+
| `audit_log_batch_interval_in_ms` | Batch write interval for audit logs in milliseconds | Long | 1000 | Restart Required |
49+
| `audit_log_batch_max_queue_bytes` | Maximum queue size in bytes for batch processing audit logs. Subsequent writes will be blocked when queue exceeds this value. | Long | 268435456 | Restart Required |
50+
51+
## 3. Access Methods
52+
53+
Supports direct reading of audit logs via SQL.
54+
55+
### 3.1 SQL Syntax
56+
57+
```SQL
58+
SELECT (<audit_log_field>, )* log FROM <AUDIT_LOG_PATH> WHERE whereclause ORDER BY order_expression
59+
```
60+
61+
Where:
62+
63+
* `AUDIT_LOG_PATH`: Audit log storage location `__audit.audit_log`;
64+
* `audit_log_field`: Query fields refer to the metadata structure below
65+
* Supports WHERE clause filtering and ORDER BY sorting
66+
67+
### 3.2 Metadata Structure
68+
69+
| Field | Description | Data Type |
70+
|------------------------|--------------------------------------------------|----------------|
71+
| `time` | The date and time when the event started | timestamp |
72+
| `username` | User name | string |
73+
| `cli_hostname` | Client hostname identifier | string |
74+
| `audit_event_type` | Audit event type, e.g., WRITE_DATA, GENERATE_KEY| string |
75+
| `operation_type` | Operation type, e.g., DML, DDL, QUERY, CONTROL | string |
76+
| `privilege_type` | Privilege used, e.g., WRITE_DATA, MANAGE_USER | string |
77+
| `privilege_level` | Event privilege level, global or object | string |
78+
| `result` | Event result, success=1, fail=0 | boolean |
79+
| `database` | Database name | string |
80+
| `sql_string` | User's original SQL statement | string |
81+
| `log` | Detailed event description | string |
82+
83+
### 3.3 Usage Examples
84+
85+
* Query times, usernames and host information for successfully executed DML operations:
86+
87+
```SQL
88+
IoTDB:__audit> select time,username,cli_hostname from audit_log where result = true and operation_type='DML'
89+
+-----------------------------+--------+------------+
90+
| time|username|cli_hostname|
91+
+-----------------------------+--------+------------+
92+
|2026-01-23T11:43:46.697+08:00| root| 127.0.0.1|
93+
|2026-01-23T11:45:39.950+08:00| root| 127.0.0.1|
94+
+-----------------------------+--------+------------+
95+
Total line number = 2
96+
It costs 0.284s
97+
```
98+
99+
* Query latest operation details:
100+
101+
```SQL
102+
IoTDB:__audit> select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1
103+
+-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+
104+
| time|username|cli_hostname|operation_type| sql_string|
105+
+-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+
106+
|2026-01-23T11:46:31.026+08:00| root| 127.0.0.1| QUERY|select time,username,cli_hostname,operation_type,sql_string from audit_log order by time desc limit 1|
107+
+-----------------------------+--------+------------+--------------+------------------------------------------------------------------------------------------------------+
108+
Total line number = 1
109+
It costs 0.053s
110+
```
111+
112+
* Query failed operations:
113+
114+
```SQL
115+
IoTDB:__audit> select time,database,operation_type,log from audit_log where result=false
116+
+-----------------------------+--------+--------------+----------------------------------------------------------------------+
117+
| time|database|operation_type| log|
118+
+-----------------------------+--------+--------------+----------------------------------------------------------------------+
119+
|2026-01-23T11:47:42.136+08:00| | CONTROL|User user1 (ID=-1) login failed with code: 804, Authentication failed.|
120+
+-----------------------------+--------+--------------+----------------------------------------------------------------------+
121+
Total line number = 1
122+
It costs 0.011s
123+
```

0 commit comments

Comments
 (0)