Hyrax - OLFS Configuration

From OPeNDAP Documentation
Jump to: navigation, search

This document should help you get started configuring the OLFS component of Hyrax. This servlet was developed, compiled, and tested using the java 1.5.0 compiler, the 1.5.0 Java Virtual Machine, and Jakarta Tomcat 6.x.x (which also provided the javax.servlet packages).

Note: All Examples of web.xml configurations in this document were checked against Jakarta Tomcat 6.0.14

The OLFS web application is composed of two servlets, the OLFS servlet and the Docs servlet.

  • The OLFS servlet does the majority of the work in the OLFS web application. It does this by providing a flexible "dispatch" mechanism through which incoming requests are evaluated by a series of DispatchHandlers (pieces of software) that can choose to handle the request, or ignore it. The OLFS ships with a standard set of DispathHandlers which handle requests for OPeNDAP data products, THREDDS catalogs, and OPeNDAP directories. These defalut DispatchHandlers can be augmented by adding custom handlers without the need to recompile the software. All of the DispatchHandlers used by the OLFS are identified in the olfs.xml configuration file.
  • The Docs servlet provides clients access to a tree of static documents. By default a minimal set of documents are provided (containing information about Hyrax), these can be replaced by user supplied documents and images. By changing the images and documents available through the Docs servlet the data provider can further customize their Hyrax installtion.

Contents

1 OLFS Servlet Configuration

The OLFS servlet is the front end (public interface) for Hyrax. It provides THREDDS catalogs, directory views, logging, and authentication services. The OLFS relies on one or more instances of the [BES] to provide it with data access and basic catalog metadata.

1.1 Dispatch Handlers

Request dispatch is the process in through which the OLFS determines what actual piece of code is going to respond to a given incoming request. This version of the OLFS handles each incoming request by offering the request to a series of DispatchHandlers. Each DispatchHandler is asked if it can handle the request. The first DispatchHandler to say that it can is then asked to handle the request. The OLFS creates an ordered list of DispatchHandlers by reading the olfs.xml.

The order of the list is significant. There is no guarantee that two (or more) DispatchHandlers may claim a particular request. Since the first DispatchHandler in the list to claim a request gets to service it, changing the order of the DispatchHandlers can change the behaviour of the OLFS (and thus of Hyrax). For example the URL:

http://localhost:8080/opendap/data/ 

Is recognized by both the DirectoryDispatchHandler and the ThreddsDispatchHandler as a request for a directory view: both can provide a such a view. However, only the DirectoryDispatchHandler can be configured to not claim the request and pass it on for another handler (in this case the ThreddsDispatchHandler) to pickup. The result is that if you put the ThreddsDispatchHandler prior to the DirectoryDispatchHandler on the list there will be no possible way to get OPeNDAP directory view - the ThreddsDispatchHandler will claim them all.

The usefulness of this dispatching scheme is that it creates extensibility. If a third party wishes to add new functionality to Hyrax one way is to write a DispatchHandler. To incorporate it into Hyrax they only need to add it to the list in the olfs.xml and add the java classes to the Tomcat lib directory.

1.2 Files

The OLFS servlet gets its configuration from 4 files. In general all of your configuration need will be met by making changes to the first two: olfs.xml and catalog.xml located in the 'persistent content directory': $CATALINA_HOME/content/opendap

olfs.xml
role: Contains the localized OLFS configuration - location of the BES(s), directory view instructions, etc.
location: In the persistent content directory which by default is located at $CATALINA_HOME/content/opendap/
catalog.xml
role: Master(top-level) THREDDS catalog content for static THREDDS catalogs.
location: In the persistent content directory which by default is located at $CATALINA_HOME/content/opendap/
web.xml
role: Core servlet configuration.
location: The servlet's web.xml file located in the WEB-INF directory of the web application "opendap". Typically that means $CATALINA_HOME/webapps/opendap/WEB-INF/web.xml
log4j.xml
role: Contains the logging configuration for Hyrax.
location: The default location for the log4j.xml is in the WEB-INF directory of the web application "opendap". Typically that means $CATALINA_HOME/webapps/opendap/WEB-INF/log4j.xml However, Hyrax can be configured to look in additional places for the log4j.xml file. Read More About It Here.

2 olfs.xml Configuration File

For those of you that already have Hyrax this change will render your current olfs.xml obsolete. You have two options, either:

1) Remove the directory $CATALINA_HOME/content/opendap. Restarting Tomcat will cause it to be recreated with a new compatible olfs.xml file.

OR

2) Copy the file from the web application:

cp $CATALINA_HOME/webapps/opendap/initialContent/olfs.xml $CATALINA_HOME/content/opendap

Then read the rest of this section to localize your new installation.

The olfs.xml file contains the core configuration of the OLFS. It identifies all of the DispatchHandlers to be used by the OLFS, at it must identify at least one BES to be paired with the OLFS and it controls both view and access behaviours of the OLFS servlet.

2.1 OLFSConfig element

The <OLFSConfig> element is the document root and it contains three elements that suppy the configuration for the OLFS: <BESConfig>, <DirectoryView>, and <AllowDirectDataSourceAccess >

2.2 <DispatchHandlers> element

The <DispatchHandlers> element has two child elements: <HttpGetHandlers> and <HttpPostHandlers>. The <HttpGetHandlers> contains and ordered list of the DispatchHandler classes used by the OLFS to handle incoming HTTP GET requests.

2.2.1 <HttpGetHandlers> element

The <HttpGetHandlers> contains and ordered list of the DispatchHandler classes used by the OLFS to handle incoming HTTP GET requests. The list order is significant, and permutating the order will (probably negatively) change the behavior of the OLFS. Each DispatchHandler on the list will be asked to handle the request. The first DispatchHandler on the list to claim the request will be asked to build the response.

2.2.2 <HttpPostHandlers> element

The <HttpPostHandlers> contains and ordered list of the DispatchHandler classes used by the OLFS to handle incoming HTTP POST requests. The list order is significant, and permutating the order will (probably negatively) change the behavior of the OLFS. Each DispatchHandler on the list will be asked to handle the request. The first DispatchHandler on the list to claim the request will be asked to build the response.

2.2.2.1 <Handler> elements

Both the <HttpGetHandlers> and <HttpPostHandlers> contain an orderd list of <Handler> elements. Each <Handler> must have an attribute call className whose value is set to the fully qualified Java class name for the DispatchHandler implementation to be used. For example:

           <Handler className="opendap.bes.VersionDispatchHandler" />

Names the class opendap.bes.VersionDispatchHandler.

Each <Handler> element may contain a collection of child elements that provide configuration information to the DispatchHandler implementation. In this example:

           <Handler className="opendap.bes.DirectoryDispatchHandler">
               <DefaultDirectoryView>OPeNDAP</DefaultDirectoryView>
           </Handler>

The <Handler> element contains a child element <DefaultDirectoryView> that specifies the default directory view for Hyrax to the DirectoryDispatchHandler class.

2.3 HTTP GET Handlers

Hyrax uses the following DispatchHandlers to handle HTTP GET requests:

  • BESManager - Provides configuration and access to the BES(s) for the other handlers.
  • BotBlocker - This optional handler may be used to block access to your server individual IP addressesl or groups of IP addresses.
  • StaticCatalogDispatch - Provides static THREDDS catalog services for Hyrax.
  • DapDispatchHandler - Handles all DAP requests.
  • DirectoryDispatchHandler - Handles the OPeNDAP directory view (contents.html) requests.
  • SpecialRequestDispatchHandler - Handles special requests (help, system properties, staus, etc.)
  • VersionDispatchHandler - Handles the version document requests.
  • FileDispatchHandler - Handles requests for file level access. (README files etc.)
  • BESThreddsDispatchHandler - Provides dynamic THREDDS catalogs of all BES holdings..

2.3.1 BESManager

Provides configuration and access to the BES(s) for the other handlers. This DispatchHandler is key to the function of Hyrax. In it each BES that is connected to a Hyrax installation is defined. The following examples will show a single BES example. For more information on configuring Hyrax to use multiple BES's look here.

Each BES is identified using a seperate <BES> child element inside of the <Handler> element that references the BESManager class.

2.3.1.1 <BES> element

The <BES> element provides the OLFS with connection and control information for a BES. There are 4 child elements in a <BES> element: <prefix>, <host>, <port>, and <ClientPool>

2.3.1.1.1 <prefix> element

This element contains the URL prefix that the OLFS will associate with this BES. This provides a mapping bewteen this BES to the URI space serviced by the OLFS. Essentailly what this means is that the prefix is a token that is placed between the host:port/context/ part of the Hyrax URL and the catalog root used to designate a particular BES instance in the case that multiple BES's are available to a single OLFS. For a single BES (the default configuration) the tag MUST be designated by "/". The prefix is used to provide a mapping for each BES connected to the OLFS to URI space serviced by the OLFS.

  1. There must one (but only one) BES element in the BESManager handler configuration whose prefix has a value of "/" (see example 1). There may be more than one <BES> but there must be at least that one.
  2. For a single BES (the one with "/" as it's prefix) no additional effort is required. However, when using multiple BES's it is neccesary that each BES have a mount point exposed as a directory (aka collection) in URI space where it's going to appear. See Configuring With Multiple BES's for more information.
  3. The prefix string must always begin with the slash ("/") character. (see example 2)

example 1:

<prefix>/</prefix>

example 2:

<prefix>/data/nc</prefix>
2.3.1.1.2 <host> element

This element contains the host name or IP address of the BES.

example:

<host>test.opendap.org</host >
2.3.1.1.3 <port> element

The port number on which the BES is listening.

example:

<port>10022</port >
2.3.1.1.4 <ClientPool> element

Configures the behavior of the pool of client connections that the OLFS maintains with the BES. These connections are pooled for efficiency and speed. Currently the only configuration item available is to control the maximum number of concurrent BES client connections that the OLFS may make, the default is 10, but the size should be optimized for your locale by empirical testing. The size of the Client Pool is controlled by the maximum attribute.

example:

<ClientPool maximum="17" />

If the <ClientPool> element is missing the pool size defaults to 10.

2.3.2 BotBlocker (optional)

This optional handler can be used to block access from specific IP addresses and by a ranges of IP addresses using a regular expressions. It turns out that many of the web crawling robots do not respect the robots.txt file when one is provided. Since many sites do not want their data holdings exhaustively queried by automated software, we created a simple robot blocking handler to protect system resources from non-compliant robots.

2.3.2.1 <IpAddress> element

The text value of this element should be the IP address of a system which you would like to block from accessing your service. For example:

   <IpAddress>128.193.64.33</IPAddress>

Blocks the system located at 128.193.64.33 from accessing your server. There can be zero or more <IpAddress> elements in the <BotBlocker>

2.3.2.2 < IpMatch > element

The text value of this element should be the regular expression that will be used to match the IP addresses clients attempting to access Hyrax.

For example:

       <IpMatch>65\.55\.[012]?\d?\d\.[012]?\d?\d</IpMatch>

Matches all IP address beginning with 65.55 and thus block access for clients whose IP addresses lie in that range. There can be zero or more < IpMatch > elements in the Handler configuration for teh BotBlocker

2.3.2.3 Example Configuration Element

    <Handler className="opendap.coreServlet.BotBlocker">

        <IpAddress>127.0.0.1</IpAddress>

        <!-- This matches all IPv4 addresses, work yours out from here.... -->
        <!--<IpMatch>[012]?\d?\d\.[012]?\d?\d\.[012]?\d?\d\.[012]?\d?\d</IpMatch> -->

        <!-- Any IP starting with 65.55 (MSN bots the don't respect robots.txt  -->
        <IpMatch>65\.55\.[012]?\d?\d\.[012]?\d?\d</IpMatch>

    <!-- </Handler>  -->

2.3.3 Static Thredds Catalog Dispatch Handler

Serves static THREDDS catalogs. Provides both a presentation view (HTML) for humans using browsers, and direct catalog access (XML).

2.3.3.1 <prefix> element

Defines the path component the comes after the servlet context and before all catalog requests. For example, if the prefix is thredds, then http://localhost:8080/opendap/thredds/ should give you the top-level static catalog (the contents of the file $CATALINA_HOME/content/opendap/catalog.xml)

2.3.3.2 <useMemoryCache> element

If the text value of this element is the string 'true' this will cause the servlet to ingest all of the static catalog files at startup and hold their contents in memory. See this page for more information about the memory caching operations

2.3.3.3 Example Configuration Element

           <Handler className="opendap.threddsHandler.Dispatch">
               <prefix>thredds</prefix>
               <useMemoryCache>true</useMemoryCache>
           </Handler>



2.3.4 DapDispatchHandler

Handles DAP request for Hyrax. For example the DapDispatchHandler will handle requests for DDS, DAS, DDX and DAP data . This DispatchHandler has no configuration elements, so it will always be written like this:

2.3.4.1 Example Configuration Element

           <Handler className="opendap.bes.DapDispatchHandler" />

2.3.5 DirectoryDispatchHandler

Handles the OPeNDAP directory view (contents.html) requests.

2.3.5.1 Example Configuration Element

           <Handler className="opendap.bes.DirectoryDispatchHandler" />


2.3.6 SpecialRequestDispatchHandler

Handles special requests (help, system properties, staus, etc.). This DispatchHandler has no configuration elements, so it will always be written like this:

2.3.6.1 Example Configuration Element

           <Handler className="opendap.coreServlet.SpecialRequestDispatchHandler" />


2.3.7 VersionDispatchHandler

Handles the version document requests. This DispatchHandler has no configuration elements, so it will always be written like this:

2.3.7.1 Example Configuration Element

           <Handler className="opendap.bes.VersionDispatchHandler" />


2.3.8 File Dispatch Handler

Handles requests for file level access. (README files etc.). This DispatchHandler has a single configuration element <AllowDirectDataSourceAccess>.

2.3.8.1 <AllowDirectDataSourceAccess> element

The <AllowDirectDataSourceAccess /> element controls the users ability to directly access data sources via the web interface. If this element is present in the OLFS.xml file (and not commented out as in the example below) a client can get an entire data source (such as an HDF file) by simply requesting it through the HTTP URL interface. This is NOT a good practice and is not recommended. By default Hyrax ships with this option turned off and I recommend that you leave it that way unless you really want users to be able to circumvent the OPeNDAP request interface and have direct access to the data products stored on your server.

2.3.8.2 Example Configuration Element

In the following example, the FileDispatchHandler is configured to deny direct access to data sources (note that the <AllowDirectDataSourceAccess /> element is commented out:

           <Handler className="opendap.bes.FileDispatchHandler" >
               <!-- <AllowDirectDataSourceAccess /> -->
           </Handler>

2.3.9 BES Thredds Dispatch Handler

Provides dynamic THREDDS catalogs of BES data holdings.

2.3.9.1 Example Configuration Element

           <Handler className="opendap.bes.BESThreddsDispatchHandler" />

2.4 HTTP POST Handlers

Hyrax currently has a single HTTP POST DispatchHandler implementation: SOAPRequestDispatcher. It provides a prototype SOAP interface for Hyrax. It will handle ALL HTTP POST responses, regardless of the path URI. It will always expect to find a SOAP request in the body of the POST.

2.4.1 SOAPRequestDispatcher

Handles ALL HTTP POST requests that it receives, and assumes that they contain a SOAP request document in the body of the POST message. This DispatchHandler has a single configuration element <OpendapSoapDispatchHandler>.

2.4.1.1 <OpendapSoapDispatchHandler> element

The <OpendapSoapDispatchHandler> element is used to specify which class is to used to provide the body of the SOAP responses.

In the following example, the DirectoryDispatchHandler is configured to provide the OPeNDAP directory view as the default:

           <Handler className="opendap.coreServlet.SOAPRequestDispatcher">
               <OpendapSoapDispatchHandler>opendap.bes.SoapDispatchHandler</OpendapSoapDispatchHandler >
           </Handler>

2.5 Example olfs.xml file

<?xml version="1.0" encoding="UTF-8"?>
<OLFSConfig>

    <DispatchHandlers>

        <HttpGetHandlers>

            <Handler className="opendap.bes.BESManager">

                <BES>
                    <prefix>/</prefix>
                    <host>localhost</host>
                    <port>10022</port>
                    <ClientPool maximum="10" />
                </BES>

            </Handler>

            <Handler className="opendap.coreServlet.SpecialRequestDispatchHandler" />
            
            <Handler className="opendap.bes.VersionDispatchHandler" />

            <Handler className="opendap.bes.DirectoryDispatchHandler">
                <DefaultDirectoryView>OPeNDAP</DefaultDirectoryView>
            </Handler>

            <Handler className="opendap.bes.DapDispatchHandler" />

            <Handler className="opendap.bes.FileDispatchHandler" >
                <!-- <AllowDirectDataSourceAccess /> -->
            </Handler>

            <Handler className="opendap.bes.ThreddsDispatchHandler" />

        </HttpGetHandlers>

        <HttpPostHandlers>
            <Handler className="opendap.coreServlet.SOAPRequestDispatcher" >
                <OpendapSoapDispatchHandler>opendap.bes.SoapDispatchHandler</OpendapSoapDispatchHandler>
            </Handler>
        </HttpPostHandlers>

    </DispatchHandlers>

</OLFSConfig>

3 catalog.xml file

The catalog.xml file contains the THREDDS catalog configuration for Hyrax. Read About It Here.

4 logback.xml file

The logback.xml file contains the logging configuration for Hyrax. Read About It Here.

5 web.xml file

We strongly recommend that you do NOT mess with the web.xml file. At least for now. Future versions of Server and the OLFS may have "user configurable" stuff in the web.xml file, but this version does not. SO JUST DON'T DO IT. OK? Having said that, here are the details regarding the web.xml file:

5.1 Servlet Definition

The OLFS running in the opendap context area needs an entry in the web.xml file. Multiple instances of a servlet and/or several different servlets can be configured in the one web.xml file. For instance you could have a DTS and a Hyrax running in from the same web.xml and thus under the same servlet context. Running multiple instances of the OLFS in a single web.xml file (aka context) will NOT work.

Each a servlet needs a unique name which is specified inside a <servlet> element in the web.xml file using the <servlet-name> tag. This is a name of convenience, for example if you where serving data from an ARGOS satellite you might call that servlet argos.

Additionally each instance of a <servlet> must specify which Java class contains the actual servlet to run. This is done in the <servlet-class> element. For example the OLFS servlet class name is opendap.coreServlet.DispatchServlet

Here is a syntax example combining the two previous example values:

<servlet>
	<servlet-name>hyrax</servlet-name>
	<servlet-class>opendap.coreServlet.DispatchServlet</servlet-name>
	.
	.
	.
</servlet>

This servlet could then be accessed as: http://hostname/opendap/servlet/argos

You may also add to the end of the web.xml file a set of <servlet-mapping> elements. These allow you to abbreviate the URL or the servlet. By placing the servlet mappings:

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

<servlet-mapping>
    <servlet-name>argos</servlet-name>
    <url-pattern>/argos/*</url-pattern>
</servlet-mapping>

At the end of the web.xml file our previous example changes it's URL to: http://hostname/opendap/argos

Eliminating the need for the word servlet in the URL. For more on the <servlet-mapping> element see the Jakarta-Tomcat documentation.

5.2 <init-param> Elements

The OLFS uses <init-param> elements inside of each <servlet> element to get specific configuration information.

<init-param>'s common to all OPeNDAP servlets are:

5.2.1 OLFSConfigFileName

This parameter identifies the name of the XML document file that contains the OLFS configuration. This file must be located in the persistent content directory and is typically called olfs.xml

For example:

    <init-param>
	<param-name>OLFSConfigFileName</param-name>
	<param-value>olfs.xml</param-value>
    </init-param>

5.2.2 DebugOn

This controls output to the terminal from which the servlet engine was launched. The value is a list of flags that turn on debugging instrumentation in different parts of the code. Supported values are:

  • probeRequest: Prints a lengthy inspection of the HttpServletRequest object to stdout. Don't leave this on for long, it will clog your Catalina logs.
  • DebugInterface: Enables the servers debug interface. This ineractive interface allows a user to look at (and change) the server state via a web browser. Enable this only for analysis purposes, disable when finshed!

Example:

    <init-param>
	<param-name>DebugOn</param-name>
	<param-value>probeRequest</param-value>
    </init-param>

Default: If this parameter is not set, or the value field is empty then these features will be disabled - which is what you want unless there is a problem to analyze.

5.3 Example of web.xml content

<servlet>

    <servlet-name>hyrax</servlet-name>

    <servlet-class>opendap.coreServlet.DispatchServlet</servlet-class>

    <init-param>
        <param-name>DebugOn</param-name>
        <param-value></param-value>
    </init-param>

    <load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>
    <servlet-name>hyrax</servlet-name>
    <url-pattern>*</url-pattern>
</servlet-mapping>

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

<servlet-mapping>
    <servlet-name>hyrax</servlet-name>
    <url-pattern>/hyrax/*</url-pattern>
</servlet-mapping>

6 Docs Servlet

The Docs (or documentation) servlet provides the OLFS web application with the ability to serve a tree of static documentation files. By default it will serve the files in the documentation tree provided with the OLFS in the Hyrax distribution. This tree is rooted at $CATALINA_HOME/webapps/opendap/docs/ and contains documentation pertaining to the software in the Hyrax distribution - installation and configuration instruction, release notes, java docs, etc.

If one wishes to replace this information with their own set of web pages, one can remove/replace the files in the default directory. However, installing a new version of Hyrax will cause these files to be overwritten, forcing them to be replaced after the install (and hopefully AFTER the new release documentation had been read and understood by the user).

The Docs servlet provides an alternative to this. If a docs directory is created in the persistent content directory for Hyrax the Docs servlet will detect it (when Tomcat is launched) and it will serve files from there instead of from the default location.

This scheme provides 2 beneficial effects:

  1. It allows localizations of the web documents associated with Hyrax to persist through Hyrax upgrades with no user intervention.
  2. It preserves important release documents that ship with the Hyrax software.

In summary, to provide persistent web pages as part of a Hyrax localization simple create the directory: $CATALINA_HOME/content/opendap/docs

Place your content in there and away you go. If later you wish to view the web based documentation bundled with Hyrax simply change the name of the directory from docs to something else and restart Tomcat. (or, you could just look in the $CATALINA_HOME/webapps/opendap/docs directory)

In the Docs servlet, if a URL ends in a directory name or a "/" then the servlet will attempt to serve the index.html in that directory. In other words index.html is the default document.

7 Logging

Logging is a big enough subject we gave it it's own page.

8 Authentication & Authorization

8.1 Request For Input

So far Hyrax relies on the Tomcat security implementation for authentication services. If after reading this section and the Tomcat documentation on security you are left wanting something more, then please get in touch with us at OPeNDAP. We would like to talk with you about your security needs for OPeNDAP Hyrax and possibly develop some use cases that describe your needs. In the future we hope to provide a richer security configuration environment than the one currently offered by Tomcat.

8.2 Synopsis

Hyrax currently relies on the security features implemented by Tomcat for authentication and authorization services. It is recommended that you read carefully and understand the Tomcat security documentation.

For Tomcat 5.x see:

For Tomcat 6.x see:

And that you read chapter 12 of the Java Servlet Specification 2.4 that decribes how to configure security constraints at the web application level.

Tomcat security requires fairly extensive additions to the web.xml file. (It is important to keep in mind that altering the <servlet> definitions may render your Hyrax server inoperable - please see the previous sections that discuss this.)

Examples of security content for the web.xml file can be found in the persistent content directory of the Hyrax server, which by default is located at $CATALINA_HOME/content/opendap/.

8.3 Limitations

Officially Tomcat security supports context level authentication. What this means is that you can restrict access to the collection of servlets running in a single web application - in other words all of the stuff that is defined in a single web.xml file. You can call out different authentication rules for different <url-pattern>'s within the web application, but only clients which do not cache ANY security information will be able to easily access the different areas.

For example in your web.xml file you might have:

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>fnoc1</web-resource-name>
            <url-pattern>/hyrax/nc/fnoc1.txt</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>fn1</role-name>
        </auth-constraint>
    </security-constraint>
 
    <security-constraint>
        <web-resource-collection>
             <web-resource-name>fnoc2</web-resource-name>
             <url-pattern>/hyrax/nc/fnoc2.txt</url-pattern>
         </web-resource-collection>
         <auth-constraint>
             <role-name>fn2</role-name>
          </auth-constraint>
    </security-constraint>
 
    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>MyApplicationRealm</realm-name>
    </login-config>


Where the security roles fn1 and fn2 (defined in the tomcat-users.xml file) have no common members.

The complete URI's would be:

http://localhost:8080/mycontext/hyrax/nc/fnoc1.txt
http://localhost:8080/mycontext/hyrax/nc/fnoc2.txt

Now - this works, for clients that aren't too smart - i.e. they don't cache anything. However, if you access these URLs with a typical browser, once you authenticate for one URI, then you are locked out of the other one until you successfully "reset" the browser (purge all caches).

I think the reason is as follows: In the exchange between Tomcat and the client, Tomcat is sending the header:

WWW-Authenticate: Basic realm="MyApplicationRealm"

And the client authenticates. When the second URI is accessed Tomcat sends the the same authentication challenge, with the same WWW-Authenticate header. The client, having recently authenticated to this realm-name (defined in the <login-config> element in the web.xml file - see above), resends the authentication information, and, since it's not valid for that url pattern, the request is denied.

8.4 Persistence

You should be careful to back up your modified web.xml file to a location outside of the $CATALINA_HOME/webapps/opendap directory as new versions of Hyrax will overwrite it when installed. You could use an XML ENTITY and an entity reference in the web.xml to cause a local file containing the security configuration to be included in the web.xml. For example adding the ENTITY:

[<!ENTITY securityConfig SYSTEM "file:/fully/qualified/path/to/your/security/config.xml">]

To the <!DOCTYPE> declaration at the top of the web.xml in conjunction with adding an entity reference:

&securityConfig;

To the content of the <web-app> element would cause your external security configuration to be included in the web.xml file.

Here is an example of an ENTITY configuration:

    <?xml version="1.0" encoding="ISO-8859-1"?>
 
    <!DOCTYPE web-app
        PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
        "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"
        [<!ENTITY securityConfig      SYSTEM "file:/fully/qualified/path/to/your/security/config.xml">]
    >
    <web-app>
 
        <!--
            Loads a persistent security configuration from the content directory.
            This configuration may be empty, in which case no security constraints will be
            applied by Tomcat.
        -->
        &securityConfig;
 
        .
        .
        .
 
    </web-app>

This will not prevent you from losing your web.xml file when a new version of Hyrax is installed, but adding the ENTITY stuff to the new web.xml file would be easier than remembering an extensive security configuration. Of course, Y.M.M.V.

9 Compressed Responses and Tomcat

Many OPeNDAP clients accept compressed responses. This can greatly increase the efficiency of the client/server interaction by diminishing the number of bytes actually transmitted over "the wire". Tomcat provides native compression support for the GZIP compression mechanism, however it is NOT turned on by default.

The following example is based on Tomcat 5.15. We recommend that you read carefully the Tomcat documentation related to this topic before proceeding:

9.1 Details

To enable compression you will need to edit the $CATALINA_HOME/conf/server.xml file. You will need to locate the <Connector> element associated with your server, typically this will be the only <Connector> element whose port attribute is set equal to 8080. To this you will need to add/change several attributes to enable compression.

With my Tomcat 5.5 distribution I found this default <Connector> element definition in my server.xml file:

    <Connector port="8080" maxHttpHeaderSize="8192"
        maxThreads="150" minSpareThreads="25" maxSpareThreads="75";
        enableLookups="false" redirectPort="8443" acceptCount="100"
        connectionTimeout="20000" disableUploadTimeout="true"
        compression="no"
     >

You will need to add to this four attributes:

compression="force"
compressionMinSize="2048"
noCompressionUserAgents="gozilla, traviata"
compressableMimeType="text/html,text/xml,application/octet-stream"

Notice that there is a list of compressible MIME types. Basically:

  • compression="no" means nothing gets compressed.
  • compression="yes" means only the compressible MIME types get compressed.
  • compression="force" means everything gets compressed (assuming the client accepts gzip and the response is bigger than compressionMinSize)

You MUST set compression="force" for compression to work with the OPeNDAP data transport.

The final result being:

    <Connector port="8080" maxHttpHeaderSize="8192"
        maxThreads="150" minSpareThreads="25" maxSpareThreads="75";
        enableLookups="false" redirectPort="8443" acceptCount="100"
        connectionTimeout="20000" disableUploadTimeout="true"
        compression="no"
        compression="force"
        compressionMinSize="2048"
        noCompressionUserAgents="gozilla, traviata"
        compressableMimeType="text/html,text/xml,application/octet-stream"
     >

Restart Tomcat for these changes to take effect.

NOTE: If you are using Tomcat in conjunction with the Apache Web Server (our friend httpd) via AJP you will need to configure Apache to deliver compressed responses too. Tomcat will not compress content sent over the AJP connection.