Squirrelmail Logging Plugin (squirrel_logger)
----------------------------------------------------------------------------
coded by Ron Chinn, <ron@squeaksoft.com>  ICQ#: 4479244
version 1.4

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

This is a short bit of code that will log user logins and logouts to a 
user specified flat file or syslog.  It's useful if you want to know who's 
using yourSquirrelmail installation, for how long, etc.  I wrote it when the 
subject came up on the SquirrelMail users mailing list.

The output of the flat file is in the format:

event,user,IP,date

Where event is either "LOGIN", "LOGOUT", "TIMEOUT", or "INVALID".  
The delimiter is changeable. You can turn on/off hostname lookups.  
You can specify what date format to use, also.

You can also enable syslog logging using any priority allowed in PHP.  The
syslog messages are in standard english sentences, rather than the
comma-delimited format of the flat file.

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 ron@squeaksoft.com.

This plugin has been reported to work with SquirrelMail 1.0.6, 1.1.2 and 
1.2.0[rc1].  If you get it to work with a different version, I'd like to 
know about it.  I'd also like to hear about any issues you may have.


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 file in the squirrel_logger directory.  There
   are instructions at the top of the file to help you.

4. Activate the plugin in SquirrelMail by using SquirrelMail's configuration
   script.  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.)

5. 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 version 1.0.6, this is near line 196.  
   In 1.2.0 rc1, this is at line 223.
   In 1.4.0 rc1, this is at line 319

   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.)



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

If the log file doesn't get updated and/or doesn't get created, check your
web server error log file (probably error_log if you're using apache).
It's likely that your web server doesn't have permission to write to the
log file.

If you want a human readable flat-file log format, consider using tab ("\t") 
as your field delimiter.  It'll space things out nicely and make it a lot easier
to read. 


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

1.4     Mar 28, 2003
        Added ability to log to syslog.

1.3	Mar 28, 2003
	Fixed safe mode issue.  Thanks to Christian Mayer for pointing this out.

1.2     Oct 12, 2001
        Added ability to log user inactivity timeouts using Ray Black's
          Timeout User plugin.
        Added failed login attempt logging.  This requires the user
          edit the imap_general.php file to add a hook.

1.1     Oct 12, 2001
        Added hostname lookup feature (set $sl_namelookups)
	Changed default time format to show date before time.

1.0     Oct 11, 2001
        Initial Release
