pam_mysql - A PAM authentication module against MySQL database.
$Id: README,v 1.4.2.3 2005/06/13 10:26:20 moriyoshi Exp $

Introduction
------------
This is a successor of the "old" pam_mysql module, which comes with
a more stable, secure and robust implementation.

Prerequisites
-------------
To try this module, you need the following stuff:
 - A *NIX (or similar) system, in which PAM facility is set up and working
   either system-wide or in a chroot jail.
 - A MySQL server, up and running.

Installation instruction
------------------------
See INSTALL file for detail.

An example of the configuration file:
---------------------------------------------------------------
auth       optional     pam_mysql.so user=root passwd=password
account    required     pam_mysql.so user=root passwd=password
---------------------------------------------------------------

Available options
-----------------
The module options are listed below with default in ()s:

verbose (0)

    If set to 1, produces logs with detailed messages that describes what
    pam-mysql is doing. May be useful for debugging.

user

    The user name used to open the specified MySQL database.

passwd

    The password used to open the specified MySQL database.

host

    The host name or the absolute path to the unix socket where the
	MySQL server is listening.  The following formats are accepted:

    1. absolute path to the unix socket (e.g. "/tmp/mysql.sock")
	2. host name (e.g. "somewhere.example.com")
	3. host name + port number (e.g. "somewhere.example.com:3306")

db

    The name of the database that contains a user-password table.

table

    The name of table that maps unique login names to the passwords.
    This can be a combination of tables with full JOIN syntax if you
    need more control.  For example:

        [table=Host LEFT JOIN HostUser ON HostUser.host_id=Host.id \
                    LEFT JOIN User ON HostUser.user_id=User.id]

update_table

    The name of the table used for password alteration.
    If not defined, the value of the "table" option will be used instead.
    This is handy if you have a complex JOIN instead of a simple table in
    the "table" option above.

usercolumn

    The name of the column that contains a unix login name.
    Should be in a fully qualified form.

passwdcolumn

    The name of the column that contains a (encrypted) password string.
    Should be in a fully qualified form.

statcolumn

    The name of the column that indicates the status of the user.
    Should be in a fully qualified form.

crypt (plain)

    The method to encrypt the user's password:

       0 (or "plain") = No encryption.  Passwords stored in plaintext.
                        HIGHLY DISCOURAGED.

       1 (or "Y")     = Use crypt(3) function.

       2 (or "mysql") = Use MySQL PASSWORD() function. It is possible
                        that the encryption function used by pam-mysql
                        is different from that of the MySQL server, as
                        pam-mysql uses the function defined in MySQL's
                        C-client API instead of using PASSWORD() SQL function
                        in the query.
                        
       3 (or "md5")   = Use plain hex MD5

where

    Additional criteria for the query. For example:
	    [where=Host.name="web" AND User.active=1]

sqllog

	If set to either "true" or "yes", SQL logging is enabled.

logtable

    The name of the table to which logs are written.

logmsgcolumn

    The name of the column in the log table to which the description of the
    performed operation is stored.

logusercolumn

    The name of the column in the log table to which the name of the user
    being authenticated is stored.

logpidcolumn

    The name of the column in the log table to which the pid of the process
    utilising the pam_mysql's authentication service is stored.

loghostcolumn

    The name of the column in the log table to which the IP address of the
    machine performing the operation is stored.

logtimecolumn

    The name of the column in the log table to which the timestamp of
    the log entry is stored.

BUGS
----
Beware that user names and clear text passwords may be logged to mysql.log
if you explicitly configured pam-mysql to log select statements (verbose=1).
(Not sure why you want to anyway, slogs your system down badly!)

Q&A
---
Q. What on earth is PAM anyway?

A. PAM is an acronym for Pluggable Authentication Modules.
   See http://www.kernel.org/pub/linux/libs/pam/whatispam.html for further
   information.

Q. Are there any tools for changing passwords, etc. that are in pam-mysql?

A. No, not provided yet.

Q. I need to retrieve misc. UNIX user information such as one's home
   directory coming from MySQL. Can pam-mysql do this?

A. No. As the name says, PAM is only involved in authentication
   that in principle has little to do with the account database itself.
   You need to use the nss-mysql module, which can be retrieved from here:
   http://savannah.nongnu.org/projects/nss-mysql

Q. How can I quickly tell in which way a given password is encrypted,
   PASSWORD(), CRYPT()-ed, or md5()?

A. Try using the following MySQL functions: ENCRYPT(), PASSWORD() and md5(),
   and compare the results with each other.

   SELECT ENCRYPT('mypass'), PASSWORD('mypass'), MD5('mypass');

LINKS
-----
- MySQL
  http://www.mysql.com/

- NSS-MySQL:
  http://savannah.nongnu.org/projects/nss-mysql

- OpenPAM
  http://www.openpam.org/

- PAM
  http://pam.sourceforge.net/

- sysauth-pgsql (the PostgreSQL counterpart of pam-mysql, accompanied by the
  nss module also)
  http://sourceforge.net/projects/sysauth-pgsql

- Cyrus-SASL
  http://asg.web.cmu.edu/sasl/sasl-library.html

- Sendmail-SQL:
  http://www.sourceforge.net/projects/sendmail-sql

