Hyrax WMS

From OPeNDAP Documentation
⧼opendap2-jumptonavigation⧽

Hyrax now works with ncWMS

Overview

With the recent addition of the Dynamic Services feature in the ncWMS WMS Server from Reading e-Science Centre Hyrax can now provide WMS services for all of it's appropriate holdings.

Theory of Operation

In an instance of the ncWMS a Dynamic Service is configured that points to a Hyrax server. This allows the ncWMS instance to access all of the holdings of the DAP server. However, the ncWMS does not "crawl" or "discover" or in any other way catalog or inventory the DAP server. Instead the user configures the Hyrax server to add the WMS service to its catalogs and services content. Hyrax then directs WMS traffic to the ncWMS. The ncWMS in turn retrieves the data directly from Hyrax and services the request.

The ncWMS instance may be hosted anywhere, however for a significant performance improvement we suggest you host your own ncWMS running in the same Tomcat instance as Hyrax. With such a configuration the WMS response performance for datasets backed by the DAP service is nearly as fast as the ncWMS response performance using direct file access.

Evaluating Candidate Datasets

In order for ncWMS to recognize your dataset as valid for service your data must:

  • Contain gridded data (as DAP Grid objects or DAP Array objects utilizing shared dimensional coordinate arrays) as described by the Unidata Common Data Model.
  • The NetCDF-Java library (which is what provides data access services for ncWMS) utilizes the Common Data Model and must be able to identify the coordinates system used. You can test this by using the Unidata ToolsUI application (which is also based on the NetCDF-Java library). Open your dataset with ToolsUI, and in the Feature Types -> Grid Panel there should be one or more variables shown with some kind of coordinate system.
ToolsUI Grid View
Note that ToolsUI supports opening both local files and remote (http accessible) datasets.

WMS Installation (suggested)

The ncWMS web application is easy to install.

Simply:

  • Beginning with Hyrax-1.11 we will be bundling ncWMS with the release of the OLFS. Go to the Hyrax Download web site and download the tar file bundle with the latest versions of the OLFS and ncWMS.
  • Unpack the tar file.
  • Copy the WAR files opendap.war and ncWMS.war into the $CATALINA_HOME/webapps directory
  • Restart Tomcat

OLFS/Hyrax Installation

As of the release of Hyrax 1.11 (and in particular OLFS 1.13.0) the support for WMS will be built into the server. All that is required is a (collocated) ncWMS instance and then the configuration steps as detailed below. So - get the latest Hyrax (1.11.0 or later) install and configure using the normal methods and then follow the configuration steps detailed below.

Configuration

The following sub sections assume that you have installed both Hyrax and the ncWMS on your server in a single Tomcat instance running on port 8080. If your arrangement is otherwise you will need to adjust accordingly.

For the following example sections we will use the following URLs:

ncWMS configuration

Authenticate as the Administrator

In order to access the ncWMS administration page (which you must do in oder to configure the server) you will need to configure authentication and access control for the page, or you will need to temporarily disable access control for the page in order to configure the server. I strongly recommend the former. Do that.

The default security configuration for ncWMS can be located (after initial launch) in the file:

$CATALINA_HOME/webapps/ncWMS/WEB-INF/web.xml

This default configuration stipulates that access to the ncWMS/admin pages must be over a secure transport and that there will be no access without being authenticated and in the manager role:

<!-- Define a Security Constraint on the Admin command and user interfaces -->
<security-constraint>
    <web-resource-collection>
        <web-resource-name>ncWMS Admin Interface</web-resource-name>
        <url-pattern>/admin/*</url-pattern>
    </web-resource-collection>

    <auth-constraint>
        <role-name>manager</role-name>
    </auth-constraint>

    <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
</security-constraint>

Your choices:

  1. Use apache httpd to provide authentication services for your installation.
    1. Comment out the security-constraint in the web.xml file for ncWMS.
    2. Correctly integrate Tomcat and Apache using the AJP connector.
    3. Configure an Apache httpd <Location> directive for the ncWMS/admin page.
    4. Write the directive to restrict access to specific users.
  2. Use Tomcat authentication.
    1. Leave the security-constraint in place.
    2. Correctly configure Tomcat to use some type authentication (Even MemoryRealm is better than nothing.
    3. Modify the security-constraint to reflect your authentication configuration. (Different role? HTTPS? etc.)
  3. Temporarily Disable the security-constraint.
    1. Comment out the security-constraint in the web.xml file for ncWMS.
    2. Finish the configuration steps below.
    3. At the end, when it's working, go back an un-comment the security-constraint in the web.xml file for ncWMS.
    4. Restart Tomcat.

Now that you can get to it, go to the ncWMS administration page: http://servername.org:8080/ncWMS/admin/

This page requires a simple authentication step where the default username is 'admin' and the default password is 'ncWMS' .

If you are deploying your server in a publicly accessible environment we strongly recommend that you:

  1. Change that default password.
  2. If you are using Apache httpd as the authentication engine for your service you should add a security constraint for the location <Location /ncWMS/admn> that limits the access to a select group of administrators.

Configure a Dynamic Service

Once you have authenticated and can view the ncWMS admin page, scroll down to the Dynamic Services section:

ncWMS Admin Page - Partial Screen Grab

Create a new Dynamic Service for Hyrax:

  • Choose and enter a unique ID. (Write it down, you'll need it later) The screen shot shows 'lds' for 'local dap service' which we will use for the rest of these examples.
  • The value of the Service URL field will be the URL for the top level of the Hyrax server.
    • If the Hyrax server and the ncWMS server are running together in a single Tomcat instance then this URL should be expressed as: http://localhost:8080/opendap
    • If the Hyrax server and the ncWMS server are running on separate systems this URL must be a DAP server top level URL, and not a localhost URL.
    • Best WMS response performance will be achieved by running ncWMS and Hyrax on the same server and providing the localhost URL here.
  • The Dataset Match Regex should be a regex that matches of all of the data files you have for which WMS can prove services. If that's too cumbersome then just use '.*' (as in the example) which matches everything.
  • Scroll to the bottom of the page and save the configuration.

Summary

Unique ID Service URL Dataset Match Regex Disabled? Remove Data Reading Class Link to more info Copyright Statement
lds http://localhost:8080/opendap .*

Hyrax Configuration

The Hyrax WMS configuration is contained in the file $CATALINA_HOME/content/opendap/viewers.xml. This file identifies data viewers and Web Services that Hyrax can provide for datasets. There are two relevant sections, the first defines Hyrax's view of the WMS service and the second enables Hyrax to provide access to the Godiva service that is part of ncWMS.


Edit the file $CATALINA_HOME/content/opendap/viewers.xml


Uncomment the following sections:

<!--
    <WebServiceHandler className="opendap.viewers.NcWmsService" serviceId="ncWms" >
        <applicationName>Web Mapping Service</applicationName>
        <NcWmsService href="/ncWMS/wms" base="/ncWMS/wms" ncWmsDynamicServiceId="lds" />
    </WebServiceHandler>

    <WebServiceHandler className="opendap.viewers.GodivaWebService" serviceId="godiva" >
        <applicationName>Godiva WMS GUI</applicationName>
        <NcWmsService href="http://YourServersNameHere:8080/ncWMS/wms" base="/ncWMS/wms" ncWmsDynamicServiceId="lds"/>
        <Godiva href="/ncWMS/godiva2.html" base="/ncWMS/godiva2.html"/>
    </WebServiceHandler>
-->

NcWmsServce

In the first section:

<WebServiceHandler className="opendap.viewers.NcWmsService" serviceId="ncWms" >
    <applicationName>Web Mapping Service</applicationName>
    <NcWmsService href="/ncWMS/wms" base="/ncWMS/wms" ncWmsDynamicServiceId="lds" />
</WebServiceHandler>

Edit the NcWmsService element so that:

  • The value of the ncWmsDynamicServiceId matches the Unique ID of the Dynamic Service you defined in ncWMS.
  • NB: The href and base attributes both use relative URL paths to locate the ncWMS service. If the ncWMS instance is NOT running on the same host as Hyrax then the values of the href and base attributes must be converted to fully qualified URLs.


GodivaWebService

In the second section:

<WebServiceHandler className="opendap.viewers.GodivaWebService" serviceId="godiva" >
    <applicationName>Godiva WMS GUI</applicationName>
    <NcWmsService href="http://yourNcWMSserver:8080/ncWMS/wms" base="/ncWMS/wms" ncWmsDynamicServiceId="lds"/>
    <Godiva href="/ncWMS/godiva2.html" base="/ncWMS/godiva2.html"/>
</WebServiceHandler>

Edit the NcWmsService element so that:

  • The value of the href attribute is the fully qualified URL for public access to your WMS service. The server name in this href will never be localhost - Godiva won't work. (Well OK, if your browser is running on the same system as the ncWMS instance then it would but it won't work for anybody else)
  • The value of the ncWmsDynamicServiceId matches the Unique ID of the Dynamic Service you defined in ncWMS.


The Godiva element's href and base attributes both use relative URL paths to locate the Godiva service. If the ncWMS instance is NOT running on the same host as Hyrax then the values of the href and base attributes must be converted to fully qualified URLs.

Start and Test

  • Once the configuration steps are complete restart your Tomcat server.
  • Point your browser at the Hyrax sever and navigate to a WMS-suitable dataset.
  • Clicking the dataset's Viewers link should return a page with both WMS and Godiva links.
  • Try 'em.


Issues

Logging Issue

There is a small issue with deploying this configuration onto some Linux system in which everything has been installed from RPM (except maybe Tomcat and it's components including the ncWMS and Hyrax applications)


The Symptom

The issue appears in the Tomcat log as a failure to lock files associated with the java.util.prefs.FileSystemPreferences:

Dec 12, 2014 1:17:28 PM java.util.prefs.FileSystemPreferences checkLockFile0ErrorCode
WARNING: Could not lock System prefs. Unix error code 32612.
Dec 12, 2014 1:17:28 PM java.util.prefs.FileSystemPreferences syncWorld
WARNING: Couldn't flush system prefs: java.util.prefs.BackingStoreException: Couldn't get file lock.
Dec 12, 2014 1:17:58 PM java.util.prefs.FileSystemPreferences checkLockFile0ErrorCode
WARNING: Could not lock System prefs. Unix error code 32612.
Dec 12, 2014 1:17:58 PM java.util.prefs.FileSystemPreferences syncWorld
WARNING: Couldn't flush system prefs: java.util.prefs.BackingStoreException: Couldn't get file lock.

And is logged every 30 seconds or so. So the problem is the logs fill up with this issue and not stuff we care about. The problem is that the files/directories in question either don't exist, or, if they do exist the Tomcat user does not have read/write permissions on them.

The Fix

I looked around and discovered that a number of people (including TDS deployers) had experienced this issue. It's a Linux problem and involves the existence and permissions of a global system preferences directory. I think this is only an issue on Linux systems in which everything is installed via yum/rpm, which may be why we only see this problem on certain systems, but I not 100% confident that the issue is limited only to this type of installation.

I found and tested these two ways to solve it:

1) Create the global System Preference directory and set the owner to the Tomcat user
   sudo mkdir -P /etc/.java/.systemPrefs
   sudo chown -R tomcat-user /etc/.java/.systemPrefs
This could also be accomplished by changing the group ownership to the tomcat-group and setting the group read/write flags.


2) Create your own java System Preference directory and then set the JAVA_OPTS environment variable so that the systemRoot value is set the new directory

Create the directory

   mkdir -P /home/tomcat-user/.java/.systemPrefs
   sudo chown -R tomcat-user /home/tomcat-user/.java/.systemPrefs

Then, in each shell that launches Tomcat:

   export JAVA_OPTS="-Djava.util.prefs.systemRoot=/home/tomcat-user/.java"
   $CATALINA_HOME/bin/startup.sh