Install the Audit Log Filter

Table of contents

1. Prerequisites
2. Find the plugin directory
3. Load the plugin
4. Run the installation script
5. Select a storage database (optional)
6. Verify the installation
7. Post‑installation configuration
8. Common problems & troubleshooting
9. References

---

Prerequisites

Requirement	Details
Percona Server version	8.0.34‑26 or later – the first release that ships the Audit Log Filter plugin.
Package manager	Debian/Ubuntu (APT) or RHEL/CentOS/Fedora (YUM/DNF).
Root / sudo	Needed to edit the server’s configuration file and restart the service.
Backup	Take a logical dump (mysqldump) before changing plugins or system variables.
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.
Filesystem layout	Know where the server’s plugin_dir lives (default paths are listed below).

---

Find the plugin directory

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

mysql> SELECT @@plugin_dir;
+--------------------------+
| @@plugin_dir             |
+--------------------------+
| /usr/lib/mysql/plugin/   |
+--------------------------+

When you install Percona Server from a package manager, the default locations are:

Distribution Default plugin_dir Debian / Ubuntu (APT) /usr/lib/mysql/plugin/ RHEL / CentOS / Fedora (YUM / DNF) /usr/lib64/mysql/plugin/ When you need a custom location, add or modify the variable in the server’s config file:

Debian/Ubuntu – edit /etc/mysql/percona-server.conf.d/mysqld.cnf (or /etc/mysql/my.cnf). RHEL/CentOS/Fedora – edit /etc/my.cnf.d/server.cnf (or /etc/my.cnf).

[mysqld]
plugin_dir=/opt/percona/plugins

Note

After you change my.cnf, you must restart the MySQL service for the new plugin_dir to take effect.

When you prefer a different database name, create the database and set the variable before you load the plugin.

Select a storage database (optional)

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.

mysql> SET GLOBAL audit_log_filter_database='my_audit_db';

or add the variable to the config file:

[mysqld]
audit_log_filter_database=my_audit_db

Important

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.

After you set the variable, restart the service or reload the plugin to use the new database.

Load the plugin

You can load the plugin dynamically (while the server runs) or statically (automatically at startup).

1. Dynamic (runtime) load

-- Requires SYSTEM_VARIABLES_ADMIN (or SESSION_VARIABLES_ADMIN for a temporary load)
mysql> INSTALL PLUGIN audit_log_filter SONAME 'audit_log_filter.so';

Verify:

mysql> SHOW PLUGINS LIKE 'audit_log_filter';

1. Static (startup) load

Add the following line to the same [mysqld] section you edited above and restart the service:

[mysqld]
plugin_load_add=audit_log_filter.so

Restart the server:

Debian/Ubuntu

$ sudo systemctl restart mysql

RHEL/CentOS/Fedora

$ sudo systemctl restart mysqld

Confirm the plugin is active:

mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM information_schema.PLUGINS
WHERE PLUGIN_NAME='audit_log_filter';

PLUGIN_STATUS should be ACTIVE.

Run the installation script

Percona provides an SQL script that creates the internal database and tables the filter uses.

# The package installs the script, usually under /usr/share/percona-server/
$ cd /usr/share/percona-server/
sudo mysql -u root -p < audit_log_filter_linux_install.sql

The script performs these actions:

The script creates the audit_log_filter database (or the database you later specify with audit_log_filter_database).

The script creates the rules and users tables that store filter definitions and user‑filter assignments.

The script registers built‑in UDFs (audit_log_filter_set_filter(), audit_log_filter_set_user(), and others).

Verify the installation

Check that the plugin is active

$ SHOW PLUGINS LIKE 'audit_log_filter';

Expected output:

Plugin_name Plugin_status audit_log_filter ACTIVE

Confirm the filter tables exist

mysql> USE audit_log_filter;   -- or the database you chose
mysql> SHOW TABLES;

You should see at least the rules and users tables.

Enable the filter engine

mysql> SET GLOBAL audit_log_filter_enable = ON;

Verify:

mysql> SELECT @@audit_log_filter_enable;

The result should be ON.

(Optional) Test a simple rule

mysql> INSERT INTO audit_log_filter.rules
  (rule_name, priority, filter_expression, action)
VALUES
  ('test_log_all', 10, 'TRUE', 'LOG');


mysql> SELECT * FROM audit_log_filter.rules;

Seeing the rule confirms that the tables are writable and the plugin functions properly.

Post‑installation configuration

Variable	Default	Typical setting	Description
audit_log_filter_enable	OFF	ON	Turns the filter engine on/off.
audit_log_filter_mode	ALLOW	ALLOW or DENY	Determines whether rules act as a whitelist (ALLOW) or blacklist (DENY).
audit_log_filter_rotate_on_size	1G	1G (or larger)	Size at which the filter log file rotates automatically.
audit_log_filter_max_size	0 (no limit)	10G (example)	Upper bound for total log-file storage; set > 0 to enable pruning.
audit_log_filter_prune_seconds	0	86400 (1 day)	Age-based pruning interval, if desired.

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.

Common problems & troubleshooting

Symptom	Likely cause	Fix
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).
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).
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.
ABORT rules block admin accounts	The admin user does not have the AUDIT_ADMIN privilege.	GRANT AUDIT_ADMIN TO ‘admin’@’%’;
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).
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).

For deeper log‑file management, see Manage the Audit Log Filter files.

References

Audit Log Filter Overview

Audit Log Filter Variables & Functions