Merge lp:~hrvojem/percona-server/ps-25 into lp:percona-server/5.5

[Hrvoje Matijakovic]

[Laurynas Biveinis (laurynas-biveinis)]

   I am not sure if -DHAVE_PAM=O for FreeBSD should be used in
   addition to the other options or instead of them?

   Line 34: "it's been built" doesn't sound right to me but I'm not
   sure why. "it is built with the server by default" perhaps?
   Articles:
   In case the build environment
   in case the plugin isn't needed

review: Needs Fixing

[Laurynas Biveinis (laurynas-biveinis)]

review: Approve

=== modified file 'doc/source/index.rst'
--- doc/source/index.rst	2013-01-30 10:01:50 +0000
+++ doc/source/index.rst	2013-02-06 10:29:23 +0000
@@ -129,6 +129,7 @@
    management/secure_file_priv_extended
    management/expanded_program_option_modifiers
    management/changed_page_tracking
+   management/pam_plugin
 
 Diagnostics Improvements
 ========================

=== modified file 'doc/source/installation.rst'
--- doc/source/installation.rst	2012-12-14 09:58:23 +0000
+++ doc/source/installation.rst	2013-02-06 10:29:23 +0000
@@ -134,8 +134,8 @@
 The ``libmysqlclient-dev`` package contains header files needed to
 compile software to use the client library.
 
-The ``libmysqlclient16`` package contains the client shared
-library. The ``16`` is a reference to the version of the shared
+The ``libmysqlclient18`` package contains the client shared
+library. The ``18`` is a reference to the version of the shared
 library. The version is incremented when there is a ABI change that
 requires software using the client library to be recompiled or their
 source code modified.
@@ -201,3 +201,7 @@
   $ cmake . -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_CONFIG=mysql_release -DFEATURE_SET=community -DWITH_EMBEDDED_SERVER=OFF
   $ make
   $ make install
+
+.. note::
+
+  :ref:`pam_plugin` has been merged into |Percona Server| in :rn:`5.5.24-26.0` but it is not built with the server by default. In order to build the Percona Server with PAM plugin, additional option :option:`-DWITH_PAM=ON` should be used.

=== added file 'doc/source/management/pam_plugin.rst'
--- doc/source/management/pam_plugin.rst	1970-01-01 00:00:00 +0000
+++ doc/source/management/pam_plugin.rst	2013-02-06 10:29:23 +0000
@@ -0,0 +1,72 @@
+.. _pam_plugin:
+
+===========================
+ PAM Authentication Plugin
+===========================
+
+Percona PAM Authentication Plugin is a free and Open Source implementation of the |MySQL|'s authentication plugin. This plugin acts as a mediator between the |MySQL| server, the |MySQL| client, and the PAM stack. The server plugin requests authentication from the PAM stack, forwards any requests and messages from the PAM stack over the wire to the client (in cleartext) and reads back any replies for the PAM stack.
+
+ PAM plugin uses dialog as its client side plugin. Dialog plugin can be loaded to any client application that uses :file:`libmysqlclient` library.
+
+Here are some of the benefits that Percona dialog plugin offers over the default one:
+
+  * It correctly recognizes whether PAM wants input to be echoed or not, while the default one always echoes the input on the user's console.
+  * It can use the password which is passed to |MySQL| client via "-p" parameter.
+  * Dialog client `installation bug <http://bugs.mysql.com/bug.php?id=60745>`_ has been fixed.
+  * This plugin works on |MySQL| and |Percona Server|.
+
+Percona offers two versions of this plugin:  
+
+  * Full PAM plugin called *auth_pam*. This plugin uses *dialog.so*. It fully supports the PAM protocol with arbitrary communication between client and server.
+  * Oracle-compatible PAM called *auth_pam_compat*. This plugin uses *mysql_clear_password* which is a part of Oracle MySQL client. It also has some limitations, such as, it supports only one password input. You must use ``-p`` option in order to pass the password to *auth_pam_compat*.
+
+These two versions of plugins are physically different. To choose which one you want used, you must use *IDENTIFIED WITH 'auth_pam'* for auth_pam, and *IDENTIFIED WITH 'auth_pam_compat'* for auth_pam_compat.
+
+Installation
+============
+
+This plugin requires manual installation because it isn't installed by default. :: 
+
+ mysql> INSTALL PLUGIN auth_pam SONAME 'auth_pam.so';
+ 
+After the plugin has been installed it should be present in the plugins list. To check if the plugin has been correctly installed and active :: 
+
+ mysql> SHOW PLUGINS;
+ ...
+ ...
+ | auth_pam                       | ACTIVE   | AUTHENTICATION     | auth_pam.so | GPL     |
+
+Configuration
+=============
+
+In order to use the plugin, authentication method should be configured. Simple setup can be to use the standard UNIX authentication method (``pam_unix``).
+
+.. note:: 
+
+  To use ``pam_unix``, mysql will need to be added to the shadow group in order to have enough privileges to read the /etc/shadow.
+
+A sample `/etc/pam.d/mysqld` file: ::
+
+  auth       required     pam_unix.so
+  account    required     pam_unix.so
+
+For added information in the system log, you can expand it to be: ::
+
+  auth       required     pam_warn.so
+  auth       required     pam_unix.so audit
+  account    required     pam_unix.so audit
+
+Creating a user
+================
+
+After the PAM plugin has been configured, users can be created with the PAM plugin as authentication method :: 
+
+  mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED WITH auth_pam;
+
+This will create a user ``newuser`` that can connect from ``localhost`` who will be authenticated using the PAM plugin. If the ``pam_unix`` method is being used user will need to exist on the system.
+
+Version Specific Information
+============================
+
+  * :rn:`5.5.24-26.0`
+    PAM authentication plugin has been integrated with |Percona Server|.

=== modified file 'doc/source/release-notes/Percona-Server-5.5.24-26.0.rst'
--- doc/source/release-notes/Percona-Server-5.5.24-26.0.rst	2012-09-18 05:04:43 +0000
+++ doc/source/release-notes/Percona-Server-5.5.24-26.0.rst	2013-02-06 10:29:23 +0000
@@ -11,7 +11,7 @@
 Features
 ========
 
-  * Percona PAM authentication plugin has now been integrated into the |Percona Server|. 
+  * Percona :ref:`pam_plugin` has now been integrated into the |Percona Server|. 
 
   * |Percona Server| has implemented variable :variable:`enforce_storage_engine` which can be used for enforcing the use of a specific storage engine.