Skip to content

Commit cf16bef

Browse files
patrickbirchpatrickbirch
committed
PS-10225 [DOCS] - Add Advanced Filter Configuration 8.0
 On branch ps-10225-8.0 new file: docs/advanced-audit-log-filter-example.md modified: mkdocs-base.yml
1 parent ffa7847 commit cf16bef

File tree

2 files changed

+251
-0
lines changed

2 files changed

+251
-0
lines changed

‎docs/advanced-audit-log-filter-example.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
# Advanced audit log filter configuration
2+
3+
## Overview
4+
5+
Audit log filtering controls which database events the audit log plugin records. This configuration example shows how to set up comprehensive logging for general users while completely disabling logging for monitoring users.
6+
7+
## Prerequisites
8+
9+
Before configuring audit log filters, ensure that:
10+
11+
* The audit log filter plugin is installed and enabled
12+
13+
* You have administrative privileges to configure audit log settings
14+
15+
* The audit log filter plugin has the necessary permissions to write log files
16+
17+
You can tune the audit log filter plugin using the following variables:
18+
19+
20+
| Variable | Default | Typical value for heavy logging | Description |
21+
|----------|---------|--------------------------------|-------------|
22+
| [audit-log-filter](audit-log-filter-variables.md#audit-log-filter) | OFF | ON | Master switch for the filter subsystem. |
23+
| [audit_log_filter_max_size](audit-log-filter-variables.md#audit_log_filter_max_size) | 0 (unlimited) | 1073741824 (1 GB) | Max size of the filter definition file; rotation occurs when exceeded. |
24+
| [audit_log_filter_prune_seconds](audit-log-filter-variables.md#audit_log_filter_prune_seconds) | 0 (no pruning) | 86400 (24 h) | Age after which old filter entries are pruned. |
25+
| [audit_log_filter_strategy](audit-log-filter-variables.md#audit_log_filter_strategy) | default | default | Determines how overlapping filters are resolved (keep‑first vs. most‑specific). |
26+
| [audit_log_filter_rotate_on_size](audit-log-filter-variables.md#audit_log_filter_rotate_on_size) | 0 | 1 | Rotate the audit log file when it reaches `audit_log_buffer_size`. |
27+
| [audit_log_filter_file](audit-log-filter-variables.md#audit_log_filter_file) | `<datadir>/audit.log` | *unchanged* | Path of the audit log file (requires server restart to change). |
28+
29+
Most of these variables in the table are dynamic system variables – you can view or change them at runtime with `SHOW GLOBAL VARIABLES / SET GLOBAL`.
30+
31+
Only `audit_log_file` (the path) is static; changing this variable requires a restart.
32+
33+
## Rule precedence
34+
35+
* User-Specific Filter Wins: A specific user filter set with `audit_log_filter_set_user` always takes precedence over the wildcard (`%`) filter.
36+
37+
* Most Specific Pattern Wins: If a user matches multiple connection patterns (e.g., `user@host`), the most specific pattern is applied. For example, `monitor@%` is applied instead of the less specific `%`.
38+
39+
* Last Call Wins: When a user has multiple filters attached using `audit_log_filter_set_user`, the filter from the last execution of that command is the one that is applied.
40+
41+
### Global system control
42+
43+
* The `audit-log-filter` global can enable or disable the auditing subsystem but does not affect the internal precedence logic of individual user filters.
44+
45+
## Use case requirements
46+
47+
The following requirements define the audit logging behavior:
48+
49+
For user % (wildcard/general users):
50+
51+
* Log SELECT operations
52+
53+
* Log INSERT operations
54+
55+
* Log UPDATE operations
56+
57+
* Log DELETE operations
58+
59+
* Log TRUNCATE operations
60+
61+
* Log CREATE operations
62+
63+
* Log DROP operations
64+
65+
* Log ALTER operations
66+
67+
* Log connection events (successful and failed)
68+
69+
* Log disconnection events
70+
71+
For user monitor:
72+
73+
* Log no events (completely disable logging)
74+
75+
## Implementation
76+
77+
Create and apply the audit log filters using the following configuration:
78+
79+
```sql
80+
-- Define a custom filter for comprehensive logging
81+
SET @log_custom_filter = '{
82+
"filter": {
83+
"class": [
84+
{
85+
"name": "connection",
86+
"event": [
87+
{ "name": "connect" },
88+
{ "name": "disconnect" },
89+
{ "name": "error" } /* captures failed login attempts */
90+
]
91+
},
92+
{
93+
"name": "general",
94+
"event": [
95+
{
96+
"name": "status",
97+
"log": {
98+
"or": [
99+
{ "field": { "name": "general_sql_command.str", "value": "select" } },
100+
{ "field": { "name": "general_sql_command.str", "value": "insert" } },
101+
{ "field": { "name": "general_sql_command.str", "value": "update" } },
102+
{ "field": { "name": "general_sql_command.str", "value": "delete" } },
103+
{ "field": { "name": "general_sql_command.str", "value": "truncate" } },
104+
{ "field": { "name": "general_sql_command.str", "value": "create" } }, /* DDL fix */
105+
{ "field": { "name": "general_sql_command.str", "value": "alter" } }, /* DDL fix */
106+
{ "field": { "name": "general_sql_command.str", "value": "drop" } } /* DDL fix */
107+
]
108+
}
109+
}
110+
]
111+
}
112+
]
113+
}
114+
}';
115+
```
116+
117+
```sql
118+
-- Verify JSON syntax before loading (optional but recommended)
119+
SELECT JSON_VALID(@log_custom_filter) AS is_valid;
120+
```
121+
122+
`JSON_VALID()` returns `1` if the string is valid JSON, `0` otherwise.
123+
124+
```sql
125+
-- Define a filter that disables logging
126+
SET @log_none_filter = '{
127+
"filter": { "log": false }
128+
}';
129+
```
130+
131+
```sql
132+
-- Define a filter that logs only specific SQL commands
133+
SET @log_custom_filter = '{
134+
"filter": {
135+
"log": true,
136+
"rules": [
137+
{
138+
"type": "sql",
139+
"conditions": [
140+
{ "field": { "name": "general_sql_command.str", "value": "select" } },
141+
{ "field": { "name": "general_sql_command.str", "value": "insert" } },
142+
{ "field": { "name": "general_sql_command.str", "value": "update" } },
143+
{ "field": { "name": "general_sql_command.str", "value": "delete" } },
144+
{ "field": { "name": "general_sql_command.str", "value": "create" } },
145+
{ "field": { "name": "general_sql_command.str", "value": "alter" } },
146+
{ "field": { "name": "general_sql_command.str", "value": "drop" } }
147+
]
148+
}
149+
]
150+
}
151+
}';
152+
```
153+
154+
```sql
155+
-- Apply filters to specific users
156+
SELECT audit_log_filter_set_filter('log_custom', @log_custom_filter);
157+
SELECT audit_log_filter_set_filter('log_none', @log_none_filter);
158+
159+
-- Set user-specific audit logging rules
160+
SELECT audit_log_filter_set_user('%', 'log_custom');
161+
SELECT audit_log_filter_set_user('monitor@%', 'log_none');
162+
```
163+
164+
## Filter configuration details
165+
166+
The configuration uses two distinct filter types:
167+
168+
* Comprehensive logging filter: Captures connection events and specific SQL operations for general users
169+
* No logging filter: Completely disables audit logging for monitoring users
170+
171+
The filter applies to users matching the specified patterns:
172+
173+
* `%` matches all users (wildcard pattern)
174+
175+
* `monitor@%` matches users with the monitor username from any host
176+
177+
## Testing and validation
178+
179+
Verify that the audit log filters work correctly by performing these tests:
180+
181+
```sql
182+
-- Check that filters are applied correctly
183+
SELECT audit_log_filter_set_user('testuser@localhost', 'log_custom');
184+
SELECT audit_log_filter_set_user('monitor@localhost', 'log_none');
185+
186+
-- Verify filter assignments
187+
SELECT * FROM mysql.audit_log_filter;
188+
SELECT * FROM mysql.audit_log_user;
189+
```
190+
191+
Test the configuration by:
192+
* Connecting as a general user and performing various SQL operations
193+
194+
* Connecting as a monitor user and performing operations
195+
196+
* Checking the audit log file for expected entries
197+
198+
## Troubleshooting
199+
200+
Common issues and solutions:
201+
202+
203+
| Issue | Description |
204+
|-------------------------------|----------------------------------------------------------------------------------------------|
205+
| Filter not applied | Verify that the audit log plugin is enabled and the filter names are correct |
206+
| Unexpected logging | Check user pattern matching and filter precedence rules |
207+
| Performance impact | Monitor system performance when comprehensive logging is enabled |
208+
209+
210+
## Configuration Breakdown
211+
212+
| Filter Type | Description | Key Characteristics |
213+
|------------|-------------|---------------------|
214+
| <b>Wildcard User Filter (`%`)</b> | Captures operations for general users | • Ensures <b>comprehensive auditing</b><br>• Applies to all users matching the wildcard<br>• Logs multiple SQL operation types |
215+
| <b>Monitor User Filter</b> | Logging control for specific users | • <b>Completely disables logging</b><br>• Provides granular user-level exclusion<br>• Prevents any audit trail for specified users |
216+
| <b>Flexible Matching</b> | User pattern-based filtering | • Uses `%` wildcard for broad rule application<br>• Enables dynamic user group configurations<br>• Simplifies management of similar user accounts |
217+
218+
## Security considerations
219+
220+
When configuring audit log filters:
221+
222+
* Review filter rules regularly to ensure they meet security requirements
223+
224+
* Consider the impact of comprehensive logging on system performance
225+
226+
* Ensure that monitoring users cannot bypass audit logging through filter manipulation
227+
228+
* Document all filter changes for compliance and auditing purposes
229+
230+
## Performance impact
231+
232+
Comprehensive audit logging affects system performance:
233+
234+
* Each logged event requires disk I/O operations
235+
236+
* Large numbers of concurrent users increase logging overhead
237+
238+
* Consider log rotation and cleanup strategies for long-term operation
239+
240+
## Best practices
241+
242+
* Always align audit filters with specific security and compliance requirements
243+
244+
* Regularly review and update audit logging configurations
245+
246+
* Use the principle of least privilege when defining logging scopes
247+
248+
* Test filter configurations in a development environment before applying to production
249+
250+
* Monitor audit log file sizes and implement appropriate rotation policies

‎mkdocs-base.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,7 @@ nav:
221221
- XML (New style): audit-log-filter-new.md
222222
- XML (Old style): audit-log-filter-old.md
223223
- JSON: audit-log-filter-json.md
224+
- advanced-audit-log-filter-example.md
224225
- audit-log-filter-security.md
225226
- audit-log-filter-compression-encryption.md
226227
- reading-audit-log-filter-files.md

0 commit comments

Comments
 (0)