Squirrel Logger plugin for SquirrelMail ======================================= Ver 2.3, 2008/11/30 Copyright (c) 2001-2004 Ron Chinn 2002-2003 Pat Winn 2005-2008 Paul Lesniewski 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 * 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 * Allow overrides of SquirrelMail SMTP/Sendmail settings when sending administrative alert emails v2.1 2008/02/06 Paul Lesniewski * 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 * 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