Skip to content

Commit f877171

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 f877171

File tree

2 files changed

+217
-0
lines changed

2 files changed

+217
-0
lines changed

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

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
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 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.
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+
-- Define a filter that disables logging
117+
SET @log_none_filter = '{
118+
"filter": { "log": false }
119+
}';
120+
121+
-- Apply filters to specific users
122+
SELECT audit_log_filter_set_filter('log_custom', @log_custom_filter);
123+
SELECT audit_log_filter_set_filter('log_none', @log_none_filter);
124+
125+
-- Set user-specific audit logging rules
126+
SELECT audit_log_filter_set_user('%', 'log_custom');
127+
SELECT audit_log_filter_set_user('monitor@%', 'log_none');
128+
```
129+
130+
## Filter configuration details
131+
132+
The configuration uses two distinct filter types:
133+
134+
* Comprehensive logging filter: Captures connection events and specific SQL operations for general users
135+
* No logging filter: Completely disables audit logging for monitoring users
136+
137+
The filter applies to users matching the specified patterns:
138+
139+
* `%` matches all users (wildcard pattern)
140+
141+
* `monitor@%` matches users with the monitor username from any host
142+
143+
## Testing and validation
144+
145+
Verify that the audit log filters work correctly by performing these tests:
146+
147+
```sql
148+
-- Check that filters are applied correctly
149+
SELECT audit_log_filter_set_user('testuser@localhost', 'log_custom');
150+
SELECT audit_log_filter_set_user('monitor@localhost', 'log_none');
151+
152+
-- Verify filter assignments
153+
SELECT * FROM mysql.audit_log_filter;
154+
SELECT * FROM mysql.audit_log_user;
155+
```
156+
157+
Test the configuration by:
158+
* Connecting as a general user and performing various SQL operations
159+
160+
* Connecting as a monitor user and performing operations
161+
162+
* Checking the audit log file for expected entries
163+
164+
## Troubleshooting
165+
166+
Common issues and solutions:
167+
168+
169+
| Issue | Description |
170+
|-------------------------------|----------------------------------------------------------------------------------------------|
171+
| Filter not applied | Verify that the audit log plugin is enabled and the filter names are correct |
172+
| Unexpected logging | Check user pattern matching and filter precedence rules |
173+
| Performance impact | Monitor system performance when comprehensive logging is enabled |
174+
175+
176+
## Configuration Breakdown
177+
178+
| Filter Type | Description | Key Characteristics |
179+
|------------|-------------|---------------------|
180+
| <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 |
181+
| <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 |
182+
| <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 |
183+
184+
## Security considerations
185+
186+
When configuring audit log filters:
187+
188+
* Review filter rules regularly to ensure they meet security requirements
189+
190+
* Consider the impact of comprehensive logging on system performance
191+
192+
* Ensure that monitoring users cannot bypass audit logging through filter manipulation
193+
194+
* Document all filter changes for compliance and auditing purposes
195+
196+
## Performance impact
197+
198+
Comprehensive audit logging affects system performance:
199+
200+
* Each logged event requires disk I/O operations
201+
202+
* Large numbers of concurrent users increase logging overhead
203+
204+
* Consider log rotation and cleanup strategies for long-term operation
205+
206+
## Best practices
207+
208+
* Always align audit filters with specific security and compliance requirements
209+
210+
* Regularly review and update audit logging configurations
211+
212+
* Use the principle of least privilege when defining logging scopes
213+
214+
* Test filter configurations in a development environment before applying to production
215+
216+
* 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)