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

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

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

The output is in the format:

event,user,IP,date

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

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, 
1.2.0[rc1], and 1.4.0[rc1].  If you get it to work with a different version, I'd like to 
know about it.


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 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.3     Mar 28, 2003
        Fixed safe mode file writing issue.  
         (Thanks to Christian Mayer for pointing this out.)
        Fixed the "Address is not a valid IPv4 or IPv6 address" issue
         (Thanks to Ingo Welling for the fix)

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