GT 4.2.0 WS MDS WebMDS: Developer's Guide

Features new in release 4.2.0:

Other Supported Features

Deprecated Features

Tested Platforms for WebMDS:

Protocol changes since GT version 4.0.x:

API changes since GT version 4.0.x:

Exception changes since GT version 4.0.x:

Schema changes since GT version 4.0.x:

WebMDS depends on the following GT components:

WebMDS depends on the following 3rd party software:

By default, the WebMDS plugins distributed as part of the Toolkit do not use authentication credentials -- they retrieve information using anonymous SSL authentication or no authentication at all, and thus retrieve only publicly-available information.

The ResourcePropertyNodeSource and ResourcePropertyQueryNodeSource plugins can be configured either to allow users to specify what resources they want to query or to only allow users to query resources pre-configured by the web administrator. The standard WebMDS deployment allows users to specify the resources they want to query; to disallow this (for example, to ensure that people don't use your site's bandwidth to view information about some other site's services), remove the files $GLOBUS_LOCATION/lib/webmds/conf/openEndedRP and $GLOBUS_LOCATION/lib/webmds/conf/openEndedQuery.

To create a new plugin to collect raw XML data, write a Java class that implements the WebmdsXmlSource or WebmdsNodeSource interface. These are documented in APIs. The FileXmlSource and NodeXmlSource classes distributed with WebMDS are examples of classes that implement WebmdsXmlSource; the ResourcePropertyNodeSource and ResourcePropertyQueryNodeSource classes distributed with WebMDS are examples of classes that implement the WebmdsNodeSource interface.

To change the appearance of the output of WebMDS, create a new XSLT transform; see the W3C XSLT Documentation for more information.

There is no "client" API for accessing WebMDS; WebMDS is a servlet that is accessed via web forms.

WebMDS uses a WebMDS plugin (a Java class that implements the WebmdsXmlSource interface) to acquire XML documents (which can be used either as raw information sources or as XSL transformations). WebMDS comes with two WebMDS plugins: FileXmlSource, which reads XML from a file (and is primarily used to acquire XSL transformations), and NodeXmlSource. NodeXmlSource in turn calls a node source plugin (a Java class that implements the WebmdsNodeSource interface) to acquire an XML DOM document. acquires XML information using a WebMDS XML source, a Java class that implements the WebmdsXmlSource interface. To summarize:

The command-line tool webmds-create-context-file is used to create Tomcat configuration files needed to deploy WebMDS.

webmds-create-context-file [-f] tomcat_context_file

The tomcat_context_file argument is the location of the Tomcat configuration file defining the WebMDS context; in a default Tomcat installation, the location of this file will be $CATALINA_HOME/conf/Catalina/localhost.

By default, webmds-create-context-file will not overwrite an existing context file; the -f option is used to force webmds-create-context-file to overwrite an existing file.

Note: webmds-create-context-file is found in $GLOBUS_LOCATION/lib/webmds/bin

    $GLOBUS_LOCATION/lib/webmds/bin/webmds-create-context-file -f \
         $CATALINA_HOME/conf/Catalina/localhost

Changes to the Tomcat context do not take effect until Tomcat is restarted or reloaded.

The WebMDS GUI is a web-based interface for browsing formatted XML data, such as the results of resource property queries on a grid service.

WebMDS can be accessed using any web browser. In a default WebMDS installation, the URL http://hostname:port/webmds corresponds to the top-level WebMDS web page. This page includes a link to a WebMDS invocation that provides summary information (with links to detailed information) about a locally-running MDS Index server. It also contains a link to a page of sample web forms demonstrating other uses of WebMDS.

The WebMDS servlet is located at http://your-tomcat-host:your-tomcat-port/webmds/webmds. It takes the following arguments:

Error conditions (such as typographical errors in resource property names) are presented as stack traces, rather than user-friendly error messages.

WebMDS can be configured to get information from any of various sources and to filter it through any XSL transform. WebMDS uses configuration files to specify the location of (and to name) sources of information and xsl and web form arguments to select among these configured information sources and xsl transforms.

By default, WebMDS comes configured to report information about an index server using transaction-level security on the default port (8443) on the local system. If you are running the Globus Toolkit in this default configuration, then you can use WebMDS to query your local Index Service without any configuration changes.

If you wish to monitor a different Index Service, you will need to edit the file $GLOBUS_LOCATION/lib/webmds/conf/indexinfo to change the URL in the line:

    <value>https://127.0.0.1:8443/wsrf/services/DefaultIndexService</value>

to match the URL of your default index service. Changes to WebMDS configuration files take effect the next time that Tomcat is restarted.

For other configuration changes (e.g., monitoring different kinds of services), see the detailed configuration information below.

Each configuration file in $GLOBUS_LOCATION/lib/webmds/conf defines a source of XML, which can be used in an HTML form to specify sources of information and XSL transforms. The distribution contains some standard configuration files in this directory, including:

Each configuration file defines a WebmdsConfig object. A WebmdsConfig object consists of:

For example, this is $GLOBUS_LOCATION/lib/webmds/conf/servicegroupxsl, which defines the servicegroupxsl XML source:

    <WebmdsConfig>
      <description>
         XSL file to show service group summary information
      </description>
      <className>org.globus.mds.webmds.xmlSources.file.FileXmlSource</className>
      <parameter>
        <name>file</name>
        <value>xslfiles/servicegrouptable.xsl</value>
      </parameter>
    </WebmdsConfig>

This file tells WebMDS to use the org.globus.mds.webmds.xmlSources.file.FileXmlSource Java class (a class which reads XML from a local file) to collect XML data and to pass a file parameter (which that Java class interprets as the name of the file to open, relative to the WebMDS base directory).

Tomcat must be restarted (or one of the more advanced Tomcat administrative mechanisms must be used) for changes to these configuration files to take effect.

Error handling in WebMDS is currently done by throwing exceptions, which are displayed by Tomcat as stack traces.

Table 1. WS MDS Trigger Service Error Messages

Error Code	Definition	Possible Solutions
java.net.ConnectException: Connection refused	If you attempt to use WebMDS to collect information from a service that is not running, you will see a stack trace that begins with: org.globus.mds.webmds.xmlSources.resourceProperties.ResourcePropertySourceException: ; nested exception is: java.net.ConnectException: Connection refused	Make sure the service you are trying to collect information from is running.
faultString: org.globus.common.ChainedIOException: Authentication failed [Caused by: Failure unspecified at GSS-API level [Caused by: Unknown CA]]	When WebMDS sends resource property queries to a secure WSRF service instance (such as an WS MDS Index Server), the WebMDS server must trust the certificate authority that issued the certificate used by the WSRF service instance. If the WebMDS server does not trust the CA used by the remote service, then WebMDS queries will produce a stack trace that includes this message.	This can be solved by configuring the Tomcat server that hosts WebMDS to trust the appropriate CA, by either: placing the CA certificate in /etc/grid-security/certificates, or placing the CA certificate somewhere else, and setting the Tomcat process's X509_CERT_DIR system parameter to the directory in which the CA certificate was installed. One way to do this is to set the CATALINA_OPTS environment variable and then restart Tomcat: export CATALINA_OPTS=-DX509_CERT_DIR=/path/to/cert/dir $CATALINA_HOME/bin/shutdown.sh $CATALINA_HOME/bin/startup.sh
WebMDS connections to secure Index Servers (or other secure WSRF servers) just hang	If the JVM used by Tomcat is configured to use a blocking random-number source, WebMDS connections to secure Index Servers (or other secure WSRF servers) can hang. This is the default configuration for many installations.	One solution is to set the CATALINA_OPTS environment variable to ensure that Tomcat's JVM will use a non-blocking random-number source: export CATALINA_OPTS=-Djava.security.egd=/dev/urandom $CATALINA_HOME/bin/shutdown.sh $CATALINA_HOME/bin/startup.sh Note f you encounter this problem with WebMDS, you may also encounter a similar problem with the Globus container on the same system.