1. Contents
2. What is JWebMail
3. Installation
4. Configuration
5. User Authentication
6. Usage
7. Different Languages, Translating JWebMail
8. Notes
9. License
10. Contributed Documentation
11. Credits

Top of section "Contents"

JWebMail is a web mail server. Web mail allows an organization to provide a WWW interface for each user to his mailbox(es). Unlike Yahoo Mail, Hotmail, and Gmail, JWebMail presents a web interface to traditional email accounts which you or somebody else provide. The target email account servers may be restricted by JWebMail.

By virtue of JWebMail being a pure Java appplication, it has excellent portability, scalability, and performance. We have designed JWebMail so that it works out-of-the-box for a home LAN setup by just dropping the .war file into your servlet container (which includes all modern application servers).

2.1. Use Cases

Common use-cases

• Serve JWebMail on the same host that your traditional email server runs on, to provide web access in addition to dedicated email client access.
• Run JWebMail to provide members Internet web access to their email accounts on an internal mail server.
• Run a single JWebMail server to allow for a single, unified interface to all of the email accounts for your users, whether the target email accounts are internal organizational accounts and/or external accounts.

Top of section "Use Cases"

2.2. Features

Features include:

• Product is independent of the target email account provider(s).
• 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)
• Supports SSL protocols imaps and pop3s.
• Sophisticated folder management system
• 100% HTML 3.2/4.0 output, no Java on the Client side
• Supports multiple languages, configurable for each user
• Flexible template system to personalize look and feel and write new language files using XML and XSL
• Runs as a web application in a Java servlet container
• Improved session management keeps mail connections alive
• Performance, scalability, and portability of a pure Java application
• Usage of JavaMail-API ensures compatibility to many mail standards
• Open Source distribution allows easy customization
• Web-based administration interface
• Support for multiple virtual user domains
• Easily add new features through the JWebMail modular plugin concept (support for dependencies, hooking into URLs, etc)
• Application/Data separation allows for redeployments and upgrades without losing any configuration or user data.

Top of section "Features"

Top of section "What is JWebMail"

3.1. Introduction

Top of section "Introduction"

3.2. Requirements

For running JWebMail you need the following software:

• A mailserver for sending (SMTP) and receiving (IMAP) mails; by default, JWebMail will use localhost for both
• A Java servlet container which supports the 2.4 servlet spec, and runs on a Java 1.5 or greater JVM (either JRE or JDK). Anything from a stripped down servlet-container like Tomcat, to a J2EE application server like JBoss or WebSphere will work.
• Your servlet container needs modern versions of the following libraries installed:
  • JavaMail API (typically mailapi-*.jar) You can download version 1.4.1 of the JavaMail API library here.
  • JavaMail SMTP provider (typically smtp-*.jar). You can download version 1.4.1 of the SMTP library here.
  • JAF/Java Activation Framework (not necessary if your servlet container uses Java 1.6, since Java 1.6 includes the activation framework). Java 1.5-users can download version 1.1.1 of JAF library here.

If you wish to build a custom app, or develop, you will also need a standalone Java JDK 1.5 or later, and Ant 1.7 or later, as described below. Any or no Java IDE will work.

Top of section "Requirements"

3.3. Installing

There are separate sections below, depending on whether you want to just run JWebMail, or to build it on the command-line or with an IDE.

3.3.1. Installing Application (binary install)

This is the preferred installation method if you just want to run JWebMail, and have no need to customize the application iteself.

This installation is very simple:

Install jwebmail.war as you would install any War file.

With Tomcat, the easiest way is to use the Manager webapp, which serves http://localhost:8080/manager/html by default. Log in and deploy the war using the Gui (you can see or add manager accounts in the file $CATALINA_BASE/config/tomcat-users.xml).

For every application server that I know of, if you have auto-deploy on (usually the default mode) you can become the app-server owner (the account under which the server process(es) run), and just copy the war file into the webapp landing directory. If you don't have access to that account, see your app server docs, because the war file permission requirements vary (if you have superuser privileges, you can always change the file to be owned by the app-server owner). Rest assured, your app server has several easy ways to deploy war files.

JWebMail is then available by visiting http://yourhost:PORT/jwebmail with a web browser.

Please don't forget to visit the administration interface first. You can access it by browsing http://yourhost:PORT/jwebmail/admin. Initial password is Secret.

Top of section "Installing Application (binary install)"

3.3.2. Build and Install from source

JWebMail is compiled by using the Ant build-system. You will need Ant version 1.7 or greater and Java JDK 1.5 or greater to build JWebMail.

You can obtain the JWebMail source code by extracing a source code distribution package, or by exporting or checking out our code from SourceForge. You can get our distro packages athttps://sourceforge.net/project/showfiles.php?group_id=2056. You can use any Subversion client to get our trunk code from https://jwebmail.svn.sourceforge.net/svnroot/jwebmail/trunk.

The following steps are required (for a quick-start):

1. Set your JAVA_HOME environment variable (to the directory where the JDK is installed)
2. Make sure that the bin directory of your Ant installation is in your search path. Run "ant -v" to verify.
3. You will need Internet access the first time you run the build, so that build process can download the needed third party libraries (automatically).
4. Just run 'ant' to build a war file in subdirectory dist. If you don't have an Ivy jar file in your CLASSPATH, the Ant command above will display the simple command that you can copy-and-paste to your command line to satisfy it.

   Note: An error message like ...doesn't support the nested "matches" element... means you need to upgrade Ant to 1.7 or later.

5. Deploy the file at dist/jwebmail.jar to your servlet container, as explained in the previous section. Alternatively, you set Ant property exploded.dir and deploy the exploded webapp to a live deployment directory. Since you are building software, we figure you are handy enough to figure this out without further instruction from us.

Run "ant -p" for further possible targets that may be used. To customize any Ant properties, create a standard Java properties file in this directory with name local.properties. Most developers will want to use the targets gen-guide and javadoc to build documentation. (They get written to the build/apidocs and doc subdirectories respectively).

Unless the version of the User's Guide you are reading is out-of-date, you probably won't need this, but... The gen-guide task requires the program "xsltproc". You have a few alternatives to access a User's Guide if you don't have xsltproc.

• Read it online at http://jwebmail.sourceforge.net/jwebmail-guide.html
• Use your own XSLT processor program to generate jwebmail-guide.html file from the guide.* artifacts in the doc-src directory.
• Download the desired version of the binary distribution of JWebMail. These include a pre-build User's Guide.

The build system uses Apache Ivy to fetch third party libraries. The configuration allows you to change the library repository location by editing local.properties and ivy-settings.xml. Seehttp://ant.apache.org/ivy/ for details about Apache Ivy.

Code contributors must read and follow the coding conventions listed in the conventions.txt file located in the doc subdirectory. It's important to not submit files which should not be change-controlled, and to set the right Subversion file properties. The easiest way to accomplish this is to put the supplied file samples/config-svn.txt into place at $HOME/.subversion/config on UNIX-like OSes, or wherever your Subversion client wants it on Windows. When you submit code, always add a meaningful subversion commit message which very briefly describes what you have changed, added, or removed.

Top of section "Build and Install from source"

3.3.3. IDE Setup

At this point in time, we only have the JWebMail pre-configured for Eclipse. Any developer who has a strong preference for a different IDE should be capable of getting things working in it. If you do this in a way to share the configuration in a fool-proof manner, like we do for Eclipse, please contact me to get these improvements into the code baseline.

Here are the steps to start from 0 and get JWebMail building. Most developers will skip many of these steps because they probably already have some of the components in place.

1. Install a 1.5 or later JDK and set a Windows env. variable for JAVA_HOME, with value of the absolute path to your JDK installation root. You can download a JDK from Sun.
2. Install or have deployment access to a 2.4-spec-compliant servlet container like Tomcat version 6. (Could be installed on a different computer).
3. Install a JDT variant of Eclipse, version 3.4.1 or later. I prefer the plain Java package, because it doesn't include tons of stuff that you will never use, like the much larger distributions have. After you extract the distribution, execute the startup binary once with the -initialize switch.
4. To install Subversive, the Subversion client plugin, use pulldown menu Help / Software Updates and click the Install button. Bring up a web browser at the same time and browse tohttp://www.polarion.com/products/svn/subversive.php?src=eclipseproject. Back in Eclipse, click the Available Software tab and Add the two "required" URLs listed in the "Latest Release" section of that web page. Select the latest available release of each of the four following items and install them.
   • SVN Team Provider
   • JDT Ignore Extensions
   • Connectors / Subversive SVN Connectors
   • Connectors / SVNKit
   When done, you will be prompted to restart Eclipse. Do so.
5. After Eclipse restarts, use pulldown menu File / Import and import from Subversion. Enter URL of https://jwebmail.svn.sourceforge.net/svnroot/jwebmail/trunk and no other detals (unless you're a team developer). If it craps out, restart Eclipse and retry... or it could be a bad Internet connection to Sourceforge.
6. Get rid of any Eclipse views that you don't need. Use pulldown Window / Show View / Ant. Click the target icon in the Ant view toolbar to hide internal Ant targets. Right click in the view and add the Ant build file build.xml from the root directory of the project. At this point all of the listed Ant targets should work, except for gen-guide and all, if you don't have xsltproc installed. Double click on jwebmail to execute the default target, which builds the war file. You will probably also want to execute the target javadoc to build the JWebMail API spec docs with entry point of build/apidocs/index.html.
7. Now you just need to get IDE compilation working, and cooperating with the Ant build. Go to Preferences / General / Workspace to turn Build automatically off and Refresh and Save on.
8. Use pulldown Project / Clean... to clean just the jwebmail project... and turn off the nasty Start a build immediately button (definitely a bad thing for shared Ant setups).
9. Execute the ant target eclipse-setup and set the build variable as you instructed in the console output.
10. Anybody who will be contributing code to this project, or to any other project with professional standards should read the next section too.

Top of section "IDE Setup"Top of section "Installing"

3.4. IDE Code Contributors

People contributing code to the JWebMail project must create code that isn't difficult for other developers to work with, and must commit resources in a way that doesn't clobber other workers. Even if you aren't going to commit code to our project, you're welcome to use these procedures if you just like developing like a professional, or if you are sharing with somebody else.

1. Even though you are a graphical developer, you need to read and understand the development rules above in the Build and Install from source section bove.
2. Back to eclipse. A general tip is to be liberal with hitting Apply and OK when changing Eclipse preferences. It's much better now than with older versions, but Eclipse is known to sometimes not getyour changes. If that happens, just repeat and make sure you apply. Back to the task at hand, go to Windows / Preferences / Team / SVN / Properties Configuration and Import the file samples/config-svn.txt. This file has specifically been massaged to do what it needs to do while accommodating several serious parsing bugs in the Eclipse Subversive plugin.
3. The remaining items all involve importing Eclipse XML Java style profiles. Window / Preferences / Java / Code Style First, go to the Clean Up and Import the file samples/cleanup-ecpro.xml.
4. Go to the Formatter and Import the file samples/formatter-ecpro.xml. Note that this formatter disabled word-wrapping for Java files, because Eclipse does a truly terrible job at it. It doesn't even enforce the rules as it explains and exemplifies them. Sorry to say, but after running Eclipse's code formatter, you'll need to apply word-wrapping manually (according to doc/conventions.txt. (The formatter works perfectly well for Javadoc and non-Javadoc comments).
5. Finally, go to Code Templates, but this time don't load the profile at the global level. That's because, whereas the other settings are good for any Java project, these templates may not be appropriate for other Java projects that you may work on in the same Eclipse workspace. The only known issues with the code templates is that they will insert useless blank Javadoc lines like " *" if there are no tags for a method, and it will insert a blank line after {'s and before }'s.
6. Click on the Configure Project Specific Settings.... Select the jwebmail project and click OK. Click the Enable project specific settings checkbox. Import the file samples/codetemplates-ecpro.xml.
7. In the upper tree, select Comments / Types and hit the Edit... button. (IMO it's rather counterintuitive that the lower box there is not an editable box-- you must hit the Edit... button to edit. Change the text "Your Name Here" to your name, spelled out and capitalized like that.
8. Before exiting the Properties for jwebmail... screen, make sure to check the Automatically add comments... button and click the Apply and OK buttons.

Top of section "IDE Code Contributors"

3.5. Logging setup

Webapp logging is best administered at the container level. Most servlet containers were designed to work this way, and many technology companies expend much effort to defeat Classloader design and manage logging with delivered application artifacts. Remember that logging settings are a runtime consideration which should be modifiable after deployment by operations personnel. JWebMail is exceptional in that it facilitates logging

Webapp bundles just Apache Commons Logging. Commons Logging provides the front end for logging, where the JWebMail application sends log messages. Your servlet container will connect these generated messages to a logging back end to write log files, database records, or emails from them. If you have a straight-forward servlet container, and you have not added a logging product to it, then Commons Logging will also handle the back end in the container space, just logging to the console or stdout/stderr log with default settings. But it is very easy to improve on that. Some application servers have logging management utilities, and you can use them to pipe the JWebMail log entries to destinations using Gui tools or text files. You'll have to see your App Server documentation about these tools. Otherwise, you can put text files in container-level classloader directories to easily set up text, HTML, and even email-alert logging.

I will explain how to set up really nice JWebMail logs using Log4J as the back end (container-side) logging product on Tomcat. In my experience, everybody is satisfied with Log4j. The procedure is very much the same to use another logging back end product (see the Commons Logging documentation about how to do it). The setup procedure is the same for other servlet containers (that don't force their logging management system on you), except you just need to find out where the system classpath directories are (or how to add them).

Container logging setup with Log4j and Tomcat

• The default container classpath directory on Tomcat 6.x is CATALINA_HOME/lib by default. I.e., the "lib" subdirectory of the Tomcat installation root directory. You can put both Jar files and in .class files (in package directory trees) into it. (You can add other classpath directories by changing the setting common.loader in the file conf/catalina.properties).
• Copy a recent version of the file log4j.jar into the servlet container classpath directory.
• Copy a recent version of the file admc-log4j.jar into the servlet container classpath directory.
• Copy the file log4j.xml from the samples directory of your JWebMail distribution into the servlet container classpath directory.
• Set the Java System Property logdir.common for Tomcat. Our log4j.xml file uses this variable to set the destination directory for log files independently of where Tomcat is started from. The best way to set Java System Properties for Tomcat is by setting the environmental variable CATALINA_OPTS. Where to set this variable depends on how you start Tomcat. If you use one of Tomcat's startup scripts directly on the command-line, then set the variable according to these samples. On Windows,

  CATALINA_OPTS="-Djava.awt.headless=true -Xms512m -Xmx1024m -XX:MaxPermSize=256m -Dlogdir.common=$HOME/logs"

  On Unix,

  set CATALINA_OPTS=-Djava.awt.headless=true -Xms512m -Xmx1024m -XX:MaxPermSize=256m -Dlogdir.common=c:/logs

  The samples shows unrelated settings which are often useful. See the Tomcat docs for details about them.
• Restart Tomcat.

If you prefer working with .properties files instead of .xml files, you can make a log4j.properties file instead. See the Log4j documentation about how to set up email alerts with the SMTP appender, how to log to a database, etc.

Be aware that the file (log4j.xml or log4j.properties) will control all messages which reach Log4j in the container space. If you have three other web apps deployed to this container without log4j jar files bundled, their log messages will also be filtered by this file.

Regardless of the container and logging product, if you manage logging at the container level without a Gui, the server classpath file will be the central point of application log management for the container. You can use package names to route messages to application-specific destinations (files, emails, etc.). The only tricky part of container-managed logs is routing messages initiated by classes common to more than one webapp. This isn't the place to discuss how to route such messages, but you generally don't have to worry about it if your app catches all throwables, and you have the same app deployed more than once-at-a-time.

Top of section "Logging setup"

Top of section "Installation"

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

• Changing all configuration settings
• Adding, deleting or editing JWebMail virtual domains
• Adding, deleting or editing JWebMail users
• Getting status information

See the JWebMail Administrator Plugin section for details.

4.1. Storage Methods

By default, when you install the web application, a XML storage are will be set up under the servlet container owner's home directory. The location, and many other things can be changed, but data should not be written under the context root (appication deployment directory).

Top of section "Storage Methods"

4.2. JWebMail Administrator Plugin

4.2.1. Connecting

You can connect to the administration interface with your browser by simply entering the URL http(s)://webmail_server:port/jwebmail/admin in the address field of your browser. (set http/https and replace webmail_server and port with the correct values).

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.

Top of section "Connecting"

4.2.2. System Settings

The first page gives you a list of JWebMail 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.

Top of section "System Settings"

4.2.3. JWebMail Virtual Domain Support

Virtual Domains in JWebMail 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 JWebMail can impose certain restrictions on users of a JWebMail 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 JWebMail 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)).

Top of section "JWebMail Virtual Domain Support"

4.2.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 JWebMail 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

Top of section "Editing Users"

4.2.5. Viewing JWebMail 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.

Top of section "Viewing JWebMail Status"Top of section "JWebMail Administrator Plugin"

Top of section "Configuration"

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

• SIMPLE: Use JWebMail's former authentication method. Password is only checked against the user's configuration. The user may change his password from within JWebMail
• IMAP: Check login/password on a remote IMAP host. JWebMail tries to login on a remote IMAP host with the given login and password.
  If login fails, JWebMail 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: JWebMail 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.

Top of section "User Authentication"

6.1. General Usage

The JWebMail daemon listens on whatever port you have configure. Just point your browser´s URL to http://yourhost:yourport/jwebmail 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. JWebMail 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.

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

Top of section "General Usage"

6.2. Folders

JWebMail supports as many IMAP folders on as many different hosts you like.

JWebMail mailboxes are configured by each user, however the administrator can change the default mailbox for each virtual domain. The default mailbox is the mailbox the user gets on the first login. He can than choose to remove it at any time and also add other mailboxes (the administrator can restrict that in the virtual domain configuration).

Top of section "Folders"

Top of section "Usage"

JWebMail supports the usage of different languages on a per user basis. Since v0.6.0 JWebMail 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 JWebMail to a new language, please read the file "Translating" in the developers' documentation (source only).

Top of section "Different Languages, Translating JWebMail"

8.1. JWebMail Status

JWebMail Pre-1.0.1 is BETA.

Some features on the wish-list are

• Captcha
to prevent robots, trojans, and miners from sapping our servers.
• JDBC Integration
• Refactor and modernize the authentication methods
• Different XSL stylesheets to convert the JWebMail UI to other formats than HTML (perhaps WML for mobile phones)
• PGP
• Extras like calendar and so on (will be realized as JWebMail Plugins)

Top of section "JWebMail Status"

8.2. Changes

See the file changes.txt for a list of changes in the different JWebMail releases.

Top of section "Changes"

Top of section "Notes"

JWebMail is copyright 2008 by the JWebMail Development Team and Sebastian Schaffert.

The base JWebMail product is distributed under the terms of the Apache 2.0 license. You can find a copy in the file LICENSE.txt, or at http://www.apache.org/licenses/LICENSE-2.0.

The Bibop theme is copyrighted under the supplied GPL 2 license.

Top of section "License"

Contributed Documentation is documentation that has been provided by people that are not core JWebMail developers but have managed to run JWebMail on different platforms/systems and taken the effort to provide you with some sort of extra documentation (thanks a lot, BTW). I (Sebastian Schaffert) have not tested what you will find here.

Top of section "Contributed Documentation"

Appreciation to all who reported bugs and made suggestions to improve JWebMail.

Some, however, I want to mention explicitly:

• Sebastian Schaffert, schaffer@informatik.uni-muenchen.de, who was the project lead before me.
• Devin Kowatch, devink@webengruven.org, for contributing challenge/response authentication
• Homero Borgo, homero@apoyo.uson.mx, for testing JWebMail under rough conditions and helping much to find bugs in the product.
• Sebastian's girlfriend for her patience and the cool icons for JWebMail 0.5 and 0.6
• The people at Bibop in Italy, especially Gianugo Rabellino and Ricardo Rocha for doing the Bibop Theme and lots of inspirations
• Sacha Berger, bergers@informatik.uni-muenchen.de, for some very interesting discussions about how to do things right.:-)

Blaine Simpson, blaine.simpson@admc.com