MySQL 8.0 Reference Manual Including MySQL NDB Cluster 8.0
The following sections provide a reference to MySQL Enterprise Audit elements:
To install the audit log tables and functions, use the
instructions provided in
Section 6.4.5.2, “Installing or Uninstalling MySQL Enterprise Audit”. Unless those objects
are installed, the audit_log
plugin operates
in legacy mode. See
Section 6.4.5.9, “Legacy Mode Audit Log Filtering”.
MySQL Enterprise Audit uses tables in the mysql
system
database for persistent storage of filter and user account
data. The tables can be accessed only by users who have
privileges for that database. The tables use the
InnoDB
storage engine.
If these tables are missing, the audit_log
plugin operates in legacy mode. See
Section 6.4.5.9, “Legacy Mode Audit Log Filtering”.
The audit_log_filter
table stores filter
definitions. The table has these columns:
NAME
The filter name.
FILTER
The filter definition associated with the filter name.
Definitions are stored as
JSON
values.
The audit_log_user
table stores user
account information. The table has these columns:
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.
This section describes, for each audit log user-defined function (UDF), its purpose, calling sequence, and return value. For information about the conditions under which these UDFs can be invoked, see Section 6.4.5.7, “Audit Log Filtering”.
Each audit log UDF returns a string that indicates whether the
operation succeeded. OK
indicates success.
ERROR:
indicates failure.
message
As of MySQL 8.0.19, audit log UDFs convert string arguments to
utf8mb4
and string return values are
utf8mb4
strings. Prior to MySQL 8.0.19,
audit log UDFs treat string arguments as binary strings (which
means they do not distinguish lettercase), and string return
values are binary strings.
These audit log UDFs are available:
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 Encrypting Audit Log Files.
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:
mysql> SELECT audit_log_encryption_password_get();
+-------------------------------------+
| audit_log_encryption_password_get() |
+-------------------------------------+
| secret |
+-------------------------------------+
To retrieve a password by ID, you can determine which
audit log keyring IDs exist by querying the Performance
Schema keyring_keys
table:
mysql>SELECT KEY_ID FROM performance_schema.keyring_keys
WHERE KEY_ID LIKE 'audit_log%'
ORDER BY KEY_ID;
+-----------------------------+ | KEY_ID | +-----------------------------+ | audit_log-20190415T152248-1 | | audit_log-20190415T153507-1 | | audit_log-20190416T125122-1 | | audit_log-20190416T141608-1 | +-----------------------------+ mysql>SELECT audit_log_encryption_password_get('audit_log-20190416T125122-1');
+------------------------------------------------------------------+ | audit_log_encryption_password_get('audit_log-20190416T125122-1') | +------------------------------------------------------------------+ | segreto | +------------------------------------------------------------------+
audit_log_encryption_password_set(
password
)
Sets the current audit log encryption password to the
argument and stores the password in the MySQL keyring. As
of MySQL 8.0.19, the password is stored as a
utf8mb4
string. Prior to MySQL 8.0.19,
the password is stored in binary form.
If encryption is enabled, this 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 Encrypting Audit Log Files.
Arguments:
password
: The password string.
The maximum permitted length is 766 bytes.
Return value:
1 for success, 0 for failure.
Example:
mysql>SELECT audit_log_encryption_password_set(
+---------------------------------------------+ | audit_log_encryption_password_set(password
);password
) | +---------------------------------------------+ | 1 | +---------------------------------------------+
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()
.
audit_log_filter_flush()
should be used only after modifying the audit tables
directly, to force reloading all filters. Otherwise,
this function should be avoided. It is, in effect, a
simplified version of unloading and reloading the
audit_log
plugin with
UNINSTALL PLUGIN
plus
INSTALL PLUGIN
.
audit_log_filter_flush()
affects all current sessions and detaches them from
their previous filters. Current sessions are no longer
logged unless they disconnect and reconnect, or execute
a change-user operation.
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:
indicates
failure.
message
Example:
mysql> SELECT audit_log_filter_flush();
+--------------------------+
| audit_log_filter_flush() |
+--------------------------+
| OK |
+--------------------------+
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:
filter_name
: A string that
specifies the filter name.
Return value:
A string that indicates whether the operation succeeded.
OK
indicates success. ERROR:
indicates
failure.
message
Example:
mysql> SELECT audit_log_filter_remove_filter('SomeFilter');
+----------------------------------------------+
| audit_log_filter_remove_filter('SomeFilter') |
+----------------------------------------------+
| OK |
+----------------------------------------------+
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:
user_name
: The user account
name as a string in
format, or user_name
@host_name
%
to represent the
default account.
Return value:
A string that indicates whether the operation succeeded.
OK
indicates success. ERROR:
indicates
failure.
message
Example:
mysql> SELECT audit_log_filter_remove_user('user1@localhost');
+-------------------------------------------------+
| audit_log_filter_remove_user('user1@localhost') |
+-------------------------------------------------+
| OK |
+-------------------------------------------------+
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:
filter_name
: A string that
specifies the filter name.
definition
: A
JSON
value that
specifies the filter definition.
Return value:
A string that indicates whether the operation succeeded.
OK
indicates success. ERROR:
indicates
failure.
message
Example:
mysql>SET @f = '{ "filter": { "log": false } }';
mysql>SELECT audit_log_filter_set_filter('SomeFilter', @f);
+-----------------------------------------------+ | audit_log_filter_set_filter('SomeFilter', @f) | +-----------------------------------------------+ | OK | +-----------------------------------------------+
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:
user_name
: The user account
name as a string in
format, or user_name
@host_name
%
to represent the
default account.
filter_name
: A string that
specifies the filter name.
Return value:
A string that indicates whether the operation succeeded.
OK
indicates success. ERROR:
indicates
failure.
message
Example:
mysql> SELECT audit_log_filter_set_user('user1@localhost', 'SomeFilter');
+------------------------------------------------------------+
| audit_log_filter_set_user('user1@localhost', 'SomeFilter') |
+------------------------------------------------------------+
| OK |
+------------------------------------------------------------+
Reads the audit log and returns a
JSON
string result. If the
audit log format is not
JSON
, an error occurs.
With no argument or a JSON
hash argument,
audit_log_read()
reads
events from the audit log and returns a
JSON
string containing an
array of audit events. Items in the hash argument
influence how reading occurs, as described later. Each
element in the returned array is an event represented as a
JSON
hash, with the
exception that the last element may be a
JSON
null
value to indicate no following
events are available to read.
With an argument consisting of a
JSON
null
value,
audit_log_read()
closes the
current read sequence.
For additional details about the audit log-reading process, see Section 6.4.5.6, “Reading Audit Log Files”.
Arguments:
To obtain a bookmark for the most recently written event,
call
audit_log_read_bookmark()
.
arg
: The argument is optional.
If omitted, the function reads events from the current
position. If present, the argument can be a
JSON
null
value to close the read sequence,
or a JSON
hash. Within a
hash argument, items are optional and control aspects of
the read operation such as the position at which to begin
reading or how many events to read. The following items
are significant (other items are ignored):
start
: The position within the
audit log of the first event to read. The position is
given as a timestamp and the read starts from the
first event that occurs on or after the timestamp
value. The start
item has this
format, where value
is a
literal timestamp value:
"start": { "timestamp": "value
" }
The start
item is permitted as of
MySQL 8.0.22.
timestamp
, id
:
The position within the audit log of the first event
to read. The timestamp
and
id
items together comprise a
bookmark that uniquely identify a particular event. If
an audit_log_read()
argument includes either item, it must include both to
completely specify a position or an error occurs.
max_array_length
: The maximum
number of events to read from the log. If this item is
omitted, the default is to read to the end of the log
or until the read buffer is full, whichever comes
first.
To specify a starting position to
audit_log_read()
, pass a
hash argument that includes either a
start
item or a bookmark consisting of
timestamp
and id
items. If a hash argument includes both a
start
item and a bookmark, an error
occurs.
If a hash argument specifies no starting position, reading continues from the current position.
If a timestamp value includes no time part, a time part of
00:00:00
is assumed.
Return value:
If the call succeeds, the return value is a
JSON
string containing an
array of audit events, or a
JSON
null
value if that was passed as the
argument to close the read sequence. If the call fails,
the return value is NULL
and an error
occurs.
Example:
mysql>SELECT audit_log_read(audit_log_read_bookmark());
+-----------------------------------------------------------------------+ | audit_log_read(audit_log_read_bookmark()) | +-----------------------------------------------------------------------+ | [ {"timestamp":"2020-05-18 22:41:24","id":0,"class":"connection", ... | +-----------------------------------------------------------------------+ mysql>SELECT audit_log_read('null');
+------------------------+ | audit_log_read('null') | +------------------------+ | null | +------------------------+
Notes:
Prior to MySQL 8.0.19, string return values are binary
JSON
strings. For
information about converting such values to nonbinary
strings, see Section 6.4.5.6, “Reading Audit Log Files”.
Returns a 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 that uniquely identify the
position of an event within the audit log. It is suitable
for passing to
audit_log_read()
to indicate
to that function the position at which to begin reading.
For additional details about the audit log-reading process, see Section 6.4.5.6, “Reading Audit Log Files”.
Arguments:
None.
Return value:
A JSON
string containing a
bookmark for success, or NULL
and an
error for failure.
Example:
mysql> SELECT audit_log_read_bookmark();
+-------------------------------------------------+
| audit_log_read_bookmark() |
+-------------------------------------------------+
| { "timestamp": "2019-10-03 21:03:44", "id": 0 } |
+-------------------------------------------------+
Notes:
Prior to MySQL 8.0.19, string return values are binary
JSON
strings. For
information about converting such values to nonbinary
strings, see Section 6.4.5.6, “Reading Audit Log Files”.
Table 6.37 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_compression | 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_encryption | Yes | Yes | 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_filter_id | Yes | Both | 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_password_history_keep_days | Yes | Yes | Yes | Global | Yes | |
audit_log_policy | Yes | Yes | Yes | Global | No | |
audit_log_prune_seconds | Yes | Yes | Yes | Global | Yes | |
audit_log_read_buffer_size | Yes | Yes | Yes | Varies | 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 configure 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 configure activation of the audit log plugin, use this option:
Command-Line Format | --audit-log[=value] |
---|---|
Type | Enumeration |
Default Value | ON |
Valid Values |
|
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.
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.
Command-Line Format | --audit-log-buffer-size=# |
---|---|
System Variable | audit_log_buffer_size |
Scope | Global |
Dynamic | No |
SET_VAR Hint Applies |
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.
Command-Line Format | --audit-log-compression=value |
---|---|
System Variable | audit_log_compression |
Scope | Global |
Dynamic | No |
SET_VAR Hint Applies |
No |
Type | Enumeration |
Default Value | NONE |
Valid Values |
|
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
Compressing Audit Log Files.
Command-Line Format | --audit-log-connection-policy=value |
---|---|
System Variable | audit_log_connection_policy |
Scope | Global |
Dynamic | Yes |
SET_VAR Hint Applies |
No |
Type | Enumeration |
Default Value | ALL |
Valid Values |
|
This variable applies only to legacy mode audit log filtering (see Section 6.4.5.9, “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 |
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.5.5, “Configuring Audit Logging Characteristics”.
System Variable | audit_log_current_session |
---|---|
Scope | Global, Session |
Dynamic | No |
SET_VAR Hint Applies |
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.)
Command-Line Format | --audit-log-encryption=value |
---|---|
System Variable | audit_log_encryption |
Scope | Global |
Dynamic | No |
SET_VAR Hint Applies |
No |
Type | Enumeration |
Default Value | NONE |
Valid Values |
|
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
Encrypting Audit Log Files.
Command-Line Format | --audit-log-exclude-accounts=value |
---|---|
System Variable | audit_log_exclude_accounts |
Scope | Global |
Dynamic | Yes |
SET_VAR Hint Applies |
No |
Type | String |
Default Value | NULL |
This variable applies only to legacy mode audit log filtering (see Section 6.4.5.9, “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 6.4.5.7, “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 |
SET_VAR Hint Applies |
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,
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
Naming Conventions for Audit Log Files.
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
Section 6.4.5.6, “Reading Audit Log Files”.
System Variable | audit_log_filter_id |
---|---|
Scope | Global, Session |
Dynamic | No |
SET_VAR Hint Applies |
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.
System Variable | audit_log_flush |
---|---|
Scope | Global |
Dynamic | Yes |
SET_VAR Hint Applies |
No |
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.5.5, “Configuring Audit Logging Characteristics”.
Command-Line Format | --audit-log-format=value |
---|---|
System Variable | audit_log_format |
Scope | Global |
Dynamic | No |
SET_VAR Hint Applies |
No |
Type | Enumeration |
Default Value | NEW |
Valid Values |
|
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”.
For information about issues to consider when changing the log format, see Selecting Audit Log File Format.
Command-Line Format | --audit-log-include-accounts=value |
---|---|
System Variable | audit_log_include_accounts |
Scope | Global |
Dynamic | Yes |
SET_VAR Hint Applies |
No |
Type | String |
Default Value | NULL |
This variable applies only to legacy mode audit log filtering (see Section 6.4.5.9, “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 6.4.5.7, “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
Command-Line Format | --audit-log-password-history-keep-days=# |
---|---|
Introduced | 8.0.17 |
System Variable | audit_log_password_history_keep_days |
Scope | Global |
Dynamic | Yes |
SET_VAR Hint Applies |
No |
Type | Integer |
Default Value | 0 |
Minimum Value | 0 |
Maximum Value | 4294967295 |
The audit log plugin implements log file encryption using encryption passwords stored in the MySQL keyring (see Encrypting Audit Log Files). The plugin also implements password history, which includes password archiving and expiration (removal).
When the audit log plugin creates a new encryption
password, it archives the previous password, if one
exists, for later use. The
audit_log_password_history_keep_days
variable controls automatic removal of expired archived
passwords. Its value indicates the number of days after
which archived audit log encryption passwords are removed.
The default of 0 disables password expiration: the
password retention period is forever.
New audit log encryption passwords are created under these circumstances:
During plugin initialization, if the plugin finds that log file encryption is enabled, it checks whether the keyring contains an audit log encryption password. If not, the plugin automatically generates a random initial encryption password.
When the
audit_log_encryption_password_set()
function is called to set a specific password.
In each case, the plugin stores the new password in the key ring and uses it to encrypt new log files.
Removal of expired audit log encryption passwords occurs under these circumstances:
During plugin initialization.
When the
audit_log_encryption_password_set()
function is called.
When the runtime value of
audit_log_password_history_keep_days
is changed from its current value to a value greater
than 0. Runtime value changes occur for
SET
statements that use the GLOBAL
or
PERSIST
keyword, but not the
PERSIST_ONLY
keyword.
PERSIST_ONLY
writes the variable
setting to mysqld-auto.cnf
, but
has no effect on the runtime value.
When password removal occurs, the current value of
audit_log_password_history_keep_days
determines which passwords to remove:
If the value is 0, the plugin removes no passwords.
If the value is N
> 0,
the plugin removes passwords more than
N
days old.
Take care not to expire old passwords that are still needed to read archived encrypted log files.
If you normally leave password expiration disabled (that
is,
audit_log_password_history_keep_days
has a value of 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:
SET GLOBAL audit_log_password_history_keep_days = 365; SET GLOBAL audit_log_password_history_keep_days = 0;
Setting the runtime value of
audit_log_password_history_keep_days
requires the AUDIT_ADMIN
privilege, in addition to the
SYSTEM_VARIABLES_ADMIN
privilege (or the deprecated
SUPER
privilege) normally
required to set a global system variable runtime value.
Command-Line Format | --audit-log-policy=value |
---|---|
System Variable | audit_log_policy |
Scope | Global |
Dynamic | No |
SET_VAR Hint Applies |
No |
Type | Enumeration |
Default Value | ALL |
Valid Values |
|
This variable applies only to legacy mode audit log filtering (see Section 6.4.5.9, “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 6.4.5.5, “Configuring Audit Logging Characteristics”.
Command-Line Format | --audit-log-prune-seconds=# |
---|---|
Introduced | 8.0.24 |
System Variable | audit_log_prune_seconds |
Scope | Global |
Dynamic | Yes |
SET_VAR Hint Applies |
No |
Type | Integer |
Default Value | 0 |
Minimum Value | 0 |
Maximum Value | 4294967295 |
Unit | seconds |
This variable pertains to audit log file pruning, which is supported for JSON-format log files only.
audit_log_prune_seconds
has no effect unless
audit_log_rotate_on_size
is greater than 0. Assuming that is true:
If
audit_log_prune_seconds
is 0 (the default), pruning is disabled and log files
created as a result of size-based rotation accumulate
indefinitely.
If
audit_log_prune_seconds
is greater than 0, pruning is enabled and the value is
the number of seconds after which audit log files
become subject to pruning.
When pruning is enabled, it occurs under the conditions described in Space Management of Audit Log Files.
Command-Line Format | --audit-log-read-buffer-size=# |
---|---|
System Variable | audit_log_read_buffer_size |
Scope (≥ 8.0.12) | Global, Session |
Scope (8.0.11) | Global |
Dynamic (≥ 8.0.12) | Yes |
Dynamic (8.0.11) | No |
SET_VAR Hint Applies |
No |
Type | Integer |
Default Value (≥ 8.0.12) | 32768 |
Default Value (8.0.11) | 1048576 |
Minimum Value (≥ 8.0.12) | 32768 |
Minimum Value (8.0.11) | 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 log format. For more
information, see Section 6.4.5.6, “Reading Audit Log Files”.
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.
Command-Line Format | --audit-log-rotate-on-size=# |
---|---|
System Variable | audit_log_rotate_on_size |
Scope | Global |
Dynamic | Yes |
SET_VAR Hint Applies |
No |
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.)
As of MySQL 8.0.24,
audit_log_rotate_on_size
also controls whether audit log file pruning can be
enabled:
If
audit_log_rotate_on_size
is disabled (0), pruning cannot be enabled and
audit_log_prune_seconds
has no effect.
If
audit_log_rotate_on_size
is enabled (greater than 0), pruning can be enabled
and
audit_log_prune_seconds
determines whether pruning occurs.
For more information about audit log file rotation and pruning, see Space Management of Audit Log Files.
Command-Line Format | --audit-log-statement-policy=value |
---|---|
System Variable | audit_log_statement_policy |
Scope | Global |
Dynamic | Yes |
SET_VAR Hint Applies |
No |
Type | Enumeration |
Default Value | ALL |
Valid Values |
|
This variable applies only to legacy mode audit log filtering (see Section 6.4.5.9, “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 |
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.5.5, “Configuring Audit Logging Characteristics”.
Command-Line Format | --audit-log-strategy=value |
---|---|
System Variable | audit_log_strategy |
Scope | Global |
Dynamic | No |
SET_VAR Hint Applies |
No |
Type | Enumeration |
Default Value | ASYNCHRONOUS |
Valid Values |
|
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.
If the audit log plugin is enabled, it exposes several status variables that provide operational information. These variables are available for legacy mode audit filtering and JSON mode audit filtering.
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.5.5, “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.5.5, “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.5.5, “Configuring Audit Logging Characteristics”).
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, “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 of
Audit_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.5.5, “Configuring Audit Logging Characteristics”.