Skip to content

Commit d1e409d

Browse files
patrickbirchpatrickbirch
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 d1e409d

File tree

1 file changed

+216
-24
lines changed

1 file changed

+216
-24
lines changed

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

Lines changed: 216 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,232 @@
1-
# Install the Audit Log Filter
1+
# 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+
## Table of contents
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+
1. [Prerequisites](#prerequisites)
6+
2. [Find the plugin directory](#find-the-plugin-directory)
7+
3. [Load the plugin](#load-the-plugin)
8+
4. [Run the installation script](#run-the-installation-script)
9+
5. [Select a storage database (optional)](#select-a-storage-database-optional)
10+
6. [Verify the installation](#verify-the-installation)
11+
7. [Post‑installation configuration](#post‑installation-configuration)
12+
8. [Common problems & troubleshooting](#common-problems--troubleshooting)
13+
9. [References](#references)
614

7-
In the `share` directory, locate the `audit_log_filter_linux_install.sql `script.
15+
---
816

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.
17+
## Prerequisites
1018

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`.
19+
| Requirement | Details |
20+
|-------------|---------|
21+
| Percona Server version | 8.0.34‑26 or later – the first release that ships the Audit Log Filter plugin. |
22+
| Package manager | Debian/Ubuntu (APT) or RHEL/CentOS/Fedora (YUM/DNF). |
23+
| Root / sudo | Needed to edit the server’s configuration file and restart the service. |
24+
| Backup | Take a logical dump (`mysqldump`) before changing plugins or system variables. |
25+
| MySQL privileges | The account used for the steps must have `SUPER` (or `SYSTEM_VARIABLES_ADMIN` in newer releases) to set global variables and install plugins. |
26+
| Filesystem layout | Know where the server’s `plugin_dir` lives (default paths are listed below). |
1427

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.
28+
---
1629

17-
With 8.0.34 and higher, use this command:
30+
## Find the plugin directory
1831

32+
The `plugin_dir` system variable references the directory where the filter plugin binary (`audit_log_filter.so`) resides.
1933

20-
```{.bash data-prompt="$"}
21-
$ mysql -u -D database -p < audit_log_filter_linux_install.sql
34+
```sql
35+
mysql> SELECT @@plugin_dir;
36+
+--------------------------+
37+
| @@plugin_dir |
38+
+--------------------------+
39+
| /usr/lib/mysql/plugin/ |
40+
+--------------------------+
2241
```
2342

24-
To verify the plugin installation, run the following command:
43+
When you install Percona Server from a package manager, the default locations are:
2544

26-
```{.bash data-prompt="mysql>"}
27-
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'audit%';
45+
Distribution Default plugin_dir
46+
Debian / Ubuntu (APT) /usr/lib/mysql/plugin/
47+
RHEL / CentOS / Fedora (YUM / DNF) /usr/lib64/mysql/plugin/
48+
When you need a custom location, add or modify the variable in the server's config file:
49+
50+
Debian/Ubuntu – edit /etc/mysql/percona-server.conf.d/mysqld.cnf (or /etc/mysql/my.cnf).
51+
RHEL/CentOS/Fedora – edit /etc/my.cnf.d/server.cnf (or /etc/my.cnf).
52+
53+
```ini
54+
[mysqld]
55+
plugin_dir=/opt/percona/plugins
56+
```
57+
58+
!!! note
59+
60+
After you change `my.cnf`, you must restart the MySQL service for the new `plugin_dir` to take effect.
61+
62+
When you prefer a different database name, create the database and set the variable before you load the plugin.
63+
64+
### Select a storage database (optional)
65+
66+
By default, the plugin uses the mysql system database. To store the filter tables elsewhere, set the global variable `audit_log_filter_database` before you load the plugin.
67+
68+
```sql
69+
mysql> SET GLOBAL audit_log_filter_database='my_audit_db';
70+
```
71+
72+
or add the variable to the config file:
73+
74+
```ini
75+
[mysqld]
76+
audit_log_filter_database=my_audit_db
77+
```
78+
79+
!!! note "Important"
80+
81+
The database name cannot be `NULL` and must be ≤ 64 characters. When the name is invalid, the plugin uses the default `mysql` database and logs a warning.
82+
83+
After you set the variable, restart the service or reload the plugin to use the new database.
84+
85+
### Load the plugin
86+
87+
You can load the plugin dynamically (while the server runs) or statically (automatically at startup).
88+
89+
1. Dynamic (runtime) load
90+
91+
```sql
92+
-- Requires SYSTEM_VARIABLES_ADMIN (or SESSION_VARIABLES_ADMIN for a temporary load)
93+
mysql> INSTALL PLUGIN audit_log_filter SONAME 'audit_log_filter.so';
94+
```
95+
96+
Verify:
97+
98+
```sql
99+
mysql> SHOW PLUGINS LIKE 'audit_log_filter';
100+
```
101+
102+
2. Static (startup) load
103+
104+
Add the following line to the same [mysqld] section you edited above and restart the service:
105+
106+
```ini
107+
[mysqld]
108+
plugin_load_add=audit_log_filter.so
28109
```
110+
Restart the server:
111+
112+
Debian/Ubuntu
113+
114+
```bash
115+
$ sudo systemctl restart mysql
116+
```
117+
118+
RHEL/CentOS/Fedora
119+
120+
```bash
121+
$ sudo systemctl restart mysqld
122+
```
123+
Confirm the plugin is active:
124+
125+
```sql
126+
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
127+
FROM information_schema.PLUGINS
128+
WHERE PLUGIN_NAME='audit_log_filter';
129+
```
130+
131+
`PLUGIN_STATUS` should be `ACTIVE`.
132+
133+
134+
### Run the installation script
135+
136+
Percona provides an SQL script that creates the internal database and tables the filter uses.
137+
138+
```bash
139+
# The package installs the script, usually under /usr/share/percona-server/
140+
$ cd /usr/share/percona-server/
141+
sudo mysql -u root -p < audit_log_filter_linux_install.sql
142+
```
143+
144+
The script performs these actions:
145+
146+
The script creates the `audit_log_filter` database (or the database you later specify with `audit_log_filter_database`).
147+
148+
The script creates the `rules` and `users` tables that store filter definitions and user‑filter assignments.
149+
150+
The script registers built‑in UDFs (`audit_log_filter_set_filter()`, `audit_log_filter_set_user()`, and others).
151+
152+
### Verify the installation
153+
154+
Check that the plugin is active
155+
156+
```sql
157+
$ SHOW PLUGINS LIKE 'audit_log_filter';
158+
```
159+
160+
Expected output:
161+
162+
Plugin_name Plugin_status
163+
audit_log_filter ACTIVE
164+
165+
166+
Confirm the filter tables exist
167+
168+
```sql
169+
mysql> USE audit_log_filter; -- or the database you chose
170+
mysql> SHOW TABLES;
171+
```
172+
173+
You should see at least the `rules` and `users` tables.
174+
175+
Enable the filter engine
176+
177+
```sql
178+
mysql> SET GLOBAL audit_log_filter_enable = ON;
179+
```
180+
181+
Verify:
182+
183+
```sql
184+
mysql> SELECT @@audit_log_filter_enable;
185+
```
186+
187+
The result should be ON.
188+
189+
(Optional) Test a simple rule
190+
191+
```sql
192+
mysql> INSERT INTO audit_log_filter.rules
193+
(rule_name, priority, filter_expression, action)
194+
VALUES
195+
('test_log_all', 10, 'TRUE', 'LOG');
196+
197+
198+
mysql> SELECT * FROM audit_log_filter.rules;
199+
```
200+
201+
Seeing the rule confirms that the tables are writable and the plugin functions properly.
202+
203+
### Post‑installation configuration
204+
205+
| Variable | Default | Typical setting | Description |
206+
|:--------------------------------|---------------:|--------------------:|:----------------------------------------------------------------------------|
207+
| audit_log_filter_enable | OFF | ON | Turns the filter engine on/off. |
208+
| audit_log_filter_mode | ALLOW | ALLOW or DENY | Determines whether rules act as a whitelist (ALLOW) or blacklist (DENY). |
209+
| audit_log_filter_rotate_on_size | 1G | 1G (or larger) | Size at which the filter log file rotates automatically. |
210+
| audit_log_filter_max_size | 0 (no limit) | 10G (example) | Upper bound for total log-file storage; set > 0 to enable pruning. |
211+
| audit_log_filter_prune_seconds | 0 | 86400 (1 day) | Age-based pruning interval, if desired. |
212+
213+
Adjust these variables in the same [mysqld] section of your config file and restart the service (or set them dynamically with ``SET GLOBAL …`) for the changes to take effect.
214+
215+
### Common problems & troubleshooting
216+
217+
| Symptom | Likely cause | Fix |
218+
|:--------------------------------------------------|:------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------|
219+
| ERROR 1129 (HY000): Can't open shared library | The plugin_dir points to the wrong location or the .so file is missing. | Verify @@plugin_dir and ensure audit_log_filter.so exists there (`ls $plugin_dir`). |
220+
| Installation script reports “Access denied” | The MySQL account lacks CREATE DATABASE/CREATE TABLE privileges. | Run the script as root (or grant the needed privileges temporarily). |
221+
| No audit entries appear | The audit_log_filter_enable setting is still OFF or audit_log_policy excludes FILTER events. | SET GLOBAL audit_log_filter_enable=ON; and ensure audit_log_policy includes FILTER. |
222+
| ABORT rules block admin accounts | The admin user does not have the AUDIT_ADMIN privilege. | GRANT AUDIT_ADMIN TO 'admin'@'%'; |
223+
| Log rotation never occurs | You have set the audit_log_filter_rotate_on_size setting to 0. | Set a non-zero size (for example, 1G). |
224+
| Plugin loads but tables are missing | The installation script was not executed after you loaded the plugin. | Rerun audit_log_filter_linux_install.sql (or create the tables manually). |
225+
226+
For deeper log‑file management, see [Manage the Audit Log Filter files].
29227

30-
??? example "Expected output"
228+
### References
31229

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

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

0 commit comments

Comments
 (0)