<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="audit-log-installation">
      </a>
      8.4.5.2 Installing or Uninstalling MySQL Enterprise Audit
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045238596512">
  </a>
  <a class="indexterm" name="idm46045238595056">
  </a>
  <p>
   This section describes how to install or uninstall MySQL Enterprise Audit,
        which is implemented using the audit log plugin and related
        elements described in
   <a class="xref" href="audit-log-elements.html" title="8.4.5.1 Elements of MySQL Enterprise Audit">
    Section 8.4.5.1, “Elements of MySQL Enterprise Audit”
   </a>
   . For
        general information about installing plugins, see
   <a class="xref" href="plugin-loading.html" title="7.6.1 Installing and Uninstalling Plugins">
    Section 7.6.1, “Installing and Uninstalling Plugins”
   </a>
   .
  </p>
  <p>
   Plugin upgrades are not automatic when you upgrade a MySQL
        installation and some plugin loadable functions must be loaded
        manually (see
   <a class="xref" href="function-loading.html#loadable-function-installing" title="Installing Loadable Functions">
    Installing Loadable Functions
   </a>
   ).
        Alternatively, you can reinstall the plugin after upgrading
        MySQL to load new functions.
  </p>
  <div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Important
   </div>
   <p>
    Read this entire section before following its instructions.
          Parts of the procedure differ depending on your environment.
   </p>
  </div>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    If installed, the
    <code class="literal">
     audit_log
    </code>
    plugin involves
          some minimal overhead even when disabled. To avoid this
          overhead, do not install MySQL Enterprise Audit unless you plan to use it.
   </p>
  </div>
  <p>
   To be usable by the server, the plugin library file must be
        located in the MySQL plugin directory (the directory named by
        the
   <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
    <code class="literal">
     plugin_dir
    </code>
   </a>
   system
        variable). If necessary, configure the plugin directory location
        by setting the value of
   <a class="link" href="server-system-variables.html#sysvar_plugin_dir">
    <code class="literal">
     plugin_dir
    </code>
   </a>
   at server startup.
  </p>
  <p>
   To install MySQL Enterprise Audit, look in the
   <code class="filename">
    share
   </code>
   directory of your MySQL installation and choose the script that
        is appropriate for your platform. The available scripts differ
        in the file name used to refer to the script:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <code class="filename">
       audit_log_filter_win_install.sql
      </code>
     </p>
    </li>
    <li class="listitem">
     <p>
      <code class="filename">
       audit_log_filter_linux_install.sql
      </code>
     </p>
    </li>
   </ul>
  </div>
  <p>
   Run the script as follows. The example here uses the Linux
        installation script and the default
   <code class="literal">
    mysql
   </code>
   system database. Make the appropriate substitution for your
        system.
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa44341574"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">mysql</span> <span class="token property">-u</span> root <span class="token property">-p</span> <span class="token property">-D</span> mysql &lt; audit_log_filter_linux_install<span class="token punctuation">.</span>sql
Enter password<span class="token punctuation">:</span> <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">(</span>enter root password here<span class="token punctuation">)</span></em><span class="token punctuation"></span></code></pre>
  </div>
  <p>
   It is possible to specify a custom database for storing JSON
        filter tables when you run the installation script. Create the
        database first; its name should not exceed 64 characters. For
        example:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa13536271"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> <span class="token keyword">CREATE</span> <span class="token keyword">DATABASE</span> <span class="token keyword">IF</span> <span class="token operator">NOT</span> <span class="token keyword">EXISTS</span> <span class="token keyword"></span><em class="replaceable"><span class="token keyword">database</span><span class="token operator">-</span><span class="token keyword">name</span></em><span class="token keyword"></span><span class="token punctuation">;</span></code></pre>
  </div>
  <p>
   Next, run the script using the alternative database name.
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa20561140"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">mysql</span> <span class="token property">-u</span> root <span class="token property">-p</span> <span class="token property">-D</span> <em class="replaceable">database-name</em> &lt; audit_log_filter_linux_install<span class="token punctuation">.</span>sql
Enter password<span class="token punctuation">:</span> <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">(</span>enter root password here<span class="token punctuation">)</span></em><span class="token punctuation"></span></code></pre>
  </div>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    Some MySQL versions have introduced changes to the structure
          of the MySQL Enterprise Audit tables. To ensure that your tables are up to
          date for upgrades from earlier versions of MySQL, perform the
          MySQL upgrade procedure, making sure to use the option that
          forces an update (see
    <a class="xref" href="upgrading.html" title="Chapter 3 Upgrading MySQL">
     Chapter 3,
     <i>
      Upgrading MySQL
     </i>
    </a>
    ). If you
          prefer to run the update statements only for the MySQL Enterprise Audit
          tables, see the following discussion.
   </p>
   <p>
    For new MySQL installations, the
    <code class="literal">
     USER
    </code>
    and
    <code class="literal">
     HOST
    </code>
    columns in the
    <code class="literal">
     audit_log_user
    </code>
    table used by MySQL Enterprise Audit have
          definitions that better correspond to the definitions of the
    <code class="literal">
     User
    </code>
    and
    <code class="literal">
     Host
    </code>
    columns in
          the
    <code class="literal">
     mysql.user
    </code>
    system table. For upgrades
          to an installation for which MySQL Enterprise Audit is already installed,
          it is recommended that you alter the table definitions as
          follows:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa70075997"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">ALTER</span> <span class="token keyword">TABLE</span> mysql<span class="token punctuation">.</span>audit_log_user
  <span class="token keyword">DROP</span> <span class="token keyword">FOREIGN</span> <span class="token keyword">KEY</span> audit_log_user_ibfk_1<span class="token punctuation">;</span>
<span class="token keyword">ALTER</span> <span class="token keyword">TABLE</span> mysql<span class="token punctuation">.</span>audit_log_filter
  CONVERT <span class="token keyword">TO</span> <span class="token keyword">CHARACTER</span> <span class="token keyword">SET</span> utf8mb4 <span class="token keyword">COLLATE</span> utf8mb4_0900_as_ci<span class="token punctuation">;</span>
<span class="token keyword">ALTER</span> <span class="token keyword">TABLE</span> mysql<span class="token punctuation">.</span>audit_log_user
  CONVERT <span class="token keyword">TO</span> <span class="token keyword">CHARACTER</span> <span class="token keyword">SET</span> utf8mb4 <span class="token keyword">COLLATE</span> utf8mb4_0900_as_ci<span class="token punctuation">;</span>
<span class="token keyword">ALTER</span> <span class="token keyword">TABLE</span> mysql<span class="token punctuation">.</span>audit_log_user
  <span class="token keyword">MODIFY</span> <span class="token keyword">COLUMN</span> <span class="token keyword">USER</span> <span class="token datatype">VARCHAR</span><span class="token punctuation">(</span><span class="token number">32</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">ALTER</span> <span class="token keyword">TABLE</span> mysql<span class="token punctuation">.</span>audit_log_user
  <span class="token keyword">ADD</span> <span class="token keyword">FOREIGN</span> <span class="token keyword">KEY</span> <span class="token punctuation">(</span>FILTERNAME<span class="token punctuation">)</span> <span class="token keyword">REFERENCES</span> mysql<span class="token punctuation">.</span>audit_log_filter<span class="token punctuation">(</span><span class="token keyword">NAME</span><span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre>
   </div>
  </div>
  <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Note
   </div>
   <p>
    To use MySQL Enterprise Audit in the context of source/replica replication,
          Group Replication, or InnoDB Cluster, you must prepare the
          replica nodes prior to running the installation script on the
          source node. This is necessary because the
    <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
     <code class="literal">
      INSTALL PLUGIN
     </code>
    </a>
    statement in the
          script is not replicated.
   </p>
   <div class="orderedlist">
    <ol class="orderedlist" type="1">
     <li class="listitem">
      <p>
       On each replica node, extract the
       <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
        <code class="literal">
         INSTALL PLUGIN
        </code>
       </a>
       statement
              from the installation script and execute it manually.
      </p>
     </li>
     <li class="listitem">
      <p>
       On the source node, run the installation script as
              described previously.
      </p>
     </li>
    </ol>
   </div>
  </div>
  <p>
   To verify plugin installation, examine the Information Schema
   <a class="link" href="information-schema-plugins-table.html" title="28.3.22 The INFORMATION_SCHEMA PLUGINS Table">
    <code class="literal">
     PLUGINS
    </code>
   </a>
   table or use the
   <a class="link" href="show-plugins.html" title="15.7.7.27 SHOW PLUGINS Statement">
    <code class="literal">
     SHOW PLUGINS
    </code>
   </a>
   statement (see
   <a class="xref" href="obtaining-plugin-information.html" title="7.6.2 Obtaining Server Plugin Information">
    Section 7.6.2, “Obtaining Server Plugin Information”
   </a>
   ). For example:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa78236489"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token prompt">mysql&gt;</span> <span class="token keyword">SELECT</span> PLUGIN_NAME<span class="token punctuation">,</span> PLUGIN_STATUS
       <span class="token keyword">FROM</span> INFORMATION_SCHEMA<span class="token punctuation">.</span><span class="token keyword">PLUGINS</span>
       <span class="token keyword">WHERE</span> PLUGIN_NAME <span class="token operator">LIKE</span> <span class="token string">'audit%'</span><span class="token punctuation">;</span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> PLUGIN_NAME <span class="token punctuation">|</span> PLUGIN_STATUS <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span>
<span class="token output"><span class="token punctuation">|</span> audit_log   <span class="token punctuation">|</span> ACTIVE        <span class="token punctuation">|</span></span>
<span class="token output"><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">-</span><span class="token punctuation">+</span></span></code></pre>
  </div>
  <p>
   If the plugin fails to initialize, check the server error log
        for diagnostic messages.
  </p>
  <p>
   After MySQL Enterprise Audit is installed, you can use the
   <a class="link" href="audit-log-reference.html#option_mysqld_audit-log">
    <code class="option">
     --audit-log
    </code>
   </a>
   option for subsequent
        server startups to control
   <code class="literal">
    audit_log
   </code>
   plugin
        activation. For example, to prevent the plugin from being
        removed at runtime, use this option:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa93303557"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">audit-log</span><span class="token attr-value"><span class="token punctuation">=</span>FORCE_PLUS_PERMANENT</span></code></pre>
  </div>
  <p>
   If it is desired to prevent the server from running without the
        audit plugin, use
   <a class="link" href="audit-log-reference.html#option_mysqld_audit-log">
    <code class="option">
     --audit-log
    </code>
   </a>
   with a value of
   <code class="literal">
    FORCE
   </code>
   or
   <code class="literal">
    FORCE_PLUS_PERMANENT
   </code>
   to force server startup
        to fail if the plugin does not initialize successfully.
  </p>
  <div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">
   <div class="admon-title">
    Important
   </div>
   <p>
    By default, rule-based audit log filtering logs no auditable
          events for any users. This differs from legacy audit log
          behavior, which logs all auditable events for all users (see
    <a class="xref" href="audit-log-legacy-filtering.html" title="8.4.5.10 Legacy Mode Audit Log Filtering">
     Section 8.4.5.10, “Legacy Mode Audit Log Filtering”
    </a>
    ). Should you wish
          to produce log-everything behavior with rule-based filtering,
          create a simple filter to enable logging and assign it to the
          default account:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa99525951"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-sql"><span class="token keyword">SELECT</span> audit_log_filter_set_filter<span class="token punctuation">(</span><span class="token string">'log_all'</span><span class="token punctuation">,</span> <span class="token string">'{ "filter": { "log": true } }'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">SELECT</span> audit_log_filter_set_user<span class="token punctuation">(</span><span class="token string">'%'</span><span class="token punctuation">,</span> <span class="token string">'log_all'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    The filter assigned to
    <code class="literal">
     %
    </code>
    is used for
          connections from any account that has no explicitly assigned
          filter (which initially is true for all accounts).
   </p>
  </div>
  <p>
   When installed as just described, MySQL Enterprise Audit remains installed
        until uninstalled. To remove it, run the uninstall script
        located in the
   <code class="literal">
    share
   </code>
   directory of your MySQL
        installation. The example here specifies the default system
        database,
   <code class="literal">
    mysql
   </code>
   . Make the appropriate
        substitution for your system.
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa83508001"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">mysql</span> <span class="token property">-u</span> root <span class="token property">-p</span> <span class="token property">-D</span> mysql &lt; audit_log_filter_uninstall<span class="token punctuation">.</span>sql
Enter password<span class="token punctuation">:</span> <span class="token punctuation"></span><em class="replaceable"><span class="token punctuation">(</span>enter root password here<span class="token punctuation">)</span></em><span class="token punctuation"></span></code></pre>
  </div>
 </div>
 <br/>
</div>
