|Previous:||Up: Deploymenet Guide||End of book|
This section outlines step by step instructions on installing and deploying a Bare Metal instance of the Java reference implementation. The instructions contains steps for a select list of software platforms such as Windows and Ubuntu linux.
The reference implementation requires some tools to be available on the platform to install and run the Bare Metal components.
An unzip tool is required to unpack the stock assembly. Recommended tools and installation locations are listed below:
Any one of the following will work for Windows:
Install unzip using the following command:
sudo apt-get install unzip
Unzip tools should already be installed, but if not execute the following commands with root or sudo privileges:
yum install unzip yum install gzip yum install tar
The Ant tool is used for setting the domain name in the Apache James server.
Download Apache Ant from the following location and follow in the install instructions under Documentation/Manual located on the upper left side of the site below
Install ant using the following command:
sudo apt-get install ant
The Java 6 SE platform provides the runtime environment that all of the Bare Metal components will run in.
Download and install the Java 6 JRE from Oracle's download web site. After installing the JRE, set the JAVAHOME environment variable by following the instructions below:
Ubuntu 10.10 - 11.10
Install Sun Java 6 JDK. By default it is not included in the shipped repository, and needs to be added manually. After installing, you need to update java-alternatives to use the newly installed Java version instead of shipped version.
Note: For Ubuntu 10.10 Maverick, the add-apt-repository command may not be not available. Instead, uncomment or add the canonical repository "http://archive.canonical.com/ lucid partner" in the /etc/apt/sources.list and follow the remainder of the steps.
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.
The Sun JDK 6 has been moved to a Personal Package Archive (PPA) for 12.04. You will need to add Flexiondotorg repository to install the Sun JDK.
Similar to previous versions of Ubuntu, you need to update java-alternatives to use the newly installed Java version instead of shipped version.
Note The add-apt-repository command may not be available. Adding the python-software-properties package should resolve this issue. It is also okay to ignore the "no alternative" error messages displayed after running the update-java-alternatives command.
sudo apt-get install python-software-properties sudo add-apt-repository ppa:flexiondotorg/java 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
Obtain/downlaod the JDK 6 Update 29 package using the following command for the appropriate processor architecture:
x86 (32 bit)
x64 (64 bit)
After downloading, execute the following commands to install the JDK for the appropriate processor architecture:
x86 (32 bit)
chmod 755 jdk-6u29-linux-i586-rpm.bin sudo ./jdk-6u29-linux-i586-rpm.bin
x64 (64 bit)
chmod 755 jdk-6u29-linux-x64-rpm.bin sudo ./jdk-6u29-linux-x64-rpm.bin
After installing, you need to update java alternatives to use the newly installed Java version instead of shipped version. Start by creating alternatives for the new java commands installed above. Execute the following commands to set the Sun JDK:
sudo alternatives --install /usr/bin/java java /usr/java/jdk1.6.0_22/bin/java 100 sudo alternatives --install /usr/bin/jar jar /usr/java/jdk1.6.0_22/bin/jar 100 sudo alternatives --install /usr/bin/javac javac /usr/java/jdk1.6.0_22/bin/javac 100 sudo alternatives --config java sudo alternatives --config jar sudo alternatives --config javac
Finally set the JAVAHOME environment variable for the new JDK using the following commands:
export JAVA_HOME=/usr/java/jdk1.6.0_22 echo "export JAVA_HOME=$JAVA_HOME" >> ~/.bashrc
The Sun JRE/JDK requires the JCE policy jars to be updated to allow for unlimited strength encryption. The policy files must be downloaded separately and copied in the JRE library.
For all platforms, download the jce policy file using a web browser. For Unix/Linux systems, it may be necessary to manually copy or FTP the file from a system with a UI to the Unix/Linux node.
Unzip the downloaded file and copy the jar files from the jce directory to the JAVAHOME/jre/lib/security folder (Example: C:Program Filesjavajre6libsecurity). Overwrite the existing files.
From the directory where you downloaded and placed the jce zip file, run the following commands:
unzip jce_policy-6.zip sudo cp jce/local_policy.jar $JAVA_HOME/jre/lib/security sudo cp jce/US_export_policy.jar $JAVA_HOME/jre/lib/security
The stock assembly contains all of the pre-assembled and configured components of the Bare Metal deployment. Download the latest version of the stock assembly from the maven central repository or the Sonatype repository.
Note: The maven central repository may black list some IP ranges such as virutal machines running in the Amazon EC2 cloud. Use the Sonatype repository if you are blocked from the maven central repository.
The assembly contains a root directly named direct and has the following folders under the root.
From a browser, download the desired version of the assembly from one the repositories above.
Example: Download version 1.4 - direct-project-stock-1.4.tar.gz. After downloading, unzip the contents to appropriate installation location.
Obtain the URL for appropriate version of the assembly and download it the /opt directory by running wget command from the /opt directory. For example, to download version direct-project-stock-1.4.tar.gz from maven central, use the following commands:
cd /opt wget http://repo2.maven.org/maven2/org/nhind/direct-project-stock/1.4/direct-project-stock-1.4.tar.gz
If you are denied access to the location above, try the Sonatype repostitory using the following command.
cd /opt wget https://oss.sonatype.org/content/repositories/releases/org/nhind/direct-project-stock/1.4/direct-project-stock-1.4.tar.gz
Extract the contents of the assembly and set the DIRECT HOME logical using the following command. Note the name of the tar.gz file if you downloaded a different version:
tar xvfz direct-project-stock-1.4.tar.gz export DIRECT_HOME=`pwd`/direct echo "export DIRECT_HOME=$DIRECT_HOME" >> ~/.bashrc
Before running the James mail servier, the configuration services must be running and some minimum configuration completed. All of these services run inside the Tomcat web server.
To start the tomcat server, run the following command from the DIRECT HOME/apache-tomcat-7.0.27/bin directory.
Note: It may take a few minutes for the web server to finish loading as it must initially deploy all of the services when run for the first time.
To validate that Tomcat and the configuration services loaded successfully, launch a browser window against the server node with the following URL:
You should be presented with the configuration ui login screen
The first step in running your mail server is configuring the domain and a loading a trust anchor and certificate into the configuration ui.
First determine your HISPs domain name. Depending on the type of certificate resolution services you wish to host, your domain nameing convention may slightly differ. Regardless of the certificate hosting model, you will need to have to have registered domain. For this document, we will assume you have a domain registered called example.com.
Note: Refer to the Direct Project DNS Configuration Guide as a starting point for determining your DNS naming convention.
Now that we have our registered domain, we will host our HISP Direct messaging under the domain direct.example.com.
The next step is create a root certificate (anchor) for our domain and an X509 certificate for encrypting/decrypting and signing message. There are many different options for getting these certiicates such as using openssl or obtaining a certificate from a comercial third party such as Entrust or VeriSign. However the Direct Project reference implementation assembly ships a tool called certGen for generating root CAs and certificates for the purpose of pilots and interop testing.
Full documentation for the certGen tool can be found here. The documentation in the certGen link runs the certGen tool from the reference implemntation source tree. In the Bare Metal assembly, the certGen tool is found under the /direct/tools directory that was extracted from the tar.gz file.
Run the certGen tool from tools directory using the following command:
Now create a CA for your domain. In the certGen tool, enter a common name (CN:) for your new CA. For our domain direct.example.com, we might use something like Direct.Example.Com Root CA. Fill the other fields as needed. It is recommended you set the expiration to 1 year, the key strenth to at least 2048 bytes, and provide a password for your CA's private key.
After creating the CA, create a leaf cert and using your domain name as the CN: field and fill in all other fields as needed. It is recommended you set the expiration to 1 year, the key strength to at least 1024 bytes, and provide a password for your private key. Also make sure the Add Email To Al Subject Names is checked. After creating your CA and certificate, you should have to following similarly named files in your /tools directory (assuming the direct.example.com domain and no email address entered in the CA dialog. If an email address is entered, then the CA files will have the eamil address in the file name instead of the CN field).
Before the James mail server can be run, you must create you domain in the configuration ui tool and import anchors and certificates. Follow the steps below to create your domain and import your trust anchor and certificate. A full description of the config ui and operations can be found here.
Note: You do not have to enter any additional agent setting in version 1.2 and higher of the Bare Metal assembly. The agent automatically defaults to standard settings for optimal interoperability.
Before your HISP can communicate with other HISP, you must import anchors from other HISPs to estabilish trusted communication. You must also provide your trust anchor to the HISP(s) you are communicating with. There are a few options of HISPs that exist for interop testing that can be easily accessed. Anchors of these HISP can be found and downloaded from the Direct Project google code source page.
First, configure james with your domain name.
Manually edit the file config.xml under DIRECT HOME/james-2.3.2/apps/james/SAR-INF and change the following settings.
Run the following commands:
cd $DIRECT_HOME/james-2.3.2 sh bin/setdomain.sh <your domain name>
Now start the Apache James mail server with security and trust agent with the following commands:
From the DIRECT HOME/james-2.3.2/bin directory run:
cd $DIRECT_HOME/james-2.3.2 sudo -E sh bin/run.sh > james.log 2>&1 &
Now add your first user by running the following commands:
Note For Windows Users: You will need to open a separate command window from the previous step. Later versions of Windows do not come with the Telnet client installed. You have to manually install this using the server manager console.
telnet localhost 4555 > root > root > adduser username password > quit
Note: The username should not contain @domainname. This is required for James 3+, but should not be used for James 2.3.2.
Now that your HISP is running, you need to make it available to the public internet. If you intend to make your HISP's certificate available via DNS CERT records, you will need to install and configure the Direct DNS Server. Instructions can be found in the DNS Servers users/deployment guide. This guide includes directions on integrating with GoDaddy.
If you are not using DNS to distribute your certificates, you may use your registrar's DNS configuration tooling to setup MX records for you HISP.
The prefered distribution mechanism for distributing your HISP's org certificate is DNS CERT records. Instructions for setting up the Direct DNS server are found in the DNS server deploymenet guide.
Another alternative still in the formalization stage is LDAP. The default settings in the security and trust agent will attempt to use the Direct LDAP specication if SRV records can be found. The LDAP standards can be found on the S&I framework's Certificate Discovery for Direct Project workgroup page.
A fall back alternative is manually distributing your org certificate to the HISPs that you will communicate. This is an out of band process that will require you to determine how to get your certificate to the HISP. Likewise another HISP may need to manually give you their certificate(s) if they do not support DNS or LDAP discovery. To add another HISPs certificate (not anchor) to you HISP, import the certificate file into the Certificates section of the configuration ui tool.
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.
Manuall edit the config-servlet.xml file under DIRECT HOME/apache-tomcat-7.0.27/webapps/config-ui/WEB-INF and change the following setting to your new password:
<security:user name="admin" password="adm1nD1r3ct" authorities="ROLE_ADMIN"/>
Restart the tomcat server by running the following commands from the DIRECT HOME/apache-tomcat-7.0.27/bin directory.
cp $DIRECT_HOME/apache-tomcat-7.0.27/webapps/config-ui/WEB-INF/config-servlet.xml $DIRECT_HOME/apache-tomcat-7.0.27/webapps/config-ui/WEB-INF/config-servlet.xml.orig sed -i "s/adm1nD1r3ct/your_new_password/g" $DIRECT_HOME/apache-tomcat-7.0.27/webapps/config-ui/WEB-INF/config-servlet.xml sh bin/shutdown.sh sh bin/startup.sh
|Previous:||Up: Deploymenet Guide||End of book|