This guide contains advanced configuration information for system administrators working with the WS MDS Trigger Service. 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 GT 4.1.0 System Administrator's Guide. Read through this guide before continuing!

2. Building and Installing

The Trigger Service is installed as part of the standard Globus Toolkit installation.

3. Configuring

The trigger service is an MDS aggregator service, and so inherits much of its configuration system from the Aggregator Framework module.

3.1. Configuring the Aggregator Framework

The Aggregator Framework does not have its own service side configuration, although services which are based on the framework have their own service side configuration options (such as MDS Index and MDS Trigger") which are documented in the per-service documentation.

Registrations to a working Aggregator Framework are configured for the mds-servicegroup-add(1) tool. This tool takes an XML configuration file listing registrations, and causes those registrations to be made.

In general, configuration of aggregator services involves configuring the service to get information from one or more sources in a Grid. The mechanism for doing this is defined by (inherited from) the Aggregator Framework and described in this section.

3.1.1. Configuration overview

Configuring an Aggregating Service Group to perform a data aggregation is performed by specifying an AggregatorContent object as the content parameter of a ServiceGroup add method invocation. An AggregatorContent object is composed of two xsd:any arrays: AggregatorConfig and AggregatorData:

The AggregatorConfig xsd:any array is used to specify parameters that are to be passed to the underlying AggregatorSource when the ServiceGroup add method is invoked. These parameters are generally type-specific to the implementation of the AggregatorSource and/or AggregatorSink being used.
The AggregatorData xsd:any array is used as the storage location for aggregated data that is the result of message deliveries to the AggregatorSink. Generally, the AggregatorData parameter of the AggregatorContent is not populated when the ServiceGroup add method is invoked, but rather is populated by message delivery from the AggregatorSource.

3.1.2. Syntax of the interface

3.1.2.1. Configuring the Aggregator Sources

The following links provide information for configuring the three types of aggregator sources provided by the Globus Toolkit:

3.1.2.2. Configuring the Aggregator Sink

An aggregator sink may require sink-specific configuration (the MDS Trigger Service requires sink-specific configuration; the MDS Index Service does not). See the documentation for the specific aggregator service being used for details on sink-specific documentation.

3.2. Additional configuration for the Trigger Service

In addition to the source parameters specified above, the TriggerRuleType element must be added to all registrations made to the trigger service.

The TriggerRuleType is defined in trigger-types.xsd in trigger/source.

This registration parameter contains the following options:

matchingRule: XPath rule to be applied against incoming data. The XPath expression will be evaluated against aggregated data, and will be regarded as matching the incoming data if it matches one or more nodes in that data.
namespaceMappings: An array of string namespace mappings in the form xmlns:foo=http://foo.bar. This array of namespace mappings will be used to resolve namespace prefixes used in the XPath matchingRule statement.
actionScript: the logical name of a script that will be executed when the matchingRule matches (except as rate limited). This logical name must be mapped to a physical file name located in the $GLOBUS_LOCATION/libexec/trigger/ directory. The logical-to-physical filename mapping is specified in the executableMappings parameter of the triggerConfiguration block of the file $GLOBUS_LOCATION/etc/globus_wsrf_mds_trigger/jndi-config.xml.
minimumFiringInterval: the action script will not be executed more than once in this number of seconds. If unspecified, there will be no minimum interval.
minimumMatchTime: the matchingRule must be true for this number of seconds before the actionScript will be executed. If unspecified, there is no minimum time period that the rule must match and the rule will be eligible to fire immediately after the matchingRule becomes true.
invalidityTime: An array of TriggerInvalidityTime time ranges during which the trigger will not fire under any condition. If the current trigger fire time falls within any of the time ranges present in this variable, the trigger will not fire.
enableFilteredActionScriptInput: If this value is present and set to true, the service will pass the filtered output result of the XPath matchingRule as additional input to the stdin of the action script, in addition to the original input to which the matching rule was applied. The default behavior if unspecified is false, meaning the Xpath query result will not be passed as input to the action script.
disableUnmodifiedActionScriptInput: If this value is present and set to true the service will not pass the original trigger message input (to which the matching rule was applied) to the action script. The default behavior is to always pass the entire input message to the action scripts. For action scripts which do not need to consume the unmodified input, this variable may be set to true in order to increase performance.
outputXSL: (CURRENTLY UNIMPLEMENTED) The delivered message will be transformed by the specified XSLT stylesheet and fed into the stdin of the action script.

The rate limiting parameters behave in such a way that the rate of action script executions can be decreased by increasing the minimumFiringInterval and/or by increasing the minimumMatchTime.

3.3. Example of a trigger registration file

A complete and working example of a trigger registration file can be viewed at $GLOBUS_LOCATION/etc/globus_wsrf_mds_trigger/trigger-aggregator-registration.xml

4. Deploying

This component is deployed as part of the standard toolkit installation. By default, there are no trigger actions set to fire on container startup, as these must be configured and registered manually.

4.1. Manually registering the Trigger Service

To manually register the example described in Configuring the Trigger Service (above) do the following:

Configure your environment with either Ganglia or Hawkeye as described in the GLUE RP documentation. This is necessary because the trigger service relies on polling the GLUE RP which is provided by either one of them. Note: Even without configuring Ganglia or Hawkeye, the GLUE RP is emitted by the scheduler configured for your environment, so this step is not strictly necessary.
Now you can start your container as you normally do by running:
```
$GLOBUS_LOCATION/bin/globus-start-container
```

At this point, we're ready to make a registration with the DefaultTriggerService by running a command similar to the following:

$GLOBUS_LOCATION/bin/mds-servicegroup-add -s \
     https://127.0.0.1:8443/wsrf/services/DefaultTriggerService \        
     $GLOBUS_LOCATION/etc/globus_wsrf_mds_trigger/trigger-aggregator-registration.xml

You should see output similar to the following if your environment has been configured properly:

Processing configuration file...
Processed 1 registration entries
Successfully registered
https://127.0.0.1:8443/wsrf/services/ManagedJobFactoryService to servicegroup at 
https://127.0.0.1:8443/wsrf/services/DefaultTriggerService

4.2. Deploying into Tomcat

The WS MDS Trigger Service has been tested to work without any additional setup when deployed into Tomcat. Please follow these basic instructions to deploy GT4 services into Tomcat. Note: please complete any prerequisite service configuration steps before you deploy into Tomcat.

5. Testing

To determine if the registration was made properly, you can query the DefaultTriggerService using a tool like $GLOBUS_LOCATION/bin/wsrf-query and visually inspect the output.

For example, running:

$GLOBUS_LOCATION/bin/wsrf-query -s \
     https://127.0.0.1:8443/wsrf/services/DefaultTriggerService "/*"

should yield output similar to the following for the example above:

...
  <ns1:Content xsi:type="ns11:AggregatorContent"
  xmlns:ns11="http://mds.globus.org/aggregator/types">
   <ns11:AggregatorConfig>
    <ns11:GetResourcePropertyPollType>
                <ns11:PollIntervalMillis>600000</ns11:PollIntervalMillis>
                <ns11:ResourcePropertyName>glue:GLUECE</ns11:ResourcePropertyName>
         </ns11:GetResourcePropertyPollType>
    <ns3:TriggerRuleType
    xmlns:ns3="http://mds.globus.org/2004/08/trigger/types">
                <ns3:matchingRule>//*[local-name()='GLUECE']</ns3:matchingRule>
                <ns3:actionScript>glue-trigger-action.sh</ns3:actionScript>
                <ns3:minimumFiringInterval>600</ns3:minimumFiringInterval>
         </ns3:TriggerRuleType>
   </ns11:AggregatorConfig>
   <ns11:AggregatorData>
    <ns12:TriggerStatus>
     <ns12:conditionTrueSince>2005-04-11T16:31:00.501Z</ns12:conditionTrueSince>
     <ns12:actionFiredAt>2005-04-11T16:31:00.656Z</ns12:actionFiredAt>
     <ns12:ruleLastCheckedAt>2005-04-11T16:31:00.493Z</ns12:ruleLastCheckedAt>
     <ns12:actionOutput>
      <exampleGLUETriggerActionScriptOutput xmlns="">
        <glueDataDetected>true</glueDataDetected>
      </exampleGLUETriggerActionScriptOutput>
     </ns12:actionOutput>
    </ns12:TriggerStatus>
   </ns11:AggregatorData>
  </ns1:Content>
...

The included sample trigger script not only emits some XML data as seen above in the actionOutput node, but it also attempts to append some data to a file each time it is fired. Thus, to be sure it is working properly, you can inspect the file /tmp/glue_detected by running a command like

cat /tmp/glue_detected

which should yield output similar to this:

GLUECE RP was detected in the output at Mon Apr 11 11:01:01 CDT 2005 
GLUECE RP was detected in the output at Mon Apr 11 11:11:00 CDT 2005 
GLUECE RP was detected in the output at Mon Apr 11 11:21:00 CDT 2005 
GLUECE RP was detected in the output at Mon Apr 11 11:31:00 CDT 2005 
GLUECE RP was detected in the output at Mon Apr 11 11:41:00 CDT 2005

6. Security Considerations

The security considerations for the Aggregator Framework also apply to the Trigger Service:

By default, the aggregator sources do not use authentication credentials -- they retrieve information using anonymous SSL authentication or no authentication at all, and thus retrieve only publicly-available information. If a user or administrator changes that configuration so that a service's aggregator source uses credentials to acquire non-privileged data, then that user or administrator must configure the service's aggregator sink to limit access to authorized users.

7. Troubleshooting

Problem: I'm sure the registration was made properly, but the trigger script never fires.

Solution: Verify that you've properly configured the GLUE RP output via Ganglia or Hawkeye. Even a properly made trigger registration will never fire if the GLUE RP cannot be produced.

8. Usage statistics collection by the Globus Alliance

The following WS MDS-specific usage statistics are sent in a UDP packet every 60 minutes, in addition to the standard header information described in the Usage Stats section.

Service Name (service group)
Total number of registrations i.e., successfully invoked service group add operations made against the resource during its lifetime
Current number of registrants (service group entries)
The resource creation time

	Note
	The client (mds-servicegroup-add) does NOT send any data. It is the server components that send the usage statistics.

Also, please see our policy statement on the collection of usage statistics.

Prev	Up	Next
GT 4.1.0 Release Notes: WS MDS Trigger Service	Home	GT 4.1.0 WS MDS Trigger Service: User's Guide