openwebmail faq and readme

How to install Open Webmail on Red Hat Enterprise Linux 3
=========================================================
By Thomas Chung (tchung AT openwebmail.org)
Last Updated 2003-12-01

pre-requisites: httpd-2.0.46-25.ent.i386.rpm and httpd service is running
sendmail-8.12.10-1.i386.rpm and sendmail service is running

1. install all perl rpm packages if you haven't installed yet.

2. install the latest openwebmail rpm build from daily build directory

3. initialize openwebmail database using openwebmail-tool.pl

cd /var/www/cgi-bin/openwebmail
./openwebmail-tool.pl --init

3.0) Ignore the warning

"The perl on your system has serious bug in routine tell()!
While openwebmail can work properly with this bug, other perl application
may not function properly and thus cause data loss.

We suggest that you should patch your perl as soon as possible."

3.1) change the following 3 options in openwebmail.conf

from
dbm_ext .db
dbmopen_ext none
dbmopen_haslock no
to
dbm_ext .db
dbmopen_ext %dbm_ext%
dbmopen_haslock no

3.2) execute './openwebmail-tool.pl --init' again

You won't see the same suggestion for changes or modification.

4. create a user account if you haven't created one yet

5. login to openwebmail using a user account
http://localhost.localdomain/cgi-bin/openwebmail/openwebmail.pl

For Virtual Hosting Domains
===========================

If you are hosting mutiple domains with virtualHost directive,
add following lines in httpd.conf to access openwebmail login screen for each domain.
ex) http://domain.com/webmail

# Open Webmail ScriptAlias, Alias
ScriptAlias /webmail "/var/www/cgi-bin/openwebmail/openwebmail.pl"
Alias /data "/var/www/data"

Don't forget to restart httpd.

========================================================================

========================================================================

========================================================================

========================================================================

Open WebMail Frequently Asked Questions

0. SPECIAL NOTE FOR SPEEDYCGI
1. INSTALLATION & STARTUP PROBLEMS
2. LOGIN PROBLEMS
3. RUNTIME ERRORS
4. CONFIGURATION OPTIONS
5. CHANGE PASSWORD
6. READ MESSAGE
7. COMPOSE MESSAGE
8. MAIL FILTERING
9. VIRUSCHECK/SPAMCHECK
10. SEND MESSAGE
11. AUTOREPLY
12. SPELLCHECK
13. ADDRESSBOOK
14. CALENDAR
15. SSL RELATED
16. MISC PROBLEMS
17. SPEED TUNING
18. SOME CONCEPT
19. HOW CAN I...

========================================================================
SPECIAL NOTE FOR SPEEDYCGI
========================================================================

We highly recommend using SpeedyCGI with Open WebMail.
Open WebMail gets almost 5x to 10x speedup when running with SpeedyCGI.

Please refer to section "PERSISTENT RUNNING through SpeedyCGI" in
readme.txt for how to install SpeedyCGI on your system.

If you are using SpeedyCGI with Open WebMail
and you have modified any file other than etc/openwebmail.conf...

Don't forget to do 'touch openwebmail*.pl'
so SpeedyCGI knows to reload the scripts to see your modification.

========================================================================
INSTALLATION & STARTUP PROBLEMS
========================================================================

Q: I got "SCRIPT_DIR not set in /etc/openwebmail_path.conf !" error?
A: On systems not passing perl script name as $0, openwebmail relies
on /etc/openwebmail_path.conf to know the directory it locates.

Please put 'the path of your openwebmail cgi directory' in the first
line of file /etc/openwebmail_path.conf.

For example, if the script is located at

/usr/local/apache/share/cgi-bin/openwebmail/openwebmail.pl,

then the content of /etc/openwebmail_path.conf should be:

/usr/local/apache/share/cgi-bin/openwebmail

Q: I got the script content instead of the openwebmail login screen?
I got "You don't have permission to access openwebmail.pl on this
server" error?
A: Your apache is not properly configured to execute CGI program.
Please edit the httpd.conf for your apache and modify it as follow:

<Directory /var/www/cgi-bin>
AllowOverride All
Options ExecCGI
Order allow,deny
Allow from all
</Directory>

You will notice "Order allow,deny" and "Allow from all" lines are
missing in default.

Then reload httpd.

(thanks to Thomas Chung, tchung.AT.openwebmail.org)

ps: If you are using Mandrake:
httpd config file is located at /etc/httpd/conf/commonhttpd.conf
httpd reload command is "service httpd reload"

If you are using FreeBSD:
httpd config file is located at /usr/local/etc/apache/httpd.conf
httpd reload command is "/usr/local/sbin/apachectl restart"

Q: I got "Internal server error" when running Open WebMail?
I got "can not do setuid" error?
I got "Software error: Can't locate etc/openwebmail.conf in @INC" error?
A: There are many possible answers...

1. Please check if you have installed a complete set of perl 5.005 or above.
and You have uncompressed the openwebmail-1.xx.tar.gz with proper parameter.
It should be "tar -zxvBpf openwebmail-1.xx.tar.gz"

2. Your openwebmail scripts may have wrong owner or mode.
The permission of all openwebmail*.pl should be

mode=4555
owner=root
group=mail

3. The suid support of your perl may be not correctly enabled.

a. su to a regular user, then run openwebmail.pl form command line.
b. if it shows 'Can't do setuid', su to root,
have suidperl owner=root, node=4555, then try step a again
c. if it shows the following WARNING, su to root,
have suidperl owner=root, mode=555, then try step a again

YOU HAVEN'T DISABLED SET-ID SCRIPTS IN THE KERNEL YET!
FIX YOUR KERNEL, OR PUT A C WRAPPER AROUND THIS SCRIPT!

d. if it shows a long html text content, which means the suid
support of your suidperl is enabled.
e. if step b or c doesn't help, please goto step 4

ps: If you are using Suse Linux 9.0 Professional, please note that the
permissions of suidperl is changed at each time SuSEconfig is run.
To avoid having to change these permissions manually each time,
please modify /etc/permissions.easy (or what permissions file used ever)
to set the proper permissions.
(thanks to dialsc.AT.t-online.de, Schaefer, Dirk Alexander)

4. if executing openwebmail.pl with regular user always complains
'Can't do suid' or 'YOU HAVEN'T DISABLE SET-ID SCRIPTS IN THE KERNEL..'
then your perl executable was compiled without SUID support

Here are the steps to recompile your perl with suid enabled:

a. grab the perl source tar ball
b. sh Configure -de (de means default perl config)
c. edit config.sh and set this :
d_dosuid='define'
d_suidsafe='undef'

ps: If you run './Configure' to configure the perl interactively,
then don't forget to answer 'yes' for question
"Do you want to do setuid/setgid emulation? "
Or you won't be able to execute openwebmail

d. then make, make install (make suidperl if needed)
e. if you have compiled suidperl, then chmod 4555 suidperl
if you don't have suidperl, change #!/usr/bin/suidperl to
the path of your perl
(thanks to Nemo Kaiser, nemoo.AT.users.sourceforge.net)

ps: If you are using FreeBSD and your perl is compiled from port,
then please note that the SUID support is disabled by default
since the port for perl 5.8.1

You need to do 'make -DENABLE_SUIDPERL' in making port

ps: If you don't want to recompile perl, you choose to may use
misc/tools/suidwrap.pl to generate C wrappers for all suid scripts.

However, this is not recommended at all, as you will not be able
to use SpeedyCGI with the openwebmail system.

Here are the steps:
1. cd cgi-bin/openwebmail
2. perl misc/tool/wrapsuid/wrapsuid.pl /fullpath/cgi-bin/openwebmail
3. change #!/usr/bin/suidperl to the path of your perl

All suid scripts will be renamed to .scriptname.pl and
the C wrapper will be generated and named as script.pl
(thanks to Chris Heegard, heegard.AT.NativeI.com)

The spellcheck may not work on Solaris when using C wrappers.
(thanks to Isam Ishaq, isam.AT.planet.edu)

5. If you are using SpeedyCGI, and openwebmail always shows Internal error,
then your SpeedyCGI may be compiled without SUID support.
a. please be sure the speedycgi executable is owned by root with
permission 4555
b. please be sure you are using SpeedyCGI 2.22 or above
c. please be sure your perl is compiled with SUID support enabled
before compiling SpeedyCGI
d. please refer to section "PERSISTENT RUNNING through SpeedyCGI"
in readme.txt for how to compile SpeedyCGI.

6. If you are using SpeedyCGI, openwebmail seems be okay at the beginning,
but it shows "Internal Server Error" sometimes ...

Please check the apache log to see if there is error messages like

"unable to open tmp file ..."

If yes, you system may not have the savedsuid support,
please set have_savedsuid_support to 'no' in etc/suid.conf

7. Some perl modules may be too old or not exist on your system
a. install MIME-Base64-3.01.tar.gz or above
b. install CGI.pm-3.05.tar.gz or above
c. install the libnet-1.19.tar.gz or above

ps: In most cases, you can run the './openwebmail.pl' in text terminal
to get more information about the error.

Q: I got "Can't check filesystem of script ./openwebmail.pl for nosuid"?
A: Your openwebmail may be installed on a filesystem mounted nosuid.
Please remove the nosuid parameter from /etc/fstab or install openwebmail
to other filesystem.

ps: 'man mount' for more information about nosuid

Q: I got "Please execute '.../cgi-bin/openwebmail-tool.pl --init' on
server first!"?
A: This is to init the mapping tables used by openwebmail, you need to

telnet to your server
su root
cd the_cgi_bin_dir_for_openwebmail
./openwebmail-tool.pl --init

Q: I got "Please execute script openwebmail-tool.pl with full path!"
in executing 'openwebmail-tool.pl --init' with full path?
A: This may happens on platforms that run suid scripts through /dev/fd/.
Please run the script from where it is located.

cd the_dir_of_your_openwebmail_cgi
./openwebmail-tool.pl --init

Q: I got "Please change /openwebmail_scripts_dir/etc/dbm.conf from xxx to yyy"
in executing 'openwebmail-tool.pl --init' ?
A: You may has wrong settings in your etc/dbm.conf.
Please modify the etc/dbm.conf as openwebmail suggested
and don't forget to redo 'openwebmail-tool.pl --init' again.

Q: --init complains the dbm options after I upgrade OS?
--init complains the dbm options after I upgrade perl?
--init complains the dbm options when I copy openwebmail.conf to another
machine?
A: The perl system may use different dbm format depending on what packages
have been installed in your server. These dbm format may be not compatible.
To know what dbm packages are used by your perl, please execute:

perl misc/test/dbmtest.pl

And you will see output like below:

------------------------------------------------------------------
You perl uses the following packages for dbm::

AnyDBM_File.pm /usr/libdata/perl/5.00503/AnyDBM_File.pm
NDBM_File.pm /usr/libdata/perl/5.00503/mach/NDBM_File.pm

The dbm options in dbm.conf should be set as follows:

dbm_ext .db
dbmopen_ext none
dbmopen_haslock no
----------------------------------------------------------------------

AnyDBM_File.pm is a "pure virtual base class", it has nothing of its own.
It's just there to inherit from one of the various DBM packages in the
following order: NDBM_File, DB_File, GDBM_File, SDBM_File, ODBM_File
(you may type 'perldoc AnyDBM_File' to see comparison of these packages)

In the above example, the system uses NBDM package for dbm.
when you upgrade OS, perl or migrate openwebmail to other machine,
you should run dbmtest.pl on both system to ensure that they use same
underlying dbm package.

Q: ok, my two machines use different DBM systems, what can I do next?
A: you can enforce the new one to use the same dbm package as the old one by
putting the 'use XXX_File.pm' after the 'use strict;' in all openwebmail*pl.
then try to run 'openwebmail-tool.pl --test' to see if the XXX_File.pm is
really used.

where XXX_File.pm is the value you get by running dbmtest.pl on old machine.

Q: When I installed Open WebMail on Fedora 3, --init generated no output?
A: Please turn the selinux feature off by
setting "SELINUX=disabled" in /etc/selinux/config,
then try to execute openwebmail-tool.pl --init again.

========================================================================
LOGIN PROBLEMS
========================================================================

Q: The login menu showed okay, but I always got login failure?
A: Check auth_module option in openwebmail.conf:

If it is 'auth_unix.pl',
check if passwdfile_encrypted and passwdmkdb in auth_unix.conf are correct

If it is 'auth_pam.pl',
make sure you have followed the instructions of 'PAM SUPPORT' in readme.txt.

If you still got login failure, you can debug the pam module by:
1. modify auth_pam.pl
uncomment all the lines of main::log_time(...)
2. login to openwebmail
3. check the /tmp/openwebmail.debug for more information.

ps: If you are running openwebmail under SpeedyCGI, don't forget to do a
'touch openwebmail*pl' after you complete the modification to
auth module or auth conf file.

Q: It took a long time in the first login?
A: Openwebmail has to initialize some mapping tables for future use,
it creates these tables in the first successful login, this guarantees
that openwebmail creates files only if it is correctly installed.

ps: This automatic table initialization has been removed since openwebmail-1.80.
The sysadm have to initialize the db by himself explicitly with the command

'./openwebmail-tool.pl --init'

Q: It took a long time in every login?
Q: Openwebmail hangs at every login after I saved the preference in the first
time?
A: You probably have wrong settings in the dbm.conf,
please execute 'perl misc/test/dbmtest.pl' to find correct settings.

Q: Some of my users login okay, but others don't, why?
A: It is possible that you are upgrading from version prior to 1.41
to the newer version. The virtual user support is totally reimplemented.
It uses virtusertable instead of genericstable for user mapping now.
Please refer to
http://www.sendmail.org/virtual-hosting.html to know how to translate
entries in genericstable to virtusertable.

Q: Some of my user with invalid shell couldn't login since upgrade to 1.80?
A: A new variable check_shell option has been added to the auth_unix.conf
If it is set to yes, which means only users with valid shell can login.
If it is set to no, then openwebmail won't do valid shell checking.

Q: A string 'Sessions : 5, 10, 20' appeared at the bottom of the copyright
page after successful login, what does this string mean?
A: It means the number of users that were active in the last 1, 5 and 15
minutes, which gives a rough estimation of the webmail usage state.

Q: How does autologin work? Will my password be stored somewhere?
A: Whenever you have successfully logined openwebmail,
openwebmail will store your loginanme/logindomain as cookies in your browser.
If you didn't logout the session, then openwebmail will bring you into
main screen at your next login if the session is still not timeouted.

Openwebmail does this by checking if you have a valid session file on server,
so your password is not required or stored in either server or client side.

Q: Is it safe to use autologin feature?
A: It depends. You can enable it on your private computer if the computer is secure.
And if you are using a public computer, please don't enable autologin,
or be sure to do a logout before leaving that public computer.

Q: I have enabled autologin on some public computer and forget to logout,
what can I do to prevent others to autologin my account?
A: 1. go to that computer and do logout explicitly :)
2. If 1 is not possible, then you may login openwebmail, switch to webdisk,
turn on the checkbox of ShowHidden at the up-right corner,
then chdir to subdir .openwebmail, and remove the autologin.check.db
ps: this will remove all old remembered autologin sessions.
3. If you don't do anything, the old session will be finally timeouted anyway.

Q: Can I limit the use of autologin feature?
A: Yes, option allowed_autologinip can be used to control which subnets are
allowed to use the autologin, or even disable it at all.
Please refer to openwbemail.conf.help for more detail.

========================================================================
RUNTIME ERRORS
========================================================================

Q: I got "Couldn't open XXX-session-0.370606494136155!" error after login?
A: You openwebmail-1.xx.tar.gz was uncompressed with improper parameter.
It should be "tar -zxvBpf openwebmail-1.xx.tar.gz"
Or you can refer to the file permission list in the end of readme.txt
ps: you may check the permission cgi-bin/openwebmail/etc/sessions first,
it should be owner=root, group=mail, mode=771

Q: I got "Software error: Can't locate MIME/Base64.pm in @INC"?
A: Please install the MIME-Base64-3.01.tar.gz.

Q: I got "Too many arguments for MIME::QuotedPrint::encode_qp"?
A: Your MIME module is too old, please install the MIME-Base64-3.01.tar.gz.

Q: I got "Software error: Can't locate Text/Iconv.pm in @INC"?
A: Please install the Text-Iconv-1.2.tar.gz, this is required since
openwebmail-1.80

Q: First login was okay and openwebmail told me to setup preference,
then I got "Internal Server Error" ?
A: You may forget to install Text-Iconv-1.2.tar.gz,
or you may compile Text-Iconv with wrong parameter in Makefile.PL.
Please check readme.txt with keyword Text-Iconv to see
if any special modification is required for your platform

Q: First login was okay and I can setup preference without problem,
then I got "Couldn't get write lock on INBOX!" immediately ?
A: You may have wrong setting for option mailspooldir in openwebmail.conf

Q: I got "Use of uninitialized value in subroutine entry at /xxx/DB_File.pm
line yyy" error ?
A: The line you got error should be inside the sub routine tie_hash_or_array.
Please find the following comment line in DB_File.pm:

# make recno in Berkeley DB version 2 work like recno in version 1

And add the following line just before the above line:

$arg[3] = 0666 unless defined $arg[3] ;

(thanks to Paul Marquess, Paul.Marquess.AT.btinternet.com
and mainely_linux.AT.users.sourceforge.net)

Q: I got "can't open /var/log/openwebmail.log" error?
A: Please check the openwebmail.log permission, it should be
owner=root, group=mail, mode=660

ps: If you get this error periodicly and your are using Mandrake Linux,
You may have to move the logfile somewhere else.
The Mandrake's (8.2 and 9.0) security system periodically scans the
/var/log directory and changes ownerships/permissions.
(thanks to Karl Schricker, karl_schricker.AT.gmx.net)

Q: I got "Software error: ndbm store returned -1, errno XX, ..."?
A: The meaning of errno XX could be found in errno.h

If your OS is FreeBSD, please check /usr/include/sys/errno.h
If your OS is Linux, please check /usr/include/asm/errno.h
If your OS is Solaris, please check /usr/include/sys/errno.h

Most of the time, the error is due to exceeded user quota.
Please remove unwanted files or increase the quota for user.

ps: Since openwebmail 20031128, you may set the option
use_syshomedir_for_dotdir to no to have openwebmail put index db
in ow_usersdir instead of user homedir, thus creating db won't be
limited by user quota.

Q: My SENT folder shows -1 or other negative message size rather then
regular message size?
A: This problem occurs if you installed Open WebMail on the same partition
where quota is enabled. Open WebMail uses temp files in
cgi-bin/openwebmail/etc/sessions folders.
Solution is to move sessions folder to another partition with no Quota.

Please read RedHat-README.txt for detailed explanation on setting up
this, since this problem mostly occurs on RedHat Linux 6.2 and bellow.
(thanks to Emir Litric, elitric.AT.yahoo.com)

Q: I got "db warning - msg xxx index missing in INBOX" in log?
What does this mean?
A: It may have two possible meanings.

1. Your message is moved to other folder by the openwebmail filter module

While openwebmail always maintains the index consistent with the folder
content, openwebmail only calls the mailfilter in the following two
condition:
a. before browsing the message list of a folder
b. before reading a message of the INBOX

If a message(aaa) matching the filter rule comes to INBOX folder, this
message will become the neighbor of one of the existing messages(bbb)
in the index db. If the user is reading message bbb, then aaa will
become the target linked by the right or left arrows in the bottom of
the readmessage webpage. Now if user clicks the arrow for next page,
you will get the db index missing error since the message(aaa) is
moved to other folder by the filter before being accessed..

2. Your message is removed by other pop3/imap client.
Do you use outlook and openwebmail at the same time?

Q: I got "db warning - msg yyy index inconsistence in INBOX" in the log?
Does it mean my message were lost?
A: No, you message were not lost, it just means the index db was not
reflecting the newest state of your mail folder, openwebmail did the
reindex automatically after logging this message.

Q: I got "Your request didn't contain the proper session ID cookie --
access denied!" error?
A: Please enable the cookie function of your browser.
Or you can set the option session_checkcookie to 'no' to disable
the check of cookie in openwebmail, but this may put the user
session in danger that it could be hijacked by others.

Q: I got "Your request didn't come from the same ip of this session --
access denied!" error?
A: The client may access the webmail server through a gateway which may
dynamicly change it IP address, please set the option
session_checksameip to 'no' to disable the IP check.

Q: My openwebmail was okay, but I got "Your request didn't contain the
proper session ID cookie -- access denied!" in these days?
A: Openwebmail puts user uploaded attachments in
cgi-bin/openwebmail/etc/sessions/ temporarily.
User will get error if there is no space left on the partition where
cgi-bin/openwebmail/etc/sessions/ lives or user has exceeded his disk quota.

Please move cgi-bin/openwebmail/etc/sessions to a larger partition with
diskquota disabled, then create a symbolic link to that new directory

cd /new_place

mkdir sessions
chmod 771 sessions
chown 0 sessions
chgrp mail sessions

cd yourweb_cgi-bin/openwebmail/etc/
rm -Rf sessions
ln -s /new_place/sessions .

Q: I got 'Couldn't get read lock on ....' error?
'Couldn't get write lock on ....' error?
A: If the error message appears immediately after you submit the CGI request,
then it may be due to the user doesn't has enough privilege to lock the
file or the directory for the file even doesn't exist.

If the error message appears after the cgi request submission for more
than 30 seconds, then the folder openwebmail want to access may be locked
by other process.

Most of the time, it is due to the concurrent accesses to the folder by
other mail client through the pop3/imap daemons.
This is okay, just back to previous page and try again later.

To know where the error happened exactly, you may try to set option
error_with_debuginfo to yes in openwebmail.conf. This would give you
more detailed information in case openwebmailerror() happens.

If you are running openwebmail in persistent mode,
there could be openwebmail processes locking the folder file for indexing.
To release the lock, you may kill the openwebmail speedy_backend process.

Since openwebmail 20041129, you may use 'openwebmail-tool.pl -u username'
to find the processes holding the filelocks, and kill the processes after
confirmation.
If the locks couldn't be released after killing the related processes,
you may solve the problem in a quick and dirty way...

rename the file, copy it to original name, then remove the renamed one.
This would have the file a new inode and thus release all old locks.

ps: The 'openwebmail-tool.pl -u requires the lsof package.
it is available at http://freshmeat.net/projects/lsof/

ps: Killing the openwebmail process may leave an incomplete index db
on disk. It is okay, the folder index db will be fixed or rebuild
in the next access.

========================================================================
CONFIGURATION OPTIONS
========================================================================

Q: The 'From' field of my message contained only 'username@'?
A: You may has wrong setting for option domainnames in openwebmail.conf
please list all domainnames separated with comma, or
use auto for this setting, openwebmail will use the hostname in the url
or call '/bin/hostname' to get the FQDN (fully qualified domain name)
of your host.

Q: The domainname detected by openwebmail is not what I want,
how can I specified the outgoing mail domain for all my users?
A: Please set the domainnames option in openwebmail.conf from 'auto' to
the domainname you want. Multiple domainnames can be specified only
if separated by comma

Q: How can I use LDAP to authenticate user in openwebmail?
A: You have 2 ways to do this:
1. use the auth_ldap.pl written by Ivan Cerrato, pengus.AT.libero.it
2. use auth_pam module and let pam to talk with ldap server.

Below is an article posted at sourceforge by ispman.AT.user.sourceforge.net
(http://sourceforge.net/forum/message.php?msg_id=1462314)

---------------- begin ----------------
I hope this is useful to someone:

I was able to get openwebmail to authenticate using ldap/pam on a system
with Redhat 7.1, pam_ldap135, and OpenLDAP 2.0.18.

In openwebmail.conf ~

auth_module auth_pam.pl

In auth_pam.conf ~

servicenameopenwebmail
passwdfile_plaintext/etc/passwd

vi /etc/pam.d/openwebmail:

#%PAM-1.0
auth required /lib/security/pam_unix.so
auth sufficient /lib/security/pam_ldap.so
account required /lib/security/pam_unix.so
account sufficient /lib/security/pam_ldap.so

That's it. LDAP users will authenticate with the pam_ldap module and
system users with pam_unix.
---------------- end ----------------

Q: How can I use multiple virtual domains with openwebmail?
A: First, you have to decide whether to use real virtual hosting or
just user alias.

1. The User Alias

User alias is much simpler, your system is actually a one domain machine.
You only have to define the user alias in virtusertable.

For example, you have 1 real domain server.com and
2 virtual domain virtual_1.com, virtual_2.com
for your server.

You already have tom and john on this server.
And now you want 2 more tom and john for each virtual domain.

Define the following entries in your virtusertable will make it.

tom@virtual_1.comtom1
tom@virtual_2.comtom2
john@virtual_1.comjohn1
john@virtual_2.comjohn2

And how these users are used?

If the user logins as tom and the webmail url is http://virtual_1.com/....
then alias tom@virtual_1.com will be matched, real user tom1 will be used.
If the user logins as tom and the webmail url is http://virtual_2.com/....
then alias tom@virtual_2.com will be matched, real user tom2 will be used.

If the user logins as tom and the webmail url is http://server.com/....
then real user tom will be authenticated.

If the user logins as tom@virtual_1.com, then no matter what the url is,
the alias tom@virtual_1.com will be matched, user tom1 will be used.

In the user alias mapping, users of different virtualdomains are actually
mapped to the real domain and then passed to same authentication module.

2. Real Virtual Hosting

The real virtual hosting means your system is configured to a multiple
domain machine in either smtpd, pop3d, webmail and authentication module.

You will need to use the per domain config file in openwebmail for each
of your virtual domain. These config files will be loaded based on

1. the domainname part in loginname, or
2. the hostname in the url of the webmail

ps: You may need to use the domainname_equiv option to ensure no matter
which domainname is used by user or in URL, they will be mapped to
a consistent one.

For example:

If the user login as tom and the webmail url is http://virtual_1.com/...,
config file for virtual_1.com will be loaded
If the user login as tom and the webmail url is http://virtual_2.com/...,
config file for virtual_2.com will be loaded
If the user logins as tom@virtual_1.com, then no matter what the url is,
config file for virtual_1.com will be loaded

Each domain can have its own set of options in its config file,
including domainname, authentication module, quota limit, mailspooldir ...

A more detailed example is described in the Kevin Ellis's webpage:
"How to setup virtual users on Open WebMail using Postfix & vm-pop3d"
http://www.bluelavalamp.net/owmvirtual/

Q: Could I have configuration file on per user basis?
A: Yes, let us use tom@virtual_1.com as example.

If option auth_withdomain is set to yes,
the user conf is cgi-bin/openwebmail/etc/users.conf/virtual_1.com/tom

If option auth_withdomain is set to no,
the user conf is cgi-bin/openwebmail/etc/users.conf/tom

Q: The default mail domain for my user is always wrong, how can I set it?
A: To have openwebmail find the correct mail domain for the user,
you'd give it some hint.

For example, if the webmail url is

http://mail.server_1.com/cgi-bin/.....,

and you want the email for tom to be tom@virtual_1.com.

You can achieve this in either the following 2 ways:

1. create per user config file etc/users.conf/tom
and set option domainnames to virtual_1.com
2. create per domain config file etc/sites.cof/mail1.server_1.com
and set option domainnames to virtual_1.com

While 1 is only for the user tom, the method 2 has effect for all users
who logins with the url http://mail.server_1.com/cgi-bin/....

Q: I want to change not only the domainname part but also the username part
of the default email address?
A: You can use the virtusertable or the per user config file

1. virtusertable:
One or more email address can be defined in virtusertable for same user,
all those email addresses will be used as the default email address for
that user
2. per user config file:
You can set the default_fromemails option in the per user config file.
Multiple default email addresses can be specified only if you separate
them with comma.

ps: While virtusertable is convenient in setting default email addresses
for many users, per user config file let sysadm control many properties
for a specific user.

Q: How can I disallow the user to set their from email address or realname?
A: set option enable_loadfrombook to 'no'
in either openwebmail.conf or per user config.

Q: How can I allow user to change their realname
but disallow the user to set their from email address?
A: set option enable_loadfrombook to 'yes' and
set option frombook_for_realname_only to 'yes'
in either openwebmail.conf or per user config.

Q: Can I install openwebmail without iconv() support?
A: Yes, you may copy the misc/patches/iconv.pl.fake over the shares/iconv.pl,
which doesn't use iconv() at all but still support charset conversion for
Chinese and Japanese.

Q: Can I setup mail account for user without creating the unix account?
A: Yes, you need postfix + vm-pop3d + openwebmail.
Kevin Ellis(kevin.AT.bluelavalamp.net) has made a webpage for this,
it is available at http://www.bluelavalamp.net/owmvirtual/

Q: I have set openwebmail for virtual user with vm-pop3d, but I got
"Sorry, root login is disabled for security's sake" at login?
A: Please check the descriptions in auth_vdomain.pl/auth_pop3.pl and
find which case you are using. If you are using case b, don't forget
to set the $local_uid to the uid used by your vm-pop3d for all virtual
users.
ps: We suggest you use the auth_vdomain.pl for system running vm-pop3d+postfix
Please refer to descriptions in auth_vdomain.pl for more detail.

========================================================================
CHANGE PASSWORD
========================================================================

Q: The login is okay, but I can't change by my password with openwebmail?
A: There are 2 possible answers for this:

1. Your passwdfile is not local accessible.

If you use auth_unix.pl for authentication
and your passwdfile_encrypted file is not a local accessible
(ex: examples in auth_unix.pl that are terminated with |),
the changepassword feature won't be available.

If your system uses NIS, then you may try auth_nis.pl instead,
or you have to use auth_pam.pl to get the changepassword to work.

2. Your system doesn't support saved set-user-ID, so openwebmail won't get
enough privilege to change the passwd file.
Try to set option has_savedsuid_support to 'no' in etc/suid.conf
to solve this problem.

3. The authentication module which you used doesn't support password
changing, ex: auth_pop3.pl

Q: I use openwebmail with NIS/YP system, the user can login but can not
change their password?
A: The NIS/YP password can not be changed with auth_unix.pl,
you need to use the auth_nis.pl or auth_pam.pl as the authentication module.

========================================================================
READ MESSAGE
========================================================================

Q: Everything seems be fine at the beginning, but if I tried to open a
message after a period of time, the content of other message was showed
instead of the one I clicked?
A: This is due to a bug of tell() in perl 5.8. And RedHat 8.0 bundles Perl
5.8 by default. Please upgrade your openwebmail to 1.81 or higher.
And you should try to find a bug fix for your perl since other applications
written by perl may operate improperly due to this bug

Q: Some mails were not displayed right....
A: please check
http://openwebmail.org/openwebmail/download/doc/changes.txt
to see if any update fixes your problem and download the
openwebmail-current.tar.gz

Q: I got some messages that have attachment with filename "Unknown.tnef"
and contenttype "application/ms-tnef",
how can I extract files from this attachment?
A: Solution 1:

You need to install tnef viewer in the user computer,
the viewer is available at http://www.ericphelps.com/tnef/

Solution 2:

You have to install the tnef extractor on the openwebmail server,
it is available at http://sourceforge.net/projects/tnef/.

To extract the files inside a tnef attachment, the user can save the
attachment into openwebmail webdisk, than extract files through webdisk
interface.

ps: Open WebMail has supported tnef extraction since 2.32 20040719,
you may see the files encapsulated in tnef attachment directly
without extract them in webdisk by yourself

========================================================================
COMPOSE MESSAGE
========================================================================

Q: I could not add attachments?
Open WebMail was hanged when I pressed the 'add' button to add attachments?
A: 1. Your CGI or MIME-Base64 module may be too old,
Please download CGI.pm-3.05.tar.gz and MIME-Base64-3.01.tar.gz in
http://openwebmail.org/openwebmail/download/packages/
and install them to your system.
2. Your proxy may limit the size of a POST request.
Try to add attachments with no proxy setting in your browser.
If you are the administrator of the squid proxy server,
please set the request_body_max_size option to a larger value.

Q: Attachments disappeared when I forwarded a message?
A: Check permission of the following directories
cgi-bin/openwebmail/etc - owner=root, group=mail, mode=755
cgi-bin/openwebmail/etc/sessions - owner=root, group=mail, mode=771
cgi-bin/openwebmail/etc/users - owner=root, group=mail, mode=771

Q: The permission of cgi-bin/openwebmail/etc is correct but attachments
still disappeared in message forwarding?
A: Hmmm, please upgrade to the latest version.
Some very old version(1.03,1.04) has little problem in attachment handling.

Q: I can not choose to compose HTML messages?
A: The HTML editor requires
1. IE5.5+ on windows platform, or
2. Mozilla 1.3b+ on all platforms

Q: Is it possible to use openwebmail with browser other than IE5.5+
and Mozilla 1.3b+, e.g.: Opera or old Netscape?
A: If you are using windows platform, then you may install neadroid
Neptune plug-in, which will add support for IE DHTML to your browser.
The URL is http://www.meadroid.com/neptune/download/index.htm

Some discussion of this plug-in is available at
http://www.interactivetools.com/forum/gforum.cgi?post=14116;sb=post_latest_reply;so=ASC;forum_view=forum_view_collapsed

Q: The InserImage, InsertTable popup window don't show with correct charset?
A: This mostly happens with apache web server 2.0 or later.
Please edit your Apache Configuration file, replace

AddDefaultCharset ISO-8859-1

with

AddDefaultCharset off

Q: The InserImage, InsertTable popup window still show with correct charset
after I set AddDefaultCharset to off?
A: This is due to the web page cache of your browser.
Please clean the cache of your browser and try again.

========================================================================
MAIL FILTERING
========================================================================

Q: Some of my messages were moved to trash/virus/spam folder automatically?
A: Your messages were either filtered by 'global filter',
'per user filter' or 'smart filters'.

Global filter are rules defined in the file global_filterbook
(global_filterbook is defined as %ow_etcdir%/global_filterbook in
openwebmail.conf). By default, we will put rules that filters
know spammer or virus attachments in the global filter file.

Per user filter are filter rules defined by users themselves.

Smart filters includes repeatness filter, bad format from filter,
faked smtp filter, faked from filter and faked exe contenttype filter.

The 'repeatness filter' will filter messages with same from and subject for
more than certain times, those messages are often from spammers or virus.

The 'bad format from filter' will filter messages that have bad-format from
email address. A from email address is in bad format if
1. it is started with digits
2. it contains both digits and dot
3. it contains characters other than alphabets, digits, dot, dash,
underline.

The 'faked smtp filter' will filter messages that have a faked smtp
source, those messages are often from spammers.

The 'faked from filter' will filter messages whose From: field is different
than the email address in the SMTP envelope address, those messages are
often generated from virus.

The 'faked exe contenttype filter' will filter messages that have
executable attachment with faked contenttype, eg: audio, midi...
These messages are often generated by viruses, the browser will download
the attachment because its contenttype is audio and then execute the
downloaded file because it file extension is exe/com/bat/scr/pif/lnk.

The three faked xxx filters are default disabled and the default can be
changed in openwebmail.conf. The user can also enable/disable it in
the user preference.

Q: What are "messages with faked smtp"?
A: In short, they are messages coming from mail servers that fake their
name from other machines.

Where is a message coming from?

A message sent from machine A to machine B may have 2 cases:
a. A ---> M1 ---> M2 ---> B (M1, M2 are mail servers)
In this case, openwebmail use M1 as the from server.
Since most of the time, A is windows machine using outlook.
b A -------------------> B
In this case, openwebmail use A as the from server.

How do we know if a from server fakes his name?

Each host may have 3 names in the mail header:
$byas - name used by this server when saying hello to incoming connection
$relay - name used by this server when relaying mail through other host
$connectfrom - ip and name detected by other hosts resolved from DNS system
when receiving connection from this server

A from host is faking his name if
a. $byas doesn't equal to $relay, and
b. $connectfrom doesn't equal to $relay, and
c. $connectfrom has different domain than the destitution server B, and
d. $connectfrom is not private IP

Q: I still want the filtered messages, how can I disable faked smtp filter
and faked exe contenttype filter completely?
A: 1. Set default_filter_fakedsmtp and default_filter_fakedexecontenttype
to 'no' in openwebmail.conf. This will turn off the two filter for
all newly created user
2. Uncheck the faked smtp filter and faked exe contenttype filter option
in user preference. This will disable the two filters for a specific
user
3. you may set 'enable_smartfilter' to 'no' in openwebmail.conf

Q: How can I disable the global filters?
How can I disable the per user filters?
How can I disable the smart filters?
A: You may set options like enable_globalfilter, enable_userfilter,
enable_smartfilter to 'no' in openwebmail.conf.help

Q: How can I know which filter rule move my messages?
How to debug the mailfilter message movement?
A: An option debug_mailfilter is available since openwebmail20050201,
please set it to yes in openwebmail.conf, and you will see message
movement detail in logfile

Q: Some of my messages disappeared?
A: Your messages may be removed by the delmail_ifquota feature.

Q: How does the delmail_ifquotahit option work?
Which message will be removed first?
A: It will clean trash and draft first,
then remove oldest messages in other folders.
The removal will stop if the quota size is download to the 90% of user
quota limit.
ps: The messages in INBOX and user defined folders will be removed only if
these folders occupy the majority of the mailfolder space.

Please refer to routine cutfolders in ow-shared.pl for detail

Q: There were strange characters in the mail filter menu and those rules
could not be deleted?
A: This is due to the dbmopen() of your perl didn't add the ".db" extension
automatically, so the ~/.filter.book and its index were written to the same
file. This problem can be fixed by properly setting dbm options.

perl cgi-bin/openwebmail/misc/test/dbmtest.pl [enter]

and you will get output like this:

dbm_ext .db
dbmopen_ext none
dbmopen_haslock no

Then put the three lines into your etc/dbm.conf.

========================================================================
SPAMCHECK/VIRUSCHECK
========================================================================

Q: Why do I need spamcheck/viruscheck in openwebmail?
Isn't it better to do these checks in MTA or mail deliver?
A: You may need spamcheck/viruscheck in openwebmail for two reasons:
1. filter mechanism in MTA or mail deliver won't check messages that
are fetched from remote pop3 servers
2. Spam filters in MTA won't do personalized filtering.

ps: While Spam filters in local deliver can do personalized filtering,
it won't check outgoing messages.
So we suggest install the Spam and Virus filter in MTA level,
(so both incoming and outgoing will be checked for spam and virus)
then enable the spamcheck for all messages in openwebmail
(so user can train the spam filter according to his own preference)
and enable viruscheck for pop3 messages in openwebmail
(so user won't get infected messages from remote pop3 servers)

Q: What is the difference between pop3 and all when setting option
viruscheck_source and spamcheck_source?
A: If check source is set to pop3, pop3 messages are checked after fetching
and the result is append as X-OWM-... in message header.

If check source is set to all, pop3 messages are checked after fetching,
and the result is append as X-OWM-... in message header.

For messages without the X-OWM-... headers, which means they are not
fetched from pop3 servers, and they will be checked when user want
to browse the message list of the INBOX folder.

Q: What is the order of the processing of viruscheck, spamcheck, global filter,
perl user filter and smart filter?
A: viruscheck -> filter rules (including global and user filter rules) -> spamcheck -> smart filters

Q: The spamcheck is very slow, even there are only few messages in INBOX?
A: Please be sure you have start the spamd with --local option

Q: The spamcheck is still slow even with --local option?
A: Your server may be not fast enough to do the viruschecking or spamchecking
for all messages, please change the viruscheck_source_allowed and
spamcheck_source_allowed to pop3, and try to add viruscheck/spamcheck
to your mail system in MTA level or mail deliver.

Q: My spamcheck/viruscheck/learnspam doesn't work?
I see spamcheck/viruscheck/learnspam error in openwebmail.log?
A: Please be sure your system has installed the spamassassin and clamav,
then test spamc, sa-lean, clamdscan with the argument defined in pipecmd
in openwebmail.conf.
ps:You should do the test in both root and non-root account.

Q: I have disabled spamcheck/viruscheck feature,
but the Virus and Spam folder exist in my folder list?
A: you have to set option has_virusfolder_by_default and
has_spamfolder_by_default to 'no'

Q: I have set option has_virusfolder_by_default and has_spamfolder_by_default
to 'no', the Virus and Spam folders still exist.
A: When the two options are set to 'no', it only means openwebmail doesn't
treat them as default folders. (In other words, openwebmail won't creat
them automatically if they doesn't exist)
However, openwebmail will still list them if they already exist in
~user/mail/ after you change the options to 'no', so you may have to remove
the ~user/mail/spam-mail and ~user/mail/virus-mail manually.

========================================================================
SEND MESSAGE
========================================================================

Q: Most functions work fine, but I could not send message.
I got "Can't locate Net/SMTP.pm in @INC ..." error?
I got "Internal server error"?
A: Please install the libnet-1.19.tar.gz, this is required since
openwebmail 1.60.

Q: I am sure the sendmail was running up on my mail server, but I got
"Couldn't open SMTP server 127.0.0.1" error when sending messages?
A: Your sendmail may be configured to listen on the server_ip:25 only,
it didn't listen on 127.0.0.1:25
You can either

a. override the option smtpserver in openwebmail.conf and
set it to your server_ip

b. modify the sendmail.cf and find the following line

O DaemonPortOptions=Port=smtp,Addr=x.x.x.x, Name=MTA
(where x.x.x.x is the server_ip)

Please change the x.x.x.x to 0.0.0.0 to make sendmail
listen on all IPs binding on the server network interfaces.

Q: I still got the "Couldn't open SMTP server 127.0.0.1" error?
A: Please check the permission of your /etc/protocols and /etc/services,
it should be 0644. (-rw-r--r--)

Q: I got 'Sorry, there was a problem sending your message' error?
A: a. Please check if smtpserver option in openwebmail.conf points to valid
SMTP server, its default is '127.0.0.1'. If you set it to name of some
other SMTP server, please be sure the SMTP server allows mails relayed
from your host.
b. When SMTP server is set to 127.0.0.1, please be sure the hosts.allow
has the following entry

sendmail : localhost 127.0.0.1 : allow

Q: Does openwebmail support SASL authentication on SMTP?
A: Yes, but only the PLAIN type authentication is supported.
The username/password will be encoded with base64, so it is not very secure.
To enable the SASL authentication:
1. set option smtpauth to yes in openwebmail.conf
2. set the smtpauth_username, smtpauth_password in smtpauth.conf

========================================================================
AUTOREPLY
========================================================================

Q: The autoreply function doesn't work?
A: An incoming message won't be replied by vacation.pl if
1. the destinated username has entries defined in /etc/alias which causes
the mail routed to another account without calling vacation.pl
2. the destinated username doesn't not appear as an recipient in To: or Cc:
3. this message is sent by the destinated username himself

If your message is not in the above 3 cases, please be sure that
vacationinit and vacationpipe in openwebmail.conf have pointed to the
path where the vacation program is.

If the path is correct, you can do debug with the -d option

1. add the '-d' parameter to the vacationpipe in openwebmail.conf
like below

vacationpipe /usr/local/www/cgi-bin/openwebmail/vacation.pl -d -t60s

2. choose a user, enable his autoreply in openwebmail user preference
3. check the ~user/.forward file, the '-d' option should appear after
vacation.pl
4. send a message to this user to test the autoreply
5. check the /tmp/vacation.debug for possible error information

Q: When I enable autoreply feature, others get "Returned mail: see
transcript for details" instead of my autoreply message?
A: Your sendmail may be configured with Sendmail Restricted SHell or smrsh.
vacation.pl file needs to be added to smrsh.

If you are using RedHat 7.1, you may link vacation.pl to /etc/smrsh/

cd /etc/smrsh
ln -s /var/www/cgi-bin/openwebmail/vacation.pl /etc/smrsh/vacation.pl
(thanks to Emir Litric, elitric.AT.yahoo.com)

========================================================================
SPELLCHECK
========================================================================

Q: When I clicked 'spell check' button, I got "Internal Server error" in new
window?
A: 1. Please upgrade your openwebmail to 2003/11/16 or later.
2. If you are using C wrappers for suid scripts on Solaris,
please recompile you perl with suid enabled instead of using
the C wrappers.
(thanks to Isam Ishaq, isam.AT.planet.edu)
3. Please check the apache error log for more information

Q: I can use aspell for spelling check, but personal dictionary doesn't work?
A: 1. Please upgrade your openwebmail to 2003/11/16 or later.
2. If you are using aspell, please be sure your homedir is group readable.
Yes, this is strange, but it seems aspell need this.
(thanks Scott A. Mazur, scott.AT.littlefish.ca)
3. If you don't want to change the directory permission.
Please set option has_savedsuid_support to 'no' in etc/suid.conf
4. If you don't want to set option either, you may try to use ispell
instead of aspell

Q: Why is openwebmail-spell.pl a suid root program?
A: Because it needs to read the preference file, ~/.openwebmai/openwebmailrc
of different users to get their language and dictionary setting.

========================================================================
ADDRESSBOOK
========================================================================
Q: I got "Too many arguments for MIME::QuotedPrint::encode_qp"?
A: Your MIME module is too old, please install the MIME-Base64-3.01.tar.gz.

Q: The content of my global addressbook is gone after I upgrade my openwebmail?
A: No, it is still there.

The filename, location and format of openwebmail addressbook has been changes
since 2.41-20041030. While user personal addressbooks will be converted
automatically at user login, the global addressbook will be converted only if
it is specified by sysadm explicitly.

To convert the global addressbook:

cd your_cgi-bin/openwebmail
openwebmail-tool.pl -c

Q: Can I have multiple personal addressbooks?
A: Yes, each user can create as many addressbooks as he want through the
addressbooks web management menu

Q: Can I have multiple global addressbooks?
A: Yes, but this could not be done in web interface,
you have to goto directory specified by option ow_addressbooksdir
(eg: cgi-bin/openwebmail/etc/addressbooks)
then use 'touch new_addressbooks_filename' to create empty global addressbook.
Be sure the permission is right so other users can read it.

Q: Can I edit the global addressbooks?
Which user can edit global addressbooks?
A: Yes, if the option abook_globaleditable is set to yes
and the user has enough privilege to write the global addressbook file,
then he can add, delete or modify the contacts within that gobal addressbook.

========================================================================
CALENDAR
========================================================================

Q: Everything works fine, but I got timeout when clicking the calendar button?
A: Please check your apache error log if it has lines like below:

[...] openwebmail-cal.pl: Use of uninitialized value in subroutine entry
at /usr/lib/perl5/5.8.0/i386-linux-thread-multi/DB_File.pm line xxx.

If yes, please search the RUNTIME ERROR section with keyword DB_File.pm

Q: The email notification for calendar event doesn't work?
A: You need to use openwebmail-tool.pl in crontab to check the calendar
events for sending the notification emails. For example:

0 */2 * * * /usr/local/www/cgi-bin/openwebmail/openwebmail-tool.pl -a -n -q

The above line will use openwebmail-tool.pl to check the calendar
events for all users every two hours. Please note we use this
frequency because the default value of option calendar_email_notifyinterval
is 120 (minute). You have to set the crontab according to your
calendar_email_notifyinterval.

========================================================================
SSL RELATED
========================================================================

Q: Can I use openwebmail with SSL?
A: yes. just https:// instead of http:// for the URL of webmail

Q: I got "site not found" or "could not connect to the server" error?
A: Yes, openwebmail can work with SSL.
The error is due to IE doesn't do keepalives correctly when using SSL.

Please add the following line to your Apache configuration for SSL
(or VirtualHost container)

SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown
(thanks to Happy Camper, hcamper.AT.users.sourceforge.net)

Q: Can I use openwebmail with SSL on multiple virtual domains on one server?
A: Since apache only allow SSL for one virtual domain, you can have only one
https url. To use virtual domain other than the one specified in https,
you have to specify the virtual domain in URL when link to login webpage

https://sample.com/openwebmail/openwebmail.pl?logindomain=vdomain1.com
(thanks to scott.AT.littlefish.ca for his code)

========================================================================
MISC PROBLEMS
========================================================================

Q: The help tutorial doesn't show with correct charset?
A: This mostly happens with apache web server 2.0 or later.
Please edit your Apache Configuration file, replace

AddDefaultCharset ISO-8859-1

with

AddDefaultCharset off

Q: The DayLight Saving option in user preference doesn't work,
messages in folders still have wrong date in folderlist view?
A: This is due to those messages were parsed at the time that DST option
was set to wrong value, the problem could be solved by

1. set DST to auto
2. goto folder management
3. choose 'recreate index' for your folders.

ps: This could be quite time-consuming if you have large folder,
you may do it with openwebmail-tools.pl in background.

Q: Is the 'filename search' in webdisk case sensitive or case insensitive?
A: If the 'find' command in your unix supports -iname, the search will be
case insensitive. Or it will be case sensitive.

Q: Why the 'content search' in webdisk searches files in current directory
only?
A: The file content search is done with the unix command 'grep'.
If the 'grep' in your unix supports -r, the search will search current
directory and all its sub directories recursively. Or it will search files
in current directory only.

Q: The ssh terminal in openwebmail supports SSH1 only?
A: Yes. The ssh terminal support in openwebmail is actually done with the
MindTerm package from www.appgate.com. The bundled MindTerm is 1.21,
which is the latest GPLed release but quite old.

You may install MindTerm version 2.3.1 from www.appgate.com, which
supports both SSH1 and SSH2. Please refer to
data/openwebmail/applet/mindterm2/INSTALL.MINDTERM2 for more detail.

========================================================================
SPEED TUNING
========================================================================

Q: Will it speedup the login if the GNU copyright page is removed?
A: The GNU copyright page should be displayed for less than 1 second.
if you see it for a very long time after you login, then openwebmail
is busy in processing your INBOX folder (eg: mail indexing, filtering,
trash cleaning..)

Q: My openwebmail is slow, how can I make it faster?
A: You may try to use Open WebMail with the SpeedyCGI package, you will
get about 5x-10x speedup. Please refer to the readme.txt with keyword
SpeedyCGI for more detail.

Q: How SpeedyCGI speeds up Open WebMail?
A: SpeedyCGI makes Open WebMail resident in memory at the first request,
then the following requests will be served immediately without the
overhead of starting perl CGI.

This resident copy will terminate if it is idle for a certain time,
the default is 3600 seconds (1 hour)
You can set this with -t option in the Open WebMail scripts.

eg: #!/usr/bin/speedy -T -- -t7200

Q: Will the resident Open Webmail become larger and larger and finally
a memory hog?
A: No. We have tried our best to remove any memory leak from Open WebMail.
And a resident CGI will be restarted after it has served certain
number of requests. The default maxrun number is 500.
You can set this with -r option in the Open WebMail scripts.

eg: #!/usr/bin/speedy -T -- -t7200 -r250

Q: Some files of name like 'speedy.10.0.50.S' appear in my system /tmp?
A: They are the temporary files used by speedy and its backend program.
Please don't remove them. If you hope to put them in other location,
You can set the prefix of temporary files with -T option

eg: #!/usr/bin/speedy -T -- -t7200 -r250 -T/var/tmp/.speedy

Q: Open WebMail is fast when it is resident in memory, but the firsttime
startup delay is still long, is it possible to hide that delay from user?
A: You can use the script preload.pl to preload openwebmail scripts,
so the webmail user won't see the startup delay.

1. through web interface
http://your_server/cgi-bin/openwebmail/preload.pl
Please refer to preload.pl for default password and how to change it.

2. through command line or you can put the following line in crontab
to preload the most frequently used scripts into memory

0 * * * */usr/local/www/cgi-bin/openwebmail/preload.pl -q openwebmail.pl openwebmail-main.pl openwebmail-read.pl

If your machine has a lot of memory, you may choose to preload all
openwebmail scripts

0 * * * */usr/local/www/cgi-bin/openwebmail/preload.pl -q --all

Q: I got "connect error" when using preload.pl?
A: The preload.pl tries to connect the webmail server on localhost.
Please check if your webserver is binding on localhost or
change the variable $httphost in preload.pl

Q: How do I know if my Open WebMail is running under SpeedyCGI?
A: 1. Goto the user preference and click the 'about' button,
if you see word 'Persistence' appear in the line of webmail,
then your openwebmail is running under SpeedyCGI
2. Check the top of webmail page window border,
if you see a '+' appear after the 'Open WebMail' string,
then the page is generated under SpeedyCGI.

Q: I saw a HTTP compression checkbox in login screen, what is it used for?
A: When it is checked, web pages generated by Open WebMail will be
transmitted in gzip compressed format, this greatly reduces the time
required for page download.

This is very useful for users with slow connection. An rough experiment
showed that the compressed format is about only 10% in size compared with
the original web page.

Q: I could not check the HTTP compression checkbox, it is always disabled?
A: The HTTP compression feature won't be available if any one of the three
components (web server, web proxy, web browser) doesn't support HTTP
compression.

To enable the HTTP compression support:

1. Please install the Compress-Zlib-1.33.tar.gz on openwebmail server
2. Please enable "HTTP 1.1 support for direct connection" in your browser
3. If your connect to openwebmail server through proxy server,
please enable "HTTP 1.1 support over proxy" in your browser.
4. If the proxy server doesn't support HTTP 1.1,
please list your openwebmail server in exclusion table of proxy setting
in your browser.

Q: How do I know if my Open WebMail is running with HTTP compression enabled?
A: 1. Goto the user preference and click the 'about' button,
if you see word 'HTTP Compression' appear in the line of webmail,
then your openwebmail is running with HTTP compression enabled
2. Check the top of webmail page window border,
if you see a 'z' appear after the 'Open WebMail' string,
then the page is generated with HTTP compression enabled.

Q: Openwebmail uses lot of static images.
How can I avoid them being loaded frequently?
How can I extend the cache expire time for the static images?
A: Most web servers will set expire time in http header for static objects
based on their file date and the time the files are accessed.

If you would like to set the expire time explicitly:

Please add the following line to the end of your Apache configuration

<Directory "/usr/local/www/data/openwebmail">
ExpiresActive On
ExpiresByType image/gif A86400
ExpiresByType image/png A86400
ExpiresByType image/jpg A86400
ExpiresByType application/x-javascript A86400
</Directory>

The above lines set an expire time to one day for jpg, gif, png and
javascript files under openwebmail from the time they are accessed.

ps: Don't forget to change the above /usr/local/www/data/openwebmail
to where your openwebmail data locates.

Q: Any other way to get more speedup?
A: You may try the thttpd at http://www.acme.com/software/thttpd/,
here are some words from their web site :)

"thttpd is a simple, small, portable, fast, and secure HTTP server"

"It also has a very small run-time size, since it does not fork and
is very careful about memory allocation. "

"In typical use it's about as fast as the best full-featured servers
(Apache, NCSA, Netscape). Under extreme load it's much faster."

Please refer to doc/thttpd.txt for some installation tips.

========================================================================
SOME CONCEPT
========================================================================

Q: What will happen at webmail server if I click the stop key in browser?
A: When the stop key is pressed, the browser will close its connection to
the httpd on webmail server. While httpd detects this immediately,
what will httpd do to the CGI process is implementation dependent.
Basically, httpd will close the pipes to CGI process and terminate the
CGI process.

Below is our observation on apache 1.3.26 on FreeBSD.

The apache httpd won't terminate nor close the connection to the CGI
process until the CGI process sends output to its stdout. This gives
the chance to CGI process to finish its job in a more graceful way.

When httpd receives some data from CGI process stdout (which actually
pipes to stdin of httpd), the httpd will send a 'TERM' signal to CGI
process, close the pipes to CGI process, then kill the CGI process.

The situation is a little bit different if the CGI program is running
with SpeedyCGI. From the point of view of httpd, the speedycgi frontend
is the CGI process, so the frontend will be terminated as the above
when it tries to pass the data coming from the speedy_backend to httpd.
The data is result generated by real CGI process forked by speedy_backend.

When the speedy_backend detects the termination of the speedy frontend,
it will close the pipes to the real CGI process, but won't send TERM
signal to it nor kill it.

In both case (without or with speedycgi), the CGI process will get a
signal PIPE if it tries to output data to stdout after the related
pipe has been closed.

Now, what openwebmail do with this?
Since version 2.00, all stdout output code has been move to the end of the
request processing in openwebmail, this ensures the data being processed
will be always in a complete state and not terminated because of PIPE error.

Q: How is the domain of a login user determined?
A: It is determined in the following order
(the earlier one has higher precedence)
1. from the login name
eg: the user logined with username@virtualdomain
2. from the parameter 'logindomain' specified in login page url
eg: the login page was linked with
http://server/cgi-bin/openwebmail/openwebmail.pl?logindomain=virtualdomain
3. from the servername specified in the login page url
eg: the login page was linked with
http://virtualdomain/cgi-bin/openwebmail/openwebmail.pl

Q: How does the delfile_ifquotahit option work?
Which file will be removed first?
A: It will remove the oldest files or directories under the webdiskrootdir
(webdiskrootdir is default to / of user homedir, but you can change it).
The removal will stop if the quota size is download to the 90% of user
quota limit.

Q: What is the difference between 'Forward', 'ForwardAsAtt', 'ForwardAsOrig'
A: If A send msg1 to B,
and B forward this msg as msg2 to B

forward:
the subject of msg2 will be the subject of msg1 with a prefix "Fw:".
msg2 will have all attachments and content of msg1,
and headers of msg1 will be put into the body msg2 as content

forwardasatt:
the subject of msg2 will be the subject of msg1 with a prefix "Fw:".
msg2 body will be empty
and the raw format of msg1 will be become an attachment of msg2.

forwardasorig:
the subject, body and attachments of msg2 will exactly the same as msg1.
the replyto header of msg2 will be set to A.
So in case C replies the msg2, the reply will go back to A

Q: When I checked 'edit folder menu', I found some folders were empty but
took disk space?
A: The disk space occupied by a folder shown in 'edit folder menu' includes
the size of a folder and its index. Though folder is empty, the folder
index still has some data structure to maintain.

========================================================================
HOW CAN I...
========================================================================

Q: How can I move old messages in my mail client into openwebmail folders?
A: a. If your mail client program supports IMAP and your mail server has
imapd installed, you may move old messages in the mail client to
remote folders on mail server through the IMAP protocol.
Be sure to put the folders under ~/mail so openwebmail can find them
automatically.
b. Some mail client stores or can export messages into unix mbox format
folder file.(eg: Eudora) You can just upload the mbox file to the
~/mail/ and openwebmail will find them automatically.

ps: If your folder file is in dos text format, you may need use the
following command to stripe out the /r at each end of line.

perl -pi -e "s//r/n//n/" folderfile

Q: How can I upgrade from old version of Open Webmail?
A: Each version of openwebmail is made to be backward compatible with
old ones, no user setting or mail message will be lost after upgrade.
The upgrade steps:
1. make a copy of your old openwebmail.conf
2. install new openwebmail in the same location as old version
3. update the new openwebmail.conf with the setting in old one.

Q: How can I report problem?
A: If your Open WebMail doesn't work, please post your problem on
openwebmail forum http://sourceforge.net/forum/forum.php?forum_id=108433
with the following information

OS
Perl Version
your openwebmail.conf
the ls -l of the perl executable used in your openwebmail.pl
the ls -l of your cgi-bin/openwebmail and cgi-bin/openwebmail/etc
the ls -la of the ~user/mail/
the error message in your browser
the error message in your http server error log
the error message in openwebmail.log
you browser name & version
do you enable speedycgi?
do you set any proxy server in browser?

If your Open WebMail works but it shows strange output for some messages,
please forward the message as an attachment to us
(openwebmail.AT.turtle.ee.ncku.edu.tw)
ps: clicking the 'forward as attachment' icon in message reading menu

Q: How can I debug the Open WebMail by myself?
A: First, you can try to set option error_with_debuginfo to yes in
openwebmail.conf. This would give you more detailed information in case
openwebmailerror() happens.

Second, if you want to have a stack trace of how openwebmail is running,
you may use the misc/test/debugadd.pl to add debugging code to openwebmail
scripts

1. cd cgi-bin/openwebmail/
2. perl misc/test/debugadd.pl *pl

Then use openwebmail as normal, all sub routine calls will be logged into
/tmp/openwebmail.debug with timestamp. It should be helpful in debugging.

While you finish the debugging, you have to use misc/test/debugdel.pl to
remove debugging code from those scripts
1. cd cgi-vin/openwebmail/
2. perl misc/test/debugdel.pl *pl

Third, you may try to add lines like below to openwebmail scripts to log
some runtime information to /tmp/openwebmail.debug

ow::tool::log_time("$variablename");
ow::tool::log_time(ow::tool::stacktrace("$variablename and some other string"));

Q: Can I specify the composemessage menu as the openwebmail default?
A: You can call the openwebmail with url
http://server/openwebmail.pl?action=composemessage&to=EMAIL&subject=SUBJECT

Q: Can I specify the calendar month view as the openwebmail default?
A: You can call the openwebmail with url
http://server/openwebmail.pl?action=calmonth

Q: Can I specify the calendar day view as the openwebmail default?
A: You can call the openwebmail with url
http://server/openwebmail.pl?action=calday

Q: Can I specify the webdisk as the openwebmail default?
A: You can call the openwebmail with url
http://server/openwebmail.pl?action=showdir

Q: Can I call openwebmail from my programs with username/password specified?
A: this is a little dangerous since the loginname and password will
be displayed on the URL line of the user's browser.

You can call the openwebmail with url
http://server/openwebmail.pl?loginname=USER&password=PASS
or even with action specified
http://server/openwebmail.pl?action=calmonth&loginname=USER&password=PASS

ps: Openwebmail supports autologin since 2004/06/01, users doesn't have to
input username/password at login if he didn't logout his previous session
and that previous session is not timeouted.

Q: Can I get the mail/event status of a user before he logins openwebmail?
How can I get the username before user really types it?
A: If a user has ever successfully logined into openwebmail, the loginname
will be stored to cookie "ow-loginname" at the browser side.
The following CGI script demonstrates how to use this information.
-----------------------------------------
#!/usr/bin/perl
use CGI qw(-private_tempfiles :standard);
print "Content-type: text/html/n/n";
my $info;
my $loginname = cookie("ow-loginname");
$loginname=~s/[^/w/d/./-/%/@]//g;# remove dangerous char
if ($loginname ne "") {
$info=`/usr/local/www/cgi-bin/openwebmail/openwebmail-tool.pl -m -e $loginname`;
}
print $info;
------------------------------------------

Q: I already have a web application XYZ which would do authentication on user,
how can I integrate openwebmail with it so the user of XYZ doesn't need to
login again when click the openwebmail link?
A: All you have to do is writing an auth_XYZ.pl for openwebmail.

The auth_XYZ.pl should check if the user USERNAME has already logined into
application XYZ by verifying related session file or cookies.
If yes, routine check_userpassword() in auth_XYZ.pl should return 1;
if not, the routine should return 0

Then you specify auth_XYZ,pl as authentication module in openwebmail.conf
And the link to call the openwebmail.pl should be
http:/xxxx/openwebmail.pl?loginname=USERNAME&password=dummy

ps: you may modify the check_userpassword() in auth module that you already
use in openwebmail as a start.

Q: How can I setup IE to trigger Open WebMail compose window when I click
a "mailto:someone@somehost" link?
How can I set Open Webmail as the default mail client?
A: In Windows Explorer, if you go to Tools -> Folder Options, click on the
File Types tab. In the window that appears, scroll down the list to the
entry for "URL:MailTo Protocol". Highlight URL:MailTo and click edit.

Choose to edit the action for open. By default it probably has a
command to open Outlook Express (or your default email client).
Change the Application to read:
"C:/program files/internet explorer/iexplore.exe" http://your_server/cgi-bin/openwebmail/openwebmail.pl?loginname=NAME&password=PASSWORD

This will make Windows open Internet Explorer and go directly to the .pl
page and login with the specified user and pass.

(Thanks to Mike Andrews, mike.AT.lcso.org)

If you hope to goto the compose window directly
with the email address put in the To field,
please use the following open string instead

"C:/Program Files/Internet Explorer/iexplore.exe" http://your_server/cgi-bin/openwebmail/openwebmail.pl?loginname=USER&password=PASSWORD&action=composemessage&to=%1

(Thanks to Sergiy Zubatiy, sergey_sd.AT.users.sourceforge.net)

Q: How can I set an alias/redirection/link to the openwebmail script so users
can use openwebmail with a shorter url?
A: Please create a file, index.html, like below. Either a or b is okay.
Then put this index.html to the location mapped by the url you want.
a.
----------------------------------------
<html><head>
<meta http-equiv="Refresh"
content="0;URL=http://your_server/cgi-bin/openwebmail/openwebmail.pl">
</head></html>
----------------------------------------
b.
---------------------------------------
<html>
<body onload=
"window.open('http://your_server/cgi-bin/openwebmail/openwebmail.pl','_top')">
</body>
</html>
----------------------------------------

ps: An example redirect html is available at the
data/openwebmail/redirect.html

Q: Can I install openwebmail without root privilege?
A: Yes, try the auth_pop3.pl. Some information is available in it.

Q: Can Open WebMail be used with mod_perl?
A: No, the most reason is mod_perl can't be used for setuid program.
But Open Webmail works great in persistent mode with SpeedyCGI.
It is very fast too.

Q: Does Open WebMail support maildir and vpop3mail user by Qmail?
A: The official release does still not support maildir, however,
Laurent Frigault, lfrigault.AT.users.sourceforge.net has made patched
Open WebMail 2.01 to support maildir. It is available at
http://www.agneau.org/openwebmail/openwebmail-2.01-storage-20031027.tgz

Q: Will maildir be merged to official release of Open WebMail?
A: Yes, but we need to reorganization the code of openwebmail first
so the maildir patch could be merged into smoothly.
This would take some time...

Q: Can Openwebmail do xxx function or have yyy control option?
A: The best way to know all features of openwebmail is to check the
cgi-bin/openwebmail/etc/openwebmail.conf.help. Please check it.

Q: Can I use Open WebMail in a commercial web site?
A: Yes. Open WebMail is GPLed software (please see copyright.txt for
detail of GPL). You can distribute/use/modify/sell it freely ONLY IF

a. The GPL Copyright page must be kept untouched.
b. Any improvement of Open WebMail or any product based on Open WebMail
must be released to the public for free in source form if it is not for
internal use.
c. Products based on Open Webmail must be also distributed under GPL.

Jan/06/2005

openwebmail.AT.turtle.ee.ncku.edu.tw

////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////

openwebmail readme

Open WebMail is a webmail system based on
the Neomail version 1.14 from Ernie Miller.

Open WebMail is targeted on dealing with very big mail folder files in a
memory efficient way. It also provides many features to help users to
switch from Microsoft Outlook smoothly.

FEATURES
---------
Open WebMail has the following enhanced features:

For Users:

* Auto Login
* Multiple Languages/Multiple Charsets
* Strong MIME Message Capability
* Full Content Search
* Draft Folder Support
* Confirm Reading Support
* Spelling Check Support
* vCard compliant Addressbook
* POP3 Support
* Mail Filter Support
* AntiSpam Support through SpamAssassin (http://www.spamassassin.org)
* AntiVirus Support through ClamAV (http://www.clamav.net)
* Calendar with Reminder/Notification Support
* Webdisk Support
* HTTP Compression

For System:

* Fast Folder Access
* Efficient Message Movement
* Smaller Memory Footprint
* Graceful File Lock
* Various Authentication Modules
* PAM support
* Remote SMTP Relaying
* Virtual Hosting
* User Alias
* Pure Virtual User Support
* Per User Capability Configuration
* Persistent Running through SpeedyCGI

REQUIREMENT
-----------
Apache web server with cgi enabled
Perl 5.005 or above

CGI.pm-3.05.tar.gz (required)
MIME-Base64-3.01.tar.gz (required)
libnet-1.19.tar.gz (required)
Digest-1.08.tar.gz (required)
Digest-MD5-2.33.tar.gz (required)
Text-Iconv-1.2.tar.gz (required)
libiconv-1.9.1.tar.gz (required if system doesn't support iconv)

CGI-SpeedyCGI-2.22.tar.gz (optional but highly recommended, for persistent running)
Compress-Zlib-1.33.tar.gz (optional, for HTTP compression)
ispell-3.1.20.tar.gz (optional, for spellcheck)
Quota-1.4.10.tar.gz (optional, for unixfs quota support)
Authen-PAM-0.14.tar.gz (optional, for auth_pam support)
openssl-0.9.7d.tar.gz (optional, for pop3 over SSL support,
required only if system doesn't support libssl)
Net_SSLeay.pm-1.25.tar.gz (optional, for pop3 over SSL support)
IO-Socket-SSL-0.96.tar.gz (optional, for pop3 over SSL support)
clamav-0.70.tar.gz (optional, for viruscheck,
available at http://www.clamav.net)
Mail-SpamAssassin-3.02.tar.gz (optional, for spamcheck,
available at http://www.spamassassin.org)
antiword-0.35.tar.gz (optional, for msword preview)
ImageMagick-5.5.3.tar.gz (optional, for thumbnail support in webdisk)
tnef-1.2.3.1.tar.gz (optional, tnef is used mostly by mails from MS Outlook and Exchange)
wget-1.9.1.tar.gz (optional, for URL uploading support in webdisk & msg composing)
lsof_4.73A.freebsd.tar.bz2 (optional, for openwebmail-tool --unlock)

INSTALL REQUIRED PACKAGES
-------------------------
First, you have to download required packages from
http://openwebmail.org/openwebmail/download/packages/
and copy them to /tmp

CGI.pm installation:

cd /tmp
tar -zxvf CGI.pm-3.05.tar.gz
cd CGI.pm-3.05
perl Makefile.PL
make
make install

ps: It is reported that Open Webmail will hang in attachment uploading
when used with older version of CGI module. We recommend using CGI
version 2.74 or above for Open WebMail.
To check the version of your CGI module :

perl -MCGI -e 'print $CGI::VERSION'

MIME-Base64 installation:

cd /tmp
tar -zxvf MIME-Base64-3.01.tar.gz
cd MIME-Base64-3.01
perl Makefile.PL
make
make install

ps: Though you may already have the MIME-Base64 perl module,
we recommended you install MIME-Base64 module from source.
This would enable the XS support in this module which greatly
improves the encoding/decoding speed of MIME attachment.

libnet installation:

cd /tmp
tar -zxvf libnet-1.19.tar.gz
cd libnet-1.19
perl Makefile.PL (ans 'no' if asked to update configuration)
make
make install

Text-Iconv-1.2 installation:

Since Text-Iconv-1.2 is actually a perl interface to the underlying iconv()
support, you have to check if iconv() support is available in your system.
Please type the following command

man iconv

If there is no manual page for iconv, your system might not support iconv(),
You need to install libiconv package to get iconv() support.

cd /tmp
tar -zxvf libiconv-1.9.1.tar.gz
cd libiconv-1.9.1
./configure
make
make install

Type 'man iconv' again to make sure the libiconv is successfully installed.
Then we start to install the Text-Iconv package

cd /tmp
tar -zxvf Text-Iconv-1.2.tar.gz
cd Text-Iconv-1.2
perl Makefile.PL

ps: If your system is FreeBSD, or you just installed libiconv manually,
please edit the Makefile.PL and change the LIBS and INC lines
as the following before doing 'perl Makefile.PL'

'LIBS' => ['-L/usr/local/lib -liconv'], # e.g., '-lm'
'INC' => '-I/usr/local/include', # e.g., '-I/usr/include/other'

make
make test

ps: If the 'make test' failed, it means you set wrong value for LIBS and
INC in Makefile.PL or your iconv support is not complete.
You may copy the misc/patches/iconv.pl.fake to shares/iconv.pl to make
openwebmail work without iconv support.

make install

INSTALL OPENWEBMAIL
-------------------
The latest released or current version is available at
http://openwebmail.org/openwebmail/

If you are using FreeBSD and install apache with pkg_add,

1. chmod 4555 /usr/bin/suidperl
(It seems perl after 5.8.1 should set the suidperl to 555 instead,
or the suid support may not work)

2. cd /usr/local/www
tar -zxvBpf openwebmail-X.XX.tar.gz

3. cd /usr/local/www/cgi-bin/openwebmail/etc
modify openwebmail.conf for your need.

4. execute /usr/local/www/cgi-bin/openwebmail/openwebmail-tool.pl --init

ps: If you are using FreeBSD and your perl is compiled from port,
then please note that the SUID support is disabled by default
since the port for perl 5.8.1 or later

You need to do 'make -DENABLE_SUIDPERL' in making port

If you are using RedHat 7.x (or most Linux) with Apache

1. cd /var/www
tar -zxvBpf openwebmail-X.XX.tar.gz
mv data/openwebmail html/
rmdir data

2. cd /var/www/cgi-bin/openwebmail/etc

modify auth_unix.conf from defaults/auth_unix.conf
a. set passwdfile_encrypted to '/etc/shadow'
b set passwdmkdb to 'none'

modify openwebmail.conf
a. set mailspooldir to '/var/spool/mail'
b. set ow_htmldir to '/var/www/html/openwebmail'
set ow_cgidir to '/var/www/cgi-bin/openwebmail'
c. set spellcheck to '/usr/bin/ispell -a -S -w "-" -d @@@DICTIONARY@@@ -p @@@PDICNAME@@@'
d. change default_signature for your need
e. other changes you want

3. add
/var/log/openwebmail.log {
postrotate
/usr/bin/killall -HUP syslogd
endscript
}
to /etc/logrotate.d/syslog to enable logrotate on openwebmail.log

4. execute /var/www/cgi-bin/openwebmail/openwebmail-tool.pl --init

If you are using RedHat 6.2, please use /home/httpd instead of /var/www
ps: It is highly recommended to read the doc/RedHat-README.txt(contributed by
elitric.AT.yahoo.com) if you are installing Open WebMail on RedHat Linux.

ps: Thomas Chung (tchung.AT.openwebmail.org) maintains the rpm for all
released and current version of openwebmail, It is available at
http://openwebmail.org/openwebmail/download/redhat/rpm/.

Documents for RH7.3/RH8/RH9, RHEL3, FC1/FC2/FC3 are available at
http://openwebmail.org/openwebmail/download/redhat/howto/00-openwebmail.html
You can get openwebmail working in 5 minutes with this :)

If you are using other UNIX with apache, that is okay

Try to find the parent directory of both your data and cgi-bin directory,
eg: /usr/local/apache/share, then

1. cd /usr/local/apache/share
tar -zxvBpf openwebmail-X.XX.tar.gz
mv data/openwebmail htdocs/
rmdir data

2. cd /usr/local/apache/share/cgi-bin/openwebmail

modify openwebmail*.pl
change the #!/usr/bin/suidperl to the location where your suidperl is.

3. cd /usr/local/apache/share/cgi-bin/openwebmail/etc

modify openwebmail.conf
a. set mailspooldir to where your system mail spool is
b. set ow_htmldir to '/usr/local/apache/share/htdocs'
set ow_cgidir to '/usr/local/apache/share/cgi-bin'
c. set spellcheck to '/usr/local/bin/ispell -a -S -w "-" -d @@@DICTIONARY@@@ -p @@@PDICNAME@@@'
d. change default_signature for your need
e. other changes you want

modify auth_unix.conf from defaults/auth_unix.conf
a. set passwdfile_encrypted to '/etc/shadow'
b set passwdmkdb to 'none'

4. execute /usr/local/apache/share/cgi-bin/openwebmail/openwebmail-tool.pl --init

ps:If you are installing Open WebMail on Solaris, please put
'the path of your openwebmail cgi directory' in the first line of
file /etc/openwebmail_path.conf.

For example, if the script is located at
/usr/local/apache/share/cgi-bin/openwebmail/openwebmail.pl,

then the content of /etc/openwebmail_path.conf should be:
/usr/local/apache/share/cgi-bin/openwebmail

ps: If you are using Apache server 2.0 or later,
please edit your Apache Configuration file, replace

AddDefaultCharset ISO-8859-1

with

AddDefaultCharset off

INITIALIZE OPENWEBMAIL
----------------------
In the last step of installing openwebmail, you have done:

cd the_directory_of_openwebmail_cgi_scripts
./openwebmail-tool.pl --init

This init will create the mapping tables used by openwebmail in the future.
If you skip this step, you will not be able to access the openwebmail through
web interface.

As perl on various platforms may use different underlying dbm system, the
default setting in the_directory_of_openwebmail_cgi_scripts/etc/dbm.conf
may be not correct for your system.

The init routine will test them and try to give you some useful suggestions.

1. it checks options in etc/dbm.conf,
if they are set to wrong value, you may see output like
-------------------------------------------------------------
Please change '/the_directory_of_openwebmail_scripts/etc/dbm.conf' from

dbm_ext .db
dbmopen_ext none
dbmopen_haslock no

to

dbm_ext .db
dbmopen_ext none
dbmopen_haslock no
-------------------------------------------------------------

2. it checks if the dbm system uses DB_File.pm by default and will
suggest a necessary patch to DB_File.pm, you may see output like
-------------------------------------------------------------
Please modify /usr/libdata/perl/5.00503/mach/DB_File.pm by adding

$arg[3] = 0666 unless defined $arg[3];

before the following text (about line 247)

# make recno in Berkeley DB version 2 work like recno in version 1
-------------------------------------------------------------

Please follow the suggestion or the openwebmail may not work properly.
And don't forget to redo './openwebmail-tool.pl --init' after you complete
the modification.

USING OPENWEBMAIL WITH OTHER SMTP SERVER
----------------------------------------
To make openwebmail use other SMTP server for mail sending,
you have to set the option 'smtpserver' in openwebmail.conf.
Just change the default value '127.0.0.1' to the name/ip of that SMTP server.

Please be sure the SMTP server allows mail relayed from your openwebmail host.

FILTER SUPPORT
--------------
The mailfilter checks if messages in INBOX folder matches the filters rules
defined by user. If matches, move/copy the message to the target folder.
If you move a message to the DELETE folder, which means deleting messages
from a folder. If you use INBOX as the destination in a filter rule,
any message matching this rule will be kept in the INBOX folder and
other rules will be ignored.

VIRUSCHECK SUPPORT
------------------
Openwebmail can call external programs to do viruscheck for pop3 or
other messages in INBOX. To enable virus check support, you have to

1. install ClamAV (http://www.clamav.net/)
And ensure you have started up the daemon of the clamav - clamd
2. modify option viruscheck_pipe according to the location of clamdscan
(it is the client side of ClamAV)
3. set viruscheck_source_allowed to either pop3 or all.
This depends on the configuration of your mail system
If MTA or mail deliver will do virus scanning,
then you should set this to pop3, otherwise, you may set it to all.
4. set enable_viruscheck to yes in openwebmail.conf
5. there are some other viruscheck related options in defaults/openwebmail.conf,
please refer to openwebmail.conf.help for more detail

ps: Thomas Chung has written a document
"HOWTO install and configure ClamAV for Open WebMail on Red Hat/Fedora Core"
It is available at http://openwebmail.org/openwebmail/download/redhat/howto/virus/ClamAV/HOWTO-clamav.txt

SPAMCHECK SUPPORT
-----------------
Openwebmail can call external programs to do spamcheck for pop3 or
other messages in INBOX. To enable spam check support, you have to

1. install SpamAssassin (http://www.spamassassin.org)
And ensure you have started up the daemon of the spamassasin (spamd)
ps:Please be sure that the spamd is started with -L or --local option
This causes spamd to do local only test, or the spamcheck will take
a much longer time.
2. modify option spamcheck_pipe according to the location of spamc
(it is the client side of spamassassin)
3. set spamcheck_source_allowed to either pop3 or all.
This depends on the configuration of your mail system
If MTA or mail deliver will do spam scanning,
then you should set this to pop3, otherwise, you should set it to all.
4. set enable_spamcheck to yes in openwebmail.conf
5. there are some other spamcheck related options in defaults/openwebmail.conf,
please refer to openwebmail.conf.help for more detail

ps: If you have set 'allow_user_rules 1' in the local.cf of your spamassassin,
you may set option 'enable_saprefs' to yes in your openwebmail.conf,
this would allow users to set the test rules, whilelist and blacklist in
the spamassassin userprefs file (~/.spamassassin/userprefs).

ps: How and when does openwebmail call the external programs to check messages?

The pop3 messages are checked when they are fetched
from remote pop3 server, the fetching and checking are done in background.
Other new messages in INBOX (which is delivered by mail system) are checked
at the time user accesses the mail folder. A mail filtering process will be
forked at background to check the messages in INBOX.

ps: An option "wait time for background filtering" is provided in preference,
which can be used to control how long user would like to wait for mail
filtering before the folder message list or message content is returned.

Please don't set it too short or some spam/virus may not get filtered
in time before user accesses them.

ps: The viruscheck/spamcheck is majorly designed to check messages fetched
from pop3 server since these messages won't be checked by scanners in
MTA or local deliver.

While viruscheck/spamcheck can also check all messages in INBOX, but
we suggest that the sysadm should install antispam/antivurs softwares
in either MTA or local deliver so mails can get checked before delivered
into INBOX. It is more efficient than scanning all mails in Open WebMail.
And the mails will get checked even the user is using client other than
Open WebMail.

LEARNSPAM SUPPORT
-----------------
Openwebmail can call external programs to learn HAM/SPAM messages by storing
the tokens of messages in per user bayesian db..
To enable learn ham/spam support, you have to

1. install SpamAssassin (http://www.spamassassin.org)
2. modify option learnspam_pipe and learnham_pipe according to the location
of sa-learn (it is the ham/psam learner of spamassassin)
3. set enable_learnspam to yes in openwebmail.conf

ps:The learned result are stored as per user bayesian db,
and learnspam is useful only if the db is referenced.

The two cases that the per user bayesian db is used:
a. spamassassin check is called in local deliver, or
b. spamassassin check is enabled in openwebmail

USER QUOTA
----------
The disk space used by webmail, webcalendar or webdisk are counted together as
the user quota usage. There are five options can be used to control the user
quota in defaults/openwebmail.conf. You may override the defaults by setting
them in openwebmail.conf.

1. quota_module

This option is used to choose the quota system for your openwebmail.
There are two quota modules available currently.

a. quota_unixfs.pl

This is the recommended quota module if the openwebmail user is the real
unix user and you system has enables the disk quota.
It has the minimal overhead.

ps:You have to install the Quota-1.4.10.tar.gz to use the module.

b. quota_du.pl

This is the recommended module only if quota_unixfs.pl could not be used on
your system (eg: openwebmail user is not standard unix user or unix quota
is not available.), because it uses the 'du -sk' to get the user quota usage.

Since running 'du -sk' on a large directory may be quote time consuming,
this module will cache the result of the 'du -sk' to avoid too much overhead.
The default cache lifetime is 60 seconds and could be changed in quota_du.pl

If you set this option to 'none', then no quota system will be used in openwebmail

2. quota_limit

This option sets the limit (in kb) for user quota usage.
The webmail and webdisk operation is limited to 'delete' if quota is hit.
This option won't prevent the operation taking the user over this limit
from completing but simply inhibits further saving of messages or files
until the user quota usage is brought down again.

ps: The value set in this option is used only if quota module doesn't support
quotalimit. ( whose quota_info() routine returns the quotalimit as -1 )

ps: If you use the quota_unixfs.pl as the quota module,
please be sure that there is some space between the softlimit and
hardlimit (eg:5mb)

eg: filesystem quota softlimit=25000, hardlimit=30000

3. quota_threshold

Normally, the user quota info will be put in the window title of the browser.
But if the user quota usage is more the threshold set by this option,
a big quota string will be displayed at the top of webmail and webdisk main menu

4. delmail_ifquotahit

Set this option to yes to make openwebmail remove oldest messages from user
mail folders automatically in case his quotalimit is hit. the new total
size will be cut down to apporximately 90% of option quota_limit

5. delfile_ifquotahit

Set this option to yes to make openwebmail remove oldest files from webdisk
/ automatically in case his quotalimit is hit. the new total
size will be cut down to apporximately 90% of option quota_limit

ps: The above options are used to control quota of user homedir.
if you want to limit the size of user mail spool (the INBOX folder),
you have to use the spool_limit option.
Please refer to openwebmail.conf.help for more detail.

ps: Since openwebmail 20031128, you may set the option
use_syshomedir_for_dotdir to no to have openwebmail put index db
in ow_usersdir instead of user homedir, thus creating db won't be
limited by user quota.
This would fix the problem that user exceeding his quota was unable
to login openwebmail because of corrupt index folder db

COMMAND TOOL openwebmail-tool.pl
--------------------------------
Since mail filtering is activated only in Open WebMail, it means messages
will stay in the INBOX until user reads their mail with Open WebMail.
So 'finger' or other mail status check utility may give you wrong
information since they don't know about the filter.

A command tool 'openwebmail-tool.pl' can be used as finger replacement.
It does mail filtering before reporting mail status.

Some fingerd allow you to specify the name of finger program by -p option
(eg: fingerd on FreeBSD). By changing the parameter to fingerd in
/etc/inetd.conf, users can get their mail status from remote host.

openwebmail-tool.pl can be also used in crontab to prefetch pop3mail or
do folder index verification for users. For example:

59 5 * * * /usr/local/www/cgi-bin/openwebmail/openwebmail-tool.pl -q -a -p -i

The above line in crontab will do pop3mail prefetching, mail filtering and
folder index verification quietly for all users at 5:59 every morning.

If you have enabled the calendar_email_notifyinterval in openwebmail.conf,
you will also need to use openwebmail-tool.pl in crontab to check the calendar
events for sending the notification emails. For example:

0 */2 * * * /usr/local/www/cgi-bin/openwebmail/openwebmail-tool.pl -q -a -n

The above line will use openwebmail-tool.pl to check the calendar events for all
users every two hours. Please note we use this frequency because the default
value of option calendar_email_notifyinterval is 120 (minute).
You have to set the crontab according to your calendar_email_notifyinterval.

GLOBAL ADDRESSBOOK
--------------------------------------------
Open WebMail supports multiples global addressbooks, the location for global
addressbook files is specified in the option ow_addressbooksdir.

The sysadm have to create the empty global addressbooks manually with command
'touch addressbook_filename', then other user may read/write the global
addressbook from the web addressbook interface in openwebmail.

The global addressbook will be editable to a user only if:
1. the option abook_globaleditable is set to yes, and
2. the user has enough privilege to write the global addressbook file.

GLOBAL FILTERRULE and CALENDAR
--------------------------------------------
Current support for global filterrule/calendar is very limited.
The administrator has to make a copy of filterbook/calendar to the file
specified by global_filterbook or global_calendarbook by himself.

ps: An account may be created to maintain the global addressbook/filterbook,
for example: 'global'

ln -s your_global_filterbook ~global/.openwebmail/webmail/filter.book
ln -s your_global_calendarbook ~global/.openwebmail/webcal/calendar.book

Please be sure that the global files are writeable by user 'global'
and readable by others

SPELL CHECK SUPPORT
-------------------
To enable the spell check in openwebmail, you have to install the ispell or
aspell package.

1. download ispell-3.1.20.tar.gz from
http://www.cs.ucla.edu/ficus-members/geoff/ispell.html and install it,
or you can install binary from FreeBSD package or Linux rpm

ps: if you are compiling ispell from source, you may enhance your ispell
by using a better dictionary source.
a. download http://openwebmail.org/openwebmail/download/contrib/words.gz
b. gzip -d words.gz
c. mkdir /usr/dict; cp words /usr/dict/words
d. start to make your ispell by reading README

2. check the openwebmail.conf to see if spellcheck is pointed to the
ispell binary

3. If you have installed multiple dictionaries for your ispell/aspell,
you may put them in option spellcheck_dictionaries in openwebmail.conf
and these dictionary names should be separated with comma.

ps: To know if a specific dictionary is successfully installed on
your system, you can do a test with following command

ispell -d dictionaryname -a

4. If the language used by a dictionary has a different character set than
English, you have to define the characters in %dictionary_letters in
the openwebmail-spell.pl for that dictionary.

AUTOREPLY SUPPORT
-----------------
The auto reply function in Open WebMail is done with the vacation utility.
Since vacation utility is not available on some unix, a perl version of
vacation utility 'vacation.pl' is distributed with openwebmail.
This vacation.pl has the same syntax as the one on Solaris.

If the autoreply doesn't work on your system,
you can do debug with the -d option

1. choose a user, enable his autoreply in openwebmail user preference
2. edit the ~user/.forward file,
add the '-d' option after vacation.pl
3. send a message to this user to test the autoreply
4. check the /tmp/vacation.debug for possible error information

Things you may find in /tmp/vacation.debug

'User ... not found in to: and cc:',

This tends to occur (assuming the address is legitimate) when your email
addresses don't match your system accounts. For instance, when mail for
[e-mail] is deposited in system account twood. The error will look
something like this:

20040505 170028 User [e-mail] twood not found in to: and cc:, autoreply canceled

Vacation.pl assumes that the user part of the email address (e.g. tim.wood)
will match their account on the system (e.g. twood). If they don't you can
work around this by

a. add the -j after vacation.pl in option vacationpipe in openwebmail.conf

vacationpipe %ow_cgidir%/vacation.pl -j -t60s

ps: this modification won't take effect until user reset their .forward
file by switching on and off the email forwarding in openwebmail,
so you may wish to use the following modification instead

b. editing vacation.pl (in the openwebmail folder, typically at
/var/www/cgi-bin/openwebmail/). At the top of the 'MAIN' section,
you'll find a while that's used to parse options:

# parse options, handle initialization or interactive mode
while (defined($ARGV[0]) && $ARGV[0] =~ /^-/) {
$_ = shift;
[snip]
}
}

Immeadiately after that section, add:

$opt_j=1;

This tells vacation.pl to not check that the email address and system
account match. Note: this means that everytime the user receives an email
from a mailing list, everyone on the mailing list will know the user is
out-of-office. And if it's a busy list, they'll hear about it a lot.
(by twood, tim.wood.AT.compucomfed.com)

WEBDISK SUPPORT
---------------
The webdisk module provides a web interface for user to use his home
directory as a virtual disk on the web. It is also designed as a
storage of the mail attachments, you can freely copy attachments
between mail messages and the webdisk.

The / of the virtual disk is mapped to the user's home directory,
any item displayed in the virtual disk is actually located under the
user home directory.

Webdisk supports basic file operation (mkdir, rmdir, copy, move, rm),
file upload and download (multiple files or directories download is supported,
webdisk compresses them into a zip stream on the fly when transmitting).
It can also handle many types of archives, including zip, arj, rar, tar.gz,
tar.bz, tar.bz2, tgz, tbz, gz, z...

Obviously, WebDisk have to call external program to provide all the above
features, it finds the external programs in /usr/local/bin, /usr/bin
and /bin respectively.

the external programs used by webdisk are:

basic file uty - cp, mv, rm,
file compression/decompression - gzip, bzip2,
archive uty - tar, zip, unzip, unrar, unarj, lha
image thumbnail uty - convert (in ImageMagick package)

ps: You don't have to install all external programs to use WebDisk,
a feature will be disabled if related external program is not available.

External commands are invoked with exec() and parameters are passed by
array, which prevents using /bin/sh for shell escaped character
interpretation and thus is quite secure.

To limit the WebDisk space used by the user, please refer to the
'USER QUOTA' section

VIRTUAL HOSTING
---------------
You can have as many virtual domains as you want on same server with only one
copy of openwebmail installed. Open Webmail supports per domain config file.
Each domain can have its own set of configuration options, including
domainname, authentication module, quota limit, mailspooldir ...

You can even setup mail accounts for users without creating real unix accounts
for them. Please refer to Kevin Ellis's webpage:
"How to setup virtual users on Open WebMail using Postfix & vm-pop3d"
(http://www.bluelavalamp.net/owmvirtual/)

eg: To create configuration file for virtualdomain 'sr1.domain.com'

1. cd cgi-bin/openwebmail/etc/sites.conf/
2. cp ../openwebmail.conf sr1.domain.com
3. edit options in file 'sr1.domain.com' for domain 'vr1.domain.com'

USER ALIAS MAPPING
------------------
Open Webmail can use the sendmail virtusertable for user alias mapping.
The loginname typed by user may be pure name or name@somedomain. And this
loginname can be mapped to another pure name or name@otherdomain in the
virtusertable. This gives you the great flexibility in account management.

Please refer to http://www.sendmail.org/virtual-hosting.html for more detail

When a user logins Open WebMail with a loginname,
this loginname will be checked in the following order:

if (loginname is in the form of 'someone@somedomain') {
user=someone
domain=somedomain
} else { # a purename
user=loginname
domain=HTTP_HOST# hostname in url
}

is user@domain a virtualuser defined in virtusertable?
if not {
if (domain is mail.somedomain) {
is user@somedomain defined in virtusertable?
} else {
is [e-mail] defined in virtusertable?
}
}

if (no mapping found && loginname is pure name) {
is loginname a virtualuser defined in virtusertable?
}

if (any mapping found) {
if (mappedname is in the form of 'mappedone@mappeddomain') {
user=mappedone
domain=mappeddomain
} else {
user=mappedname
domain=HTTP_HOST
}
}

if (option auth_withdomain is on) {
check_userpassword for user@domain
} else {
if (domain == HTTP_HOST) {
check_userpassword for user
} else {
user not found!
}
}

ps: if any alias found in virtusertable,
the alias will be used as default email address for user

Here is an example of /etc/virtusertable

projectmanagerpm
[e-mail]1
[e-mail]1
[e-mail]2
[e-mail]3

Assume the url of the webmail server is http://mail.company1.com/....

The above virtusertable means:
1. if a user logins as projectmanager,
openwebmail checks [e-mail]
[e-mail]
projectmanager as virtualuser---> pm

2. if a user logins as [e-mail]
openwebmail checks [e-mail]---> john1

if a user logins as johnson,
openwebmail checks [e-mail]
[e-mail]---> john1

3. if a user logins as [e-mail],
openwebmail checks [e-mail]---> tom1

if a user logins as [e-mail],
openwebmail checks [e-mail]---> tom2

if a user logins as tom,
openwebmail checks [e-mail]
[e-mail]---> tom1

4. if a user logins as mary,
openwebmail checks [e-mail]
[e-mail]
mary as virtualuser---> not an alias

PURE VIRTUAL USER SUPPORT
-------------------------
Pure virtual user means a mail user who can use pop3 or openwebmail
to access his mails on the mail server but actually has no unix account
on the server.

Openwebmail pure virtual user support is currently available for system
running vm-pop3d + postfix. The authentication module auth_vdomain.pl is
designed for this purpose. Openwebmail also provides the web interface
which can be used to manage(add/delete/edit) these virtual users under
various virtual domains.

Please refer to the description in auth_vdomain.pl and auth_vdomain.conf
for more detail.

ps: vm-pop3d : http://www.reedmedia.net/software/virtualmail-pop3d/
PostFix : http://www.postfix.org/

Kevin L. Ellis (kevin.AT.bluelavalamp.net) has written a tutorial
for openwebmail + vm-pop3d + postfix
Iis available at http://www.bluelavalamp.net/owmvirtual/

PER USER CAPABILITY CONFIGURATION
---------------------------------
While options in system config file(openwebmail.conf) are applied to all
users, you may find it useful to set the options on per user basis sometimes.
For example, you may want to limit the client ip access for some users or
limit the domain which the user can sent to. This could be easily done with
the per user config file support in Open Webmail.

The user capability file is located in cgi-bin/openwebmail/etc/user.conf/
and named as the realusername of user. Options in this file are actually
a subset of options in openwebmail.conf. An example 'SAMPLE' is provided.

eg: To creat the capability file for user 'guest':

1. cd cgi-bin/openwebmail/etc/users.conf/
2. cp SAMPLE guest
3. edit options in file 'guest' for user guest

ps: Openwebmail loads configuration files in the following order

1. cgi-bin/openwebmail/etc/defaults/openwebmail.conf
2. cgi-bin/openwebmail/etc/openwebmail.conf
3. cgi-bin/openwebmail/etc/sites.conf/domainname if file exists

a. authentication module is loaded
b. user alias is mapped to real userid.
c. userid is authenticated.

4. if (option auth_withdomain is yes) {
user conf = cgi-bin/openwebmail/etc/users.conf/domain/username
} else {
user conf = cgi-bin/openwebmail/etc/users.conf/username
}
Then openwebmail will load user conf if file exists.

Options set in the later files will override the previous ones

PAM SUPPORT
-----------
PAM (Pluggable Authentication Modules) provides a flexible mechanism
for authenticating users. More detail is available at Linux-PAM webpage.
http://www.kernel.org/pub/linux/libs/pam/

Solaris 2.6, Linux and FreeBSD 3.1 are known to support PAM.
To make Open WebMail use the support of PAM, you have to:

1. download the Perl Authen::PAM module (Authen-PAM-0.14.tar.gz)
It is available at http://www.cs.kuleuven.ac.be/~pelov/pam/
2. cd /tmp
tar -zxvf Authen-PAM-0.14.tar.gz
cd Authen-PAM-0.14
perl Makefile.PL
make
make install

ps: Doing 'make test' is recommended when making the Authen::PAM,
if you encounter error in 'make test', the PAM on your system
will probable-ly not work.

3. change auth_module to 'auth_pam.pl' in the openwebmail.conf

4. check auth_pam.pl and auth_pam.conf for further information.

ps: Since the authentication module is loaded only once in persistent mode,
you need to do 'touch openwebmail*pl' to make the modification active.
To avoid this, you may change your openwebmail backto suid perl mode
before you make the modifications.
ps: For more detail about PAM configuration, it is recommended to read
"The Linux-PAM System Administrators' Guide"
http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam.html
by Andrew G. Morgan, morgan.AT.kernel.org

ps: The script in cgi-bin/openwebmail/misc/test/authtest.pl can used to
test if the a authentication module under cgi-bin/openwebmail/auth/ works
on your system.

eg: cd your_cgi-bin/openwebmail/
perl authtest.pl auth_unix.pl someusername passwd
perl authtest.pl auth_pam.pl someusername passwd

ps: On some system, root is not allowed to login,
and PAM will always return false for root login

ADD NEW AUTHENTICATION MODULE TO OPENWEBMAIL
--------------------------------------------
Various authentications are directly available for openwebmail, including

auth_ldap.pl
auth_mysql.pl
auth_mysql_vmail.pl
auth_pam.pl
auth_pg.pl
auth_pgsql.pl
auth_pop3.pl
auth_unix.pl
auth_vdomain.pl

In case you found these modules not suitable for your need,
you may write a new authentication module for your own.

To add new authentication module into openwebmail, you have to:

1. choose an abbreviation name for this new authentication, eg: xyz

2. declare the package name in the first line of file auth_xyz.pl

package ow::auth_xyz;

3. implement the following 4 function:

($retcode, $errmsg, $realname, $uid, $gid, $homedir)=
get_userinfo($r_config, $domain, $user);

($retcode, $errmsg, @userlist)=
get_userlist($r_config, $domain);

($retcode, $errmsg)=
check_userpassword($r_config, $domain, $user, $password);

($retcode, $errmsg)=
change_userpassword($r_config, $domain, $user, $oldpassword, $newpassword);

where $retcode means:
-1 : function not supported
-2 : parameter format error
-3 : authentication system internal error
-4 : username/password incorrect

$errmsg is the message to be logged to openwebmail log file,
this would ease the work for sysadm in debugging problem of openwebmail

$r_config is the reference of the openwebmail %config,
you may just leave it untouched

ps: You may refer to auth_unix.pl or auth_pam.pl to start.
And please read doc/auth_module.txt

4. modify option auth_module in openwebmail.conf to auth_xyz.pl

5. test your new authentication module :)

ps: If you wish your authentication module to be included in the next release
of openwebmail, please submit it to openwebmail.AT.turtle.ee.ncku.edu.tw.
ps: Since the authentication module is loaded only once in persistent mode,
you need to do 'touch openwebmail*pl' to make the modification active.
To avoid this, you may change your openwebmail backto suid perl mode
before you make the modifications.

ADD SUPPORT FOR NEW LANGUAGE
-----------------------------
It is very simple to add support for your language into openwebmail

1. choose an abbreviation for your language, eg: xy

ps: You may choose the abbreviation by referencing the following url
http://babel.alis.com/langues/iso639.en.htm
http://www.unicode.org/unicode/onlinedat/languages.html
http://www.w3.org/International/O-charset.html

2. cd cgi-bin/openwebmail/etc.
cp lang/en lang/xy
cp -R templates/en templates/xy

3. translate file lang/xy and templates/xy/* from English to your language

4. change the package name of you language file (in the first line)

package ow::xy

5. add the name and charset of your language to %languagenames,
%languagecharsets in modules/lang.pl, then set default_language
to 'xy' in openwebmail.conf

6. check iconv.pl, if the charset is not listed, add a line for this charset
in both %charset_localname and %charset_convlist.

7. translate the files used by HTML editor

cd data/openwebmail/javascript/htmlarea.openwebmail/popups
cp -R en xy
cd xy

then translate htmlarea-lang.js, insert_image.html, insert_sound.html,
insert_table.html and select_color.html into language xy

Some style sheel setting in insert*html may need to be adjusted to
get the best layout for your language. They are

a. the width and height of the pop window, defined in the first line
<html style="width: 398; height: 243">

b. the boxies for fieldsets, defined in middle of the file
.fl { width: 9em; float: left; padding: 2px 5px; text-align: right; }
.fr { width: 6em; float: left; padding: 2px 5px; text-align: right; }

.fl is for box in the left and .fr is for box in the right,
you may try wider width for better layout

8. If you want, you may create the holidays of your language with the
openwebmail calendar, then copy the ~/.openwebmail/webcal/calendar.book into
etc/holidaysdir/your_languagename. Them the holidays will be displayed
to all users of this language

9. If you want, you may also translation help tutorial to your language
the help files are located under data/openwebmail/help.

ps: if your language is Right-To-Left oriented and you can read Arabic,
you can use the Arabic template instead of English as the start templates.
And don't forget to mention it when you submit the templates
to the openwebmail team.
ps: Since the language and templates are loaded only once in persistent mode,
you need to do 'touch openwebmail*pl' to make the modification active.
To avoid this, you may change your openwebmail backto suid perl mode
before you make the modifications.

ps: If you just want support of different charset of existing language,
you may try the openwebmail-tool.pl --langconv command

a. choose a new name for the converted language
b. add the new name and it charset to %languagenames,%languagecharsets
in modules/lang.pl
c. execute 'openwebmail-tool.pl --langconv oldlangname newlangname'
d. if you see any error complaing directory doesn't exist,
you may creat it manually and re-execute above command
e. After conversion, don't forget to test the converted lang file by
'perl etc/lang/newlangname' to ensure it is valid for perl parser.

ps: If you wish your translation to be included in the next release of
openwebmail, please submit it to openwebmail.AT.turtle.ee.ncku.edu.tw.

IMPORTANT!!!
Please be sure your translation is based on the template files in the
latest openwebmail-current.tar.gz. And please send both your tranlsation
and english version files it based on to us. So we can check if there
is any latest modification should be added your translation.

ADD NEW CHARSET TO AUTO CONVERSION LIST
---------------------------------------
Openwebmail can do charset conversion automatically if a message is written
with charset other than the one you are using. Openwebmail does this by calling
the iconv() charset conversion function, as defined by the Single UNIX Specification.

To make openwebmail do auto-convert a new charset for your language:
1. find the charset used by your language in %charset_convlist in charset_iconv.pl
2. put this new charset to the convlist of the charset of your language
3. define the localname of the new charset on your OS to the %charset_localname.
(It is always the same as the name of charset but in capitals.)

Note: The possible conversions and the quality of the conversions depend on the
available iconv conversion tables and algorithms, which are in most cases
supplied by the operating system vendor.

ADD MORE BACKGROUNDS TO OPENWEBMAIL
-----------------------------------
If you would like to add some background images into openwebmail for your
user, you can copy them into %ow_htmldir%/images/backgrounds.
Then the user can choose these backgrounds from user preference menu.

ps: If you wish to share your wonderful backgrounds with others,
please email it to openwebmail.AT.turtle.ee.ncku.edu.tw

DESIGN YOUR OWN ICONSET IN OPENWEBMAIL
---------------------------------------
If you are interested in designing your own image iconset in the openwebmail,
you have to

1. create a new sub directory in the %ow_htmldir%/images/iconsets/,
eg: MyIconSet
ps: %ow_htmldir% is the dir where openwebmail could find its html objects,
it is defined in openwebmail.conf
2. copy all images from %ow_htmldir%/images/iconsets/Default to MyIconSet
3. modify the image files in the %ow_htmldir%/images/iconsets/MyIconSet
for your need

ps:In case you want to design iconsets with text inside, the default font used
in Default.English and Cool3D.English is 'Arial Narrow'.

If you are interested in designing your own text iconset in the openwebmail,
you have to

1. create a new sub directory started with Text. in the %ow_htmldir%/images/iconsets/,
eg: Text.MyLang
ps: %ow_htmldir% is the dir where openwebmail could find its html objects,
it is defined in openwebmail.conf
2. copy %ow_htmldir%/images/iconsets/Text.English/icontext to Text.MyLnag/icontext
3. modify the Text.MyLang/icontext for your language

ps: If your are going to make Cool3D iconset for your language with Photoshop,
you may start with the psd file created by Jan Bilik <jan.AT.bilik.org>,
it could save some of your time. The psd file is available at
http://openwebmail.org/openwebmail/contrib/Cool3D.iconset.Photoshop.template.zip

ps: If you wish the your new iconset to be included in the next release of
openwebmail, please submit it to openwebmail.AT.turtle.ee.ncku.edu.tw

TEST
-----
1. chdir to openwebmail cgi dir (eg: /usr/local/www/cgi-bin/openwebmail)
and check the owner, group and permission of the following files

~/openwebmail*.pl - owner=root, group=mail, mode=4755
~/vacation.pl - owner=root, group=mail, mode=0755
~/etc - owner=root, group=mail, mode=755
~/etc/sessions - owner=root, group=mail, mode=771
~/etc/users - owner=root, group=mail, mode=771

/var/log/openwebmail.log - owner=root, group=mail, mode=660

2. test your webmail with http://your_server/cgi-bin/openwebmail/openwebmail.pl

If there is any problem, please check the faq.txt.
The latest version of FAQ will be available at
http://openwebmail.org/openwebmail/download/doc/faq.txt

PERSISTENT RUNNING through SpeedyCGI
------------------------------------
SpeedyCGI: http://www.daemoninc.com/SpeedyCGI/

"SpeedyCGI is a way to run perl scripts persistently, which can make
them run much more quickly." - Sam Horrocks.

Openwebmail can get almost 5x to 10x speedup when running with SpeedyCGI.
You can get a quite reactive openwebmail systems on a very old P133 machine :)

Note: Don't try to fly before you can walk...
Please do this speedup modification only after
your openwebmail is working with regular suidperl

1. install SpeedyCGI

get the latest SpeedyCGI source from
http://sourceforge.net/project/showfiles.php?group_id=2208
http://daemoninc.com/SpeedyCGI/CGI-SpeedyCGI-2.22.tar.gz

cd /tmp
tar -zxvf path_to_source/CGI-SpeedyCGI-2.22.tar.gz
cd CGI-SpeedyCGI-2.22
perl Makefile.PL (ans 'no' with the default)

then edit speedy/Makefile
and add " -DIAMSUID" to the end of the line of "DEFINE = "

make
make install
(If you encounter error complaining about install mod_speedy,
that is okay, you can safely ignore it.)

2. set speedy to setuid root

Find the speedy binary according to the messages in previous step,
it is possible-ly at /usr/bin/speedy or /usr/local/bin/speedy.

Assume it is installed in /usr/bin/speedy

cp /usr/bin/speedy /usr/bin/speedy_suidperl
chmod 4555 /usr/bin/speedy_suidperl

3. modify openwebmail for speedy

The code of openwebmail has already been modified to work with SpeedyCGI,
so all you have to do is to
replace the first line of all cgi-bin/openwebmail/openwebmail*pl
from
#!/usr/bin/suidperl -T
to
#!/usr/bin/speedy_suidperl -T -- -T/tmp/speedy

The first -T option (before --) is for perl interpreter.
The second -T/tmp/speedy option is for SpeedyCGI system,
which means the prefix of temporary files used by SpeedyCGI.

ps: You will see a lot of /tmp/speedy.number files if your system is
quite busy, so you may change this to value like /var/run/speedy

4. test you openwebmail for the speedup.

5. If you are installing openwebmail on a low end machine, then you may
wish to eliminate the firsttime startup delay of the scripts for the user.
You may use the preload.pl, it acts as a http client to start
openwebmail on the web server automatically.

a. through web interface
http://your_server/cgi-bin/openwebmail/preload.pl
Please refer to preload.pl for default password and how to change it.

b. through command line or you can put the following line in crontab
to preload the most frequently used scripts into mempry

0 * * * */usr/local/www/cgi-bin/openwebmail/preload.pl -q openwebmail.pl openwebmail-main.pl openwebmail-read.pl

If your machine has a lot of memory, you may choose to preload all
openwebmail scripts

0 * * * */usr/local/www/cgi-bin/openwebmail/preload.pl -q --all

6. Need more speedup?

Yes, you can try to install the mod_speedycgi to your Apache,
but you may need to recompile Apache to make it allow using root as euid
Please refer to README in SpeedyCGI source tar ball..

Another approach for speedup is to use some httpd that handles muliples
connections with only one process, eg: http://www.acme.com/software/thttpd/,
instead of the apache web server.

Please refer to doc/thttpd.txt for some installation tips.

ps: Kevin L. Ellis (kevin.AT.bluelavalamp.net) has written a tutorial
and benchmark for OWM + SpeedyCGI.
It is available at http://www.bluelavalamp.net/owmspeedycgi/

7. Compatibility with perl 5.8.4

The latest perl 5.8.4 does more strict check for suid scripts,
and the following two may cause incompatibility for some users

a. the name of the perl interpreter must has string 'perl'

We used suggest 'speedy_suid' as the name of suid speedy perl interpreter,
but we would like to suggest 'speedy_suidperl' as the name of speedy perl
interpreter now.

b. the parameter passed in the first line of the script must be the same
as the one the perl interpreter get.

This restirction stop us from using the following line in the script

#!/usr/bin/speedy_suidperl -T -- -T/tmp/speedy

All we can use is

#!/usr/bin/speedy_suidperl

In other words, we can't use "-- -parameter_for_speedy" to pass parameter
to speedycgi itself

ps: If you really need to change the tmpbase for SpeedyCGI, you may apply the
patch in cgi-bin/openwebmail/misc/patches/speedycgi.tmpbase.patch to the
SpeedyCGi 2.22 source, it changes tmpbase from /tmp/speedy to /var/run/speedy

HTTP COMPRESSION
----------------
To make this feature work, you have to install the Compress-Zlib-1.33.tar.gz.
HTTP Compression is very useful for users with slow connection to the
openwebmail server (eg: dialup user, PDA user).

Note: There are some compatibility issues for HTTP compression

1. Some proxy servers only support HTTP compression via HTTP 1.1,
the user have to enable the use of HTTP1.1 for proxy in their browser
2. Some proxy servers don't support HTTP compression at all,
the user have to list the webmail server as directly connected in
the advanced proxy setting in their browser
3. Some browsers have problems when using HTTP compression with SSL,
4. Some browsers claim to support HTTP compression but actually not.

The login screen has a checkbox for HTTP compression.
So in case there is any problem, the user can relogin with checkbox unchecked.

INTEGRATION WITH HTML PAGES
---------------------------
A small script has been made to let static html page display the
user mail/calendar status dynamically.
All you need to do is to put the following text in html source code.

<table cellspacing=0 cellpadding=0><tr><td>
<script language="JavaScript"
src="http://you_server_domainname/cgi-bin/openwebmail/userstat.pl">
</script>
</td></tr></table>

or

<table cellspacing=0 cellpadding=0><tr><td>
<script language="JavaScript"
src="http://you_server_domainname/cgi-bin/openwebmail/userstat.pl?playsound=1">
</script>
</td></tr></table>

If the user has ever logined openwebmail successfully,
then his mail/calendar ststus would be displayed in this html page
as an link to the openwebmail login page.

TODO
----
Features that we would like to implement first...

1. web bookmark
2. PGP/GNUPG integration
3. shared folder/calendar

Features that people may also be interested

1. maildir support
2. online people sign in
3. log analyzer

Jan/06/2005

openwebmail.AT.turtle.ee.ncku.edu.tw