WebMail is an ACS solution to allow users to check their mail via a web browser.
Here we are going to check and see which of the following items we need to download.
You must have Oracle 8.1.6, Intermedia, and ACS 4.0.1 or higher installed to use WebMail. It is also recommended that you install the acs-reference and acs-lang packages in order to allow Webmail to handle servers and clients operating in different timezones (if you do not install this, Webmail will display all times using the timezone that Oracle is running in). Please make sure that these items are properly installed before proceeding.
We will check to see if qmail is running.
$ ps -ef | grep qmail
qmails 593 1 0 16:36 ? 00:00:00 qmail-send
qmaill 604 593 0 16:36 ? 00:00:00 splogger qmail
root 605 593 0 16:36 ? 00:00:00 qmail-lspawn ./Mailbox
qmailr 606 593 0 16:36 ? 00:00:00 qmail-rspawn
qmailq 607 593 0 16:36 ? 00:00:00 qmail-clean
root 1256 1241 0 18:47 pts/0 00:00:00 grep qmail
$
This output means that qmail is installed and running. If you have problems with your qmail install please consult Appendix A: Troubleshooting any further help can be found at www.qmail.org.
We will check to see if java is installed.
$ which jar
/usr/local/java/bin/jar
$
You should have output similar to this meaning that you have java installed. And that you have jar which is the needed utility.
Everything you download here should be stored in the /tmp directory of your machine. This is not required but the rest of the document will reference the files as if they are in the temp directory. To complete this install, you will need access to a user in the dba group and root.
Qmail: Qmail is the mail delivery tool we will use to send a recieve mail from your web server. This should replace sendmail.
Java Development SDK: This is used for the jar utility. Generally java is also a good idea to have installed on your system.
To install the java portion of webmail you need to have the JavaMail library from http://java.sun.com/products/javamail/ and the JavaBeans Activation Framework from http://java.sun.com/beans/glasgow/jaf.html.
The following are instructions to modify the qmail install to be compatible with WebMail. Qmail should already be installed and running for this step. If not, follow instructions from qmail.org or ask your systems administrator. The instructions are for a default installation. If you need to modify the default settings, consult Appendix C.
There is a script to make this task easier. However, this script was written on a Sun server and is not gauranteed to work correctly on your particular flavor of UNIX. You should review its contents to verify that it will work properly for your particular machine and configuration. The script is at /webmail/scripts/wm-qmail-setup. It must be run as root and automates all the steps outlined below in this section. After running the script, proceed to Installing the package.
If you choose not to run the script, please follow the directions below to configure qmail for Webmail.
You must know what domain name you are going to use for your email e.g. here.there.com. You must then add your domain name to the rcpthosts file. This will tell qmail to accept mail for your domain. This file might or might not exist. If it doesn't exist create one. Note that you should use the home directory of AOL Server if it is not /home/aol32 wherever appropriate.
$ su
# cd /var/qmail/control
# vi rcpthosts; on a new line simply add your domain name:
here.there.com
# exit
$
Create an alias directory and make sure it can be written to by the nsadmin user.
$ su
# mkdirhier /home/aol32/servers/yourservername/qmail/alias
# chown -R nsadmin:web /home/aol32/servers/yourservername/qmail
Add the following line to /var/qmail/control/virtualdomains. This file may or may not exist if it does not exist just create it.
$ su
# cd /var/qmail/control
# vi virtualdomains; add a line like this:
here.there.com:webmail-there
# exit
$
Now we will decompose the string: here.there.com:webmail-there
here.there.com : This is the hostname that resolves to the webserver you are on. This is also the second half of your email address *@here.there.com.
webmail-there : This is prepended to the email address. So, mail sent to foo@here.there.com will be delivered internally by qmail as webmail-there-foo@here.there.com. This is so we can tell qmail to deliver the messages to Webmail instead of to the usual maildirs in each users home directory. In this case, the string "webmail" will be the qmail "account" which handles the mail for qmail, and "there" will be an identifier for Webmail associated with the here.there.com domain.
Run the following to find the user id and the group id of Oracle:
$ su
# su - oracle
$ id
uid=101(oracle) gid=102(oinstall)
$ exit
# exit
$
Insert a line into users/assign. This file might or might not exist if it doesn't exist create one.
$ su
# cd /var/qmail/users
# vi assign; add a line like this:
+webmail-:oracle:101:102:/home/aol32/servers/yourservername/qmail/alias:-::
.
# exit
$
Make sure this file is ended by a line consisting of a single dot
(.).
Now we will decompose the string: +webmail-:oracle:101:102:/home/aol32/servers/yourservername/qmail/alias
+webmail- : This is the name of the account that is going to handle all of the mail that comes in for webmail. WebMail reads all the mail as it comes into this account and figures out which user it is meant for and forwards it on to them.
oracle : This is the user that has permission to read the mail and shove it into the database.
101 : This is the user id for oracle
102 : This is the group id for oinstall
/home/aol32/servers/yourservername/qmail/alias: This is the alias directory which qmail will search when it delivers mail. Webmail will insert user alias files here.
Choose a queue directory for deliveries to the webmail user. This directory must not be shared with any other virtual server running on the same machine; /home/aol32/servers/yourservername/qmail/queue should be a safe choice. Create the directory and make sure it is writable and readable by the oracle Unix account (or whatever user Oracle runs at):
$ su
# /var/qmail/bin/maildirmake /home/aol32/servers/yourservername/qmail/queue
# chown -R oracle /home/aol32/servers/yourservername/qmail/queue
Now restart qmail. Run
# /var/qmail/bin/qmail-newu
# ps -ef | grep qmail
find the "qmail-send" PID
# kill -HUP qmail-send PID
First, you will have to obtain a copy of the Webmail package. Then use the APM to install and enable the package. When given the option, do not install the MessageParser.sqlj and MessageComposer.sqlj files. We will install these by hand later. Do install the webmail-create.sql file though.
Next you must create an instance of Webmail. Go to the site-map and make a new sub-folder under / called webmail (you may choose a different mount point if you like). Click new application under this new webmail folder and select the webmail package and give it a name. Then set the following parameters:
AliasDirectory=/home/aol32/servers/yourservername/qmail/alias/
QueueDirectory=/home/aol32/servers/yourservername/qmail/queue/
You may also choose different names for the four default mailboxes (INBOX, SENT, DRAFTS, and TRASH) if you prefer, by editing the appropriate parameters. The parameter ShowMailboxInfo should be set to "t" if you want to display the number of unread/total messages in each mailbox on the side nav-bar ("f" if not; this is both a UI and a performance consideration).
To allow for proper display of dates accross timezones, make sure you have installed the acs-lang package and set the system timezone to the timezone which Oracle is running in. The timezones of the clients are individually set in the preferences section of the Webmail UI.
After setting these parameters, restart your aolserver so they can be read in upon startup.
If you do not already have the JavaMail package and the JavaBeans Activation Framework already loaded into Oracle, you will have to do so now.
There is a script to make this easier at /webmail/scripts/wm-java-setup. It should be run from the /tmp directory, and the zipped JavaMail and JAF jar files should be placed in the /tmp directory before running the script. After the script has completed succesfully, proceed to Testing the system.
Alternatively, you may do it by hand:
This loads the JavaBeans Activation Framework:
$ cd /tmp
$ unzip jaf1_0_1.zip
$ unzip javamail1_1_3.zip
$ cd jaf-1.0.1
$ jar xvf activation.jar
$ rm activation.jar
$ jar cf0M activation.jar META-INF javax com
$ loadjava -user dbuser/dbuserpasswd -resolve -verbose activation.jar
Don't worry if you get a verification warning, as long as there are no errors.
This loads the JavaMail Program
$ cd ../javamail-1.1.3
$ jar xvf mail.jar
--(if you get a could not create directory error, just run the command again, it should go away)
$ rm mail.jar
$ jar cf0M mail.jar META-INF javax com
$ loadjava -user dbuser/dbuserpasswd -resolve -verbose mail.jar
Now we will go into the webmail directory and load the java packages associated with it.
$ cd /web/yourservicename/packages/webmail/java
$ loadjava -user dbuser/dbpasswd -resolve -verbose BlobDataSource.java ClobDataSource.java StringBufDataSource.java MessageParser.sqlj MessageComposer.sqlj
The loader will probably complain about some errors. Don't worry about it
because they're actually just a bunch of warnings. As long as the loader does not
say ORA-29535: source requires recompilation you are okay.
Now load up the page for webmail/admin. Register your domain with the webmail system by using the administration pages, with (again, just for this example) "there" as the short name and "here.there.com" as the domain name. These parameters must match those you set up in the qmail control files. In particular, the domain names must match, and the short name must match the second string you entered in the virtualdomains file. In this case, we entered "here.there.com:webmail-there", so we choose "there" as the short name.
You then have to add a user to the domain and give that person an email address. While you're at it, create an email account for the admin of this domain, and click the choose admin link to assign that person as the admin for the domain. This person will receive any undeliverable mail in a reserved mailbox called SYSTEM. If you do not assign an admin, bounced mail will cause a parse error and remain in the queue directory.
To test the system, go to the webmail user pages as the user whose account you created, and send an email to yourself. Wait a minute and then click check mail to see if it has arrived. If that works, try sending and receiving from an external address.
Mail is not getting delivered.
First check that qmail is delivering mail properly to your queue. You may do this by viewing the qmail log at /var/log/syslog/ to see what qmail is doing with the mail. If there are no errors there, use root access to view the contents of the queue:
$ su
# ls /home/aol32/servers/yourservername/qmail/queue/new
If you don't see any messages (and qmail says it delivered them succesfully to your webmail address), qmail is not delivering mail to the right queue. Manually check the alias files in the qmail directory:
$ su
# ls -a /home/aol32/servers/yourservername/qmail/alias
.qmail-there-foo (this is user foo's alias)
# cat .qmail-there-foo
/home/aol32/servers/yourservername/qmail/queue/
If this does not point to the right qmail queue directory, you have not correctly configured the QueueDirectory parameter in Webmail. Change the QueueDirectory parameter to point to /home/aol32/servers/yourservername/qmail/queue/, delete the user "foo" and then recreate his account. If the file .qmail-there-foo is not there, you need to set the AliasDirectory parameter to point to /home/aol32/servers/yourservername/qmail/alias/ and delete and recreate the user.
If mail is showing up in the correct queue directory, try processing the queue manually:
SQL> execute wm_process_queue('/home/aol32/servers/yourservername/qmail/queue/new');
If the command fails and the error message says something like
"file permission not granted", then go check
/home/aol32/servers/yourservername/qmail and
/home/aol32/servers/yourservername/qmail/new. Make sure both
of them have "oracle" as the owner. Another possible reason is that
Oracle database user used by AOLServer has not been granted java
execution privilege. Grant it the appropriate pemission, that
should fix the problem.You may also check that messages were actually inserted into Oracle by looking at the wm_messages table. It is possible that these messages were inserted but not mapped to the user, in which case, they will show up in the admin's SYSTEM mailbox. The main reason for this happening is if the short name which you set up in the admin page does not match the entry in /var/qmail/control/virtualdomains. Fix this and then try resending mail.
Once the domain has been set up, you can start adding email accounts. An email account is tied to an ACS user; Email accounts can be assigned to users by using the administration pages.
When an email account is added, a file is created automatically in the alias directory of the form ".qmail-[short domain name]-username" (e.g., ".qmail-wm-jsc") that contains one line with the full path to the queue directory (/home/aol32/servers/yourservername/qmail/queue/). This file specifies that mail sent to "webmail-there-foo@here.there.com" be delivered to the maildir directory that we have set up. All email to be handled by the webmail system ends up in the same place (/home/aol32/servers/yourservername/qmail/queue/new). The system uses the RFC822 Delivered-To header to distinguish who it should be displayed to. The redirection through the .qmail alias files is done so that only email sent to valid accounts will be received. Email sent to an address that does not have a .qmail file set up for it will bounce normally.
Once every minute, Oracle polls the new directory of the maildir queue and picks up any mail that has been delivered. Using the JavaMail library running inside Oracle, it stores and parses the message, and saves off various pieces of information (parsed headers, attachments, etc.; see the data model).
Migration Issues
I have not written a complete migration script for updating old Webmail installations to the new data model. There are a few useful functions included in the file /webmail/scripts/webmail-migrate.sql. Feel free to contact Erik Bielefeldt if you need advice regarding migration.
Performance Issues
The original Webmail was a little bit infamous for being a slug when many users were on at once. Whether or not it deserved that reputation, I have sought to improve the data model, simplify overly complex queries, and tune things to run reasonably well (see the Webmail Design Document for details).
Here are the results of my load testing:
environment:
Sparc Ultra 10 333MHz processor
1 GB RAM
Oracle 8.1.7
20,000 rows in the users table
80,000 mailboxes
137,000 messages
1,455,000 headers
1,900 attachments
results:
I did not test the search functions, as the efficiency of the query varies highly upon the particular user's search. The following results are biased towards heavy use of the index and message pages, with some folder-index, preferences, index-view, and index-search pages thrown in. I tested the sending of messages seperately, but obtained similar performance to the following results.
Capable of sustaining 3 hits/sec. up to 100 concurrent requests
Longest query takes .4 seconds.
Transfer rates of 30 Kb/s (I.e. 30Kb of data served per second by Webmail)
I was a little disappointed by these results, but after spending several days tuning this was the best that I could come up with. As I expected, the index view was the costliest to produce, and even with caching of the message ids it was quite slow. However, I do not know of a reasonable way to speed it up.
It is possible to choose different alias and queue directories in the qmail setup. To choose a different alias directory, simply follow the installation instructions above, but substitute the desired directory for /home/aol32/servers/yourservername/qmail/alias. The queue directory may also be moved freely. Remember to update the AliasDirectory and QueueDirectory parameters.
Webmail has been successfully used on a server cluster (iluvcamp has used 6 servers for over 100,000 users). A couple things to note: You should choose one server to handle all incoming mail and the processing of the queue by Oracle (presumably the machine the database is running on). All of your AolServer instances may serve Webmail pages, however, you must place the alias directory in a directory which is commonly accessible by all your servers. Generally, this will not be under /home/aol32. A good bet would be under your /web/servername/ directory. If you fail to do this, each server will end up having a different set of aliases on it (and your mail will start bouncing).