# Rev 9/26/2002

This document explains the why and how to get Squirrelmail to use a combination 
	of MySQL and PAM for authentication.


Requirements:
		MySQL
		UW IMAP (compiled with support for PAM)
		PERL (with DBI if you want to use our migration tools)



Why?  Reasons will vary, but here's why we did it:


1) Desire to authenticate all Squirrelmail users from a MySQL database.  This 
	proves to be more complicated than first sounds, because we wanted MD5 
	support in addition to crypt, and we needed the ability to force users 
	to change passwords.

2) Desire to continue to use UW's IMAP server


Please note that these instructions are geared for use on a (recent-flavor) linux system.
Your mileage may vary, or the whole thing may not work at all.  If you need to
contact us regarding these instructions, feel free to do so at squirrelmail@jeffco.net.

Now, back to the dirty work....


How:

0) Download howto_pam_mysql.tar from http://jeffco.net/downloads/squirrelmail

1) Grab pam_mysql from http://sourceforge.net/projects/pam-mysql/
	Unpack it and then replace pam_mysql.c with the patched version in the tarball 
	called pam_mysql.c, which supports MD5.  
	Read the instructions carefully in the pam-mysql package, but the main push
	is to get pam_mysql.so compiled and copied into /lib/security with the same
	ownership/modes as other /lib/security .so files.

2) Use create_db.sql from downloaded tarball to create the database:

		mysql -u root -p <create_db.sql

	Then, set the permissions with something like:
		mysql> GRANT all ON SquirrelMailAuth.* TO your_user@yourhost 
			identified by 'yourpassword';

3) Copy imap.txt from tarball to /etc/pam.d/imap; 
	edit the file to contain proper information for your setup (database, 
	user, yourpassword).  There is not need to reboot or do anything to 'tickle' 
	PAM to start using the imap file; it's dynamic in nature.

4) Next, install the squirrelmail change_mysqlpass plugin (v 2.0 or later) and be 
	sure to follow the instructions carefully.

5) Should you want to migrate existing users' passwords (/etc/shadow stuff) into the 
	new database, use tools/update_passwd_db.pl from tarball.  
	Edit it to reflect your configuration and try it out.  Please note that the 
	first thing the script does is whack the contents of the existing table, so be careful.
