Squirrel Logger plugin for SquirrelMail
=======================================
Ver 2.3, 2008/11/30


Copyright (c) 2001-2004 Ron Chinn <ron@squeaksoft.com>
              2002-2003 Pat Winn <ptwinn@velocibyte.com>
              2005-2008 Paul Lesniewski <paul@squirrelmail.org>



Description
===========

This plugin implements logging functionality for your webmail
interface.  You can choose to log to a database, a file, your
system log, or any combination thereof.  You can also choose
which kinds of events to log, including login events, logout
events, login error events, all outgoing messages, possible
outgoing spam messages, and other error events.

Also included is monitoring functionality that will send alert
emails to the administrator when certain events trigger.

If you use the timeout_user plugin, logout events caused by
user timeouts will be captured.

Log message format is also completely custom-defined to meet
your needs in the configuration file.



License
=======

This plugin is released under the GNU General Public
License (see COPYING for details).



Donations
=========

If you or your company make regular use of this software, please
consider supporting Open Source development by donating to the authors
or inquire about hiring them to consult on other projects.  Donation/
wish list links for the author(s) are as follows:

Paul Lesniewski: https://sourceforge.net/donate/index.php?user_id=508228



Requirements
============

  * Compatibility plugin, version 2.0.10 or above

  * For logging of failed login attempts or other errors, you need
    at least SquirrelMail 1.4.4

  * For logging of outgoing messages, you need SquirrelMail at least 1.4.6

  * For logging to SQL databases, you need Pear and a SQL-compliant database



Installation
============

See the INSTALL file for setup instructions.



Configuration
=============

Please see the configuration file included herein.



Privacy
=======

PLEASE NOTE that some of the logging and alert types may be
considered invasive (particularly MASS_MAILING) and if you
turn them on, BE SURE your users understand that their
messages may be subject to review.  You are encouraged to
have an appropriate privacy policy and terms of service
agreement if you use these options.

Keep user privacy concerns in mind whilst carefully setting
the following options:

$sl_log_mass_mailing_show_recipients
$sl_log_mass_mailing_show_from
$sl_log_mass_mailing_show_reply_to
$sl_log_mass_mailing_show_subject
$sl_log_mass_mailing_show_message_body
$sl_log_outgoing_messages_show_recipients
$sl_log_outgoing_messages_show_from
$sl_log_outgoing_messages_show_reply_to
$sl_log_outgoing_messages_show_subject
$sl_log_outgoing_messages_show_message_body



Help Requests
=============

Before looking for help elsewhere, please try to help yourself:

  * Read the Troubleshooting section herein.

  * Look to see if others have already asked about the same issue.
    There are tips and links for the best places to do this in
    the SquirrelMail mailing list posting guidelines:
    http://squirrelmail.org/wiki/MailingListPostingGuidelines
    You should also try Google or some other search engine.

  * If you cannot find any information about your issue, please
    first mail your help request to the squirrelmail-plugins
    mailing list.  Information about it can be found here:
    http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
    You MUST read the mailing list posting guidelines (see above)
    and include as much information about your issue (and your
    system) as possible.  Including configtest output, any debug
    output, the plugin configuration settings you've made and
    anything else you can think of to make it easier to diagnose
    your problem will get you the most useful responses.  Inquiries
    that do not comply with the posting guidelines are liable to
    be ignored.

  * If you don't get any replies on the mailing list, you are
    welcome to send a help request to the authors' personal
    address(es), but please be patient with the mailing list.



Tips and Troubleshooting
========================

  * If, when logging to file, 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 or your database connection parameters are incorrect.

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

  * If you use the login_alias, password_forget, vlogin or other
    plugins that might manipulate the username during login, this
    plugin might be best placed *AFTER* those plugins in the list
    of all activated plugins.

  * Make sure the plugin is configured correctly by browsing to
    http://your-squirrelmail-location/src/configtest.php

  * For information about setting up fail2ban to monitor the failed
    login attempts that Squirrel Logger catches, see the file
    "fail2ban" in the "contrib" directory.

  * If you have some SMTP authentication method configured in the
    main SquirrelMail configuration (or perhaps POP before SMTP is
    turned on) and administrative alert emails are not getting sent,
    particularly when a user fails to login, this is because the
    SMTP authentication credentials are not yet available before a
    user has logged in, so you need to provide administrative
    credentials for sending such emails.  See $sl_smtp_auth_mech
    (and related settings) in the configuration file.

  * If changes to the configuration file don't seem to be having any
    effect, ensure that there are not two Squirrel Logger configuration
    files, one in the squirrel_logger directory and one in the main
    SquirrelMail config directory (named "config_squirrel_logger.php").
    The one in the main SquirrelMail config directory will always
    override the one in the squirrel_logger directory.



Viewing Logs
============

Included herein is a script called "show_stats.php" that will let
you query and manage your logs if they are in a MySQL database.
This script could conceivably be modified to use Pear and be brought
inside of the SquirrelMail interface; contributions welcome.  For
now, if you want to use this, you'll have to edit the file and
take the first "exit" command out, then put the file somewhere
safe (password protected) and have fun.



Data Schema
===========

If you use the SQL logging type, you will need a database table
that the plugin can work with.  What follows is the recommended
DDL for the logging table.  You may change this at will, but be
sure to update the needed SQL queries in the config.php file.
This is a MySQL DDL, but should be easily adapted to your database
of choice.


CREATE DATABASE squirrelmail_logging;
GRANT SELECT, UPDATE, INSERT, DELETE on squirrelmail_logging.* TO 'user'@'localhost';

CREATE TABLE user_activity (
  id int(11) NOT NULL auto_increment,
  event varchar(30) NOT NULL,
  username varchar(128) NOT NULL,
  domain varchar(128) NOT NULL,
  remote_address varchar(255) NOT NULL,
  date datetime NOT NULL,
  comments varchar(255) DEFAULT '',
  PRIMARY KEY (id),
  UNIQUE KEY id (id),
  KEY event (event),
  KEY domain (domain),
  KEY date (date)
) TYPE=MyISAM;



API
===

It is possible for other plugins and code to send custom log events
to the SquirrelMail log.  Any event types are acceptable, as long
as they are added to the $sl_log_events, $sl_logs and possibly
$sl_send_alerts (and $sl_alert_to, etc) settings in the configuration
file.  The two possible points of entry for logging an event are:

   sl_logit($event, $message='', $user='')
   sl_send_to_log($event, $timestamp, $date_str, $user='', $dom='',
                  $remote_addr='', $message='')

sl_logit() will construct the log fields for you, using the current
request and SquirrelMail login environment (note that the $user parameter
to sl_logit() is only an override and is not usually necessary).
sl_send_to_log() may be used when any of the logged fields need to be
built differently by other modules; this function will only dispatch
the fields to the needed log backends.  See the documentation for
both of these functions in the "functions.php" file herein.



Todo
====

  * For logging outgoing messages, do we want to include any headers
    beside Message-ID, From, Reply-To, Subject and To/Cc/Bcc?

  * Someone once asked to have the ability to log when users download
    message attachments.  This would probably involve a source hack,
    and it's a one-off request, so I am leaving it alone for now.  If
    many people see this and think "that's a great idea", please speak
    up and maybe it can be implemented.



Change Log
==========

  v2.3  2008/11/30  Paul Lesniewski <paul@squirrelmail.org>
    * Added ability to show message subject separately from
      message body when logging OUTGOING and MASS_MAILING events
    * Added ability to log From and Reply-To headers for
      the OUTGOING and MASS_MAILING events
    * Make the From address for administrative alert messages
      configurable
    * Added ability to store configuration file in main SquirrelMail
      config directory

  v2.2  2008/04/11  Paul Lesniewski <paul@squirrelmail.org>
    * Allow overrides of SquirrelMail SMTP/Sendmail settings
      when sending administrative alert emails

  v2.1  2008/02/06  Paul Lesniewski <paul@squirrelmail.org>
    * HTML is removed from any log messages; multiline messages
      crammed into one line
    * System logging controls have been made much more fine-grained;
      $sl_syslog_priority has been removed from the configuration
      file
    * Small code cleanup
    * Use sq_send_mail() to send alerts
    * Added logging of all outgoing messages
    * Make sure syslog events are done in UTC/GMT when configured as
      such (Thanks to Eray Aslan)

  v2.0  2005/06/10  Paul Lesniewski <paul@squirrelmail.org>
    * Re-write and cleanup; the plugin has changed quite a bit
      (many new configuration settings, log format has changed
      slightly (it's completely configurable though), new
      features... needs testing)
    * Split configuration into separate file
    * Log messages configurable per log type and event type
    * Merged SQL functionality from SQL Logger plugin
    * Logging can be done to more than one place
    * Logging can be turned on/off per event type
    * Alert emails can be sent to administrators
    * Added monitoring of outgoing messages for mass mailings
      (possible spam)
    * Added API so other plugins and code can log custom events
    * Minor cleanup of show_stats.php
    * Will now fail silently if database connection can't be made
    * Added ability to turn on/off logging for certain domains

  v1.4  2004/03/23
    * Added option to log to syslog

  v1.3  2003/03/28
    * 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)

  v1.2  2001/10/12
    * 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.

  v1.1  2001/10/12
    * Added hostname lookup feature (set $sl_namelookups)
    * Changed default time format to show date before time.

  v1.0  2001/10/11
    * Initial Release