1. Contents
2. What is WebMail
3. Installation
4. Configuration
5. User Authentication
6. Usage
7. Different Languages, Translating WebMail
8. Notes
9. SSL Support (standalone installation)
10. JDK Installation And Other Java Issues
11. License
12. Credits

WebMail is a server application that allows ISPs to provide a WWW interface for each user to his mailbox(es) (similar to the programs YahooMail or HotMail use). WebMail should scale well enough to support large userbases and should be easy enough to be used in a home LAN.

Features include:

• Gives a user full access to his/her IMAP mailbox through a simple-to-use WWW interface
• Supports multiple folders on multiple hosts, depending on mail protocol used (IMAP supports different folders on the same host, POP doesn't)
• 100% HTML 3.2/4.0 output, no Javascript, no Java on the Client side
• supports multiple languages, configurable for each user
• Standalone HTTP-server completely written in Java
• Improved session management keeps mail connections alive
• Improved speed compared to CGI scripts (about factor 5-10, depending on usage)
• Usage of JavaMail-API ensures compatibility to many mailstandards ("officially" supported and tested: IMAPv4)
• Open Source distribution allows easy customization
• webbased administration interface
• support for multiple virtual user domains
• Easily add new features through the WebMail modular plugin concept (support for dependencies, hooking into URLs, etc)

Who should use WebMail:
WebMail's primary goal is to provide ISPs, companies and universities with a simple and zero-cost solution to give WWW mailaccess to their users.
Users can read and write their email while they are sitting in an Internet-Cafe, at expositions, etc without having to carry their PC around.
It is not intended as a replacement for the different personal email clients, but as a supplement for an existing mail solution.
The secondary goal is to unify a user's different email accounts under one interface which is easily accomplished using WebMails folder capability.

1. Introduction

There are two different ways to install WebMail, the standalone installation and the Java Servlet installation. Which one you should choose depends on what you plan to do with WebMail:

• a standalone server is much easier to install and will allow you to run WebMail almost immediately without much configuration. This can be used if you want to evaluate WebMail's capabilities or develop new features/bugfixes. It also makes sense to use this for small to medium installations if you don't want to set up a Java Servlet capable webserver
• a Java Servlet installation is recommended for production use since it allows greater performance and scalability. You will need to set up a webserver that is capable of serving Java Servlets, e.g. Apache. I can't give too detailed instructions here since this depends in large parts on your webserver, but I include a sample Apache configuration (the parts relevant to WebMail) in the distribution

There are also several ways to store data:

• You could use the simple file-based storage which stores configuration data in XML documents and is very easy to set up, but perhaps not very fast.
• The performance method however is to store the configuration in a SQL database. Currently only MySQL is supported, but it is easy to implement storage on Oracle or PostgreSQL. Using a SQL database for storage has several advantages which I will describe below.

2. Standalone Server

1. Requirements

To run WebMail properly on your server, you need to have the following software installed:

• Java 1.1.6 or better - see the Java Section on Java issues
• About 20 megs of RAM (minimum) plus additional 80 megs on high load servers (these are just recommendations, WebMail will run on any Java-capable server; if you have less than 32 MB RAM, you should try to adjust the settings in the startup script called webmail.sh/webmail.bat)
• Using a JIT ("just in time compiler") is greatly recommended! The Solaris and Windows JDKs from Sun use a JIT by default (sunwjit). On Linux, the Sun/Blackdown JDK uses a JDK, however it is not very fast, so you could profit from using a JIT like tya. The IBM Linux JDK 1.1.8 comes with a very fast JIT (actually the fastest Java platform available).

WebMail has been successfully tested on:

• Solaris x86 and SPARC, JDK 1.1.6 and JDK 1.2
• Linux x86 (tested: Debian and SuSE), IBM JDK 1.1.8 and Sun/Inprise JDK 1.2.2 (RC3)
• FreeBSD 3.4 x86, JDK 1.1.8
• Windows NT/2000 (did not do the tests myself)

WebMail will make profit of multiprocessor machines (e.g. Sun Enterprise 450) as it is multithreaded in large parts.

2. Binary Installation

1. Change to the prefix where you want to install WebMail (e.g. /usr/local)
2. Unpack the tar.gz or zip archive: tar xzvf webmail-0.7.0.tar.gz
3. Change to webmail/bin
4. Edit the file webmail.sh if necessary
5. Start WebMail using the provided script ./webmail.sh >> stdout.log 2>&1 &
6. See Configuration for further steps to take.

3. Source Installation

Additional requirements:

• GNU make (Only GNU make will work)
• zip/unzip

To install the source distribution of WebMail you will have to take the following steps:

1. Change to the src/ subdirectory
2. Set the CLASSPATH environment variable to your classes.zip (JDK 1.1) or rt.jar (JDK 1.2) archives (on Solaris: /usr/java1.1/lib/classes.zip for JDK 1.1 and /usr/java1.2/jre/lib/rt.jar for JDK 1.2)
3. Have a look at the makefile and edit it if necessary
4. Call "make" to compile the classfiles and create the archives (containing classfiles, language dependent HTML templates and images).
   You will find the compiled archives in the lib/ directory when the compilation was successful.
5. See steps 3 to 5 from binary installation then

3. Servlet Installation

Running WebMail as a Servlet has several advantages over the standalone installation (and also some disadvantages):

• you can run (and integrate) WebMail on an already-running webserver
• you can make use of the webserver's fast connection handling and HTTP parsing routines
• you can e.g. use Apache's load-balancing feature to run WebMail on a whole server cluster for large installation.
• installation is however much more complicated (and so it is definately not suited for webserver newbies)

Before trying this, please ensure that you are familiar with your Webserver's Servlet configuration. I provided a sample zone file for Apache, though (but you will have to do many modifications concerning the initArgs at the end of the file).

To make use of this feature you have to:

1. Configure your webserver to run Java Servlets
2. Add the net.wastl.webmail.servlet.WebMailServlet servlet to your servlet repository (and add all the jar files provided here to the classpath)
3. Add the necessary initArgs to the servlet configuration for WebMail. These are:

   webmail.plugin.path	Path to the plugin directory
   webmail.auth.path	Path to the authenticator directory
   webmail.data.path	Path were data will be stored (this has to be writeable by the process owner of the webserver)
   webmail.lib.path	Path to WebMail libraries
   webmail.template.path	Path to language dependent template files
   webmail.storage	Set this to net.wastl.webmail.storage.simple.SimpleStorage for the simple storage and to net.wastl.webmail.storage.mysql.MySQLStorage for the MySQL based storage

4. Ensure that all webmail directories are readable for the WWW-user and that the data directory is writeable by the WWW user.

To simplify the above, I provided an Apache JServ zone file called webmail-servlet.properties in the root directory. You will just have to i modify this file to fit your configuration (mainly the initArgs at the bottom of the file), add a new zone to your Apache configuration and then call webmail with http://www.yourdomain.top/[mountpoint]/webmail

Please note that I haven't tested this with a different server than Apache and that it is still experimental.

4. Storage Methods

By default, WebMail uses a so-called SimpleStorage to store user and system configurations, i.e. the data is stored in separate (XML-) files. This is a very easy but not very efficient method.

A more performant method is WebMail's MySQL storage where the data is stored in a MySQL database instead. This has all the advantages of a standardized database management system plus a smaller memory footprint (per session) since data doesn't need to be cached.

1. Why and when use WebMail with MySQL

Using MySQL to store the WebMail data has several advantages, e.g.:

• User configuration is compatible over different WebMail versions
• DBMS allow easy backup and management
• DBMS might be faster than file access
• You can change the WebMail configuration with any tool you like (you can edit users even while WebMail is running, changes are active immediately)
• you could write simple PHP3 or Perl scripts that perform some kind of user creation, perhaps asking the user for extra information like address etc and storing that separately

Clearly, this also has some disadvantages:

• You will have to do some extra configuration work to set up MySQL as well as WebMail before you can start
• DBMS also might be slower than file access, depending on configuration

When you should consider using MySQL:

• You have a large userbase
• You are running MySQL commercially
• You already have a (My)SQL database that stores user data (e.g. addresses, passwords, ...) and want to give your users WebMail access
• You use WebMail on a load balancing Apache server as servlet. Thus you can set up an additional MySQL server that stores all the data.
• etc.

2. Preparing MySQL

This document assumes that you already have a running MySQL server. If you don't, please set up MySQL and consult the documents provided with it.

1. Set up a user/password for webmail that has access from the host WebMail will be running on (don't forget to FLUSH PRIVILEGES after that). Give it all privileges (i.e. set everything to 'Y'=). You may change that to access only the "webmail"-database after the database is set up.
2. In the WebMail contrib directory, have a look at the file mysql_scheme.sql. This file contains the DDL statements for creating a database called "webmail" and creating the necessary tables and relations. You might want to change the database name to something different than "webmail"
3. Execute mysql -u [webmailuser] -p < mysql_scheme.sql. Please substitute [webmailuser] with the user you configured in step 1. This will first ask you for the password that you gave the webmail user in step 1 and then execute the DDL statements.

MySQL is now set up to work with WebMail.

3. Setting up WebMail for use with MySQL

Setting up WebMail is quite simple. All changes will be done in the startup script webmail.sh (or webmail.bat under Windows or initArgs in case of a servlet installation) in the bin/ directory. The corresponding servlet configuration options are given in "(" and ")".

1. Change the value of the STORAGE variable (or webmail.storage initArg) to net.wastl.webmail.storage.mysql.MySQLStorage
2. Change the variables SQL_LOGIN and SQL_PASS (or webmail.storage.sqllogin and webmail.storage.sqlpass initArgs) to the values you configured in section 4, step 1
3. Change the SQL_HOST variable (or the webmail.storage.sqlhost initArg) to the DNS name of the MySQL server (most likely localhost is just fine if you only have a single server)
4. Possibly change the value of SQL_DB (or webmail.storage.sqldb) to another database name (whatever you configured in section 4, step 2)

Now you should be able to start WebMail standalone with "./webmail.sh".

4. Further suggestions

If you are also running Apache with PHP3 on the same (or a different) host:

• Consider fetching "phpMyAdmin" (see freshmeat.net). It gives you a webbased interface for changing all kinds of MySQL data, including the WebMail configuration
• If you want to provide some logon scheme for new users to logon, you can write that by yourself using PHP3 without too much trouble.

Also, you can write your own set of administration tools in Perl (or other languages).

5. WebMail SQL Scheme

The WebMail SQL scheme is not yet well documented, but not too difficult to understand. It consists of the relations "users2userdata" and "users2mailhosts" that connect the data tables as well as the data tables "users", "userdata" and "mailhosts" containing the real data.

WebMail has an administration interface which allows you to perform several runtime administration tasks, including:

• Changing all configuration settings
• Shutting down the server properly
• Adding, deleting or editing WebMail virtual domains
• Adding, deleting or editing WebMail users
• Getting status information

1. WebMail Administrator Plugin

1. Connecting

You can connect to the administration interface with your browser by simply entering the URL http(s)://webmail_server:port/admin in the address field of your browser. (set http/https and replace webmail_server and port with the correct values; port is usually port 6789 after the first start on a standalone server; on a servlet installation you will very likely have to add the WebMail mountpoint before the /admin).

You'll be presented the administrator's login screen then. Enter the password there (on first startup the password is "Secret") and click the login button. You should see the system settings form then.

2. System Settings

The first page gives you a list of WebMail system variables and their values. You can change any variables you like (there is a short description for each of them) and then hit the submit button on the bottom of the page.

There are basically 4 kinds of input fields (although you will probably only recognize 2 on first look):

• simple text input fields
• drop down selects
• integer input fields (look like text input fields)
• password input fields (look like text input fields and show the encrypted password!)

All of these fields will check whether the value entered is (more or less) correct if you submit the form.

To shutdown or restart the WebMail server, enter the time in seconds until the action will be performed and hit the appropriate button ("SHUTDOWN" or "REBOOT"). ATTENTION: You will not get anything like an answer after you do this (since you are shutting down the server this is quite difficult) and you will not be asked whether you really want to do this! Most likely you will get a "connection timed out" or "document contains no data" dialog.

3. WebMail Virtual Domain Support

Virtual Domains in WebMail are a quite new concept (thanks to Oswaldo E. Aguirre M. for the idea).

They basically provide the following features:

• users are associated to a domain (even if you only have one domain)
• each domain can have its own authentication host (if IMAP/POP authentication is used)
• the administrator of WebMail can impose certain restrictions on users of a WebMail domain. e.g. you can restrict the hosts where users may connect to here
• each domain has its own default host where the user's primary folder will be found
• the user's default email address will be set to "user@domain"

Naturally, with this concept you will need to have at least one domain even if you don't plan to use virtual domains really.

The WebMail virtual domain setup form is quite simple and self explanatory, I think. There is one column where you have to enter the domain name, one where you have to enter this domain's default host (user's primary folder host), one for the authenti- cation host (not necessarily the same as the default host), and some fields that control the restrictions for users of this domain. With the checkbox, you can turn on/off host restriction completely, in the allowed hosts column, you can enter a comma-separated list of domains/hosts where users may access IMAP folders (e.g. "wastl.net" would allow them to use "mail.wastl.net" and "pop.wastl.net" while setting it to "mail.wastl.net" would just allow "mail.wastl.net" (and certainly "imap.mail.watl.net") and so on (suffix is matched to say it simple)).

4. Editing Users

You can add, edit and delete users from the administration interface (Note that you don't have to create users before they may use WebMail since they get default settings when they first log on authenticating against IMAP, POP or Unix).

To create a user,

• enter the user name and the domain in the user field (in the form "user@domain")
• optionally change all the other fields from the default settings
• hit the create/edit button on the bottom of the page

To edit a user,

• select the user in the drop down menu OR enter the user name (with domain) in the short text field
• edit the user settings
• hit the create/edit button on the bottom of the page

To delete a user,

• select the user in the drop down menu OR enter the user name (with domain) in the short text field
• Hit the delete button

5. Viewing WebMail Status

Last but not least you can get an overview of currently active sessions with the "view sessions" link. You will get some status information there as well as the possibility to explicitly kill an active session (whatever maybe the reason). Please be careful however with this feature, as you are very likely to kill a session that is currently in use and its user will probably not be very happy about that. The sessions will expire after a configured time anyway.

The Administrator Interface is currently available in English only, but the templates are already prepared for translation The system's default language will then be used (determined by the LANG environment setting).

I hope the rest is quite self explanatory at the moment, but I'll add some documentation later.

2. File-Based Shutdown

You can initiate a WebMail shutdown when you create a file "shutdown" (or whatever you configured) in the data directory with only the admin password in it. This option can be disabled. It is useful in automatic system startup/shutdown.

WebMail supports extended user authentication. At the moment, the following authentication methods are supported:

• SIMPLE: Use WebMail's former authentication method. Password is only checked against the user's configuration. The user may change his password from within WebMail
• IMAP: Check login/password on a remote IMAP host. WebMail tries to login on a remote IMAP host with the given login and password.
  If login fails, WebMail doesn't allow access.
• POP: Same for a POP3 server
• UNIX: Check login/password using Unix's login facility. login/password are checked against the Unix passwd/shadow files.
  Note: WebMail must be run as user root to use Unix Authentication

Changing authentication method can be achieved using the Administration Interface and changing the "AUTH" variable. For IMAP authentication there is an extra configuration variable called "AUTHHOST".

1. General Usage

The WebMail daemon listens on whatever port you have configure. Just point your browser´s URL to http://yourhost:yourport/ and see the login screen.

A user will get the password he logs in with the first time. Passwords may be changed by the user in the options dialog. WebMail will try to establish a default connection to the configured default IMAP host with the user ID and password it was given, so it may be useful to use the same ID and password as on the IMAP host.

For further information, just click on the "?" at the navigation bar.

WebMail should also work with Proxy Servers and other Clients than Netscape Communicator.

2. Folders

WebMail supports the usage of different languages on a per user basis. Since v0.6.0 WebMail scans for available languages automatically and adds the corresponding locales to the user's setup dialog ("de" will add the locales "de_DE", "de_AT", "de_CH", ...).
To translate WebMail to a new language, please read the file "Translating" in the developers' documentation (source only).

1. WebMail Status

WebMail v0.7 is considered BETA, as not all features I want for a "1.0" are yet included.

Things I think of are:

• Different XSL stylesheets to convert the WebMail UI to other formats than HTML (perhaps WML for mobile phones)
• PGP for users using the Cryptix JCE. (http://www.cryptix.org)
• "Extras" like calendar and so on (will be realized as WebMail Plugins)

2. Changes

See the file "Changes" for a list of changes in the different WebMail releases.

Since WebMail 0.7.0, there is finally a free SSL implementation available for Java called ITI-SSL.

Installation is simple:

• Fetch the ITI-SSL library from the WebMail homepage for your platform (if there is no binary for your platform, please fetch the source code at the ITI-SSL homepage at http://www-sp.iti.informatik.tu-darmstadt.de/itissl/)
• Copy the library "libitissl.so" to the WebMail lib/ directory.
• Start WebMail and possibly enable the SSL support in the administration interface

However, SSL in WebMail has some drawbacks:

• only works with JDK >= 1.2 (:-( )
• is a native library it is no longer platform independent

If you compile ITI-SSL yourself, please ensure that you use openssl-0.9.4 for compilation because Netscape and IE won't work with WebMail SSL with prior versions.

1. What is Java

Java is a platform independent, object-oriented (OO) programming language. Java programs are compiled using the JDK Compiler (javac) or other compilers (e.g. IBM jikes). The resulting bytecode is optimized for the Java Virtual Machine (JVM) and still platform independent.
The JVM interpretes the previously compiled bytecode and translates it "on the fly" into platform dependent system calls. Therefore a JVM must exist for your platform in order to run Java programs.
You'll obviously recognize that Java is an interpreted language similar to Perl or Python. The most sigificant difference to the former two is that Java is precompiled.
So Java is a kind of compromise between purely interpreted languages and languages that are compiled to machine code which tries to combine the advantages of both (reliability and speed). As far as i know, this principle is derived from PROLOG.

2. Where to obtain Java for your platform

The main Java distribution site is http://java.sun.com.
You will get the "officially supported" platforms and lots of documentation and additions there.

Java distributions for the different platforms:

Solaris SPARC and x86	http://java.sun.com
Windows:	http://java.sun.com
Linux/x86:	http://www.ibm.com (recommended IBM JDK 1.1.8)
	http://www.blackdown.org (Blackdown port of JDK 1.2)
	http://java.sun.com (Sun and Inprise port of JDK 1.2)
Linux/PPC:	http://business.tyler.wm.edu/mklinux/
Linux/Alpha:	http://www.voicenet.com/~gatgul/JDK/java-alpha.html
Linux/SPARC:	http://tinukai.sesuadra.org/~jdk/
AIX:	http://www.ibm.com
Macintosh:	http://applejava.apple.com
OS/2:	http://www.ibm.com
FreeBSD:	http://www.freebsd.org/ports/lang.html

3. How to install Java properly

Use your system's standard facility to install the Java packages. Note that the Linux JDK most likely comes as "tar.gz" and not as .rpm or .deb, so you will have to manually install it using tar.

On Solaris, the JDK will install in /usr/java1.x/ by default. On Linux, I prefer installing the "tar.gz" in /usr/local and renaming the extracted path to "java1.x". Many distributions, however, will install Java in /usr/lib/java1.x or /usr/lib/jdkxxx.

Next, link all programs in the bin/ directory to somewhere in your path (e.g. /usr/local/bin) or alternativly add the bin/ directory to your PATH environment.

Last, set your CLASSPATH environment variable (e.g. in /etc/profile) to

• /path/to/java/lib/classes.zip with JDK 1.1.x
• /path/to/java/jre/lib/rt.jar with JDK 1.2

You should have a running system now. Test it by typing "java -version".

Special note for Linux users: There are problems with earlier versions of the libc6 (aka glibc). Please use glibc 2.1.2 or above to ensure a stable environment for WebMail.

4. Improving speed

To improve Java performance, you will most likely use an JIT (Just in time compiler) that compiles bytecode to native code on-the-fly (while executing the program). This especially improves speed for routines that are used frequently, as it is with WebMail. So I strongly recommend using a JIT for WebMail!

If you already have Java 1.2 (aka Java 2) or the IBM JDK 1.1.8 on Linux, you won't need to get a JIT as it already ships with one. If you still have Java 1.1, it depends on your platform.

• On Linux (Blackdown port) you will need to fetch an extra JIT. I recommend using TYA, but you can get a list at http://www.blackdown.org
• On Solaris, a JIT is already included in the Java 1.1 releases

I don't know what it's like for other platforms. You can always try whether you have a JIT or not by setting JAVA_COMPILER to "NONE" and testing whether that affects the execution speed of WebMail. If it is considerably slower, than you most likely already have a JIT.

5. Glossary

JDK	Java Depelopment Kit - what you need to compile programs
JRE	Java Runtime Environment - what you need to only run programs
JVM	Java Virtual Machine - bytecode interpreter
JIT	Just In Time Compiler - improves execution speed of the JVM

WebMail is (c)1998-2000 by Sebastian Schaffert, schaffer@informatik.uni-muenchen.de

WebMail is distributed under the terms of the GNU Lesser General Public License (LGPL). You can find a copy in the file COPYING.

The LGPL allows you, said in short, to add WebMail to other projects that are not covered by the GPL.

I give my credits to all who reported me bugs and made suggestions to improve WebMail.

Some, however, I want to mention explicitly:

• Andrew D. Fernandez, andrew@cryptonym.com, for contributing the RedHat packages and making some very good suggestions.
• Rafa Couto, rafa@citania.com, for doing the Spanish and Galician translations
• Homero Borgo, homero@apoyo.uson.mx, for testing WebMail under rough conditions and helping much to find bugs in the product.
• My girlfriend for her patience and the cool icons for WebMail 0.5 and 0.6
• Sacha Berger, bergers@informatik.uni-muenchen.de, for the new icons in later WebMail versions and some very interesting discussions about how to do things right.:-)

Sebastian Schaffert, schaffer@informatik.uni-muenchen.de