Java Agent Test Environment

Overview

This is a document detailing the steps of a standalone developers environment.
 
 No part of this document is meant to be any sort of instructions for a production install. Please see the Bare Metal documentation for this. The Bare Metal documentation can also serve the majority of test environments when duplicated on two machines.
 
  This documentation describes the steps necessary to set up two James instances on a single machine which are used to simulate real-world transactions. There are no MX or DNS records needed for this environment. It serves a very specific test environment. Because of this, there are additional steps which are not found in the production Bare Metal documentation.
 
 [impediment] Using a single configuration service for both James instances causes each instance to think they own both domains. This causes all mail to be delivered locally without passing through the security agent. Using two configuration services (8081 and 8082) ends up sharing a single derby instance, defeating the point of having two.
 

Environment

The development environment is set up as follows:
 

james_california		james_florida
Simulates domain: california.directproject.org Includes user: doctor@california.directproject.org SMTP port: 25 POP3 port: 110 NNTP port: 119 Admin port: 4555 Routes all non-local outgoing mail to james_florida instance.		Simulates domain: florida.directproject.org Includes user: doctor@florida.directproject.org SMTP port: 8025 POP3 port: 8110 NNTP port: 8119 Admin port: 8555 Drops all non-local outgoing mail.

General

Install required tools.
 
sudo apt-get update
sudo apt-get install wget
sudo apt-get install unzip
sudo apt-get install mercurial
sudo apt-get install maven2

Install Java

Install Sun Java 6 JDK. By default it is not included in the shipped repository, and needs to be added manually. After installing, need to update java-alternatives to use the newly installed Java version instead of shipped version.
 
sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
sudo apt-get update
sudo apt-get install sun-java6-jdk
sudo update-java-alternatives -s java-6-sun
export JAVA_HOME=/usr/lib/jvm/java-6-sun
echo "export JAVA_HOME=$JAVA_HOME" >> ~/.bashrc

Java Cryptographic Extensions

Download and install the Java Cryptographic Extensions.
  Unzip the resulting files, and place the jar files in $JAVA_HOME/jre/lib/security, or, for OS X, $JAVA_HOME/lib/security.
 
  The jar files in zip may be older than the ones found in your JDK. You must replace the files in your JDK regardless of data. JDKs by default are not package with the strong encryption policy jars.
 
unzip jce_policy-1_4_2.zip*
sudo cp jce/local_policy.jar $JAVA_HOME/jre/lib/security
sudo cp jce/US_export_policy.jar $JAVA_HOME/jre/lib/security
rm -rf jce*

Check-out and Build Source

Check-out the source from the repository and compile and test all artifacts.
 
hg clone https://nhin-d.googlecode.com/hg/ direct-src
cd direct-src/java
mvn clean install

Note: Maven occasionally hangs while downloading dependencies. If the build appears to stop for an unreasonable amount of time while downloading a file, use control-c to stop the process. Run the command again to continue from where it left off.

Create James and Tomcat

Get the Apache James mail server, used to process incoming and outgoing email messages. The install script will insert the security agent, which was build above, into the James processing pipeline. Also get Apache Tomcat, which is used to run the configuration service which will hold domain information, anchors and certificates, and settings for the security agent.
 
cd install
mkdir direct
sh install.sh direct

[dev] Create a copy of James for the two mock entities.

mv direct/james-2.3.2 direct/james_california
cp -r direct/james_california/ direct/james_florida

Set an environment variable which will be used for convenience.

export DIRECT_HOME=`pwd`/direct
echo "export DIRECT_HOME=$DIRECT_HOME" >> ~/.bashrc

Developer Specific Config

[dev] Replace the standard configuration with pre-configured configuration files for a developers test environment. This sets specific ports and addresses to avoid conflict.
 
wget http://nhindirect.org/file/view/james_config_california.xml -O $DIRECT_HOME/james_california/apps/james/SAR-INF/config.xml
wget http://nhindirect.org/file/view/james_config_florida.xml -O $DIRECT_HOME/james_florida/apps/james/SAR-INF/config.xml

Run Tomcat

[dev] Run Apache Tomcat and start the configuration service.
  [issue 84] Load .war files in specific order.
 
cd $DIRECT_HOME/apache-tomcat-6.0.29
mv webapps/config-ui.war .
rm -rf webapps/config-ui
sh bin/startup.sh
sleep 15s
mv config-ui.war webapps

Configure James (manual step)

[dev] Set up the configuration service to handle the two mock entities.
 

1. Log into [1] with username:admin and password:adm1nD1r3ct
2. Click New Domain.
   1. Domain Name: california.directproject.org
   2. Postmaster: postmaster@california.directproject.org
   3. Choose ENABLED as the status.
3. Click the Anchors tab.
   1. Add the dev anchor found here.
   2. Check Incoming and Outgoing.
   3. Choose ENABLED as the status.
4. Click Cancel
5. Click New Domain.
   1. Domain Name: florida.directproject.org
   2. Postmaster: postmaster@florida.directproject.org
   3. Choose ENABLED as the status.
6. Click the Anchors tab.
   1. Add the same dev anchor found above (or here).
7. Click Cancel
8. Click Go To Certificates.
   1. Import the dev p12 files found here and here.
   2. Choose ENABLED as the status.
9. Click Cancel
10. Click Go To Settings.
    1. Add setting key:PrivateStoreType with value:WS
    2. Add setting key:AnchorStoreType with value:WS
    3. Add setting key:PublicStoreType with value:DNS,WS
    4. Add setting key:RawMessageSaveFolder with value:RawMsgFolder

[dev] Tell each James instance the domain it will be handling.
[fixme] This fails since folder names are hardcoded.

cd $DIRECT_HOME/james_california
sh bin/setdomain.sh california.directproject.org
cd $DIRECT_HOME/james_florida
sh bin/setdomain.sh florida.directproject.org

Run James

Start the Apache James mail server with security trust agent.
  [dev] Start both instances.
 
cd $DIRECT_HOME/james_california
sudo -E sh bin/run.sh > james.log 2>&1 &
cd $DIRECT_HOME/james_florida
sudo -E sh bin/run.sh > james.log 2>&1 &

Create James users (manual step)

Create users that will be using the Apache James mail server.
  [dev] Both instances.
 
telnet localhost 4555
> root
> root
> adduser doctor password
> quit

telnet localhost 8555
> root
> root
> adduser doctor password
> quit

Send A Test Message

[dev] At this point, the instances are ready to send/receive test messages. You can choose to configure an email client to connect to each of the instances (using the ports defined at the top of the documentation, and users defined in the previous step), or you can use telnet to simulate as follows:
 
telnet localhost 25
> ehlo localhost
> auth login
> ZG9jdG9y
> cGFzc3dvcmQ=
> mail from: <doctor@california.directproject.org>
> rcpt to: <doctor@florida.directproject.org>
> data
> Subject:Direct Test Message
>
> This is a test message
> .
> quit

Verify S/MIME Encryption

cat $DIRECT_HOME/james_california/bin/RawMsgFolder/*

Verify S/MIME Decryption

cat $DIRECT_HOME/james_florida/apps/james/var/mail/inboxes/doctor/*.FileStreamStore

Supporting Files

java.dev-ca.directproject.org.der
doctor@california.directproject.org.p12
doctor@florida.directproject.org.p12
james_config_california.xml
james_config_florida.xml