MySQL 5.6 Reference Manual Including MySQL NDB Cluster 7.3-7.4 Reference Guide

6.4.4.6 Audit Log Reference

The following sections provide a reference to MySQL Enterprise Audit elements:

Audit Log Option and Variable Reference

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

Audit Log Options and System Variables

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:

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.

  • audit_log_buffer_size

    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

    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.

  • audit_log_connection_policy

    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
    Note

    At server startup, any explicit value given for audit_log_connection_policy may be overridden if audit_log_policy is also specified, as described in Section 6.4.4.4, “Audit Log Logging Control”.

  • audit_log_current_session

    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 and audit_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.)

  • audit_log_exclude_accounts

    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.

  • audit_log_file

    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 of audit_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, “Audit Log Logging Control”.

  • audit_log_flush

    System Variable audit_log_flush
    Scope Global
    Dynamic Yes
    Type Boolean
    Default Value 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. For more information, see Section 6.4.4.4, “Audit Log Logging Control”.

  • audit_log_format

    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 and NEW (default OLD). For details about each format, see Section 6.4.4.3, “Audit Log File Formats”.

    Note

    Changing 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.

  • audit_log_include_accounts

    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.

  • audit_log_policy

    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 and audit_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 use audit_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, “Audit Log Logging Control”.

    Before MySQL 5.6.20, the audit_log_connection_policy and audit_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.

  • audit_log_rotate_on_size

    Command-Line Format --audit-log-rotate-on-size=#
    System Variable audit_log_rotate_on_size
    Scope Global
    Dynamic Yes
    Type Integer
    Default Value 0
    Unit bytes

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

    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 the audit_log_rotate_on_size value, the audit log plugin closes the current log file, renames it, and opens a new log file.

    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. (Thus, setting it to a value less than 4096 has the effect of setting it to 0 and no rotation occurs, except manually.)

    For more information about audit log file rotation, see Space Management and Rotation of Audit Log Files.

  • audit_log_statement_policy

    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
    Note

    At server startup, any explicit value given for audit_log_statement_policy may be overridden if audit_log_policy is also specified, as described in Section 6.4.4.4, “Audit Log Logging Control”.

  • audit_log_strategy

    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. Call sync() after each request.

Audit Log Plugin Status Variables

If the audit log plugin is enabled, it exposes several status variables that provide operational information.

MySQL Documentation Library