Squirrelmail Logging Plugin (sql_squirrel_logger)
----------------------------------------------------------------------------
Coded by Pat Winn <ptwinn@velocibyte.com>
Version 1.0 (01/19/2002)

Coded originally as squirrel_logger by Ron Chinn, <ron@amalgasys.com>  ICQ#: 4479244
squirrel_logger uses a file instead of database, so if you want a file use his
instead ;-) This is pretty much a re-write.

Parts of this readme taken from Ron's (sorry, I'm being lazy).

DESCRIPTION
----------------------------------------------------------------------------

This is a short bit of code that will log user logins and logouts to a 
mysql database.  It's useful if you want to know who's using your
Squirrelmail installation, for how long, etc.  

The username, event, remote host and date are logged.
Event is either "LOGIN", "LOGOUT", "TIMEOUT", or "INVALID".  

The plugin cooperates with Ray Black's Timeout User plugin to determine if 
a logout is due to the user clicking "sign out" or if they were timed out 
due to idle time.

I welcome any comments (positive or negative) you might have.  If you want
an additional feature, let me know.  I'll try to accomodate it as best I 
can.  My email address is ptwinn@velocibyte.com.

This plugin has been written and tested under SquirrelMail v1.2.3 cvs.
I have not tested it under any other version, so feedback would be helpful.


INSTRUCTIONS
---------------------------------------------------------------------------
1. Change to the plugins/ directory of your SquirrelMail installation.

2. Unpack the Squirrel_Logger archive

   tar xvzf <path_to_archive>/squirrel_logger.tgz

   (the command for your system may vary)

3. Edit the setup.php and showinfo.php files in the squirrel_logger directory.  
   There are instructions at the top of the files to help you.

4. Edit mysql.sql to taste (set the database name to use, etc.) and then create the database:
   somehost$ mysql -u root -p < myssql.sql 

5. Grant the database user you wish to use permissions on the table as shown in mysql.sql.

6. MAKE CERTAIN THAT DATABASE NAME, TABLE NAME, ETC. MATCH UP!!
   The variables at the top of setup.php and showinfo.php MUST match what is in the database or this
   will not work ;-) (I know, should go without saying..)

7. Go to the config directory and run conf.pl to activate the plugin.
   For more detailed instructions, see SquirrelMail's web page:

   http://www.squirrelmail.org/wiki/index.php?page=InstallingPlugins


** Optional Step:  (The plugin will function without this, but will not
                    log failed login attempts at all.)

8. If you want to log invalid login attempts, you have to edit the 
   SquirrelMail source. In the functions/imap_general.php file, add:

   do_hook('invalid_login');

   right before the call to session_destroy() at the end of the
   sqimap_login() function.  

   In 1.2.3 cvs, this is at line 227.

   In any case, insert the hook before the only call to session_destroy()
   in imap_general.php. (This is subject to change in future releases
   of SquirrelMail, of course.)

   Invalid attempts will show up in red in the showinfo.php page should you decide
   to log them.

9. The showinfo.php file is what you want to call up in your browser to
   view the data being logged. Please consider putting it in a seperate
   directory and use a .htaccess file or something to prevent just anyone
   from using it. Leaving it in the default location and unprotected could 
   allow someone to view user account names, etc. You have been warned ;-)

** This is GPL'd code. You may do with it what you like so long as the
   original author(s) retain credit where credit is due.

=========================================================================
Standard Disclaimer Thingy:
 Use this code at your own risk. The author assumes no responsibility
 for anything it might do. You are on your own. 
=========================================================================


TIPS
---------------------------------------------------------------------------

If you don't see anything going into the database, insert a line somewhere
in the doQuery() function in setup.php which calls error_log('your info', 0);
to debug it. 'your info' could be the $db, $dbuser, $dbhost, etc. variables
so you can see what is being passed. The output by default will go into your
web server error log so long as you are using Apache.

Also try logging into mysql as your database user and try to insert a record
by hand to make sure that things are working there (for additional troubleshooting
if need be).

CHANGELOG
---------------------------------------------------------------------------

1.0.0   01/19/2002
        Initial release.
