Writing the Package Control Script

The package control script contains all the information necessary to run all the services in the package, monitor them during operation, react to a failure, and halt the package when necessary. You can use either SAM or HP-UX commands to create or modify the package control script. For security reasons, the control script must reside in a directory with the string cmcluster in the path.

Using SAM to Write the Package Control Script

Select the High Availability options in SAM, then choose "Package Configuration." From the Action menu, choose "Create/Add a Package." The step menu appears, showing a group of options. The last two steps on the menu are for choosing the pathname of the package control script. Select each option after you define the package itself. For more information, use the Help key.

When you create a package control script this way, you do not need to do any further editing, but you may customize the script if you wish.

Using Commands to Write the Package Control Script

Each package must have a separate control script. The control script is placed in the package directory and is given the same name that it has in the package configuration file. The package control script contains both the run instructions and the halt instructions for the package. It must be executable. Use the following procedure to create a control scripts for the sample package pkg1.

First, generate a control script template:

# cmmakepkg -s /etc/cmcluster/pkg1/control.sh

You may customize the script, as described in the section, "“Writing the Package Control Script ”."

Customizing the Package Control Script

Check the definitions and declarations at the beginning of the control script using the information in the Package Configuration worksheet. You need to customize as follows:

Update the PATH statement to reflect any required paths needed to start your services.
Enter the names of volume groups that will be activated.
Add the names of logical volumes and file systems that will be mounted on them.
Define IP subnet and IP address pairs for your package.
Add service name(s).
Add service command(s)
Add a service restart parameter, if desired.




	NOTE: Use care in defining service run commands. Each run command is executed by the control script in the following way: The `cmrunserv` command executes each run command and then monitors the process id of the process created by the run command. When the command started by `cmrunserv` exits, MC/LockManager determines that a failure has occurred and takes appropriate action, which may include transferring the package to an adoptive node. If a run command is a shell script that runs some other command and then exits, MC/LockManager will consider this normal exit as a failure. To avoid problems in the execution of control scripts, ensure that each run command is the name of an actual service and that its process remains alive until the actual service stops.

If you need to define a set of run and halt operations in addition to the defaults, create functions for them in the sections under the heading CUSTOMER DEFINED FUNCTIONS. The next section, "“Creating the Control Script for Starting OPS Instances”," shows an excerpt from the control script for a sample package configuration.

Creating the Control Script for Starting OPS Instances

Use the package control script to perform the following:

Activation and deactivation of OPS volume groups.
Startup and shutdown of the OPS instance.

Enter the names of the volume groups you wish to activate in shared mode in the VG[] array. Use a different array element for each OPS volume group. (Remember that OPS volume groups must also be coded in the cluster configuration file using OPS_VOLUME_GROUP parameters.)

Be sure to specify shared activation with the vgchange command by setting the VGCHANGE parameter as follows:

VGCHANGE="vgchange -a s"




	NOTE: Do not define the OPS instance as a package service. Instead, include the commands that start up an OPS instance in the `customer_defined_run_commands` section of the package control script. Similarly, you should include the commands that halt an OPS instance in the `customer_defined_halt_commands` section of the package control script. You may also need to set OPS environment variables in the package control script to define the correct execution environment for OPS. Refer to your OPS documentation for more details.

Package Control Script Template File

#"(#) A.11.06                                         $Date: 99/01/25 $"# **********************************************************************# *                                                                    *# *        HIGH AVAILABILITY PACKAGE CONTROL SCRIPT (template)         *# *                                                                    *# *       Note: This file MUST be edited before it can be used.        *# *                                                                    *# **********************************************************************       # UNCOMMENT the variables as you set them.# Set PATH to reference the appropriate directories.PATH=/sbin:/usr/bin:/usr/sbin:/etc:/bin# VOLUME GROUP ACTIVATION: # Specify the method of activation for volume groups.# Leave the default ("VGCHANGE="vgchange -a e") if you want volume# groups activated in exclusive mode. This assumes the volume groups have# been initialized with 'vgchange -c y' at the time of creation.## Uncomment the first line (VGCHANGE="vgchange -a e -q n"), and comment # out the default, if your disks are mirrored on separate physical paths,## Uncomment the second line (VGCHANGE="vgchange -a e -q n -s"), and comment # out the default, if your disks are mirrored on separate physical paths,# and you want the mirror resynchronization to ocurr in parallel with# the package startup.## Uncomment the third line (VGCHANGE="vgchange -a y") if you wish to # use non-exclusive activation mode. Single node cluster configurations# must use non-exclusive activation.## VGCHANGE="vgchange -a e -q n"# VGCHANGE="vgchange -a e -q n -s"# VGCHANGE="vgchange -a y"VGCHANGE="vgchange -a e"                # Default       # VOLUME GROUPS# Specify which volume groups are used by this package. Uncomment VG[0]="" # and fill in the name of your first volume group. You must begin with # VG[0], and increment the list in sequence.## For example, if this package uses your volume groups vg01 and vg02, enter:#         VG[0]=vg01#         VG[1]=vg02## The volume group activation method is defined above. The filesystems# associated with these volume groups are specified below.##VG[0]=""# FILESYSTEMS# Specify the filesystems which are used by this package. Uncomment # LV[0]=""; FS[0]=""; FS_MOUNT_OPT[0]="" and fill in the name of your first # logical volume, filesystem and mount option for the file system. You must # begin with LV[0], FS[0] and FS_MOUNT_OPT[0] and increment the list in # sequence.## For example, if this package uses the file systems pkg1a and pkg1b, # which are mounted on the logical volumes lvol1 and lvol2 with read and# write options enter:#          LV[0]=/dev/vg01/lvol1; FS[0]=/pkg1a; FS_MOUNT_OPT[0]="-o rw"#          LV[1]=/dev/vg01/lvol2; FS[1]=/pkg1b; FS_MOUNT_OPT[1]="-o rw"## The filesystems are defined as triplets of entries specifying the logical # volume, the mount point and the mount options for the file system. Each # filesystem will be fsck'd prior to being mounted. The filesystems will be # mounted in the order specified during package startup and will be unmounted # in reverse order during package shutdown. Ensure that volume groups # referenced by the logical volume definitions below are included in # volume group definitions above.##LV[0]=""; FS[0]=""; FS_MOUNT_OPT[0]=""# FILESYSTEM UNMOUNT COUNT# Specify the number of unmount attempts for each filesystem during package# shutdown.  The default is set to 1.LV_UMOUNT_COUNT=1# IP ADDRESSES# Specify the IP and Subnet address pairs which are used by this package.# Uncomment IP[0]="" and SUBNET[0]="" and fill in the name of your first# IP and subnet address. You must begin with IP[0] and SUBNET[0] and # increment the list in sequence.## For example, if this package uses an IP of 192.10.25.12 and a subnet of # 192.10.25.0 enter:#          IP[0]=192.10.25.12 #          SUBNET[0]=192.10.25.0 # (netmask=255.255.255.0)## Hint: Run "netstat -i" to see the available subnets in the Network field.## IP/Subnet address pairs for each IP address you want to add to a subnet # interface card.  Must be set in pairs, even for IP addresses on the same# subnet.##IP[0]=""#SUBNET[0]=""# SERVICE NAMES AND COMMANDS.# Specify the service name, command, and restart parameters which are # used by this package. Uncomment SERVICE_NAME[0]="", SERVICE_CMD[0]="",# SERVICE_RESTART[0]="" and fill in the name of the first service, command,# and restart parameters. You must begin with SERVICE_NAME[0], SERVICE_CMD[0],# and SERVICE_RESTART[0] and increment the list in sequence.## For example:#          SERVICE_NAME[0]=pkg1a #          SERVICE_CMD[0]="/usr/bin/X11/xclock -display 192.10.25.54:0"#          SERVICE_RESTART[0]=""  # Will not restart the service.##          SERVICE_NAME[1]=pkg1b#          SERVICE_CMD[1]="/usr/bin/X11/xload -display 192.10.25.54:0"#          SERVICE_RESTART[1]="-r 2"   # Will restart the service twice.##          SERVICE_NAME[2]=pkg1c#          SERVICE_CMD[2]="/usr/sbin/ping"#          SERVICE_RESTART[2]="-R" # Will restart the service an infinite #                                    number of times.## Note: No environmental variables will be passed to the command, this # includes the PATH variable. Absolute path names are required for the# service command definition.  Default shell is /usr/bin/sh.##SERVICE_NAME[0]=""#SERVICE_CMD[0]=""#SERVICE_RESTART[0]=""       # DTC manager information for each DTC.# Example: DTC[0]=dtc_20#DTC_NAME[0]=

The above excerpt from the control script shows the assignment of values to a set of variables. The remainder of the script uses these variables to control the package by executing Logical Volume Manager commands, HP-UX commands, and MC/LockManager commands including cmrunserv, cmmodnet, and cmhaltserv. Examine a copy of the control script template to see the flow of logic. Use the following command:

# cmmakepkg -s | more

The main function appears at the end of the script.

Note that individual variables are optional; you should include only as many as you need for proper package operation. For example, if your package does not need to activate a volume group, omit the VG variables; if the package does not use services, omit the corresponding SERVICE_NAME, SERVICE_CMD, and SERVICE_RESTART variables; and so on.

After customizing the script, distribute it to each node in the cluster using rcp, ftp, or your favorite method of copying.

Adding Customer Defined Functions to the Package Control Script

You can add additional shell commands to the package control script to be executed whenever the package starts or stops. Simply enter these commands in the CUSTOMER DEFINED FUNCTIONS area of the script. This gives you the ability to further customize the control script.

An example of this portion of the script is shown below, with the date and echo commands included to log starts and halts of the package to a special file.

# START OF CUSTOMER DEFINED FUNCTIONS
 
# This function is a place holder for customer defined functions.
# You should define all actions you want to happen here, before the service is
# started.  You can create as many functions as you need.
 
function customer_defined_run_cmds
{
# ADD customer defined run commands.
: # do nothing instruction, because a function must contain some command.
 date >> /tmp/pkg1.datelog
 echo 'Starting pkg1' >> /tmp/pkg1.datelog
 test_return 51
}
 
# This function is a place holder for customer defined functions.
# You should define all actions you want to happen here, before the service is
# halted.
 
function customer_defined_halt_cmds
{
# ADD customer defined halt commands.
: # do nothing instruction, because a function must contain some command.
 date >> /tmp/pkg1.datelog
 echo 'Halting pkg1' >> /tmp/pkg1.datelog
 test_return 52
}
 
# END OF CUSTOMER DEFINED FUNCTIONS

Adding MC/LockManager Commands in Customer Defined Functions

You can add MC/LockManager commands (such as cmmodpkg) in the Customer Defined Functions section of a package control script. However, these commands must not interact with the package itself. Additionally, if an MC/LockManager command interacts with another package, then you need to check all packages with MC/LockManager commands for the possibility of a command loop.

For instance, a command loop might occur under the following circumstances. Suppose Pkg1 does a cmmodpkg -d of Pkg2, and Pkg2 does a cmmodpkg -d of Pkg1. If both Pkg1 and Pkg2 start at the same time, Pkg1 tries to cmmodpkg Pkg2. However, that cmmodpkg command has to wait for Pkg2 startup to complete. Pkg2 tries to cmmodpkg Pkg1, but Pkg2 has to wait for Pkg1 startup to complete, thereby causing a command loop.

To avoid this situation, it is a good idea to always specify a RUN_SCRIPT_TIMEOUT and a HALT_SCRIPT_TIMEOUT for all packages, especially packages that use MC/LockManager commands in their control scripts. If a timeout is not specified and your configuration has a command loop as described above, inconsistent results can occur, including a hung cluster.