Skip to content

Commit 5196db2

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 5196db2

File tree

1 file changed

+210
-24
lines changed

1 file changed

+210
-24
lines changed

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

Lines changed: 210 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,226 @@
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 binary for the filter plugin (`audit_log_filter.so`) resides in the directory referenced by the `plugin_dir` system variable.
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+
If you installed 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+
If 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 changing `my.cnf` you must restart the MySQL service for the new `plugin_dir` to take effect.
61+
62+
### Load the plugin
63+
64+
You can load the plugin dynamically (while the server is running) or statically (automatically at startup).
65+
66+
1. Dynamic (runtime) load
67+
68+
```sql
69+
-- Requires SYSTEM_VARIABLES_ADMIN (or SESSION_VARIABLES_ADMIN for a temporary load)
70+
mysql> INSTALL PLUGIN audit_log_filter SONAME 'audit_log_filter.so';
71+
```
72+
73+
Verify:
74+
75+
```sql
76+
mysql> SHOW PLUGINS LIKE 'audit_log_filter';
77+
```
78+
79+
2. Static (startup) load
80+
Add the following line to the same [mysqld] section you edited above and restart the service:
81+
82+
```ini
83+
[mysqld]
84+
plugin_load_add=audit_log_filter.so
85+
```
86+
Restart the server:
87+
88+
Debian/Ubuntu
89+
90+
```bash
91+
$ sudo systemctl restart mysql
2892
```
2993

30-
??? example "Expected output"
94+
RHEL/CentOS/Fedora
95+
96+
```bash
97+
$ sudo systemctl restart mysqld
98+
```
99+
Confirm the plugin is active:
100+
101+
```sql
102+
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
103+
FROM information_schema.PLUGINS
104+
WHERE PLUGIN_NAME='audit_log_filter';
105+
```
106+
107+
`PLUGIN_STATUS` should be `ACTIVE`.
108+
109+
110+
### Run the installation script
111+
112+
Percona ships an SQL script that creates the internal database and tables used by the filter.
113+
114+
```bash
115+
# The script is installed with the package, usually under /usr/share/percona-server/
116+
$ cd /usr/share/percona-server/
117+
sudo mysql -u root -p < audit_log_filter_linux_install.sql
118+
```
119+
120+
What the script does:
121+
122+
Creates the `audit_log_filter` database (or the database you later specify with `audit_log_filter_database`).
123+
124+
Creates the `rules` and `users` tables that store filter definitions and user‑filter assignments.
125+
126+
Registers built‑in UDFs (`audit_log_filter_set_filter()`, `audit_log_filter_set_user()`, …).
127+
128+
If you prefer a different database name, you can create it yourself and then set the variable before the plugin is loaded (see the next section).
129+
130+
Select a storage database (optional)
131+
By default the plugin uses the mysql system database. To store the filter tables elsewhere, set the global variable `audit_log_filter_database` before the plugin is loaded.
132+
133+
```sql
134+
SET GLOBAL audit_log_filter_database='my_audit_db';
135+
```
136+
137+
or add it to the config file:
138+
139+
```ini
140+
[mysqld]
141+
audit_log_filter_database=my_audit_db
142+
```
143+
144+
Important: The database name cannot be `NULL` and must be ≤ 64 characters. If the name is invalid, the plugin falls back to the default `mysql` database and logs a warning.
145+
146+
After setting the variable, restart the service (or reload the plugin) so the new database is used.
147+
148+
### Verify the installation
149+
150+
Check the plugin is active
151+
152+
```sql
153+
$ SHOW PLUGINS LIKE 'audit_log_filter';
154+
```
155+
156+
Expected output:
157+
158+
Plugin_name Plugin_status
159+
audit_log_filter ACTIVE
160+
161+
162+
Confirm the filter tables exist
163+
164+
```sql
165+
mysql> USE audit_log_filter; -- or the database you chose
166+
mysql> SHOW TABLES;
167+
```
168+
169+
You should see at least `rules` and `users`.
170+
171+
Enable the filter engine
172+
173+
```
174+
mysql> SET GLOBAL audit_log_filter_enable = ON;
175+
```
176+
177+
Verify:
178+
179+
```sql
180+
mysql> SELECT @@audit_log_filter_enable;
181+
```
182+
183+
Result should be ON.
184+
185+
(Optional) Test a simple rule
186+
187+
```sql
188+
mysql> INSERT INTO audit_log_filter.rules
189+
(rule_name, priority, filter_expression, action)
190+
VALUES
191+
('test_log_all', 10, 'TRUE', 'LOG');
192+
193+
194+
mysql> SELECT * FROM audit_log_filter.rules;
195+
```
196+
197+
Seeing the rule confirms that the tables are writable and the plugin is functional.
198+
199+
Post‑installation configuration
200+
201+
| Variable | Default | Typical setting | Description |
202+
|:--------------------------------|---------------:|--------------------:|:----------------------------------------------------------------------------|
203+
| audit_log_filter_enable | OFF | ON | Turns the filter engine on/off. |
204+
| audit_log_filter_mode | ALLOW | ALLOW or DENY | Determines whether rules act as a whitelist (ALLOW) or blacklist (DENY). |
205+
| audit_log_filter_rotate_on_size | 1G | 1G (or larger) | Size at which the filter log file rotates automatically. |
206+
| audit_log_filter_max_size | 0 (no limit) | 10G (example) | Upper bound for total log-file storage; set > 0 to enable pruning. |
207+
| audit_log_filter_prune_seconds | 0 | 86400 (1 day) | Age-based pruning interval, if desired. |
208+
209+
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.
31210

32-
```text
33-
+--------------------+---------------+
34-
| PLUGIN_NAME | PLUGIN_STATUS |
35-
+--------------------+---------------+
36-
| audit_log_filter | ACTIVE |
37-
+--------------------+---------------+
38-
```
211+
Common problems & troubleshooting
212+
Symptom Likely cause Fix
213+
ERROR 1129 (HY000): Can't open shared library 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).
214+
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).
215+
No audit entries appear audit_log_filter_enable is still OFF or audit_log_policy excludes FILTER events. SET GLOBAL audit_log_filter_enable=ON; and ensure audit_log_policy includes FILTER.
216+
ABORT rules block admin accounts The admin user does not have the AUDIT_ADMIN privilege. GRANT AUDIT_ADMIN TO 'admin'@'%';
217+
Log rotation never occurs audit_log_filter_rotate_on_size is set to 0. Set a non‑zero size (e.g., 1G).
218+
Plugin loads but tables are missing The installation script was not executed after the plugin was loaded. Rerun audit_log_filter_linux_install.sql (or create the tables manually).
219+
For deeper log‑file management, see [Manage the Audit Log Filter files].
39220

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.
221+
References
222+
Audit Log Filter Overview – https://docs.percona.com/percona-server/8.0/audit-log-filter-overview.html
223+
Audit Log Filter Variables & Functions – https://docs.percona.com/percona-server/8.0/audit-log-filter-variables.html
224+
Create and Manage Filter Rules – (link to the rules guide when available)
225+
General Percona Server Installation (Linux) – https://docs.percona.com/percona-server/8.0/installation.html
226+
Document last updated: 22 Sep 2025

0 commit comments

Comments
 (0)