.. _audit_log_plugin:

==================
 Audit Log Plugin
==================

Percona Audit Log Plugin provides monitoring and logging of connection and query activity that were performed on specific server. Information about the activity will be stored in the XML log file where each event will have its ``NAME`` field, it's own unique ``RECORD_ID`` field and a ``TIMESTAMP`` field. This implementation is alternative to the `MySQL Enterprise Audit Log Plugin <dev.mysql.com/doc/refman/5.5/en/audit-log-plugin.html>`_

Audit Log plugin produces the log of following events:

* **Audit** - Audit event indicates that audit logging started or finished. ``NAME`` field will be ``Audit`` when logging started and ``NoAudit`` when logging finished. Audit record also includes server version and command-line arguments.

Example of the Audit event: :: 

 <AUDIT_RECORD
  "NAME"="Audit"
  "RECORD"="1_2014-04-29T09:29:40"
  "TIMESTAMP"="2014-04-29T09:29:40 UTC"
  "MYSQL_VERSION"="5.5.37-35.0-655.trusty"
  "STARTUP_OPTIONS"="--basedir=/usr --datadir=/var/lib/mysql --plugin-dir=/usr/lib/mysql/plugin --user=mysql --log-error=/var/log/mysql/error.log --pid-file=/var/run/mysqld/mysqld.pid --socket=/var/run/mysqld/mysqld.sock --port=3306"
  "OS_VERSION"="x86_64-debian-linux-gnu",
  />

* **Connect**/**Disconnect** - Connect record event will have ``NAME`` field ``Connect`` when user logged in or login failed, or ``Quit`` when connection is closed. Additional fields for this event are ``CONNECTION_ID``, ``STATUS``, ``USER``, ``PRIV_USER``, ``OS_LOGIN``, ``PROXY_USER``, ``HOST``, and ``IP``. ``STATUS`` will be  ``0`` for successful logins and non-zero for failed logins.

Example of the Disconnect event: :: 

 <AUDIT_RECORD
  "NAME"="Quit"
  "RECORD"="24_2014-04-29T09:29:40"
  "TIMESTAMP"="2014-04-29T10:20:13 UTC"
  "CONNECTION_ID"="49"
  "STATUS"="0"
  "USER"=""
  "PRIV_USER"=""
  "OS_LOGIN"=""
  "PROXY_USER"=""
  "HOST"=""
  "IP"=""
  "DB"=""
  />

* **Query** - Additional fields for this event are: ``COMMAND_CLASS`` (values come from the ``com_status_vars`` array in the :file:`sql/mysqld.cc`` file in a MySQL source distribution. Examples are ``select``, ``alter_table``, ``create_table``, etc.), ``CONNECTION_ID``, ``STATUS`` (indicates error when non-zero), ``SQLTEXT`` (text of SQL-statement), ``USER``, ``HOST``, ``OS_USER``, ``IP``. Possible values for the ``NAME`` name field for this event are ``Query``, ``Prepare``, ``Execute``, ``Change user``, etc.

Example of the Query event: :: 

 <AUDIT_RECORD
  "NAME"="Query"
  "RECORD"="23_2014-04-29T09:29:40"
  "TIMESTAMP"="2014-04-29T10:20:10 UTC"
  "COMMAND_CLASS"="select"
  "CONNECTION_ID"="49"
  "STATUS"="0"
  "SQLTEXT"="SELECT * from mysql.user"
  "USER"="root[root] @ localhost []"
  "HOST"="localhost"
  "OS_USER"=""
  "IP"=""
  />

Installation
============

Audit Log plugin is shipped with |Percona Server|, but it is not installed by default. To enable the plugin you must run the following command: 

.. code-block:: mysql

   INSTALL PLUGIN audit_log SONAME 'audit_log.so';

You can check if the plugin is loaded correctly by running:

.. code-block:: mysql

   SHOW PLUGINS;

Audit log should be listed in the output:
    
.. code-block:: mysql

   +--------------------------------+----------+--------------------+--------------+---------+
   | Name                           | Status   | Type               | Library      | License |
   +--------------------------------+----------+--------------------+--------------+---------+
   ...
   | audit_log                      | ACTIVE   | AUDIT              | audit_log.so | GPL     |
   +--------------------------------+----------+--------------------+--------------+---------+

Log Format
==========

The audit log plugin supports four log formats: ``OLD``, ``NEW``, ``JSON``, and ``CSV``. ``OLD`` and ``NEW`` formats are based on XML, where the former outputs log record properties as XML attributes and the latter as XML tags. Information logged is the same in all four formats. The log format choice is controlled by :variable:`audit_log_format` variable.

Example of the ``OLD`` format: ::

 <AUDIT_RECORD
  "NAME"="Query"
  "RECORD"="2_2014-04-28T09:29:40"
  "TIMESTAMP"="2014-04-28T09:29:40 UTC"
  "COMMAND_CLASS"="install_plugin"
  "CONNECTION_ID"="47"
  "STATUS"="0"
  "SQLTEXT"="INSTALL PLUGIN audit_log SONAME 'audit_log.so'"
  "USER"="root[root] @ localhost []"
  "HOST"="localhost"
  "OS_USER"=""
  "IP"=""
 />

Example of the ``NEW`` format: :: 

 <AUDIT_RECORD>
  <NAME>Quit</NAME>
  <RECORD>10902_2014-04-28T11:02:54</RECORD>
  <TIMESTAMP>2014-04-28T11:02:59 UTC</TIMESTAMP>
  <CONNECTION_ID>36</CONNECTION_ID>
  <STATUS>0</STATUS>
  <USER></USER>
  <PRIV_USER></PRIV_USER>
  <OS_LOGIN></OS_LOGIN>
  <PROXY_USER></PROXY_USER>
  <HOST></HOST>
  <IP></IP>
  <DB></DB>
 </AUDIT_RECORD>

Example of the ``JSON`` format: ::

 {"audit_record":{"name":"Query","record":"4707_2014-08-27T10:43:52","timestamp":"2014-08-27T10:44:19 UTC","command_class":"show_databases","connection_id":"37","status":0,"sqltext":"show databases","user":"root[root] @ localhost []","host":"localhost","os_user":"","ip":""}}

Example of the ``CSV`` format: :: 

 "Query","49284_2014-08-27T10:47:11","2014-08-27T10:47:23 UTC","show_databases","37",0,"show databases","root[root] @ localhost []","localhost","",""

.. _streaming_to_syslog:

Streaming the audit log to syslog
=================================

Ability to stream the audit log to `syslog <http://www.syslog.org/>`_ was implemented in |Percona Server| :rn:`5.5.39-36.0`. To stream the audit log to syslog you'll need to set :variable:`audit_log_handler` variable to ``SYSLOG``. To control the syslog file handler, the following variables can be used: :variable:`audit_log_syslog_ident`, :variable:`audit_log_syslog_facility`, and :variable:`audit_log_syslog_priority` These variables have the same meaning as appropriate parameters described in the `syslog(3) manual <http://linux.die.net/man/3/syslog>`_.

.. note::

   Variables: :variable:`audit_log_strategy`, :variable:`audit_log_buffer_size`, :variable:`audit_log_rotate_on_size`, :variable:`audit_log_rotations` have effect only with ``FILE`` handler. 

System Variables
================

.. variable:: audit_log_strategy

     :version 5.5.37-35.0: Implemented
     :cli: Yes
     :scope: Global
     :dyn: No
     :vartype: String
     :default: ASYNCHRONOUS
     :allowed values: ``ASYNCHRONOUS``, ``PERFORMANCE``, ``SEMISYNCHRONOUS``, ``SYNCHRONOUS``

This variable is used to specify the audit log strategy, possible values are:

* ``ASYNCHRONOUS`` - (default) log using memory buffer, do not drop messages if buffer is full
* ``PERFORMANCE`` - log using memory buffer, drop messages if buffer is full
* ``SEMISYNCHRONOUS`` - log directly to file, do not flush and sync every event
* ``SYNCHRONOUS`` - log directly to file, flush and sync every event

This variable has effect only when :variable:`audit_log_handler` is set to ``FILE``.

.. variable:: audit_log_file

     :version 5.5.37-35.0: Implemented
     :cli: Yes
     :scope: Global
     :dyn: No
     :vartype: String
     :default: audit.log

This variable is used to specify the filename that's going to store the audit log. It can contain the path relative to the datadir or absolute path.

.. variable:: audit_log_flush

     :version 5.5.37-35.0: Implemented
     :cli: Yes
     :scope: Global
     :dyn: Yes
     :vartype: String
     :default: OFF

When this variable is set to ``ON`` log file will be closed and reopened. This can be used for manual log rotation.

.. variable:: audit_log_buffer_size

     :version 5.5.37-35.0: Implemented
     :cli: Yes
     :scope: Global
     :dyn: No
     :vartype: Numeric
     :default: 4096

This variable can be used to specify the size of memory buffer used for logging, used when :variable:`audit_log_strategy` variable is set to ``ASYNCHRONOUS`` or ``PERFORMANCE`` values. This variable has effect only when :variable:`audit_log_handler` is set to ``FILE``.

.. variable:: audit_log_format

     :version 5.5.37-35.0: Original implementation
     :version 5.5.39-36.0: Implemented support for ``CSV`` and  ``JSON`` log formats
     :cli: Yes
     :scope: Global
     :dyn: No 
     :vartype: String
     :default: OLD
     :allowed values: ``OLD``, ``NEW``, ``CSV``, ``JSON``

This variable is used to specify the audit log format. The audit log plugin supports four log formats: ``OLD``, ``NEW``, ``JSON``, and ``CSV``. ``OLD`` and ``NEW`` formats are based on XML, where the former outputs log record properties as XML attributes and the latter as XML tags. Information logged is the same in all four formats.

.. variable:: audit_log_policy

     :version 5.5.37-35.0: Implemented
     :cli: Yes
     :scope: Global
     :dyn: Yes 
     :vartype: String
     :default: ALL
     :allowed values: ``ALL``, ``LOGINS``, ``QUERIES``, ``NONE``

This variable is used to specify which events should be logged. Possible values are: 

* ``ALL`` - all events will be logged
* ``LOGINS`` - only logins will be logged
* ``QUERIES`` - only queries will be logged
* ``NONE`` - no events will be logged

.. variable:: audit_log_rotate_on_size

     :version 5.5.37-35.0: Implemented
     :cli: Yes
     :scope: Global
     :dyn: No 
     :vartype: Numeric
     :default: 0 (don't rotate the log file)

This variable is used to specify the maximum audit log file size. Upon reaching this size the log will be rotated. The rotated log files will be present in the same same directory as the current log file. A sequence number will be appended to the log file name upon rotation. This variable has effect only when :variable:`audit_log_handler` is set to ``FILE``.
 
.. variable:: audit_log_rotations

     :version 5.5.37-35.0: Implemented
     :cli: Yes
     :scope: Global
     :dyn: No 
     :vartype: Numeric
     :default: 0 

This variable is used to specify how many log files should be kept when :variable:`audit_log_rotate_on_size` variable is set to non-zero value. This variable has effect only when :variable:`audit_log_handler` is set to ``FILE``.

.. variable:: audit_log_handler

     :version 5.5.39-36.0: Implemented
     :cli: Yes
     :scope: Global
     :dyn: No 
     :vartype: String
     :default: FILE
     :allowed values: ``FILE``, ``SYSLOG``

This variable is used to configure where the audit log will be written. If it is set to ``FILE``, the log will be written into a file specified by :variable:`audit_log_file` variable. If it is set to ``SYSLOG``, the audit log will be written to syslog.

.. variable:: audit_log_syslog_ident

   :version 5.5.39-36.0: Implemented
   :cli: Yes
   :scope: Global
   :dyn: No 
   :vartype: String
   :default: percona-audit

This variable is used to specify the ``ident`` value for syslog. This variable has the same meaning as the appropriate parameter described in the `syslog(3) manual <http://linux.die.net/man/3/syslog>`_.

.. variable:: audit_log_syslog_facility
   
   :version 5.5.39-36.0: Implemented
   :cli: Yes
   :scope: Global
   :dyn: No 
   :vartype: String
   :default: LOG_USER

This variable is used to specify the ``facility`` value for syslog. This variable has the same meaning as the appropriate parameter described in the `syslog(3) manual <http://linux.die.net/man/3/syslog>`_.

.. variable:: audit_log_syslog_priority

   :version 5.5.39-36.0: Implemented
   :cli: Yes
   :scope: Global
   :dyn: No 
   :vartype: String
   :default: LOG_INFO

This variable is used to specify the ``priority`` value for syslog. This variable has the same meaning as the appropriate parameter described in the `syslog(3) manual <http://linux.die.net/man/3/syslog>`_.

Version Specific Information
============================

  * :rn:`5.5.37-35.0`
    Audit Log plugin has been implemented in |Percona Server|.
  * :rn:`5.5.39-36.0`
    |Percona Server| :ref:`audit_log_plugin` now supports ``JSON`` and ``CSV`` log formats. 
  * :rn:`5.5.39-36.0`
    |Percona Server| :ref:`audit_log_plugin` now supports :ref:`streaming the audit log to syslog <streaming_to_syslog>`.

 
