Trigger Variables
Moab Workload Manager®

19.5 Trigger Variables

19.5.1 Trigger Variables Overview

Trigger variables can add greater flexibility and power to a site administrator who wants to automate certain tasks and system behaviors. Variables allow triggers to launch based on another trigger's behavior, state, and/or output.

Example

Setting Variables
AType=exec,Action="/tmp/trigger1.sh",EType=start,Sets=Var1 \
AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=Var1

In this example the first trigger will assign a value to the variable Var1 if Var1 is included in the output of the script (meaning the script '/tmp/trigger1.sh' will produce the output "Var1=34.234l" and Moab will internally set the value of Var1 to 34.324l). The second trigger will look to make sure that Var1 has been set and then it will add its value to the launch script (referencing its value using the $ operator), effectively launching /tmp/trigger2.sh with the value of the variable Var1 as a parameter, which would be accessed in the script through $1. Any additional variables would be accessed through $2, $3, and so forth.

Example

Multiple Variable Usage
AType=exec,Action="/tmp/trigger1.sh",EType=start,Sets=Var1.Var2 \
AType=exec,Action="/tmp/trigger2.sh $Var1 $Var2",EType=start,Requires=Var1.Var2

In this example, the first trigger sets two variables (separated by a '.'), which are received in the second (separated by a ':'). As previously mentioned, those arguments could be accessed in the second trigger through the variables $1 and $2.

It is also possible to have a trigger set a variable when it fails using the '!' symbol:

Example

Setting Variables on Failure
AType=exec,Action="/tmp/trigger1.sh",EType=start,Sets=!Var1.Var2 \
AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=Var1 \
AType=exec,Action="/tmp/trigger3.sh",EType=start,Requires=Var2

In this example, the first trigger will set Var1 if it fails and Var2 if it succeeds. The second trigger will launch if Var1 has been set (the first trigger failed). The third trigger will launch if Var2 is set (the first trigger succeeded).

Variable requirements can be further refined to allow for the evaluation and comparison of the variable's value. That is, triggers can have a dependency on a variable having (or not having) a certain value. The format for this is as follows:

[*]<VARID>[:<TYPE>[:<VARVAL>]]

The optional * specifies that the dependencies are satisified by an external source that must be previously registered. A number of valid comparison types exist:

Type Comparison Notes
set is set (exists) Default
notset not set (does not exits) Same as specifying '!' before a variable
eq equals  
ne not equal  
ge greater than Integer values only
le less than Integer values only
ge greater than or equal to Integer values only
le less than or equal to Integer values only

Following is an example of how these comparitive dependencies can be expressed when creating a trigger.

Example

Comparitive Variable Dependencies
AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=Var1:eq:45 \
AType=exec,Action="/tmp/trigger3.sh",EType=start,Requires=Var2:ne:failure1

In this example, the first trigger will fire if Var1 exists and has a value of 45. The second trigger will only fire if Var2 is not the string failure1.

19.5.2 Default Internal Variables Available to Trigger Scripts

Several internal variables are available for use in trigger scripts. These can be accessed using $<VARNAME>:

  • OID is the name of the object to which the trigger was attached.
  • OTYPE is the type of object to which the trigger is attached; can be rsv, job, node, or sched.
  • TIME is the time of the trigger launch.
  • HOSTLIST is the HostList of the trigger's object (when applicable).
  • OWNER is the owner of the trigger's object (when applicable).
  • USER is the user (when applicable).

Other unique variables are available to triggers attached to specific objects:

Jobs

  • MASTERHOST — The primary node for the job.
  • HOSTLIST — The entire hostlist of the job.

Reservations

  • GROUPHOSTLIST — The hostlist for the reservation and all of its peers. (In the case of VPCs, the aggregate hostlist for all VPC reservations.)
  • HOSTLIST — The entire hostlist for the reservation.
  • OS — The operating system on the first node of the reservation.

VPCs

  • VPCID — The ID of the parent VPC.
  • VPCHOSTLIST The HostList for the entire VPC. (NOTE: may or may not be dedicated.)

NOTE: By default, the reservation group master (first reservation created) of a VPC automatically imports the variables of the parent VPC. Other non-master reservation children of the VPC do not automatically import these VPC variables, and if this information is required by associated reservation triggers, it must be explicitly imported as described later.

Example

Using Internal Valiables
AType=exec,Action="/tmp/trigger3.sh $OID $HOSTLIST",EType=start

In this example, the object ID ($OID) and hostlist ($HOSTLIST) will be passed to /tmp/trigger3.sh as command line arguments when the trigger executes the script. The script can then process this information as needed.

19.5.3 Importing Variables from Other Objects

By default, triggers may access variables located in their own environment and in the environment of a master object. However, in some cases, it is necessary to load variables or configuration information from parent or peer objects. Using a query trigger, certain environment variables (see table that follows) may be imported from one object to another. Query triggers are created by specifying an action type (trigger attribute atype) of query and a trigger action in the format <label>:<variable>. To associate a label with a peer object, use the label attribute when specifying resource requirements (reqs) via the mshow command or the VCPROFILE parameter.

Requested Variable Exported Variable Description
AllocNodeList <label>-HOSTLIST Comma delimited list of hosts allocated to queried object.
ReqOS <label>-OS Operating system requested for queried object.
Variable=<name> <label>-<name> Generic variables local to queried object.

NOTE: When a query trigger is run within a reservation group, the variable is imported into the master reservation, and consequently, the variable is made available to all other peer reservation triggers.

Example 1

Import the ReqOS requirement from the compute reservation and the vlanid variable from the vlan reservation.

moab.cfg
RSVPROFILE[head]  TRIGGER=atype=query,action=compute:ReqOS,etype=start
RSVPROFILE[head]  TRIGGER=atype=query,action=vlan:Variable=vlanid,etype=start
RSVPROFILE[head]  TRIGGER=atype=exec,action="/bin/echo
$compute-OS $vlan-vlanid",etype=start,requires=compute-OS
...

Example 2

Import the Allocated Node List from the compute reservation echo it to stdout.

moab.cfg
RSVPROFILE[test] TRIGGER=atype=query,action=compute:AllocNodeList,etype=start,sets=QUERY
RSVPROFILE[test] TRIGGER=atype=exec,action="/bin/echo $compute-HOSTLIST",etype=start,requires=QUERY
...

NOTE: In the case of multiple reservations with the same label, a "-<#>" may be appended to the variable to access a specific reservations environment.

19.5.4 Externally Injecting Variables into Job Triggers

For triggers that are attached to job objects, another method for supplying variables exists. The trigger is able to see the variables in the job object to which it is attached. Updating the job object's variables effectively updates the variable for the trigger. This can be accomplished through the use of mjobctl using the -m flag.

mjobctl -m
> mjobctl -m var=Flag1=TRUE 1664

This sets the variable Flag1 to the value TRUE, creating Flag1, if necessary. This will be seen by any trigger attached to job 1664.

19.5.5 Exporting Variables to Parent Objects

Variables used and created by triggers are stored in the namespace of the object to which the trigger is attached. Sometimes it is desirable to make certain variables more accessible to triggers on other objects. When using the Sets trigger attribute, you can specify that a variable, created either by a success or failure, should be exported to the name space of the parent object when the current object is destroyed through a completion event. This is done by placing the caret (^) symbol in front of the variable name when specifying it.

Example

Exporting Variables to Parent Object
AType=exec,Action="/tmp/trigger1.sh",EType=start,Sets=^Var1.!^Var2 \
AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=Var1 \
AType=exec,Action="/tmp/trigger3.sh",EType=start,Requires=Var2

In this example, both Var1 and Var2 will be exported to the parent object when the trigger has completed. They can also be used by triggers at their own level, just as in previous examples.

19.5.6 Requiring Variables in Parent Objects

By default, triggers will only look for variables to fulfill dependencies in the object to which they are directly attached. In addition, if they are attached to a job object, they will also look in the job group, if defined. However, it is not uncommon for objects to have multiple generations of parent objects. If the desired behavior is to search through all generations of parent objects, the caret (^) symbol must be specified, as in the following example:

Example

Requiring Variables in Parent Objects
AType=exec,Action="/tmp/trigger2.sh",EType=start,Requires=^Var1

See Also
© 2001-2008 Cluster Resources, Incorporated