The following sections provide a reference to MySQL Enterprise Audit elements:
Table 6.16 Audit Log Option and Variable Reference
Name | Cmd-Line | Option File | System Var | Status Var | Var Scope | Dynamic |
---|---|---|---|---|---|---|
audit-log | Yes | Yes | ||||
audit_log_buffer_size | Yes | Yes | Yes | Global | No | |
audit_log_connection_policy | Yes | Yes | Yes | Global | Yes | |
audit_log_current_session | Yes | Both | No | |||
Audit_log_current_size | Yes | Global | No | |||
Audit_log_event_max_drop_size | Yes | Global | No | |||
Audit_log_events | Yes | Global | No | |||
Audit_log_events_filtered | Yes | Global | No | |||
Audit_log_events_lost | Yes | Global | No | |||
Audit_log_events_written | Yes | Global | No | |||
audit_log_exclude_accounts | Yes | Yes | Yes | Global | Yes | |
audit_log_file | Yes | Yes | Yes | Global | No | |
audit_log_flush | Yes | Global | Yes | |||
audit_log_format | Yes | Yes | Yes | Global | No | |
audit_log_include_accounts | Yes | Yes | Yes | Global | Yes | |
audit_log_policy | Yes | Yes | Yes | Global | Varies | |
audit_log_rotate_on_size | Yes | Yes | Yes | Global | Yes | |
audit_log_statement_policy | Yes | Yes | Yes | Global | Yes | |
audit_log_strategy | Yes | Yes | Yes | Global | No | |
Audit_log_total_size | Yes | Global | No | |||
Audit_log_write_waits | Yes | Global | No |
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 does not recognize them.
To control activation of the audit log plugin, use this option:
-
Command-Line Format --audit-log[=value]
Type Enumeration Default Value 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 withINSTALL PLUGIN
or is loaded with--plugin-load
or--plugin-load-add
. See Section 6.4.4.1, “Installing MySQL Enterprise Audit”.The option value should be one of those available for plugin-loading options, as described in Section 5.5.1, “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.
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_connection_policy | ALL |
| audit_log_current_session | ON |
| audit_log_exclude_accounts | |
| audit_log_file | audit.log |
| audit_log_flush | OFF |
| audit_log_format | OLD |
| audit_log_include_accounts | |
| audit_log_policy | ALL |
| audit_log_rotate_on_size | 0 |
| audit_log_statement_policy | ALL |
| audit_log_strategy | ASYNCHRONOUS |
+-----------------------------+--------------+
You can set any of these variables at server startup, and some of them at runtime.
-
Command-Line Format --audit-log-buffer-size=#
System Variable audit_log_buffer_size
Scope Global Dynamic No Type Integer Default Value 1048576
Minimum Value 4096
Maximum Value (64-bit platforms) 18446744073709547520
Maximum Value (32-bit platforms) 4294967295
Unit bytes Block Size 4096
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.
-
Command-Line Format --audit-log-connection-policy=value
Introduced 5.6.20 System Variable audit_log_connection_policy
Scope Global Dynamic Yes Type Enumeration Default Value ALL
Valid Values ALL
ERRORS
NONE
The policy controlling how the audit log plugin writes connection events to its log file. The following table shows the permitted values.
Value Description ALL
Log all connection events ERRORS
Log only failed connection events NONE
Do not log connection events NoteAt server startup, any explicit value given for
audit_log_connection_policy
may be overridden ifaudit_log_policy
is also specified, as described in Section 6.4.4.4, “Configuring Audit Logging Characteristics”. -
Introduced 5.6.20 System Variable audit_log_current_session
Scope Global, Session Dynamic No Type Boolean Default Value depends on filtering policy
Whether audit logging is enabled for the current session. The session value of this variable is read only. It is set when the session begins based on the values of the
audit_log_include_accounts
andaudit_log_exclude_accounts
system variables. The audit log plugin uses the session value to determine whether to audit events for the session. (There is a global value, but the plugin does not use it.) -
Command-Line Format --audit-log-exclude-accounts=value
Introduced 5.6.20 System Variable audit_log_exclude_accounts
Scope Global Dynamic Yes Type String Default Value NULL
The accounts for which events should not be logged. The value should be
NULL
or a string containing a list of one or more comma-separated account names. For more information, see Section 6.4.4.5, “Audit Log Filtering”.Modifications to
audit_log_exclude_accounts
affect only connections created subsequent to the modification, not existing connections. -
Command-Line Format --audit-log-file=file_name
System Variable audit_log_file
Scope Global Dynamic No Type File name Default Value audit.log
The name of the file to which the audit log plugin writes events. The default value is
audit.log
. If the value ofaudit_log_file
is a relative path name, the plugin interprets it relative to the data directory. If the value is a full path name, the plugin uses the value as is. A full path name may be useful if it is desirable to locate audit files on a separate file system or directory. For security reasons, the audit log file should be written to a directory accessible only to the MySQL server and to users with a legitimate reason to view the log. For more information, see Section 6.4.4.4, “Configuring Audit Logging Characteristics”. -
System Variable audit_log_flush
Scope Global Dynamic Yes Type Boolean Default Value OFF
If
audit_log_rotate_on_size
is 0, automatic audit log file rotation is disabled and rotation occurs only when performed manually. In that case, enablingaudit_log_flush
by setting it to 1 orON
causes the audit log plugin to close and reopen its log file to flush it. (The variable value remainsOFF
so that you need not disable it explicitly before enabling it again to perform another flush.) For more information, see Section 6.4.4.4, “Configuring Audit Logging Characteristics”. -
Command-Line Format --audit-log-format=value
Introduced 5.6.14 System Variable audit_log_format
Scope Global Dynamic No Type Enumeration Default Value OLD
Valid Values OLD
NEW
The audit log file format. Permitted values are
OLD
andNEW
(defaultOLD
). For details about each format, see Section 6.4.4.3, “Audit Log File Formats”.NoteChanging the value of
audit_log_format
can result in writing log entries in one format to an existing log file that contains entries in a different format. To avoid this issue, use the procedure described at Audit Log File Format. -
Command-Line Format --audit-log-include-accounts=value
Introduced 5.6.20 System Variable audit_log_include_accounts
Scope Global Dynamic Yes Type String Default Value NULL
The accounts for which events should be logged. The value should be
NULL
or a string containing a list of one or more comma-separated account names. For more information, see Section 6.4.4.5, “Audit Log Filtering”.Modifications to
audit_log_include_accounts
affect only connections created subsequent to the modification, not existing connections. -
Command-Line Format --audit-log-policy=value
System Variable audit_log_policy
Scope Global Dynamic (≥ 5.6.20) No Dynamic (≤ 5.6.19) Yes Type Enumeration Default Value ALL
Valid Values ALL
LOGINS
QUERIES
NONE
The policy controlling how the audit log plugin writes events to its log file. The following table shows the permitted values.
Value Description ALL
Log all events LOGINS
Log only login events QUERIES
Log only query events NONE
Log nothing (disable the audit stream) As of MySQL 5.6.20,
audit_log_policy
can be set only at server startup. At runtime, it is a read-only variable. This is due to the introduction of two other system variables,audit_log_connection_policy
andaudit_log_statement_policy
, that provide finer control over logging policy and that can be set either at startup or at runtime. If you continue to useaudit_log_policy
at startup instead of the other two variables, the server uses its value to set those variables. For more information about the policy variables and their interaction, see Section 6.4.4.4, “Configuring Audit Logging Characteristics”.Before MySQL 5.6.20, the
audit_log_connection_policy
andaudit_log_statement_policy
system variables do not exist.audit_log_policy
is the only policy control variable and it can be set at server startup or runtime. -
Command-Line Format --audit-log-rotate-on-size=#
System Variable audit_log_rotate_on_size
Scope Global Dynamic Yes Type Integer Default Value 0
Minimum Value 0
Maximum Value 18446744073709551615
Unit bytes Block Size 4096
If
audit_log_rotate_on_size
is 0, the audit log plugin does not perform automatic size-based log file rotation. If rotation is to occur, you must perform it manually; see Manual Audit Log File Rotation.If
audit_log_rotate_on_size
is greater than 0, automatic size-based log file rotation occurs. Whenever a write to the log file causes its size to exceed theaudit_log_rotate_on_size
value, the audit log plugin renames the current log file and opens a new current log file using the original name.If you set
audit_log_rotate_on_size
to a value that is not a multiple of 4096, it is truncated to the nearest multiple. In particular, setting it to a value less than 4096 sets it to 0 and no rotation occurs, except manually.For more information about audit log file rotation, see Space Management of Audit Log Files.
-
Command-Line Format --audit-log-statement-policy=value
Introduced 5.6.20 System Variable audit_log_statement_policy
Scope Global Dynamic Yes Type Enumeration Default Value ALL
Valid Values ALL
ERRORS
NONE
The policy controlling how the audit log plugin writes statement events to its log file. The following table shows the permitted values.
Value Description ALL
Log all statement events ERRORS
Log only failed statement events NONE
Do not log statement events NoteAt server startup, any explicit value given for
audit_log_statement_policy
may be overridden ifaudit_log_policy
is also specified, as described in Section 6.4.4.4, “Configuring Audit Logging Characteristics”. -
Command-Line Format --audit-log-strategy=value
System Variable audit_log_strategy
Scope Global Dynamic No Type Enumeration Default Value ASYNCHRONOUS
Valid Values ASYNCHRONOUS
PERFORMANCE
SEMISYNCHRONOUS
SYNCHRONOUS
The logging method used by the audit log plugin. These strategy values are permitted:
ASYNCHRONOUS
: Log asynchronously. Wait for space in the output buffer.PERFORMANCE
: Log asynchronously. Drop requests for which there is insufficient space in the output buffer.SEMISYNCHRONOUS
: Log synchronously. Permit caching by the operating system.SYNCHRONOUS
: Log synchronously. Callsync()
after each request.
If the audit log plugin is enabled, it exposes several status variables that provide operational information.
The size of the current audit log file. The value increases when an event is written to the log and is reset to 0 when the log is rotated.
The size of the largest dropped event in performance logging mode. For a description of logging modes, see Section 6.4.4.4, “Configuring Audit Logging Characteristics”.
The number of events handled by the audit log plugin, whether or not they were written to the log based on filtering policy (see Section 6.4.4.4, “Configuring Audit Logging Characteristics”).
The number of events handled by the audit log plugin that were filtered (not written to the log) based on filtering policy (see Section 6.4.4.4, “Configuring Audit Logging Characteristics”).
The number of events lost in performance logging mode because an event was larger than the available audit log buffer space. This value may be useful for assessing how to set
audit_log_buffer_size
to size the buffer for performance mode. For a description of logging modes, see Section 6.4.4.4, “Configuring Audit Logging Characteristics”.The number of events written to the audit log.
The total size of events written to all audit log files. Unlike
Audit_log_current_size
, the value ofAudit_log_total_size
increases even when the log is rotated.The number of times an event had to wait for space in the audit log buffer in asynchronous logging mode. For a description of logging modes, see Section 6.4.4.4, “Configuring Audit Logging Characteristics”.