Chapter 4. Defining a New Resource Type

Chapter 4. Defining a New Resource Type
Prev		Next

Already installed resource types are created automatically when a FailSafe cluster is created. This chapter describes how to define a new resource type, which can be performed using the FailSafe GUI or the cmgr command.

The following are examples of candidates for resource types:

Databases that support transactions
Web servers
Applications that require user datagram protocol (UDP) for communication with clients

You will want to define a new resource type when creating something entirely new or when you want to have multiple resource types that are similar except for one or two attributes. For example, if you want to enable local restart for most IP addresses but not for some, you could create a new resource type called IP_address2 using all of the same information as for the default IP_address except changing the value of the restart mode to 1 rather than the default 0.

This chapter contains the following sections:

Information You Must Gather

To define a new resource type, you must have the following information:

Name of the resource type. The name can consist of alphanumeric characters and any of the following:
- (hyphen) / = : @ _ (underscore) . " ,
The name cannot contain a space, an unprintable character, or any of the following characters:
* ? \ #
Name of the cluster to which the resource type will apply.
If the resource type is to be restricted to a specific node, you must know the node name.

Order of performing the action scripts for resources of this type in relation to resources of other types. If multiple resource groups are being made online, the start action for the resource groups are done in parallel. Resources in each group are started in increasing order of their resource type order. If there are multiple resources of the same type in the resource group, they are passed as parameters to same invocation of resource type start script. For example, all resources of resource type order 10 will be started after resources with resource type order 5 in the resource group.

Ensure that the number you choose for a new resource type permits the resource types on which it depends to be started before it is started, or stopped after it is stopped, as appropriate.

Table 4-1 shows the conventions used for order ranges. The values available for customer use are 201-400 and 701-999.

Table 4-1. Order Ranges

Range	Reservation
2-100	SGI-provided basic system resource types, such as `MAC_address`
101-200	SGI-provided system plug-ins that can be started before `IP_address`
201-400	User-defined resource types that can be started before `IP_address`
401-500	SGI-provided basic system resource types, such as `IP_address`
501-700	SGI-provided system plug-ins that must be started after `IP_address`
701-999	User-defined resource types that must be started after `IP_address`

Table 4-2 shows the order numbers of the resource types provided with the release.

Table 4-2. Resource Type Order Numbers

Order Number	Resource Type
10	`MAC_address`
20	`volume`
30	`filesystem`
201	`NFS`
401	`IP_address`
412	`statd_unlimited`
500	`CXFS`
501	`Netscape_web`
502	`Samba`
511	`Oracle_DB`
521	`INFORMIX_DB`

Restart mode, which can be one of the following values:
- 0 = Do not restart upon monitoring failures
- 1 = Restart a fixed number of times
Number of local restarts (when restart mode is 1).
Location of the executable script. This is always as follows:/var/cluster/ha/resource_types/resource_type_tname
Monitoring interval, which is the time period (in milliseconds) between successive executions of the monitor action script; this is only valid for the monitor action script.
Starting time for monitoring. When the resource group is made online in a cluster node, FailSafe will start monitoring the resources after the specified time period (in milliseconds).
Action scripts to be defined for this resource type. You must specify scripts for start, stop, exclusive, and monitor, although the monitor script may contain only a return-success function if you wish. If you specify 1 for the restart mode, you must specify a restart script.
Type-specific attributes to be defined for this resource type. The action scripts use this information to start, stop, and monitor a resource of this resource type. For example, NFS requires the following resource keys:
- export-point, which takes a value that defines the export disk name. This name is used as input to the exportfs command. For example:
  export-point = /this_disk
- export-info, which takes a value that defines the export options for the file system. These options are used in the exportfs command. For example:
  export-info = rw,wsync,anon=root
- filesystem, which takes a value that defines the raw file system. This name is used as input to the mount command. For example:
  filesystem = /dev/xlv/xlv_object

Copying an Existing Resource Type to Create a New One

Caution: Any user can use the GUI to view database information; therefore, you should not include any sensitive information in the cluster database. Users should keep this mind when deciding the list of resource attributes for the resource type.

If an existing resource type is similar to the type you want to create, you can use the following procedure:

Log in as root.
Copy the directory for the existing resource type and give the new directory an appropriate name. For example, to use the NFS resource type as the basis for a new resource type named NFS_CXFS, do the following:
# cp -r /var/cluster/ha/resource_types/NFS /var/cluster/ha/resource_types/NFS_CXFS
Modify each script in the new NFS_CXFS directory so that it uses the name of the new resource type. You must make this modification for the LOCAL_TEST_KEY= variable definition; modifying log messages and comments is optional but recommended.

For example, you would change the LOCAL_TEST_KEY=NFS line in the /var/cluster/ha/resource_types/NFS_CXFS/start script as follows:
- From:
  LOCAL_TEST_KEY=NFS
- To:
  LOCAL_TEST_KEY=NFS_CXFS

Eliminate any unneeded dependencies for the new resource type, using either the GUI or the cmgr command.

For example, you would eliminate the filesystem dependency from the new NFS_CXFS as follows:

# cmgr
Welcome to SGI Cluster Manager Command-Line Interface
cmgr> modify resource_type NFS_CXFS in cluster "testcluster"
Enter commands, when finished enter either "done" or "cancel"
resource_type NFS_CXFS ? remove dependency filesystem
resource_type NFS_CXFS ? done
Successfully modified resource_type NFS_CXFS

Modify the monitor script for the new resource type as needed.

For example, the difference between the standard NFS monitor script and the new NFS_CXFS monitor script is that when you export CXFS filesystems, you do not want FailSafe to check if the filesystem is mounted and to exit with HA_CMD_FAILED if it is not. The NFS_CXFS monitor script itself will determine what action should take place if the filesystem becomes unmounted. To accomplish this, you would modify the /var/cluster/ha/resource_types/NFS_CXFS/monitor script to comment out the exit_script line in the following section (the line as modified is shown here in bold):

# Check to see if the filesystem is mounted
HA_CMD="/sbin/mount | grep $fs >> /dev/null 2>&1"
ha_execute_cmd "check to see if $fs is mounted"
if [ $? -ne 0 ]; then
    ${HA_LOG} "NFS: $fs not mounted";
    ha_write_status_for_resource ${resource} ${HA_CMD_FAILED};
#   exit_script $HA_CMD_FAILED;
fi

The result of this change is that the status of the commands will be written to the log, but the script will not exit.

Creating a New Resource Type from Scratch

If none of the existing resource types are similar to the type you want to create, you can create a resource type from scratch using the following methods:

Using the FailSafe Manager GUI

You can use the FailSafe Manager graphical user interface (GUI) to define a new resource type and to define the dependencies for a given type. For details about the GUI, see Appendix A, “Starting the FailSafe Manager GUI” and the FailSafe Administrator's Guide for SGI InfiniteStorage.

Define a New Resource Type

To define a new resource type using the GUI, select the following menu:

Tasks -> Resource Types -> Define a Resource Type

The GUI will prompt you for required and optional information. Online help is provided for each item.

The following figures show this process for a new resource type called newresourcetype.

Figure 4-1. Specify the Name of the New Resource Type

Figure 4-2. Specify Settings for Required Actions

Figure 4-3. Change Settings for Optional Actions

Figure 4-4. Set Type-specific Attributes

Define Dependencies

To define the dependencies for a given type, select the following menu:

Tasks -> Resource Types -> Add/Remove Dependencies for a Resource Type

Figure 4-5 shows an example of adding a dependency (filesystem) to the newresourcetype resource type.

Figure 4-5. Add Dependencies

Using `cmgr` Interactively

The following steps show the use of cmgr interactively to define a resource type called newresourcetype.

Note: A resource type name cannot contain a space, an unprintable character, or any of the following characters:

*      ?       \       #

Execute the cmgr command. You can use the -p option to prompt you for information:

# /usr/cluster/bin/cmgr -p 
Welcome to SGI Cluster Manager Command-Line Interface
 
cmgr>

Use the set subcommand to specify the default cluster used for cmgr operations. In this example, we use a cluster named TEST:
cmgr> set cluster TEST
If you prefer, you can specify the cluster name as needed with each subcommand.

Use the define resource_type subcommand. By default, the resource type will apply across the cluster; if you wish to limit the resource type to a specific node, enter the node name when prompted. If you wish to enable restart mode, enter 1 when prompted.

Note: The following example only shows the prompts and answers for two action scripts (start and stop) for a new resource type named newresourcetype.

cmgr> define resource_type newresourcetype

(Enter "cancel" at any time to abort)

Node[optional]?
Order ? 300
Restart Mode ? (0)
 
DEFINE RESOURCE TYPE OPTIONS
 
        0) Modify Action Script.
        1) Add Action Script.
        2) Remove Action Script.
        3) Add Type Specific Attribute.
        4) Remove Type Specific Attribute.
        5) Add Dependency.
        6) Remove Dependency.
        7) Show Current Information.
        8) Cancel. (Aborts command)
        9) Done. (Exits and runs command)
 
Enter option:1
 
No current resource type actions
 
Action name ? start
Executable timeout (in milliseconds) ? 40000
 
        0) Modify Action Script.
        1) Add Action Script.
        2) Remove Action Script.
        3) Add Type Specific Attribute.
        4) Remove Type Specific Attribute.
        5) Add Dependency.
        6) Remove Dependency.
        7) Show Current Information.
        8) Cancel. (Aborts command)
        9) Done. (Exits and runs command)
 
Enter option:1
 
Current resource type actions:
        start
 
Action name stop
Executable timeout?  (in milliseconds) 40000
 
        0) Modify Action Script.
        1) Add Action Script.
        2) Remove Action Script.
        3) Add Type Specific Attribute.
        4) Remove Type Specific Attribute.
        5) Add Dependency.
        6) Remove Dependency.
        7) Show Current Information.
        8) Cancel. (Aborts command)
        9) Done. (Exits and runs command)
 
Enter option:3
 
No current type specific attributes
 
Type Specific Attribute ? integer-att
Datatype ? integer
Default value[optional] ? 33 
 
        0) Modify Action Script.
        1) Add Action Script.
        2) Remove Action Script.
        3) Add Type Specific Attribute.
        4) Remove Type Specific Attribute.
        5) Add Dependency.
        6) Remove Dependency.
        7) Show Current Information.
        8) Cancel. (Aborts command)
        9) Done. (Exits and runs command)
 
Enter option:3
 
Current type specific attributes:
        Type Specific Attribute - 1: integer-att
 
Type Specific Attribute ? string-att
Datatype ? string
Default value[optional] ? rw
 
        0) Modify Action Script.
        1) Add Action Script.
        2) Remove Action Script.
        3) Add Type Specific Attribute.
        4) Remove Type Specific Attribute.
        5) Add Dependency.
        6) Remove Dependency.
        7) Show Current Information.
        8) Cancel. (Aborts command)
        9) Done. (Exits and runs command)
 
Enter option:5
 
No current resource type dependencies
 
Dependency name ? filesystem
 
        0) Modify Action Script.
        1) Add Action Script.
        2) Remove Action Script.
        3) Add Type Specific Attribute.
        4) Remove Type Specific Attribute.
        5) Add Dependency.
        6) Remove Dependency.
        7) Show Current Information.
        8) Cancel. (Aborts command)
        9) Done. (Exits and runs command)
 
Enter option:7

Current resource type actions:
        Action - 1: start
        Action - 2: stop

Current type specific attributes:
        Type Specific Attribute - 1: integer-att
        Type Specific Attribute - 2: string-att

No current resource type dependencies

Resource dependencies to be added:
        Resource dependency - 1: filesystem

        0) Modify Action Script.
        1) Add Action Script.
        2) Remove Action Script.
        3) Add Type Specific Attribute.
        4) Remove Type Specific Attribute.
        5) Add Dependency.
        6) Remove Dependency.
        7) Show Current Information.
        8) Cancel. (Aborts command)
        9) Done. (Exits and runs command)
 
Enter option:9
Successfully defined resource_type newresourcetype
 
cmgr> show resource_types
 
template
MAC_address
newresourcetype
IP_address
filesystem
volume

cmgr> exit
#

Using `cmgr` With a Script

You can write a script that contains all of the information required to define a resource type and supply it to cmgr by using the -f option:

cmgr -f scriptname

Or, you could include the following as the first line of the script and then execute the script itself:

#!/usr/cluster/bin/cmgr -f

If any line of the script fails, cmgr will exit. You can choose to ignore the failure and continue the process by using the -i option, as follows:

#!/usr/cluster/bin/cmgr -if

Note: If you include -i when using a cmgr command line as the first line of the script, you must use this exact syntax (that is, -if).

A template script for creating a new resource type is located in /var/cluster/cmgr-templates/cmgr-create-resource_type. Each line of the script must be a valid cmgr line, a comment line (starting with #), or a blank line. You must include a done command line to finish a multilevel command. If you concatenate information from multiple template scripts to prepare your cluster configuration, you must remove the quit at the end of each template script.

For example, you could use the following script to define the same newresourcetype resource type defined interactively in the previous section:

# Script to define the "newresourcetype" resource type

set cluster TEST
define resource_type newresourcetype
set order to 300
set restart_mode to 0

add action start
set exec_time to 40000
done

add action stop
set exec_time to 40000
done

add type_attribute integer-att
set data_type to integer
set default_value to 33
done

add type_attribute string-att
set data_type to string
set default_value to rw
done

add dependency filesystem
done

quit

When you execute the cmgr -f command line with this script, you will see the following output:

# /usr/cluster/bin/cmgr -f newresourcetype.script
Successfully defined resource_type newresourcetype

To verify that the resource type was defined, enter the following:

# /usr/cluster/bin/cmgr -c "show resource_types in cluster TEST"
 
template
MAC_address
newresourcetype
IP_address
filesystem
volume

Server-side Properties File

Each resource type can have an optional properties file containing a formatted label for each plug-in attribute and strings of help text that will be displayed in the GUI. The file has the following name:

/var/cluster/ha/resource_types/resource_type/resource_type

For example, the properties file for the IP_Address resource type would be as follows:

/var/cluster/ha/resource_types/IP_Address/IP_Address

The contents of this file is not propagated by the cluster database; therefore, it should be installed on each node in the cluster along with the resource type's scripts. (If the properties file is not installed on a given node and that node is used as the GUI server, the help text will not be displayed.)

Property Formats

In each resource type's properties file, you can have the following property:

resource_type.properFormat = introductory text

For each type-specific attribute, you can have the following properties:

Label that will be displayed in the GUI:

resource_type.Attribute.label = GUI_label

Help (glossary) text that will be linked to from each attribute's label:
resource_type.Attribute.glossary = glossary_key
Information describing what the resource type is for and how it should be configured:
glossary_key = help text

Example Properties File

Following is an example properties file for the IP_Address resource type.

# IP_address

IP_address.properFormat = \
An IP address resource that belongs to a resource group can be \
used by clients to access the highly available resource group. \
As with any other type of resource, an IP address resource will \
be moved from one node to another when \
FailSafe detects a failure. \
The resource name for an IP address must follow standard dot \
notation.  It should not be configured on any network interface. \
IP addresses that require name resolution are not valid IP_address \
resource names. \
For example, "192.0.2.22" could be the name of an IP_address \
resource.

IP_address.NetworkMask.label = \
        Network Mask
IP_address.NetworkMask.glossary = \
        glossary.IP_address.NetworkMask
glossary.IP_address.NetworkMask: \
        <B>IP address network mask</B><P>\
        The network mask of the IP address \
        (for example, "0xffffff00"). \
        See the <B>ifconfig(1M)</B> reference page for more \
        information.

IP_address.interfaces.label = \
        Interfaces
IP_address.interfaces.glossary = \
        glossary.IP_address.interfaces
glossary.IP_address.interfaces: \
        <B>IP address interfaces</B><P>\
        A comma-separated list of interfaces on which the \
        IP address can be configured \
        (for example, "ec0,et0,ef0" or "hip0" or "lb0"). \
        See the <B>ifconfig(1M)</B> reference page for more \
        information.

IP_address.BroadcastAddress.label = \
        Broadcast Address
IP_address.BroadcastAddress.glossary = \
        glossary.IP_address.BroadcastAddress
glossary.IP_address.BroadcastAddress: \
        <B>IP address broadcast address</B><P>\
        The broadcast address for the IP address \
        (for example, "192.0.2.255"). \
        See the <B>ifconfig(1M)</B> reference page for more \
        information.

Testing a New Resource Type

After adding a new resource type, you should test it as follows:

Define a resource group that contains resources of the new type. Ensure that the group contains all of the resources on which the new resource type depends.
Bring the resource group online in the cluster using cmgr or the GUI.

For example, using cmgr:
cmgr> admin online resource_group new_rg in cluster TEST
Check the status of the resource group using cmgr or GUI after a few minutes.

For example:
cmgr> show status of resource_group new_rg in cluster TEST
If the resource group has been made online successfully, you will see output similar to the following:
State: Online Error: No error Owner: node1

If there are resource group errors, do the following:

Check the srmd logs (/var/cluster/ha/log/srmd_ nodename) on the node on which the resource group is online.

Search for the string ERROR in the log file. There should be an error message about a resource in the resource group. The message also provides information about the action script that failed. For example:

Wed Nov 3 04:20:10.135 <E ha_srmd srm 12127:1 sa_process_tasks.c:627>
CI_FAILURE, ERROR: Action (exclusive) for resource (10.0.2.45) of type
(IP_address) failed with status (failed)
exclusive script failed for the resource 10.0.2.45 of resource type
IP_address. The status "failed"
indicates that the script returned an error.

Check the script logs (/var/cluster/ha/log/script_ nodename on the same node) for IP_address exclusive script errors.
After the fixing the problems in the action script, perform an offline_force operation to clear the error. For example:
cmgr> admin offline_force resource_group new_rg in cluster TEST

Prev	Table of Contents	Next
Chapter 3. Creating a Failover Policy		Chapter 5. Testing Scripts