From 9e47511e098e7e7048643283025384fa6dd65ab6 Mon Sep 17 00:00:00 2001 From: Patrick Birch <48594400+patrickbirch@users.noreply.github.com> Date: Mon, 22 Sep 2025 05:15:33 -0500 Subject: [PATCH] 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 --- docs/install-audit-log-filter.md | 240 +++++++++++++++++++++++++++---- 1 file changed, 216 insertions(+), 24 deletions(-) diff --git a/docs/install-audit-log-filter.md b/docs/install-audit-log-filter.md index 143aa2c1440..9313267fc4f 100644 --- a/docs/install-audit-log-filter.md +++ b/docs/install-audit-log-filter.md @@ -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 + +```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)