JamesPostage

Overview

Postage is a stand-alone application generating constant mail traffic on a James server instance. It can be considered being a load test tool.

Postage records the resources used by James and supports finding resource leaks, for example memory bottlenecks.

While putting load on James, Postage also records the resulting mail traffic and tries to match incoming and outgoing mail making it possible to use it for end-to-end test.

It's flexible enough to mimic many real-world load scenarios, for example

• many users, each receiving few mails every day

• few users, heavily receiving mails

• moderate mail traffic, yet very big attachments

Features

• Easy XML-file-based configuration with multiple running scenarios for different load profiles

• Supports unlimited number of internal and external users.

• Within one scenario supports different email profiles running in parallel. Every profile has its own specification in terms of

  • number of generated mails per minute

  • sender/receiver

  • mail size

• Records incoming and outgoing mails and matches them to keep track of successful and failed deliveries

• Is able to record the Mail Servers thread and heap memory consumption (only Java SE 5)

Prepare

as prerequisites you need

• Java 1.4.2 or Java 5

• Apache Ant 1.6.5

• Apache James from 2.3 branch

• JavaMail 1.4

• Activation 1.1

get the latest source code from subversion:

svn checkout http://svn.apache.org/repos/asf/james/postage/trunk postage

cd postage

make sure, that you download and add the following libraries to lib/

from Sun

• activation-1.1.jar

• mail-1.4.0.jar

from a local James build:

• james-2.3-dev.jar

• mailet-2.3.jar

• mailet-api-2.3.jar

Building

to build, type

ant

Postage optionally uses JVM JMX features not available before Java 5. At build time, Postage detects the Java version you are building with and deactivates the Java5 features if you are on Java 1.4. (This works by excluding the Java5 specific class from the build.) At run-time, Postage activates JMX if available and possible:

to compile the jar, type

ant package

Prepare James

You should have a James instance readily installed. This means at least extracted James binary and started the server once (see JamesQuickstart).

1. Edit the configuration file JAMES_HOME/apps/james/SAR-INF/config.xml

1.1. Internal test domain

In the server names sections, add new line containing the virtual domain "mail.james.local". This makes James consume all mails addressed to, for example test@mail.james.local.

It should look something like this, depending on your further configuration preferences:

   <servernames autodetect="true" autodetectIP="true">
<!-- CONFIRM? -->
      <servername>localhost</servername>
      <servername>mail.james.local</servername>
   </servernames>

1.2.Sending external mail

All mail addresses not handled by James are delivered to their intended destination, if possible. For Postage to intercept this and receive all mails send out by James, we must enable gateway forwarding.

change

   <!--
      <gateway> otherserver.mydomain.com </gateway>
      <gatewayPort>25</gatewayPort>
   -->

into

   <gateway> localhost </gateway>
   <gatewayPort>2525</gatewayPort>

If Postage is running on another machine than James, you should use the appropriate host/port combination under which Postage is receiving mail.

Now Postage is consuming all mail sent out by James and tries to align the mail it puts into James with mail coming out of the server.

NOTE: This configuration makes James unable to deliver regular external mail, don't do this on a production system!

2. Enable Postage to record memory and thread resource consumption of James

This is optional configuration.

It only works, if James is run under JSE5 or newer and only if Postage has been build with JMX support. It also conflicts with James' current genuine MX4J-based JMX support, which has to be disabled (see ConfigureJmx how to use JSE5 JMX support).

Edit file <JAMES_HOME>/bin/phoenix.[sh|bat]

Replace line

JVM_OPTS="-Djava.ext.dirs=$JVM_EXT_DIRS"

with (on one line)

JVM_OPTS="-Djava.ext.dirs=$JVM_EXT_DIRS -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.port=10201 "

Configure Postage

At startup, you can provide Postage with a configuration file on the command line. The configuration file is split up into sections called scenarios. Each scenarios stands for one postage run with a set of result files. You would typically choose one scenario to be run, but you can run an arbitrary sequence of scenarios.

See the configuration file distributed with Postage for detailed documentation. You'll find postage.xml in config/ or in svn at http://svn.apache.org/repos/asf/james/postage/trunk/src/main/config/postage.xml .

For your own scenario just copy/paste an existing scenario, give it a new ID and start modifying it.

Existing scenarios cover

Running

ant run

TODO: elaborate on running a specific scenario