Skip to content

Commit a1a4aeb

Browse files
patrickbirchpatrickbirch
authored
Merge pull request #574 from percona/ps-10192-8.0
PS-10192 - [DOCS] - Update Audit Log Filter overview …
2 parents ffa7847 + bd9cb2a commit a1a4aeb

File tree

1 file changed

+99
-108
lines changed

1 file changed

+99
-108
lines changed

‎docs/audit-log-filter-overview.md‎

Lines changed: 99 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,122 @@
11
# Audit Log Filter overview
22

3-
The Audit Log Filter plugin allows you to monitor, log, and block a connection or query actively executed on the selected server.
3+
The Audit Log Filter plugin provides security monitoring and access control for your MySQL server. The plugin allows you to monitor database activity, log specific events, and block connections or queries based on configurable rules.
44

5-
Enabling the plugin produces a log file that contains a record of server activity. The log file has information on connections and databases accessed by that connection.
5+
## What the plugin does
66

7-
The plugin uses the `mysql` system database to store filter and user account data. Set the [`audit_log_filter_database`](audit-log-filter-variables.md#audit_log_filter_database) variable at server startup to select a different database.
7+
The plugin monitors server activity and creates detailed log files containing information about:
88

9-
The `AUDIT_ADMIN` privilege is required to enable users to manage the Audit Log Filter plugin.
9+
* Database connections and disconnections
1010

11-
## Privileges
11+
* SQL statements executed by users
1212

13-
Define the privilege at runtime at the startup of the server. The associated Audit Log Filter privilege can be unavailable if the plugin is not enabled.
13+
* Database objects accessed
14+
15+
* User account activity
16+
17+
## How it works
18+
19+
The plugin uses the `mysql` system database to store filter configurations and user account assignments. You can change the database location by setting the [`audit_log_filter_database`](audit-log-filter-variables.md#audit_log_filter_database) variable at server startup.
20+
21+
## Required privileges
22+
23+
The `AUDIT_ADMIN` privilege is required to manage the Audit Log Filter plugin configuration. Define privileges at runtime at server startup. Audit Log Filter privileges may be unavailable if the plugin is not enabled.
1424

1525
### `AUDIT_ADMIN`
1626

17-
This privilege is defined by the server and enables the user to configure the plugin.
27+
This privilege is required to manage audit log filters and their configuration. Users with this privilege can create, modify, and remove filters, assign filters to user accounts, and perform other administrative operations.
28+
29+
Required for audit log filter functions such as:
30+
31+
* Creating and removing filters
32+
33+
* Assigning filters to user accounts
34+
35+
* Flushing filter configurations
36+
37+
* Managing audit log file rotation
1838

1939
### `AUDIT_ABORT_EXEMPT`
2040

21-
This privilege allows queries from a user account to always be executed. An `abort` item does not block them. This ability lets the user account regain access to a system if an audit is misconfigured. The query is logged due to the privilege. User accounts with the `SYSTEM_USER` privilege have the `AUDIT_ABORT_EXEMPT` privilege.
41+
This privilege allows queries from a user account to bypass blocking actions in audit log filters. When a filter is configured to block or deny queries, users with this privilege can still execute their queries successfully.
42+
43+
The privilege provides emergency access when audit filters are misconfigured and would otherwise block legitimate operations. Queries executed by users with this privilege are still logged for audit compliance.
44+
45+
User accounts with the `SYSTEM_USER` privilege automatically have the `AUDIT_ABORT_EXEMPT` privilege.
46+
47+
## Performance considerations
48+
49+
The Audit Log Filter plugin consumes system resources while running. Consider the following factors when enabling the plugin:
50+
51+
* CPU overhead: Filtering and logging operations require additional CPU cycles for each audited event
52+
53+
* Memory usage: The plugin uses memory for buffering log entries and maintaining filter configurations
54+
55+
* Disk I/O: Log file writes create additional disk activity, especially on high-traffic systems
56+
57+
* Storage requirements: Audit log files can grow large and consume significant disk space over time
58+
59+
* Network impact: If logging to remote systems, network bandwidth usage increases
60+
61+
* Complex filtering: Queries that monitor multiple events and users consume more resources than simple filters
62+
63+
Monitor system performance after enabling the plugin and adjust filter configurations or log rotation settings as needed to maintain acceptable performance levels.
64+
65+
## Complex filtering considerations
66+
67+
The Audit Log Filter plugin supports sophisticated filtering rules that can monitor multiple criteria simultaneously. However, complex filters require more processing power:
68+
69+
* Multiple event types: Filters that check for several event classes (connection, query, table access) use more CPU cycles
70+
71+
* Multiple user accounts: Monitoring many users simultaneously increases memory usage and processing time
72+
73+
* Nested conditions: JSON filters with multiple nested conditions require more evaluation time
74+
75+
* Real-time evaluation: Each query must be evaluated against all active filters, so more filters mean more overhead
76+
77+
Start with simple filters and gradually add complexity while monitoring performance impact.
78+
79+
## Comparison with audit log plugin
80+
81+
The Audit Log Filter plugin is the successor to the [audit log plugin](audit-log-plugin.md) and provides significant improvements:
82+
83+
* Enhanced filtering: More granular control over what gets logged and when
84+
85+
* Blocking capabilities: Can block queries and connections, not just log them
86+
87+
* JSON configuration: More flexible filter definitions using JSON format
88+
89+
* Multiple output formats: Supports XML and JSON log formats
90+
91+
* Advanced features: Compression, encryption, and remote logging capabilities
2292

2393
## Audit Log Filter tables
2494

2595
The Audit Log Filter plugin uses `mysql` system database tables in the `InnoDB` storage engine. These tables store user account data and filter data. When you start the server, change the plugin's database with the `audit_log_filter_database` variable.
2696

2797
The `audit_log_filter` table stores the definitions of the filters and has the following column definitions:
2898

29-
<!DOCTYPE html>
30-
<html>
31-
<head>
32-
<title>HTML Table Generator</title>
33-
<style>
34-
#demTable {
35-
width:100%;
36-
height:100%;
37-
border:1px solid #b3adad;
38-
border-collapse:collapse;
39-
padding:5px;
40-
}
41-
#demTable th {
42-
border:1px solid #b3adad;
43-
padding:5px;
44-
background: #f0f0f0;
45-
color: #313030;
46-
}
47-
#demTable td {
48-
border:1px solid #b3adad;
49-
text-align:left;
50-
padding:5px;
51-
background: #ffffff;
52-
color: #313030;
53-
}
54-
</style>
55-
</head>
56-
<body>
57-
<table id="demTable">
58-
<thead>
59-
<tr>
60-
<th><div style="color: #333333;background-color: #f5f5f5;font-family: Menlo, Monaco, 'Courier New', monospace;font-weight: normal;font-size: 14px;line-height: 21px;white-space: pre;">Column name</div></th>
61-
<th><div style="color: #333333;background-color: #f5f5f5;font-family: Menlo, Monaco, 'Courier New', monospace;font-weight: normal;font-size: 14px;line-height: 21px;white-space: pre;">Description</div></th>
62-
</tr>
63-
</thead>
64-
<tbody>
65-
<tr>
66-
<td>&nbsp;NAME</td>
67-
<td>&nbsp;Name of the filter</td>
68-
</tr>
69-
<tr>
70-
<td>&nbsp;FILTER</td>
71-
<td>&nbsp;Definition of the filter linked to the name as a JSON value</td>
72-
</tr>
73-
</tbody>
74-
</table>
75-
</body>
76-
</html>
99+
| Column name | Data type | Description |
100+
|-------------|-----------|-------------|
101+
| NAME | VARCHAR(64) | Name of the filter |
102+
| FILTER | JSON | Definition of the filter linked to the name as a JSON value |
77103

78104
The `audit_log_user` table stores account data and has the following column definitions:
79105

80-
<!DOCTYPE html>
81-
<html>
82-
<head>
83-
<title>HTML Table Generator</title>
84-
<style>
85-
#demTable {
86-
width:100%;
87-
height:100%;
88-
border:1px solid #b3adad;
89-
border-collapse:collapse;
90-
padding:5px;
91-
}
92-
#demTable th {
93-
border:1px solid #b3adad;
94-
padding:5px;
95-
background: #f0f0f0;
96-
color: #313030;
97-
}
98-
#demTable td {
99-
border:1px solid #b3adad;
100-
text-align:left;
101-
padding:5px;
102-
background: #ffffff;
103-
color: #313030;
104-
}
105-
</style>
106-
</head>
107-
<body>
108-
<table id="demTable">
109-
<thead>
110-
<tr>
111-
<th><div style="color: #333333;background-color: #f5f5f5;font-family: Menlo, Monaco, 'Courier New', monospace;font-weight: normal;font-size: 14px;line-height: 21px;white-space: pre;">Column name</div></th>
112-
<th><div style="color: #333333;background-color: #f5f5f5;font-family: Menlo, Monaco, 'Courier New', monospace;font-weight: normal;font-size: 14px;line-height: 21px;white-space: pre;">Description</div></th>
113-
</tr>
114-
</thead>
115-
<tbody>
116-
<tr>
117-
<td>&nbsp;USER</td>
118-
<td>&nbsp;The account name of the user</td>
119-
</tr>
120-
<tr>
121-
<td>&nbsp;HOST</td>
122-
<td>&nbsp;The account name of the host</td>
123-
</tr>
124-
<tr>
125-
<td>&nbsp;FILTERNAME</td>
126-
<td>&nbsp;The account filter name</td>
127-
</tr>
128-
</tbody>
129-
</table>
130-
</body>
131-
</html>
106+
| Column name | Data type | Description |
107+
|-------------|-----------|-------------|
108+
| USER | VARCHAR(32) | The account name of the user |
109+
| HOST | VARCHAR(255) | The account name of the host |
110+
| FILTERNAME | VARCHAR(64) | The account filter name |
111+
112+
## Next steps
113+
114+
To get started with the Audit Log Filter plugin:
115+
116+
1. [Install the Audit Log Filter](install-audit-log-filter.md) - Installation instructions
117+
118+
2. [Filter Audit Log Files](filter-audit-log-filter-files.md) - Creating and managing filters
119+
120+
3. [Audit Log Filter Variables](audit-log-filter-variables.md) - Configuration options
121+
122+
4. [Manage Audit Log Files](manage-audit-log-filter.md) - Log file management

0 commit comments

Comments
 (0)