6.4.5.9 Audit Log Reference

NAME

The filter name.

FILTER

The filter definition associated with the filter name. Definitions are stored as JSON values.

USER

The user name part of an account. For an account user1@localhost, the USER part is user1.

HOST

The host name part of an account. For an account user1@localhost, the HOST part is localhost.

FILTERNAME

The name of the filter assigned to the account. The filter name associates the account with a filter defined in the audit_log_filter table.

audit_log_encryption_password_get([keyring_id])

This function fetches an audit log encryption password from the MySQL keyring, which must be enabled or an error occurs. Any keyring plugin can be used; for instructions, see Section 6.4.4, “The MySQL Keyring”.

With no argument, the function retrieves the current encryption password as a binary string. An argument may be given to specify which audit log encryption password to retrieve. The argument must be the keyring ID of the current password or an archived password.

For additional information about audit log encryption, see Audit Log File Encryption.

Arguments:

keyring_id: As of MySQL 8.0.17, this optional argument indicates the keyring ID of the password to retrieve. The maximum permitted length is 766 bytes. If omitted, the function retrieves the current password.

Prior to MySQL 8.0.17, no argument is permitted. The function always retrieves the current password.

Return value:

The password string for success (up to 766 bytes), or NULL and an error for failure.

Example:

Retrieve the current password:

To retrieve a password by ID, you can determine which audit log keyring IDs exist by querying the Performance Schema keyring_keys table:

audit_log_encryption_password_set(password)

Sets the current audit log encryption password to the argument and stores the password in the MySQL keyring. If encryption is enabled, the function performs a log file rotation operation that renames the current log file, and begins a new log file encrypted with the password. The keyring must be enabled or an error occurs. Any keyring plugin can be used; for instructions, see Section 6.4.4, “The MySQL Keyring”.

For additional information about audit log encryption, see Audit Log File Encryption.

Arguments:

password: The password string. The maximum permitted length is 766 bytes.

Return value:

1 for success, 0 for failure.

Example:

audit_log_filter_flush()

Calling any of the other filtering UDFs affects operational audit log filtering immediately and updates the audit log tables. If instead you modify the contents of those tables directly using statements such as INSERT, UPDATE, and DELETE, the changes do not affect filtering immediately. To flush your changes and make them operational, call audit_log_filter_flush().

If this function fails, an error message is returned and the audit log is disabled until the next successful call to audit_log_filter_flush().

Arguments:

None.

Return value:

A string that indicates whether the operation succeeded. OK indicates success. ERROR: message indicates failure.

Example:

audit_log_filter_remove_filter(filter_name)

Given a filter name, removes the filter from the current set of filters. It is not an error for the filter not to exist.

If a removed filter is assigned to any user accounts, those users stop being filtered (they are removed from the audit_log_user table). Termination of filtering includes any current sessions for those users: They are detached from the filter and no longer logged.

Arguments:

Return value:

A string that indicates whether the operation succeeded. OK indicates success. ERROR: message indicates failure.

Example:

audit_log_filter_remove_user(user_name)

Given a user account name, cause the user to be no longer assigned to a filter. It is not an error if the user has no filter assigned. Filtering of current sessions for the user remains unaffected. New connections for the user are filtered using the default account filter if there is one, and are not logged otherwise.

If the name is %, the function removes the default account filter that is used for any user account that has no explicitly assigned filter.

Arguments:

Return value:

A string that indicates whether the operation succeeded. OK indicates success. ERROR: message indicates failure.

Example:

audit_log_filter_set_filter(filter_name, definition)

Given a filter name and definition, adds the filter to the current set of filters. If the filter already exists and is used by any current sessions, those sessions are detached from the filter and are no longer logged. This occurs because the new filter definition has a new filter ID that differs from its previous ID.

Arguments:

Return value:

A string that indicates whether the operation succeeded. OK indicates success. ERROR: message indicates failure.

Example:

audit_log_filter_set_user(user_name, filter_name)

Given a user account name and a filter name, assigns the filter to the user. A user can be assigned only one filter, so if the user was already assigned a filter, the assignment is replaced. Filtering of current sessions for the user remains unaffected. New connections are filtered using the new filter.

As a special case, the name % represents the default account. The filter is used for connections from any user account that has no explicitly assigned filter.

Arguments:

Return value:

A string that indicates whether the operation succeeded. OK indicates success. ERROR: message indicates failure.

Example:

audit_log_read([arg])

Reads events from the audit log and returns a binary JSON string containing an array of audit events. If the audit log format is not JSON, an error occurs.

Each event in the return value is a JSON hash, except that the last array element may be a JSON null value to indicate no following events are available to read.

For the first call to audit_log_read() within a session, pass a bookmark indicating where to begin reading. If the final value of the returned array is not a JSON null value, there are more events following those just read and audit_log_read() can be called without or with a bookmark argument. Without an argument, reading continues with the next unread event. With a bookmark argument, reading continues from the bookmark.

If the final value of the returned array is a JSON null value, there are no more events left to be read and the next call to audit_log_read() must include a bookmark argument.

To obtain a bookmark for the most recently written event, call audit_log_read_bookmark().

For additional information about audit log-reading functions, see Audit Log File Reading.

Arguments:

arg: An optional bookmark, represented as a string containing a JSON hash that indicates where and how much to read. The following items are significant in the arg value (other items are ignored):

Return value:

A binary JSON string containing an array of audit events for success, or NULL and an error for failure.

Example:

audit_log_read_bookmark()

Returns a binary JSON string representing a bookmark for the most recently written audit log event. If the audit log format is not JSON, an error occurs.

The bookmark is a JSON hash with timestamp and id items indicating the event position within the audit log. It is suitable for passing to audit_log_read() to indicate to that function where to begin reading.

For additional information about audit log-reading functions, see Audit Log File Reading.

Arguments:

None.

Return value:

A binary JSON string containing a bookmark for success, or NULL and an error for failure.

Example:

--audit-log[=value]

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 or --plugin-load-add. See Section 6.4.5.2, “Installing or Uninstalling MySQL Enterprise Audit”.

The option value should be one of those available for plugin-loading options, as described in Section 5.6.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.

audit_log_buffer_size

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

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

The policy controlling how the audit log plugin writes connection events to its log file. The following table shows the permitted values.

audit_log_current_session

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

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

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

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, write the audit log file 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.

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

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

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.5.5, “Audit Log Logging Configuration”.

audit_log_format

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

audit_log_include_accounts

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

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

audit_log_password_history_keep_days

When a new encryption password is created, the audit log plugin archives the previous password, if one exists, for later use. The audit_log_password_history_keep_days variable controls automatic removal of archived passwords. Its value indicates the number of days after which archived audit log encryption passwords are removed. The default is 0, which disables password removal; the password retention period is forever.

New audit log encryption passwords are created under these circumstances:

In each case, the plugin stores the password in the key ring and uses it to encrypt new log files.

Cleanup of old audit log encryption passwords occurs under these circumstances:

When password cleanup occurs, the current value of audit_log_password_history_keep_days determines which passwords to remove:

If you normally leave password expiration disabled (audit_log_password_history_keep_days=0), it is possible to perform an on-demand cleanup operation by temporarily assigning the variable a value greater than zero. For example, to expire passwords older than 365 days, do this:

Setting the runtime value of audit_log_password_history_keep_days requires the AUDIT_ADMIN privilege, in addition to the SYSTEM_VARIABLES_ADMIN or SUPER privilege normally required to set a global system variable runtime value.

audit_log_policy

The policy controlling how the audit log plugin writes events to its log file. The following table shows the permitted values.

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 6.4.5.5, “Audit Log Logging Configuration”.

audit_log_read_buffer_size

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 log format. For more information, see Audit Log File Reading.

As of MySQL 8.0.12, 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 8.0.12, 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

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

The policy controlling how the audit log plugin writes statement events to its log file. The following table shows the permitted values.

audit_log_strategy

The logging method used by the audit log plugin. These strategy values are permitted:

Audit_log_current_size

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.

Audit_log_event_max_drop_size

The size of the largest dropped event in performance logging mode. For a description of logging modes, see Section 6.4.5.5, “Audit Log Logging Configuration”.

Audit_log_events

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.5.5, “Audit Log Logging Configuration”).

Audit_log_events_filtered

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.5.5, “Audit Log Logging Configuration”).

Audit_log_events_lost

The number of events lost in performance logging mode because an event was larger than 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.5.5, “Audit Log Logging Configuration”.

Audit_log_events_written

The number of events written to the audit log.

Audit_log_total_size

The total size of events written to all audit log files. Unlike Audit_log_current_size, the value of Audit_log_total_size increases even when the log is rotated.

Audit_log_write_waits

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.5.5, “Audit Log Logging Configuration”.