Skip to content

Commit 8289ff9

Browse files
patrickbirchpatrickbirch
authored
Merge pull request #573 from percona/ps-10191-8.0
PS-10191 [DOCS] - Update Audit Log Filter installation instructions f…
2 parents 60d6552 + f0d8575 commit 8289ff9

File tree

2 files changed

+200
-42
lines changed

2 files changed

+200
-42
lines changed

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

Lines changed: 84 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,54 @@
11
# Audit Log Filter overview
22

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.
3+
The Audit Log Filter plugin provides comprehensive database auditing capabilities for Percona Server. The plugin allows you to monitor, log, and block connections or queries actively executed on the selected server.
4+
5+
## What is audit log filter?
6+
7+
The Audit Log Filter plugin enables you to:
8+
9+
| Issue | Description |
10+
|:----------------------|:----------------------------------------------------------------------------------------------|
11+
| Monitor database activity | Track all database connections, queries, and administrative actions |
12+
| Comply with regulations | Meet compliance requirements for database auditing |
13+
| Enhance security | Detect suspicious activities and unauthorized access attempts |
14+
| Control access | Block specific queries or connections based on configurable rules |
15+
| Generate reports | Create detailed audit trails for security analysis |
416

517
## What the plugin does
618

7-
The plugin monitors server activity and creates detailed log files containing information about:
19+
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. When you change the database, you must create the required tables in the new database and migrate any existing filter data.
820

921
* Database connections and disconnections
1022

11-
* SQL statements executed by users
23+
## System requirements
24+
25+
* Percona Server version: 8.0.34-26 or later
26+
27+
* Storage engine: InnoDB (for audit tables)
28+
29+
* Privileges: SYSTEM_VARIABLES_ADMIN to configure the plugin
30+
31+
* Disk space: Sufficient space for audit log files
32+
33+
* Memory: Additional memory overhead for audit processing
34+
35+
## Basic configuration
36+
37+
The Audit Log Filter plugin uses several key configuration variables:
38+
39+
* Dynamic variables: Can be changed at runtime using `SET GLOBAL` without restarting the server
40+
41+
* Read-only variables: Can only be changed at server startup in the configuration file
42+
43+
* [`audit_log_filter_enable`](audit-log-filter-variables.md#audit_log_filter_enable): Enable or disable the audit filter engine (dynamic)
44+
45+
* [`audit_log_filter_database`](audit-log-filter-variables.md#audit_log_filter_database): Database for storing filter definitions (read-only)
46+
47+
* [`audit_log_filter_mode`](audit-log-filter-variables.md#audit_log_filter_mode): Set to ALLOW (whitelist) or DENY (blacklist) (dynamic)
48+
49+
* [`audit_log_filter_rotate_on_size`](audit-log-filter-variables.md#audit_log_filter_rotate_on_size): Log file rotation size limit (dynamic)
50+
51+
## Privileges
1252

1353
* Database objects accessed
1454

@@ -92,31 +132,56 @@ The Audit Log Filter plugin is the successor to the [audit log plugin](audit-log
92132

93133
## Audit Log Filter tables
94134

95-
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.
135+
The Audit Log Filter plugin uses `mysql` system database tables in the `InnoDB` storage engine. These tables store user account data and filter data.
96136

97137
The `audit_log_filter` table stores the definitions of the filters and has the following column definitions:
98138

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 |
139+
| Column name | Description |
140+
|:-----------:|:-----------:|
141+
| NAME | Name of the filter |
142+
| FILTER | Definition of the filter linked to the name as a JSON value |
103143

104144
The `audit_log_user` table stores account data and has the following column definitions:
105145

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 |
146+
| Column name | Description |
147+
|:-----------:|:-----------:|
148+
| USER | The account name of the user |
149+
| HOST | The account name of the host |
150+
| FILTERNAME | The account filter name |
151+
152+
## Log formats and output
153+
154+
The Audit Log Filter plugin supports multiple log formats:
155+
156+
* JSON format: Machine-readable format for automated processing
157+
158+
* XML (new): Human-readable format with structured data
159+
160+
* XML (old): Legacy XML format for backward compatibility
161+
162+
The plugin logs various types of events:
163+
164+
* Connection events: User logins, logouts, and connection failures
165+
166+
* Query events: SQL statements executed by users
167+
168+
* Administrative events: Server configuration changes
111169

112-
## Next steps
170+
* Error events: Failed operations and security violations
113171

114-
To get started with the Audit Log Filter plugin:
172+
## Security considerations
115173

116-
1. [Install the Audit Log Filter](install-audit-log-filter.md) - Installation instructions
174+
When implementing the Audit Log Filter plugin, consider these security aspects:
117175

118-
2. [Filter Audit Log Files](filter-audit-log-filter-files.md) - Creating and managing filters
176+
| Issue | Description |
177+
|:--------------------|:----------------------------------------------------------------------------------------------|
178+
| Performance impact | Audit logging adds overhead to database operations |
179+
| Storage requirements | Audit logs can grow large; plan for log rotation and archival |
180+
| Sensitive data | Configure filters to avoid logging sensitive information |
181+
| Access control | Restrict access to audit log files and configuration |
182+
| Backup strategy | Include audit logs in your backup and recovery procedures |
183+
## References
119184

120-
3. [Audit Log Filter Variables](audit-log-filter-variables.md) - Configuration options
185+
[Install the Audit Log Filter](install-audit-log-filter.md)
121186

122-
4. [Manage Audit Log Files](manage-audit-log-filter.md) - Log file management
187+
[Audit Log Filter Variables & Functions](audit-log-filter-variables.md)

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

Lines changed: 116 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,133 @@
11
# Install the Audit Log Filter
22

3-
The `plugin_dir` system variable defines the plugin library location. If needed, at server startup, set the `plugin_dir` variable.
3+
## Installation script
44

5-
When upgrading a MySQL installation, plugins are not automatically upgraded. You may need to manually load the plugin after the MySQL upgrade.
5+
The recommended way to install the plugin is to use the `audit_log_filter_linux_install.sql` script, located in the share directory, which creates the required tables before installing the plugin.
66

7-
In the `share` directory, locate the `audit_log_filter_linux_install.sql `script.
7+
### Prerequisites
88

9-
Implemented in 8.0.34, at the time you run the script, you can select the database used to store the JSON filter tables.
9+
The `plugin_dir` system variable defines the plugin library location. When you need a custom location, set the `plugin_dir` variable at server startup.
1010

11-
* If the plugin is loaded, the installation script takes the database name from the `audit_log_filter_database` variable
12-
* If the plugin is not loaded, but passes the `-D db_name` to the mysql client when the installation script runs, uses the `db_name`.
13-
* If the plugin is not loaded and the `-D` option is not provided, the installation script creates the required tables in the default database name `mysql`.
11+
### Database selection
1412

15-
You can also designate a different database with the `audit_log_filter_database` system variable. The database name cannot be NULL or exceed 64 characters. If the database name is invalid, the audit log filter tables are not found.
13+
The script determines the target database using the following priority:
1614

17-
With 8.0.34 and higher, use this command:
15+
1. When the plugin is already loaded, the script uses the database name from the `audit_log_filter_database` variable
1816

17+
2. When the plugin is not loaded, but you pass the `-D db_name` option to the mysql client when running the script, the script uses the specified `db_name`
1918

20-
```{.bash data-prompt="$"}
21-
$ mysql -u -D database -p < audit_log_filter_linux_install.sql
19+
3. When the plugin is not loaded and no `-D` option is provided, you must specify the `mysql` database when running the script
20+
21+
You can also designate a different database with the `audit_log_filter_database` system variable. The database name cannot be NULL or exceed 64 characters. When the database name is invalid, the audit log filter tables are not found.
22+
23+
### Install the component
24+
25+
To install the plugin using the script, you must specify the `mysql` database. You can do this in two ways:
26+
27+
Option 1: Run the script from the command line with the `-D mysql` option:
28+
29+
```bash
30+
mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql
31+
```
32+
33+
Option 2: Connect to `mysql` database and run the script interactively:
34+
35+
```sql
36+
mysql> use mysql;
37+
mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql;
38+
```
39+
40+
Replace `/path/to/mysql/share/` with the actual path to your MySQL installation's share directory.
41+
42+
### Verify installation
43+
44+
After you run the script, verify that the required tables are created:
45+
46+
```sql
47+
mysql> show tables in mysql like 'aud%';
48+
```
49+
50+
Expected output:
51+
52+
```
53+
+------------------------+
54+
| Tables_in_mysql (aud%) |
55+
+------------------------+
56+
| audit_log_filter |
57+
| audit_log_user |
58+
+------------------------+
59+
2 rows in set (0.00 sec)
60+
```
61+
62+
## Alternative: INSTALL PLUGIN method
63+
64+
You can also install the plugin using the `INSTALL PLUGIN` command, but this method does not create the required tables and will cause filter operations to fail.
65+
66+
### Verify plugin installation
67+
68+
Check that the plugin is properly installed:
69+
70+
```sql
71+
mysql> SHOW PLUGINS LIKE 'audit_log_filter';
72+
```
73+
74+
Expected output:
75+
76+
```
77+
+-------------------+----------+--------------------+
78+
| Name | Status | Type |
79+
+-------------------+----------+--------------------+
80+
| audit_log_filter | ACTIVE | AUDIT |
81+
+-------------------+----------+--------------------+
82+
1 row in set (0.00 sec)
83+
```
84+
85+
### Test filter functionality
86+
87+
Test that the audit log filter is working correctly:
88+
89+
```sql
90+
mysql> SELECT audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}');
91+
```
92+
93+
Expected output:
94+
95+
```
96+
+---------------------------------------------------------------------+
97+
| audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}') |
98+
+---------------------------------------------------------------------+
99+
| ERROR: Failed to check filtering rule name existence |
100+
+---------------------------------------------------------------------+
101+
1 row in set (0.00 sec)
22102
```
23103

24-
To verify the plugin installation, run the following command:
104+
!!! note
105+
106+
This error occurs when the plugin is installed without the required tables. Using the SQL script prevents this issue.
25107

26-
```{.bash data-prompt="mysql>"}
27-
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'audit%';
108+
### Fix missing tables
109+
110+
When you have already installed the audit log plugin but are missing the required tables, you can run the `audit_log_filter_linux_install.sql` script to create the audit tables in the `mysql` database:
111+
112+
```bash
113+
mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql
28114
```
29115

30-
??? example "Expected output"
116+
Or interactively:
117+
118+
```sql
119+
mysql> use mysql;
120+
mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql;
121+
```
122+
123+
This operation creates the missing tables without reinstalling the plugin.
124+
125+
## Additional information
126+
127+
For information about upgrading the audit log filter plugin, see the upgrade documentation.
128+
129+
## References
31130

32-
```text
33-
+--------------------+---------------+
34-
| PLUGIN_NAME | PLUGIN_STATUS |
35-
+--------------------+---------------+
36-
| audit_log_filter | ACTIVE |
37-
+--------------------+---------------+
38-
```
131+
[Audit Log Filter Overview](audit-log-filter-overview.md)
39132

40-
After the installation, you can use the `--audit_log_filter` option when restarting the server. To prevent the server from not running the plugin use `--audit_log_filter` with either the `FORCE` or the `FORCE_PLUS_PERMANENT` values.
133+
[Audit Log Filter Variables & Functions](audit-log-filter-variables.md)

0 commit comments

Comments
 (0)