GT 3.9.5 WS MDS WebMDS (Tech Preview): System Administrator's Guide

Introduction

WebMDS enables end users to view monitoring information via a standard web browser interface, without installing any additional software on their PC. WebMDS is implemented as a servlet that uses a plugin interface to gather monitoring information (or any other information in XML format) and XSLT transforms, and present the data to the user in a readable form. Web site administrators can customize their own WebMDS deployments by using HTML form options, configuring different plugins to collect data and XSLT transforms, and creating their own plugins and XSLT transforms.

This guide contains advanced configuration information for system administrators working with WS MDS WebMDS. It provides references to information on procedures typically performed by system administrators, including installation, configuring, deploying, and testing the installation.

This information is in addition to the basic installation instructions in the GT 3.9.5 System Administrator's Guide.

Building and Installing

WebMDS is built and installed as part of the standard Globus Toolkit installation.

Configuring

Configuration overview

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 server, you will need to edit the file $GLOBUS_LOCATION/lib/webmds/conf/indexinfo to change the URL in the line: 

    https://127.0.0.1:8443/wsrf/services/DefaultIndexService
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.

Syntax of the interface

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:

indexinfo all resource properties from an index server running with transaction-level security on port 8443 on the local host
indexinfo_nosec all resource properties from an index server running with no security on port 8080 on the local host
openEndedQuery all resource properties from a user-specified grid service
openEndedRP a user-specified resource property from a user-specified grid service
servicegroupxsl an xsl transform that presents summary information about a service group
sgedetail an xsl transform that presents detailed information about a service group entry

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

  • A description: a textual description of the XML source being defined.
  • A className: the name of the Java class that will be used to acquire the XML data.
  • Zero or more parameter objects, each of which consists of the name of some parameter recognized by the Java class specified by className, and the string value of that parameter.
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.

XML Sources included with WebMDS

FileXMLSource

The class org.globus.mds.webmds.xmlSources.file.FileXmlSource reads XML from a file, and recognizes a single parameter:
file The name of the file to read. Relative path names are interpreted relative to the WebMDS base directory ($GLOBUS_LOCATION/lib/webmds).

NodeXMLSource

This XML source class uses a WebmdsNodeSource object to fetch an XML document and return it in a form that is usable by WebMDS. It recognizes the following options:
class The name of a class that implements the WebmdsNodeSource interface. An instance of this class will be used to get an XML document.
parameters Additional parameters are passed to an instance of the class specified by the class argument.

Classes That Implement WebmdsNodeSource

The following classes implement the NodeXMLSource interfaces and can be used in conjunction with NodeXMLSource

ResourcePropertyQueryNodeSource

This class performs a resource property query to get all the resource properties for some web service. It recognizes the following configuration parameters:
endpoint The endpoint name to be used in a resource property query.
endpointKeyName and endpointKeyValue An optional key/value pair to use as reference properties for the endpoint specified with the endpoint parameter.
allowUserEndpoints If true, values for xmlSource.sourceName.param.endpoint, xmlSource.sourceName.param.endpointKeyName, and xmlSource.sourceName.param.endpointKeyValue specified in the request will override the configured endpoint value.
endpointFile The name of a file from which the endpoint information (in XML) will be read. This configuration parameter can never be overridden by request arguments.

ResourcePropertyNodeSource

This class queries a web service for a single resource property. It recognizes the following parameters:
endpoint The endpoint name to be used in a resource property query.
endpointKeyName and endpointKeyValue An optional key/value pair to use as reference properties for the endpoint specified with the endpoint parameter.
allowUserEndpoints If true, values for xmlSource.sourceName.param.endpoint, xmlSource.sourceName.param.endpointKeyName, and xmlSource.sourceName.param.endpointKeyValue specified in the request will override the configured endpoint value.
endpointFile The name of a file from which the endpoint information (in XML) will be read. This configuration parameter can never be overridden by request arguments.
rpNamespace The namespace part of the QName of the resource property to be queried for.
rpName The local name part of the QName of the resource property to be queried for.
allowUserResourceProperties If true, values of xmlSource.sourceName.param.rpNamespace and xmlSource.sourceName.param.rpNames specified in the request will override the configured resource property namespace and name.

Deploying

Because WebMDS is implemented as a servlet, it must be deployed into a servlet container, such as Tomcat. The following instructions assume that you've installed Tomcat version 5.0.28. and set the $CATALINA_HOME environment variable to the directory into which you've installed Tomcat.

Standard deployment into Tomcat 5.0.28

The standard deployment consists of two steps: creating a configuration file that tells Tomcat where to find the WebMDS servlet and related files, and restarting Tomcat so that it will read this new configuration file. These steps require write permission on files and directories in $CATALINA_HOME; they do not require write permission on anything in $GLOBUS_LOCATION.

To create the configuration file, run this command:

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

This will create $CATALINA_HOME/conf/Catalina/localhost/webmds.xml. Note: if this file already exists (e.g., if you've previously installed another varsion of WebMDS), you'll need to use the -f option to webmds-create-context-file.

Next, restart Tomcat. If Tomcat is already running, stop it:

    $CATALINA_HOME/bin/shutdown.sh

Then, start Tomcat:

    $CATALINA_HOME/bin/startup.sh

Custom deployment

If you are already running a Tomcat server (or other server that supports servlets) and your preferred mechanism for installing servlets is something other than creating a configuration file and restarting your web server, feel free to use that mechanism. The servlet root for WebMDS is $GLOBUS_LOCATION/lib/webmds.

For the rest of these instructions, the term Globus user will be used to refer to the owner of the $GLOBUS_LOCATION directory, and Tomcat user will be used to refer to the owner of the $CATALINA_HOME directory. If the Globus and Tomcat installations were performed from the same user account, the Globus user and Tomcat user will be the same.

Any time you change the servlet configuration (or any jar files used by the servlet), you'll need to let tomcat know there was a change. If you have a preferred way of configuring tomcat, feel free to use it, with $GLOBUS_LOCATION/lib/webmds as the servlet directory. These steps need to be performed by the Tomcat user.

If you're using tomcat 5.0.28 and haven't done any custom configuration (such as defining additional hosts) other than changing the tomcat port, you can configure tomcat by doing the following:

  1. Create a context descriptor file called webmds.xml in the location where tomcat will look for it: 
    
    $GLOBUS_LOCATION/lib/webmds/bin/webmds-create-context-file \
         $CATALINA_HOME/conf/Catalina/localhost
    Note: if the file $CATALINA_HOME/conf/Catalina/localhost/webmds.xml already exists, you can use the -f flag to create-context-file to overwrite it. to the tomcat configuration directory.
  2. If tomcat is running, shut it down.
    3. 
    $CATALINA_HOME/bin/shutdown.sh
  3. Start tomcat up.
    4. 
    $CATALINA_HOME/bin/startup.sh

Testing

The easiest way to test your installation is to use it to view your index service, by pointing your web browser at http://your-tomcat-host:your-tomcat-port/webmds and clicking on the link labelled "A list of resources registered to the local default index service".

Security Considerations

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.

Troubleshooting

Error handling in WebMDS is currently done by throwing exceptions, which are displayed by Tomcat as stack traces. 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