Skip to content

Commit 99bed02

Browse files
committed
PS-10191 [DOCS] - Update Audit Log Filter installation instructions for 8.0
On branch ps-10191-8.0 modified: docs/install-audit-log-filter.md
1 parent 241e3bf commit 99bed02

File tree

1 file changed

+115
-23
lines changed

1 file changed

+115
-23
lines changed

docs/install-audit-log-filter.md

Lines changed: 115 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,132 @@
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 component is to use the `audit_log_filter_linux_install.sql` script, located in the share directory, which creates the required tables before installing the component.
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 component 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 component is already loaded, the script uses the database name from the `audit_log_filter.database` variable
16+
2. When the component 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 component is not loaded and no `-D` option is provided, you must specify the `mysql` database when running the script
1818

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.
1920

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 component 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:
32+
33+
```sql
34+
mysql> use mysql;
35+
mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql;
36+
```
37+
38+
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 COMPONENT method
61+
62+
You can also install the component using the `INSTALL COMPONENT` command, but this method does not create the required tables and will cause filter operations to fail.
63+
64+
### Verify component installation
65+
66+
Check that the component is properly installed:
67+
68+
```sql
69+
mysql> select * from mysql.component;
2270
```
2371

24-
To verify the plugin installation, run the following command:
72+
Expected output:
2573

26-
```{.bash data-prompt="mysql>"}
27-
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'audit%';
2874
```
75+
+--------------+--------------------+------------------------------------+
76+
| component_id | component_group_id | component_urn |
77+
+--------------+--------------------+------------------------------------+
78+
| 1 | 1 | file://component_percona_telemetry |
79+
| 2 | 2 | file://component_audit_log_filter |
80+
+--------------+--------------------+------------------------------------+
81+
2 rows in set (0.00 sec)
82+
```
83+
84+
### Test filter functionality
85+
86+
Test that the audit log filter is working correctly:
87+
88+
```sql
89+
mysql> SELECT audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}');
90+
```
91+
92+
Expected output:
93+
94+
```
95+
+---------------------------------------------------------------------+
96+
| audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}') |
97+
+---------------------------------------------------------------------+
98+
| ERROR: Failed to check filtering rule name existence |
99+
+---------------------------------------------------------------------+
100+
1 row in set (0.00 sec)
101+
```
102+
103+
!!! note
104+
105+
This error occurs when the component is installed without the required tables. Using the SQL script prevents this issue.
106+
107+
### Fix missing tables
108+
109+
When you have already installed the audit log component 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:
110+
111+
```bash
112+
mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql
113+
```
114+
115+
Or interactively:
116+
117+
```sql
118+
mysql> use mysql;
119+
mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql;
120+
```
121+
122+
This operation creates the missing tables without reinstalling the component.
123+
124+
## Additional information
125+
126+
To upgrade from `audit_log_filter` plugin in Percona Server 8.4 to `component_audit_log_filter` component in Percona Server 8.4, do the manual upgrade.
29127

30-
??? example "Expected output"
128+
## References
31129

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

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.
132+
[Audit Log Filter Variables & Functions](audit-log-filter-variables.md)

0 commit comments

Comments
 (0)