8.4.7.2 Installing or Uninstalling MySQL Enterprise Audit with The Audit Log Component

Note

The Audit Log component is intended to replace the Audit Log plugin, which is now deprecated.

This section describes how to install or uninstall MySQL Enterprise Audit, which is implemented using the audit log component and related elements described in Section 8.4.7.1, “Elements of MySQL Enterprise Audit Component”. For general information about installing components, see Section 7.5.1, “Installing and Uninstalling Components”.

Plugin upgrades are not automatic when you upgrade a MySQL installation and some plugin loadable functions must be loaded manually (see Installing Loadable Functions). Alternatively, you can reinstall the plugin after upgrading MySQL to load new functions.

Important

Read this entire section before following its instructions. Parts of the procedure differ depending on your environment.

Note

If installed, the audit_log component involves some minimal overhead even when disabled. To avoid this overhead, do not install MySQL Enterprise Audit unless you plan to use it.

To be usable by the server, the component library file must be located in the MySQL plugin directory (the directory named by the plugin_dir system variable). If necessary, configure the plugin directory location by setting the value of plugin_dir at server startup.

To install MySQL Enterprise Audit for both Windows and Linux, look in the share directory of your MySQL installation and choose the following script:

• audit_log_component_filter_install.sql

Run the script as follows.

$> mysql -u root -p -D mysql < audit_log_component_filter_install.sql
Enter password: (enter root password here)

It is possible to specify a custom database for storing JSON filter tables when you run the installation script. Create the database first; its name should not exceed 64 characters. For example:

mysql> CREATE DATABASE IF NOT EXISTS database-name;

Next, run the script using the alternative database name.

$> mysql -u root -p -D database-name < audit_log_component_filter_install.sql
Enter password: (enter root password here)

Note

Some MySQL versions have introduced changes to the structure of the MySQL Enterprise Audit tables. To ensure that your tables are up to date for upgrades from earlier versions of MySQL, perform the MySQL upgrade procedure, making sure to use the option that forces an update (see Chapter 3, Upgrading MySQL). If you prefer to run the update statements only for the MySQL Enterprise Audit tables, see the following discussion.

For new MySQL installations, the USER and HOST columns in the audit_log_user table used by MySQL Enterprise Audit have definitions that better correspond to the definitions of the User and Host columns in the mysql.user system table. For upgrades to an installation for which MySQL Enterprise Audit is already installed, it is recommended that you alter the table definitions as follows:

ALTER TABLE mysql.audit_log_user
  DROP FOREIGN KEY audit_log_user_ibfk_1;
ALTER TABLE mysql.audit_log_filter
  CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_as_ci;
ALTER TABLE mysql.audit_log_user
  CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_as_ci;
ALTER TABLE mysql.audit_log_user
  MODIFY COLUMN USER VARCHAR(32);
ALTER TABLE mysql.audit_log_user
  ADD FOREIGN KEY (FILTERNAME) REFERENCES mysql.audit_log_filter(NAME);

Note

To use MySQL Enterprise Audit in the context of source/replica replication, Group Replication, or InnoDB Cluster, you must prepare the replica nodes prior to running the installation script on the source node. This is necessary because the INSTALL COMPONENT statement in the script is not replicated.

1. On each replica node, extract the INSTALL COMPONENT statement from the installation script and execute it manually.

2. On the source node, run the installation script as described previously.

To verify component installation, examine the MySQL component table (see Section 7.5.2, “Obtaining Component Information”). For example:

mysql> SELECT * FROM mysql.component;
+--------------+--------------------+----------------------------+
| component_id | component_group_id | component_urn              |
+--------------+--------------------+----------------------------+
|            1 |                  1 | file://component_audit_log |
+--------------+--------------------+----------------------------+

If the component fails to initialize, check the server error log for diagnostic messages.

The audit log component internally registers the following functions:

• audit_log_encryption_password_get([keyring_id])

• audit_log_encryption_password_set(password)

• audit_log_filter_set_filter(filter_name, definition)

• audit_log_filter_remove_filter(filter_name)

• audit_log_filter_set_user(user_name, filter_name)

• audit_log_filter_remove_user(user_name)

• audit_log_read_bookmark()

• audit_log_read([arg])

• audit_log_filter_flush()

• audit_log_rotate()

After MySQL Enterprise Audit is installed, you can use the --audit-log option for subsequent server startups to control audit_log component activation. For example, to prevent the component from being removed at runtime, use this option:

[mysqld]
audit-log=FORCE_PLUS_PERMANENT

If it is desired to prevent the server from running without the audit component, use --audit-log with a value of FORCE or FORCE_PLUS_PERMANENT to force server startup to fail if the component does not initialize successfully.

Important

By default, rule-based audit log filtering logs no auditable events for any users. Should you wish to produce log-everything behavior with rule-based filtering, create a simple filter to enable logging and assign it to the default account:

SELECT audit_log_filter_set_filter('log_all', '{ "filter": { "log": true } }');
SELECT audit_log_filter_set_user('%', 'log_all');

The filter assigned to % is used for connections from any account that has no explicitly assigned filter (which initially is true for all accounts).

When installed as just described, MySQL Enterprise Audit remains installed until uninstalled. To remove it, run the uninstall script located in the share directory of your MySQL installation. The example here specifies the default system database, mysql. Make the appropriate substitution for your system.

$> mysql -u root -p -D mysql < audit_log_component_filter_uninstall.sql
Enter password: (enter root password here)