# # Jason Woodward # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Library General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. Features: * Free Software (licensed under the GPL) * simple, self contained * customizable and themeable (css and template support) * mod_perl ready * SSL ready * Standards based; POP3, SMTP makes it cross platform and portable (OS independant) * International support (over 19 languages) * Sending and recieving of attachments supported * encrypted session/password info using Blowfish encryption * APOP and PASS POP3 support (via Mail::Box) * folder support (via Mail::Box), exportable to mbox * ability to search folders * user level customization (message listing, reply style, signature, full name, copy on send destination) * Contact management, exportable in vcard format * Calender with notes * Curses Administration interface Contents: ====================================== 1. Setup 2. Upgrading 3. Troubleshooting 4. Notes 5. Hacking 6. Contributers ====================================== 1. Setup ====================================== * REQUIREMENTS * Perl 5.6.1 (minimum, required by Mail::Box) * External modules (all available from http://www.cpan.org ) [NOTE] some of these modules require other modules (their own dependencies) not listed here. Refer to their documentation. I recommend you run `make test` before installing each. Net::IMAP::Client (version 0.6) perl -MCPAN -e 'install Net::IMAP::Client' Template http://www.cpan.org/authors/id/A/AB/ABW/ perl -MCPAN -e 'install Template' Crypt::Blowfish: (Encryption): http://www.cpan.org/authors/id/D/DP/DPARIS perl -MCPAN -e 'install Crypt::Blowfish' Crypt::CBC (Encryption): http://cpan.valueclick.com/authors/id/L/LD/LDS/ perl -MCPAN -e 'install Crypt::CBC' Debian: apt-get install libcrypt-blowfish-perl libcrypt-cbc-perl DateTime::Format::Mail: http://search.cpan.org/dist/DateTime-Format-Mail/ perl -MCPAN -e 'install libdatetime-format-mail-perl' HTML::FormatText http://search.cpan.org/~sburke/HTML-Format-2.04/ perl -MCPAN -e 'install HTML::FormatText' Debian: apt-get install libhtml-format-perl Email::MIME http://search.cpan.org/~rjbs/Email-MIME-1.861/ perl -MCPAN -e 'install Email::MIME' Debian: apt-get install libemail-mime-perl For the optional Curses Administration configuration frontend: Curses::UI: http://search.cpan.org/author/MARCUS/ perl -MCPAN -e 'install Curses::UI' File::Find::Rule: http://search.cpan.org/author/RCLAMP/ perl -MCPAN -e 'install File::Find::Rule' *Installation * Place the webmail.pl script inside your cgi-bin directory. To install the support modules, you can use the supplied Makefile.PL: perl Makefile.PL make make install #as root If you would like to install the support modules manually, you can either copy or create a PerlWebmail directory inside of your cgi-bin, or you can modify the 'use libs' line within webmail.pl to point to where the PerlWebmail directory is. Or you can put PerlWebmail/ inside of perl's @INC. That is up to you. * You will need to create a working directory for the users mailboxes and their Config.pm ( /var/lib/perlwebmail for example). This directory should be owned by the user and group your webserver runs as. This is then set in PerlWebmail/Config.pm as the 'user_storage' setting. * You can copy the images wherever you want within your webservers document tree. Modify PerlWebmail/Config.pm appropriately (imagelocation) for that location. * You can copy the webmail.css to wheverer you want within your http document root. Modify PerlWebmail/Config.pm appropriately for that location. * You will need to copy the contents of templates/ in the source directory to the location specified by the template_dir value in PerlWebmail/Config.pm or modify the value of template_dir as necessary. * Also, please check the main webmail.pl script as there may be some customization for you to do. Make sure you customize the 'use libs' line so that webmail.pl can find the perl modules (Config.pm, Language.pm, Theme.pm, UserConfig/DB.pm, UserConfig/File.pm, and UserConfig.pm). * Please customize the PerlWebmail::Config settings either via the curses admin interface or by directly editing PerlWebmail/Config.pm. To use the PerlWebmail::ConfigAdmin curses configuration, you must install the Curses::UI and File::Find::Rule modules. See: perldoc PerlWebmail::ConfigAdmin If you are going to edit the PerlWebmail/Config.pm file, keep the following in mind: Config.pm allows you to specify settings on a per domain basis. There is a 'default' => {}, entry already. You simply add your fully qualified domain below as 'webmail.foo.org' => {}, It is strongly recommended you leave the default entry as a fall back mechanism in case webmail.pl cannot map to a predefined domain. logouturl: url to go to after user logs out cssurl: url to webmail.css popauthmode: one of 'LOGIN', 'APOP', or 'AUTO' popserver: hostname of pop3 server popserverport: port for pop3 service (normally 110) smtpserver: hostname of smtp server smtpserverport: port of smtp service (normally 25) charset: default charset maxmesslistnum: maximum number of messages to list (user overridable) imagelocation: url to images hostname: the host appended to the usernames to form email addresses defaultsort: default message sorting (user overridable user_storage: local directory to store user configuration and mailboxes encryptlinksandforms: encrypt GET links and POST forms (debugging) debug: adds extra debugging info to HTML output (debugging) * Edit PerlWebmail/Theme.pm and webmail.css to modify the look of the html output. * PERL WEBMAIL should be mod_perl compliant. Please send in bug reports if you have any issues under mod_perl. * You will want to remove 'use strict' and 'use warnings' after you are finished testing to eliminate their overhead in production. * To use the PerlWebmail::UserConfig::DB backend data store, you must install the DBI and DBD::Pg modules. Support for other databases is planned, but is easily implemented by changing a few lines within the PerlWebmail::UserConfig::DB module. To enable, change the PerlWebmail::UserConfig constructor following the conventions setup in the PerlWebmail::UserConfig::DB perldoc. This feature is experimental. See: perldoc PerlWebmail::UserConfig::DB ====================================== 2. Upgrading ====================================== * To upgrade, See "Notes" below. *IT IS IMPORTANT TO BACKUP YOUR Config.pm and Theme.pm manually!* You can upgrade the support modules by following the installation instructions above (make sure to backup your Config.pm and Theme.pm). Then restore or merge them over/with the new copies. The steps below are for manually upgrading. a. unpack the tarball, then b. copy the webmail.pl to your cgi-bin location, overwriting your existing webmail.pl e. Study and modify the included Config.pm. Move Config.pm over your existing PerlWebmail/Config.pm f. copy the new Language.pm file over your existing Language.pm file. g. Study and modify the included Theme.pm. Copy Theme.pm over your existing Theme.pm and modify to suit your needs. h. copy ConfigAdmin.pm, UserConfig.pm, UserConfig/DB.pm, and UserConfig/File.pm over your existing copies. ====================================== 3. Troubleshooting ====================================== * Check to make sure the perl modules are actually present: perl -e 'use CGI qw(:standard); ' > /dev/null 2>&1 || echo need CGI perl -e 'use Crypt::Blowfish; ' > /dev/null 2>&1 || echo need Crypt::Blowfish perl -e 'use Crypt::CBC; ' > /dev/null 2>&1 || echo need Crypt::CBC perl -e 'use IO::Scalar; ' > /dev/null 2>&1 || echo need IO::Scalar perl -e 'use Mail::Box::Manager; ' > /dev/null 2>&1 || echo need Mail::Box::Manager perl -e 'use Date::Parse; ' > /dev/null 2>&1 || echo need Date::Parse * If you are having problems that seem like connection issues and are using tcp/wrappers, try adding an entry in your /etc/hosts and /etc/hosts.allow file for each hostname inside your Config.pm. Also, if these addresses are nat'd, go ahead and add the internal and external address. * If you are getting 500 errors, please check the permissions on the scripts and the modules. Make sure the user that your webserver is running under has the correct permissions to access and/or execute the correct files. See: man chmod See: man chown * If you need to email me or the mailing list, please collect the output of the following: perl -V perl -MMail::Box -e 'print $Mail::Box::VERSION,"\n";' perl -MCGI -e 'print $CGI::VERSION,"\n";' perl -c webmail.pl perl ./webmail.pl what pop3 server you are attempting to connecting too * For SSL support, just call the webmail script via a https link. You will have to change the values inside the Config.pm so that the URLs within are fully qualified https URLs. * If you are getting 500 errors complaining about upload not being found, you will need to update your CGI.pm from CPAN ( http://www.cpan.org/authors/id/L/LD/LDS ). * If you are having problems with the multipart/form-data form submission (sending mail) such as getting kicked back to the login screen, check that your CGI.pm is up to date. If you are using mod_gzip try the following configuration addition: mod_gzip_item_exclude reqheader Content-Type:multipart/form-data ====================================== 4. Notes ====================================== *As of 3.0.4, the UserConfig backend has been split out into UserConfig::File and UserConfig::DB. The DB backend is experimental (currently hard coded for PostgreSQL), but seems to work ok. Any testing or bug reports are appreciated. *As of 3.0.0, this is a complete rewrite. All old code has been thrown away and replaced. This is a development release. Things will need to be tested and stabilized. Some features are incomplete (see TODO). Theme.pm and Config.pm both have new syntaxes, so you will need to examine them and apply your customizations to their new format. *As of 2.4.1 CGI::EncryptForm was added to required module list to alleviate the get being public. *As of 2.3.14 The language packs have change from perl modules so that they can be required/import'd at runtime. *As of 2.3.8 the configuration has been moved into Config.pm and the language files have been perl modulized as well. If you would like to fix a specific encoding type, see the two functions: convert, convertCoded There is now a mailing list setup, Signup and archives available here: http://software.jaos.org/cgi-bin/mailman/listinfo/perlwebmail-devel *As of 2.3.6: The webmail.conf file has been moved into Config.pm (which in turn is inside PerlWebmail/ along side the Language_*.pm files). The perlwebmailconfig utility has been updated to read this file. You may have to manually edit your Config.pm file as the old webmail.conf file is not supported with the new perlwebmailconfig utility. Or you can copy the first 6 lines out of the Config.pm file into your existing webmail.conf file, then rename it PerlWebmail/Config.pm. The perlwebmailconfig utility will then read that file for your existing settings. Check http://sofware.jaos.org/ for debs. *As of 2.2.16, the language paks have been updated for the $LISTMESSAGES_MORE variable (and more). I am unable to translate all, so please send back modified versions for your language (if you are so inclined). Also note new perlwebmailconfig utility and webmail.conf format. There is also a cvs repository for webmail available at CVSROOT=:pserver:anonymous@jaos.org:/var/cvs cvs login (no pass) cvs -z3 checkout webmail or via http://software.jaos.org/cgi-bin/cvsweb The config utility was renamed perlwebmailconfig in 2.3.2. This is going to help move the webmail package into a more packageable format very soon... *As of 2.2.15, the language paks have been updated for the CC and BCC fields. I am unable to translate all, so please send back modified versions for your language (if you are so inclined). *As of 2.2.13, a new config format has been introduced. All old webmail.conf files will have to be updated (as well as the perlwebmailconfig utility). Replace yours from the webmail tarball. *As of 2.2.11, The Blowfish module was causing problems with passwords over 8 characters long. This version fixes that problem with the addition of the Crypt::CBC (cipher block chaining) module. This allows longer strings to be encrypted. The md5 requirement (see libmd5-perl) for Crypt::CBC has caused a lot of people problems, since the digest perl modules do not provide the legacy MD5.pm module. Debian users can apt-get the libmd5-perl package. All other OS/distro users should consult your vendor. ====================================== 5. Hacking ====================================== * Plugins (Planned): Soon you will be able to register your plugin with a require line. There will be ways to register a toolbar button, read message link, and any custom actions, maybe like: $global->{actions}->{my_custom_action} = sub { custom_func1(); custom_func2(); }; To add a custom button to the toolbar, its similar except $global->{buttons} is an arrayref, so to add your custom button: push(@{$global->{buttons}},['custom_action','image_filename.png','text description']); * Code additions, cleanups, or updates If you have an idea or a patch, the best way to contribute is to send a message into the mailing list to find out if someone else has already started or finished a patch. Maybe your implementation is better. If so, the mailing list is the best place to start. Patches are best submitted against current cvs. A brief explanation about your patch is very helpful. * Language Translations Language translations, new or update of existing, are always appreciated. If you have an update for an existing language, please make your diff against current CVS. If you would like to add a new language, try to identify the HTTP_ACCEPT_LANGUAGE http header for that language, and add it as the hash key in the Language.pm language->{} hashref. * Graphics, CSS, HTML Updates to any of the images/graphics are most welcome. Currently the default distributed images come from the Gnome desktop and Evolution email suite. [NOTE], if you are the author of said images and have any issues with those images being distributed within this GPL package, please email me asap! New graphics are welcome. Updated CSS is very needed. HTML fixes or updates are always welcome. Please keep the javascript to a minimum or none at all if at all possible. ====================================== 6. Contributers ====================================== *VERSION 3 completely authored by Jason Woodward Inspired by contributions of code and ideas from many including those listed below. *VERSION 2 and language/code contributers: Alx Andreas Fitzner Andrey N. Nidchenko Łukasz Karbowski Brendan Kehoe Christopher E. Stith / <_pcu_@yahoo.com> Christopher Gilmore Drew Schatt Eric-S Lachance G.Home Gary Guthary Greg Ing. Alejandro Lay Ian Thurlbeck James Freeman Jan Houtsma Jan Kudrnovsky Joe Rinck/Axiom joe@axiom.co.za. J?rgen N?rgaard Kalin Kallai Peter Kevin L. Papendick Lawrence Abel Lincoln Bauer Louis Lyle Marcelo Miranda Mirko Elviro Massimiliano Francario Nick Pinckernell Nicolas.Martin@lodyc.jussieu.fr Paul Hein Paul Murphy Phil Endecott Piotr Dawidowski Robert James Kaes Robert Frunzke Robert R. George Rod@querix.com Stanislav Lechev Stefano Selleri Steve Head alol@sm-as.dk eric@hallway.com gdavis@mn.rr.com kkeller@speakeasy.net lbauer@sirus.com vdongen@hetisw.nl wbg ZUKERAN, shin ====================================== Also, I would like to thank all the Free Software developers who have enabled me to work in a Free, open enviroment and have allowed me the opportunity to contribute a little bit back. Thank you! If you have any questions, ideas, problems, or just wanna tell me how much this script sucks =]... join the mailing list: http://software.jaos.org/cgi-bin/mailman/listinfo/perlwebmail-devel Jason Woodward