Java SPEP Installation Guide

Authors
Bradley Beddoes

Applicable versions
0.9+

We no longer support JVM 1.4 releases.

For OC4J installations, please also refer to the OC4J SPEP Installation Guide

Preparing your server

To successfully operate the Java SPEP your server must be accessible on port 443 from the ESOE system. You can ask your ESOE system administrator for the IP addresses ESOE will connect from if your running a restrictive firewall policy and update it appropriately. In some circumstances your administrator may allow you to configure port 80 unsecured SPEP instances. This is a per installation decision which your ESOE system administrator can advise you of.

The distribution of SPEP comes with 3 gziped tared files:

  1. Extract spep-endorsed.tar.gz to your $TOMCAT/common/endorsed directory
  2. Extract spep.tar.gz and copy the spep.war file to $TOMCAT/webapps
  3. Create a core directory to store spep artifacts, a sub directory called config to store configuration and a sub directory called logging for log files. This must be readable by the user tomcat runs as. e.g /opt/spep/config and /opt/spep/logging
  4. Copy the spep.config file to the configuration directory e.g /opt/spep/config/spep.config
  5. At this point you have a choice in how to advise the SPEP install of your configuration location
    1. Java Property (RECOMMENDED). Export a java property called spep.data to your Java environment when tomcat starts. This should be set to the top level artifacts directory. e.g -Dspep.data=/opt/spep
    2. Create a Java properties file called spepvars.config and place it in $tomcat/webapps/spep/WEB-INF/ this is a standard java properties file format, set the variable spep.data to the same value you would above. We don't recommend this method though it may be useful in a multi spep environment, be sure to save your spepvars.config file safely, it will need to be copied back to the web application on each upgrade you perform, it may also be wise to recreate the shipped spep.war file with this file stored inside before starting tomcat.

The distribution of SPEP also comes with another gziped tared file called spepfilter.tar.gz this contains several jar files which you must locate in each web applications WEB-INF/lib directory that your deploying.

Registering the SPEP with ESOE Manager

Ask your ESOE administrator, or see this page for information if you manage your ESOE instance.

Service configuration

Retrieve your service configuration and keystore from ESOE Manager, or from your ESOE administrator.

This page shows you the configuration values that need to be set up in the spep.config file, which can be found at the location you've earlier configured for spep.data.

For each of the configuration options shown by the ESOE Manager service node configuration page, enter the corresponding value for the current node in its spep.config file.

It is very important that each node's configuration be correct. There may be some differences between them.

The keystore will be the same for all nodes. Store the keystore as spep.data/config/spepKeystore.ks

Protecting your webapp

There are 2 steps to configuring a web application to be protected by the SPEP:

  1. Edit the tomcat/webapps/_yourapp_/WEB-INF/web.xml file so that it uses the filter.
  2. Configure your webapp for cross context access.

The following should be placed in the web.xml file for your webapp to protect it with the filter:

<filter>
    <filter-name>spep-filter</filter-name>
    <filter-class>com.qut.middleware.spep.filter.SPEPFilter</filter-class>

    <init-param>
        <param-name>spep-context</param-name>
        <param-value>/spep</param-value>
    </init-param>
</filter>

<filter-mapping>
    <filter-name>spep-filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

The param-value for the spep-context parameter should be changed to the location of the SPEP webapp in your Tomcat instance. By default this is /spep. The url-pattern in the filter-mapping section describes which part of the webapp to protect. By matching /* we protect the entire webapp.

Important note about cross context access
The SPEP webapp by default operates in the /spep context, or in whichever context it is placed. In order to have different paths such as /secure which are protected by an SPEP filter, cross context access needs to be enabled. This is enabled by default, by the context.xml file in the META-INF/context.xml.

Your application MUST also be enabled for cross context. To enable cross context access, the following should be placed in tomcat/webapps/_yourapp_/META-INF/context.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Context path="/secure" crossContext="true">
  <WatchedResource>WEB-INF/web.xml</WatchedResource>
  <WatchedResource>META-INF/context.xml</WatchedResource>
</Context>

Logging

SPEP ships with support for Log4j logging. Each spep.war ships with a log4j configuration pointing at spep.data/logging for file output and by default logs at the INFO level. You may choose to modify this to suit your own needs but for general production usage INFO is considered sufficient.

Run the environment

Your environment is now able to be started, we reccomend you watch logging closely for the first little while to make sure all configuration is in order at which time you can lower the output of SPEP logging from DEBUG to INFO. To invoke spep simply point your browser at http://<<server [:port]>/__your__app/

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 an SPEP. We welcome any comments or additions you may have on the ESOE users mailing list at any time.

Also available in: HTML TXT