Documentation Home
MySQL 5.6 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 30.1Mb
PDF (A4) - 30.3Mb
PDF (RPM) - 30.2Mb
EPUB - 7.8Mb
HTML Download (TGZ) - 7.6Mb
HTML Download (Zip) - 7.6Mb
HTML Download (RPM) - 6.6Mb
Eclipse Doc Plugin (TGZ) - 8.3Mb
Eclipse Doc Plugin (Zip) - 10.2Mb
Man Pages (TGZ) - 200.0Kb
Man Pages (Zip) - 311.5Kb
Info (Gzip) - 2.9Mb
Info (Zip) - 2.9Mb
Excerpts from this Manual

MySQL 5.6 Reference Manual  /  ...  /  Audit Log Plugin Logging Control Audit Log Plugin Logging Control

This section describes how the audit_log plugin performs logging and the system variables that control how logging occurs. It assumes familiarity with the log file format described in Section, “The Audit Log File”.

When the audit log plugin opens its log file, it checks whether the XML declaration and opening <AUDIT> root element tag must be written and writes them if so. When the audit log plugin terminates, it writes a closing </AUDIT> tag to the file.

If the log file exists at open time, the plugin checks whether the file ends with an </AUDIT> tag and truncates it if so before writing any <AUDIT_RECORD> elements. If the log file exists but does not end with </AUDIT> or the </AUDIT> tag cannot be truncated, the plugin considers the file malformed and fails to initialize. This can occur if the server crashes or is killed with the audit log plugin running. No logging occurs until the problem is rectified. Check the error log for diagnostic information:

[ERROR] Plugin 'audit_log' init function returned error.

To deal with this problem, you must either remove or rename the malformed log file and restart the server.

The MySQL server calls the audit log plugin to write an <AUDIT_RECORD> element whenever an auditable event occurs, such as when it completes execution of an SQL statement received from a client. Typically the first <AUDIT_RECORD> element written after server startup has the server description and startup options. Elements following that one represent events such as client connect and disconnect events, executed SQL statements, and so forth. Only top-level statements are logged, not statements within stored programs such as triggers or stored procedures. Contents of files referenced by statements such as LOAD DATA INFILE are not logged.

To permit control over how logging occurs, the audit_log plugin provides several system variables, described following. For more information, see Section, “Audit Log Plugin Options and System Variables”.

Audit Log File Naming

To control the audit log file name, set the audit_log_file system variable at server startup. By default, the name is audit.log in the server data directory. For security reasons, the audit log file should be written to a directory accessible only to the MySQL server and users with a legitimate reason to view the log.

Audit Logging Strategy

The audit log plugin can use any of several strategies for log writes. To specify a strategy, set the audit_log_strategy system variable at server startup. By default, the strategy value is ASYNCHRONOUS and the plugin logs asynchronously to a buffer, waiting if the buffer is full. It's possible to tell the plugin not to wait (PERFORMANCE) or to log synchronously, either using file system caching (SEMISYNCHRONOUS) or forcing output with a sync() call after each write request (SYNCHRONOUS).

Asynchronous logging strategy has these characteristics:

  • Minimal impact on server performance and scalability.

  • Blocking of threads that generate audit events for the shortest possible time; that is, time to allocate the buffer plus time to copy the event to the buffer.

  • Output goes to the buffer. A separate thread handles writes from the buffer to the log file.

A disadvantage of PERFORMANCE strategy is that it drops events when the buffer is full. For a heavily loaded server, it is more likely that the audit log will be missing events.

With asynchronous logging, the integrity of the log file may be compromised if a problem occurs during a write to the file or if the plugin does not shut down cleanly (for example, in the event that the server host crashes). To reduce this risk, set audit_log_strategy to use synchronous logging. Regardless of strategy, logging occurs on a best-effort basis, with no guarantee of consistency.

If the file system to which the audit log is being written fills up, a disk full error is written to the error log. Audit logging continues until the audit log buffer is full. If free disk space has not been made available by the time the buffer fills, client sessions will hang, and stopping the server at the time of client sessions hanging will result in audit log corruption. To avoid this if client sessions are hung, ensure that free space is available on the audit logging file system before stopping the server.

Audit Log Space Management

The audit log plugin provides several system variables that enable you to manage the space used by its log files:

  • audit_log_buffer_size: Set this variable at server startup to set the size of the buffer for asynchronous logging. 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_rotate_on_size, audit_log_flush: These variables permit audit log file rotation and flushing. The audit log file has the potential to grow very large and consume a lot of disk space. To manage the space used, either enable automatic log rotation, or manually rename the audit file and flush the log to open a new file. The renamed file can be removed or backed up as desired.

    By default, audit_log_rotate_on_size=0 and there is no log rotation. In this case, the audit log plugin closes and reopens the log file when the audit_log_flush value changes from disabled to enabled. Log file renaming must be done externally to the server. Suppose that you want to maintain the three most recent log files, which cycle through the names audit.log.1 through audit.log.3. On Unix, perform rotation manually like this:

    1. From the command line, rename the current log files:

      shell> mv audit.log.2 audit.log.3
      shell> mv audit.log.1 audit.log.2
      shell> mv audit.log audit.log.1

      At this point, the plugin is still writing to the current log file, which has been renamed to audit.log.1.

    2. Connect to the server and flush the log file so the plugin closes it and reopens a new audit.log file:

      mysql> SET GLOBAL audit_log_flush = ON;

    If audit_log_rotate_on_size is greater than 0, setting audit_log_flush has no effect. In this case, the audit log plugin closes and reopens its log file whenever a write to the file causes its size to exceed the audit_log_rotate_on_size value. The plugin renames the original file to have a timestamp extension. For example, audit.log might be renamed to audit.log.13440033615657730. The last 7 digits are a fractional second part. The first 10 digits are a Unix timestamp value that can be interpreted using the FROM_UNIXTIME() function:

    mysql> SELECT FROM_UNIXTIME(1344003361);
    | FROM_UNIXTIME(1344003361) |
    | 2012-08-03 09:16:01       |
Audit Log Filtering

The audit log plugin can filter audited events. This enables you to control whether it writes events to the audit log file based on the account from which events originate or event status. Status filtering occurs separately for connection events and statement events.

Event Filtering by Account

As of MySQL 5.6.20, to filter audited events based on the originating account, set one of these system variables at server startup or runtime:

  • audit_log_include_accounts: The accounts to include in audit logging. If this variable is set, only these accounts are audited.

  • audit_log_exclude_accounts: The accounts to exclude from audit logging. If this variable is set, all but these accounts are audited.

The value for either variable can be NULL or a string containing one or more comma-separated account names, each in user_name@host_name format. By default, both variables are NULL, in which case, no account filtering is done and auditing occurs for all accounts.

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

Example: To enable audit logging only for the user1 and user2 local host account accounts, set the audit_log_include_accounts system variable like this:

SET GLOBAL audit_log_include_accounts = 'user1@localhost,user2@localhost';

Only one of audit_log_include_accounts or audit_log_exclude_accounts can be non-NULL at a time:

-- This sets audit_log_exclude_accounts to NULL
SET GLOBAL audit_log_include_accounts = value;

-- This fails because audit_log_include_accounts is not NULL
SET GLOBAL audit_log_exclude_accounts = value;

-- To set audit_log_exclude_accounts, first set
-- audit_log_include_accounts to NULL
SET GLOBAL audit_log_include_accounts = NULL;
SET GLOBAL audit_log_exclude_accounts = value;

If you inspect the value of either variable, be aware that SHOW VARIABLES displays NULL as an empty string. To avoid this, use SELECT instead:

mysql> SHOW VARIABLES LIKE 'audit_log_include_accounts';
| Variable_name              | Value |
| audit_log_include_accounts |       |
mysql> SELECT @@audit_log_include_accounts;
| @@audit_log_include_accounts |
| NULL                         |

If a user name or host name requires quoting because it contains a comma, space, or other special character, quote it using single quotes. If the variable value itself is quoted with single quotes, double each inner single quote or escape it with a backslash. The following statements each enable audit logging for the local root account and are equivalent, even though the quoting styles differ:

SET GLOBAL audit_log_include_accounts = 'root@localhost';
SET GLOBAL audit_log_include_accounts = '''root''@''localhost''';
SET GLOBAL audit_log_include_accounts = '\'root\'@\'localhost\'';
SET GLOBAL audit_log_include_accounts = "'root'@'localhost'";

The last statement will not work if the ANSI_QUOTES SQL mode is enabled because in that mode double quotes signify identifier quoting, not string quoting.

Event Filtering by Status

As of MySQL 5.6.20, to filter audited events based on status, set these system variables at server startup or runtime:

Each variable takes a value of ALL (log all associated events; this is the default), ERRORS (log only failed events), or NONE (do not log events). For example, to log all statement events but only failed connection events, use these settings:

SET GLOBAL audit_log_statement_policy = ALL;
SET GLOBAL audit_log_connection_policy = ERRORS;

Before MySQL 5.6.20, audit_log_connection_policy and audit_log_statement_policy are not available. Instead, use audit_log_policy at server startup or runtime. It takes a value of ALL (log all events; this is the default), LOGINS (log connection events), QUERIES (log statement events), or NONE (do not log events). For any of those values, the audit log plugin logs all selected events without distinction as to success or failure.

As of MySQL 5.6.20, audit_log_policy is still available but can be set only at server startup. At runtime, it is a read-only variable. Its use at startup works as follows:

  • If you do not set audit_log_policy or set it to its default of ALL, any explicit settings for audit_log_connection_policy or audit_log_statement_policy apply as specified. If not specified, they default to ALL.

  • If you set audit_log_policy to a non-ALL value, that value takes precedence over and is used to set audit_log_connection_policy and audit_log_statement_policy, as indicated in the following table. If you also set either of those variables to a value other than their default of ALL, the server writes a message to the error log to indicate that their values are being overridden.

    Startup audit_log_policy ValueResulting audit_log_connection_policy ValueResulting audit_log_statement_policy Value
Event Filtering Reporting

To check the effect of filtering, you can inspect the values of these status variables:

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

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

  • Audit_log_events_written: The number of events written to the audit log.

These variables are available as of MySQL 5.6.20.

Download this Manual
PDF (US Ltr) - 30.1Mb
PDF (A4) - 30.3Mb
PDF (RPM) - 30.2Mb
EPUB - 7.8Mb
HTML Download (TGZ) - 7.6Mb
HTML Download (Zip) - 7.6Mb
HTML Download (RPM) - 6.6Mb
Eclipse Doc Plugin (TGZ) - 8.3Mb
Eclipse Doc Plugin (Zip) - 10.2Mb
Man Pages (TGZ) - 200.0Kb
Man Pages (Zip) - 311.5Kb
Info (Gzip) - 2.9Mb
Info (Zip) - 2.9Mb
User Comments
Sign Up Login You must be logged in to post a comment.