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

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)