This section describes the command options and system variables
that control operation of MySQL Enterprise Audit. If values specified at
startup time are incorrect, the audit_log
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:
| Introduced | 5.5.28 | ||
| Command-Line Format | --audit-log[=value] | ||
| 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 plugin has been previously registered
with INSTALL PLUGIN or is
loaded with --plugin-load.
See Section 6.5.2.1, “Installing MySQL Enterprise Audit”.
The option value should be one of those available for
plugin-loading options, as described in
Section 5.5.2, “Installing and Uninstalling Plugins”. For example,
--audit-log=FORCE_PLUS_PERMANENT
tells the server to load the plugin at startup and prevents
it from being removed while the server is running.
This option was added in MySQL 5.5.28.
If the audit_log plugin is enabled, 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.
| Introduced | 5.5.28 | ||
| Command-Line Format | --audit_log_buffer_size=value | ||
| System Variable | Name | audit_log_buffer_size | |
| Variable Scope | Global | ||
| Dynamic Variable | No | ||
| Permitted Values (32-bit platforms) | Type | integer | |
| Default | 1048576 | ||
| Min Value | 4096 | ||
| Max Value | 4294967295 | ||
| Permitted Values (64-bit platforms) | Type | integer | |
| Default | 1048576 | ||
| Min Value | 4096 | ||
| Max Value | 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 was added in MySQL 5.5.28.
| Introduced | 5.5.28 | ||
| Command-Line Format | --audit_log_file=file_name | ||
| System Variable | Name | audit_log_file | |
| Variable Scope | Global | ||
| Dynamic Variable | No | ||
| Permitted Values | Type | file name | |
| 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 was added in MySQL 5.5.28.
| Introduced | 5.5.28 | ||
| 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 was added in MySQL 5.5.28.
| Introduced | 5.5.34 | ||
| Command-Line Format | --audit_log_format=value | ||
| System Variable | Name | audit_log_format | |
| Variable Scope | Global | ||
| Dynamic Variable | No | ||
| Permitted Values (>= 5.5.34) | Type | enumeration | |
| Default | OLD | ||
| Valid Values | OLD | ||
NEW | |||
The audit log file format. Permitted values are
OLD and NEW (default
OLD). For details about each format, see
Section 6.5.2.3, “The Audit Log File”.
If you change the value of
audit_log_format, use this
procedure to avoid writing log entries in one format to an
existing log file that contains entries in a different
format:
Stop the server.
Rename the current audit log file manually.
Restart the server with the new value of
audit_log_format. The
audit log plugin will create a new log file, which will
contain log entries in the selected format.
This variable was added in MySQL 5.5.34.
| Introduced | 5.5.28 | ||
| Command-Line Format | --audit_log_policy=value | ||
| System Variable | Name | audit_log_policy | |
| Variable Scope | Global | ||
| Dynamic Variable | Yes | ||
| Permitted Values | Type | enumeration | |
| Default | ALL | ||
| Valid Values | ALL | ||
LOGINS | |||
QUERIES | |||
NONE | |||
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 was added in MySQL 5.5.28.
| Introduced | 5.5.28 | ||
| Command-Line Format | --audit_log_rotate_on_size=N | ||
| System Variable | Name | audit_log_rotate_on_size | |
| Variable Scope | Global | ||
| Dynamic Variable | Yes | ||
| Permitted Values | Type | integer | |
| 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.5.2.4, “Audit Log Logging Control”.
If you set this variable to a value that is not a multiple of 4096, it is truncated to the nearest multiple. (Thus, setting it to a value less than 4096 has the effect of setting it to 0 and no rotation occurs.)
This variable was added in MySQL 5.5.28.
| Introduced | 5.5.28 | ||
| Command-Line Format | --audit_log_strategy=value | ||
| 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.17 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 was added in MySQL 5.5.28.