Installing WebMail ACS 3.3

WebMail is a homegrown solution to allow users to check their mail via a webpage. This install doc is for Linux. Not tested on Solaris.

Table of Contents

1. Pre-Installation Tasks
2. Acquiring Needed Items
3. Setting up Qmail
4. Loading the Data Model
5. Loading Java Classes
6. Acceptance Test
7. Appendix B: Trouble Shooting

Pre-Installation Tasks

Here we are going to check and see which of the following items we need to download.

1. You must have Oracle, Intermedia, ACS 3.3 or higher installed to use WebMail. If you don't have all of these items installed please go back to the beginning of the install docs at http://www.arsdigita.com/doc/install-guide/.

2. 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 B: Trouble Shooting any further help can be found at www.qmail.org.

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

Acquiring Needed Items

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 do this correctly you will need access to a user in the dba group and root.

1. Qmail: Qmail is the mail delivery tool we will use to send a recieve mail from your web server. This should replace sendmail.
2. Java Development SDK: This is used for the jar utility. Generally java is also a good idea to have installed on your system.
3. 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.

Setting up Qmail

1. You must know what domain name you are going to use for your email e.g. arsdigita.com. You must then add your domain name to the rcpthosts. This file might or might not exist if it doesn't exist create one.

   $ su
   #cd /var/qmail/control
   #vi rcpthosts (on a new line add your domain name)
   #exit
   $
   

2. Select a name for the email account that will handle all of the incoming webmail. This can be arbitrary, so we will just use "webmail" (if you want to use something else, you must edit the Java code). That line must then be inserted into assign. This file might or might not exist if it doesn't exist create one.

   Note that you should use /home/aol30 instead of /home/nsadmin wherever appropriate hereinafter if you are running AOL Server v3.0

   $ su
   #cd /var/qmail/users
   #vi assign (add a line like this +webmail-:oracle:101:102:/home/nsadmin/qmail/alias:-::)
   #exit
   $
   

   Now we will decompose the string.
   +webmail-:oracle:101:102:/home/nsadmin/qmail/alias
      1        2     3   4              5
   

   1. +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. Make sure this file is ended by a line consisting of a single dot (.).
   2. oracle : This is the user that has permission to read the mail and shove it into the database.
   3. 101 : This is the user id for oracle
   4. 102 : This is the group id for oinstall
   5. /home/nsadmin/qmail/alias : This is where you want to store the alias's for your users. For items 3 and 4 you can run this command to find the user id and the group id.

      $ su
      # su - oracle 
      $ id
      uid=101(oracle) gid=102(oinstall)
      $ exit
      # exit
      $
      

3. Make sure that the alias directory exists, and can be written to by the nsadmin user.

   $ su
   # mkdir /home/nsadmin/qmail/alias
   # chown -R nsadmin /home/nsadmin/qmail
   

   The location of this directory can be changed by setting the AliasDirectory Parameter in the webmail section of the ACS .ini file for this server. It is ok to share this directory with other virtual servers running on the same machine.
4. 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 webmail.arsdigita.com:webmail-wm)
   # exit
   $
   

   Now we will decompose the string. webmail.arsdigita.com:webmail-wm 1 2
   1. webmail.arsdigita.com : This is the hostname that resolves to the webserver you are on. This is also the second half of your email addresss *@webmail.arsdigita.com.
   2. webmail-wm : This is prepended to the email address. So, mail sent to "foo@webmail.arsdigita.com" will be delivered to the webmail user as "webmail-wm-foo@webmail.arsdigita.com".
5. 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/nsadmin/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
   # mkdir /home/nsadmin/servers/yourservername/qmail
   # /var/qmail/bin/maildirmake /home/nsadmin/servers/yourservername/qmail/queue
   # chown -R oracle /home/nsadmin/servers/yourservername/qmail
   

   Set the QueueDirectory parameter in the webmail section of the ACS .ini file for this server to the location of the queue directory. [ns/server/yourdomainname/acs/webmail] AliasDirectory=/home/nsadmin/qmail/alias/ ; if QueueDirectory is changed, change it in webmail.sql and MessageParsers.sqlj as well QueueDirectory=/home/nsadmin/servers/yourdomainname/qmail/queue/ 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).
6. Now restart qmail to make sure it is working. Run

        # /var/qmail/bin/qmail-newu
        

7. You also have to restart the qmail smtp server. Let's make sure it is running.

        $ telnet localhost 25
        

   If you connect that means you have a mail smtp server running. Now we have to make sure it is qmail and not sendmail. You also need to find out where the qmail smtp server is started. On linux it could be one of two things.

   1.      $ ps -ef | grep tcpserver
            cspears 19385 19379  0 11:53:01 pts/92   0:00 grep tcpserver
            qmaild 25212     1  0   Jun 20 ?        0:02 tcpserver -v -RH -x /var/qmail/etc/smtp.cdb -u 7791 -g 103 -c 200 0 25 qmail-sm
           $
           (You need to go to /etc/init.d/ and run this)
           # /etc/init.d/tcpserver stop
           # /etc/init.d/tcpserver start

   2. Look for a line like this smtp stream tcp nowait qmaild /usr/sbin/tcpd /var/qmail/bin/tcp-env /var/qmail/bin/qmail-smtpd. If you don't see this line you might want to ask your sysadmin if qmail smtp is install on your server.

           # vi /etc/inetd.conf
           # ps -ef | grep inetd
      root       450     1  0 Jun07 ?        00:00:00 inetd
      root     15030 14988  0 16:56 pts/6    00:00:00 grep inetd     
           # kill -HUP 450
           

      That will reset the smtp server with the changes.

Loading the data model

$ cd /web/yourservicename/www/doc/sql/
$ vi webmail.sql (go to line 237 and change /home/nsadmin/qmail/queue/new to your specified directory)
$ sqlplus dbuser/dbuserpasswd < webmail.sql

Loading in Java to Oracle

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 cf0 activation.jar META-INF javax com
$ rm -rf META-INF javax com
$ loadjava -user dbuser/dbuserpasswd -resolve -verbose activation.jar

This loads the JavaMail Program
$ cd ../javamail-1.1.3
$ jar xvf mail.jar; rm mail.jar
$ jar cf0 mail.jar META-INF javax com
$ rm -rf META-INF javax com 
$ loadjava -user dbuser/dbuserpasswd -resolve -verbose mail.jar.

If you are using Oracle 8.1.5, you will not be able to load the JAF and the JavaMail packages into a 
user's schema, even with JAVASYSPRIV. You must load them into the SYS schema:
 
loadjava -user internal/internalpasswd -synonym -resolve -verbose activation.jar
loadjava -user internal/internalpasswd -synonym -resolve -verbose mail.jar

(Note: loadjava takes about 5 minutes to install activation and 14 minutes for mail. You may get 
a verification warning attempting to resolve javax/activation/ActivationDataFlavor which you can 
ignore.) 

$ cd /web/yourservicename/www/webmail/java
$ loadjava -user dbuser/dbpasswd -resolve -verbose BlobDataSource.java ClobDataSource.java MessageParser.sqlj MessageComposer.sqlj

You will probably see something like "14 errors". Don't worry about it because it's actually a bunch of warnings.

Trouble Shooting

Make sure you create the PL/SQL bindings in the data model file and create the job which will poll the mail queue (if you decide to do so -- see next item).

In 8.1.5, add a resolver spec to the above loadjava statement:

-resolver "((* dbuser) (* public) (* -))"