TWiki> Public Web>PalConcepts>HttpPool (revision 3)EditAttach

Http Pool

Under construction...

This page serves as the main documentation for running an HTTP server pool. The corresponding client pool is contained in the build and not covered here. Most of this page is about configuring Tomcat to run servlets using the HCSS in general, rather than specifically HttpPool.


The server pool requires a web server that supports Java servlets. This page assumes that Tomcat is used for this purpose. It should work with the latest version (6.0.18 at the time of writing). The first step then is to install Tomcat, although adding the pool servlet to an existing installation is also fine. Note that this does not detail all possible configurations that experts may wish to set up, but a single simple one.

Note that only one HTTP pool server is needed, regardless of the number of pools it accesses.

There is no need to install Tomcat in a privileged account, and probably good security reasons for not doing so. Set the environment variable CATALINA_HOME to point to the directory where it is installed. You can also use the CATALINA_OPTS variable to set JVM options. This should be used to increase the available memory. My settings look like this:

CATALINA_OPTS=-server -Xmx4096m

The global configuration files are in Tomcat's conf directory. You should only need to make minor changes to server.xml. The default port is 8080 and defined in the server.xml file. You can change this if you like, but running on a privileged port makes things a bit more complicated, see below.

User Access Control

I recommend enabling this for two reasons:

  1. If you do not your pools will be open to the world...
  2. It makes troubleshooting easier as you can see who is doing what in the logs.

There are several ways to set this up with Tomcat. I use the simplest, which is what is described here. Its main disadvantage is that it does not scale well to large numbers of users and major enterprise systems. See the Tomcat documentation for other possibilities.

Edit the server.xml file in the conf directory. Look for the Realm entry and specify digest as SHA. It should now look like this:

      <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
             resourceName="UserDatabase" digest="SHA"/>

Edit the tomcat-users.xml file in the conf directory. Add some roles, like this:

  <role rolename="spire_admin"/>
  <role rolename="spire_user"/>
You might want to leave the tomcat role as a placeholder for future general Tomcat admin.

This is how to add a user.

  1. Get a user name and password. Passwords should not be the same as login passwords, as while they are encrypted, the means used is not particularly secure. There are no restrictions on passwords. The main purpose is to offer some protection and log who is doing what and when.
  2. Encrypt the password. The command is java -cp $CATALINA_HOME/lib/catalina.jar:$CATALINA_HOME/bin/tomcat-juli.jar org.apache.catalina.realm.RealmBase -a SHA password. You may wish to define an alias for this...
  3. Edit the file tomcat-users.xml and add a new user line. password should be set to the encrypted password and roles should normally be set to the user role above (give yourself admin as well).

Adding a servlet

Servlets live inside the webapps directory. Applications have their own area in this directory and run in a sandbox isolated from the others. Note that a single application area can contain any number of servlets.

Adding the Http pool servlet

Starting and stopping

The scripts can be found in Tomcat's bin directory. Use startup to start it, and shutdown to stop it. You may wish to check the catalina.out log to see if it started correctly.

Tomcat should automatically notice if a new servlet is defined and load it. You can force a servlet to reload by starting and stopping Tomcat. Wait a few seconds between stopping and starting or it might get confused (see next section). There is also a Tomcat "Manager" application that can do this from a web interface without stopping Tomcat - see the Tomcat documentation for details.

Occasionally it can get in a mess, which can be caused by things such as running out of memory, and refuse to restart. In this case you should see a message in the log along the lines of:

LifecycleException:  Protocol handler initialization failed: Address already in use:8080
In this case you need to kill the process (look for catalina) before restarting it.


It is important to understand that the Tomcat scripts do not use the Java CLASSPATH environment variable. All required resources must be present in the classes or lib directories. For full details read the section on "Classloading" in the Tomcat documentation.

The first rule of troubleshooting is to check the log file. The principle log file is $CATALINA_HOME/logs/catalina.out.

Running on a privileged port

This is normally the standard HTTP port 80. The port is set by editing the server.xml file in the conf directory. I was not able to get the default Tomcat startup script to work when installed on this port. Here is my script:

# Adapt the following lines to your configuration

case "$1" in
    # Start Tomcat
    $CATALINA_HOME/bin/jsvc \
    -user $TOMCAT_USER \
    -home $JAVA_HOME \
    -Dcatalina.home=$CATALINA_HOME \$TMP_DIR \
    -Djava.library.path=$VERSANT_ROOT/lib:$VERSANT_ROOT/lib/jvi/1p \
    -outfile $CATALINA_HOME/logs/catalina.out \
    -errfile '&1' \
    -cp $CLASSPATH \
    # To get a verbose JVM
    #-verbose \
    # To get a debug of jsvc.
    #-debug \

    # Stop Tomcat
    PID=`cat /var/run/`
    kill $PID

    echo "Usage start/stop"
    exit 1;;

This script must be started with root privilege. Note that the daemon still runs as a less privileged user.

Further complications arise if there is a need to access the Versant library, as this accesses native shared libraries, e.g. for DbPool or the TM/data frame server. Whilst the startup script uses the java.library.path argument to pass the location of these libraries to the daemon process, this does not entirely work since the first called library then calls other libraries, which does not work since the process does not inherit the value of the LD_LIBRARY_PATH environment variable (it defines its own). A workaround solution is to link to the required libraries from the Java installation, which is accessible, e.g.

cd  $JAVA_HOME/jre/lib/amd64
ln -s $VERSANT_ROOT/lib/
ln -s $VERSANT_ROOT/lib/

Note that this is only necessary since the server is running as a daemon process in order to access the privileged port 80. There may well be a better solution than this.

Using the telemetry and data frame server

-- SteveGuest - 23 Apr 2009

Edit | Attach | Watch | Print version | History: r34 | r5 < r4 < r3 < r2 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r3 - 2009-04-24 - SteveGuest
This site is powered by the TWiki collaboration platform Powered by Perl