Skip to content

PS-10191 [DOCS] - Update Audit Log Filter installation instructions f… #573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: 8.0
Choose a base branch
from
Open

PS-10191 [DOCS] - Update Audit Log Filter installation instructions f… #573

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
240 changes: 216 additions & 24 deletions docs/install-audit-log-filter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,232 @@
# Install the Audit Log Filter
# Install the Audit Log Filter

The `plugin_dir` system variable defines the plugin library location. If needed, at server startup, set the `plugin_dir` variable.
## Table of contents

When upgrading a MySQL installation, plugins are not automatically upgraded. You may need to manually load the plugin after the MySQL upgrade.
1. [Prerequisites](#prerequisites)
2. [Find the plugin directory](#find-the-plugin-directory)
3. [Load the plugin](#load-the-plugin)
4. [Run the installation script](#run-the-installation-script)
5. [Select a storage database (optional)](#select-a-storage-database-optional)
6. [Verify the installation](#verify-the-installation)
7. [Post‑installation configuration](#post‑installation-configuration)
8. [Common problems & troubleshooting](#common-problems--troubleshooting)
9. [References](#references)

In the `share` directory, locate the `audit_log_filter_linux_install.sql `script.
---

Implemented in 8.0.34, at the time you run the script, you can select the database used to store the JSON filter tables.
## Prerequisites

* If the plugin is loaded, the installation script takes the database name from the `audit_log_filter_database` variable
* 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`.
* 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`.
| 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). |

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

With 8.0.34 and higher, use this command:
## Find the plugin directory

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

```{.bash data-prompt="$"}
$ mysql -u -D database -p < audit_log_filter_linux_install.sql
```sql
mysql> SELECT @@plugin_dir;
+--------------------------+
| @@plugin_dir |
+--------------------------+
| /usr/lib/mysql/plugin/ |
+--------------------------+
```

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

```{.bash data-prompt="mysql>"}
mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'audit%';
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).

```ini
[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.

```sql
mysql> SET GLOBAL audit_log_filter_database='my_audit_db';
```

or add the variable to the config file:

```ini
[mysqld]
audit_log_filter_database=my_audit_db
```

!!! note "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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The numbered list is broken. Add four spaces to every line after this one.


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

Verify:

```sql
mysql> SHOW PLUGINS LIKE 'audit_log_filter';
```

2. Static (startup) load

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

```ini
[mysqld]
plugin_load_add=audit_log_filter.so
```
Restart the server:

Debian/Ubuntu

```bash
$ sudo systemctl restart mysql
```

RHEL/CentOS/Fedora

```bash
$ sudo systemctl restart mysqld
```
Confirm the plugin is active:

```sql
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.

```bash
# 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

```sql
$ SHOW PLUGINS LIKE 'audit_log_filter';
```

Expected output:

Plugin_name Plugin_status
audit_log_filter ACTIVE


Confirm the filter tables exist

```sql
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

```sql
mysql> SET GLOBAL audit_log_filter_enable = ON;
```

Verify:

```sql
mysql> SELECT @@audit_log_filter_enable;
```

The result should be ON.

(Optional) Test a simple rule

```sql
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](manage-audit-log-filter.md).

??? example "Expected output"
### References

```text
+--------------------+---------------+
| PLUGIN_NAME | PLUGIN_STATUS |
+--------------------+---------------+
| audit_log_filter | ACTIVE |
+--------------------+---------------+
```
[Audit Log Filter Overview](audit-log-filter-overview.md)

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