GT 4.2.1 WS MDS Trigger Service: Developer's Guide

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.

First things first -- in order to run most Globus commands, you must have your environment set up correctly and have a valid proxy certificate. To set up your environment, first set the GLOBUS_LOCATION environment variable to the directory in which Globus is installed. To finish setting up your environment, run:

. $GLOBUS_LOCATION/etc/globus-user-env.sh

if you're a Bourne shell user, or

source $GLOBUS_LOCATION/etc/globus-user-env.csh

if you're a C shell user. Finally, generate a proxy certificate with:

$GLOBUS_LOCATION/bin/grid-proxy-init -verify -debug

Next, we will specify what commands can be used in Trigger Service triggers. The Trigger Service comes with some simple action scripts in the $GLOBUS_LOCATION/libexec/trigger directory; we will edit the $GLOBUS_LOCATION/etc/globus_wsrf_mds_trigger/jndi-config.xml file to enable them:

<?xml version="1.0" encoding="UTF-8"?>
<jndiConfig xmlns="http://wsrf.globus.org/jndi/config">
    <global>
       <resource name="configuration"
                 type="org.globus.mds.aggregator.impl.AggregatorConfiguration">
            ...
       </resource>
      
       <resource name="triggerConfiguration"
                 type="org.globus.mds.trigger.impl.TriggerConfiguration">
          <resourceParams>
             <parameter>
                 ...
             </parameter>
             <parameter>
	        <name>executableMappings</name>
	        <value>trigger-action-default=trigger-action-default.sh, trigger-action-input-default=trigger-action-input-default.sh</value>
	     </parameter>
	  </resourceParams>
       </resource>  
                    
    </global>
    
    <service name="TriggerRegistrationService">
          ...
    </service>
       ...

</jndiConfig>
      

This jndi-config.xml file defines an executableMappings parameter. The format of the executableMappings parameter is a sequence of name=value strings, separated by commas. The left hand side of each name/value pair is the name that users will specify in trigger definitions; the right hand side is the path name (relative to the $GLOBUS_LOCATION/libexec/trigger directory) of the program to execute. In this example, we define two trigger actions: trigger-action-default maps to $GLOBUS_LOCATION/libexec/trigger/trigger-action-default.sh, and trigger-action-input-default maps to $GLOBUS_LOCATION/libexec/trigger-action-input-default.sh. These action scripts are distributed as part of the Globus distribution. The version of $GLOBUS_LOCATION/etc/globus_wsrf_mds_trigger/jndi-config.xml distributed with Globus has these mappings defined in a commented-out section; in order to continue with this example, you must uncomment them.

Before you continue, you'll need to restart your Globus container to make the changes to jndi-config.xml take effect. If you normally use /etc/init.d/gt4container, then you can type /etc/init.d/gt4container restart, or you can kill the running Globus container (if there is one) and run $GLOBUS_LOCATION/etc/globus-start-container-detached by hand. If you have a production container running and want to test the trigger service with a different instance on another port, you can run globus-start-container-detached -p NNNN to cause the new container to listen on port NNNN.

The next thing we will do is configure the trigger service to collect some information (we will later configure the trigger service to periodically run a query on that information and, based on the results of the query, take some action). In this example, we will configure the trigger service to collect infoformation by querying the Default Index Service running in the same Globus container for the entire contents of its index.

The Trigger Service uses the Aggregator Framework to configure its sources of information. Aggregator sources are configured through a service interface; we will create a file specifying configuration parameters and then run the mds-servicegroup-add command to read that configuration file and register the configuration information with the Trigger Service. We will start with the example trigger registration file included with Globus distributions in $GLOBUS_LOCATION/etc/globus_wsrf_mds_trigger/trigger-registration-example.xml

  <DefaultServiceGroupEPR>
    <wsa:Address>https://localhost:8443/wsrf/services/TriggerRegistrationService</wsa:Address>
  </DefaultServiceGroupEPR>
  <ServiceGroupRegistrationParameters
      xmlns="http://mds.globus.org/servicegroup/client"
      xmlns:wsa="http://www.w3.org/2005/08/addressing"
      xmlns:agg="http://mds.globus.org/aggregator/types">
    <RegistrantEPR
        xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsa:Address>https://localhost:8443/wsrf/services/DefaultIndexService</wsa:Address>
    </RegistrantEPR>
    <RefreshIntervalSecs>600</RefreshIntervalSecs>
    <Content xsi:type="agg:AggregatorContent"
             xmlns:agg="http://mds.globus.org/aggregator/types">
      <agg:AggregatorConfig xsi:type="agg:AggregatorConfig">
        <agg:GetResourcePropertyPollType 
             xmlns:wssg="http://docs.oasis-open.org/wsrf/sg-2">
          <agg:PollIntervalMillis>30000</agg:PollIntervalMillis>
          <agg:ResourcePropertyName>wssg:Entry</agg:ResourcePropertyName>
        </agg:GetResourcePropertyPollType>
      </agg:AggregatorConfig>
      <agg:AggregatorData />
    </Content>
  </ServiceGroupRegistrationParameters>
</ServiceGroupRegistrations>

For this example, the only items in the registration file that you might need to edit are the DefaultServiceGroupEPR (the address of your trigger registration service) and the RegistrantEPR (the address of the resource you want to monitor; in this case, your Default Index Service). If these look correct (i.e., the host names and port numbers correspond to the Globus container you just started), then you do not need to edit this file at all.

Finally, run mds-servicegroup-add to register these configuration parameters to the Trigger Service:

mds-servicegroup-add $GLOBUS_LOCATION/etc/globus_wsrf_mds_trigger/trigger-registration-example.xml &

Of course, if you copied the trigger-registration-example.xml file before editing it, you would use the name of the edited file instead. The output from mds-servicegroup-add should look something like this:

Processing configuration file...
INFO: Processed 1 registration entries
INFO: Successfully registered https://localhost:8443/wsrf/services/DefaultIndexService to servicegroup at https://localhost:8443/wsrf/services/TriggerRegistrationService

Warning

In general, it's a bad idea to use loopback addresses like "localhost" or "127.0.0.1" in MDS configuration files (because if you configure a remote host to poll "localhost" for information, the remote host will poll itself, not the host that the mds-servicegroup-add command was run from). We can get away with it here because all the addresses we're using are local, but in real life, it's better to use non-local IP addresses or fully-qualified domain names

Now, we're going to define a trigger that checks how many Entries are being registered by the Index Service and then takes actions based on the results. But first, let's check how many Entries are being registered by the Index Service. Type the following command in one line (substituting your hostname and port if appropriate):

$GLOBUS_LOCATION/bin/wsrf-query -s https://127.0.0.1:8443/wsrf/services/DefaultIndexService 'count(//*[local-name()="Entry"])'

On our setup we get: 3.

At this point, the Trigger Service is collecting information, but we haven't told it to do anything with that information. We will now follow a few simple steps to set up a trigger.

To view more details about this particular trigger, type:

mds-trigger-view -b https://127.0.0.1:8443/wsrf/services \
        546aae00-418b-11dd-a5ea-ebfac2dfbbee

   MDS4 Trigger View Client
   ------------------------

----Detailed Trigger Information----------------------------

MONITORED SERVICE:  https://127.0.0.1:8443/wsrf/services/DefaultIndexService
TriggerID:          546aae00-418b-11dd-a5ea-ebfac2dfbbee
TRIGGER NAME:       Default Trigger Name

MATCHING RULE:      count(//*[local-name()='Entry'])>0
ACTION SCRIPT:      trigger-action-default
TRIGGER STATUS:     enabled

ENABLE BOOLEAN:                         true
ACTION SCRIPT INPUT FULL ORIGINAL:      true
ACTION SCRIPT INPUT XPATH QUERY RESULT: true

MINIMUM FIRING INTERVAL: 20
MINIMUM MATCH TIME:      30

START TIME:            N/A
END TIME:              N/A

INVALIDITY START TIME: N/A
INVALIDITY END TIME:   N/A

----Non-editable stats--------------------------------------
RULE LAST CHECKED AT: 2008-06-23 19:09:18 PDT-0700
CONDITION TRUE SINCE: 2008-06-23 19:03:48 PDT-0700
ACTION FIRED AT:      2008-06-23 19:09:18 PDT-0700
------------------------------------------------------------

Now after a minute or so, you will notice that the trigger has fired successfully. You can verify this by checking the contents of the log file we created in our action script from above:

more $GLOBUS_LOCATION/trigger_service_base_action_log

This should look similar to the following

Trigger Service Entry: Sun Jun 17 14:45:26 CDT 2007
Trigger Service Entry: Sun Jun 17 14:45:56 CDT 2007
Trigger Service Entry: Sun Jun 17 14:46:26 CDT 2007
Trigger Service Entry: Sun Jun 17 14:46:56 CDT 2007
      

There is a 30 second interval that we specified in our aggregator configuration file above. This should probably be lengthened eventually so that you don't have the triggers going off so often.

You have now successfully setup, configured, registered, created, edited and tested a trigger from scratch!

Next Steps: Check out the documentation and create more triggers to perform actions more relevant to your own objectives. Experiment with the XPath queries to expand the possibilities of what you can use them for. If you have questions, feel free to [fixme contact us]!

For MDS Trigger troubleshooting information, see Troubleshooting MDS Trigger.

Server side logging can be configured in $GLOBUS_LOCATION/container-log4j.properties, when the container is stand alone container. For tomcat level logging, refer to Logging for Tomcat, . The logger log4j.appender.A1 is used for developer logging and by default writes output to the system output. By default it is set for all warnings in the Globus Toolkit package to be displayed.

Additional logging can be enabled for a package by adding a new line to the configuration file. Example:

   #for debug level logging from org.globus.package.FooClass 
   log4j.category.org.globus.package.name.FooClass=DEBUG
   #for warnings from org.some.warn.package
   log4j.category.org.some.warn.package=WARN
   

Client side logging can be configured in $GLOBUS_LOCATION/log4j.properties. The logger log4j.appender.A1 is used for developer logging and by default writes output to the system output. By default it is set for all warnings in the Globus Toolkit package to be displayed.