ESOE Installation Guide

Authors
Bradley Beddoes
Paul Stepowski
Shaun Mangelsdorf

Applicable versions
Beta 2

Note: The instructions here do not apply to builds from the current development branch.

For the security conscious we highly recommend our guide on Securing ESOE in Unix environments in addition to this guide

Custom Linux install documentation is available for some platforms and should be read in addition to this document

These instructions assume a standalone tomcat installation not fronted by Apache, please see ESOE Installation Additions - Apache and Mod Proxy AJP for instructions on deploying behind apache

Prerequisites

System

Software Website
Sun Java SE 5 (Sun Java SE 6 for Active Directory Integration) http://java.sun.com
MySQL Server 5.x or Oracle 9g1 http://dev.mysql.com/downloads/mysql/5.0.html or http://www.oracle.com
Tomcat 5.5.x or higher http://tomcat.apache.org

1 May be substituted with other supported database software.

Dependencies

ESOE is a complex system with many dependencies, all dependencies are Apache 2.0 licensed or licensed under compatible terms.

Apart from database dependencies which need to be shipped directly by vendors and logging dependencies which are a per site special deployment the ESOE download supplies all required jar files in two separate packages, NAME-shared.tar.gz and NAME-endorsed.tar.gz installation of these packages is explained in the subsequent passages below. Each package contains a html file which specifies versions which are relied on for the release of the ESOE you are installing. Should you wish to manage your dependencies via a package management repository such as those provided by jpackage.org this file will be invaluable in assisting you with deployment. Be aware that dependencies which are specified as endorsed are particularly important, failure to correctly endorse dependencies can lead to problems with utilization of broken or incomplete implementations of classes from the JVM.

MySQL Dependencies

You need to retrieve MySQL JDBC driver from:
http://www.mysql.com/products/connector/j/

The version you will require is 5.0+

Oracle Dependencies

You need to retrieve Oracle JDBC driver from:
http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html

Please select the correct version for your backend Oracle deployment.

Overview of ESOE components

There are 4 major components which are deployed to get your ESOE deployment up and running:

  • esoestartup - Asks a series of questions about your environment in an easy to use web interview, once this process is undertaken customized ESOE configuration files and keystores are setup for you
  • esoecore - This is the core of the ESOE and where all the processing code lives, this is generally deployed as a web application named ROOT.war
  • esoemanager - This is the management interface of the ESOE, it allows you to register new services, view metadata, set authorization policies and undertake other actions. The current version of ESOE manager is aimed at administrators and developers. This tool is now under heavy development and later versions will feature a lot more functionality.
  • spep - This is the code which lives on the application side and communicates with the ESOE, an SPEP is deployed in the initial instance to protect the ESOE Manager environment, you will deploy countless more in the future to protect your other services.

Some decisions around deployment should be made at this stage. The components esoemanager and spep MUST be deployed in the same tomcat instance. However we recommend that the esoecore component is deployed in a separate instance (preferably on a separate machine), however if you are limited to one tomcat instance all three components will play happily together.

Generally we run esoestartup and esoecore in the same tomcat instance, you may however freely separate this to two further tomcat instances if you desire.

Considerations for physical hardware are important for ESOE deployments. All operations the ESOE undertakes require cryptographic processes which is CPU intensive. As a guide we are able to guarantee around 25 operations a second on Pentium 3 class hardware with JVM memory maximums of 768m. Further performance figures are forthcoming.

Configure Your System

Taking a backup

If you are using versions of software that already exist on the system, particularly the tomcat instance we cannot stress enough the need to MAKE A BACKUP before continuing. The best of us make mistakes, a backup makes them small mistakes, not backing up can make them a nightmare.

Ensure active Prerequisites

To run ESOE you need the following available on your system:

  1. A Sun JVM preferably Java SE 6 but 5 is also acceptable (NOTE: Users of Java 5 you will not be able to use the Active Directory true single sign on).
    ESOE requires more memory than the defaults. You should set JAVA_OPTS to have memory sizes similar to the following -Xms128m -Xmx512m, this will work for most testing environments. For Production we recommend a range between 512 and 1024 but this needs to be tuned to your expected load.
  2. Tomcat 5.5.x or 6.x (Other Java containers should also be suitable but are as yet untested - let us know your experiences on the mailing list if you install in another container)
  3. Either an Oracle or MySQL database instance, with a unique database/schema and an account with read/write privileges. This account will be used by both the ESOE Core and ESOE Manager components.

Ensure your default Tomcat install can be accessed on port 8080 and you can see the generic welcome message, then continue below.

For the security conscious we highly recommend our guide on Securing ESOE in Unix environments in addition to this guide

Configure Dependencies

Dependencies Package

Extract the package you have downloaded for the ESOE Project. E.g.
$ mkdir esoestartup
$ cp esoe-startup.tar.gz esoestartup
$ tar zxf esoe-startup.tar.gz

This will result in a number of gziped tar packages being made available, along with esoestartup.war.

At this stage you will have decided if all the components will be running on a single tomcat instance or across multiple instances. If you are running a separate container then you need to make similar decisions, likewise the below extraction points need to be mapped to your container of choice. We would appreciate your instructions for achieving this on other containers. Some of these dependencies are similar across components. If you are deploying several components in the same container you can safely expect warnings about overwriting files when extracting.

ESOE Startup dependencies

  1. Extract esoestartup-endorsed.tar.gz to your $TOMCAT/common/endorsed directory of the tomcat instance which will run esoestartup
  2. Extract esoestartup-shared.tar.gz to your $TOMCAT/shared/lib directory of the tomcat instance which will run esoestartup

ESOE Core dependencies

  1. Extract esoecore-endorsed.tar.gz to your $TOMCAT/common/endorsed directory of the tomcat instance which will run esoecore
  2. Extract esoecore-shared.tar.gz to your $TOMCAT/shared/lib directory of the tomcat instance which will run esoecore

ESOE Manager dependencies

  1. Extract esoemanager-shared.tar.gz to your $TOMCAT/shared/lib directory of the tomcat instance which will run esoemanager
  2. Extract spep-endorsed.tar.gz to your $TOMCAT/common/endorsed directory of the tomcat instance which will run esoemanager
  3. Extract spep-shared.tar.gz to your $TOMCAT/shared/lib directory of the tomcat instance which will run esoemanager

Configuring your own dependencies

To configure your own dependencies you should acquire them from whatever source deemed most suitable and configure as endorsed and shared libraries to match the versions set down in the supplied html files in each NAME-endorsed.tar.gz and NAME-shared.tar.gz package.

Database dependencies

Earlier you downloaded dependencies for your database either MySQL or Oracle. Both distributions should come with a single jar file. This jar file should be copied to $TOMCAT_HOME/shared/lib for tomcat instances which are running the components esoestartup, esoecore and esoemanager

Configure Database

Your database itself is already configured, undertake the following for your environment.

MySQL

  1. Start the mysql command line tool and login as a user with the global SUPER privilege
  2. Switch to your esoe database
  3. Run the following command:
    source $esoestartupextractdir/databasegeneration/generate_db-mysql.sql
    NOTE: Replace $esoestartupextractdir with your working directory you extracted esoestartup.tar.gz to.
  4. You will see a lot of query successful commands fly by, you may wish to check that all tables are populated by issuing "show tables"

Oracle

Oracle databases are generally controlled by a DBA with the ESOE account not having permission to actually create schema. Give your DBA the generate_db-oracle.sql script to setup your environment. You should then be able to connect as the account provided for ESOE and ensure that tables exist in your schema.

Configure ESOE

Ensure Tomcat is shutdown before proceeding. Copy the esoestartup WAR file to tomcat's webapps directory.

Setup run time configuration properties.

ESOE, ESOE Manager and all SPEP instances rely on Java properties being configured to point to locations at which they can resolve their configuration and keystores. ESOE Startup also utilizes these properties to write configuration files and keystores it generates to.

We recommend you create a directory structure to hold all these files as such
/opt/esoe
        |
        - core
             |
             - config
             - logging
        - manager
             |
             - config
             - logging
        - spep
             |
             - config
             - logging

Windows users should select a suitable location on your server to create a similar structure.

Assuming the above structure you should ensure that the following are exposed to the system variable JAVA_OPTS before starting tomcat:

JAVA_OPTS="${JAVA_OPTS} -Desoe.data=/opt/esoe/core" 
JAVA_OPTS="${JAVA_OPTS} -Desoemanager.data=/opt/esoe/manager" 
JAVA_OPTS="${JAVA_OPTS} -Dspep.data=/opt/esoe/spep" 

Logging

Logging is configured for you in WEB-INF/classes/log4j.xml - Feel free to modify this configuration for your needs.

Run ESOE Startup

You are now ready to restart tomcat. This will automatically deploy the web applications in the WAR file.

The first time you restart tomcat after copying over all the WAR and JAR files, it may take some time for tomcat to start. This is normal. Please be patient. You can view the tomcat and ESOE logs to watch the deployment as it progresses.

Once the esoestartup web application is deployed, point your web browser at [http://$HOSTNAME:8080/esoestartup/]. Where $HOSTNAME is the fully qualified domain name of the IP address that tomcat is listening on.

NOTE: Do not use an IP address for $HOSTNAME. This will cause an error.

The ESOE startup application will now guide you through the remainder of the install process asking you many questions along the way, please have all details about your environment ready for this process.

BE CAREFUL with host addresses. When configuring ESOE and ESOE Manager SPEP details be sure to include the port on URL's if you are not deploying on the standard ports of 80 or 443 which IS the case for most standalone tomcat installations. Changing this later can prove to be difficult so plan your access URL's before proceeding. For most standalone tomcat installs you will want to append port 8080 to each URL or host entry.

Feedback

We aim to continually improve this documentation set to make it as easy as possible for new users and seasoned users alike to setup the ESOE. We welcome any comments or additions you may have on the ESOE users mailing list at any time.

Also available in: HTML TXT