Difference: HttpPool (1 vs. 34)

<-- ANALYTICS CODE - DO NOT EDIT -->

<-- Google Analytics script BEGIN -->

<-- Google Analytics script END -->

<-- END OF ANALYTICS CODE -->

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

The HTTP pool servlet

• ia_pal_pool_http_server (the PAL HTTP server)
• access_server (telemetry and data frame server)

1. It sets up user authentication for this area (note that different authentication can be applied to different application areas).
2. It defines a compression filter. This is for performance reasons; the effect is TBC.

1. You need only one property set, and that is var.hcss.dir within CATALINA_OPTS. It is recommended that this be set to the WEB-INF directory of the application.
2. Create a directory config/properties in that directory.
3. Place any desired property files in that directory. They must have the extenstion .properties.

Trying it out

Running on a privileged port

Using the telemetry and data frame server

hcss.access.server.default

If a server is not specified, use this one. It itself defaults to localhost.

hcss.access.server.redirect

Redirect all database server requests to this one. The purpose of this is to ensure that operationally critical servers cannot be accessed by this process; the data of course has to be present on the server redirected to.

Using Tomcat's Manager application

• Add the manager role to tomcat-users.xml and add the role to your username.
• Edit the web.xml file for the manager application and change the manager role to spire_admin or whatever.

1. GeHcss.[objectObject] a user namHcss.[objectObject] and password. Passwords should not bHcss.[objectObject] thHcss.[objectObject] samHcss.[objectObject] as login passwords, as whilHcss.[objectObject] they arHcss.[objectObject] encrypted, thHcss.[objectObject] means used is noHcss.[objectObject] particularly securHcss.[objectObject]. TherHcss.[objectObject] arHcss.[objectObject] nHcss.[objectObject] restrictions on passwords. ThHcss.[objectObject] main purposHcss.[objectObject] is tHcss.[objectObject] offer somHcss.[objectObject] protection and log whHcss.[objectObject] is doing whaHcss.[objectObject] and when.
2. EncrypHcss.[objectObject] thHcss.[objectObject] password. ThHcss.[objectObject] command is java -cp $CATALINA_HOME/liHcss.[objectObject]/catalina.jar:$CATALINA_HOME/bin/tomcaHcss.[objectObject]-juli.jar org.apachHcss.[objectObject].catalina.realm.RealmBasHcss.[objectObject] -a SHA password. You may wish tHcss.[objectObject] definHcss.[objectObject] an alias for this...
3. EdiHcss.[objectObject] thHcss.[objectObject] filHcss.[objectObject] tomcaHcss.[objectObject]-users.xml and add a new user linHcss.[objectObject]. password should bHcss.[objectObject] seHcss.[objectObject] tHcss.[objectObject] thHcss.[objectObject] encrypted password and roles should normally bHcss.[objectObject] seHcss.[objectObject] tHcss.[objectObject] thHcss.[objectObject] user rolHcss.[objectObject] abovHcss.[objectObject] (givHcss.[objectObject] yourself admin as well).

Adding a servleHcss.[objectObject]

ThHcss.[objectObject] HTTP pool servleHcss.[objectObject]

• ia_pal_pool_http_server (thHcss.[objectObject] PAL HTTP server)
• access_server (telemetry and data framHcss.[objectObject] server)

1. IHcss.[objectObject] sets up user authentication for this area (notHcss.[objectObject] thaHcss.[objectObject] differenHcss.[objectObject] authentication can bHcss.[objectObject] applied tHcss.[objectObject] differenHcss.[objectObject] application areas).
2. IHcss.[objectObject] defines a compression filter. This is for performancHcss.[objectObject] reasons; thHcss.[objectObject] effecHcss.[objectObject] is TBC.

1. You need only onHcss.[objectObject] property seHcss.[objectObject], and thaHcss.[objectObject] is var.hcss.dir within CATALINA_OPTS. IHcss.[objectObject] is recommended thaHcss.[objectObject] this bHcss.[objectObject] seHcss.[objectObject] tHcss.[objectObject] thHcss.[objectObject] WEB-INF directory of thHcss.[objectObject] application.
2. CreatHcss.[objectObject] a directory config/properties in thaHcss.[objectObject] directory.
3. PlacHcss.[objectObject] any desired property files in thaHcss.[objectObject] directory. They must havHcss.[objectObject] thHcss.[objectObject] extenstion .properties.

Trying iHcss.[objectObject] ouHcss.[objectObject]

Running on a privileged porHcss.[objectObject]

Using thHcss.[objectObject] telemetry and data framHcss.[objectObject] server

hcss.access.server.defaulHcss.[objectObject]

If a server is noHcss.[objectObject] specified, usHcss.[objectObject] this onHcss.[objectObject]. IHcss.[objectObject] itself defaults tHcss.[objectObject] localhosHcss.[objectObject].

hcss.access.server.redirecHcss.[objectObject]

RedirecHcss.[objectObject] all databasHcss.[objectObject] server requests tHcss.[objectObject] this onHcss.[objectObject]. ThHcss.[objectObject] purposHcss.[objectObject] of this is tHcss.[objectObject] ensurHcss.[objectObject] thaHcss.[objectObject] operationally critical servers cannoHcss.[objectObject] bHcss.[objectObject] accessed by this process; thHcss.[objectObject] data of coursHcss.[objectObject] has tHcss.[objectObject] bHcss.[objectObject] presenHcss.[objectObject] on thHcss.[objectObject] server redirected tHcss.[objectObject].

Using TomcaHcss.[objectObject]'s Manager application

• Add thHcss.[objectObject] manager rolHcss.[objectObject] tHcss.[objectObject] tomcaHcss.[objectObject]-users.xml and add thHcss.[objectObject] rolHcss.[objectObject] tHcss.[objectObject] your usernamHcss.[objectObject].
• EdiHcss.[objectObject] thHcss.[objectObject] weHcss.[objectObject].xml filHcss.[objectObject] for thHcss.[objectObject] manager application and changHcss.[objectObject] thHcss.[objectObject] manager rolHcss.[objectObject] tHcss.[objectObject] spire_admin or whatever.

Updating an existing installation

This is all that is necessary to update to a new HCSS version:

cd $CATALINA_HOME/webapps/hcss/WEB-INF/
rm lib/*.jar
copyBuildJars lib/
cp <hcss-dir>/project.xml .

Then restart the server.

1. You need only one property set, and that is var.hcss.dir within CATALINA_OPTS. It is recommended that this be set to the WEB-INF directory of the application.
2. Create a directory config/properties in that directory.
3. Place any desired property files in that directory. They must have the extenstion .properties.

Note that the user.props of the user owning the Tomcat process will also be read if it exists and with higher precedence. You might not want this. This is one reason for running the server from a dedicated account rather than a standard user account.

HCSS properties configuration

Follow the steps below to set HCSS properties:

1. you need only one property set, and that is

   var.hcss.dir 

   within the CATALINA_OPTS.
2. create a directory config/properties in that directory
3. copy your favourite property files (the files with extension ".properties" ) into there.

The HTTP pool servlet

HcssScr:6672

The system property hcss.init.logging should be set to false. It will not work to add it user.props or any other HCSS property file! You can add it to CATALINA_OPS, which now looks something like this:

Sometimes there is no substitute for putting debugging statements in the code. You can do this by making modifications in a developer environment as normal, and then copying the class file(s) into the classes directory of the servlet. For example:

cvs co ia_pal_pool_http_server
edit HttpPoolServlet.java
jake

If a needed library is somehow missing, it is possible to be plagued by the dreaded NoClassDefFoundError. The class reported to be missing is not necessarily the one that is. If you know it's there, follow the dependency trail from the reported class to look for something missing. Pay particular attention to what is used in static initialisation statements.

• release_m_n.jar

• versant_store_m_n.jar
• versant_tools_schema_m_n.jar

• access_server_m.n.jar

• vanilla_m_n.jar

It is also necessary to create the application configuration file web.xml in WEB-INF. A version with a servlet defined is in the next section. You can also look at the versions of this file in the other applications that come preinstalled with Tomcat.

"Old/new" style configuration

CIB Configuration

These libraries are needed by all servlets:

• ia_dataset_m.n.jar
• ia_io_m.n.jar
• ia_numeric_m.n.jar
• share_m.n.jar
• share_fltdyn_m.n.jar

These libraries are needed to run the PAL servlet:

• ia_pal_m.n.jar
• ia_pal_pool_http_m.n.jar
• ia_pal_pool_http_server_m.n.jar
• ia_pal_pool_lstore_m.n.jar
• ia_server_util_m.n.jar
• jython.jar
• share_interpreter_m.n.jar
• share_predicate_m.n.jar
• share_unit_m.n.jar

These libraries are needed to run telemetry and data frames servlet:

• access_m.n.jar
• ccm_m_n.jar
• jvi7.0.1-jdk1.4.jar
• store_m_n.jar
• tmproc_m_n.jar
• versant_store_m_n.jar
• versant_ccm_m_n.jar

Using Tomcat's Manager application

• Add the manager role to tomcat-users.xml and add the role to your username.
• Edit the web.xml file for the manager application and change the manager role to spire_admin or whatever.

Then go to the "manager/html" web page on your server. I found that with my configuration I was getting HTTP 401 errors when I tried this. I got it to work by commenting out the error-page entry in the manager web.xml file.

Traceback (innermost last):
  File "<string>", line 1, in ?
  File "/Users/hcssbld/hcss_builds/dp-hifi_current/lib/herschel/__init__.py", line 128, in ?
  File "/Users/hcssbld/hcss_builds/dp-hifi_current/lib/herschel/__init__.py", line 48, in recursive_module_lookup
ImportError: no module named javaos

        at org.python.core.Py.ImportError(Py.java:184)
        at org.python.core.imp.import_first(imp.java)
        at org.python.core.imp.import_name(imp.java)
        at org.python.core.imp.importName(imp.java)

Logging configuration

Tomcat will normally by default write log messages to catalina.out, but it is generally better for applications to write to their own logs. However the reinitialisation of Java logging performed by the Configuration class can interfere with Tomcat's logging and prevent it from working properly, see HcssScr:6672.

In the classes directory under hcss create a file called logging.properties like this:

handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

org.apache.juli.FileHandler.level = FINE
org.apache.juli.FileHandler.directory = ${catalina.base}/logs
org.apache.juli.FileHandler.prefix = hcss.
org.apache.juli.FileHandler.formatter = herschel.share.log.api.StandardFormatter

java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = herschel.share.log.api.StandardFormatter

Now make a patch to Configuration to stop it interfering:

cvs co develop/main/herschel/share/util/Configuration.java
cp develop/main/herschel/share/util/Configuration.java herschel/share/util
cd herschel/share/util
Edit Configuration.java and comment out the line LogInitialiser.init();
javac Configuration.java

The hcss application area should now log to a file called hcss.date.log.

hcss.access.store = herschel.access.db.SimpleStoreHandler

hcss.access.server.default

If a server is not specified, use this one. It itself defaults to localhost.

hcss.access.server.redirect

Redirect all database server requests to this one. The purpose of this is to ensure that operationally critical servers cannot be accessed by this process; the data of course has to be present on the server redirected to.

This servlet is accessed by using the normal access API. These client-side properties need to be set:

hcss.access.connection=herschel.access.net.NetworkConnection
hcss.access.authentication=true
hcss.access.url=http://whatever:8080/hcss/tm

Convenience methods to set these properties dynamically are provided in the herschel.access.Access class.

-- SteveGuest - 28 Apr 2009

SEVERE: Failed to create pool Traceback (innermost last):
  File "<string>", line 1, in ?
ImportError: no module named herschel

Trying it out

Following the instructions above and starting Tomcat, we should now have a running PAL server with url http://whatever:8080/hcss/pal. Check the log for any initialisation errors. Here is an example Jython script for trying it out on the client side:

from herschel.ia.pal.pool.http import HttpClientPool
pool = HttpClientPool ("http://wakefield.bnsc.rl.ac.uk/hcss/pal", "sims3")
st = ProductStorage (pool)
st.authenticate()
r = st.select (Query (ObservationContext, "1"))

hcss - WEB-INF - lib
               - classes

The general idea is to put jar files in the lib directory and class files in classes. Everything you need should be in there. Don't assume that it will pick up your CLASSPATH environment variable - it won't.

Things are currently a little confused due to the transition period between the "new style" and the "continuous integration builds", and I am unsure about the best way to do some things right now. The following section mostly refers to the "new-style" builds.

Copy these libraries into the lib directory:

• hcss-core.jar
• dp-core.jar
• dp-{inst}.jar
• hcssExtLibs.jar (needs workaround first, see below)
• jvi7.0.1-jdk1.4.jar (only required if you need database access)

These libraries should be updated whenever a new version of the HCSS is deployed, although in practice it usually continues working anyway (except for schema evolutions which kill database accessing servlets).

For the hcssExtLibs library, it is necessary to work around HcssSpr:5410. You can do it like this:

1. Put the library in an empty temporary directory.
2. Extract the contents with jar xf hcssExtLibs.jar.
3. Delete the directory javax/servlet.
4. Delete the jar file itself.
5. Recreate it with jar cf hcssExtLibs.jar *

It is also necessary to create the application configuration file web.xml in WEB-INF. A version with a servlet defined is in the next section. You can also look at the versions of this file in the other applications that come preinstalled with Tomcat.

• ia_server_util (utility classes)
• ia_pal_pool_http_server (the PAL HTTP server)
• access_server (telemetry and data frame server)

These can be installed by either checking them out from CVS and compiling them, or using the CIB installer and extracting the jar files (see reference to current uncertainty above).

CVS method

This method is a little messy, but does have the advantage that it leaves you with an already set up developer environment, which is useful for troubleshooting.

From the classes directory, get the source code and put it in the right place, e.g.

cvs export -r D_IA_SERVER_UTIL_0_2 develop/main/herschel/ia/server/util
cp -r develop/main/herschel/ia/server herschel/ia

Now do the same for the ia_pal_pool_http_server module, e.g.

cvs export -r D_IA_PAL_POOL_HTTP_SERVER_0_2 develop/main/herschel/ia/pal/pool/http/server
mv develop/main/herschel/ia/pal herschel/ia

Then compile the source code (javac will do). The source files can be left there and as an aid to debugging, although Tomcat won't look at them.

CIB method

Application configuration

Now create the web.xml file in the WEB-APPS directory that will tell Tomcat what to do with all this lot. It should look something like this (you can paste this directly, but don't forget to change the role names to your instrument):

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

<web-app>

    <display-name>HCSS applications</display-name>
    <description>
    Servlets that use the HCSS.
    </description>

    <filter>
        <filter-name>GzipFilter</filter-name>
        <filter-class>herschel.ia.server.util.GzipFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>GzipFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    <servlet>
        <servlet-name>pal</servlet-name>
        <servlet-class>herschel.ia.pal.pool.http.server.HttpPoolServlet</servlet-class>
        <init-param>
            <param-name>allowLoadAccess</param-name>
            <param-value>true</param-value>
        </init-param>
        <init-param>
            <param-name>allowSaveAccess</param-name>
            <param-value>false</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>pal</servlet-name>
        <url-pattern>/pal</url-pattern>
    </servlet-mapping>

  <security-constraint>
    <web-resource-collection>
       <web-resource-name>Protected Area</web-resource-name>
       <url-pattern>/</url-pattern>
    </web-resource-collection>
    <auth-constraint>
       <!-- Anyone with one of the listed roles may access this area -->
       <role-name>spire_user</role-name>
       <role-name>spire_admin</role-name>
    </auth-constraint>
  </security-constraint>

  <!-- Default login configuration -->
  <login-config>
    <auth-method>BASIC</auth-method>
  </login-config>

  <!-- Security roles referenced by this web application -->
  <security-role>
    <role-name>spire_user</role-name>
    <role-name>spire_admin</role-name>
  </security-role>

</web-app>

This example does two things in addition to defining the servlet:

1. It sets up user authentication for this area (note that different authentication can be applied to different application areas).
2. It defines a compression filter. This is for performance reasons; the effect is TBC.

HCSS configuration

These properties should be set for the PAL server to work correctly. You can put them in user.props.

hcss.interpreter.python.path = {${var.hcss.dir}/lib}
hcss.ia.io.fits.handle_missing_classes = true

Additionally you may wish to configure pool locations etc, for example:

hcss.ia.pal.pool.lstore.dir=/misc/winchester1/data/products

Then add this servlet definition to the web.xml file in WEB-APPS.

    <servlet>
        <servlet-name>tm</servlet-name>
        <servlet-class>herschel.access.server.HcssTmHttpServer</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>tm</servlet-name>
        <url-pattern>/tm</url-pattern>
    </servlet-mapping>

Adding a servlet

Adding the Http pool servlet

Starting and stopping

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: java.net.BindException: Address already in use:8080

CATALINA_HOME=/home/spire/hcssbld/tomcat
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 and web.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"/>

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).

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.

Installation

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.

Troubleshooting

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.

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. The default Tomcat startup script does not work when installed on this port. Here is my script:

# Adapt the following lines to your configuration
JAVA_HOME=/home/spire/hcssbld/java/jdk1.6.0_10/
CATALINA_HOME=/home/spire/hcssbld/tomcat
TOMCAT_USER=hcssbld
TMP_DIR=/var/tmp
CATALINA_OPTS=-Xmx4096m
CLASSPATH=\
$JAVA_HOME/lib/tools.jar:\
$CATALINA_HOME/bin/commons-daemon.jar:\
$CATALINA_HOME/bin/bootstrap.jar

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

  stop)
    #
    # Stop Tomcat
    #
    PID=`cat /var/run/jsvc.pid`
    kill $PID
    ;;

  *)
    echo "Usage tomcat.sh start/stop"
    exit 1;;
esac

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/liboscfe.so liboscfe.so
ln -s $VERSANT_ROOT/lib/libxa.so libxa.so

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