Documentation Home
MySQL 5.5 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 27.1Mb
PDF (A4) - 27.1Mb
PDF (RPM) - 26.1Mb
HTML Download (TGZ) - 6.6Mb
HTML Download (Zip) - 6.6Mb
HTML Download (RPM) - 5.6Mb
Man Pages (TGZ) - 168.7Kb
Man Pages (Zip) - 277.1Kb
Info (Gzip) - 2.5Mb
Info (Zip) - 2.5Mb
Excerpts from this Manual

MySQL 5.5 Reference Manual  /  ...  /  Socket Peer-Credential Pluggable Authentication

6.5.1.6 Socket Peer-Credential Pluggable Authentication

As of MySQL 5.5.10, a server-side auth_socket authentication plugin is available that authenticates clients that connect from the local host through the Unix socket file. The plugin uses the SO_PEERCRED socket option to obtain information about the user running the client program. Thus, the plugin can be used only on systems that support the SO_PEERCRED option, such as Linux.

The source code for this plugin can be examined as a relatively simple example demonstrating how to write a loadable authentication plugin.

The following table shows the plugin and library file names. The file must be located in the directory named by the plugin_dir system variable. For installation information, see Section 6.3.6, “Pluggable Authentication”.

Table 6.14 Plugin and Library Names for Socket Peer-Credential Authentication

Server-side plugin nameauth_socket
Client-side plugin nameNone, see discussion
Library file nameauth_socket.so

The following sections provide installation and usage information specific to socket pluggable authentication:

For general information about pluggable authentication in MySQL, see Section 6.3.6, “Pluggable Authentication”.

Installing Socket Pluggable Authentication

This section describes how to install the socket authentication plugin. For general information about installing plugins, see Section 5.5.2, “Installing and Uninstalling Plugins”.

To be usable by the server, the plugin library file must be located in the MySQL plugin directory (the directory named by the plugin_dir system variable). If necessary, set the value of plugin_dir at server startup to tell the server the plugin directory location.

To load the plugin at server startup, use the --plugin-load 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 your my.cnf file:

[mysqld]
plugin-load=auth_socket.so

Alternatively, to register the plugin at runtime, use this statement (adjust the extension as necessary):

INSTALL PLUGIN auth_socket SONAME 'auth_socket.so';

INSTALL PLUGIN loads a plugin, and also registers it in the mysql.plugins table to cause the plugin to be loaded for each subsequent normal server startup.

To verify plugin installation, examine the INFORMATION_SCHEMA.PLUGINS table or use the SHOW PLUGINS statement (see Section 5.5.3, “Obtaining Server Plugin Information”). For example:

mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
       FROM INFORMATION_SCHEMA.PLUGINS
       WHERE PLUGIN_NAME LIKE '%socket%';
+-------------+---------------+
| PLUGIN_NAME | PLUGIN_STATUS |
+-------------+---------------+
| auth_socket | ACTIVE        |
+-------------+---------------+

If the plugin fails to initialize, check the server error log for diagnostic messages.

To associate a MySQL account with the socket plugin, use the plugin name auth_socket in the IDENTIFIED WITH clause of the CREATE USER statement that creates the account. (See Using Socket Pluggable Authentication.)

Uninstalling Socket Pluggable Authentication

The method used to uninstall the socket authentication plugin depends on how you installed it:

  • If you installed the plugin at server startup using a --plugin-load option, restart the server without the option.

  • If you installed the plugin at runtime using INSTALL PLUGIN, it remains installed across server restarts. To uninstall it, use UNINSTALL PLUGIN:

    UNINSTALL PLUGIN auth_socket;
    
Using Socket Pluggable Authentication

The socket plugin checks whether the socket user name matches the MySQL user name specified by the client program to the server, and permits the connection only if the names match.

Suppose that a MySQL account is created for a user named valerie who is to be authenticated by the auth_socket plugin for connections from the local host through the socket file:

CREATE USER 'valerie'@'localhost' IDENTIFIED WITH auth_socket;

If a user on the local host with a login name of stefanie invokes mysql with the option --user=valerie to connect through the socket file, the server uses auth_socket to authenticate the client. The plugin determines that the --user option value (valerie) differs from the client user's name (stephanie) and refuses the connection. If a user named valerie tries the same thing, the plugin finds that the user name and the MySQL user name are both valerie and permits the connection. However, the plugin refuses the connection even for valerie if the connection is made using a different protocol, such as TCP/IP.


User Comments
Sign Up Login You must be logged in to post a comment.