You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 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.
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.
6
18
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.
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.
8
20
9
21
The `AUDIT_ADMIN` privilege is required to enable users to manage the Audit Log Filter plugin.
10
22
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)
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.
@@ -22,110 +62,56 @@ This privilege allows queries from a user account to always be executed. An `abo
22
62
23
63
## Audit Log Filter tables
24
64
25
-
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.
65
+
The Audit Log Filter plugin uses `mysql` system database tables in the `InnoDB` storage engine. These tables store user account data and filter data.
26
66
27
67
The `audit_log_filter` table stores the definitions of the filters and has the following column definitions:
The `plugin_dir` system variable defines the plugin library location. If needed, at server startup, set the `plugin_dir` variable.
3
+
## Installation script
4
4
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.
6
6
7
-
In the `share` directory, locate the `audit_log_filter_linux_install.sql `script.
7
+
### Prerequisites
8
8
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.
10
10
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
14
12
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:
16
14
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
16
+
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`
17
+
3. When the plugin is not loaded and no `-D` option is provided, you must specify the `mysql` database when running the script
18
18
19
+
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.
19
20
20
-
```{.bash data-prompt="$"}
21
-
$ mysql -u -D database -p < audit_log_filter_linux_install.sql
21
+
### Install the component
22
+
23
+
To install the plugin using the script, you must specify the `mysql` database. You can do this in two ways:
24
+
25
+
Option 1: Run the script from the command line with the `-D mysql` option:
26
+
27
+
```bash
28
+
mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql
29
+
```
30
+
31
+
Option 2: Connect to `mysql` database and run the script interactively:
Replace `/path/to/mysql/share/` with the actual path to your MySQL installation's share directory.
39
+
40
+
### Verify installation
41
+
42
+
After you run the script, verify that the required tables are created:
43
+
44
+
```sql
45
+
mysql> show tables in mysql like'aud%';
46
+
```
47
+
48
+
Expected output:
49
+
50
+
```
51
+
+------------------------+
52
+
| Tables_in_mysql (aud%) |
53
+
+------------------------+
54
+
| audit_log_filter |
55
+
| audit_log_user |
56
+
+------------------------+
57
+
2 rows in set (0.00 sec)
58
+
```
59
+
60
+
## Alternative: INSTALL PLUGIN method
61
+
62
+
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.
63
+
64
+
### Verify plugin installation
65
+
66
+
Check that the plugin is properly installed:
67
+
68
+
```sql
69
+
mysql> SHOW PLUGINS LIKE'audit_log_filter';
22
70
```
23
71
24
-
To verify the plugin installation, run the following command:
72
+
Expected output:
25
73
26
-
```{.bash data-prompt="mysql>"}
27
-
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'audit%';
This error occurs when the plugin is installed without the required tables. Using the SQL script prevents this issue.
105
+
106
+
### Fix missing tables
107
+
108
+
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:
109
+
110
+
```bash
111
+
mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql
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.
0 commit comments