Bare Metal Project - Java (source)

From Direct Project
Jump to navigation Jump to search
This page documents a bare metal install of the Java reference implementation from source. For a HISP only install (no source), see Bare Metal Project - Java (HISP only).

WARNING:

These instructions are out of date. The installer provided with the source code has several bugs and does not provide the newest version of James (version 3). You can still use these instructions to build the RI, but you will need to correct some issues along the way and either settle for reduced functionality or learn on your own how to find the needed James 3 integration points.

Preface

This document is a starting-point, from which a production HISP can be derived. It is not meant to be a final solution for real-world scenarios. It documents the fastest and simplest way to launch a operational instance using the Java reference implementation.
 
  It is strongly advised and encouraged to back the reference implementation with a tested and proven enterprise mail server. Please review the various deployment models and configurations with your architect and decide which best suits your needs. This should also involve input from you security officer to evaluate things such as HIPAA compliance.
 
  The bare metal install is not HIPAA compliant.

Assumptions

It is assumed that the user is root or has sudo privileges.
 
  The setup of external DNS zonefiles is out of scope of this document.
  It is assumed, if not using the provided DNS server (optional documentation below), that the HISP already has MX and related DNS records set up.
 
  For a reference on creating certificates and trust anchors using the tool provided in the Java reference implementation, please see TBD.

Create a Deployable Package

Steps for creating a deployable package from the source code.

General

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

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

Note: It is okay to ignore the "no alternative" error messages displayed after running the update-java-alternatives command.

Java Cryptographic Extensions (manual step)

Download the Java Cryptographic Extensions.
 
  Follow the steps below to unzip the resulting files, and place the jar files in $JAVA_HOME/jre/lib/security (or for OS X, $JAVA_HOME/lib/security).
 
  Note: 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

Package James and Tomcat

Create a tarball containing all related artifacts needed to run a HISP. This includes Apache James, the security and trust agent, Apache Tomcat, and the configuration service. The only other requirement is Sun Java 6 (with JCE libraries).
 
tar -pcvzf direct.tar.gz direct


Install and Configure Deployable Artifacts

Use the artifacts generated above to stand up a HISP.

Extract James and Tomcat

Extract the Apache James mail server with security agent, and Apache Tomcat with configuration service.
 
tar xvfz direct.tar.gz
export DIRECT_HOME=`pwd`/direct
echo "export DIRECT_HOME=$DIRECT_HOME" >> ~/.bashrc

Run Tomcat

Set the necessary Java options and add to the .bashrc file for the future.
 
export JAVA_OPTS="-XX:PermSize=256M -XX:MaxPermSize=256M"
export JAVA_OPTS="$JAVA_OPTS -Dorg.apache.cxf.io.CachedOutputStream.Threshold=1000000"
echo "export JAVA_OPTS=\"$JAVA_OPTS\"" >> ~/.bashrc

Run Apache Tomcat and start the configuration service.

cd $DIRECT_HOME/apache-tomcat-6.0.32
sh bin/startup.sh

Note: Give this step a minute or two to start the server before continuing to the next step. You can monitor the progress by tailing logs/catalina.out.

Configure James (manual step)

  1. Log into [1] with username: admin and password: adm1nD1r3ct
  2. Click New Domain.
    1. Enter the Domain Name and Postmaster E-Mail Address for the domain this HISP will be handling.
    2. Choose ENABLED as the status.
  3. Click the Anchors tab.
    1. Import trust anchors.
    2. Choose ENABLED as the status.
  4. Click Cancel and click Go To Certificates.
    1. Import certificates.
    2. Choose ENABLED as the status.
  5. Click Cancel and 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: MDNAutoResponse with value: true


Tell James the domain this HISP will be handling by replacing my.domain.com with your domain.

cd $DIRECT_HOME/james-2.3.2
sh bin/setdomain.sh my.domain.com

Run James

Start the Apache James mail server with security trust agent.
 
cd $DIRECT_HOME/james-2.3.2
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.
 
telnet localhost 4555
> root
> root
> adduser username password
> quit

(Optional) Start DNS Server

Start the DNS server to host SOA, A, MX, and CERT records to the public.
 
cd $DIRECT_HOME/DirectDNSServices/DirectDNSServer/bin
sudo ./DirectDNSServer start

TODO: Document quirks/options (memory, console mode)

Configure DNS server (manual step)

Configure the DNS server to properly serve SOA, A, MX, and CERT records to the public.
  1. Log into [2] with username: admin and password: adm1nD1r3ct
  2. Click DNS.
    1. TODO: document steps
      See the DNS Users Guide.


(Optional) XD Support

Following are the steps for adding support of the XD functionality.

Configure Addresses (manual step)

Addresses associated with XD endpoints are mapped using the config-ui.
  1. Log into [3] with username: admin and password: adm1nD1r3ct
  2. Click Search.
  3. Click on the domain to be configured.
  4. Click on the Addresses tab.
    1. Enter the email address which is mapped to an XD endpoint.
    2. Enter the endpoint to which the email address is mapped.
    3. Select ENABLED from the Status dropdown.
    4. Enter XD for the type.
  5. Add any necessary trust anchors and/or certificates (see Configure James steps 2 and 3 above).
  6. Click Cancel.
  7. Click Settings.
    1. Create a password for an internal James account used to connect Tomcat and James for delivering XDM packages. The James account will be created in the next section.
      1. Add setting key: xd.MailPass with value:supersecretpassword
    2. Add setting key: xd.AuditMethod with value: file
    3. Add setting key: xd.AuditFile with value: /tmp/xd.log
    4. Add the following optional setting if the value is something other than localhost
      1. Add setting key: xd.MailHost with value: your-mail-host.com - (defaults to localhost)


Create James user (manual step)

Create an Apache James user for the XDM functionality. The password should match the settings in the previous step.
 
telnet localhost 4555
> root
> root
> adduser direct supersecretpassword
> quit

Apply SSL/TLS Support

TODO: Document steps add SSL/TLS support for XD service.

Recommended Next Steps

Following are optional, but recommended, next steps to secure your environment.

Secure Configuration Service Port (8081)

To secure the configuration service, it is recommended to limit access to port 8081 to localhost and/or a local subnet.

Secure Configuration Service Password

To further protect the configuration service, or if port 8081 must remain public, it is recommended to change the default password.
 
cp $DIRECT_HOME/apache-tomcat-6.0.29/webapps/config-ui/WEB-INF/config-servlet.xml $DIRECT_HOME/apache-tomcat-6.0.29/webapps/config-ui/WEB-INF/config-servlet.xml.orig
sed -i "s/adm1nD1r3ct/your_new_password/g" $DIRECT_HOME/apache-tomcat-6.0.29/webapps/config-ui/WEB-INF/config-servlet.xml
sh bin/shutdown.sh
sh bin/startup.sh
Retrieved from "https://directproject.mywikis.wiki/w139/index.php?title=Bare_Metal_Project_-_Java_(source)&oldid=51"