23.5 The Action Script

23.5 The Action Script

Every Application resource must have an action script. The action script starts and stops the application resource as well as optionally checking the status of the application resource.

The action script can be written in any language. The only requirement is that the script accept a "start", "stop", and (optionally) "check" arguments on the command line.

myAppResource.scr start	– Starts myAppResource
myAppResource.scr stop	– Stops myAppResource
myAppResource.scr check	– Checks the status of myAppResource

The TruCluster Server software includes a template.scr that the caa_profile command uses to create an application resource. The template.scr script, which is located in the /var/cluster/caa/template directory, includes all three entry points.

Note

The template.scr script is different in nearly every TruCluster Server release we've seen to date. Therefore, the output in this book that pertains to this script may differ from that on your cluster.

23.5.1 Application Resource Action Script Tips

This section contains suggestions for what to think about when writing an action script.

1. Completely test your script before registering your application resource.

2. The action script should be named in the form of AppResourceName.scr.

   If your application resource is named "guitar", then it is a good idea to name the action script guitar.scr. This is not a requirement, but we recommend keeping things consistent and simple to avoid confusion.

3. Make sure that your script is located in the /var/cluster/caa/script directory and that you edit the ACTION_SCRIPT attribute in the application resource's profile to be the name of the script. If you choose to place the action script in an alternate directory, make sure it is on a disk physically shared by all members in the cluster and not mounted as a partitioned file system. Partitioned file systems were covered in Chapter 13. If the action script is located in an alternate directory, then the ACTION_SCRIPT attribute must contain the full pathname.

   If the action script is…

   in /var/cluster/caa/script	– ACTION_SCRIPT = guitar.scr
   not in /var/cluster/caa/script	– ACTION_SCRIPT = /altScrDir/guitar.scr

   We recommend keeping all action scripts in the /var/cluster/caa/script directory.

4. Add environment variables that the action script may need to properly execute.

   The action script will not be running with the benefit of the environment variables that are in a user's .profile, .kshrc, .cshrc, or .login scripts. For example, if the application were an X Window System application, the DISPLAY environment variable would need to be set.

5. Verify that the action script has the execute permission bit set.

6. Verify that the action script is owned by root, and that only root has permission to write to the script.

7. The exit status is defined as:

   0	(zero)	– Success
   !0	(not zero)	– Failure

8. If your application is designed to run in the foreground, make sure to put it in the background otherwise your action script will timeout (see SCRIPT_TIMEOUT in Table 23-5), which is considered a failure by caad.

9. Remember to redirect stdin, stdout, and stderr if necessary.

23.5.2 Redirecting Action Script Output

By default an action script does not open stdin, stdout, and stderr. So, if you need your action script to receive input and/or write output, you will need to handle this explicitly.

For example, within the action script for the memberUP resource, we placed "print" statements within the start and stop entry points. We did not redirect the output.

 # grep print memberUP.scr    print "Entering the 'start' entry point for $_CAA_NAME..."    print "Entering the 'stop' entry point for $_CAA_NAME..." 

We will start the memberUP resource.

 # caa_start memberUP Attempting to start 'memberUP' on member 'sheridan' Start of 'memberUP' on member 'sheridan' succeeded. 

Note that the output does not include our print statement.

There are a couple of methods of getting information from your action script:

• Redirect stdin, stdout, and stderr as you would within any script.

   $START_APPCMD > $tmpfile 2>&1 

• Set the _CAA_UI_FMT environment variable, which was introduced in V5.1A-IPK, to redirect output of an action script to your stdout when using the caa_start, caa_stop, and caa_relocate commands.

  Valid values for the _CAA_UI_FMT environment variable are:

  • v – Verbose

     sheridan:memberUP:Entering the 'start' entry point for memberUP... 

  • vs – Verbose, but suppress the "member:resource:" information

     Entering the 'start' entry point for memberUP... 

Set the environment as you would any shell environment variable.

To complete the example we started at the beginning of this section, let's set the environment variable and then stop the memberUP resource.

 # export _CAA_UI_FMT=v 

 # caa_stop memberUP Attempting to stop 'memberUP' on member 'sheridan' Stop of 'memberUP' on member 'sheridan' succeeded. sheridan:memberUP:Entering the 'stop' entry point for memberUP... 

You can see by the previous output, stdout was redirected as expected.

23.5.3 CAA Action Script Environment Variables

Introduced in V5.1A-IPK, an application resource action script is able to access a number of environment variables in the following categories:

• Profile Attributes

• Reason Codes

• User-Defined Attributes

• Locale Information

23.5.3.1 Profile Attribute Environment Variables

Any profile attribute can be accessed within an application resource's action script by adding the "_CAA_" prefix to the attribute name.

To see the resource's SCRIPT_TIMEOUT value, use the _CAA_SCRIPT_TIMEOUT environment variable for example.

Here is a short and extremely simple code snippet (in Korn shell) illustrating how you can make decisions based on the value of a particular attribute value.

 # grep -p ARG memberUP.scr if [[ $_CAA_REQUIRED_RESOURCES != "" ]] then    ARG="REQ" fi if [[ $_CAA_OPTIONAL_RESOURCES != "" ]] then    ARG="${ARG}OPT" fi START_APPCMD="/code/caa/xhostname $ARG" 

← If there are any Required Resources…
← Set ARG to "REQ"
← If there are any Optional Resources…
← Set ARG to the current value of ARG plus the string "OPT".

In this example, the action script checks to see if the resource has any required or optional resources that it depends upon. If it does, an additional parameter is passed to the program that the resource will start.

The REQUIRED_RESOURCES and OPTIONAL_RESOURCES are shown in the following output.

 # caa_stat -p memberUP | grep _RESOURCE OPTIONAL_RESOURCES=nicUP REQUIRED_RESOURCES=powerUP 

So the START_APPCMD would be set to "/code/caa/xhostname REQOPT".

23.5.3.2 Reason Code Environment Variable

When an application resource's action script is called, the _CAA_REASON environment variable is set to the reason the script was called. Valid reasons are shown in Table 23-14.

Table 23-14: CAA Reason Codes

CAA Reaspm Codes
Reason	Description
user	The action script was invoked by user action. The cluster administrator ran a caa_* command.
failure	The action script was invoked from the result of a failure condition. This reason is usually set as a result of failure in the "check" entry point.
dependency	The action script was invoked as a result of being a dependency of another resource. For example, if the powerUP resource is a dependent of the memberUP resource, and both resources are OFFLINE, then if the memberUP resource is started, the powerUP resource would also be started. This value would be set in the _CAA_REASON environment variable for powerUP.
boot	The action script was invoked when the cluster was booted. The resource was running prior to cluster shutdown.
autostart	The action script was invoked when the cluster was booted. The resource's AUTO_START attribute was set to 1 and the resource was OFFLINE prior to cluster shutdown.
system	The action script was invoked by the system during normal maintenance.
unknown	If the _CAA_REASON is set to this state the action script was invoked when the internal state was unknown. If this value is set, record the state of the application and the cluster, then contact the HP Customer Support Center.

23.5.3.3 User-Defined Attributes and Environment Variables

User-defined attributes can be added to application resources by defining the new attribute in the application.tdf file that is located in the /var/cluster/caa/template directory. Once defined, the user-defined attributes can be used from within an application resource profile and action script.

Note, user-defined resource attributes should always start with "USR_" so that your attribute names do not conflict with CAA resource attributes that exist (or may exist in a future release).

Furthermore, the caa_start, caa_stop, and caa_relocate commands have been modified to be able to override user-defined attributes that are defined in an application resource profile when starting, stopping, or relocating the resource. This action is not permanent – it does not modify the resource profile. It merely overrides the value for the running (or soon to be non-running) instance and is designed to be used to modify the behavior of the action script.

23.5.3.3.1 Creating a User-Defined Attribute

Defining a user-defined attribute simply involves defining the attribute in the application.tdf file.

1. Save the original application.tdf file.

    # cd /var/cluster/caa/template 

    # cp application.tdf application.tdf.orig 

2. Add the attribute.

   We decided to add two attributes to be used to manage a cluster alias from our application resource.

    # grep -p ALIAS application.tdf #!========================== attribute: USR_ALIAS_NAME type: name_string switch: -o an default: required: no #!========================== attribute: USR_ALIAS_IP type: internet_address switch: -o aa default: required: no 

3. You can now use the attribute.

   For example, we will create a new application resource using the new attributes.

    # caa_profile -create aliasAPP -t application -B /code/caa/aliasAPP \ > -o an=caa_alias,aa=192.168.1.71 

   We can verify that the resource was created by printing the resource profile using the caa_profile command. Note the output has been trimmed.

    # caa_profile -print aliasAPP | grep -E "NAME|ALIAS" NAME=aliasAPP USR_ALIAS_IP=192.168.1.71 USR_ALIAS_NAME=caa_alias 

23.5.3.3.2 Using a User-Defined Attribute in an Action Script

User-defined attributes can be accessed within an application resource's action script by adding an underscore prefix to the attribute name.

For example, we added two print statements to the action script of the aliasAPP resource we created in the previous section.

 # grep print aliasAPP.scr print "_USR_ALIAS_NAME = \"$_USR_ALIAS_NAME\"" print " _USR_ALIAS_IP  = \"$_USR_ALIAS_IP\"" 

We still have the _CAA_UI_FMT environment variable set from section 23.5.2, so all we need to do is register and start the resource (of course, we had to modify the action script and test it too).

 # caa_register aliasAPP 

 # caa_start aliasAPP Attempting to start 'aliasAPP' on member 'sheridan' Start of 'aliasAPP' on member 'sheridan' succeeded. _USR_ALIAS_NAME = "caa_alias" _USR_ALIAS_IP   = "192.168.1.71" 

As you see by the output, our user-defined attributes are accessible from the action script.

23.5.3.3.3 Modifying a User-Defined Attribute Value Temporarily

You can temporarily modify a user-defined attribute using the caa_start, caa_stop, and caa_relocate commands.

For example, we will relocate aliasAPP and change the USR_ALIAS_NAME and USR_ALIAS_IP using the caa_relocate command.

 # caa_relocate USR_ALIAS_NAME=clu_faf USR_ALIAS_IP=192.168.1.77 aliasAPP Attempting to stop 'aliasAPP' on member 'molari' Stop of 'aliasAPP' on member 'molari' succeeded. Attempting to start 'aliasAPP' on member 'sheridan' Start of 'aliasAPP' on member 'sheridan' succeeded. sheridan:aliasAPP:_USR_ALIAS_NAME = "clu_faf" sheridan:aliasAPP:  _USR_ALIAS_IP = "192.168.1.77" molari:aliasAPP: _USR_ALIAS_NAME = "clu_faf" molari:aliasAPP:  _USR_ALIAS_IP  = "192.168.1.77" Start of 'aliasAPP' on member 'molari' succeeded. 

Note the values were modified. Let's relocate it back to the other member. This time we will not modify the attribute values.

 # caa_relocate aliasAPP Attempting to stop 'aliasAPP' on member 'molari' Stop of 'aliasAPP' on member 'molari' succeeded. Attempting to start 'aliasAPP' on member 'sheridan' Start of 'aliasAPP' on member 'sheridan' succeeded. molari:aliasAPP:_USR_ALIAS_NAME = "caa_alias" molari:aliasAPP:  _USR_ALIAS_IP = "192.168.1.71" sheridan:aliasAPP: _USR_ALIAS_NAME = "caa_alias" sheridan:aliasAPP:   _USR_ALIAS_IP = "192.168.1.71" 

The attribute values are returned to those defined in the resource profile.

23.5.3.4 Locale Information Environment Variable

The _CAA_CLIENT_LOCALE environment variable contains a whitespace delimited list of the current locale where the action script is invoked.

The locale information contained in the list is in the following order:

     LC_ALL, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME, LC_MESSAGES 

Here is an example output from an application resource when we started it in the cluster.

 # grep _CAA_CLIENT_LOCALE /var/cluster/caa/script/powerUP.scr   print "_CAA_CLIENT_LOCALE = \"$_CAA_CLIENT_LOCALE\"" 

Since we still have the _CAA_UI_FMT environment variable set from section 23.5.2, we will start the powerUP resource but grep (1) for only the _CAA_CLIENT_LOCALE output.

 # caa_start powerUP | grep _CAA_CLIENT_LOCALE _CAA_CLIENT_LOCALE = "C C C C C C" 

For more information on locales, see the locales (5), locale (1), and setlocale (3) reference pages.