Skip to content

Commit 165c89f

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 165c89f

File tree

2 files changed

+215
-0
lines changed

2 files changed

+215
-0
lines changed

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

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
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 with the following variables:
18+
| Variable | Default | Typical value for heavy logging | Description |
19+
|----------|---------|--------------------------------|-------------|
20+
| [audit_log_filter](audit-log-filter-variables.md#audit_log_filter) | OFF | ON | Master switch for the filter subsystem. |
21+
| [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. |
22+
| [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. |
23+
| [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). |
24+
| [audit_log_rotate_on_size](audit-log-filter-variables.md#audit_log_rotate_on_size) | 0 | 1 | Rotate the audit log file when it reaches `audit_log_buffer_size`. |
25+
| [audit_log_file](audit-log-filter-variables.md#audit_log_file) | `<datadir>/audit.log` | *unchanged* | Path of the audit log file (requires server restart to change). |
26+
27+
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`.
28+
29+
Only `audit_log_file` (the path) is static; changing this variable requires a restart.
30+
31+
## Rule precedence
32+
33+
* User-Specific Filter Wins: A specific user filter set with `audit_log_filter_set_user` always takes precedence over the wildcard (`%`) filter.
34+
35+
* 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 `%`.
36+
37+
* 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.
38+
39+
### Global system control
40+
41+
* The global variable, `audit_log_filter`, can enable or disable the entire auditing subsystem but does not affect the internal precedence logic of individual user filters.
42+
43+
## Use case requirements
44+
45+
The following requirements define the audit logging behavior:
46+
47+
For user % (wildcard/general users):
48+
49+
* Log SELECT operations
50+
51+
* Log INSERT operations
52+
53+
* Log UPDATE operations
54+
55+
* Log DELETE operations
56+
57+
* Log TRUNCATE operations
58+
59+
* Log CREATE operations
60+
61+
* Log DROP operations
62+
63+
* Log ALTER operations
64+
65+
* Log connection events (successful and failed)
66+
67+
* Log disconnection events
68+
69+
For user monitor:
70+
71+
* Log no events (completely disable logging)
72+
73+
## Implementation
74+
75+
Create and apply the audit log filters using the following configuration:
76+
77+
```sql
78+
-- Define a custom filter for comprehensive logging
79+
SET @log_custom_filter = '{
80+
"filter": {
81+
"class": [
82+
{
83+
"name": "connection",
84+
"event": [
85+
{ "name": "connect" },
86+
{ "name": "disconnect" },
87+
{ "name": "error" } /* captures failed login attempts */
88+
]
89+
},
90+
{
91+
"name": "general",
92+
"event": [
93+
{
94+
"name": "status",
95+
"log": {
96+
"or": [
97+
{ "field": { "name": "general_sql_command.str", "value": "select" } },
98+
{ "field": { "name": "general_sql_command.str", "value": "insert" } },
99+
{ "field": { "name": "general_sql_command.str", "value": "update" } },
100+
{ "field": { "name": "general_sql_command.str", "value": "delete" } },
101+
{ "field": { "name": "general_sql_command.str", "value": "truncate" } },
102+
{ "field": { "name": "general_sql_command.str", "value": "create" } }, /* DDL fix */
103+
{ "field": { "name": "general_sql_command.str", "value": "alter" } }, /* DDL fix */
104+
{ "field": { "name": "general_sql_command.str", "value": "drop" } } /* DDL fix */
105+
]
106+
}
107+
}
108+
]
109+
}
110+
]
111+
}
112+
}';
113+
114+
-- Define a filter that disables logging
115+
SET @log_none_filter = '{
116+
"filter": { "log": false }
117+
}';
118+
119+
-- Apply filters to specific users
120+
SELECT audit_log_filter_set_filter('log_custom', @log_custom_filter);
121+
SELECT audit_log_filter_set_filter('log_none', @log_none_filter);
122+
123+
-- Set user-specific audit logging rules
124+
SELECT audit_log_filter_set_user('%', 'log_custom');
125+
SELECT audit_log_filter_set_user('monitor@%', 'log_none');
126+
```
127+
128+
## Filter configuration details
129+
130+
The configuration uses two distinct filter types:
131+
132+
* Comprehensive logging filter: Captures connection events and specific SQL operations for general users
133+
* No logging filter: Completely disables audit logging for monitoring users
134+
135+
The filter applies to users matching the specified patterns:
136+
137+
* `%` matches all users (wildcard pattern)
138+
139+
* `monitor@%` matches users with the monitor username from any host
140+
141+
## Testing and validation
142+
143+
Verify that the audit log filters work correctly by performing these tests:
144+
145+
```sql
146+
-- Check that filters are applied correctly
147+
SELECT audit_log_filter_set_user('testuser@localhost', 'log_custom');
148+
SELECT audit_log_filter_set_user('monitor@localhost', 'log_none');
149+
150+
-- Verify filter assignments
151+
SELECT * FROM mysql.audit_log_filter;
152+
SELECT * FROM mysql.audit_log_user;
153+
```
154+
155+
Test the configuration by:
156+
* Connecting as a general user and performing various SQL operations
157+
158+
* Connecting as a monitor user and performing operations
159+
160+
* Checking the audit log file for expected entries
161+
162+
## Troubleshooting
163+
164+
Common issues and solutions:
165+
166+
167+
| Issue | Description |
168+
|-------------------------------|----------------------------------------------------------------------------------------------|
169+
| Filter not applied | Verify that the audit log plugin is enabled and the filter names are correct |
170+
| Unexpected logging | Check user pattern matching and filter precedence rules |
171+
| Performance impact | Monitor system performance when comprehensive logging is enabled |
172+
173+
174+
## Configuration Breakdown
175+
176+
| Filter Type | Description | Key Characteristics |
177+
|------------|-------------|---------------------|
178+
| <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 |
179+
| <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 |
180+
| <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 |
181+
182+
## Security considerations
183+
184+
When configuring audit log filters:
185+
186+
* Review filter rules regularly to ensure they meet security requirements
187+
188+
* Consider the impact of comprehensive logging on system performance
189+
190+
* Ensure that monitoring users cannot bypass audit logging through filter manipulation
191+
192+
* Document all filter changes for compliance and auditing purposes
193+
194+
## Performance impact
195+
196+
Comprehensive audit logging affects system performance:
197+
198+
* Each logged event requires disk I/O operations
199+
200+
* Large numbers of concurrent users increase logging overhead
201+
202+
* Consider log rotation and cleanup strategies for long-term operation
203+
204+
## Best practices
205+
206+
* Always align audit filters with specific security and compliance requirements
207+
208+
* Regularly review and update audit logging configurations
209+
210+
* Use the principle of least privilege when defining logging scopes
211+
212+
* Test filter configurations in a development environment before applying to production
213+
214+
* 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)