Merge lp:~stewart/percona-pam-for-mysql/basic-docs into lp:percona-pam-for-mysql

[Stewart Smith]

some very basic docs to get people going. (updated based on review feedback)

[Valentine Gostev (longbow)]

Stewart,

124 +This creates a user `username` that can connect from `host` and will be authenticated using the PAM plugin.

We should also mention that 'username' account must exist in system.

[Valentine Gostev (longbow)]

see comment

review: Needs Fixing

[Laurynas Biveinis (laurynas-biveinis)]

In /etc/shadow question might be a good idea to add "the PAM libraries such as pam_unix.so" or similar.
In "compiling from source" I'd mention add to "MySQL 5.5 headers available on your system" "and corresponding mysql_config" or similar.

@Valentine - the account must exist on the system iff pam_unix.so is used (i.e. in other setups it's not necessary)

[Laurynas Biveinis (laurynas-biveinis)]

LGTM.
Will wait for Valentine's review before merging.

review: Approve

[Valentine Gostev (longbow)]

lgtm

review: Approve

=== modified file 'doc/source/faq.rst'
--- doc/source/faq.rst	2011-10-25 10:51:19 +0000
+++ doc/source/faq.rst	2011-11-14 04:10:27 +0000
@@ -22,3 +22,9 @@
 ====================================
 
 Yes.
+
+
+Can I use the PAM plugin to authenticate against /etc/shadow?
+=============================================================
+
+Yes, but you will need to run mysqld as root so that the PAM libraries such as 'pam_unix.so` can access /etc/shadow.

=== modified file 'doc/source/index.rst'
--- doc/source/index.rst	2011-10-25 10:51:19 +0000
+++ doc/source/index.rst	2011-11-14 04:10:27 +0000
@@ -2,7 +2,7 @@
  Percona PAM authentication plugin For MySQL - Documentation
 ============================================================
 
-Percona PAM authentication plugin for MySQL
+Percona PAM authentication plugin for MySQL.
 
 Introduction
 ============
@@ -17,7 +17,7 @@
 ============
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :glob:
 
    installation

=== modified file 'doc/source/installation.rst'
--- doc/source/installation.rst	2011-10-25 14:07:24 +0000
+++ doc/source/installation.rst	2011-11-14 04:10:27 +0000
@@ -5,4 +5,46 @@
 .. toctree::
    :hidden:
 
-Install instructions go here.
+Compiling from Source
+=====================
+
+You will need both the PAM headers and the MySQL 5.5 headers and corresponding `mysql_config` binary available on your system.
+
+If you are not using one of the pre-built binary packages, you will need to compile the plugin from source. You can either use a source tarball or the source repository.
+
+For getting a copy of the latest development bzr tree: ::
+
+  $ bzr branch lp:percona-pam-for-mysql
+
+If you are building from bzr, you will need to generate the configure script: ::
+
+  $ ./bootstrap
+
+You do not need to run `bootstrap` if you are using a source tarball.
+
+You then need to build the plugin: ::
+
+  $ ./configure
+  $ make
+
+To install, you can simply run (as root or using sudo or similar): ::
+
+  $ make install
+
+Installing server-side plugin
+=============================
+
+The shared library that holds the plugin, auth_pam.so, needs to be stored in the plugindir directory of mysql. You can get this value via the command: ::
+
+  $ mysql_config --plugindir
+
+Make sure that after installed, the library has got the appropiate permissions (file execution is required).
+
+Most packages should do this for you, so this is likely only required with the binary tarballs.
+
+  In order to load the plugin into the working server, issue the following command: ::
+
+ mysql> INSTALL PLUGIN auth_pam_server SONAME 'auth_pam.so';
+
+
+You can now create a PAM configuration for the MySQL server and create users that are authenticated by PAM.

=== modified file 'doc/source/manual.rst'
--- doc/source/manual.rst	2011-10-25 10:51:19 +0000
+++ doc/source/manual.rst	2011-11-14 04:10:27 +0000
@@ -8,4 +8,30 @@
    :maxdepth: 1
    :hidden:
 
-Manual goes here.
+Configuring PAM for MySQL
+=========================
+
+You will need to configure PAM on your system for how it should authenticate for MySQL. A simple setup can be to use the standard UNIX authentication method.
+
+*NOTE:* Using pam_unix means the MySQL Server needs to read the `/etc/shadow` file, which usually means it has to be run as `root` - usually not a recommended configuration.
+
+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
+===============
+
+You will need to execute `CREATE USER` with specifying the PAM plugin. For example: ::
+
+  CREATE USER 'username'@'host' IDENTIFIED WITH auth_pam_server;
+
+This creates a user `username` that can connect from `host` and will be authenticated using the PAM plugin. If you are using the `pam_unix` method in PAM (or similar) you will need to have an account for `username` existing on the system.