Skip to content

Commit 02a40ea

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 02a40ea

File tree

1 file changed

+215
-24
lines changed

1 file changed

+215
-24
lines changed

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

Lines changed: 215 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,231 @@
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+
If you prefer a different database name, you can create it yourself and then set the variable before the plugin is loaded.
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 the plugin is loaded.
67+
68+
```sql
69+
mysql> SET GLOBAL audit_log_filter_database='my_audit_db';
70+
```
71+
72+
or add it 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. If the name is invalid, the plugin falls back to the default `mysql` database and logs a warning.
82+
83+
After setting the variable, restart the service or reload the plugin so the new database is used.
84+
85+
### Load the plugin
86+
87+
You can load the plugin dynamically (while the server is running) 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+
Add the following line to the same [mysqld] section you edited above and restart the service:
104+
105+
```ini
106+
[mysqld]
107+
plugin_load_add=audit_log_filter.so
108+
```
109+
Restart the server:
110+
111+
Debian/Ubuntu
112+
113+
```bash
114+
$ sudo systemctl restart mysql
115+
```
116+
117+
RHEL/CentOS/Fedora
118+
119+
```bash
120+
$ sudo systemctl restart mysqld
121+
```
122+
Confirm the plugin is active:
123+
124+
```sql
125+
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
126+
FROM information_schema.PLUGINS
127+
WHERE PLUGIN_NAME='audit_log_filter';
128+
```
129+
130+
`PLUGIN_STATUS` should be `ACTIVE`.
131+
132+
133+
### Run the installation script
134+
135+
Percona ships an SQL script that creates the internal database and tables used by the filter.
136+
137+
```bash
138+
# The script is installed with the package, usually under /usr/share/percona-server/
139+
$ cd /usr/share/percona-server/
140+
sudo mysql -u root -p < audit_log_filter_linux_install.sql
28141
```
29142

30-
??? example "Expected output"
143+
What the script does:
144+
145+
Creates the `audit_log_filter` database (or the database you later specify with `audit_log_filter_database`).
146+
147+
Creates the `rules` and `users` tables that store filter definitions and user‑filter assignments.
148+
149+
Registers built‑in UDFs (`audit_log_filter_set_filter()`, `audit_log_filter_set_user()`, …).
150+
151+
### Verify the installation
152+
153+
Check the plugin is active
154+
155+
```sql
156+
$ SHOW PLUGINS LIKE 'audit_log_filter';
157+
```
158+
159+
Expected output:
160+
161+
Plugin_name Plugin_status
162+
audit_log_filter ACTIVE
163+
164+
165+
Confirm the filter tables exist
166+
167+
```sql
168+
mysql> USE audit_log_filter; -- or the database you chose
169+
mysql> SHOW TABLES;
170+
```
171+
172+
You should see at least `rules` and `users`.
173+
174+
Enable the filter engine
175+
176+
```sql
177+
mysql> SET GLOBAL audit_log_filter_enable = ON;
178+
```
179+
180+
Verify:
181+
182+
```sql
183+
mysql> SELECT @@audit_log_filter_enable;
184+
```
185+
186+
Result should be ON.
187+
188+
(Optional) Test a simple rule
189+
190+
```sql
191+
mysql> INSERT INTO audit_log_filter.rules
192+
(rule_name, priority, filter_expression, action)
193+
VALUES
194+
('test_log_all', 10, 'TRUE', 'LOG');
195+
196+
197+
mysql> SELECT * FROM audit_log_filter.rules;
198+
```
199+
200+
Seeing the rule confirms that the tables are writable and the plugin is functional.
201+
202+
### Post‑installation configuration
203+
204+
| Variable | Default | Typical setting | Description |
205+
|:--------------------------------|---------------:|--------------------:|:----------------------------------------------------------------------------|
206+
| audit_log_filter_enable | OFF | ON | Turns the filter engine on/off. |
207+
| audit_log_filter_mode | ALLOW | ALLOW or DENY | Determines whether rules act as a whitelist (ALLOW) or blacklist (DENY). |
208+
| audit_log_filter_rotate_on_size | 1G | 1G (or larger) | Size at which the filter log file rotates automatically. |
209+
| audit_log_filter_max_size | 0 (no limit) | 10G (example) | Upper bound for total log-file storage; set > 0 to enable pruning. |
210+
| audit_log_filter_prune_seconds | 0 | 86400 (1 day) | Age-based pruning interval, if desired. |
211+
212+
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.
213+
214+
### Common problems & troubleshooting
215+
216+
| Symptom | Likely cause | Fix |
217+
|:--------------------------------------------------|:------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------|
218+
| 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`). |
219+
| 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). |
220+
| 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. |
221+
| ABORT rules block admin accounts | The admin user does not have the AUDIT_ADMIN privilege. | GRANT AUDIT_ADMIN TO 'admin'@'%'; |
222+
| Log rotation never occurs | audit_log_filter_rotate_on_size is set to 0. | Set a non-zero size (e.g., 1G). |
223+
| 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). |
224+
225+
For deeper log‑file management, see [Manage the Audit Log Filter files].
226+
227+
### References
31228

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

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

0 commit comments

Comments
 (0)