Description\n-----------\n\nWhile application design specifications and database configurations may intend specific limitations to be placed around access to data, audit mechanisms help confirm the effectiveness of these controls.\n\nMariaDB Enterprise Audit is a plugin that logs data access and database operations.\n\nAudit mechanisms are most effective when they produce a manageable quantity of output. MariaDB Enterprise Audit includes advanced filtering features to enable narrowly defining which information is logged.\n\nWhere audit mechanisms may only be effective when control parameters can also be audited, MariaDB Enterprise Audit implements logging of configuration changes.\n\nPlugin Conflict (MENT-316)\n\nThe MariaDB Enterprise Audit plugin (server_audit2.so) is incompatible with the older server_audit.so (v1) plugin. Running both can cause server instability or deadlocks.\n\n_If you are a new user: You can continue reading._\n\n_If you are migrating: You must remove the old v1 plugin. Please go directly to the_ _Upgrades_ _section for complete instructions._\n\nConfiguration Overview\n\nMariaDB Enterprise Audit is installed and loaded by default. If you are unsure whether it is loaded on your system, you can confirm that the plugin is loaded.\n\nTo use MariaDB Enterprise Audit, the plugin must be configured: Administrators must define Audit Filters to configure what MariaDB Enterprise Audit writes to the audit log.\n\nMariaDB Enterprise Audit supports two types of Audit Filters:\n\n| Audit Filter Type                                                        | Used For                                                                                         |\n| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |\n| Default Audit Filter | The Default Audit Filter is used for any user account that is not assigned a Named Audit Filter. |\n| Named Audit Filters   | Named Audit Filters are assigned to specific user accounts.                                      |\n\nAdministrators can define Audit Filters to audit log activity using multiple types of filters:\n\n| Filter Type                                                   | Used For                                                                                                                                                                                                                                                                                                     |\n| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Event Filters    | Event Filters are used to enable or disable audit logging for specific types of operations performed by the user accounts assigned to the Audit Filter.                                                                                                                                                      |\n| Logging Filters | Logging Filters are used to enable or disable audit logging for the user accounts assigned to the Audit Filter.                                                                                                                                                                                              |\n| Object Filters  | Object Filters are used to enable or disable audit logging for specific databases or tables accessed by the user accounts assigned to the Audit Filter. Support for Object Filters was added in MariaDB Enterprise Server 10.6. Support for Object Filters was backported to ES 10.4.21-13 and ES 10.5.12-8. |\n\nAdministrators must start audit logging.\n\nGeneral Operation\n\nMariaDB Enterprise Audit performs audit logging during typical operations of MariaDB Enterprise Server:\n\n When a user connects, fails to connect, or disconnects, MariaDB Enterprise Audit will write a message to the audit log if the Audit Filter specifies the specific type of Connect Event.\n When a user executes a query, MariaDB Enterprise Audit will write a message to the audit log if the Audit Filter specifies the specific type of Query Event and if the queried objects are not excluded by Object Filters.\n When a query accesses a table, MariaDB Enterprise Audit will write a message to the audit log if the Audit Filter specifies the specific type of Table Event and if the table is not excluded by Object Filters.\n When a query modifies the MariaDB Enterprise Audit configuration, MariaDB Enterprise Audit will write a message to the audit log if the Audit Filter specifies the Audit Config Event.\n When a user's Audit Filter contains a Logging Filter that disables audit logging, all audit logging for the user's activity will be skipped.\n\nMariaDB Enterprise Audit writes audit log messages either to a dedicated audit log file or to the system log (syslog), depending on configuration.\n\nAudit log messages that correspond to a query are logged when the query completes. If a query is executed in a transaction, the audit log messages that correspond to the query are logged when the individual query completes, not when the transaction completes. If the query fails, the audit log message is logged at time of failure.\n\nAudit Log Considerations\n\nCare must be taken when logging data for audit to maintain alignment to business requirements. Concerns include:\n\n Queries should not be logged for tables containing Personally Identifiable Information (PII) or Sensitive PII (SPII) such as passwords, since audit log data is written unencrypted. Consider using Object Filters to exclude sensitive information from the audit log.\n Backup of audit data should be performed at least as frequently as database backups.\n Audit log data on database servers could be tampered with if the database server is compromised. Consider secure transmission of log data to a hardened and remote logging server.\n Where audit data is mission-critical, it should be subject to controls, data protection, data retention, and highly-available storage as are used for other mission-critical data.\n\nInstall the Audit Plugin\n\nMariaDB Enterprise Audit comes preinstalled with MariaDB Enterprise Server, so no manual installation is required.\n\nTo verify that the plugin is installed:\n\n1. Locate your server’s plugin directory.\n    When MariaDB Enterprise Server is running, you can find the directory by checking the value of the plugin_dir system variable.\n\n``sql\nSHOW GLOBAL VARIABLES\n   LIKE 'plugin_dir';\n`\n\n`sql\n+---------------+--------------------------+\n| Variable_name | Value                    |\n+---------------+--------------------------+\n| plugin_dir    | /usr/lib64/mysql/plugin/ |\n+---------------+--------------------------+\n`\n\n2. Verify the server_audit2.so file—the shared library used by MariaDB Enterprise Audit—is present in your server’s plugin directory.\n\n`bash\n$ ls -l /usr/lib64/mysql/plugin/server_audit2.so\n`\n\n`bash\n-rwxr-xr-x. 1 root root 70432 Jul 15 19:03 /usr/lib64/mysql/plugin/server_audit2.so\n`\n\nMariaDB Enterprise Audit is bundled with all MariaDB Enterprise Server distributions (binary tarball, DEB/RPM package tarball, and DEB/RPM packages). If you do not see the server_audit2.so file, verify that MariaDB Enterprise Server has been installed correctly.\n\nLoad the Audit Plugin\n\nMariaDB Enterprise Audit is enabled through the mariadb-enterprise.cnf configuration file, which is included by default with MariaDB Enterprise Server. This means manual loading is usually not required.\n\nThe mariadb-enterprise.cnf file activates MariaDB Enterprise Audit by configuring the plugin-load-add and server-audit options.\n\n`ini\n-- Auditing - pre-load Plugin\nplugin-load-add=server_audit\nserver_audit=FORCE_PLUS_PERMANENT\n`\n\nIf your environment does not use mariadb-enterprise.cnf, you can enable MariaDB Enterprise Audit by adding the same options to your own configuration file.\n\nConfirm the Audit Plugin is Loaded\n\nTo verify that MariaDB Enterprise Audit is installed, check the information_schema.PLUGINS table.\n\n`sql\nSELECT PLUGIN_STATUS, PLUGIN_LIBRARY, PLUGIN_DESCRIPTION, LOAD_OPTION\nFROM information_schema.PLUGINS\nWHERE PLUGIN_NAME='SERVER_AUDIT'\\G\n`\n\n`sql\n************************ 1. row ***********************\n     PLUGIN_STATUS: ACTIVE\n    PLUGIN_LIBRARY: server_audit2.so\nPLUGIN_DESCRIPTION: MariaDB Enterprise Audit\n       LOAD_OPTION: FORCE_PLUS_PERMANENT\n`\n\nMariaDB Enterprise Audit is enabled through the mariadb-enterprise.cnf configuration file, which is included by default in MariaDB Enterprise Server. If your results differ from the example output above, verify that the mariadb-enterprise.cnf file specifies the plugin-load-add and server-audit options.\n\nStart Audit Logging\n\nWhen MariaDB Enterprise Audit is installed and loaded, audit logging does not begin automatically. You must explicitly start it, either from the shell or through SQL.\n\n<table><thead><tr><th width="111">Interface</th><th width="207">Method</th><th>Benefits</th></tr></thead><tbody><tr><td>Shell</td><td><a href="mariadb-enterprise-audit.md#start-audit-logging-in-configuration-file">Configuration File</a></td><td>SQL access is not required SUPER privilege is not required Configuration file can be version controlled.</td></tr><tr><td>SQL</td><td><a href="mariadb-enterprise-audit.md#start-audit-logging-with-set-global">SET GLOBAL Statement</a></td><td>Server restart is not required.</td></tr></tbody></table>\n\nStart Audit Logging in Configuration File\n\nEnable audit logging with MariaDB Enterprise Audit by setting the server_audit_logging system variable in a configuration file. Alternatively, enable it dynamically with SET GLOBAL, which does not require a server restart.\n\nTo configure in a file:\n\n1\\. Set the server_audit_logging system variable in the configuration file.\n\n`ini\n[mariadb]\nserver_audit_logging = ON\n`\n\n2. Restart MariaDB Enterprise Server:\n\n`bash\n$ sudo systemctl restart mariadb\n`\n\nIf the server does not start, review the error log for details.\n\n3. To confirm that audit logging is running, check the value of the Server_audit_active status variable using the SHOW GLOBAL STATUS statement.\n\n`sql\nSHOW GLOBAL STATUS\n   LIKE 'Server_audit_active';\n`\n\n`sql\n+---------------------+-------+\n| Variable_name       | Value |\n+---------------------+-------+\n| Server_audit_active | ON    |\n+---------------------+-------+\n`\n\nStart Audit Logging with SET GLOBAL\n\nAudit logging with MariaDB Enterprise Audit can be started by setting the server_audit_logging system variable with the SET GLOBAL statement, which requires the SUPER privilege.\n\n1. Set the server_audit_logging system variable with the SET GLOBAL statement:\n\n`sql\nSET GLOBAL server_audit_logging=ON;\n`\n\n2. Confirm that audit logging is started by querying the Server_audit_active status variable with the SHOW GLOBAL STATUS statement:\n\n`sql\nSHOW GLOBAL STATUS\n   LIKE 'Server_audit_active';\n`\n\n`sql\n+---------------------+-------+\n| Variable_name       | Value |\n+---------------------+-------+\n| Server_audit_active | ON    |\n+---------------------+-------+\n`\n\nWhen you modify a system variable dynamically using the SET GLOBAL statement, the change is not preserved after a server restart. To ensure audit logging automatically starts with the server, also configure the server_audit_logging system variable in a configuration file.\n\n`ini\n[mariadb]\nserver_audit_logging = ON\n`\n\nConfirm Audit Logging is Started\n\nConfirm that audit logging is started by querying the Server_audit_active status variable with the SHOW GLOBAL STATUS statement:\n\n`sql\nSHOW GLOBAL STATUS\n   LIKE 'Server_audit_active';\n`\n\n`sql\n+---------------------+-------+\n| Variable_name       | Value |\n+---------------------+-------+\n| Server_audit_active | ON    |\n+---------------------+-------+\n`\n\nAudit Logging Buffer Writes\n\nBuffer writes are available from MariaDB Enterprise Server 11.8.\n\nAudit log buffering is controlled by these variables:\n\n server_audit_file_buffer_size — This defines the size of the buffer. The default value is 0, meaning there's no buffering at all. Setting non-zero value enables the buffering with the buffer of the specified size aligned by 8192. The maximum value is 65536.\n server_audit_sync_log_file — This flushes the buffer to the log file. While the log record is in the buffer, it cannot be seen in the log file. If there aren't many events to log, the time before records can be observed can be significant. You can issue this statement to force writing the buffer to the file, making sure not to miss recent records:\n\n`sql\nSET GLOBAL server_audit_log_file=1\n`\n\nForbid Uninstallation\n\nIn a secure environment, MariaDB Enterprise Audit provides administrators with an audit trail of actions performed by users on the MariaDB Enterprise Server node. To protect the integrity of the audit trail, users should not be able to uninstall MariaDB Enterprise Audit. If the server-audit option is set to FORCE_PLUS_PERMANENT, MariaDB Enterprise Server will prevent MariaDB Enterprise Audit from being uninstalled:\n\n`ini\nserver_audit=FORCE_PLUS_PERMANENT\n`\n\nWhen a user tries to uninstall MariaDB Enterprise Audit with the server-audit option set to FORCE_PLUS_PERMANENT, the operation fails with the ER_PLUGIN_IS_PERMANENT error code:\n\n`sql\nUNINSTALL SONAME 'server_audit2';\n`\n\n`sql\nERROR 1702 (HY000): Plugin 'SERVER_AUDIT' is force_plus_permanent and can not be unloaded\n`\n\nThe mariadb-enterprise.cnf configuration file included by default in MariaDB Enterprise Server sets the server-audit option to FORCE_PLUS_PERMANENT. As a consequence, MariaDB Enterprise Server forbids MariaDB Enterprise Audit from being uninstalled by default.\n\nIf you do not use mariadb-enterprise.cnf in your environment, you can configure MariaDB Enterprise Audit to forbid uninstallation by setting the server-audit option in your configuration file.\n\nConfirm that Uninstallation is Forbidden\n\nTo confirm that MariaDB Enterprise Audit is configured to forbid uninstallation, query the information_schema.PLUGINS table:\n\n`sql\nSELECT PLUGIN_STATUS, PLUGIN_LIBRARY, PLUGIN_DESCRIPTION, LOAD_OPTION\nFROM information_schema.PLUGINS\nWHERE PLUGIN_NAME='SERVER_AUDIT'\\G\n`\n\n`sql\n*********************** 1. row ***********************\n     PLUGIN_STATUS: ACTIVE\n    PLUGIN_LIBRARY: server_audit2.so\nPLUGIN_DESCRIPTION: MariaDB Enterprise Audit\n       LOAD_OPTION: FORCE_PLUS_PERMANENT\n`\n\nIf your output does not match the example output shown above, confirm that the mariadb-enterprise.cnf configuration file sets the server-audit option to FORCE_PLUS_PERMANENT.\n\nServer Startup Behavior\n\nSome specific server startup behavior is described in the sections below.\n\nFor examples of error messages that can appear in the MariaDB error log during server startup, see Messages\n\n[Truncated — full content at mariadb.com/docs]