GT 4.0 WS MDS WebMDS: System Administrator's Guide

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 define these xml sources (e.g., "get resource property X from service Y" or "read file Z") and HTML form arguments to select among them (e.g., "use xml source A to find the raw data to present, and use xml source B to find the XSL transform to filter it through"). These configuration files live in the directory $GLOBUS_LOCATION/lib/webmds/conf. When WebMDS receives a request, it uses the configuration information in the configuration file whose name is the same as the value of the info form argument to determine how to get the raw data to present, and the configuration file whose name is the same as the value of the xsl form argument to determine how to get the xsl transform to use to filter the data.

In version 4.0.5, WebMDS also uses a global configuration file to enable or disable various WebMDS features.

By default, WebMDS comes with configuration files that can be used to query an index server using transaction-level security on the default port (8443) on the local system and to use an xsl transform to present that information in summary form. 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

3.2.1. Configuring XML Sources

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

indexinfoall resource properties from an index server running with transaction-level security on port 8443 on the local host
indexinfo_nosecall resource properties from an index server running with no security on port 8080 on the local host
openEndedQueryall resource properties from a user-specified grid service
openEndedRPa user-specified resource property from a user-specified grid service
servicegroupxslan xsl transform that presents summary information about a service group
sgedetailan 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.2.2. Global Configuration (version 4.0.5 only)

The global configuration file $GLOBUS_LOCATION/lib/webmds/globalconfig.xml is used to specify whether or not options new in version 4.0.5 are enabled. By default, the new options are disabled:

<WebmdsGlobalConfig>
  <newStyleErrors>false</newStyleErrors>
  <allowUserSpecifiedQuery>false</allowUserSpecifiedQuery>
</WebmdsGlobalConfig>

Setting newStyleErrors to true will cause WebMDS to display easier-to-understand messages when errors occur.

Setting allowUserSpecifiedQuery to true will cause WebMDS to honor form arguments that specify xpath queries to run.

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

fileThe 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

classThe name of a class that implements the WebmdsNodeSource interface. An instance of this class will be used to get an XML document.
parametersAdditional 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

endpointThe endpoint name to be used in a resource property query.
endpointKeyName and endpointKeyValueAn optional key/value pair to use as reference properties for the endpoint specified with the endpoint parameter.
allowUserEndpointsIf 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.
endpointFileThe name of a file from which the endpoint information (in XML) will be read. This configuration parameter can never be overridden by request arguments.
xpathQueryAn xpath query to run. This configuration parameter is only recognized from request arguments, and is only available in version 4.0.5 and later (and only if the global allowUserSpecifiedQuery option is set).

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

endpointThe endpoint name to be used in a resource property query.
endpointKeyName and endpointKeyValueAn optional key/value pair to use as reference properties for the endpoint specified with the endpoint parameter.
allowUserEndpointsIf 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.
endpointFileThe name of a file from which the endpoint information (in XML) will be read. This configuration parameter can never be overridden by request arguments.
rpNamespaceThe namespace part of the QName of the resource property to be queried for.
rpNameThe 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 one of the supported versions of Tomcat and set the $CATALINA_HOME environment variable to the directory into which you've installed Tomcat.

4.1. Standard deployment into Tomcat

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. Also, in some Tomcat installations, you may need to create the directories $CATALINA_HOME/conf/Catalina and $CATALINA_HOME/conf/Catalina/localhost.

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:

  1. Install Globus and deploy it into Tomcat, as described in the GT4 Admin Guide.
  2. 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).

  3. 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
    
  4. 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 one of the supported versions of Tomcat 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]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.

        $CATALINA_HOME/bin/shutdown.sh
    
  3. Start tomcat up.

        $CATALINA_HOME/bin/startup.sh
    

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:

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

    make gt4-webmds-test
    
  3. 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.

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

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

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