Documentation Home
Security in MySQL
Related Documentation Download this Excerpt
PDF (US Ltr) - 1.5Mb
PDF (A4) - 1.5Mb
HTML Download (TGZ) - 315.8Kb
HTML Download (Zip) - 324.5Kb


Security in MySQL  /  ...  /  Audit Log Options and Variables

7.5.8.4 Audit Log Options and 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 will not recognize them.

To control the 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   | OFF          |
| audit_log_exclude_accounts  |              |
| audit_log_file              | audit.log    |
| audit_log_filter_id         | 0            |
| audit_log_flush             | OFF          |
| audit_log_format            | NEW          |
| 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. Those that are available only for legacy mode audit log filtering are so noted.

  • audit_log_buffer_size

    Property Value
    Command-Line Format --audit-log-buffer-size=value
    Introduced 5.7.9
    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_compression

    Property Value
    Command-Line Format --audit-log-compression=value
    Introduced 5.7.21
    System Variable audit_log_compression
    Scope Global
    Dynamic No
    Type Enumeration
    Default Value NONE
    Valid Values

    NONE

    GZIP

    The type of compression for the audit log file. Permitted values are NONE (no compression; the default) and GZIP (GNU Zip compression). For more information, see Audit Log File Compression.

  • audit_log_connection_policy

    Property Value
    Command-Line Format --audit-log-connection-policy=value
    Introduced 5.7.9
    System Variable audit_log_connection_policy
    Scope Global
    Dynamic Yes
    Type Enumeration
    Default Value ALL
    Valid Values

    ALL

    ERRORS

    NONE

    Note

    This variable applies only to legacy mode audit log filtering (see Section 7.5.7, “Legacy Mode Audit Log Filtering”).

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

  • audit_log_current_session

    Property Value
    Introduced 5.7.9
    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_encryption

    Property Value
    Command-Line Format --audit-log-encryption=value
    Introduced 5.7.21
    System Variable audit_log_encryption
    Scope Global
    Dynamic No
    Type Enumeration
    Default Value NONE
    Valid Values

    NONE

    AES

    The type of encryption for the audit log file. Permitted values are NONE (no encryption; the default) and AES (AES-256-CBC cipher encryption). For more information, see Audit Log File Encryption.

  • audit_log_exclude_accounts

    Property Value
    Command-Line Format --audit-log-exclude-accounts=value
    Introduced 5.7.9
    System Variable audit_log_exclude_accounts
    Scope Global
    Dynamic Yes
    Type String
    Default Value NULL
    Note

    This variable applies only to legacy mode audit log filtering (see Section 7.5.7, “Legacy Mode Audit Log Filtering”).

    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 7.5.6, “Audit Log Filtering”.

    Modifications to audit_log_exclude_accounts affect only connections created subsequent to the modification, not existing connections.

  • audit_log_file

    Property Value
    Command-Line Format --audit-log-file=file_name
    Introduced 5.7.9
    System Variable audit_log_file
    Scope Global
    Dynamic No
    Type File name
    Default Value audit.log

    The base name and suffix of the file to which the audit log plugin writes events. The default value is audit.log, regardless of logging format. To have the name suffix correspond to the format, set the name explicitly, choosing a different suffix (for example, audit.xml for XML format, audit.json for JSON format).

    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 details about how the audit log plugin interprets the audit_log_file value and the rules for file renaming that occurs at plugin initialization and termination, see Audit Log File Name.

    As of MySQL 5.7.21, the audit log plugin uses the directory containing the audit log file (determined from the audit_log_file value) as the location to search for readable audit log files. From these log files and the current file, the plugin constructs a list of the ones that are subject to use with the audit log bookmarking and reading functions. See Audit Log File Reading.

  • audit_log_filter_id

    Property Value
    Introduced 5.7.13
    System Variable audit_log_filter_id
    Scope Global, Session
    Dynamic No
    Type Integer

    The session value of this variable indicates the internally maintained ID of the audit filter for the current session. A value of 0 means that the session has no filter assigned.

  • audit_log_flush

    Property Value
    Introduced 5.7.9
    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 7.5.5, “Audit Log Logging Control”.

  • audit_log_format

    Property Value
    Command-Line Format --audit-log-format=value
    Introduced 5.7.9
    System Variable audit_log_format
    Scope Global
    Dynamic No
    Type Enumeration
    Default Value NEW
    Valid Values (>= 5.7.21)

    OLD

    NEW

    JSON

    Valid Values (>= 5.7.9, <= 5.7.20)

    OLD

    NEW

    The audit log file format. Permitted values are OLD (old-style XML), NEW (new-style XML; the default), and (as of MySQL 5.7.21) JSON. For details about each format, see Section 7.5.4, “Audit Log File Formats”.

    Note

    For information about issues to consider when changing the log format, see Audit Log File Format.

  • audit_log_include_accounts

    Property Value
    Command-Line Format --audit-log-include-accounts=value
    Introduced 5.7.9
    System Variable audit_log_include_accounts
    Scope Global
    Dynamic Yes
    Type String
    Default Value NULL
    Note

    This variable applies only to legacy mode audit log filtering (see Section 7.5.7, “Legacy Mode Audit Log Filtering”).

    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 7.5.6, “Audit Log Filtering”.

    Modifications to audit_log_include_accounts affect only connections created subsequent to the modification, not existing connections.

  • audit_log_policy

    Property Value
    Command-Line Format --audit-log-policy=value
    Introduced 5.7.9
    System Variable audit_log_policy
    Scope Global
    Dynamic No
    Type Enumeration
    Default Value ALL
    Valid Values

    ALL

    LOGINS

    QUERIES

    NONE

    Note

    This variable applies only to legacy mode audit log filtering (see Section 7.5.7, “Legacy Mode Audit Log Filtering”).

    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)

    audit_log_policy can be set only at server startup. At runtime, it is a read-only variable. Two other system variables, audit_log_connection_policy and audit_log_statement_policy, provide finer control over logging policy and can be set either at startup or at runtime. If you 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 7.5.5, “Audit Log Logging Control”.

  • audit_log_read_buffer_size

    Property Value
    Command-Line Format --audit-log-read-buffer-size=#
    Introduced 5.7.21
    System Variable audit_log_read_buffer_size
    Scope (>= 5.7.23) Global, Session
    Scope (<= 5.7.22) Global
    Dynamic (>= 5.7.23) Yes
    Dynamic (<= 5.7.22) No
    Type Integer
    Default Value (>= 5.7.23) 32768
    Default Value (<= 5.7.22) 1048576
    Minimum Value (>= 5.7.23) 32768
    Minimum Value (<= 5.7.22) 1024
    Maximum Value 4194304

    The buffer size for reading from the audit log file, in bytes. The audit_log_read() function reads no more than this many bytes. Log file reading is supported only for JSON logging format. For more information, see Audit Log File Reading.

    As of MySQL 5.7.23, this variable has a default of 32KB and can be set at runtime. Each client should set its session value of audit_log_read_buffer_size appropriately for its use of audit_log_read(). Prior to MySQL 5.7.23, audit_log_read_buffer_size has a default of 1MB, affects all clients, and can be changed only at server startup.

  • audit_log_rotate_on_size

    Property Value
    Command-Line Format --audit-log-rotate-on-size=N
    Introduced 5.7.9
    System Variable audit_log_rotate_on_size
    Scope Global
    Dynamic Yes
    Type Integer
    Default Value 0

    If the audit_log_rotate_on_size value is 0, the audit log plugin does not perform automatic 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 the audit_log_rotate_on_size value 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.

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

    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, except manually.)

  • audit_log_statement_policy

    Property Value
    Command-Line Format --audit-log-statement-policy=value
    Introduced 5.7.9
    System Variable audit_log_statement_policy
    Scope Global
    Dynamic Yes
    Type Enumeration
    Default Value ALL
    Valid Values

    ALL

    ERRORS

    NONE

    Note

    This variable applies only to legacy mode audit log filtering (see Section 7.5.7, “Legacy Mode Audit Log Filtering”).

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

  • audit_log_strategy

    Property Value
    Command-Line Format --audit-log-strategy=value
    Introduced 5.7.9
    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.


User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.