6.3.11.5. Audit Log Plugin Options and Variables

This section describes the command options and system variables that control operation of the audit log plugin. If values specified at startup time are incorrect, the plugin may fail to initialize properly and the server does not load it. In this case, the server may also produce error messages for other audit log settings because it will not recognize them.

To control the activation of the audit_log plugin, use this option:

--audit-log[=value]

Command-Line Format	`--audit-log[=value]`
Option-File Format	`audit-log`
	Permitted Values
	Type	`enumeration`
	Default	`ON`
	Valid Values	`ON`
		`OFF`
		`FORCE`
		`FORCE_PLUS_PERMANENT`

This option controls how the server loads the audit_log plugin at startup. It is available only if the audit log plugin has been previously registered with INSTALL PLUGIN or is loaded with --plugin-load. See Section 6.3.11.1, "Installing the Audit Log Plugin".

The option value should be one of those available for plugin-loading options, as described in Section 5.1.8.1, "Installing and Uninstalling Plugins". For example, --audit-log=FORCE_PLUS_PERMANENT tells the server to load the plugin and prevent it from being removed while the server is running.

If the audit_log plugin is installed, it exposes several system variables that permit control over logging:

mysql> SHOW VARIABLES LIKE
        'audit_log%';+--------------------------+--------------+| Variable_name            | Value        |+--------------------------+--------------+| audit_log_buffer_size    | 1048576      || audit_log_file           | audit.log    || audit_log_flush          | OFF          || audit_log_policy         | ALL          || audit_log_rotate_on_size | 0            || audit_log_strategy       | ASYNCHRONOUS |+--------------------------+--------------+

You can set any of these variables at server startup, and some of them at runtime.

audit_log_buffer_size

System Variable Name	`audit_log_buffer_size`
Variable Scope	Global
Dynamic Variable	No
	Permitted Values
	Platform Bit Size	`32`
	Type	`numeric`
	Default	`1048576`
	Range	`4096 .. 4294967295`
	Permitted Values
	Platform Bit Size	`64`
	Type	`numeric`
	Default	`1048576`
	Range	`4096 .. 18446744073709547520`

When the audit log plugin writes events to the log asynchronously, it uses a buffer to store event contents prior to writing them. This variable controls the size of that buffer, in bytes. The server adjusts the value to a multiple of 4096. The plugin uses a single buffer, which it allocates when it initializes and removes when it terminates. The plugin allocates this buffer only if logging is asynchronous.

This variable is available only if the audit_log plugin is enabled.

audit_log_file

System Variable Name	`audit_log_file`
Variable Scope	Global
Dynamic Variable	No
	Permitted Values
	Type	`string`
	Default	`audit.log`

The name of the file to which the audit log plugin writes events. The default value is audit.log. If the file name is a relative path, the server interprets it relative to the data directory. For security reasons, the audit log file should be written to a directory accessible only to the MySQL server and users with a legitimate reason to view the log.

This variable is available only if the audit_log plugin is enabled.

audit_log_flush

System Variable Name	`audit_log_flush`
Variable Scope	Global
Dynamic Variable	Yes
	Permitted Values
	Type	`boolean`
	Default	`OFF`

When this variable is set to enabled (1 or ON), the audit log plugin closes and reopens its log file to flush it. (The value remains OFF so that you need not disable it explicitly before enabling it again to perform another flush.) Enabling this variable has no effect unless audit_log_rotate_on_size is 0.

This variable is available only if the audit_log plugin is enabled.

audit_log_policy

System Variable Name	`audit_log_policy`
Variable Scope	Global
Dynamic Variable	Yes
	Permitted Values
	Type	`enumeration`
	Default	`ALL`
	Valid Values	`ALL`
		`NONE`
		`LOGINS`
		`QUERIES`

The policy controlling the information written by the audit log plugin to its log file. The following table shows the permitted values.

Value	Description
`ALL`	Log all events
`NONE`	Log nothing (disable the audit stream)
`LOGINS`	Log only login events
`QUERIES`	Log only query events

This variable is available only if the audit_log plugin is enabled.

audit_log_rotate_on_size

System Variable Name	`audit_log_rotate_on_size`
Variable Scope	Global
Dynamic Variable	Yes
	Permitted Values
	Type	`numeric`
	Default	`0`

If the audit_log_rotate_on_size value is greater than 0, the audit log plugin closes and reopens its log file if a write to the file causes its size to exceed this value. The original file is renamed to have a timestamp extension.

If the audit_log_rotate_on_size value is 0, the plugin does not close and reopen its log based on size. Instead, use audit_log_flush to close and reopen the log on demand. In this case, rename the file externally to the server before flushing it.

For more information about audit log file rotation and timestamp interpretation, see Section 6.3.11.4, "Audit Log Plugin Logging Control".

If you set this variable to a value that is not a multiple of 4096, it is truncated to the nearest multiple.

This variable is available only if the audit_log plugin is enabled.

audit_log_strategy

System Variable Name	`audit_log_strategy`
Variable Scope	Global
Dynamic Variable	No
	Permitted Values
	Type	`enumeration`
	Default	`ASYNCHRONOUS`
	Valid Values	`ASYNCHRONOUS`
		`PERFORMANCE`
		`SEMISYNCHRONOUS`
		`SYNCHRONOUS`

The logging method used by the audit log plugin. The following table describes the permitted values.

Table 6.15. Audit Log Strategies

Value	Meaning
`ASYNCHRONOUS`	Log asynchronously, wait for space in output buffer
`PERFORMANCE`	Log asynchronously, drop request if insufficient space in output buffer
`SEMISYNCHRONOUS`	Log synchronously, permit caching by operating system
`SYNCHRONOUS`	Log synchronously, call `sync()` after each request

This variable is available only if the audit_log plugin is enabled.