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

docs/audit-log-filter-overview.md

@@ -1,14 +1,54 @@
 # Audit Log Filter overview
 
-The Audit Log Filter plugin provides security monitoring and access control for your MySQL server. The plugin allows you to monitor database activity, log specific events, and block connections or queries based on configurable rules.
+The Audit Log Filter plugin provides comprehensive database auditing capabilities for Percona Server. The plugin allows you to monitor, log, and block connections or queries actively executed on the selected server.
+
+## What is audit log filter?
+
+The Audit Log Filter plugin enables you to:
+
+| Issue                | Description                                                                                   |
+|:----------------------|:----------------------------------------------------------------------------------------------|
+| Monitor database activity | Track all database connections, queries, and administrative actions                         |
+| Comply with regulations   | Meet compliance requirements for database auditing                                          |
+| Enhance security          | Detect suspicious activities and unauthorized access attempts                              |
+| Control access            | Block specific queries or connections based on configurable rules                          |
+| Generate reports          | Create detailed audit trails for security analysis                                        |
 
 ## What the plugin does
 
-The plugin monitors server activity and creates detailed log files containing information about:
+The plugin uses the `mysql` system database to store filter and user account data. Set the [`audit_log_filter_database`](audit-log-filter-variables.md#audit_log_filter_database) variable at server startup to select a different database. When you change the database, you must create the required tables in the new database and migrate any existing filter data.
 
 * Database connections and disconnections
 
-* SQL statements executed by users
+## System requirements
+
+* Percona Server version: 8.0.34-26 or later
+
+* Storage engine: InnoDB (for audit tables)
+
+* Privileges: SYSTEM_VARIABLES_ADMIN to configure the plugin
+
+* Disk space: Sufficient space for audit log files
+
+* Memory: Additional memory overhead for audit processing
+
+## Basic configuration
+
+The Audit Log Filter plugin uses several key configuration variables:
+
+* Dynamic variables: Can be changed at runtime using `SET GLOBAL` without restarting the server
+
+* Read-only variables: Can only be changed at server startup in the configuration file
+
+* [`audit_log_filter_enable`](audit-log-filter-variables.md#audit_log_filter_enable): Enable or disable the audit filter engine (dynamic)
+
+* [`audit_log_filter_database`](audit-log-filter-variables.md#audit_log_filter_database): Database for storing filter definitions (read-only)
+
+* [`audit_log_filter_mode`](audit-log-filter-variables.md#audit_log_filter_mode): Set to ALLOW (whitelist) or DENY (blacklist) (dynamic)
+
+* [`audit_log_filter_rotate_on_size`](audit-log-filter-variables.md#audit_log_filter_rotate_on_size): Log file rotation size limit (dynamic)
+
+## Privileges
 
 * Database objects accessed
 
@@ -92,31 +132,56 @@ The Audit Log Filter plugin is the successor to the [audit log plugin](audit-log
 
 ## Audit Log Filter tables
 
-The Audit Log Filter plugin uses `mysql` system database tables in the `InnoDB` storage engine. These tables store user account data and filter data. When you start the server, change the plugin's database with the `audit_log_filter_database` variable.
+The Audit Log Filter plugin uses `mysql` system database tables in the `InnoDB` storage engine. These tables store user account data and filter data.
 
 The `audit_log_filter` table stores the definitions of the filters and has the following column definitions:
 
-| Column name | Data type | Description |
-|-------------|-----------|-------------|
-| NAME | VARCHAR(64) | Name of the filter |
-| FILTER | JSON | Definition of the filter linked to the name as a JSON value |
+| Column name | Description |
+|:-----------:|:-----------:|
+| NAME | Name of the filter |
+| FILTER | Definition of the filter linked to the name as a JSON value |
 
 The `audit_log_user` table stores account data and has the following column definitions:
 
-| Column name | Data type | Description |
-|-------------|-----------|-------------|
-| USER | VARCHAR(32) | The account name of the user |
-| HOST | VARCHAR(255) | The account name of the host |
-| FILTERNAME | VARCHAR(64) | The account filter name |
+| Column name | Description |
+|:-----------:|:-----------:|
+| USER | The account name of the user |
+| HOST | The account name of the host |
+| FILTERNAME | The account filter name |
+
+## Log formats and output
+
+The Audit Log Filter plugin supports multiple log formats:
+
+* JSON format: Machine-readable format for automated processing
+
+* XML (new): Human-readable format with structured data
+
+* XML (old): Legacy XML format for backward compatibility
+
+The plugin logs various types of events:
+
+* Connection events: User logins, logouts, and connection failures
+
+* Query events: SQL statements executed by users
+
+* Administrative events: Server configuration changes
 
-## Next steps
+* Error events: Failed operations and security violations
 
-To get started with the Audit Log Filter plugin:
+## Security considerations
 
-1. [Install the Audit Log Filter](install-audit-log-filter.md) - Installation instructions
+When implementing the Audit Log Filter plugin, consider these security aspects:
 
-2. [Filter Audit Log Files](filter-audit-log-filter-files.md) - Creating and managing filters
+| Issue               | Description                                                                                   |
+|:--------------------|:----------------------------------------------------------------------------------------------|
+| Performance impact   | Audit logging adds overhead to database operations                                            |
+| Storage requirements | Audit logs can grow large; plan for log rotation and archival                                 |
+| Sensitive data       | Configure filters to avoid logging sensitive information                                     |
+| Access control       | Restrict access to audit log files and configuration                                          |
+| Backup strategy      | Include audit logs in your backup and recovery procedures                                    |
+## References
 
-3. [Audit Log Filter Variables](audit-log-filter-variables.md) - Configuration options
+[Install the Audit Log Filter](install-audit-log-filter.md)
 
-4. [Manage Audit Log Files](manage-audit-log-filter.md) - Log file management
+[Audit Log Filter Variables & Functions](audit-log-filter-variables.md)

docs/install-audit-log-filter.md

@@ -1,40 +1,133 @@
 # 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.
+## Installation script
 
-When upgrading a MySQL installation, plugins are not automatically upgraded. You may need to manually load the plugin after the MySQL upgrade.
+The recommended way to install the plugin is to use the `audit_log_filter_linux_install.sql` script, located in the share directory, which creates the required tables before installing the plugin.
 
-In the `share` directory, locate the `audit_log_filter_linux_install.sql `script.
+### Prerequisites
 
-Implemented in 8.0.34, at the time you run the script, you can select the database used to store the JSON filter tables. 
+The `plugin_dir` system variable defines the plugin library location. When you need a custom location, set the `plugin_dir` variable at server startup.
 
-* 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`.
+### Database selection
 
-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.
+The script determines the target database using the following priority:
 
-With 8.0.34 and higher, use this command:
+1. When the plugin is already loaded, the script uses the database name from the `audit_log_filter_database` variable
 
+2. When the plugin is not loaded, but you pass the `-D db_name` option to the mysql client when running the script, the script uses the specified `db_name`
 
-```{.bash data-prompt="$"}
-$ mysql -u -D database -p < audit_log_filter_linux_install.sql
+3. When the plugin is not loaded and no `-D` option is provided, you must specify the `mysql` database when running the script
+
+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. When the database name is invalid, the audit log filter tables are not found.
+
+### Install the component
+
+To install the plugin using the script, you must specify the `mysql` database. You can do this in two ways:
+
+Option 1: Run the script from the command line with the `-D mysql` option:
+
+```bash
+mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql
+```
+
+Option 2: Connect to `mysql` database and run the script interactively:
+
+```sql
+mysql> use mysql;
+mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql;
+```
+
+Replace `/path/to/mysql/share/` with the actual path to your MySQL installation's share directory.
+
+### Verify installation
+
+After you run the script, verify that the required tables are created:
+
+```sql
+mysql> show tables in mysql like 'aud%';
+```
+
+Expected output:
+
+```
++------------------------+
+| Tables_in_mysql (aud%) |
++------------------------+
+| audit_log_filter       |
+| audit_log_user         |
++------------------------+
+2 rows in set (0.00 sec)
+```
+
+## Alternative: INSTALL PLUGIN method
+
+You can also install the plugin using the `INSTALL PLUGIN` command, but this method does not create the required tables and will cause filter operations to fail.
+
+### Verify plugin installation
+
+Check that the plugin is properly installed:
+
+```sql
+mysql> SHOW PLUGINS LIKE 'audit_log_filter';
+```
+
+Expected output:
+
+```
++-------------------+----------+--------------------+
+| Name              | Status   | Type               |
++-------------------+----------+--------------------+
+| audit_log_filter  | ACTIVE   | AUDIT              |
++-------------------+----------+--------------------+
+1 row in set (0.00 sec)
+```
+
+### Test filter functionality
+
+Test that the audit log filter is working correctly:
+
+```sql
+mysql> SELECT audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}');
+```
+
+Expected output:
+
+```
++---------------------------------------------------------------------+
+| audit_log_filter_set_filter('log_all', '{"filter": {"log": true}}') |
++---------------------------------------------------------------------+
+| ERROR: Failed to check filtering rule name existence                |
++---------------------------------------------------------------------+
+1 row in set (0.00 sec)
 ```
 
-To verify the plugin installation, run the following command:
+!!! note
+
+    This error occurs when the plugin is installed without the required tables. Using the SQL script prevents this issue.
 
-```{.bash data-prompt="mysql>"}
-mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'audit%';
+### Fix missing tables
+
+When you have already installed the audit log plugin but are missing the required tables, you can run the `audit_log_filter_linux_install.sql` script to create the audit tables in the `mysql` database:
+
+```bash
+mysql -u root -p -D mysql < /path/to/mysql/share/audit_log_filter_linux_install.sql
 ```
 
-??? example "Expected output"
+Or interactively:
+
+```sql
+mysql> use mysql;
+mysql> source /path/to/mysql/share/audit_log_filter_linux_install.sql;
+```
+
+This operation creates the missing tables without reinstalling the plugin.
+
+## Additional information
+
+For information about upgrading the audit log filter plugin, see the upgrade documentation.
+
+## 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)