How to Install and Configure Percona Audit Plugin on MySQL 8.0

Background

With MySQL 5.7 reaching end‑of‑life, many users upgrade to MySQL 8.0. The MariaDB audit plugin, which was adapted for 5.7, is no longer compatible with MySQL 8.0, so a community‑available audit plugin is required.

Percona announced in July 2024 that its audit plugin now supports MySQL 8.0 and provided a demonstration.

Environment Information

Operating System: CentOS Linux release 7.5.1804

Database: MySQL 8.0.37 Community Edition

Plugin version: extracted from Percona Server 8.0.37

Plugin Installation

Extract audit_log.so from the Percona package and copy it to MySQL’s plugin directory.

shell> mkdir -p Percona-Server-8.0.37-29-Linux.x86_64.glibc2.17/lib/plugin/
shell> tar -xvf Percona-Server-8.0.37-29-Linux.x86_64.glibc2.17.tar.gz --wildcards --no-anchored '*audit_log.so*'
shell> ls -al Percona-Server-8.0.37-29-Linux.x86_64.glibc2.17/lib/plugin/audit_log.so
-rwxr-xr-x 1 root root 914544 Aug 18 2024 audit_log.so

Copy the file and adjust ownership:

shell> cp /usr/local/Percona-Server-8.0.37-29-Linux.x86_64.glibc2.17/lib/plugin/audit_log.so /usr/local/mysql/lib/plugin/
shell> chown mysql:mysql /usr/local/mysql/lib/plugin/audit_log.so

Install the plugin inside MySQL:

mysql> INSTALL PLUGIN audit_log SONAME 'audit_log.so';
Query OK, 0 rows affected (0.02 sec)

Verify installation:

mysql> SELECT * FROM mysql.plugin;
+-----------+--------------+
| name      | dl           |
+-----------+--------------+
| audit_log | audit_log.so |
+-----------+--------------+

Plugin Usage

After installation, more than ten variables appear. Example of showing audit‑related variables:

mysql> SHOW GLOBAL VARIABLES LIKE 'audit%';
+-----------------------------+-----------------------------------------+
| Variable_name               | Value                                   |
+-----------------------------+-----------------------------------------+
| audit_log_buffer_size       | 1048576                                 |
| audit_log_exclude_accounts  | orchestrator'@'10*                     |
| audit_log_exclude_commands  |                                         |
| audit_log_exclude_databases |                                         |
| audit_log_file              | /data/mysql/mysqldata3306/log/audit.log |
| audit_log_flush             | OFF                                     |
| audit_log_format            | JSON                                    |
| audit_log_handler           | FILE                                    |
| audit_log_include_accounts  |                                         |
| audit_log_include_commands   |                                         |
| audit_log_include_databases  |                                         |
| audit_log_policy            | LOGINS                                  |
| audit_log_rotate_on_size    | 1073741824                              |
| audit_log_rotations         | 7                                       |
| audit_log_strategy          | ASYNCHRONOUS                            |
| audit_log_syslog_facility   | LOG_USER                                |
| audit_log_syslog_ident      | percona-audit                           |
| audit_log_syslog_priority   | LOG_INFO                                |
+-----------------------------+-----------------------------------------+

Key Parameter Usage

1. audit_log_policy

The audit_log_policy variable can be set dynamically to one of ALL , LOGINS , QUERIES or NONE .

2. audit_log_format

Supported formats are OLD , NEW , CSV and JSON .

3. audit_log_exclude_accounts

Example: adding 'test'@'%' to the exclusion list prevents any operations by that user from being logged.

SET GLOBAL audit_log_exclude_accounts = "'orchestrator'@'10%','test'@'%'";

4. audit_log_include_commands

This variable specifies which command types should be recorded. Querying performance_schema.setup_instruments shows that the plugin can handle 159 different command types.

SELECT name FROM performance_schema.setup_instruments
WHERE name LIKE "statement/sql/%"
ORDER BY name;

5. audit_log_exclude_databases

Setting audit_log_exclude_databases = 'mysql','test_%' excludes all operations on those databases from the audit log.

SELECT @@global.audit_log_exclude_databases;

Test Conclusions

audit_log_policy : supports ALL, LOGINS, QUERIES, NONE.

audit_log_format : supports OLD, NEW, CSV, JSON.

audit_log_exclude_accounts : can filter out specific users.

audit_log_include_commands : can control logging of 159 command types.

audit_log_exclude_databases : can filter out entire databases.

Recommended Reading

Technical Share | Compatibility Test of MySQL 5.7 and MariaDB 10.1 Audit Plugins

References

MariaDB: https://mariadb.org/

Percona: https://www.percona.com/

Percona Blog: https://www.percona.com/blog/using-the-percona-audit-logging-plugin-on-mysql-community-8-0-x/