<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="socket-pluggable-authentication">
      </a>
      8.4.1.10 Socket Peer-Credential Pluggable Authentication
     </h4>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045244161280">
  </a>
  <a class="indexterm" name="idm46045244160240">
  </a>
  <p>
   The server-side
   <code class="literal">
    auth_socket
   </code>
   authentication
        plugin authenticates clients that connect from the local host
        through the Unix socket file. The plugin uses the
   <code class="literal">
    SO_PEERCRED
   </code>
   socket option to obtain
        information about the user running the client program. Thus, the
        plugin can be used only on systems that support the
   <code class="literal">
    SO_PEERCRED
   </code>
   option, such as Linux.
  </p>
  <p>
   The source code for this plugin can be examined as a relatively
        simple example demonstrating how to write a loadable
        authentication plugin.
  </p>
  <p>
   The following table shows the plugin and library file names. The
        file must be located in 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.
  </p>
  <div class="table">
   <a name="idm46045244153488">
   </a>
   <p class="title">
    <b>
     Table 8.25 Plugin and Library Names for Socket Peer-Credential Authentication
    </b>
   </p>
   <div class="table-contents">
    <table summary="Names for the plugins and library file used for socket peer-credential password authentication.">
     <colgroup>
      <col style="width: 30%"/>
      <col style="width: 70%"/>
     </colgroup>
     <thead>
      <tr>
       <th>
        Plugin or File
       </th>
       <th>
        Plugin or File Name
       </th>
      </tr>
     </thead>
     <tbody>
      <tr>
       <td>
        Server-side plugin
       </td>
       <td>
        <code class="literal">
         auth_socket
        </code>
       </td>
      </tr>
      <tr>
       <td>
        Client-side plugin
       </td>
       <td>
        None, see discussion
       </td>
      </tr>
      <tr>
       <td>
        Library file
       </td>
       <td>
        <code class="filename">
         auth_socket.so
        </code>
       </td>
      </tr>
     </tbody>
    </table>
   </div>
  </div>
  <br class="table-break"/>
  <p>
   The following sections provide installation and usage
        information specific to socket pluggable authentication:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <a class="xref" href="socket-pluggable-authentication.html#socket-pluggable-authentication-installation" title="Installing Socket Pluggable Authentication">
       Installing Socket Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="socket-pluggable-authentication.html#socket-pluggable-authentication-uninstallation" title="Uninstalling Socket Pluggable Authentication">
       Uninstalling Socket Pluggable Authentication
      </a>
     </p>
    </li>
    <li class="listitem">
     <p>
      <a class="xref" href="socket-pluggable-authentication.html#socket-pluggable-authentication-usage" title="Using Socket Pluggable Authentication">
       Using Socket Pluggable Authentication
      </a>
     </p>
    </li>
   </ul>
  </div>
  <p>
   For general information about pluggable authentication in MySQL,
        see
   <a class="xref" href="pluggable-authentication.html" title="8.2.17 Pluggable Authentication">
    Section 8.2.17, “Pluggable Authentication”
   </a>
   .
  </p>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="socket-pluggable-authentication-installation">
       </a>
       Installing Socket Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    This section describes how to install the socket
          authentication plugin. 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>
    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 load the plugin at server startup, use the
    <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
     <code class="option">
      --plugin-load-add
     </code>
    </a>
    option to
          name the library file that contains it. With this
          plugin-loading method, the option must be given each time the
          server starts. For example, put these lines in the server
    <code class="filename">
     my.cnf
    </code>
    file:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa11859201"><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">plugin-load-add</span><span class="token attr-value"><span class="token punctuation">=</span>auth_socket.so</span></code></pre>
   </div>
   <p>
    After modifying
    <code class="filename">
     my.cnf
    </code>
    , restart the
          server to cause the new settings to take effect.
   </p>
   <p>
    Alternatively, to load the plugin at runtime, use this
          statement:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa13009236"><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">INSTALL</span> <span class="token keyword">PLUGIN</span> auth_socket <span class="token keyword">SONAME</span> <span class="token string">'auth_socket.so'</span><span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
     <code class="literal">
      INSTALL PLUGIN
     </code>
    </a>
    loads the plugin
          immediately, and also registers it in the
    <code class="literal">
     mysql.plugins
    </code>
    system table to cause the
          server to load it for each subsequent normal startup without
          the need for
    <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
     <code class="option">
      --plugin-load-add
     </code>
    </a>
    .
   </p>
   <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="sa39944415"><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">'%socket%'</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> auth_socket <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>
    To associate MySQL accounts with the socket plugin, see
    <a class="xref" href="socket-pluggable-authentication.html#socket-pluggable-authentication-usage" title="Using Socket Pluggable Authentication">
     Using Socket Pluggable Authentication
    </a>
    .
   </p>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="socket-pluggable-authentication-uninstallation">
       </a>
       Uninstalling Socket Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    The method used to uninstall the socket authentication plugin
          depends on how you installed it:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       If you installed the plugin at server startup using a
       <a class="link" href="server-options.html#option_mysqld_plugin-load-add">
        <code class="option">
         --plugin-load-add
        </code>
       </a>
       option,
              restart the server without the option.
      </p>
     </li>
     <li class="listitem">
      <p>
       If you installed the plugin at runtime using an
       <a class="link" href="install-plugin.html" title="15.7.4.4 INSTALL PLUGIN Statement">
        <code class="literal">
         INSTALL PLUGIN
        </code>
       </a>
       statement,
              it remains installed across server restarts. To uninstall
              it, use
       <a class="link" href="uninstall-plugin.html" title="15.7.4.6 UNINSTALL PLUGIN Statement">
        <code class="literal">
         UNINSTALL PLUGIN
        </code>
       </a>
       :
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa8158676"><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">UNINSTALL</span> <span class="token keyword">PLUGIN</span> auth_socket<span class="token punctuation">;</span></code></pre>
      </div>
     </li>
    </ul>
   </div>
  </div>
  <div class="simplesect">
   <div class="titlepage">
    <div>
     <div class="simple">
      <h5 class="title">
       <a name="socket-pluggable-authentication-usage">
       </a>
       Using Socket Pluggable Authentication
      </h5>
     </div>
    </div>
   </div>
   <p>
    The socket plugin checks whether the socket user name (the
          operating system user name) matches the MySQL user name
          specified by the client program to the server. If the names do
          not match, the plugin checks whether the socket user name
          matches the name specified in the
    <code class="literal">
     authentication_string
    </code>
    column of the
    <code class="literal">
     mysql.user
    </code>
    system table row. If a match is
          found, the plugin permits the connection. The
    <code class="literal">
     authentication_string
    </code>
    value can be
          specified using an
    <code class="literal">
     IDENTIFIED ...AS
    </code>
    clause
          with
    <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
     <code class="literal">
      CREATE USER
     </code>
    </a>
    or
    <a class="link" href="alter-user.html" title="15.7.1.1 ALTER USER Statement">
     <code class="literal">
      ALTER USER
     </code>
    </a>
    .
   </p>
   <p>
    Suppose that a MySQL account is created for an operating
          system user named
    <code class="literal">
     valerie
    </code>
    who is to be
          authenticated by the
    <code class="literal">
     auth_socket
    </code>
    plugin for
          connections from the local host through the socket file:
   </p>
   <div class="copytoclipboard-wrapper">
    <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa50931155"><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">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'valerie'</span>@<span class="token string">'localhost'</span> <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> auth_socket<span class="token punctuation">;</span></code></pre>
   </div>
   <p>
    If a user on the local host with a login name of
    <code class="literal">
     stefanie
    </code>
    invokes
    <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
     <span class="command">
      <strong>
       mysql
      </strong>
     </span>
    </a>
    with the option
    <code class="option">
     --user=valerie
    </code>
    to connect
          through the socket file, the server uses
    <code class="literal">
     auth_socket
    </code>
    to authenticate the client. The
          plugin determines that the
    <code class="option">
     --user
    </code>
    option
          value (
    <code class="literal">
     valerie
    </code>
    ) differs from the client
          user's name (
    <code class="literal">
     stephanie
    </code>
    ) and refuses
          the connection. If a user named
    <code class="literal">
     valerie
    </code>
    tries the same thing, the plugin finds that the user name and
          the MySQL user name are both
    <code class="literal">
     valerie
    </code>
    and
          permits the connection. However, the plugin refuses the
          connection even for
    <code class="literal">
     valerie
    </code>
    if the
          connection is made using a different protocol, such as TCP/IP.
   </p>
   <p>
    To permit both the
    <code class="literal">
     valerie
    </code>
    and
    <code class="literal">
     stephanie
    </code>
    operating system users to access
          MySQL through socket file connections that use the account,
          this can be done two ways:
   </p>
   <div class="itemizedlist">
    <ul class="itemizedlist" style="list-style-type: disc; ">
     <li class="listitem">
      <p>
       Name both users at account-creation time, one following
       <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
        <code class="literal">
         CREATE USER
        </code>
       </a>
       , and the other
              in the authentication string:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting one-line language-sql"><div class="docs-select-all right" id="sa86371581"><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">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'valerie'</span>@<span class="token string">'localhost'</span> <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> auth_socket <span class="token keyword">AS</span> <span class="token string">'stephanie'</span><span class="token punctuation">;</span></code></pre>
      </div>
     </li>
     <li class="listitem">
      <p>
       If you have already used
       <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
        <code class="literal">
         CREATE
              USER
        </code>
       </a>
       to create the account for a single user,
              use
       <a class="link" href="alter-user.html" title="15.7.1.1 ALTER USER Statement">
        <code class="literal">
         ALTER USER
        </code>
       </a>
       to add the
              second user:
      </p>
      <div class="copytoclipboard-wrapper">
       <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa34583903"><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">CREATE</span> <span class="token keyword">USER</span> <span class="token string">'valerie'</span>@<span class="token string">'localhost'</span> <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> auth_socket<span class="token punctuation">;</span>
<span class="token keyword">ALTER</span> <span class="token keyword">USER</span> <span class="token string">'valerie'</span>@<span class="token string">'localhost'</span> <span class="token keyword">IDENTIFIED</span> <span class="token keyword">WITH</span> auth_socket <span class="token keyword">AS</span> <span class="token string">'stephanie'</span><span class="token punctuation">;</span></code></pre>
      </div>
     </li>
    </ul>
   </div>
   <p>
    To access the account, both
    <code class="literal">
     valerie
    </code>
    and
    <code class="literal">
     stephanie
    </code>
    specify
    <code class="option">
     --user=valerie
    </code>
    at connect time.
   </p>
  </div>
 </div>
 <br/>
</div>
