PS-10191 [DOCS] - Update Audit Log Filter installation instructions f… #573
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,13 +1,53 @@ | ||
| # Audit Log Filter overview | ||
|
|
||
| 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 | | ||
|
|
||
| Enabling the plugin produces a log file that contains a record of server activity. The log file has information on connections and databases accessed by that connection. | ||
|
|
||
| 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. | ||
|
|
||
| The `AUDIT_ADMIN` privilege is required to enable users to manage the Audit Log Filter plugin. | ||
|
|
||
| ## 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) | ||
|
There was a problem hiding this comment. 🚫 [linkspector] reported by reviewdog 🐶 |
||
|
|
||
| * [`audit_log_filter_rotate_on_size`](audit-log-filter-variables.md#audit_log_filter_rotate_on_size): Log file rotation size limit (dynamic) | ||
|
|
||
| ## Privileges | ||
|
|
||
| Define the privilege at runtime at the startup of the server. The associated Audit Log Filter privilege can be unavailable if the plugin is not enabled. | ||
|
|
@@ -22,110 +62,56 @@ This privilege allows queries from a user account to always be executed. An `abo | |
|
|
||
| ## 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. | ||
|
|
||
| The `audit_log_filter` table stores the definitions of the filters and has the following column definitions: | ||
|
|
||
| | 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 | 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 | ||
|
|
||
| * Error events: Failed operations and security violations | ||
|
|
||
| ## Security considerations | ||
|
|
||
| When implementing the Audit Log Filter plugin, consider these security aspects: | ||
|
|
||
| | 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 | ||
|
|
||
| [Install the Audit Log Filter](install-audit-log-filter.md) | ||
|
|
||
| [Audit Log Filter Variables & Functions](audit-log-filter-variables.md) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,40 +1,131 @@ | ||
| # Install the Audit Log Filter | ||
|
|
||
| ## Installation script | ||
|
|
||
| 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. | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| The `plugin_dir` system variable defines the plugin library location. When you need a custom location, set the `plugin_dir` variable at server startup. | ||
|
|
||
| ### Database selection | ||
|
|
||
| The script determines the target database using the following priority: | ||
|
|
||
| 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` | ||
| 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) | ||
| ``` | ||
|
|
||
| !!! note | ||
|
|
||
| This error occurs when the plugin is installed without the required tables. Using the SQL script prevents this issue. | ||
|
|
||
| ### 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 | ||
| ``` | ||
|
|
||
| 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 | ||
|
|
||
| [Audit Log Filter Overview](audit-log-filter-overview.md) | ||
|
|
||
| [Audit Log Filter Variables & Functions](audit-log-filter-variables.md) |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🚫 [linkspector] reported by reviewdog 🐶
Cannot reach audit-log-filter-variables.md#audit_log_filter_enable. Status: 404 Cannot find section: #audit_log_filter_enable in file: /home/runner/work/psmysql-docs/psmysql-docs/docs/audit-log-filter-variables.md.