GT 4.0 WS MDS WebMDS: System Administrator's Guide

Home -> Toolkit -> Docs -> 4.0 -> Info -> Webmds	Website Email Lists Search:

Table of Contents

1. Introduction

2. Building and Installing

3. Configuring

3.1. Configuration overview
3.2. Syntax of the interface
3.3. XML Sources included with WebMDS

4. Deploying

4.1. Standard deployment into Tomcat 5.0.28
4.2. Deploying WebMDS and Globus in the same Tomcat Server
4.3. Custom deployment

5. Testing

6. Security Considerations

7. Troubleshooting

1. 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 Globus Toolkit prerequisite, overview, installation, security configuration instructions in the GT 4.0 System Administrator's Guide. Read through this guide before continuing!

2. Building and Installing

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

3. Configuring

3.1. 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:

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

3.2. 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:

Table 1. Pre-configured information sources

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

3.3. XML Sources included with WebMDS

3.3.1. FileXMLSource

The class org.globus.mds.webmds.xmlSources.file.FileXmlSource reads XML from a file, and recognizes a single parameter:

Table 2. Configuration parameters used with FileXMLSource

file The name of the file to read. Relative path names are interpreted relative to the WebMDS base directory ($GLOBUS_LOCATION/lib/webmds).

3.3.2. 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:

Table 3. Configuration parameters used with NodeXMLSource

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

3.3.3. Classes That Implement WebmdsNodeSource

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

3.3.4. ResourcePropertyQueryNodeSource

This class performs a resource property query to get all the resource properties for some web service. It recognizes the following configuration parameters:

Table 4. Configuration parameters used with ResourcePropertyQueryNodeSource

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

3.3.5. ResourcePropertyNodeSource

This class queries a web service for a single resource property. It recognizes the following parameters:

Table 5. Configuration parameters used with ResourcePropertyNodeSource

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

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

4.1. 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 version of WebMDS), you'll need to use the -f option to webmds-create-context-file.

Next, make sure that Tomcat has a version of the Xalan library (used by WebMDS to do XSL transforms) that is compatible with the one used by Globus:

    cp $GLOBUS_LOCATION/endorsed/xalan.jar $CATALINA_HOME/common/endorsed/.

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

    $CATALINA_HOME/bin/shutdown.sh

Then, start Tomcat:

    $CATALINA_HOME/bin/startup.sh

4.2. Deploying WebMDS and Globus in the same Tomcat Server

If you wish to run Globus and WebMDS in the same Tomcat instance (instead of, for example, running Globus in the Globus standalone container and WebMDS in Tomcat), then do the following:

Install Globus and deploy it into Tomcat, as described in the GT4 Admin Guide.

Run webmds-create-context-file:

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

(see the previous section for more details about webmds-create-context-file).

The Globus and WebMDS deployments install identical copies of certain files in different places. The presence of these duplicates causes WebMDS to fail when sending requests to secure servers. To prevent this problem, remove the duplicates:
```
rm $GLOBUS_LOCATION/lib/webmds/WEB-INF/lib/puretls.jar
rm $GLOBUS_LOCATION/lib/webmds/WEB-INF/lib/cryptix*.jar
rm $GLOBUS_LOCATION/lib/webmds/WEB-INF/lib/jce-jdk*.jar
```
Finally, restart Tomcat. If Tomcat is already running, stop it:
```
    $CATALINA_HOME/bin/shutdown.sh
```
Then, start Tomcat:
```
    $CATALINA_HOME/bin/startup.sh
```

4.3. 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:

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.
If tomcat is running, shut it down.
```
    $CATALINA_HOME/bin/shutdown.sh
```
Start tomcat up.
```
    $CATALINA_HOME/bin/startup.sh
```

	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.

5. 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".

For more in-depth tests, you can run the WebMDS unit tests, by doing the following:

Install httpunit, version 1.6 or later. Set the environment variable GLOBUS_HTTPUNIT_DIR to the directory into which httpunit has been installed.
Install the WebMDS test package; from the GT4 distribution directory, run
```
make gt4-webmds-test
```

Run the core WebMDS test suite. This tests the WebMDS servlet itself, the File XML Source, and the more commonly-used xslt transforms. There are two modes in which this test suite can be run.

The core WebMDS tests can be run in a servlet container simulator. This tests the WebMDS code but does not test whether or not WebMDS has been deployed correctly into Tomcat:

ant -f $GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_test/build.xml test-installed

The output should look something like this:

Buildfile: GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_test/build.xml

test-installed:
    [junit] Running org.globus.mds.webmds.test.PackageTests
    [junit] Running org.globus.mds.webmds.test.SimpleServletTest tests with servlet simulator.
    [junit] No webmds.test.servletURL property specified; skipping org.globus.mds.webmds.test.SimpleServletTest http tests
    [junit] Running org.globus.mds.webmds.test.ServletXslTests tests with servlet simulator.
    [junit] No webmds.test.servletURL property specified; skipping org.globus.mds.webmds.test.ServletXslTests http tests
    [junit] Tests run: 8, Failures: 0, Errors: 0, Time elapsed: 4.516 sec

BUILD SUCCESSFUL
Total time: 8 seconds

The core WebMDS tests can be run against a running WebMDS server, to test the local WebMDS deployment:

ant \
  -f $GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_test/build.xml \
  "-Dwebmds.test.servletURL=http://webmds_host:webmds_port/webmds/webmds" \
  test-installed

The output should look something like this:

Buildfile: GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_test/build.xml

test-installed:
    [junit] Running org.globus.mds.webmds.test.PackageTests
    [junit] Running org.globus.mds.webmds.test.SimpleServletTest tests with servlet simulator.
    [junit] Running org.globus.mds.webmds.test.SimpleServletTest tests against server at http://webmds_host:webmds_port/webmds/webmds
    [junit] Running org.globus.mds.webmds.test.ServletXslTests tests with servlet simulator.
    [junit] Running org.globus.mds.webmds.test.ServletXslTests tests against server at http://webmds_host:webmds_port/webmds/webmds
    [junit] Tests run: 8, Failures: 0, Errors: 0, Time elapsed: 5.229 sec

BUILD SUCCESSFUL
Total time: 8 seconds

The tests have passed if the number of failures and number of errors are both 0. Detailed test output can be found in the file $GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_test/test-reports/TEST-org.globus.mds.webmds.test.PackageTests.xml.

Run the WebMDS resource property node source test suite, to test the ability of WebMDS to query a running MDS4 Index Server. This test suite requires that both a secure Index server and an insecure Index server be running. As with the core tests, the resource property tests may be run in two modes.

The tests can be run in a servlet container simulator. This tests the WebMDS code, and the interaction between the WebMDS code and running Index servers, but does not test whether or not WebMDS has been deployed correctly into tomcat:

ant -f \
  $GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_resource_property_source_test/build.xml \
  "-Dwebmds.rpTest.insecureServicePrefix=http://index_server_host:index_server_port/wsrf/services" \
  "-Dwebmds.rpTest.secureServicePrefix=https://index_server_host:index_server_port/wsrf/services" \
  test-installed

The output should look something like this:

Buildfile: GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_resource_property_source_test/build.xml

test-installed:
    [junit] Running org.globus.mds.webmds.xmlSources.resourceProperties.test.PackageTests
    [junit] querying resource properties at 'http://insecure_index_server_host:insecure_index_server_port/wsrf/services/DefaultIndexService'
    [junit] querying resource properties at 'https://secure_index_server_host:secure_index_server_port/wsrf/services/DefaultIndexService'
    [junit] Tests will use Globus servers at https://secure_index_server_host:secure_index_server_port/wsrf/services/DefaultIndexService and http://insecure_index_server_host:insecure_index_server_port/wsrf/services/DefaultIndexService
    [junit] Running org.globus.mds.webmds.xmlSources.resourceProperties.test.ResourcePropertyServletTest tests with servlet simulator.
    [junit] Tests will use Globus servers at https://secure_index_server_host:secure_index_server_port/wsrf/services/DefaultIndexService and http://insecure_index_server_host:insecure_index_server_port/wsrf/services/DefaultIndexService
    [junit] No webmds.test.servletURL property specified; skipping org.globus.mds.webmds.xmlSources.resourceProperties.test.ResourcePropertyServletTest http tests
    [junit] Tests will use Globus servers at https://secure_index_server_host:secure_index_server_port/wsrf/services/DefaultIndexService and http://insecure_index_server_host:insecure_index_server_port/wsrf/services/DefaultIndexService
    [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 6.626 sec

BUILD SUCCESSFUL
Total time: 10 seconds

To run an end-to-end test that tests the communication between a deployed WebMDS server and running index servers, do the following:

ant -f \
  $GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_resource_property_source_test/build.xml \
  "-Dwebmds.rpTest.insecureServicePrefix=http://insecure_index_server_host:index_server_port/wsrf/services" \
  "-Dwebmds.rpTest.secureServicePrefix=https://secure_index_server_host:index_server_port/wsrf/services" \
  "-Dwebmds.test.servletURL=http://webmds_host:webmds_port/webmds/webmds" \
  test-installed

The output should look something like this:

Buildfile: GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_resource_property_source_test/build.xml

test-installed:
    [junit] Running org.globus.mds.webmds.xmlSources.resourceProperties.test.PackageTests
    [junit] querying resource properties at 'http://insecure_index_server_host:insecure_index_server_port/wsrf/services/DefaultIndexService'
    [junit] querying resource properties at 'https://secure_index_server_host:secure_index_server_port/wsrf/services/DefaultIndexService'
    [junit] Tests will use Globus servers at https://secure_index_server_host:secure_index_server_port/wsrf/services/DefaultIndexService and http://insecure_index_server_host:insecure_index_server_port/wsrf/services/DefaultIndexService
    [junit] Running org.globus.mds.webmds.xmlSources.resourceProperties.test.ResourcePropertyServletTest tests with servlet simulator.
    [junit] Tests will use Globus servers at https://secure_index_server_host:secure_index_server_port/wsrf/services/DefaultIndexService and http://insecure_index_server_host:insecure_index_server_port/wsrf/services/DefaultIndexService
    [junit] Running org.globus.mds.webmds.xmlSources.resourceProperties.test.ResourcePropertyServletTest tests against server at http://webmds_host:webmds_port/webmds/webmds
    [junit] Tests will use Globus servers at https://secure_index_server_host:secure_index_server_port/wsrf/services/DefaultIndexService and http://insecure_index_server_host:insecure_index_server_port/wsrf/services/DefaultIndexService
    [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 7.041 sec

BUILD SUCCESSFUL
Total time: 10 seconds

The tests have passed if the number of failures and number of errors are both 0. Detailed test output can be found in the file $GLOBUS_LOCATION/etc/globus_wsrf_mds_webmds_resource_property_source_test/test-reports/TEST-org.globus.mds.webmds.xmlSources.resourceProperties.test.PackageTests.xml.

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

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

When WebMDS sends resource property queries to a secure WSRF service instance (such as an MDS4 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 the following:
```
faultString: org.globus.common.ChainedIOException: Authentication failed 
[Caused by: Failure unspecified at GSS-API level [Caused by: Unknown CA]]
```
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
```
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
If you encounter this problem with WebMDS, you may also encounter a similar problem with the Globus container on the same system.

	Note
	If you encounter this problem with WebMDS, you may also encounter a similar problem with the Globus container on the same system.